150 lines
7.8 KiB
Markdown
150 lines
7.8 KiB
Markdown
# 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.
|