Skip to content

F17: bind Graphile reuse to the exact build contract - #1852

Open
Zetazzz wants to merge 4 commits into
agent/graphile-readiness-disposalfrom
graphile-build-identity-c8f5bfd9
Open

Zetazzz wants to merge 4 commits into
agent/graphile-readiness-disposalfrom
graphile-build-identity-c8f5bfd9

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Implements F17 from constructive-io/constructive-planning#1693, stacked on #1747 (F04).

A logical service key can resolve to different databases, schemas, roles, plugin settings, or compute bindings. Server and Explorer snapshot their effective build inputs and use a domain-separated, process-local HMAC fingerprint for cache reuse. Functions and opaque objects retain reference identity; credentials stay out of cache keys. The captured inputs also construct the preset.

Service, database, and physical-pool invalidation use explicit entry metadata to remove every build variant. Public schema notifications invalidate by database before hostname lookup. Existing scoped-introspection wiring is preserved.

The server reuses the API, pool, service key, module loader, and PostgreSQL settings owned by req.constructive. Missing request claims were added to the express-context owner, including current request protection, principal/read-only credentials, trusted private identity headers, and anonymous database attribution. Shared schemas read these settings per request. The canonical errors package retains internal causes and registered HTTP status/code while excluding private messages and context. /flush authenticates and invalidates before starting a Graphile build.

Validation: 130 express-context tests; 50 graphile-cache tests at this layer; targeted error/snapshot/response/observability tests; seven real PostgreSQL/scoped-routing HTTP scenarios replace the mocked middleware tests. Server, Explorer, context and error-package builds passed. Final stack validation is recorded in #1855.

Dependency stack: #1747 → #1852 (F17) → #1853 (F19) → #1854 (F20) → #1855 (F21). F20 logically depends on F04/F17 and is stacked after F19 to share the admitted publication owner.

@tenki-reviewer

tenki-reviewer Bot commented Sep 21, 2026 •

Copy link
Copy Markdown

Review complete. No issues found — approved ✅.


This PR overhauls the GraphQL build cache. graphile-cache gains a deterministic canonicalizer/fingerprinter in build-identity.ts (typed-value handling and an HMAC digest used as the build-cache key) plus clearGraphileEntriesForService/Database/Pool eviction helpers with manual-eviction bookkeeping. The middleware stack is split: graphile-build-snapshot.ts snapshots the build, flush.ts exposes HTTP flush routes, and graphile.ts wires single-flight build creation with cache publication. The explorer now shares one graphile instance keyed by hash/service/pool and exposes a merged /flush handler.

The change is functionally coherent and the scoping/pool-cleanup wiring is consistent, but the adjudicated review surfaced three lower-confidence concerns that did not clear the reporting threshold: a TOCTOU window where an in-flight build can be re-published after a flush, the compute loader being awaited on every cache-hit request, and a nullish serviceKey potentially matching every entry in clearGraphileEntriesForService. Each is narrow and operator-guarded; none rises to a release blocker.

Files Change
graphile/graphile-cache/src/* Adds canonical build-identity fingerprinting and scoped clear/eviction helpers with pool-cleanup wiring
graphql/server/src/middleware/graphile.ts Reworks cache publication, compute resolution, and single-flight handling around the new cache key
graphql/server/src/middleware/graphile-build-snapshot.ts, flush.ts Adds snapshot capture and HTTP flush routes
graphql/explorer/src/server.ts, settings.ts Collapses caching onto a shared hash-keyed graphile instance with a merged /flush
*__tests__/* New unit tests for build identity, invalidation, flush, snapshot, and single-flight behavior
README.md, package.json Documentation and package metadata for the graphile-cache package

Reviewed commit: 9f64b13

@Zetazzz

Zetazzz commented Sep 21, 2026

Copy link
Copy Markdown
Contributor Author

Followed up on the three observations in the approval summary:

Validation: 6 focused invalidation tests on this branch; the final dependency stack passes all 84 graphile-cache tests, all 8 server flush tests, and the graphile-cache build.

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