Skip to content

Establish complete PostgreSQL request context across Graphile execution - #1744

Draft
Zetazzz wants to merge 6 commits into
mainfrom
feat/complete-graphile-request-context
Draft

Establish complete PostgreSQL request context across Graphile execution#1744
Zetazzz wants to merge 6 commits into
mainfrom
feat/complete-graphile-request-context

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

Summary

This combines planning items F02, F13, and F16 into one atomic request-context correction based on main.

  • F02: @constructive-io/express-context now owns a canonical, complete pgSettings contract; pg-query-context applies all settings in one parameterized PostgreSQL round trip with transaction-local semantics.
  • F13: Graphile i18n and LLM request-lane SQL now consume the existing complete Grafast request context and fail closed when it is missing. Bulk mutation SQL uses the native @dataplan/pg query-config contract.
  • F16: PublicKeySignature derives a fresh anonymous execution context by copying the complete request settings and replacing only role with the configured anonymous role.
  • The GraphQL server consumes req.constructive.pgSettings instead of reconstructing a second, incomplete settings object. Unauthenticated identity-bearing private headers remain inert until a separate authenticated internal-ingress boundary owns their translation.
  • Ordered graphile.introspectionDependencySchemas are wired into the canonical request search_path alongside the resolved API schemas.

Planning: constructive-io/constructive-planning#1693

Ownership and security contract

packages/express-context owns the request facts and canonical builder. Every request gets a fresh object containing all supported security GUCs, with absent claims represented by empty strings, plus explicit role, request.id, transaction_read_only, search_path, and row_security values.

Trusted overrides are restricted to the declared security-GUC allowlist and reject accessors, symbols, arrays, nulls, non-string values, and PostgreSQL session controls such as role/search path/read-only/RLS. This PR does not translate caller-controlled identity headers into trusted claims; that requires the separately authenticated internal-ingress boundary excluded below.

postgres/pg-query-context owns application to PostgreSQL. Non-empty pooled context cannot be combined with skipTransaction; settings and callback failures roll back and release without replacing the original error. The direct algorithmic change is:

N per-setting SQL round trips -> 1 parameterized settings round trip

Ordinary Graphile lanes use the exact canonical object. The PublicKey lane creates a copy and changes only role; API/database/request identity, search path, RLS, read-only state, and empty-claim clearing are retained.

F13 package changes

  • graphile-i18n: request withPgClient + complete pgSettings, native query-config execution, deterministic fail-closed behavior.
  • graphile-llm: RAG and metering request lanes use the complete context; metadata queries use native query configs and preserve database errors while treating only absent optional module relations as unprovisioned.
  • graphile-bulk-mutations: insert/upsert/update/delete callbacks use typed native PgClient queries.
  • graphile-test: applies derivative settings in the existing test transaction and restores the primary request context. Root-mode fixtures default to the configured root connection user; explicit authRole, client context, and request role overrides remain effective. Real PostgreSQL regression tests cover root defaults, anonymous denial, explicit restricted roles, and restoration between requests.
  • CI includes pg-query-context in the PostgreSQL test group. Refusal-context assertions verify both claims in the batched settings call and the transaction boundaries.

No storage plugins were changed.

Schema and behavior

  • Public GraphQL SDL is unchanged.
  • A real schema introspection contract verifies the three existing PublicKey mutation names, arguments, and return types.
  • Signature verification remains behind its existing feature flag; this PR does not enable it or change that behavior.
  • The active PublicKey signup/challenge paths use the common anonymous helper. Disabled verification/failure-recording behavior is intentionally not activated here.

Validation

Rebased onto main@7d28f718c049. Verified final head 10574e19f6df223edbdfc0f795cdba373c828901:

Local verification:

  • CJS/ESM builds for 10 affected or restored packages passed.
  • Request-context regression checks across 7 packages: 12 suites / 109 tests passed. The 11 external Ollama tests were excluded only from this local run; the full remote AI job uses the real Ollama service.
  • Additional debugging regression run: 26 suites / 336 tests passed across graphile-test, express-context, aggregates, connection filters, bulk mutations, and preset integration.
  • CI package coverage check: all 108 test packages are assigned to a CI job.

Explicit exclusions

This does not include F01 runtime identity, F10 checkout sanitation, F14 storage snapshots/isolation, F07 SQL qualification, F08 cache ownership, F15 storage wiring, F17 build contracts, F18 admission or authenticated internal-ingress claims, scoped introspection behavior, build-state retirement, notification broker, pg-many-to-many, pnpm patches, Crystal/upstream changes, or performance-harness extensions.

@Zetazzz
Zetazzz force-pushed the feat/complete-graphile-request-context branch from f0b8184 to d9eb179 Compare August 16, 2026 14:02
@Zetazzz
Zetazzz force-pushed the test/performance-harness-core branch from 45cbb07 to 658736e Compare September 6, 2026 01:51
@Zetazzz
Zetazzz force-pushed the feat/complete-graphile-request-context branch from 9c8214b to 4e166ca Compare September 6, 2026 02:22
@Zetazzz
Zetazzz force-pushed the test/performance-harness-core branch from 658736e to f7c63ec Compare September 7, 2026 03:22
@Zetazzz
Zetazzz force-pushed the feat/complete-graphile-request-context branch from 4e166ca to 581262c Compare September 9, 2026 01:46
@Zetazzz
Zetazzz changed the base branch from test/performance-harness-core to main September 9, 2026 01:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant