From 56f230f7d9300b450d7c8fd42371da237bdc9505 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 15:53:06 +0800 Subject: [PATCH 01/10] Deploy production on push to `prod`. Production had no ref to release from: the workflow was manual dispatch only, so a release was whoever clicked "Run workflow", while the old repo released on push to its `prod` branch. `prod` is the production ref, so advancing it with `git push origin main:prod` is the release. No path filter, because a push here is already deliberate, and a concurrency group keeps one deploy running so a deploy is never interrupted between the api migration and the workers. --- .github/workflows/platform-deploy.yml | 10 ++++++++++ platform/README.md | 2 +- platform/meta/operations.md | 14 ++++++++------ 3 files changed, 19 insertions(+), 7 deletions(-) diff --git a/.github/workflows/platform-deploy.yml b/.github/workflows/platform-deploy.yml index 44ecf40d0..70d636752 100644 --- a/.github/workflows/platform-deploy.yml +++ b/.github/workflows/platform-deploy.yml @@ -1,8 +1,18 @@ name: Deploy Platform Production on: + push: + # `prod` is the production ref: it holds the commit that is live, and + # advancing it is the release. No path filter — a push here is deliberate. + branches: [prod] workflow_dispatch: +concurrency: + # One running deploy plus at most one pending. Never interrupt a deploy + # between the api migration and the workers that depend on it. + group: platform-deploy-production + cancel-in-progress: false + permissions: {} jobs: diff --git a/platform/README.md b/platform/README.md index f7ac71832..bce547677 100644 --- a/platform/README.md +++ b/platform/README.md @@ -73,7 +73,7 @@ Paths in this file are relative to `platform/` unless they begin with `../`. For The `@voidcloud/platform` workspace package retains the dashboard-only `dev` and `build` scripts. Dashboard deploys run after the platform workers in the platform deploy pipeline. -**Production deploys are manual only; staging deploys on every push to `main`.** See [`meta/operations.md`](./meta/operations.md#github-actions) for the workflow triggers. Do not ask to push or deploy. +**Production deploys on push to `prod`; staging deploys on every push to `main`.** See [`meta/operations.md`](./meta/operations.md#github-actions) for the workflow triggers. Do not push `prod` or ask to deploy. ## Local Development diff --git a/platform/meta/operations.md b/platform/meta/operations.md index 964cfa20e..5f42387d5 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -27,10 +27,10 @@ Five Cloudflare Workers: Two fully isolated environments. Each has its own CF resources (KV, R2, dispatch namespace, analytics engine) and a separate Hyperdrive configuration pointing to its own PlanetScale PostgreSQL database. -| Environment | API URL | Dashboard | User Sites | Trigger | -| -------------- | ------------------------ | ------------------------- | -------------------- | ----------------------------------------------------------------------------- | -| **Production** | `api.void.cloud` | `dash.void.cloud` | `*.void.app` | Manual: "Deploy Platform Production" workflow | -| **Staging** | `api.staging.void.cloud` | `dash.staging.void.cloud` | `*.staging.void.app` | Automatic: "Deploy Platform Staging" on push to `main` (also manual dispatch) | +| Environment | API URL | Dashboard | User Sites | Trigger | +| -------------- | ------------------------ | ------------------------- | -------------------- | -------------------------------------------------------------------------------- | +| **Production** | `api.void.cloud` | `dash.void.cloud` | `*.void.app` | Automatic: "Deploy Platform Production" on push to `prod` (also manual dispatch) | +| **Staging** | `api.staging.void.cloud` | `dash.staging.void.cloud` | `*.staging.void.app` | Automatic: "Deploy Platform Staging" on push to `main` (also manual dispatch) | ## Cloudflare Resources @@ -231,7 +231,7 @@ Two GitHub environments (`Prod` and `Staging`) share the same repo-level secrets | `CF_ACCESS_CLIENT_ID_STAGING` | Staging | CF Access service-token client id for reaching staging (see Staging Access Control) | | `CF_ACCESS_CLIENT_SECRET_STAGING` | Staging | CF Access service-token client secret for reaching staging | -`platform-deploy.yml` uses the `Prod` environment and runs only on manual dispatch; `platform-deploy-staging.yml` uses `Staging` and also runs on every push to `main` that matches the `platform-ci.yml` path filter. Both run only when the repository variable `VOID_PLATFORM_DEPLOY_ENABLED` is `true`. +`platform-deploy.yml` uses the `Prod` environment and runs on every push to `prod` or on manual dispatch; `platform-deploy-staging.yml` uses `Staging` and runs on every push to `main` that matches the `platform-ci.yml` path filter, or on manual dispatch. Both run only when the repository variable `VOID_PLATFORM_DEPLOY_ENABLED` is `true`. **GitHub Actions `CF_API_TOKEN` permissions** — narrower-scope token used only for wrangler deploys. Separate from the API worker runtime token. @@ -514,12 +514,14 @@ Four platform workflows live in the repository-level `.github/workflows/` direct 6. `vp test run --project platform-unit` and `--project platform-api-integration` 7. Builds the API build container image (PRs only) -**`platform-deploy.yml`** — manual dispatch (production, environment: `Prod`): +**`platform-deploy.yml`** — push to `prod`, or manual dispatch (production, environment: `Prod`): 1. Runs `platform-ci.yml` first 2. `vp run build` (SDK packages the dashboard bundles) 3. `vp run --filter @voidcloud/platform deploy` (api with drizzle-kit migrations, proxy, tail, dispatch, dashboard) +`prod` is the production ref: it points at the commit that is live, so advancing it is the release (`git push origin main:prod` deploys whatever `main` is at). There is no path filter — a push to `prod` is deliberate. A `concurrency` group (`platform-deploy-production`, `cancel-in-progress: false`) keeps one deploy running and at most one pending, so a deploy is never interrupted between the API migration and the workers. + **`platform-deploy-staging.yml`** — push to `main` that matches the `platform-ci.yml` path filter, or manual dispatch (staging, environment: `Staging`): 1. Runs `platform-ci.yml` first From 590a8a47b5a67c4b39b7658442b1f3d1139ef76b Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 15:56:24 +0800 Subject: [PATCH 02/10] Document the `prod` ruleset. The branch that deploys production is now protected, so say who can move it rather than leaving the readme to imply anyone with push access can. --- platform/meta/operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform/meta/operations.md b/platform/meta/operations.md index 5f42387d5..13f70417b 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -520,7 +520,7 @@ Four platform workflows live in the repository-level `.github/workflows/` direct 2. `vp run build` (SDK packages the dashboard bundles) 3. `vp run --filter @voidcloud/platform deploy` (api with drizzle-kit migrations, proxy, tail, dispatch, dashboard) -`prod` is the production ref: it points at the commit that is live, so advancing it is the release (`git push origin main:prod` deploys whatever `main` is at). There is no path filter — a push to `prod` is deliberate. A `concurrency` group (`platform-deploy-production`, `cancel-in-progress: false`) keeps one deploy running and at most one pending, so a deploy is never interrupted between the API migration and the workers. +`prod` is the production ref: it points at the commit that is live, so advancing it is the release (`git push origin main:prod` deploys whatever `main` is at). There is no path filter — a push to `prod` is deliberate. The branch carries a `prod` ruleset that blocks deletion and force-pushes and allows updates only from its bypass actors (organization admins, repository admins, and the `Void` team), so a push to `prod` is a maintainer action. A `concurrency` group (`platform-deploy-production`, `cancel-in-progress: false`) keeps one deploy running and at most one pending, so a deploy is never interrupted between the API migration and the workers. **`platform-deploy-staging.yml`** — push to `main` that matches the `platform-ci.yml` path filter, or manual dispatch (staging, environment: `Staging`): From 9d30e83402e98ae73121ff85bcd905bf02eeaad3 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 16:36:05 +0800 Subject: [PATCH 03/10] Restore the schema-compatibility guard for production. `platform-deploy.yml` migrates before it deploys the api worker, so a push to `prod` applies a new schema while the previous release is still serving. The former repository checked that on every platform CI run; the job came over inert here, waiting for the production ref to be chosen. Migrate a real Postgres with the ref under test, then run the production ref's integration tests against that schema. It runs on PRs, where the code under test differs from what is live, and on the production deploy itself; staging deploys skip it. Until `prod` is advanced past the platform merge there is no baseline to compare against, so the job warns instead of failing. --- .github/workflows/platform-ci.yml | 78 +++++++++++++++++++++++++++++-- 1 file changed, 73 insertions(+), 5 deletions(-) diff --git a/.github/workflows/platform-ci.yml b/.github/workflows/platform-ci.yml index 85a063fdf..951cbf777 100644 --- a/.github/workflows/platform-ci.yml +++ b/.github/workflows/platform-ci.yml @@ -75,11 +75,79 @@ jobs: - run: vp run --filter './platform/packages/**' build - run: vp test run --project ${{ matrix.project }} - # The former repository compared migrations against its `prod` branch. The merged repository's - # production ref has intentionally not been chosen yet, so this job remains visible but inert - # until the deployment-cutover change supplies the authoritative ref. + # The production guard. `platform-deploy.yml` migrates before it deploys the api worker, so a + # push to `prod` applies a new schema while the previous release is still serving traffic. This + # migrates a real Postgres with the migrations under test, then runs the production ref's + # integration tests against that schema: if the code that is live cannot run on the new schema, + # the push must not ship. + # + # It has teeth on PRs, where the code under test is a different commit from the one that is + # live. On a push to `prod` the caller is the deploy itself, so the job covers the migrations + # rather than a code difference. Staging deploys skip it: they cannot break production, and they + # run on nearly every push to `main`. schema-compat: - if: ${{ false }} + if: github.event_name == 'pull_request' || github.ref == 'refs/heads/prod' runs-on: blacksmith-4vcpu-ubuntu-2404 + timeout-minutes: 20 + permissions: + contents: read + env: + POSTGRES_USER: void_ci + POSTGRES_PASSWORD: void_ci_pass + POSTGRES_DB: void_schema_compat + COMPAT_DATABASE_URL: postgresql://void_ci:void_ci_pass@localhost:5432/void_schema_compat + services: + postgres: + image: postgres:18 + env: + POSTGRES_USER: ${{ env.POSTGRES_USER }} + POSTGRES_PASSWORD: ${{ env.POSTGRES_PASSWORD }} + POSTGRES_DB: ${{ env.POSTGRES_DB }} + ports: + - 5432:5432 + options: >- + --health-cmd="pg_isready -U $POSTGRES_USER" + --health-interval=5s + --health-timeout=5s + --health-retries=5 steps: - - run: echo 'Enable after choosing the merged repository production ref.' + # Phase 1 — apply the migrations under test to a real Postgres. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0 + with: + cache: true + node-version-file: .node-version + - run: vp run build + - run: vp run --filter @voidcloud/api migrate + env: + DATABASE_URL: ${{ env.COMPAT_DATABASE_URL }} + + # Phase 2 — the production ref's code must still run on that schema. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: prod + persist-credentials: false + - name: Does the production ref carry the platform? + id: production + run: | + if [ -d platform/packages/api ]; then + echo 'usable=true' >> "$GITHUB_OUTPUT" + else + echo 'usable=false' >> "$GITHUB_OUTPUT" + echo '::warning::The production ref predates the platform, so this check has no baseline yet. It starts comparing once the prod branch is advanced past the platform merge.' + fi + - if: steps.production.outputs.usable == 'true' + uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0 + with: + cache: true + node-version-file: .node-version + - name: Run the production ref's integration tests on the migrated schema + if: steps.production.outputs.usable == 'true' + run: | + vp run build + vp run --filter './platform/packages/**' build + vp test run --project platform-api-integration + env: + VOID_TEST_DATABASE_URL: ${{ env.COMPAT_DATABASE_URL }} From 2a42603e03c9cd817cc28940aefed305492b65ee Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 16:53:44 +0800 Subject: [PATCH 04/10] Compare a production deploy against the release it replaces. The compatibility baseline was the `prod` branch, which on a push already resolves to the commit being deployed, so the check never saw the code that is live while its migrations run. Use the push event's previous commit instead; PRs keep comparing against the deployed branch. The production deploy also asks for the guard on every trigger, so a manual dispatch from any ref cannot skip it, and the job pins TZ=UTC because the suite compares Postgres timestamps against local time. --- .github/workflows/platform-ci.yml | 45 ++++++++++++++++++++++----- .github/workflows/platform-deploy.yml | 4 +++ 2 files changed, 41 insertions(+), 8 deletions(-) diff --git a/.github/workflows/platform-ci.yml b/.github/workflows/platform-ci.yml index 951cbf777..a92c765b3 100644 --- a/.github/workflows/platform-ci.yml +++ b/.github/workflows/platform-ci.yml @@ -12,6 +12,11 @@ on: - 'vite.config.ts' - '.github/workflows/platform-*.yml' workflow_call: + inputs: + require-schema-compat: + description: Run the production schema-compatibility guard. The production deploy sets this for every trigger. + type: boolean + default: false permissions: {} @@ -82,11 +87,11 @@ jobs: # the push must not ship. # # It has teeth on PRs, where the code under test is a different commit from the one that is - # live. On a push to `prod` the caller is the deploy itself, so the job covers the migrations - # rather than a code difference. Staging deploys skip it: they cannot break production, and they - # run on nearly every push to `main`. + # live. The production deploy sets `require-schema-compat` for every trigger — including a + # manual dispatch, which can be started from any ref and would otherwise skip the job. Staging + # deploys skip it: they cannot break production, and they run on nearly every push to `main`. schema-compat: - if: github.event_name == 'pull_request' || github.ref == 'refs/heads/prod' + if: github.event_name == 'pull_request' || inputs.require-schema-compat runs-on: blacksmith-4vcpu-ubuntu-2404 timeout-minutes: 20 permissions: @@ -96,6 +101,9 @@ jobs: POSTGRES_PASSWORD: void_ci_pass POSTGRES_DB: void_schema_compat COMPAT_DATABASE_URL: postgresql://void_ci:void_ci_pass@localhost:5432/void_schema_compat + # Pinned: the suite compares timestamps written by Postgres with local time, so a + # runner whose locale is not UTC shifts them by the offset. + TZ: UTC services: postgres: image: postgres:18 @@ -124,19 +132,40 @@ jobs: env: DATABASE_URL: ${{ env.COMPAT_DATABASE_URL }} - # Phase 2 — the production ref's code must still run on that schema. + # Phase 2 — the release that is live must still run on that schema. On a push that is the + # commit `prod` pointed at before the push, never the commit being deployed: the api worker + # is replaced after its migrations run, so the previous release is what serves traffic for + # the length of the deploy. PRs compare against the deployed branch. + - name: Resolve the compatibility baseline + id: baseline + env: + EVENT_NAME: ${{ github.event_name }} + PREVIOUS_SHA: ${{ github.event.before }} + run: | + if [ "$EVENT_NAME" = 'push' ]; then + printf '%s' "$PREVIOUS_SHA" | grep -Eq '^[0-9a-f]{40}$' || { + echo '::error::The push event carries no previous commit to compare against.' + exit 1 + } + echo "ref=$PREVIOUS_SHA" >> "$GITHUB_OUTPUT" + else + echo 'ref=prod' >> "$GITHUB_OUTPUT" + fi - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: prod + ref: ${{ steps.baseline.outputs.ref }} persist-credentials: false - - name: Does the production ref carry the platform? + - name: Does the baseline carry the platform? id: production run: | if [ -d platform/packages/api ]; then echo 'usable=true' >> "$GITHUB_OUTPUT" else + # Production still runs a pre-monorepo revision, so there is no platform code to test + # against: the schema is checked, the code is not. That gap closes with the first + # release from this repository, after which this branch stops being taken. echo 'usable=false' >> "$GITHUB_OUTPUT" - echo '::warning::The production ref predates the platform, so this check has no baseline yet. It starts comparing once the prod branch is advanced past the platform merge.' + echo '::warning::The compatibility baseline predates the platform, so the production code was not exercised against the migrated schema. This stops once prod carries the platform.' fi - if: steps.production.outputs.usable == 'true' uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0 diff --git a/.github/workflows/platform-deploy.yml b/.github/workflows/platform-deploy.yml index 70d636752..085e404f5 100644 --- a/.github/workflows/platform-deploy.yml +++ b/.github/workflows/platform-deploy.yml @@ -19,6 +19,10 @@ jobs: ci: if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }} uses: ./.github/workflows/platform-ci.yml + with: + # Every production trigger runs the schema-compatibility guard, whichever ref the + # dispatch came from. + require-schema-compat: true permissions: contents: read From e11090621ec914385a81731bc528c7376c6d87f0 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 16:53:44 +0800 Subject: [PATCH 05/10] Make two integration tests hold on a real Postgres. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both pin an interleaving that only PGlite's single-connection statement queue produces, and both drive code rewritten after the merge (60afd361, e3bd5168) in ways that invalidated the trick while still passing on PGlite: - sandbox teardown race: the fire-and-forget status flip opened a new session on a pool and lost to the deploy's warm connection, so the deploy committed live. Hook the `cutover-ready:` write instead — no transaction is open there — and await the flip and the routing delete. - rollback-vs-rollback: Postgres grants the queued row lock at the other rollback's commit, so the loser read the rollback lease and answered 409. Hold the second rollback at the transaction seam until the first has fully finished, which is the serialization this test is about. The suite now passes on PGlite and on Postgres 18 with the migrations applied. --- .../test/integration/api-migrations.test.ts | 56 ++++++++++++++----- .../api/test/integration/api-sandbox.test.ts | 22 ++++---- 2 files changed, 53 insertions(+), 25 deletions(-) diff --git a/platform/packages/api/test/integration/api-migrations.test.ts b/platform/packages/api/test/integration/api-migrations.test.ts index 5026d8e63..d4484d843 100644 --- a/platform/packages/api/test/integration/api-migrations.test.ts +++ b/platform/packages/api/test/integration/api-migrations.test.ts @@ -4564,10 +4564,42 @@ describe('POST /projects/:id/migrations/rename', () => { ); await aReachedPut; - // Kick rollback B to C. It enters the tx callback and blocks on the - // per-project row lock — A still holds it. (On PGlite this is also - // enforced by the underlying single-connection serialization, a safe - // upper bound for this test.) + // B is held at the waypoint between its pre-lock reads and its row-lock + // acquisition, so it can only run once A's rollback — including the + // post-commit lease cleanup — has finished. The wrapper is installed after + // A's transaction started, so the first transaction it sees is B's. + // + // Without the hold the driver decides the order: PGlite queues statements, + // so B's in-lock read runs after A's cleanup, while a pooled Postgres grants + // the queued row lock at A's commit, so B resumes before that cleanup, reads + // A's rollback lease and answers 409 `deploy in progress`. That fence is + // real, but it is driver order rather than the serialization under test. + const realDb = env.db; + const realTransaction = realDb.transaction.bind(realDb); + let releaseB: () => void = () => {}; + const bHold = new Promise((r) => { + releaseB = r; + }); + let bHoldFired = false; + const wrappedDb: Db = new Proxy(realDb, { + get(target, prop, receiver) { + if (prop === 'transaction') { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + return (async (fn: any) => { + if (!bHoldFired) { + bHoldFired = true; + await bHold; + } + return realTransaction(fn); + }) as unknown as typeof realDb.transaction; + } + return Reflect.get(target, prop, receiver); + }, + }) as Db; + setTestDb(wrappedDb); + + // Kick rollback B to C. It does its pre-lock reads, then waits at the + // waypoint until A's rollback has fully completed. const rollbackBPromise = app.fetch( authedReq(`/projects/${project.id}/rollback`, user.jwt, { method: 'POST', @@ -4576,18 +4608,14 @@ describe('POST /projects/:id/migrations/rename', () => { env, ); - // Give B's request time to reach its tx/lock acquisition and - // actually be blocked. We cannot poll pg to confirm this — a - // `SELECT` through env.db would itself block on the single - // PGlite connection that A's tx still holds — so we use a small - // sleep. Release A afterward. - await new Promise((r) => setTimeout(r, 30)); - - // Release A. It commits the tx (pg active=B, ROUTING=B, etc), - // then B acquires the lock and flips pg active=C, ROUTING=C. + // Release A. It commits the tx (pg active=B, ROUTING=B, etc) and clears its + // rollback lease, then B acquires the lock and flips pg active=C, ROUTING=C. releaseA(); - const [resA, resB] = await Promise.all([rollbackAPromise, rollbackBPromise]); + const resA = await rollbackAPromise; expect(resA.status).toBe(200); + releaseB(); + const resB = await rollbackBPromise; + setTestDb(realDb); expect(resB.status).toBe(200); const bodyA = (await resA.json()) as { diff --git a/platform/packages/api/test/integration/api-sandbox.test.ts b/platform/packages/api/test/integration/api-sandbox.test.ts index a591b0f69..2dafd560a 100644 --- a/platform/packages/api/test/integration/api-sandbox.test.ts +++ b/platform/packages/api/test/integration/api-sandbox.test.ts @@ -503,25 +503,26 @@ describe('per-deploy sandbox integration', () => { const originalPut = env.ROUTING.put.bind(env.ROUTING); const originalDelete = env.ROUTING.delete.bind(env.ROUTING); let teardownTriggered = false; - let teardownPromise: Promise | undefined; const putSpy = vi.spyOn(env.ROUTING, 'put').mockImplementation((async ( key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream, options?: KVNamespacePutOptions, ) => { const result = await originalPut(key, value as never, options as never); - if (key === project.slug && !teardownTriggered) { + // The `cutover-ready:` key is written after the routing-switch transaction + // commits and before the deploy's finalize transaction opens, so the + // teardown writes can be awaited here: no transaction is open, nothing + // deadlocks, and the flip is guaranteed to land before the finalize read. + // Queuing them instead (the earlier shape) only ordered them in PGlite's + // favour — on a pooled Postgres the flip opened a new session and lost the + // race against the deploy's warm connection, which committed live. + if (key.startsWith('cutover-ready:') && !teardownTriggered) { teardownTriggered = true; - // Queue teardown behind the cutover's project-row lock. Do not await - // it here: PGlite uses one connection, so awaiting a second query from - // inside the transaction-backed ROUTING mock would deadlock the test. - // The queued query runs as soon as the cutover transaction releases - // the lock, before deploy's following database-finalize transaction. - teardownPromise = env.db + await env.db .update(projects) .set({ status: 'deleting' }) - .where(eq(projects.id, project.id)) - .then(() => originalDelete(project.slug)); + .where(eq(projects.id, project.id)); + await originalDelete(project.slug); } return result; }) as typeof env.ROUTING.put); @@ -538,7 +539,6 @@ describe('per-deploy sandbox integration', () => { typeof e === 'object' && e !== null && (e as { event?: unknown }).event === 'error', ); expect(errorEvent).toBeDefined(); - await teardownPromise; // Teardown's deletion remains authoritative. Before the compensation // fence, restoreTrackedRouting() put `previousRouting` back here and a From c4463407fbe6c24b2ef2ffdb3b47daaf7a538131 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 17:21:19 +0800 Subject: [PATCH 06/10] Require released migrations to be append-only. `drizzle-kit migrate` applies only journal entries whose `when` is later than the last entry it applied and never compares the stored hash, so production skips an edited historical `.sql` and a new entry whose timestamp is not after the last applied one. A fresh database applies both, which let the schema guard pass on a migration set production would not apply. `check-migration-set.ts` reads two drizzle directories and reports every way the candidate is not an append-only extension of the released set: a released file modified or removed, the released journal no longer a prefix, or a new entry not newer than the one before it. The `schema-compat` job copies the candidate's migrations and the checker aside before the baseline checkout and runs it against the baseline's migrations. With that, migrating a fresh database is the same operation as upgrading production's. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01WNXbwieSdsSErZwQ7HWRwG --- .github/workflows/platform-ci.yml | 15 +- platform/meta/operations.md | 1 + .../api/scripts/check-migration-set.ts | 188 ++++++++++++++++++ .../api/test/unit/check-migration-set.test.ts | 186 +++++++++++++++++ 4 files changed, 389 insertions(+), 1 deletion(-) create mode 100644 platform/packages/api/scripts/check-migration-set.ts create mode 100644 platform/packages/api/test/unit/check-migration-set.test.ts diff --git a/.github/workflows/platform-ci.yml b/.github/workflows/platform-ci.yml index a92c765b3..97c0586a9 100644 --- a/.github/workflows/platform-ci.yml +++ b/.github/workflows/platform-ci.yml @@ -84,7 +84,9 @@ jobs: # push to `prod` applies a new schema while the previous release is still serving traffic. This # migrates a real Postgres with the migrations under test, then runs the production ref's # integration tests against that schema: if the code that is live cannot run on the new schema, - # the push must not ship. + # the push must not ship. The fresh database stands in for production's only while the + # migrations under test are the released ones plus new entries, so the job also rejects any + # edit, removal, or reordering of a released migration. # # It has teeth on PRs, where the code under test is a different commit from the one that is # live. The production deploy sets `require-schema-compat` for every trigger — including a @@ -151,6 +153,11 @@ jobs: else echo 'ref=prod' >> "$GITHUB_OUTPUT" fi + # The baseline checkout replaces the workspace, and the baseline may predate the checker. + - name: Keep the candidate's migration set for the append-only check + run: | + cp -R platform/packages/api/drizzle "$RUNNER_TEMP/candidate-drizzle" + cp platform/packages/api/scripts/check-migration-set.ts "$RUNNER_TEMP/check-migration-set.ts" - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ steps.baseline.outputs.ref }} @@ -167,6 +174,12 @@ jobs: echo 'usable=false' >> "$GITHUB_OUTPUT" echo '::warning::The compatibility baseline predates the platform, so the production code was not exercised against the migrated schema. This stops once prod carries the platform.' fi + # Production applies only journal entries newer than its last applied one and never re-runs + # an entry it has applied, so a candidate that edits, removes, or reorders released + # migrations would migrate this fresh database differently from production. Reject it. + - name: The candidate must only append to the released migrations + if: steps.production.outputs.usable == 'true' + run: node "$RUNNER_TEMP/check-migration-set.ts" --baseline platform/packages/api/drizzle --candidate "$RUNNER_TEMP/candidate-drizzle" - if: steps.production.outputs.usable == 'true' uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0 with: diff --git a/platform/meta/operations.md b/platform/meta/operations.md index 13f70417b..3dee76448 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -513,6 +513,7 @@ Four platform workflows live in the repository-level `.github/workflows/` direct 5. `vp run check:platform` and `vp run check:sdk` (typecheck the platform packages and the SDK packages; the playgrounds are typechecked by `ci.yml`) 6. `vp test run --project platform-unit` and `--project platform-api-integration` 7. Builds the API build container image (PRs only) +8. The production schema-compatibility guard (`schema-compat`; PRs and every production deploy): applies the migrations under test to a fresh Postgres 18, then runs the live release's `platform-api-integration` suite against that schema. Released migrations are append-only: an edit, a removal, a reordering, or a new entry whose journal timestamp is not after the last released one fails the guard, because production never re-applies a migration it has applied and skips an entry that is not newer than its last. **`platform-deploy.yml`** — push to `prod`, or manual dispatch (production, environment: `Prod`): diff --git a/platform/packages/api/scripts/check-migration-set.ts b/platform/packages/api/scripts/check-migration-set.ts new file mode 100644 index 000000000..9d4c0990d --- /dev/null +++ b/platform/packages/api/scripts/check-migration-set.ts @@ -0,0 +1,188 @@ +/** + * Checks that a candidate drizzle migration set is an append-only extension of the released + * set: every released file is unchanged, the released journal is a prefix of the candidate + * journal, and every new entry is newer than the one before it. + * + * `drizzle-kit migrate` applies only journal entries whose `when` is later than the last entry + * it applied and never re-runs an entry it has applied, so a set that fails this check would + * migrate a fresh database differently from production. The `schema-compat` CI job runs this + * from `$RUNNER_TEMP`, so it must not import anything from the repository. + * + * Usage: + * node scripts/check-migration-set.ts --baseline --candidate + */ + +import { createHash } from 'node:crypto'; +import { existsSync, readdirSync, readFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { parseArgs } from 'node:util'; + +export type JournalEntry = Readonly<{ idx: number; tag: string; when: number }>; + +export type MigrationSet = Readonly<{ + /** relative path → sha256 hex, for every file under the migrations dir except meta/_journal.json */ + files: ReadonlyMap; + journal: ReadonlyArray; +}>; + +const JOURNAL_PATH = 'meta/_journal.json'; + +// ── Reading ───────────────────────────────────────────────────────── + +function hashFilesUnder(dir: string, prefix: string, into: Map): void { + for (const entry of readdirSync(join(dir, prefix), { withFileTypes: true })) { + const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name; + if (entry.isDirectory()) { + hashFilesUnder(dir, relativePath, into); + } else if (relativePath !== JOURNAL_PATH) { + into.set( + relativePath, + createHash('sha256') + .update(readFileSync(join(dir, relativePath))) + .digest('hex'), + ); + } + } +} + +function readJournal(dir: string): ReadonlyArray { + const path = join(dir, JOURNAL_PATH); + const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8')); + const entries = + typeof parsed === 'object' && parsed !== null && 'entries' in parsed + ? parsed.entries + : undefined; + if (!Array.isArray(entries)) { + throw new Error(`${path} has no "entries" array`); + } + return entries.map((raw: unknown, i) => { + if ( + typeof raw !== 'object' || + raw === null || + !('idx' in raw && typeof raw.idx === 'number') || + !('tag' in raw && typeof raw.tag === 'string') || + !('when' in raw && typeof raw.when === 'number') + ) { + throw new Error(`${path} entry ${i} lacks a numeric idx, a string tag, or a numeric when`); + } + return { idx: raw.idx, tag: raw.tag, when: raw.when }; + }); +} + +export function readMigrationSet(dir: string): MigrationSet { + const files = new Map(); + hashFilesUnder(dir, '', files); + return { files, journal: readJournal(dir) }; +} + +// ── Comparison ────────────────────────────────────────────────────── + +function describeEntry(entry: JournalEntry): string { + return `${entry.tag} (idx ${entry.idx}, when ${entry.when})`; +} + +/** Returns the reasons the candidate is not an append-only extension of the baseline; empty when it is. */ +export function compareMigrationSets( + baseline: MigrationSet, + candidate: MigrationSet, +): Array { + const problems: Array = []; + + let releasedFilesChanged = false; + for (const [path, hash] of baseline.files) { + const candidateHash = candidate.files.get(path); + if (candidateHash === undefined) { + problems.push(`released migration ${path} was removed`); + releasedFilesChanged = true; + } else if (candidateHash !== hash) { + problems.push(`released migration ${path} was modified`); + releasedFilesChanged = true; + } + } + if (releasedFilesChanged) { + problems.push( + 'Production never re-applies a migration it has already applied, so this database would not match production.', + ); + } + + if (candidate.journal.length < baseline.journal.length) { + problems.push( + `journal is shorter than the released journal (${candidate.journal.length} entries, released ${baseline.journal.length})`, + ); + return problems; + } + for (let i = 0; i < baseline.journal.length; i++) { + const released = baseline.journal[i]; + const proposed = candidate.journal[i]; + if ( + released.idx !== proposed.idx || + released.tag !== proposed.tag || + released.when !== proposed.when + ) { + problems.push( + `journal entry ${i} differs from the released journal: released ${describeEntry(released)}, candidate ${describeEntry(proposed)}`, + ); + return problems; + } + } + + for (let i = baseline.journal.length; i < candidate.journal.length; i++) { + const previous = candidate.journal[i - 1]; + const entry = candidate.journal[i]; + if (previous !== undefined && entry.when <= previous.when) { + problems.push( + `migration ${entry.tag} (idx ${entry.idx}) has timestamp ${entry.when}, not after the previous entry ${previous.tag} (${previous.when}); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.`, + ); + } + } + + return problems; +} + +// ── CLI ───────────────────────────────────────────────────────────── + +function main(): void { + const { values } = parseArgs({ + options: { + baseline: { type: 'string' }, + candidate: { type: 'string' }, + }, + }); + + if (!values.baseline || !values.candidate) { + console.error( + 'Usage: node check-migration-set.ts --baseline --candidate ', + ); + process.exit(1); + } + + if (!existsSync(join(values.baseline, JOURNAL_PATH))) { + console.log( + `The baseline ${values.baseline} has no ${JOURNAL_PATH}, so there is no released migration set to compare against.`, + ); + return; + } + if (!existsSync(join(values.candidate, JOURNAL_PATH))) { + console.error(`::error::The candidate ${values.candidate} has no ${JOURNAL_PATH}.`); + process.exit(1); + } + + const baseline = readMigrationSet(values.baseline); + const candidate = readMigrationSet(values.candidate); + const problems = compareMigrationSets(baseline, candidate); + + if (problems.length > 0) { + for (const problem of problems) { + console.error(`::error::${problem}`); + } + process.exit(1); + } + + console.log( + `Migration set is an append-only extension of the released set (${baseline.journal.length} released, ${candidate.journal.length - baseline.journal.length} new).`, + ); +} + +if (import.meta.main) { + main(); +} diff --git a/platform/packages/api/test/unit/check-migration-set.test.ts b/platform/packages/api/test/unit/check-migration-set.test.ts new file mode 100644 index 000000000..ef642f1dd --- /dev/null +++ b/platform/packages/api/test/unit/check-migration-set.test.ts @@ -0,0 +1,186 @@ +import { createHash } from 'node:crypto'; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; +import { afterAll, describe, expect, it } from 'vite-plus/test'; +import { + compareMigrationSets, + readMigrationSet, + type JournalEntry, + type MigrationSet, +} from '../../scripts/check-migration-set.ts'; + +const REAPPLY_NOTE = + 'Production never re-applies a migration it has already applied, so this database would not match production.'; + +function entry(idx: number, when: number): JournalEntry { + return { idx, tag: `${String(idx).padStart(4, '0')}_tag`, when }; +} + +function migrationSet( + journal: ReadonlyArray, + files: Readonly>, +): MigrationSet { + return { files: new Map(Object.entries(files)), journal }; +} + +const releasedFiles = { + '0000_tag.sql': 'hash-0000', + '0001_tag.sql': 'hash-0001', + 'meta/0000_snapshot.json': 'hash-snap-0000', + 'meta/0001_snapshot.json': 'hash-snap-0001', +} as const; + +const released = migrationSet([entry(0, 100), entry(1, 200)], releasedFiles); + +describe('compareMigrationSets', () => { + it('accepts an identical set', () => { + expect(compareMigrationSets(released, released)).toEqual([]); + }); + + it('accepts an appended entry with a later timestamp and its new files', () => { + const candidate = migrationSet([...released.journal, entry(2, 300)], { + ...releasedFiles, + '0002_tag.sql': 'hash-0002', + 'meta/0002_snapshot.json': 'hash-snap-0002', + }); + expect(compareMigrationSets(released, candidate)).toEqual([]); + }); + + it('rejects a modified released .sql', () => { + const candidate = migrationSet(released.journal, { + ...releasedFiles, + '0001_tag.sql': 'hash-0001-edited', + }); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'released migration 0001_tag.sql was modified', + REAPPLY_NOTE, + ]); + }); + + it('rejects a removed released snapshot', () => { + const { 'meta/0001_snapshot.json': _removed, ...rest } = releasedFiles; + const candidate = migrationSet(released.journal, rest); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'released migration meta/0001_snapshot.json was removed', + REAPPLY_NOTE, + ]); + }); + + it('lists every changed released file once and the explanation once', () => { + const { 'meta/0001_snapshot.json': _removed, ...rest } = releasedFiles; + const candidate = migrationSet(released.journal, { + ...rest, + '0000_tag.sql': 'hash-0000-edited', + }); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'released migration 0000_tag.sql was modified', + 'released migration meta/0001_snapshot.json was removed', + REAPPLY_NOTE, + ]); + }); + + it('rejects a new entry whose timestamp equals the last released one', () => { + const candidate = migrationSet([...released.journal, entry(2, 200)], { + ...releasedFiles, + '0002_tag.sql': 'hash-0002', + }); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'migration 0002_tag (idx 2) has timestamp 200, not after the previous entry 0001_tag (200); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.', + ]); + }); + + it('rejects a new entry whose timestamp is before the last released one', () => { + const candidate = migrationSet([...released.journal, entry(2, 150)], { + ...releasedFiles, + '0002_tag.sql': 'hash-0002', + }); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'migration 0002_tag (idx 2) has timestamp 150, not after the previous entry 0001_tag (200); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.', + ]); + }); + + it('checks each new entry against the entry before it, not only the last released one', () => { + const candidate = migrationSet([...released.journal, entry(2, 400), entry(3, 300)], { + ...releasedFiles, + '0002_tag.sql': 'hash-0002', + '0003_tag.sql': 'hash-0003', + }); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'migration 0003_tag (idx 3) has timestamp 300, not after the previous entry 0002_tag (400); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.', + ]); + }); + + it('rejects a released journal entry whose timestamp changed', () => { + const candidate = migrationSet([entry(0, 100), entry(1, 201)], releasedFiles); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'journal entry 1 differs from the released journal: released 0001_tag (idx 1, when 200), candidate 0001_tag (idx 1, when 201)', + ]); + }); + + it('rejects a released journal entry whose tag or idx changed', () => { + const candidate = migrationSet([entry(0, 100), { idx: 1, tag: '0001_other', when: 200 }], { + ...releasedFiles, + }); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'journal entry 1 differs from the released journal: released 0001_tag (idx 1, when 200), candidate 0001_other (idx 1, when 200)', + ]); + }); + + it('rejects a journal shorter than the released one', () => { + const candidate = migrationSet([entry(0, 100)], releasedFiles); + expect(compareMigrationSets(released, candidate)).toEqual([ + 'journal is shorter than the released journal (1 entries, released 2)', + ]); + }); +}); + +describe('readMigrationSet', () => { + const dir = mkdtempSync(join(tmpdir(), 'void-check-migration-set-')); + + afterAll(() => { + rmSync(dir, { recursive: true, force: true }); + }); + + it('hashes every file except the journal and parses the journal', () => { + mkdirSync(join(dir, 'meta')); + writeFileSync(join(dir, '0000_first.sql'), 'CREATE TABLE a ();'); + writeFileSync(join(dir, 'meta', '0000_snapshot.json'), '{"id":"snap"}'); + writeFileSync( + join(dir, 'meta', '_journal.json'), + JSON.stringify({ + version: '7', + dialect: 'postgresql', + entries: [{ idx: 0, version: '7', when: 1, tag: '0000_first', breakpoints: true }], + }), + ); + + const set = readMigrationSet(dir); + + expect([...set.files.keys()].sort()).toEqual(['0000_first.sql', 'meta/0000_snapshot.json']); + expect(set.files.get('0000_first.sql')).toBe( + createHash('sha256').update('CREATE TABLE a ();').digest('hex'), + ); + expect(set.files.get('meta/0000_snapshot.json')).toBe( + createHash('sha256').update('{"id":"snap"}').digest('hex'), + ); + expect(set.journal).toEqual([{ idx: 0, tag: '0000_first', when: 1 }]); + }); +}); + +describe("the repository's migration set", () => { + const real = readMigrationSet(resolve(import.meta.dirname, '../../drizzle')); + + it('is an append-only extension of itself', () => { + expect(compareMigrationSets(real, real)).toEqual([]); + }); + + it('has strictly increasing journal timestamps', () => { + for (let i = 1; i < real.journal.length; i++) { + expect( + real.journal[i].when, + `${real.journal[i].tag} must be after ${real.journal[i - 1].tag}`, + ).toBeGreaterThan(real.journal[i - 1].when); + } + }); +}); From 14e723dc7c0cb900d11dfd4fecd2054746ef1d2a Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 17:22:48 +0800 Subject: [PATCH 07/10] Compare against the release that is live, not the previous push. The schema guard took `github.event.before` as the release it must keep running. That is only the previous push to `prod`: it may have failed to deploy, or been replaced while pending in the `platform-deploy-production` concurrency group, which keeps one deploy running and one pending and lets a newer pending run replace the older. The live release is the head of the last successful `platform-deploy.yml` run, so the job now reads that from the workflow's run history, which needs `actions: read` on the job and on the deploy's `ci` job that calls it. Until a production deploy has been recorded there is nothing to read, so the job falls back to the previous `prod` commit on a push and to the `prod` branch otherwise, and warns that it did. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01WNXbwieSdsSErZwQ7HWRwG --- .github/workflows/platform-ci.yml | 32 ++++++++++++++++++--------- .github/workflows/platform-deploy.yml | 2 ++ platform/meta/operations.md | 2 +- 3 files changed, 25 insertions(+), 11 deletions(-) diff --git a/.github/workflows/platform-ci.yml b/.github/workflows/platform-ci.yml index 97c0586a9..a45691aff 100644 --- a/.github/workflows/platform-ci.yml +++ b/.github/workflows/platform-ci.yml @@ -86,7 +86,8 @@ jobs: # integration tests against that schema: if the code that is live cannot run on the new schema, # the push must not ship. The fresh database stands in for production's only while the # migrations under test are the released ones plus new entries, so the job also rejects any - # edit, removal, or reordering of a released migration. + # edit, removal, or reordering of a released migration. The release it tests is the head of the + # last successful production deploy, read from `platform-deploy.yml`'s run history. # # It has teeth on PRs, where the code under test is a different commit from the one that is # live. The production deploy sets `require-schema-compat` for every trigger — including a @@ -98,6 +99,8 @@ jobs: timeout-minutes: 20 permissions: contents: read + # The schema guard reads the production deploy's run history to find the live release. + actions: read env: POSTGRES_USER: void_ci POSTGRES_PASSWORD: void_ci_pass @@ -134,24 +137,33 @@ jobs: env: DATABASE_URL: ${{ env.COMPAT_DATABASE_URL }} - # Phase 2 — the release that is live must still run on that schema. On a push that is the - # commit `prod` pointed at before the push, never the commit being deployed: the api worker - # is replaced after its migrations run, so the previous release is what serves traffic for - # the length of the deploy. PRs compare against the deployed branch. + # Phase 2 — the release that is live must still run on that schema. That release is the head + # of the last successful production deploy: not `github.event.before`, which is only the + # previous push and may have failed to deploy or been replaced while pending in the deploy + # concurrency group. Until a production deploy has been recorded, fall back to the previous + # `prod` commit on a push and to the `prod` branch on a PR, and say so. - name: Resolve the compatibility baseline id: baseline env: + GH_TOKEN: ${{ github.token }} EVENT_NAME: ${{ github.event_name }} PREVIOUS_SHA: ${{ github.event.before }} + NO_PREVIOUS_SHA: '0000000000000000000000000000000000000000' run: | - if [ "$EVENT_NAME" = 'push' ]; then - printf '%s' "$PREVIOUS_SHA" | grep -Eq '^[0-9a-f]{40}$' || { - echo '::error::The push event carries no previous commit to compare against.' - exit 1 - } + live=$(curl -sSf \ + -H "Authorization: Bearer $GH_TOKEN" \ + -H 'Accept: application/vnd.github+json' \ + "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/actions/workflows/platform-deploy.yml/runs?status=success&per_page=1" \ + | node -e 'let s = ""; process.stdin.on("data", (d) => (s += d)).on("end", () => process.stdout.write(JSON.parse(s).workflow_runs?.[0]?.head_sha ?? ""))') + if [ -n "$live" ]; then + echo "ref=$live" >> "$GITHUB_OUTPUT" + echo "Baseline: $live (last successful production deploy)" + elif [ "$EVENT_NAME" = 'push' ] && printf '%s' "$PREVIOUS_SHA" | grep -Eq '^[0-9a-f]{40}$' && [ "$PREVIOUS_SHA" != "$NO_PREVIOUS_SHA" ]; then echo "ref=$PREVIOUS_SHA" >> "$GITHUB_OUTPUT" + echo "::warning::No successful production deploy is recorded yet; comparing against the previous prod commit $PREVIOUS_SHA instead of the live release." else echo 'ref=prod' >> "$GITHUB_OUTPUT" + echo '::warning::No successful production deploy is recorded yet; comparing against the prod branch instead of the live release.' fi # The baseline checkout replaces the workspace, and the baseline may predate the checker. - name: Keep the candidate's migration set for the append-only check diff --git a/.github/workflows/platform-deploy.yml b/.github/workflows/platform-deploy.yml index 085e404f5..9cab35338 100644 --- a/.github/workflows/platform-deploy.yml +++ b/.github/workflows/platform-deploy.yml @@ -25,6 +25,8 @@ jobs: require-schema-compat: true permissions: contents: read + # The schema guard reads this workflow's run history to find the live release. + actions: read deploy: if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }} diff --git a/platform/meta/operations.md b/platform/meta/operations.md index 3dee76448..45bc72007 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -513,7 +513,7 @@ Four platform workflows live in the repository-level `.github/workflows/` direct 5. `vp run check:platform` and `vp run check:sdk` (typecheck the platform packages and the SDK packages; the playgrounds are typechecked by `ci.yml`) 6. `vp test run --project platform-unit` and `--project platform-api-integration` 7. Builds the API build container image (PRs only) -8. The production schema-compatibility guard (`schema-compat`; PRs and every production deploy): applies the migrations under test to a fresh Postgres 18, then runs the live release's `platform-api-integration` suite against that schema. Released migrations are append-only: an edit, a removal, a reordering, or a new entry whose journal timestamp is not after the last released one fails the guard, because production never re-applies a migration it has applied and skips an entry that is not newer than its last. +8. The production schema-compatibility guard (`schema-compat`; PRs and every production deploy): applies the migrations under test to a fresh Postgres 18, then runs the live release's `platform-api-integration` suite against that schema. The live release is the head of the last successful `platform-deploy.yml` run; until one is recorded the guard falls back, with a warning, to the previous `prod` commit on a push and to the `prod` branch on a PR. Released migrations are append-only: an edit, a removal, a reordering, or a new entry whose journal timestamp is not after the last released one fails the guard, because production never re-applies a migration it has applied and skips an entry that is not newer than its last. **`platform-deploy.yml`** — push to `prod`, or manual dispatch (production, environment: `Prod`): From 7549e2c853455e44fe465d30407bb7d95a9fa9cf Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 17:32:42 +0800 Subject: [PATCH 08/10] Treat every commit pushed to `prod` as released. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The append-only check compared the candidate's migrations with the last successful release's. That set can lag production's schema: the api deploy migrates before it deploys the worker, so a push whose deploy failed afterwards has still applied its migrations, and a retry could edit or replace them and pass. The check now takes the previous `prod` commit on a push, and the `prod` branch otherwise, as the released set — at or ahead of the live release's, since `prod` only moves forward — checked out sparsely beside the code baseline so the live release still decides which tests run. A released commit that predates the platform carries nothing to extend, so the check says so and skips; the tests keep their own gate. The staging deploy calls the same workflow and granted its `ci` job only `contents: read`, which a called job asking for `actions: read` exceeds. Grant it there too, though staging never runs the guard. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01WNXbwieSdsSErZwQ7HWRwG --- .github/workflows/platform-ci.yml | 42 ++++++++++++++++--- .github/workflows/platform-deploy-staging.yml | 2 + platform/meta/operations.md | 2 +- .../api/test/unit/check-migration-set.test.ts | 42 +++++++++++++++++++ 4 files changed, 81 insertions(+), 7 deletions(-) diff --git a/.github/workflows/platform-ci.yml b/.github/workflows/platform-ci.yml index a45691aff..58c0ee9ba 100644 --- a/.github/workflows/platform-ci.yml +++ b/.github/workflows/platform-ci.yml @@ -84,10 +84,15 @@ jobs: # push to `prod` applies a new schema while the previous release is still serving traffic. This # migrates a real Postgres with the migrations under test, then runs the production ref's # integration tests against that schema: if the code that is live cannot run on the new schema, - # the push must not ship. The fresh database stands in for production's only while the - # migrations under test are the released ones plus new entries, so the job also rejects any - # edit, removal, or reordering of a released migration. The release it tests is the head of the - # last successful production deploy, read from `platform-deploy.yml`'s run history. + # the push must not ship. The release it tests is the head of the last successful production + # deploy, read from `platform-deploy.yml`'s run history. + # + # The fresh database stands in for production's only while the migrations under test are the + # released ones plus new entries, so the job also rejects any edit, removal, or reordering of a + # released migration. "Released" is every commit ever pushed to `prod`, not only the ones whose + # deploy succeeded: the api deploy migrates first, so a deploy that failed afterwards has still + # applied its migrations. That set is the previous `prod` commit, which is at or ahead of the + # live release's because `prod` only moves forward. # # It has teeth on PRs, where the code under test is a different commit from the one that is # live. The production deploy sets `require-schema-compat` for every trigger — including a @@ -142,6 +147,11 @@ jobs: # previous push and may have failed to deploy or been replaced while pending in the deploy # concurrency group. Until a production deploy has been recorded, fall back to the previous # `prod` commit on a push and to the `prod` branch on a PR, and say so. + # + # The released migration set is a second, stricter baseline: the previous `prod` commit on a + # push, and the `prod` branch otherwise. Every push to `prod` starts a deploy that migrates + # before it deploys, so a commit's migrations count as applied whether or not its deploy + # succeeded; a retry may only append to them. - name: Resolve the compatibility baseline id: baseline env: @@ -165,6 +175,13 @@ jobs: echo 'ref=prod' >> "$GITHUB_OUTPUT" echo '::warning::No successful production deploy is recorded yet; comparing against the prod branch instead of the live release.' fi + if [ "$EVENT_NAME" = 'push' ] && printf '%s' "$PREVIOUS_SHA" | grep -Eq '^[0-9a-f]{40}$' && [ "$PREVIOUS_SHA" != "$NO_PREVIOUS_SHA" ]; then + echo "released=$PREVIOUS_SHA" >> "$GITHUB_OUTPUT" + echo "Released migrations: $PREVIOUS_SHA (previous prod commit)" + else + echo 'released=prod' >> "$GITHUB_OUTPUT" + echo 'Released migrations: prod' + fi # The baseline checkout replaces the workspace, and the baseline may predate the checker. - name: Keep the candidate's migration set for the append-only check run: | @@ -174,6 +191,15 @@ jobs: with: ref: ${{ steps.baseline.outputs.ref }} persist-credentials: false + # After the checkout above, which cleans the workspace. `released/` sits outside every + # workspace and test glob, so the builds and tests below do not see it. + - name: Check out the released migration set + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ steps.baseline.outputs.released }} + path: released + sparse-checkout: platform/packages/api/drizzle + persist-credentials: false - name: Does the baseline carry the platform? id: production run: | @@ -190,8 +216,12 @@ jobs: # an entry it has applied, so a candidate that edits, removes, or reorders released # migrations would migrate this fresh database differently from production. Reject it. - name: The candidate must only append to the released migrations - if: steps.production.outputs.usable == 'true' - run: node "$RUNNER_TEMP/check-migration-set.ts" --baseline platform/packages/api/drizzle --candidate "$RUNNER_TEMP/candidate-drizzle" + run: | + if [ ! -d released/platform/packages/api/drizzle ]; then + echo '::notice::The released commit carries no migrations, so there is no released set for the candidate to extend.' + exit 0 + fi + node "$RUNNER_TEMP/check-migration-set.ts" --baseline released/platform/packages/api/drizzle --candidate "$RUNNER_TEMP/candidate-drizzle" - if: steps.production.outputs.usable == 'true' uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0 with: diff --git a/.github/workflows/platform-deploy-staging.yml b/.github/workflows/platform-deploy-staging.yml index 3e35e4004..878f8b049 100644 --- a/.github/workflows/platform-deploy-staging.yml +++ b/.github/workflows/platform-deploy-staging.yml @@ -29,6 +29,8 @@ jobs: uses: ./.github/workflows/platform-ci.yml permissions: contents: read + # The schema guard reads the production deploy's run history; a called job may not ask for more than its caller grants. + actions: read deploy: if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }} diff --git a/platform/meta/operations.md b/platform/meta/operations.md index 45bc72007..cc98cbc13 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -513,7 +513,7 @@ Four platform workflows live in the repository-level `.github/workflows/` direct 5. `vp run check:platform` and `vp run check:sdk` (typecheck the platform packages and the SDK packages; the playgrounds are typechecked by `ci.yml`) 6. `vp test run --project platform-unit` and `--project platform-api-integration` 7. Builds the API build container image (PRs only) -8. The production schema-compatibility guard (`schema-compat`; PRs and every production deploy): applies the migrations under test to a fresh Postgres 18, then runs the live release's `platform-api-integration` suite against that schema. The live release is the head of the last successful `platform-deploy.yml` run; until one is recorded the guard falls back, with a warning, to the previous `prod` commit on a push and to the `prod` branch on a PR. Released migrations are append-only: an edit, a removal, a reordering, or a new entry whose journal timestamp is not after the last released one fails the guard, because production never re-applies a migration it has applied and skips an entry that is not newer than its last. +8. The production schema-compatibility guard (`schema-compat`; PRs and every production deploy): applies the migrations under test to a fresh Postgres 18, then runs the live release's `platform-api-integration` suite against that schema. The live release is the head of the last successful `platform-deploy.yml` run; until one is recorded the guard falls back, with a warning, to the previous `prod` commit on a push and to the `prod` branch on a PR. Released migrations are append-only: an edit, a removal, a reordering, or a new entry whose journal timestamp is not after the last released one fails the guard, because production never re-applies a migration it has applied and skips an entry that is not newer than its last. "Released" here is the previous `prod` commit on a push and the `prod` branch otherwise, not the live release: the api deploy migrates before it deploys, so every commit pushed to `prod` counts as having applied its migrations whether or not its deploy succeeded. **`platform-deploy.yml`** — push to `prod`, or manual dispatch (production, environment: `Prod`): diff --git a/platform/packages/api/test/unit/check-migration-set.test.ts b/platform/packages/api/test/unit/check-migration-set.test.ts index ef642f1dd..9c9816c8c 100644 --- a/platform/packages/api/test/unit/check-migration-set.test.ts +++ b/platform/packages/api/test/unit/check-migration-set.test.ts @@ -133,6 +133,48 @@ describe('compareMigrationSets', () => { 'journal is shorter than the released journal (1 entries, released 2)', ]); }); + + // The api deploy migrates before it deploys the worker, so a push to `prod` whose deploy failed + // afterwards has still applied its migrations. The workflow therefore takes the previous `prod` + // commit, not the last successful release, as the released set; these pin what that buys. + describe('a migration applied by a deploy that then failed', () => { + const lastSuccessfulRelease = migrationSet([entry(0, 100)], { + '0000_tag.sql': 'hash-0000', + 'meta/0000_snapshot.json': 'hash-snap-0000', + }); + const releasedThoughFailed = migrationSet([...lastSuccessfulRelease.journal, entry(1, 300)], { + ...Object.fromEntries(lastSuccessfulRelease.files), + '0001_tag.sql': 'hash-0001', + 'meta/0001_snapshot.json': 'hash-snap-0001', + }); + + it('rejects a retry that edits it', () => { + const retry = migrationSet(releasedThoughFailed.journal, { + ...Object.fromEntries(releasedThoughFailed.files), + '0001_tag.sql': 'hash-0001-edited', + }); + expect(compareMigrationSets(lastSuccessfulRelease, retry)).toEqual([]); + expect(compareMigrationSets(releasedThoughFailed, retry)).toEqual([ + 'released migration 0001_tag.sql was modified', + REAPPLY_NOTE, + ]); + }); + + it('rejects a retry that replaces it with an earlier entry', () => { + const retry = migrationSet([...lastSuccessfulRelease.journal, entry(1, 200)], { + ...Object.fromEntries(lastSuccessfulRelease.files), + '0001_tag.sql': 'hash-0001-redone', + 'meta/0001_snapshot.json': 'hash-snap-0001-redone', + }); + expect(compareMigrationSets(lastSuccessfulRelease, retry)).toEqual([]); + expect(compareMigrationSets(releasedThoughFailed, retry)).toEqual([ + 'released migration 0001_tag.sql was modified', + 'released migration meta/0001_snapshot.json was modified', + REAPPLY_NOTE, + 'journal entry 1 differs from the released journal: released 0001_tag (idx 1, when 300), candidate 0001_tag (idx 1, when 200)', + ]); + }); + }); }); describe('readMigrationSet', () => { From 8839699fd04bd41459843b922623ec373f8ec815 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 17:47:10 +0800 Subject: [PATCH 09/10] Keep the production guard as simple as the old repository's. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The extra baselines and the migration-set checker added more moving parts than the risk they cover. The old model — migrate a fresh Postgres with the candidate's migrations, then run the `prod` branch's integration tests on it — ran seven months without incident, so the guard goes back to that. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01WNXbwieSdsSErZwQ7HWRwG --- .github/workflows/platform-ci.yml | 85 +------ .github/workflows/platform-deploy-staging.yml | 2 - .github/workflows/platform-deploy.yml | 2 - platform/meta/operations.md | 2 +- .../api/scripts/check-migration-set.ts | 188 --------------- .../api/test/unit/check-migration-set.test.ts | 228 ------------------ 6 files changed, 9 insertions(+), 498 deletions(-) delete mode 100644 platform/packages/api/scripts/check-migration-set.ts delete mode 100644 platform/packages/api/test/unit/check-migration-set.test.ts diff --git a/.github/workflows/platform-ci.yml b/.github/workflows/platform-ci.yml index 58c0ee9ba..7d40dd58b 100644 --- a/.github/workflows/platform-ci.yml +++ b/.github/workflows/platform-ci.yml @@ -82,17 +82,11 @@ jobs: # The production guard. `platform-deploy.yml` migrates before it deploys the api worker, so a # push to `prod` applies a new schema while the previous release is still serving traffic. This - # migrates a real Postgres with the migrations under test, then runs the production ref's + # migrates a real Postgres with the migrations under test, then runs the `prod` branch's # integration tests against that schema: if the code that is live cannot run on the new schema, - # the push must not ship. The release it tests is the head of the last successful production - # deploy, read from `platform-deploy.yml`'s run history. - # - # The fresh database stands in for production's only while the migrations under test are the - # released ones plus new entries, so the job also rejects any edit, removal, or reordering of a - # released migration. "Released" is every commit ever pushed to `prod`, not only the ones whose - # deploy succeeded: the api deploy migrates first, so a deploy that failed afterwards has still - # applied its migrations. That set is the previous `prod` commit, which is at or ahead of the - # live release's because `prod` only moves forward. + # the push must not ship. Accepted limits: the baseline is the `prod` branch head rather than the + # deployed revision, and released migrations are assumed append-only (drizzle never re-applies an + # applied entry and skips entries not newer than the last applied). # # It has teeth on PRs, where the code under test is a different commit from the one that is # live. The production deploy sets `require-schema-compat` for every trigger — including a @@ -104,8 +98,6 @@ jobs: timeout-minutes: 20 permissions: contents: read - # The schema guard reads the production deploy's run history to find the live release. - actions: read env: POSTGRES_USER: void_ci POSTGRES_PASSWORD: void_ci_pass @@ -142,63 +134,12 @@ jobs: env: DATABASE_URL: ${{ env.COMPAT_DATABASE_URL }} - # Phase 2 — the release that is live must still run on that schema. That release is the head - # of the last successful production deploy: not `github.event.before`, which is only the - # previous push and may have failed to deploy or been replaced while pending in the deploy - # concurrency group. Until a production deploy has been recorded, fall back to the previous - # `prod` commit on a push and to the `prod` branch on a PR, and say so. - # - # The released migration set is a second, stricter baseline: the previous `prod` commit on a - # push, and the `prod` branch otherwise. Every push to `prod` starts a deploy that migrates - # before it deploys, so a commit's migrations count as applied whether or not its deploy - # succeeded; a retry may only append to them. - - name: Resolve the compatibility baseline - id: baseline - env: - GH_TOKEN: ${{ github.token }} - EVENT_NAME: ${{ github.event_name }} - PREVIOUS_SHA: ${{ github.event.before }} - NO_PREVIOUS_SHA: '0000000000000000000000000000000000000000' - run: | - live=$(curl -sSf \ - -H "Authorization: Bearer $GH_TOKEN" \ - -H 'Accept: application/vnd.github+json' \ - "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/actions/workflows/platform-deploy.yml/runs?status=success&per_page=1" \ - | node -e 'let s = ""; process.stdin.on("data", (d) => (s += d)).on("end", () => process.stdout.write(JSON.parse(s).workflow_runs?.[0]?.head_sha ?? ""))') - if [ -n "$live" ]; then - echo "ref=$live" >> "$GITHUB_OUTPUT" - echo "Baseline: $live (last successful production deploy)" - elif [ "$EVENT_NAME" = 'push' ] && printf '%s' "$PREVIOUS_SHA" | grep -Eq '^[0-9a-f]{40}$' && [ "$PREVIOUS_SHA" != "$NO_PREVIOUS_SHA" ]; then - echo "ref=$PREVIOUS_SHA" >> "$GITHUB_OUTPUT" - echo "::warning::No successful production deploy is recorded yet; comparing against the previous prod commit $PREVIOUS_SHA instead of the live release." - else - echo 'ref=prod' >> "$GITHUB_OUTPUT" - echo '::warning::No successful production deploy is recorded yet; comparing against the prod branch instead of the live release.' - fi - if [ "$EVENT_NAME" = 'push' ] && printf '%s' "$PREVIOUS_SHA" | grep -Eq '^[0-9a-f]{40}$' && [ "$PREVIOUS_SHA" != "$NO_PREVIOUS_SHA" ]; then - echo "released=$PREVIOUS_SHA" >> "$GITHUB_OUTPUT" - echo "Released migrations: $PREVIOUS_SHA (previous prod commit)" - else - echo 'released=prod' >> "$GITHUB_OUTPUT" - echo 'Released migrations: prod' - fi - # The baseline checkout replaces the workspace, and the baseline may predate the checker. - - name: Keep the candidate's migration set for the append-only check - run: | - cp -R platform/packages/api/drizzle "$RUNNER_TEMP/candidate-drizzle" - cp platform/packages/api/scripts/check-migration-set.ts "$RUNNER_TEMP/check-migration-set.ts" + # Phase 2 — the release that is live must still run on that schema. `prod` is that release. + # PRs are checked against it; a push to `prod` checks itself, as in the old repository; a + # manual dispatch from another ref is checked against `prod`. - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: ${{ steps.baseline.outputs.ref }} - persist-credentials: false - # After the checkout above, which cleans the workspace. `released/` sits outside every - # workspace and test glob, so the builds and tests below do not see it. - - name: Check out the released migration set - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: ${{ steps.baseline.outputs.released }} - path: released - sparse-checkout: platform/packages/api/drizzle + ref: prod persist-credentials: false - name: Does the baseline carry the platform? id: production @@ -212,16 +153,6 @@ jobs: echo 'usable=false' >> "$GITHUB_OUTPUT" echo '::warning::The compatibility baseline predates the platform, so the production code was not exercised against the migrated schema. This stops once prod carries the platform.' fi - # Production applies only journal entries newer than its last applied one and never re-runs - # an entry it has applied, so a candidate that edits, removes, or reorders released - # migrations would migrate this fresh database differently from production. Reject it. - - name: The candidate must only append to the released migrations - run: | - if [ ! -d released/platform/packages/api/drizzle ]; then - echo '::notice::The released commit carries no migrations, so there is no released set for the candidate to extend.' - exit 0 - fi - node "$RUNNER_TEMP/check-migration-set.ts" --baseline released/platform/packages/api/drizzle --candidate "$RUNNER_TEMP/candidate-drizzle" - if: steps.production.outputs.usable == 'true' uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0 with: diff --git a/.github/workflows/platform-deploy-staging.yml b/.github/workflows/platform-deploy-staging.yml index 878f8b049..3e35e4004 100644 --- a/.github/workflows/platform-deploy-staging.yml +++ b/.github/workflows/platform-deploy-staging.yml @@ -29,8 +29,6 @@ jobs: uses: ./.github/workflows/platform-ci.yml permissions: contents: read - # The schema guard reads the production deploy's run history; a called job may not ask for more than its caller grants. - actions: read deploy: if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }} diff --git a/.github/workflows/platform-deploy.yml b/.github/workflows/platform-deploy.yml index 9cab35338..085e404f5 100644 --- a/.github/workflows/platform-deploy.yml +++ b/.github/workflows/platform-deploy.yml @@ -25,8 +25,6 @@ jobs: require-schema-compat: true permissions: contents: read - # The schema guard reads this workflow's run history to find the live release. - actions: read deploy: if: ${{ vars.VOID_PLATFORM_DEPLOY_ENABLED == 'true' }} diff --git a/platform/meta/operations.md b/platform/meta/operations.md index cc98cbc13..76a08907b 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -513,7 +513,7 @@ Four platform workflows live in the repository-level `.github/workflows/` direct 5. `vp run check:platform` and `vp run check:sdk` (typecheck the platform packages and the SDK packages; the playgrounds are typechecked by `ci.yml`) 6. `vp test run --project platform-unit` and `--project platform-api-integration` 7. Builds the API build container image (PRs only) -8. The production schema-compatibility guard (`schema-compat`; PRs and every production deploy): applies the migrations under test to a fresh Postgres 18, then runs the live release's `platform-api-integration` suite against that schema. The live release is the head of the last successful `platform-deploy.yml` run; until one is recorded the guard falls back, with a warning, to the previous `prod` commit on a push and to the `prod` branch on a PR. Released migrations are append-only: an edit, a removal, a reordering, or a new entry whose journal timestamp is not after the last released one fails the guard, because production never re-applies a migration it has applied and skips an entry that is not newer than its last. "Released" here is the previous `prod` commit on a push and the `prod` branch otherwise, not the live release: the api deploy migrates before it deploys, so every commit pushed to `prod` counts as having applied its migrations whether or not its deploy succeeded. +8. The production schema-compatibility guard (`schema-compat`; PRs and production deploys): migrates a fresh Postgres 18 with the candidate's migrations and runs the `prod` branch's `platform-api-integration` suite on it **`platform-deploy.yml`** — push to `prod`, or manual dispatch (production, environment: `Prod`): diff --git a/platform/packages/api/scripts/check-migration-set.ts b/platform/packages/api/scripts/check-migration-set.ts deleted file mode 100644 index 9d4c0990d..000000000 --- a/platform/packages/api/scripts/check-migration-set.ts +++ /dev/null @@ -1,188 +0,0 @@ -/** - * Checks that a candidate drizzle migration set is an append-only extension of the released - * set: every released file is unchanged, the released journal is a prefix of the candidate - * journal, and every new entry is newer than the one before it. - * - * `drizzle-kit migrate` applies only journal entries whose `when` is later than the last entry - * it applied and never re-runs an entry it has applied, so a set that fails this check would - * migrate a fresh database differently from production. The `schema-compat` CI job runs this - * from `$RUNNER_TEMP`, so it must not import anything from the repository. - * - * Usage: - * node scripts/check-migration-set.ts --baseline --candidate - */ - -import { createHash } from 'node:crypto'; -import { existsSync, readdirSync, readFileSync } from 'node:fs'; -import { join } from 'node:path'; -import { parseArgs } from 'node:util'; - -export type JournalEntry = Readonly<{ idx: number; tag: string; when: number }>; - -export type MigrationSet = Readonly<{ - /** relative path → sha256 hex, for every file under the migrations dir except meta/_journal.json */ - files: ReadonlyMap; - journal: ReadonlyArray; -}>; - -const JOURNAL_PATH = 'meta/_journal.json'; - -// ── Reading ───────────────────────────────────────────────────────── - -function hashFilesUnder(dir: string, prefix: string, into: Map): void { - for (const entry of readdirSync(join(dir, prefix), { withFileTypes: true })) { - const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name; - if (entry.isDirectory()) { - hashFilesUnder(dir, relativePath, into); - } else if (relativePath !== JOURNAL_PATH) { - into.set( - relativePath, - createHash('sha256') - .update(readFileSync(join(dir, relativePath))) - .digest('hex'), - ); - } - } -} - -function readJournal(dir: string): ReadonlyArray { - const path = join(dir, JOURNAL_PATH); - const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8')); - const entries = - typeof parsed === 'object' && parsed !== null && 'entries' in parsed - ? parsed.entries - : undefined; - if (!Array.isArray(entries)) { - throw new Error(`${path} has no "entries" array`); - } - return entries.map((raw: unknown, i) => { - if ( - typeof raw !== 'object' || - raw === null || - !('idx' in raw && typeof raw.idx === 'number') || - !('tag' in raw && typeof raw.tag === 'string') || - !('when' in raw && typeof raw.when === 'number') - ) { - throw new Error(`${path} entry ${i} lacks a numeric idx, a string tag, or a numeric when`); - } - return { idx: raw.idx, tag: raw.tag, when: raw.when }; - }); -} - -export function readMigrationSet(dir: string): MigrationSet { - const files = new Map(); - hashFilesUnder(dir, '', files); - return { files, journal: readJournal(dir) }; -} - -// ── Comparison ────────────────────────────────────────────────────── - -function describeEntry(entry: JournalEntry): string { - return `${entry.tag} (idx ${entry.idx}, when ${entry.when})`; -} - -/** Returns the reasons the candidate is not an append-only extension of the baseline; empty when it is. */ -export function compareMigrationSets( - baseline: MigrationSet, - candidate: MigrationSet, -): Array { - const problems: Array = []; - - let releasedFilesChanged = false; - for (const [path, hash] of baseline.files) { - const candidateHash = candidate.files.get(path); - if (candidateHash === undefined) { - problems.push(`released migration ${path} was removed`); - releasedFilesChanged = true; - } else if (candidateHash !== hash) { - problems.push(`released migration ${path} was modified`); - releasedFilesChanged = true; - } - } - if (releasedFilesChanged) { - problems.push( - 'Production never re-applies a migration it has already applied, so this database would not match production.', - ); - } - - if (candidate.journal.length < baseline.journal.length) { - problems.push( - `journal is shorter than the released journal (${candidate.journal.length} entries, released ${baseline.journal.length})`, - ); - return problems; - } - for (let i = 0; i < baseline.journal.length; i++) { - const released = baseline.journal[i]; - const proposed = candidate.journal[i]; - if ( - released.idx !== proposed.idx || - released.tag !== proposed.tag || - released.when !== proposed.when - ) { - problems.push( - `journal entry ${i} differs from the released journal: released ${describeEntry(released)}, candidate ${describeEntry(proposed)}`, - ); - return problems; - } - } - - for (let i = baseline.journal.length; i < candidate.journal.length; i++) { - const previous = candidate.journal[i - 1]; - const entry = candidate.journal[i]; - if (previous !== undefined && entry.when <= previous.when) { - problems.push( - `migration ${entry.tag} (idx ${entry.idx}) has timestamp ${entry.when}, not after the previous entry ${previous.tag} (${previous.when}); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.`, - ); - } - } - - return problems; -} - -// ── CLI ───────────────────────────────────────────────────────────── - -function main(): void { - const { values } = parseArgs({ - options: { - baseline: { type: 'string' }, - candidate: { type: 'string' }, - }, - }); - - if (!values.baseline || !values.candidate) { - console.error( - 'Usage: node check-migration-set.ts --baseline --candidate ', - ); - process.exit(1); - } - - if (!existsSync(join(values.baseline, JOURNAL_PATH))) { - console.log( - `The baseline ${values.baseline} has no ${JOURNAL_PATH}, so there is no released migration set to compare against.`, - ); - return; - } - if (!existsSync(join(values.candidate, JOURNAL_PATH))) { - console.error(`::error::The candidate ${values.candidate} has no ${JOURNAL_PATH}.`); - process.exit(1); - } - - const baseline = readMigrationSet(values.baseline); - const candidate = readMigrationSet(values.candidate); - const problems = compareMigrationSets(baseline, candidate); - - if (problems.length > 0) { - for (const problem of problems) { - console.error(`::error::${problem}`); - } - process.exit(1); - } - - console.log( - `Migration set is an append-only extension of the released set (${baseline.journal.length} released, ${candidate.journal.length - baseline.journal.length} new).`, - ); -} - -if (import.meta.main) { - main(); -} diff --git a/platform/packages/api/test/unit/check-migration-set.test.ts b/platform/packages/api/test/unit/check-migration-set.test.ts deleted file mode 100644 index 9c9816c8c..000000000 --- a/platform/packages/api/test/unit/check-migration-set.test.ts +++ /dev/null @@ -1,228 +0,0 @@ -import { createHash } from 'node:crypto'; -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import { join, resolve } from 'node:path'; -import { afterAll, describe, expect, it } from 'vite-plus/test'; -import { - compareMigrationSets, - readMigrationSet, - type JournalEntry, - type MigrationSet, -} from '../../scripts/check-migration-set.ts'; - -const REAPPLY_NOTE = - 'Production never re-applies a migration it has already applied, so this database would not match production.'; - -function entry(idx: number, when: number): JournalEntry { - return { idx, tag: `${String(idx).padStart(4, '0')}_tag`, when }; -} - -function migrationSet( - journal: ReadonlyArray, - files: Readonly>, -): MigrationSet { - return { files: new Map(Object.entries(files)), journal }; -} - -const releasedFiles = { - '0000_tag.sql': 'hash-0000', - '0001_tag.sql': 'hash-0001', - 'meta/0000_snapshot.json': 'hash-snap-0000', - 'meta/0001_snapshot.json': 'hash-snap-0001', -} as const; - -const released = migrationSet([entry(0, 100), entry(1, 200)], releasedFiles); - -describe('compareMigrationSets', () => { - it('accepts an identical set', () => { - expect(compareMigrationSets(released, released)).toEqual([]); - }); - - it('accepts an appended entry with a later timestamp and its new files', () => { - const candidate = migrationSet([...released.journal, entry(2, 300)], { - ...releasedFiles, - '0002_tag.sql': 'hash-0002', - 'meta/0002_snapshot.json': 'hash-snap-0002', - }); - expect(compareMigrationSets(released, candidate)).toEqual([]); - }); - - it('rejects a modified released .sql', () => { - const candidate = migrationSet(released.journal, { - ...releasedFiles, - '0001_tag.sql': 'hash-0001-edited', - }); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'released migration 0001_tag.sql was modified', - REAPPLY_NOTE, - ]); - }); - - it('rejects a removed released snapshot', () => { - const { 'meta/0001_snapshot.json': _removed, ...rest } = releasedFiles; - const candidate = migrationSet(released.journal, rest); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'released migration meta/0001_snapshot.json was removed', - REAPPLY_NOTE, - ]); - }); - - it('lists every changed released file once and the explanation once', () => { - const { 'meta/0001_snapshot.json': _removed, ...rest } = releasedFiles; - const candidate = migrationSet(released.journal, { - ...rest, - '0000_tag.sql': 'hash-0000-edited', - }); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'released migration 0000_tag.sql was modified', - 'released migration meta/0001_snapshot.json was removed', - REAPPLY_NOTE, - ]); - }); - - it('rejects a new entry whose timestamp equals the last released one', () => { - const candidate = migrationSet([...released.journal, entry(2, 200)], { - ...releasedFiles, - '0002_tag.sql': 'hash-0002', - }); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'migration 0002_tag (idx 2) has timestamp 200, not after the previous entry 0001_tag (200); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.', - ]); - }); - - it('rejects a new entry whose timestamp is before the last released one', () => { - const candidate = migrationSet([...released.journal, entry(2, 150)], { - ...releasedFiles, - '0002_tag.sql': 'hash-0002', - }); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'migration 0002_tag (idx 2) has timestamp 150, not after the previous entry 0001_tag (200); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.', - ]); - }); - - it('checks each new entry against the entry before it, not only the last released one', () => { - const candidate = migrationSet([...released.journal, entry(2, 400), entry(3, 300)], { - ...releasedFiles, - '0002_tag.sql': 'hash-0002', - '0003_tag.sql': 'hash-0003', - }); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'migration 0003_tag (idx 3) has timestamp 300, not after the previous entry 0002_tag (400); drizzle-kit migrate applies only entries newer than the last applied one and would skip it in production.', - ]); - }); - - it('rejects a released journal entry whose timestamp changed', () => { - const candidate = migrationSet([entry(0, 100), entry(1, 201)], releasedFiles); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'journal entry 1 differs from the released journal: released 0001_tag (idx 1, when 200), candidate 0001_tag (idx 1, when 201)', - ]); - }); - - it('rejects a released journal entry whose tag or idx changed', () => { - const candidate = migrationSet([entry(0, 100), { idx: 1, tag: '0001_other', when: 200 }], { - ...releasedFiles, - }); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'journal entry 1 differs from the released journal: released 0001_tag (idx 1, when 200), candidate 0001_other (idx 1, when 200)', - ]); - }); - - it('rejects a journal shorter than the released one', () => { - const candidate = migrationSet([entry(0, 100)], releasedFiles); - expect(compareMigrationSets(released, candidate)).toEqual([ - 'journal is shorter than the released journal (1 entries, released 2)', - ]); - }); - - // The api deploy migrates before it deploys the worker, so a push to `prod` whose deploy failed - // afterwards has still applied its migrations. The workflow therefore takes the previous `prod` - // commit, not the last successful release, as the released set; these pin what that buys. - describe('a migration applied by a deploy that then failed', () => { - const lastSuccessfulRelease = migrationSet([entry(0, 100)], { - '0000_tag.sql': 'hash-0000', - 'meta/0000_snapshot.json': 'hash-snap-0000', - }); - const releasedThoughFailed = migrationSet([...lastSuccessfulRelease.journal, entry(1, 300)], { - ...Object.fromEntries(lastSuccessfulRelease.files), - '0001_tag.sql': 'hash-0001', - 'meta/0001_snapshot.json': 'hash-snap-0001', - }); - - it('rejects a retry that edits it', () => { - const retry = migrationSet(releasedThoughFailed.journal, { - ...Object.fromEntries(releasedThoughFailed.files), - '0001_tag.sql': 'hash-0001-edited', - }); - expect(compareMigrationSets(lastSuccessfulRelease, retry)).toEqual([]); - expect(compareMigrationSets(releasedThoughFailed, retry)).toEqual([ - 'released migration 0001_tag.sql was modified', - REAPPLY_NOTE, - ]); - }); - - it('rejects a retry that replaces it with an earlier entry', () => { - const retry = migrationSet([...lastSuccessfulRelease.journal, entry(1, 200)], { - ...Object.fromEntries(lastSuccessfulRelease.files), - '0001_tag.sql': 'hash-0001-redone', - 'meta/0001_snapshot.json': 'hash-snap-0001-redone', - }); - expect(compareMigrationSets(lastSuccessfulRelease, retry)).toEqual([]); - expect(compareMigrationSets(releasedThoughFailed, retry)).toEqual([ - 'released migration 0001_tag.sql was modified', - 'released migration meta/0001_snapshot.json was modified', - REAPPLY_NOTE, - 'journal entry 1 differs from the released journal: released 0001_tag (idx 1, when 300), candidate 0001_tag (idx 1, when 200)', - ]); - }); - }); -}); - -describe('readMigrationSet', () => { - const dir = mkdtempSync(join(tmpdir(), 'void-check-migration-set-')); - - afterAll(() => { - rmSync(dir, { recursive: true, force: true }); - }); - - it('hashes every file except the journal and parses the journal', () => { - mkdirSync(join(dir, 'meta')); - writeFileSync(join(dir, '0000_first.sql'), 'CREATE TABLE a ();'); - writeFileSync(join(dir, 'meta', '0000_snapshot.json'), '{"id":"snap"}'); - writeFileSync( - join(dir, 'meta', '_journal.json'), - JSON.stringify({ - version: '7', - dialect: 'postgresql', - entries: [{ idx: 0, version: '7', when: 1, tag: '0000_first', breakpoints: true }], - }), - ); - - const set = readMigrationSet(dir); - - expect([...set.files.keys()].sort()).toEqual(['0000_first.sql', 'meta/0000_snapshot.json']); - expect(set.files.get('0000_first.sql')).toBe( - createHash('sha256').update('CREATE TABLE a ();').digest('hex'), - ); - expect(set.files.get('meta/0000_snapshot.json')).toBe( - createHash('sha256').update('{"id":"snap"}').digest('hex'), - ); - expect(set.journal).toEqual([{ idx: 0, tag: '0000_first', when: 1 }]); - }); -}); - -describe("the repository's migration set", () => { - const real = readMigrationSet(resolve(import.meta.dirname, '../../drizzle')); - - it('is an append-only extension of itself', () => { - expect(compareMigrationSets(real, real)).toEqual([]); - }); - - it('has strictly increasing journal timestamps', () => { - for (let i = 1; i < real.journal.length; i++) { - expect( - real.journal[i].when, - `${real.journal[i].tag} must be after ${real.journal[i - 1].tag}`, - ).toBeGreaterThan(real.journal[i - 1].when); - } - }); -}); From 22e988b1a49e4bbcf0f3cf5fc88c8f7f0f93c75f Mon Sep 17 00:00:00 2001 From: LongYinan Date: Mon, 14 Sep 2026 18:05:28 +0800 Subject: [PATCH 10/10] Name the rollback sequence test for what it verifies. The second rollback is held until the first has fully finished, so the test checks two rollbacks in sequence rather than row-lock contention, and its title and comments now say so. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01WNXbwieSdsSErZwQ7HWRwG --- .../test/integration/api-migrations.test.ts | 36 +++++++++++-------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/platform/packages/api/test/integration/api-migrations.test.ts b/platform/packages/api/test/integration/api-migrations.test.ts index d4484d843..d4038bcc1 100644 --- a/platform/packages/api/test/integration/api-migrations.test.ts +++ b/platform/packages/api/test/integration/api-migrations.test.ts @@ -4476,18 +4476,19 @@ describe('POST /projects/:id/migrations/rename', () => { expect(rollbackBody.migrationDiff).toEqual(['m3.sql']); }); - it('rollback-vs-rollback serializes on the row lock and keeps pg and ROUTING in sync', async () => { - // Concurrent rollbacks must fully serialize. The row lock covers the - // whole cutover (pg flip + ROUTING.put + cron + queue + ISR), so when - // both finish the final state is internally consistent: whatever pg - // says is active, ROUTING points at the matching worker, and the - // diffs returned by both rollbacks are computed against the correct - // pre-flip snapshots. + it('two rollbacks in sequence keep pg and ROUTING in sync, the second after the first has finished', async () => { + // Two rollbacks run one after the other must leave a consistent state. + // The row lock covers the whole cutover (pg flip + ROUTING.put + cron + + // queue + ISR), so when both finish the final state is internally + // consistent: whatever pg says is active, ROUTING points at the + // matching worker, and the diffs returned by both rollbacks are + // computed against the correct pre-flip snapshots. // - // This test pins that invariant by holding rollback A mid-cutover + // This test pins that invariant by holding rollback A mid-rollback // (inside its locked tx, AFTER the pg flip but during its // `ROUTING.put(slug, …)` external write) and kicking rollback B while - // A is paused. B must block on the row lock until A commits. + // A is paused. B starts only after A has fully finished, post-commit + // lease cleanup included. const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'r13f1-rb-rb'); await insertD1Resource(env.db, project.id); @@ -4552,9 +4553,8 @@ describe('POST /projects/:id/migrations/rename', () => { // // Both rollbacks in this scenario carry non-empty diffs (A→B drops m3; // B→C drops m2) so the destructive guard would reject them without an - // opt-in. The invariant here (lock serialization between concurrent - // rollbacks) is orthogonal, so echo each rollback's exact diff via - // `allowDestructive`. + // opt-in. The invariant here (a second rollback after the first) is + // orthogonal, so echo each rollback's exact diff via `allowDestructive`. const rollbackAPromise = app.fetch( authedReq(`/projects/${project.id}/rollback`, user.jwt, { method: 'POST', @@ -4573,7 +4573,13 @@ describe('POST /projects/:id/migrations/rename', () => { // so B's in-lock read runs after A's cleanup, while a pooled Postgres grants // the queued row lock at A's commit, so B resumes before that cleanup, reads // A's rollback lease and answers 409 `deploy in progress`. That fence is - // real, but it is driver order rather than the serialization under test. + // real, but it is driver order rather than the sequence under test. + // + // This test therefore does not exercise row-lock contention between + // rollbacks: on Postgres a rollback that wins the lock at the other's + // commit still sees its rollback lease and answers 409, which is intended. + // The row lock itself is covered by the `/apply` contention tests in this + // file. const realDb = env.db; const realTransaction = realDb.transaction.bind(realDb); let releaseB: () => void = () => {}; @@ -4637,8 +4643,8 @@ describe('POST /projects/:id/migrations/rename', () => { // Final consistency: pg says active=C AND ROUTING.workerName matches C. // The pg flip happens FIRST inside the lock and external writes follow, - // so the serialized order guarantees pg and ROUTING converge on the - // same terminal state. + // so running B after A guarantees pg and ROUTING converge on the same + // terminal state. const finalPg = await env.db.select().from(projects).where(eq(projects.id, project.id)); expect(finalPg[0]!.active_deployment_id).toBe(depC.id);