@astralarium/repo-deploy-release 0.0.0-stage → 0.2.0

package/dist/testkit/release.js

@@ -0,0 +1,61 @@
+/** Test suite of an app's release declaration against the wrangler
+ *  configs deploying it, and the released targets it reads from them. */
+import { describe, it } from "vitest";
+import { envNames } from "../src/app.js";
+import { assertReleaseConfig, isBootstrapping } from "../src/check.js";
+import { readEnvBlock, resolveTarget, } from "../src/target.js";
+import { checkDatabase, checkQueueRetries, checkScripts, checkSite, checkSlotBindings, } from "./release-checks.js";
+/** Packages of `target`: the web and slotted workers, or an in-place
+ *  env's workers. */
+const packagesOf = (target) => target.kind === "blue-green"
+    ? [target.packages.web, target.packages.worker]
+    : target.workers.map((w) => w.package);
+/** Every target of `app` its configs declare, with their env blocks;
+ *  an env whose target is undeclared is left out. */
+export function releasedTargets(app) {
+    return envNames(app).flatMap((env) => {
+        const { target } = resolveTarget(app, env);
+        if (!target)
+            return [];
+        const packages = packagesOf(target);
+        return [
+            {
+                env,
+                target,
+                bootstrapping: isBootstrapping(app, env),
+                blocks: Object.fromEntries(packages.map((pkg) => [pkg, readEnvBlock(app, pkg, env)])),
+                packages,
+            },
+        ];
+    });
+}
+/** Tests of `app`'s declaration against the repo's wrangler configs and
+ *  secrets templates, every declared target's. */
+export function testRelease(app) {
+    const targets = releasedTargets(app);
+    const { queueMaxRetries } = app;
+    it("declares the release its wrangler configs and secrets templates commit: bootstrapping exactly the envs with a config gap", () => {
+        assertReleaseConfig(app);
+    });
+    it("names each script in one target", () => {
+        checkScripts(targets);
+    });
+    describe.each(targets)("the $env target", (released) => {
+        it("serves the site every worker names, routed through the web worker", () => {
+            checkSite(released);
+        });
+        it("shares one Hyperdrive config between its workers, a real one of its own once provisioned, or none without a database", () => {
+            checkDatabase(released, targets.filter((t) => t.env !== released.env));
+        });
+        it(queueMaxRetries === undefined
+            ? "declares no queue consumers, the app lacking queue retries"
+            : "gives each queue consumer the app's queue retries", () => {
+            checkQueueRetries(released, queueMaxRetries);
+        });
+    });
+    describe.each(targets.filter((t) => t.target.kind === "blue-green"))("the $env blue/green target", (released) => {
+        it("binds both slot scripts in the web worker", () => {
+            checkSlotBindings(released);
+        });
+    });
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@astralarium/repo-deploy-release",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "license": "MIT",
+  "homepage": "https://github.com/astralarium/repo/tree/main/packages/repo-deploy-release#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astralarium/repo.git",
+    "directory": "packages/repo-deploy-release"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "sql"
+  ],
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./schema": "./dist/src/schema.js",
+    "./state": "./dist/src/state.js",
+    "./testkit": "./dist/testkit/index.js",
+    "./testkit/release": "./dist/testkit/release.js",
+    "./testkit/release-bundles": "./dist/testkit/release-bundles.js"
+  },
+  "bin": {
+    "deploy-release": "./dist/bin/deploy-release.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@stricli/core": "^1.3.0",
+    "json5": "^2.2.3",
+    "postgres": "^3.4.9",
+    "zod": "^4.6.7",
+    "@astralarium/repo-deploy-info": "^0.1.1",
+    "@astralarium/repo-postgres": "^0.2.0",
+    "@astralarium/repo-telemetry": "^0.2.0",
+    "@astralarium/repo-package-files": "^0.1.0",
+    "@astralarium/repo-deploy-workflows": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "eslint": "^10.2.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3",
+    "wrangler": "^4.132.0",
+    "@astralarium/repo-config-typescript": "^0.1.0",
+    "@astralarium/repo-config-vitest": "^0.2.0",
+    "@astralarium/repo-config-eslint": "^0.3.0"
+  },
+  "peerDependencies": {
+    "vitest": "^5.0.3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24.2"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit",
+    "lint": "eslint",
+    "test": "vitest"
+  }
 }

