@fjall/schema-gate 10.1.1

package/LICENSE

@@ -0,0 +1,50 @@
+Fjall Proprietary Software Licence
+
+Copyright (c) 2026 Fjall. All rights reserved.
+
+This software, including all source, object, bundled, and minified forms
+("the Software"), is the proprietary and confidential property of Fjall.
+
+1. Permitted Use. Subject to the terms of this Licence, Fjall grants you
+   a non-exclusive, non-transferable, revocable licence to install the
+   Software via the npm registry and to execute it solely for the purpose
+   of deploying, operating, and managing your own applications and
+   infrastructure on cloud providers.
+
+2. Restrictions. You may NOT, and may not permit any third party to:
+   (a) copy, redistribute, sublicense, sell, rent, lease, or otherwise
+       transfer the Software;
+   (b) modify, adapt, translate, or create derivative works of the Software;
+   (c) reverse engineer, decompile, disassemble, deminify, or otherwise
+       attempt to derive the source code, structure, or organisation of
+       the Software, except to the minimum extent expressly permitted by
+       applicable mandatory law;
+   (d) use the Software, or any portion of it, to develop, train, or
+       improve any product or service that competes with Fjall;
+   (e) remove, alter, or obscure any proprietary notices contained in
+       the Software;
+   (f) publish, share, or otherwise disclose the Software or its contents
+       to any third party.
+
+3. Ownership. All right, title, and interest in and to the Software,
+   including all intellectual property rights, remain with Fjall. No
+   rights are granted except as expressly set out in this Licence.
+
+4. Termination. This Licence terminates automatically if you breach any
+   of its terms. Upon termination you must cease all use of the Software
+   and destroy all copies in your possession.
+
+5. Disclaimer of Warranty. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT
+   WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
+   THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   AND NON-INFRINGEMENT.
+
+6. Limitation of Liability. IN NO EVENT SHALL FJALL BE LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES
+   ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGES.
+
+7. Governing Law. This Licence is governed by the laws of England and
+   Wales, without regard to conflict of laws principles.
+
+For commercial licensing enquiries, contact: contact@fjall.io

package/dist/.build-source-hash

@@ -0,0 +1,24 @@
+{
+  "version": 2,
+  "algorithm": "sha256",
+  "sources": [
+    "src"
+  ],
+  "extraFiles": [
+    "../scripts/minify-dist.mjs",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "hash": "505139b3e780af0997b693326624892b3c01dd78547001cfcfb3901dbc749aa4",
+  "files": {
+    "src/bin.ts": "3acde81b3b914cc4",
+    "src/index.ts": "ab1151c1b7f1bc38",
+    "src/runSchemaGate.ts": "f0a4b0fec6a095de",
+    "src/types.ts": "67a71f4a53cc1e83",
+    "../scripts/minify-dist.mjs": "6b2e4b0df8aec601",
+    "package.json": "abbd127fa295a73e",
+    "tsconfig.json": "8a11f0e3fce6a36a"
+  },
+  "outputHash": "283ec27ac60724f090ed3d911a0bd9f4e15b8be9e195d25d490a75b9b225c9ad",
+  "outputFileCount": 9
+}

package/dist/.minified

@@ -0,0 +1 @@
+4 files minified at 2026-08-11T22:22:01.205Z

package/dist/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Container entrypoint for the synthetic `fjall-schema-gate` container.
+ * Wires the real drivers into `runSchemaGate` and exits with the taxonomy
+ * code — the dependent app containers' `dependsOn: SUCCESS` turns any
+ * non-zero exit into a pre-RUNNING task stop the deployment circuit breaker
+ * can count.
+ */
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+var m=Object.defineProperty;var o=(e,t)=>m(e,"name",{value:t,configurable:!0});import{createFjallClickHouseClient as p}from"@fjall/clickhouse";import{getErrorMessage as s,maskSensitiveOutput as a}from"@fjall/util";import d from"pg";import{runSchemaGate as f}from"./runSchemaGate.js";import{SCHEMA_GATE_EXIT as S}from"./types.js";const{Client:g}=d,w="FjallSchemaGate",i=1e4;function r(e,t,n={}){process.stdout.write(`${JSON.stringify({timestamp:new Date().toISOString(),level:e,namespace:w,message:t,...n})}
+`)}o(r,"log");function u(e,t){return new g({connectionString:e,connectionTimeoutMillis:i,query_timeout:i,statement_timeout:i,...t?{ssl:{rejectUnauthorized:!1}}:{}})}o(u,"buildPgClient");const C={async connectPg(e){const t=u(e,!0);try{return await t.connect(),t}catch(n){if(!/does not support SSL/i.test(s(n)))throw n;await t.end().catch(l=>{r("warn","Postgres TLS probe cleanup failed",{error:a(s(l))})}),r("info","Server does not support TLS \u2014 connecting in plaintext");const c=u(e,!1);return await c.connect(),c}},createChClient(e){return p({url:e.url,username:e.username,password:e.password,...e.caCert!==void 0?{caCert:e.caCert}:{},request_timeout:i})},sleep:o(e=>new Promise(t=>setTimeout(t,e)),"sleep"),log:r};for(const[e,t]of[["SIGTERM",143],["SIGINT",130]])process.on(e,()=>{r("warn",`Received ${e} \u2014 exiting without a verdict`),process.exit(t)});f(process.env,C).then(e=>{process.exit(e)}).catch(e=>{r("error","Gate crashed",{error:a(s(e))}),process.exit(S.configError)});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CONNECTION_ATTEMPTS, RETRY_DELAY_MS, runSchemaGate, } from "./runSchemaGate.js";
+export { SCHEMA_GATE_EXIT, type SchemaGateChClientOpts, type SchemaGateChHandle, type SchemaGateDeps, type SchemaGateExitCode, type SchemaGateLogLevel, type SchemaGateLogger, type SchemaGatePgHandle, } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+import{CONNECTION_ATTEMPTS as r,RETRY_DELAY_MS as _,runSchemaGate as e}from"./runSchemaGate.js";import{SCHEMA_GATE_EXIT as A}from"./types.js";export{r as CONNECTION_ATTEMPTS,_ as RETRY_DELAY_MS,A as SCHEMA_GATE_EXIT,e as runSchemaGate};

