Draft plan — live PostgreSQL verification for the pure-YAZA client

Status: Proposed draft test plan for review. This document is written to be folded into the API completion plan (Gate B evidence) or an RFC; it is not an accepted decision and does not change implementation status.

Current evidence and remaining gate: local PostgreSQL 17.6 migration and generated API CRUD/restart persistence passed through the pure-YAZA client. After the API lifecycle refactor, migration and the full database-configured HTTP smoke also passed against a disposable PostgreSQL 18.6 instance, covering startup/seed/readiness, CRUD, and restart persistence. These verify loopback/plaintext configurations only. Gate B still requires the wider TLS/authentication, version, transaction/failure, timeout, snapshot, sanitizer, and repeatable CI matrix. See the runtime matrix, Appendix G, and PostgreSQL snapshot format.

Scope of the verification

The matrix must cover, per supported PostgreSQL major version, and all through the pure-YAZA client over verified TLS:

1. TLS: verified handshake against a server certificate that is trusted, a wrong-hostname certificate, an expired certificate, a self-signed certificate with an explicit local-development trust override (if one is provided at all), and a server with TLS refused (client must fail closed, not fall back to plaintext).
2. SCRAM-SHA-256: successful login with the RFC 7677 exchange shape, wrong password, non-existent role, non-ASCII credential rejection, iteration bounds, tampered server signature.
3. Simple/extended queries: pg_query trusted static commands; pg_query_params and pg_query_with_parameters with PgParameters builders for Text, Number/int8, Int32/int4, Float64/float8, Boolean, Bytes/bytea hex, and explicit SQL NULL; SQL NULL preserved distinctly from empty text and zero; typed result accessors and their mismatch errors; the 10,000-cell/16 MiB response caps reached and rejected cleanly.
4. Transactions: pg_transaction_begin/query/commit/rollback; savepoints begin/release/rollback-to; nested-BEGIN rejection; commit after failed statement; command-tag and ReadyForQuery state matching; explicit rollback after a mid-transaction failure; connection left in a clean state for reuse.
5. Migrations: yaza db migrate ledger creation, checksum recording, re-run idempotence, editing an applied migration (must be rejected), interrupted run recovery, and out-of-order file handling.
6. Schema snapshot: yaza db snapshot against the live catalogs (tables, columns, types, nullability, defaults, keys, constraints), fingerprint match with the local migration set, atomic replacement of an existing snapshot file, and yaza db validate-snapshot offline acceptance/rejection behavior.
7. Timeouts and load: statement/lock/idle-in-transaction timeouts firing; cancel/pg_cancel path if exposed; a slow query held beyond the deadline; connection-close behavior mid-query; bounded keep-alive/reconnect for one session.
8. Security negatives: connection strings with bad host, refused TLS downgrades, malformed server error frames, injected identifier vs. static template, and credential handling (values never logged).

Test implementation plan

1. Local harness: a script (comparable to tests/http-smoke.sh) that starts the pinned PostgreSQL container from compose.yaml with a configured TLS-enabled server (server certificate + key generated at build time into the container volume), waits for readiness, runs the YAZA-language integration program exercising items 3–7, then runs CLI commands (migrate/status/snapshot/validate) and asserts outputs.
2. Version matrix: PostgreSQL 14, 15, 16, 17 in the first pass; pin exact versions in the compose file with one version per run; the snapshot records the server major version so offline validation can evolve per version.
3. Sanitizer builds: every YAZA-side binary in the harness runs under ASan/UBSan (with the current documented leak-detection caveat for Bytes retention) at least once per version.
4. Evidence recording: each passing matrix cell records: server version, transport (TLS + cipher if obtainable), SCRAM iteration count, command list, sanitizer status, and command exit codes; failures record the exact failing stage. Results update the capability matrix row and Appendix H item H.8.
5. CI integration: the harness runs on the GitHub Actions workflow used for runtime security (macOS runner first), with the PostgreSQL service container version pinned; hosted-runner evidence is what converts "locally verified" into "verified" in the docs.

Acceptance criteria

• Every item in the scope list passes on every matrix version with recorded evidence, or fails with a recorded defect.
• The migration + snapshot path round-trips against the live server: snapshot accepted after migrate, rejected after a migration edit, regenerated cleanly.
• No plaintext connection ever succeeds where verification is expected; TLS failure modes fail closed.
• The live and CI matrix verifies that the generated API lifecycle and CRUD paths continue to work without libpq; the generated binary must remain free of libpq dependencies.

Explicit prerequisites

• A TLS-enabled local PostgreSQL configuration (the current compose.yaml only provides a plain development server; certificate material must be generated by the harness, not committed).
• Confirmation of the macOS TLS provider boundary: net_tls_client currently uses deprecated Secure Transport and successful handshakes are not yet integration-tested anywhere (capability matrix); if that path fails live verification, the fix belongs to the runtime before this gate can pass.
• Statements in repository/docs adjusted only after evidence lands, per the project's standing "evidence before claim" rule.

← Kembali ke semua dokumentasiVersi dan status rilis →