package/sql/before-reset.sql

@@ -0,0 +1,22 @@
+-- Deploy lease guard, ahead of reset.sql's drop: raises while a deploy
+-- command holds the lease; proceeds while the deploy schema is absent. The
+-- table lock holds through the drop: a lease taken meanwhile waits, then
+-- fails.
+DO $$
+DECLARE
+  holder text;
+  operation text;
+  expires_at timestamptz;
+BEGIN
+  IF to_regclass('deploy.state') IS NULL THEN
+    RETURN;
+  END IF;
+  LOCK TABLE deploy.state IN ACCESS EXCLUSIVE MODE;
+  SELECT d.lease_holder, d.lease_operation, d.lease_expires_at
+  INTO holder, operation, expires_at
+  FROM deploy.state d;
+  IF expires_at > now() THEN
+    RAISE EXCEPTION 'A deploy command holds the lease: % (%). Wait for it, or run deploy-release unlock for the env.',
+      holder, operation;
+  END IF;
+END $$;

package/sql/schema.sql

@@ -0,0 +1,164 @@
+-- Deploy state in the `deploy` schema: the live build, the scheduled
+-- update and the deploy lease. Loads under `@astralarium/repo-postgres`'s roles:
+-- app_admin owns the schema, app_service is the workers' login.
+SET ROLE app_admin;
+
+CREATE SCHEMA deploy AUTHORIZATION app_admin;
+
+GRANT USAGE ON SCHEMA deploy TO app_service;
+
+-- A `deploy-release` command that changes the deployment.
+CREATE TYPE deploy.operation AS ENUM
+  ('init', 'stage', 'deploy', 'cutover', 'rollback', 'settle', 'cancel',
+   'secrets');
+
+-- Deployment state, one row: live build, scheduled update, and the lease
+-- of the command changing the deployment. `version` rises with each build
+-- or update write, in commit order (writers hold the row lock).
+
+CREATE TABLE deploy.state
+(
+  id               boolean PRIMARY KEY DEFAULT true CHECK (id),
+  version          bigint NOT NULL DEFAULT 0,
+  -- The live build; null before the first release.
+  live_build       text,
+  -- The scheduled update; the app closes to new work ahead of it.
+  update_at        timestamptz,
+  -- The cutover run owning the update: its writes fence on it.
+  update_run       text CHECK ((update_run IS NULL) = (update_at IS NULL)),
+  -- The lease: who changes the deployment, doing what, until when.
+  lease_holder     text,
+  lease_operation  deploy.operation,
+  lease_expires_at timestamptz,
+  CHECK ((lease_holder IS NULL) = (lease_operation IS NULL)
+    AND (lease_holder IS NULL) = (lease_expires_at IS NULL))
+);
+
+INSERT INTO deploy.state DEFAULT VALUES;
+
+GRANT SELECT, UPDATE ON deploy.state TO app_service;
+
+-- Takes the lease for `p_holder` doing `p_operation` for `p_ttl` when
+-- free, expired, or its own (a renewal keeps its operation). One row:
+-- whether taken, and the lease as it stands.
+CREATE FUNCTION deploy.take_lease(
+  p_holder text,
+  p_operation deploy.operation,
+  p_ttl interval
+)
+RETURNS TABLE (
+  taken boolean,
+  holder text,
+  operation deploy.operation,
+  expires_at timestamptz
+)
+LANGUAGE plpgsql
+SET search_path = pg_catalog
+AS $$
+BEGIN
+  UPDATE deploy.state d
+  SET lease_holder = p_holder,
+    lease_operation = CASE
+      WHEN d.lease_holder = p_holder AND d.lease_expires_at > now()
+        THEN d.lease_operation
+      ELSE p_operation
+    END,
+    lease_expires_at = now() + p_ttl
+  WHERE d.lease_holder IS NULL
+    OR d.lease_holder = p_holder
+    OR d.lease_expires_at < now()
+  RETURNING true, d.lease_holder, d.lease_operation, d.lease_expires_at
+  INTO taken, holder, operation, expires_at;
+  IF NOT FOUND THEN
+    -- The lease as the race winner left it.
+    SELECT false, d.lease_holder, d.lease_operation, d.lease_expires_at
+    INTO taken, holder, operation, expires_at
+    FROM deploy.state d;
+  END IF;
+  RETURN NEXT;
+END;
+$$;
+
+COMMENT ON FUNCTION deploy.take_lease(text, deploy.operation, interval) IS
+  'Takes or renews the deploy lease; reports the lease as it stands.';
+REVOKE ALL ON FUNCTION deploy.take_lease(text, deploy.operation, interval) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION deploy.take_lease(text, deploy.operation, interval) TO app_service;
+
+-- Extends `p_holder`'s unexpired lease to `p_ttl` from now. One row:
+-- whether renewed, and the lease as it stands.
+CREATE FUNCTION deploy.renew_lease(p_holder text, p_ttl interval)
+RETURNS TABLE (
+  renewed boolean,
+  holder text,
+  operation deploy.operation,
+  expires_at timestamptz
+)
+LANGUAGE plpgsql
+SET search_path = pg_catalog
+AS $$
+BEGIN
+  UPDATE deploy.state d
+  SET lease_expires_at = now() + p_ttl
+  WHERE d.lease_holder = p_holder AND d.lease_expires_at > now()
+  RETURNING true, d.lease_holder, d.lease_operation, d.lease_expires_at
+  INTO renewed, holder, operation, expires_at;
+  IF NOT FOUND THEN
+    SELECT false, d.lease_holder, d.lease_operation, d.lease_expires_at
+    INTO renewed, holder, operation, expires_at
+    FROM deploy.state d;
+  END IF;
+  RETURN NEXT;
+END;
+$$;
+
+COMMENT ON FUNCTION deploy.renew_lease(text, interval) IS
+  'Extends the holder''s unexpired deploy lease; reports the lease as it stands.';
+REVOKE ALL ON FUNCTION deploy.renew_lease(text, interval) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION deploy.renew_lease(text, interval) TO app_service;
+
+-- Row-locks the deploy state for the calling transaction while `p_holder`
+-- holds an unexpired lease; raises otherwise. Command writes follow in the
+-- same transaction.
+CREATE FUNCTION deploy.fence_lease(p_holder text)
+RETURNS void
+LANGUAGE plpgsql
+SET search_path = pg_catalog
+AS $$
+DECLARE
+  holder text;
+  expires_at timestamptz;
+BEGIN
+  SELECT d.lease_holder, d.lease_expires_at INTO holder, expires_at
+  FROM deploy.state d FOR UPDATE;
+  IF NOT coalesce(holder = p_holder AND expires_at > now(), false) THEN
+    RAISE EXCEPTION 'deploy lease lost: % holds it until %',
+      coalesce(holder, 'no one'), coalesce(expires_at::text, 'released');
+  END IF;
+END;
+$$;
+
+COMMENT ON FUNCTION deploy.fence_lease(text) IS
+  'Locks the deploy state while the holder''s lease stands; raises otherwise.';
+REVOKE ALL ON FUNCTION deploy.fence_lease(text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION deploy.fence_lease(text) TO app_service;
+
+-- Drops the lease held by `p_holder`; a null holder breaks any. Returns
+-- the holder dropped; null when none matched.
+CREATE FUNCTION deploy.drop_lease(p_holder text)
+RETURNS text
+LANGUAGE sql
+SET search_path = pg_catalog
+AS $$
+  UPDATE deploy.state
+  SET lease_holder = NULL, lease_operation = NULL, lease_expires_at = NULL
+  WHERE lease_holder IS NOT NULL
+    AND (p_holder IS NULL OR lease_holder = p_holder)
+  RETURNING old.lease_holder;
+$$;
+
+COMMENT ON FUNCTION deploy.drop_lease(text) IS
+  'Drops the deploy lease of a holder, or any with a null holder.';
+REVOKE ALL ON FUNCTION deploy.drop_lease(text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION deploy.drop_lease(text) TO app_service;
+
+SET ROLE NONE;

package/sql/scrub.sql

@@ -0,0 +1,5 @@
+-- Snapshot scrub: the copy deploys nothing; it serves any build.
+UPDATE deploy.state
+SET live_build = NULL, update_at = NULL, update_run = NULL,
+  lease_holder = NULL, lease_operation = NULL, lease_expires_at = NULL,
+  version = version + 1;