feat(postgres): preserve resource write semantics

This commit is contained in:
sam committed 2026-09-24 01:38:40 +10:00
1 parent a463f5ed4c
commit cebbcb5690
4 files changed
+585

No files matched your search

@@ -0,0 +1,263 @@
// Code generated by sqlc. DO NOT EDIT.
// versions:
// sqlc v1.31.1
// source: resources.sql
package postgresdb
import (
"context"
"time"
)
const insertResource = `-- name: InsertResource :one
INSERT INTO resources (kind, value, version, updated_at)
VALUES ($1, $2, 1, $3)
RETURNING kind, value, version, updated_at
`
type InsertResourceParams struct {
Kind string
Value []byte
UpdatedAt time.Time
}
func (q *Queries) InsertResource(ctx context.Context, arg InsertResourceParams) (Resource, error) {
row := q.db.QueryRow(ctx, insertResource, arg.Kind, arg.Value, arg.UpdatedAt)
var i Resource
err := row.Scan(
&i.Kind,
&i.Value,
&i.Version,
&i.UpdatedAt,
)
return i, err
}
const insertResourceHistory = `-- name: InsertResourceHistory :one
INSERT INTO resource_history (
kind, value, version, actor, source, request_id, expected_version,
current_version, at
)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
RETURNING kind, value, version, actor, source, request_id, expected_version,
current_version, at
`
type InsertResourceHistoryParams struct {
Kind string
Value []byte
Version int64
Actor string
Source string
RequestID string
ExpectedVersion int64
CurrentVersion int64
At time.Time
}
type InsertResourceHistoryRow struct {
Kind string
Value []byte
Version int64
Actor string
Source string
RequestID string
ExpectedVersion int64
CurrentVersion int64
At time.Time
}
func (q *Queries) InsertResourceHistory(ctx context.Context, arg InsertResourceHistoryParams) (InsertResourceHistoryRow, error) {
row := q.db.QueryRow(ctx, insertResourceHistory,
arg.Kind,
arg.Value,
arg.Version,
arg.Actor,
arg.Source,
arg.RequestID,
arg.ExpectedVersion,
arg.CurrentVersion,
arg.At,
)
var i InsertResourceHistoryRow
err := row.Scan(
&i.Kind,
&i.Value,
&i.Version,
&i.Actor,
&i.Source,
&i.RequestID,
&i.ExpectedVersion,
&i.CurrentVersion,
&i.At,
)
return i, err
}
const lockResourceWrite = `-- name: LockResourceWrite :exec
SELECT pg_advisory_xact_lock(hashtextextended($1, 0))
`
// This lock is acquired in its own statement before a resource read. PostgreSQL
// takes a fresh Read Committed snapshot for the subsequent read, so concurrent
// optimistic writers see the committed revision rather than both writing v1.
func (q *Queries) LockResourceWrite(ctx context.Context, hashtextextended string) error {
_, err := q.db.Exec(ctx, lockResourceWrite, hashtextextended)
return err
}
const resourceByKind = `-- name: ResourceByKind :one
SELECT kind, value, version, updated_at FROM resources WHERE kind = $1
`
func (q *Queries) ResourceByKind(ctx context.Context, kind string) (Resource, error) {
row := q.db.QueryRow(ctx, resourceByKind, kind)
var i Resource
err := row.Scan(
&i.Kind,
&i.Value,
&i.Version,
&i.UpdatedAt,
)
return i, err
}
const resourceByRequest = `-- name: ResourceByRequest :one
SELECT kind, value, version, actor, source, request_id, expected_version,
current_version, at
FROM resource_history
WHERE kind = $1 AND request_id = $2
`
type ResourceByRequestParams struct {
Kind string
RequestID string
}
type ResourceByRequestRow struct {
Kind string
Value []byte
Version int64
Actor string
Source string
RequestID string
ExpectedVersion int64
CurrentVersion int64
At time.Time
}
func (q *Queries) ResourceByRequest(ctx context.Context, arg ResourceByRequestParams) (ResourceByRequestRow, error) {
row := q.db.QueryRow(ctx, resourceByRequest, arg.Kind, arg.RequestID)
var i ResourceByRequestRow
err := row.Scan(
&i.Kind,
&i.Value,
&i.Version,
&i.Actor,
&i.Source,
&i.RequestID,
&i.ExpectedVersion,
&i.CurrentVersion,
&i.At,
)
return i, err
}
const resourceHistory = `-- name: ResourceHistory :many
SELECT kind, value, version, actor, source, request_id, expected_version,
current_version, at
FROM resource_history
WHERE kind = $1
ORDER BY version DESC
LIMIT NULLIF($2::bigint, 0)
`
type ResourceHistoryParams struct {
Kind string
EntryLimit int64
}
type ResourceHistoryRow struct {
Kind string
Value []byte
Version int64
Actor string
Source string
RequestID string
ExpectedVersion int64
CurrentVersion int64
At time.Time
}
func (q *Queries) ResourceHistory(ctx context.Context, arg ResourceHistoryParams) ([]ResourceHistoryRow, error) {
rows, err := q.db.Query(ctx, resourceHistory, arg.Kind, arg.EntryLimit)
if err != nil {
return nil, err
}
defer rows.Close()
var items []ResourceHistoryRow
for rows.Next() {
var i ResourceHistoryRow
if err := rows.Scan(
&i.Kind,
&i.Value,
&i.Version,
&i.Actor,
&i.Source,
&i.RequestID,
&i.ExpectedVersion,
&i.CurrentVersion,
&i.At,
); err != nil {
return nil, err
}
items = append(items, i)
}
if err := rows.Err(); err != nil {
return nil, err
}
return items, nil
}
const resourceVersion = `-- name: ResourceVersion :one
SELECT version FROM resources WHERE kind = $1
`
func (q *Queries) ResourceVersion(ctx context.Context, kind string) (int64, error) {
row := q.db.QueryRow(ctx, resourceVersion, kind)
var version int64
err := row.Scan(&version)
return version, err
}
const updateResource = `-- name: UpdateResource :one
UPDATE resources
SET value = $2, version = version + 1, updated_at = $3
WHERE kind = $1 AND version = $4
RETURNING kind, value, version, updated_at
`
type UpdateResourceParams struct {
Kind string
Value []byte
UpdatedAt time.Time
Version int64
}
func (q *Queries) UpdateResource(ctx context.Context, arg UpdateResourceParams) (Resource, error) {
row := q.db.QueryRow(ctx, updateResource,
arg.Kind,
arg.Value,
arg.UpdatedAt,
arg.Version,
)
var i Resource
err := row.Scan(
&i.Kind,
&i.Value,
&i.Version,
&i.UpdatedAt,
)
return i, err
}
@@ -0,0 +1,45 @@
-- name: LockResourceWrite :exec
-- This lock is acquired in its own statement before a resource read. PostgreSQL
-- takes a fresh Read Committed snapshot for the subsequent read, so concurrent
-- optimistic writers see the committed revision rather than both writing v1.
SELECT pg_advisory_xact_lock(hashtextextended($1, 0));
-- name: ResourceByKind :one
SELECT kind, value, version, updated_at FROM resources WHERE kind = $1;
-- name: ResourceByRequest :one
SELECT kind, value, version, actor, source, request_id, expected_version,
current_version, at
FROM resource_history
WHERE kind = $1 AND request_id = $2;
-- name: ResourceHistory :many
SELECT kind, value, version, actor, source, request_id, expected_version,
current_version, at
FROM resource_history
WHERE kind = $1
ORDER BY version DESC
LIMIT NULLIF(sqlc.arg(entry_limit)::bigint, 0);
-- name: ResourceVersion :one
SELECT version FROM resources WHERE kind = $1;
-- name: InsertResource :one
INSERT INTO resources (kind, value, version, updated_at)
VALUES ($1, $2, 1, $3)
RETURNING kind, value, version, updated_at;
-- name: UpdateResource :one
UPDATE resources
SET value = $2, version = version + 1, updated_at = $3
WHERE kind = $1 AND version = $4
RETURNING kind, value, version, updated_at;
-- name: InsertResourceHistory :one
INSERT INTO resource_history (
kind, value, version, actor, source, request_id, expected_version,
current_version, at
)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
RETURNING kind, value, version, actor, source, request_id, expected_version,
current_version, at;
@@ -0,0 +1,142 @@
package postgres
import (
"context"
"errors"
"fmt"
"time"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgxpool"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/postgresdb"
"github.com/samcharles93/archie-core/internal/store"
)
// Resources is the PostgreSQL implementation of the State Store's
// control-plane resource document operations. It is separate while the rest
// of the transitional SQLite Store is still being ported.
type Resources struct {
pool *pgxpool.Pool
}
func NewResources(pool *pgxpool.Pool) *Resources {
return &Resources{pool: pool}
}
func (s *Resources) Resource(ctx context.Context, kind string) (store.Resource, error) {
resource, err := postgresdb.New(s.pool).ResourceByKind(ctx, kind)
if errors.Is(err, pgx.ErrNoRows) {
return store.Resource{}, store.ErrResourceNotFound
}
if err != nil {
return store.Resource{}, err
}
return resourceFromCurrent(resource), nil
}
func (s *Resources) ResourceHistory(ctx context.Context, kind string, limit int) ([]store.Resource, error) {
if limit <= 0 {
limit = 0
}
history, err := postgresdb.New(s.pool).ResourceHistory(ctx, postgresdb.ResourceHistoryParams{
Kind: kind, EntryLimit: int64(limit),
})
if err != nil {
return nil, err
}
resources := make([]store.Resource, 0, len(history))
for _, entry := range history {
resources = append(resources, resourceFromAudit(
entry.Kind, entry.Value, entry.Version, entry.Actor, entry.Source,
entry.RequestID, entry.ExpectedVersion, entry.CurrentVersion, entry.At,
))
}
return resources, nil
}
func (s *Resources) PutResource(ctx context.Context, write store.ResourceWrite) (_ store.Resource, retErr error) {
tx, err := s.pool.Begin(ctx)
if err != nil {
return store.Resource{}, err
}
defer func() { _ = tx.Rollback(ctx) }()
queries := postgresdb.New(tx)
if err := queries.LockResourceWrite(ctx, write.Kind); err != nil {
return store.Resource{}, err
}
if existing, err := queries.ResourceByRequest(ctx, postgresdb.ResourceByRequestParams{
Kind: write.Kind, RequestID: write.RequestID,
}); err == nil {
return resourceFromAudit(
existing.Kind, existing.Value, existing.Version, existing.Actor, existing.Source,
existing.RequestID, existing.ExpectedVersion, existing.CurrentVersion, existing.At,
), nil
} else if !errors.Is(err, pgx.ErrNoRows) {
return store.Resource{}, err
}
current, err := queries.ResourceVersion(ctx, write.Kind)
if errors.Is(err, pgx.ErrNoRows) {
current = 0
} else if err != nil {
return store.Resource{}, err
}
if current != write.ExpectedVersion {
return store.Resource{}, fmt.Errorf("%w: expected %d, current %d", store.ErrResourceVersionConflict, write.ExpectedVersion, current)
}
if write.At.IsZero() {
write.At = time.Now().UTC()
} else {
write.At = write.At.UTC()
}
var resource postgresdb.Resource
if current == 0 {
resource, err = queries.InsertResource(ctx, postgresdb.InsertResourceParams{
Kind: write.Kind, Value: write.Value, UpdatedAt: write.At,
})
} else {
resource, err = queries.UpdateResource(ctx, postgresdb.UpdateResourceParams{
Kind: write.Kind, Value: write.Value, UpdatedAt: write.At, Version: current,
})
}
if err != nil {
return store.Resource{}, err
}
history, err := queries.InsertResourceHistory(ctx, postgresdb.InsertResourceHistoryParams{
Kind: write.Kind, Value: write.Value, Version: resource.Version, Actor: write.Actor,
Source: write.Source, RequestID: write.RequestID, ExpectedVersion: write.ExpectedVersion,
CurrentVersion: current, At: write.At,
})
if err != nil {
return store.Resource{}, err
}
if err := tx.Commit(ctx); err != nil {
return store.Resource{}, err
}
return resourceFromAudit(
history.Kind, history.Value, history.Version, history.Actor, history.Source,
history.RequestID, history.ExpectedVersion, history.CurrentVersion, history.At,
), nil
}
func resourceFromCurrent(resource postgresdb.Resource) store.Resource {
return store.Resource{
Kind: resource.Kind, Value: resource.Value, Version: resource.Version, At: resource.UpdatedAt,
}
}
func resourceFromAudit(
kind string,
value []byte,
version int64,
actor, source, requestID string,
expectedVersion, currentVersion int64,
at time.Time,
) store.Resource {
return store.Resource{
Kind: kind, Value: value, Version: version, Actor: actor, Source: source,
RequestID: requestID, ExpectedVersion: expectedVersion, CurrentVersion: currentVersion, At: at,
}
}
@@ -3,12 +3,14 @@ package postgres
import (
"errors"
"testing"
"time"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgxpool"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/postgresdb"
"github.com/samcharles93/archie-core/internal/store"
)
// syntheticIssueBase mirrors the store's chat issue-number seed. It is the
@@ -38,6 +40,12 @@ func queriesFor(t *testing.T) *postgresdb.Queries {
return q
}
func resourcesFor(t *testing.T) *Resources {
t.Helper()
pool, _ := migrated(t)
return NewResources(pool)
}
// insertChatTask queues one chat-sourced task.
func insertChatTask(t *testing.T, q *postgresdb.Queries) postgresdb.Task {
t.Helper()
@@ -161,3 +169,130 @@ func TestClaimSkipsARowAnotherTransactionHolds(t *testing.T) {
t.Fatalf("claimed %d while %d was held, want the skipped-to row %d", claimed.ID, free.ID, held.ID)
}
}
// A control-plane resource write is optimistic and idempotent: a retry returns
// the audited original, while a different request based on a stale revision is
// refused. The history remains the audit trail, newest first.
func TestResourceWritesPreserveOptimisticAndIdempotentSemantics(t *testing.T) {
resources := resourcesFor(t)
firstAt := time.Date(2026, 9, 24, 1, 0, 0, 0, time.UTC)
first, err := resources.PutResource(t.Context(), store.ResourceWrite{
Kind: "settings", Value: []byte(`{"v":1}`), Actor: "operator", Source: "archie-ui",
RequestID: "r1", ExpectedVersion: 0, At: firstAt,
})
if err != nil {
t.Fatalf("first PutResource: %v", err)
}
if first.Version != 1 || first.CurrentVersion != 0 {
t.Fatalf("first write = %+v, want version 1 from version 0", first)
}
replay, err := resources.PutResource(t.Context(), store.ResourceWrite{
Kind: "settings", Value: []byte(`{"v":999}`), Actor: "other", Source: "retry",
RequestID: "r1", ExpectedVersion: 0, At: firstAt.Add(time.Minute),
})
if err != nil {
t.Fatalf("replay PutResource: %v", err)
}
if replay.Version != first.Version || string(replay.Value) != string(first.Value) || replay.Actor != first.Actor {
t.Fatalf("replay = %+v, want original %+v", replay, first)
}
if _, err := resources.PutResource(t.Context(), store.ResourceWrite{
Kind: "settings", Value: []byte(`{"v":2}`), Actor: "operator", Source: "archie-ui",
RequestID: "r2", ExpectedVersion: 0, At: firstAt.Add(2 * time.Minute),
}); !errors.Is(err, store.ErrResourceVersionConflict) {
t.Fatalf("stale PutResource = %v, want ErrResourceVersionConflict", err)
}
second, err := resources.PutResource(t.Context(), store.ResourceWrite{
Kind: "settings", Value: []byte(`{"v":2}`), Actor: "operator", Source: "messaging",
RequestID: "r2", ExpectedVersion: 1, At: firstAt.Add(3 * time.Minute),
})
if err != nil {
t.Fatalf("second PutResource: %v", err)
}
if second.Version != 2 || second.CurrentVersion != 1 {
t.Fatalf("second write = %+v, want version 2 from version 1", second)
}
lateReplay, err := resources.PutResource(t.Context(), store.ResourceWrite{
Kind: "settings", Value: []byte(`{"v":999}`), Actor: "other", Source: "retry",
RequestID: "r1", ExpectedVersion: 0, At: firstAt.Add(4 * time.Minute),
})
if err != nil {
t.Fatalf("late replay PutResource: %v", err)
}
if lateReplay.Version != first.Version || string(lateReplay.Value) != string(first.Value) {
t.Fatalf("late replay = %+v, want original %+v", lateReplay, first)
}
live, err := resources.Resource(t.Context(), "settings")
if err != nil {
t.Fatalf("Resource: %v", err)
}
if live.Version != second.Version || string(live.Value) != string(second.Value) {
t.Fatalf("live resource after replay = %+v, want second write %+v", live, second)
}
history, err := resources.ResourceHistory(t.Context(), "settings", 1)
if err != nil {
t.Fatalf("ResourceHistory: %v", err)
}
if len(history) != 1 || history[0].Version != 2 || history[0].Source != "messaging" {
t.Fatalf("limited history = %+v, want newest revision only", history)
}
history, err = resources.ResourceHistory(t.Context(), "settings", 0)
if err != nil {
t.Fatalf("unlimited ResourceHistory: %v", err)
}
if len(history) != 2 {
t.Fatalf("history after late replay = %+v, want two revisions", history)
}
if _, err := resources.Resource(t.Context(), "missing"); !errors.Is(err, store.ErrResourceNotFound) {
t.Fatalf("missing Resource = %v, want ErrResourceNotFound", err)
}
}
// PostgreSQL admits concurrent writers, unlike SQLite's single writer. The
// resource lock keeps the expected-version comparison and audit append one
// serialized operation.
func TestConcurrentResourceWritesAcceptOnlyOneExpectedVersion(t *testing.T) {
resources := resourcesFor(t)
type result struct{ err error }
start := make(chan struct{})
results := make(chan result, 2)
for _, requestID := range []string{"first", "second"} {
go func() {
<-start
_, err := resources.PutResource(t.Context(), store.ResourceWrite{
Kind: "settings", Value: []byte(`{"v":1}`), Actor: "operator", Source: "test",
RequestID: requestID, ExpectedVersion: 0,
})
results <- result{err: err}
}()
}
close(start)
var succeeded, conflicted int
for range 2 {
outcome := <-results
switch {
case outcome.err == nil:
succeeded++
case errors.Is(outcome.err, store.ErrResourceVersionConflict):
conflicted++
default:
t.Fatalf("concurrent PutResource: %v", outcome.err)
}
}
if succeeded != 1 || conflicted != 1 {
t.Fatalf("concurrent writes = %d succeeded, %d conflicted; want 1 each", succeeded, conflicted)
}
history, err := resources.ResourceHistory(t.Context(), "settings", 0)
if err != nil {
t.Fatalf("ResourceHistory: %v", err)
}
if len(history) != 1 || history[0].Version != 1 {
t.Fatalf("history after race = %+v, want exactly one version 1", history)
}
}