@fabrika/platform 0.0.1

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@fabrika/platform",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/platform"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	}
+}

package/src/deploy-locks-sql.ts

@@ -0,0 +1,71 @@
+// `DeployLocks` as ONE row per lease — the Durable Object's three guarantees expressed as properties
+// of a STATEMENT rather than of Cloudflare's single-threaded object, so the same code serves SQLite,
+// D1 and Postgres.
+//
+// It lives in `@fabrika/platform` (with the ports, not with either runtime) because it depends on
+// NOTHING but the `SqlDatabase` port: no `cloudflare:workers`, no `bun:*`, no `node:*`, no I/O
+// primitive of its own. That makes it runtime-neutral by construction, which is why the control-plane
+// Worker and a long-running Bun process can share ONE copy instead of keeping two that drift.
+//
+// The contract (verbatim from the port):
+//   * NON-REENTRANT — a live lease is refused even to its own holder, so a redelivered message defers
+//     instead of double-running.
+//   * TTL-BOUNDED — a consumer that dies mid-deploy never releases; the stored deadline is what lets
+//     the next run take over instead of the target being wedged forever.
+//   * HOLDER-CHECKED release — a late release from a superseded run cannot free a newer run's lease.
+//
+// `acquire` is ONE conditional upsert and NEVER a read-then-write. Two consumers racing for a free
+// target cannot both observe "free": one inserts, the other conflicts onto the live row and its
+// DO UPDATE is skipped by the `expires_at <= ?` guard. `meta.changes` is the whole answer — 1 means
+// the lease is ours, 0 means someone else holds it. Splitting this into a SELECT and an UPDATE
+// reintroduces exactly the race the DO existed to prevent.
+//
+// GENERIC ON PURPOSE: the table name is a parameter so a control plane that already owns a
+// `deploy_locks` table and a second service that wants its own lease table share one implementation.
+// The DDL is per-dialect and therefore NOT here — see `@fabrika/control`'s migrations (SQLite/D1) and
+// `@fabrika/platform-node`'s `migrations/0002_deploy_locks.sql` (Postgres).
+
+import type { DeployLocks } from './ports'
+import type { SqlDatabase } from './sql'
+
+export interface SqlDeployLocksOptions {
+	/** Table holding the leases. Must already exist; the DDL is the owning service's migration. */
+	table?: string
+	/** Injectable clock so lease expiry is testable without sleeping. */
+	now?: () => number
+}
+
+/** The default lease table, matching the `deploy_locks` table both current consumers migrate. */
+const DEFAULT_TABLE = 'deploy_locks'
+/** A table name is interpolated into SQL, so it is restricted to a bare unqualified identifier. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+export class SqlDeployLocks implements DeployLocks {
+	private readonly acquireSql: string
+	private readonly releaseSql: string
+	private readonly now: () => number
+
+	constructor(private readonly db: SqlDatabase, options: SqlDeployLocksOptions = {}) {
+		const table = options.table ?? DEFAULT_TABLE
+		if (!IDENTIFIER.test(table)) {
+			throw new Error(`invalid lock table name: ${table}`)
+		}
+		this.now = options.now ?? Date.now
+		this.acquireSql = `INSERT INTO ${table} (lock_key, holder, expires_at) VALUES (?, ?, ?)
+			ON CONFLICT (lock_key) DO UPDATE SET holder = excluded.holder, expires_at = excluded.expires_at
+			WHERE ${table}.expires_at <= ?`
+		this.releaseSql = `DELETE FROM ${table} WHERE lock_key = ? AND holder = ?`
+	}
+
+	async acquire(key: string, holder: string, ttlMs: number): Promise<boolean> {
+		const now = this.now()
+		const result = await this.db.prepare(this.acquireSql).bind(key, holder, now + ttlMs, now).run()
+		return (result.meta.changes ?? 0) > 0
+	}
+
+	async release(key: string, holder: string): Promise<void> {
+		// Deleting the row is what "free" means. The holder predicate makes this a no-op for a run whose
+		// lease already expired and was taken over — it cannot delete the newer holder's row.
+		await this.db.prepare(this.releaseSql).bind(key, holder).run()
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// @fabrika/platform — the ports every runtime-specific implementation must satisfy, plus the
+// implementations that need nothing BUT those ports.
+//
+// The rule is not "types only" — it is: NO runtime-specific imports and NO I/O primitives of its own.
+// Nothing here may import `cloudflare:workers`, `bun:*`, or `node:*`; nothing here may open a socket,
+// touch a filesystem, or reach for a global that only one runtime has. A portable implementation
+// written purely against a port (`SqlDeployLocks` over `SqlDatabase`) is runtime-neutral by
+// construction and belongs here — keeping one copy instead of one per runtime is the whole point.
+// Runtime-specific implementations live with the workers that use them, or in @fabrika/platform-node.
+
+export { SqlDeployLocks, type SqlDeployLocksOptions } from './deploy-locks-sql'
+export type { AssetServer, BlobStore, DeployLocks, HttpService, JobQueue, WaitUntil } from './ports'
+export type { SqlDatabase, SqlQueryResult, SqlRunResult, SqlStatement } from './sql'

package/src/ports.ts

@@ -0,0 +1,59 @@
+// The remaining platform ports. Each one names a capability the control plane needs, in the
+// narrowest form the code actually uses — not the full surface of whatever Cloudflare primitive
+// happens to provide it today. Widening a port is a decision; keep them boring.
+//
+// UNLIKE `SqlDatabase`, these are NOT satisfied structurally by the Cloudflare bindings, and no
+// amount of wishing makes them so: `R2Bucket.put` resolves to `R2Object | null` and `Queue.send` to
+// `QueueSendResponse`, neither of which is assignable to `Promise<void>`. The Cloudflare side wraps
+// them in await-and-discard adapters (`packages/control/src/platform-cf.ts`). That is the correct
+// shape — a port should describe what callers need, not inherit a vendor's return values — but it
+// does mean adopting one of these ports costs a small adapter rather than nothing.
+
+/** Bytes written to blob storage (run logs). Both R2 and S3/MinIO satisfy this. */
+export interface BlobStore {
+	put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>
+	get(key: string): Promise<{ body: ReadableStream; text(): Promise<string> } | null>
+	delete(key: string): Promise<void>
+}
+
+/** Enqueue a deploy job. The CONSUMER side is platform-specific and deliberately not modelled here. */
+export interface JobQueue<T> {
+	send(message: T, options?: { delaySeconds?: number }): Promise<void>
+}
+
+/**
+ * Per-target mutual exclusion, keyed by `<app>:<env>`. Matches the seam the control plane already
+ * had around its Durable Object, so swapping the implementation touches no call site.
+ *
+ * Contract, unchanged from the DO it replaces:
+ *  - NON-REENTRANT — a live lease returns false even to the same holder, so a redelivered message
+ *    defers rather than double-running.
+ *  - TTL-BOUNDED — a consumer that dies mid-deploy self-heals when the lease expires, instead of
+ *    wedging that app-env forever.
+ *  - HOLDER-CHECKED release — a late release from a superseded run can never free a lease that a
+ *    newer run has since taken.
+ *
+ * The database-backed implementation expresses all three as one conditional UPDATE, which is atomic
+ * on SQLite and Postgres alike — so this port has ONE implementation on every platform.
+ */
+export interface DeployLocks {
+	/** Take the lease for `key`. `true` when acquired (free or expired), `false` when live elsewhere. */
+	acquire(key: string, holder: string, ttlMs: number): Promise<boolean>
+	/** Release the lease iff `holder` still owns it. Idempotent; a stale holder's call is a no-op. */
+	release(key: string, holder: string): Promise<void>
+}
+
+/** One HTTP-speaking service behind a platform-native or network transport. */
+export interface HttpService {
+	fetch(request: Request): Promise<Response>
+}
+
+/** Serves the built SPA for non-API paths. */
+export interface AssetServer extends HttpService {}
+
+/**
+ * Keep work alive past the response. On Workers this is `ctx.waitUntil`; in a long-running process
+ * it is a supervised background promise. Implementations MUST swallow-and-log rejections — a
+ * background failure must never take the process down.
+ */
+export type WaitUntil = (promise: Promise<unknown>) => void