package/dist/runSchemaGate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Core gate logic for the synthetic `fjall-schema-gate` container.
+ *
+ * Reads the env contract injected by `EcsCompute` (names shared via
+ * `@fjall/util/migration` — coupled values across the construct↔runner
+ * boundary), verifies each configured target against the live database with
+ * the tolerant comparator (`actual >= expected`; rollbacks after expand-only
+ * migrations must boot), and returns an exit code from the taxonomy in
+ * `types.ts`.
+ *
+ * Connection attempts are bounded: `CONNECTION_ATTEMPTS` tries,
+ * `RETRY_DELAY_MS` apart, per target. Targets verify in parallel so the
+ * worst-case wall clock stays inside the dependent containers'
+ * `startTimeout` (120s) with headroom.
+ */
+import { type SchemaGateDeps, type SchemaGateExitCode } from "./types.js";
+export declare const CONNECTION_ATTEMPTS = 3;
+export declare const RETRY_DELAY_MS = 5000;
+/**
+ * Bound on how long a post-verdict client close may hold up the exit path.
+ * The verdict is already in hand — a close that outlives this is abandoned
+ * (the process exits immediately after, dropping the socket).
+ */
+export declare const CLIENT_CLOSE_TIMEOUT_MS = 2000;
+/**
+ * Run every configured verification target and reduce to one exit code.
+ * See `SCHEMA_GATE_EXIT` for the taxonomy and its precedence rules.
+ */
+export declare function runSchemaGate(env: Record<string, string | undefined>, deps: SchemaGateDeps): Promise<SchemaGateExitCode>;

package/dist/runSchemaGate.js

