From 038b8035ff2149adb83a9611257aa8e637dddf9c Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 01:38:40 +1000 Subject: [PATCH] feat(postgres): preserve resource write semantics --- .../postgres/postgresdb/resources.sql.go | 263 ++++++++++++++++++ .../postgres/queries/resources.sql | 45 +++ internal/infrastructure/postgres/resources.go | 142 ++++++++++ .../postgres/statestore_test.go | 135 +++++++++ 4 files changed, 585 insertions(+) create mode 100644 internal/infrastructure/postgres/postgresdb/resources.sql.go create mode 100644 internal/infrastructure/postgres/queries/resources.sql create mode 100644 internal/infrastructure/postgres/resources.go diff --git a/internal/infrastructure/postgres/postgresdb/resources.sql.go b/internal/infrastructure/postgres/postgresdb/resources.sql.go new file mode 100644 index 000000000..d76eca21b --- /dev/null +++ b/internal/infrastructure/postgres/postgresdb/resources.sql.go @@ -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 +} diff --git a/internal/infrastructure/postgres/queries/resources.sql b/internal/infrastructure/postgres/queries/resources.sql new file mode 100644 index 000000000..e8b8aa96b --- /dev/null +++ b/internal/infrastructure/postgres/queries/resources.sql @@ -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; diff --git a/internal/infrastructure/postgres/resources.go b/internal/infrastructure/postgres/resources.go new file mode 100644 index 000000000..d335fa740 --- /dev/null +++ b/internal/infrastructure/postgres/resources.go @@ -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, + } +} diff --git a/internal/infrastructure/postgres/statestore_test.go b/internal/infrastructure/postgres/statestore_test.go index 10112d263..027ca8381 100644 --- a/internal/infrastructure/postgres/statestore_test.go +++ b/internal/infrastructure/postgres/statestore_test.go @@ -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) + } +}