youfak/proxy-pool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
912db2aa18
proxy-pool/docs/superpowers/plans/2026-07-29-postgresql-admin-state.md
youfak 08800cb7a5 docs: design postgres admin state module
2026-07-29 18:17:26 +08:00

7.8 KiB
Raw Blame History

PostgreSQL Admin State Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build the authoritative PostgreSQL management-state module for config revisions, Upstream/Routing mutations, Admin audit and reliable Outbox without storing Proxy or per-extraction data.

Architecture: domain/adminstate defines narrow capability interfaces implemented by a concurrency-safe MemoryStore and one deep PostgreSQL Adapter. Every mutation hides a single transaction that commits state, audit and Outbox together. Both adapters run the same public contract; Controller Admin maps its existing typed commands onto this seam.

Tech Stack: Go 1.26, standard library, pgx/v5, PostgreSQL 18, Docker Compose.

Task 1: Domain Contracts and Immutable Values

Files:

  • Create: internal/domain/adminstate/adminstate.go

  • Create: internal/domain/adminstate/validation_test.go

  • Define Mutator, SnapshotReader and Outbox interfaces from ADR-006.

  • Define typed config, Upstream, Routing, actor, audit, event and mutation values.

  • Define stable errors for invalid input, missing resources, CAS conflict and unavailable storage.

  • Validate non-empty bounded identifiers, UTC timestamps, unique lists, config checksum, Routing references, claim limits and claim TTL.

  • Clone every slice/map/JSON value at the seam so callers cannot mutate stored state.

  • Run go test -count=1 -timeout 60s ./internal/domain/adminstate and verify the tests fail before implementation, then pass after implementation.

  • Commit with feat: define admin state transaction contracts.

Task 2: Memory Reference Adapter and Shared Contract

Files:

  • Create: internal/domain/adminstate/memory.go

  • Create: internal/domain/adminstate/contracttest/contract.go

  • Create: internal/domain/adminstate/contract_external_test.go

  • Write a public contract factory that can create an isolated Mutator + SnapshotReader + Outbox implementation.

  • Cover config commit/replay/conflict/invalid references and zero-write rollback.

  • Cover Upstream idempotency, monotonic revisions, mandatory audit and changed-only events.

  • Cover Routing CAS and 100 concurrent switches with at most one success.

  • Cover bounded claim, exclusive claim, lease expiry, ACK ownership and stable ordering.

  • Cover context cancellation and immutable Snapshot/output values.

  • Implement MemoryStore behind the seam with one mutex per atomic management state.

  • Run go test -count=1 -timeout 60s ./internal/domain/adminstate/....

  • Commit with feat: add transactional admin state reference store.

Task 3: Schema Migration and Static Data-Boundary Test

Files:

  • Create: internal/adapters/postgresadmin/migrations/0001_admin_state.sql

  • Create: internal/adapters/postgresadmin/migrations.go

  • Create: internal/adapters/postgresadmin/migrations_test.go

  • Embed ordered migrations and expose one Migrations() []Migration read-only accessor.

  • Create only the six ADR-006 tables with primary/foreign keys, UTC timestamps, indexes, outbox claim fields and bounded checks.

  • Add a parser-backed/static test that asserts required tables/columns are present and forbidden Proxy/extraction/ownership/idempotency tables or columns are absent.

  • Test migration IDs are unique, strictly ordered and statements are transactional.

  • Run go test -count=1 -timeout 60s ./internal/adapters/postgresadmin.

  • Commit with feat: add postgres admin state schema.

Task 4: PostgreSQL Deep Adapter

Files:

  • Create: internal/adapters/postgresadmin/adapter.go

  • Create: internal/adapters/postgresadmin/mutate.go

  • Create: internal/adapters/postgresadmin/snapshot.go

  • Create: internal/adapters/postgresadmin/outbox.go

  • Create: internal/adapters/postgresadmin/codec.go

  • Modify: go.mod

  • Modify: go.sum

  • Add the approved pinned pgx/v5 dependency without changing unrelated modules.

  • Accept a narrow pgx pool interface and options; reject nil pools and invalid namespaces.

  • Implement Config/Upstream/Routing mutations with SQL validation, row locks/CAS and one transaction for revision, state, audit and Outbox.

  • Map PostgreSQL constraint/CAS/connection errors to domain errors without leaking DSNs, SQL or values.

  • Implement immutable Snapshot reads from one repeatable-read transaction.

  • Implement bounded Outbox claim using FOR UPDATE SKIP LOCKED and guarded ACK.

  • Keep SQL, tx retries, codecs and driver types private to the Adapter.

  • Run focused unit tests and go vet ./internal/adapters/postgresadmin/....

  • Commit with feat: implement postgres admin state adapter.

Task 5: Real PostgreSQL Contract Fixture

Files:

  • Create: deploy/docker-compose.postgres-test.yml

  • Create: scripts/test-postgres.ps1

  • Create: internal/adapters/postgresadmin/testpostgres_test.go

  • Create: internal/adapters/postgresadmin/contract_integration_test.go

  • Create: internal/adapters/postgresadmin/rollback_integration_test.go

  • Start an isolated PostgreSQL 18 fixture on a dedicated loopback port and database.

  • Apply migrations through the same migration runner used by the production Adapter.

  • Run the public adminstate contract against a unique schema per test.

  • Inject audit and Outbox constraint failures and prove state/revision rollback.

  • Query information_schema and prove no Proxy, extraction, ownership or idempotency detail tables/columns exist.

  • Clean only the unique test schema; do not drop shared databases or use broad cleanup.

  • Run .\scripts\test-postgres.ps1 with every Go test timeout set to 60 seconds.

  • Commit with test: add postgres admin state contract fixture.

Task 6: Admin Application Integration

Files:

  • Create: internal/controller/admin/service.go

  • Create: internal/controller/admin/service_test.go

  • Modify: internal/controller/admin/handler.go

  • Modify: internal/controller/admin/handler_test.go

  • Change Admin protection to resolve httpsecurity.Identity once and add actor/source IP to mutation commands without exposing credentials.

  • Map typed Handler commands to adminstate.Mutator; map domain conflict/not-found/ invalid/unavailable errors to the existing HTTP contract.

  • Build Status from one adminstate Snapshot plus injected activity/worker aggregate readers.

  • Reload configuration with existing strict loader/validator, submit a secret-free management snapshot, then atomically publish runtime config only after persistence succeeds.

  • Test persistence failure leaves the current runtime config unchanged and Redis Extract is not referenced by the Admin module.

  • Run go test -count=1 -timeout 60s ./internal/controller/admin/....

  • Commit with feat: connect admin API to management state.

Task 7: Documentation and Delivery Verification

Files:

  • Modify: docs/development/implementation-plan.md

  • Modify: docs/requirements/completion-audit.md

  • Modify: docs/testing/test-strategy.md

  • Modify: docs/operations/runbook.md

  • Modify: progress.md

  • Mark only verified PostgreSQL capabilities complete and retain command/runtime/load gaps.

  • Document migration, backup, Outbox backlog/replay and data-boundary checks.

  • Run .\scripts\verify.ps1, .\scripts\test-redis.ps1, .\scripts\test-postgres.ps1 and git diff --check.

  • Audit that Gateway has no PostgreSQL/Redis dependency and Distribution has no PostgreSQL dependency.

  • Confirm the user-owned deletion of proxy-pool-docs-v1.0.zip is not staged.

  • Commit with docs: record postgres admin state delivery and push the feature branch.