@@ -0,0 +1 @@
+var R=Object.defineProperty;var i=(e,t)=>R(e,"name",{value:t,configurable:!0});import{verifyExpectedClickHouseSchemaVersion as k}from"@fjall/clickhouse";import{maskSensitiveOutput as H}from"@fjall/util";import{EXPECTED_CH_SCHEMA_VERSION_ENV as m,EXPECTED_SCHEMA_VERSION_ENV as p,EXPECTED_SCHEMA_VERSION_TOOL_ENV as C,SCHEMA_ADMIN_PASSWORD_ENV as M,SCHEMA_ADMIN_USER_ENV as b,SCHEMA_GATE_CH_CA_CERT_ENV as P,SCHEMA_GATE_CH_DATABASE_ENV as V,SCHEMA_GATE_CH_URL_ENV as D,SCHEMA_GATE_DB_PASSWORD_ENV as G,SCHEMA_GATE_DB_URL_BASE_ENV as S,SCHEMA_GATE_DB_USER_ENV as O,verifyExpectedSchemaVersion as U}from"@fjall/util/migration";import{SCHEMA_GATE_EXIT as f}from"./types.js";const g=3,x=5e3,w=500,v="42P01",I=new Set(["60","81"]),$=2e3,L=new Set(["postgresql:","postgres:"]);class _ extends Error{static{i(this,"GateConfigError")}}function d(e){const t=e instanceof Error?e.message:String(e),a=H(t);return a.length>w?`${a.slice(0,w)}...`:a}i(d,"maskedError");function E(e,t,a){const r=e[t];if(r===void 0||r==="")throw new _(`${a}, but ${t} is missing or empty. The construct injects both together \u2014 an incomplete set points at an author override or a framework bug.`);return r}i(E,"requireEnv");function B(e,t,a){let r;try{r=new URL(e)}catch{throw new _(`${S} is not a parseable URL`)}if(!L.has(r.protocol))throw new _(`${S} has scheme '${r.protocol}' \u2014 the materialised gate supports the postgres engine family only. Set schemaGate: { materialise: false } for this service.`);return r.username=encodeURIComponent(t),r.password=encodeURIComponent(a),r.searchParams.delete("sslmode"),r.toString()}i(B,"composePgUrl");function y(e){return typeof e=="object"&&e!==null&&"code"in e&&e.code===v}i(y,"isUndefinedTableError");function A(e){if(typeof e!="object"||e===null)return!1;const t=e.code;return typeof t=="string"&&I.has(t)}i(A,"isChNeverMigratedError");async function T(e,t,a){await Promise.race([a().catch(r=>{e.log("warn",`${t} client close failed`,{error:d(r)})}),e.sleep($)])}i(T,"closeWithTimeout");async function N(e,t,a){let r;for(let n=1;n<=g;n++)try{return await a()}catch(s){if(r=s,y(s)||A(s))throw s;e.log("warn","Verification attempt failed",{target:t,attempt:n,of:g,error:d(s)}),n<g&&await e.sleep(x)}throw r}i(N,"withRetry");async function X(e,t,a){const r=`${p} is set`,n=E(e,C,r);if(n!=="prisma")throw new _(`${C}='${n}' \u2014 the materialised gate supports tool "prisma" only (a custom tool's metadata query cannot be expressed through the env contract). Set schemaGate: { materialise: false } for this service.`);const s=E(e,S,r),u=E(e,O,r),l=E(e,G,r),o=B(s,u,l);try{const c=await N(t,"postgres",async()=>{const h=await t.connectPg(o);try{return await U({tool:"prisma",expected:a,client:h})}finally{await T(t,"Postgres",()=>h.end())}});return{target:"postgres",kind:c.matches?"pass":"refused",expected:a,actual:c.actual}}catch(c){return y(c)?{target:"postgres",kind:"refused",expected:a,actual:null,detail:"migrations table absent \u2014 the database has never been migrated while the deployed image expects a schema version"}:{target:"postgres",kind:"connection-error",expected:a,detail:d(c)}}}i(X,"verifyPostgres");async function j(e,t,a){const r=`${m} is set`,n=E(e,D,r),s=E(e,b,r),u=E(e,M,r),l=e[P],o=e[V];try{const c=await N(t,"clickhouse",async()=>{const h=t.createChClient({url:n,username:s,password:u,...l!==void 0&&l!==""?{caCert:l}:{}});try{return await k({client:h,expected:a,...o!==void 0&&o!==""?{database:o}:{}})}finally{await T(t,"ClickHouse",()=>h.close())}});return{target:"clickhouse",kind:c.matches?"pass":"refused",expected:a,actual:c.actual}}catch(c){return A(c)?{target:"clickhouse",kind:"refused",expected:a,actual:null,detail:"migrations audit table absent \u2014 the ClickHouse database has never been migrated while the deployed image expects a schema version"}:{target:"clickhouse",kind:"connection-error",expected:a,detail:d(c)}}}i(j,"verifyClickHouse");async function J(e,t){const a=e[p],r=e[m],n=a!==void 0&&a!=="",s=r!==void 0&&r!=="";if(!n&&!s)return t.log("error","Nothing to verify \u2014 no expected-version env present",{hint:`neither ${p} nor ${m} is set; the construct should never materialise a gate container without one`}),f.configError;const u=[];n&&u.push(X(e,t,a)),s&&u.push(j(e,t,r));let l;try{l=await Promise.all(u)}catch(o){return o instanceof _?(t.log("error","Gate configuration invalid",{error:d(o)}),f.configError):(t.log("error","Gate failed unexpectedly",{error:d(o)}),f.configError)}for(const o of l)o.kind==="pass"?t.log("info","Schema version satisfied",{target:o.target,expected:o.expected,actual:o.actual??null}):o.kind==="refused"?t.log("error","REFUSED \u2014 schema version not satisfied",{target:o.target,expected:o.expected,actual:o.actual??null,...o.detail!==void 0?{detail:o.detail}:{}}):t.log("error","Verification target unreachable after retries",{target:o.target,expected:o.expected,attempts:g,...o.detail!==void 0?{error:o.detail}:{}});return l.some(o=>o.kind==="refused")?f.refused:l.some(o=>o.kind==="connection-error")?f.connectionError:f.pass}i(J,"runSchemaGate");export{$ as CLIENT_CLOSE_TIMEOUT_MS,g as CONNECTION_ATTEMPTS,x as RETRY_DELAY_MS,J as runSchemaGate};

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Exit taxonomy for the materialised gate container. The dependent app
+ * containers declare `dependsOn: [{ container: "fjall-schema-gate",
+ * condition: "SUCCESS" }]`, so ANY non-zero exit stops the task pre-RUNNING
+ * and counts toward the deployment circuit breaker's stage-1 arithmetic —
+ * the codes exist for the forensic log and the deploy-time ECS tail, not for
+ * ECS itself.
+ *
+ * - `pass` (0) — every configured target verified; app containers start.
+ * - `refused` (1) — a target's live schema does not satisfy the expected
+ *   version (forward skew, or a never-migrated database). The gate did its
+ *   job; the deploy must roll back or the migration must land first.
+ * - `configError` (2) — the gate could not even attempt verification:
+ *   missing/empty env, unsupported tool or engine family, or an internal
+ *   error. Points at a construct bug or an author override.
+ * - `connectionError` (3) — a target was unreachable after the bounded
+ *   retry budget. Indeterminate: the schema may be fine.
+ *
+ * Precedence when targets disagree: `configError` is detected before any
+ * connection is attempted; a verified `refused` outranks `connectionError`
+ * (a refusal is definitive evidence, an unreachable sibling is not).
+ */
+export declare const SCHEMA_GATE_EXIT: {
+    readonly pass: 0;
+    readonly refused: 1;
+    readonly configError: 2;
+    readonly connectionError: 3;
+};
+export type SchemaGateExitCode = (typeof SCHEMA_GATE_EXIT)[keyof typeof SCHEMA_GATE_EXIT];
+export type SchemaGateLogLevel = "info" | "warn" | "error";
+/**
+ * Structured one-line JSON log sink. The container's stdout lands in the
+ * service's CloudWatch log group (and, on abnormal stop, in the task-stop
+ * watchdog's forensic log via `stoppedReason`), so every line must be
+ * self-contained and pre-masked.
+ */
+export type SchemaGateLogger = (level: SchemaGateLogLevel, message: string, context?: Record<string, unknown>) => void;
+/** Minimal Postgres handle the runner needs — `pg.Client` satisfies it. */
+export interface SchemaGatePgHandle {
+    query(sql: string): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+    end(): Promise<void>;
+}
+/** Minimal ClickHouse handle — `@clickhouse/client` satisfies it. */
+export interface SchemaGateChHandle {
+    query(params: {
+        query: string;
+        format: "JSONEachRow";
+    }): Promise<{
+        json(): Promise<unknown>;
+    }>;
+    close(): Promise<void>;
+}
+export interface SchemaGateChClientOpts {
+    url: string;
+    username: string;
+    password: string;
+    caCert?: string;
+}
+/**
+ * Injectable seams. `bin.ts` supplies the real drivers; tests supply fakes
+ * that can express every failure shape (refusal, missing table, connect
+ * timeout) — a fake that cannot express the bug shape cannot catch it.
+ */
+export interface SchemaGateDeps {
+    connectPg(connectionUrl: string): Promise<SchemaGatePgHandle>;
+    createChClient(opts: SchemaGateChClientOpts): SchemaGateChHandle;
+    sleep(ms: number): Promise<void>;
+    log: SchemaGateLogger;
+}

package/dist/types.js

@@ -0,0 +1 @@
+const r={pass:0,refused:1,configError:2,connectionError:3};export{r as SCHEMA_GATE_EXIT};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@fjall/schema-gate",
+  "version": "10.1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fjall-tech/fjall.git",
+    "directory": "schema-gate"
+  },
+  "description": "Schema-version gate runner for the synthetic fjall-schema-gate ECS container. Verifies the deployed image's expected schema version against the live database (Postgres + ClickHouse) and exits with a structured taxonomy so a refusing task stops pre-RUNNING and trips the deployment circuit breaker.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "fjall-schema-gate": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf ./dist ./sourcemaps",
+    "clean:node": "rm -rf ./node_modules",
+    "build": "npm run clean && npx tsc && node ../scripts/minify-dist.mjs dist && node ../scripts/stamp-build.mjs",
+    "prepack": "node ../scripts/check-dist-freshness.mjs",
+    "watch": "npm run build && npx tsc-watch",
+    "watch:only": "npx tsc-watch",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json}\"",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "test": "vitest run",
+    "typecheck": "npx tsc --noEmit"
+  },
+  "author": "",
+  "license": "SEE LICENSE IN LICENSE",
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "@types/pg": "^8.16.0",
+    "prettier": "^3.9.6",
+    "tsc-watch": "^7.2.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "@clickhouse/client": "^1.23.1",
+    "@fjall/clickhouse": "^10.1.1",
+    "@fjall/util": "^10.1.1",
+    "pg": "^8.16.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}