package/src/sql.ts

@@ -0,0 +1,61 @@
+// The SQL port — the ONE database seam every service sits on.
+//
+// Shape is deliberately D1's: a real `D1Database` satisfies `SqlDatabase` STRUCTURALLY, with no
+// adapter and no rewriting of the ~90 statements the services already carry. The Postgres driver
+// reimplements this same surface (see @fabrika/platform-node), so the SQL bodies stay in ONE place
+// instead of being duplicated per backend.
+//
+// The cost of that choice lands on the SQL, not on the code: every statement must stay inside the
+// SQLite ∩ Postgres common subset. In practice that is cheap — both dialects support `ON CONFLICT`
+// and `RETURNING`, and this codebase already generates ids and timestamps caller-side (never
+// `strftime`/`unixepoch`/`AUTOINCREMENT` in a query). Placeholder syntax is the one real divergence
+// and the Postgres driver rewrites `?` → `$n` mechanically. DDL is NOT covered here — migrations are
+// per-dialect and are the genuinely expensive part of the port.
+
+/**
+ * A prepared statement. `bind()` returns a NEW statement; it never mutates the receiver (D1
+ * semantics) — call sites build a base statement and bind it repeatedly, so a mutating `bind()`
+ * corrupts them silently.
+ *
+ * Two further contracts every driver must honour, both relied on by existing call sites:
+ *  - **`bind()` is optional.** A statement with no placeholders is executed directly, and `bind()`
+ *    may legally be called with zero arguments.
+ *  - **SQL NULL maps to JS `null`, never `undefined`.** Row shapes are checked with `=== null`.
+ */
+export interface SqlStatement {
+	/** Bind positional parameters, left to right, for this statement's `?` placeholders. */
+	bind(...values: unknown[]): SqlStatement
+	/** First row, or `null` when the query matched nothing. */
+	first<T = Record<string, unknown>>(): Promise<T | null>
+	/** All matching rows. */
+	all<T = Record<string, unknown>>(): Promise<SqlQueryResult<T>>
+	/** Execute a write. Read `meta.changes` to learn whether it affected anything. */
+	run(): Promise<SqlRunResult>
+}
+
+/** The result of `all()` — wrapped in `{ results }` to match D1 so no call site changes. */
+export interface SqlQueryResult<T> {
+	results: T[]
+}
+
+/**
+ * The result of `run()`. `changes` is how the guarded-UPDATE idioms across this codebase detect a
+ * no-op, so it is REQUIRED: a driver that left it undefined would turn every successful guarded
+ * write into a silent "not found". `D1Meta.changes` is likewise non-optional, so D1 still satisfies
+ * this structurally.
+ *
+ * It counts rows AFFECTED BY A WRITE. A `SELECT` reports `0` — drivers whose underlying client
+ * returns a row count for reads must map that to `0` rather than passing it through.
+ */
+export interface SqlRunResult {
+	meta: {
+		/** Rows actually affected. `0` means the guard did not match — never treat it as success. */
+		changes: number
+	}
+}
+
+/** A database handle. `batch()` executes its statements atomically, in order. */
+export interface SqlDatabase {
+	prepare(sql: string): SqlStatement
+	batch<T = Record<string, unknown>>(statements: SqlStatement[]): Promise<SqlQueryResult<T>[]>
+}