@firetail/finchly 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@firetail/finchly`. Versions follow semver.
 
 ## Unreleased
 
+## 0.0.6 - 2026-11-12
+
+- `connectDatabase`: PostgreSQL for a service whose manifest sets
+  `permissions.db`. It asks the platform for the role and schema made for
+  the service and connects with the `pg` package, which the service
+  installs itself. `execute`, `transaction`, `withAdvisoryLock`, `migrate`.
+- `fetchSettings`: what the platform holds for the service.
+- New error codes: `database_unavailable`, `database_not_granted`,
+  `migration_invalid`.
+- `pg` is an optional peer dependency.
+
 ## 0.0.5 - 2026-11-12
 
 - The README covers using the SDK only. Notes for people working on the

package/README.md

@@ -5,7 +5,7 @@ A service or app uses it to register with a Finchly deployment, verify who
 is calling it, and reach the platform's database, object store, queue and
 other services.
 
-Status: early. The package builds and is tested, but only the first four
+Status: early. The package builds and is tested, but only the first five
 modules exist.
 
 The SDK implements the platform API, which is specified in
@@ -160,6 +160,52 @@ The other half of the `app` module is not built: serving the
 that is already running, and fetching the settings the platform creates for
 an app.
 
+### A database of its own
+
+A service whose manifest sets `permissions.db` is given a PostgreSQL role
+and a schema that only that role can use. The service installs `pg` itself:
+
+```
+npm install pg
+```
+
+```js
+import { connectDatabase } from "@firetail/finchly";
+
+// Once, at startup. Asks the platform for the role and schema it made.
+const db = await connectDatabase({ service });
+await db.migrate(new URL("./migrations/", import.meta.url).pathname);
+
+const { rows } = await db.execute("SELECT id, body FROM notes WHERE author = $1", [caller.subject]);
+
+await db.transaction(async (tx) => {
+  await tx.execute("INSERT INTO notes (body, author) VALUES ($1, $2)", ["hello", caller.subject]);
+  await tx.execute("UPDATE authors SET notes = notes + 1 WHERE id = $1", [caller.subject]);
+});
+
+// One instance at a time, across every instance of this service.
+await db.withAdvisoryLock("nightly-import", async (tx) => {
+  // ...
+});
+```
+
+- **Names need no schema.** `notes` means the service's own table. The
+  service cannot read the platform's tables or another service's.
+- **Values go in the second argument**, as `$1`, `$2`. They are never built
+  into the SQL.
+- **A transaction** commits if its function returns and rolls back if it
+  throws.
+- **Migrations** are files named `NNNN_name.sql`, applied in order, once
+  each, in one transaction. Every instance may call `migrate` at startup:
+  they take turns. A migration that was applied is never edited; add a new
+  one. A problem is a `FinchlyError` with code `migration_invalid`.
+- `connectDatabase` rejects with `database_not_granted` if the manifest
+  does not ask for a database, and with `database_unavailable` if the
+  platform or the database cannot be reached.
+
+To run a service on its own, without a platform, give the URL directly:
+`connectDatabase({ url, slug })`.
+
 ### What every request carries
 
 Every request this SDK makes to the platform says which SDK and which
@@ -168,7 +214,7 @@ release is asking:
 | Header | Value |
 |---|---|
 | `x-platform-sdk` | `@firetail/finchly` |
-| `x-platform-sdk-version` | This release, for example `0.0.5` |
+| `x-platform-sdk-version` | This release, for example `0.0.6` |
 | `x-platform-api-version` | The platform API version it speaks, `v1` |
 
 That covers fetching the gateway's issuer and keys, registering an instance
@@ -198,7 +244,7 @@ not leak them.
 | `identity` | Verify `x-platform-identity` | Done. Directory lookups (`listUsers`, `membersOf`) and `require*` helpers are planned |
 | `app` | Register with the platform, serve `/_platform/*`, renew keys, fetch settings | Self-registration and key renewal are done, through `service`. Serving `/_platform/*` and fetching settings are not |
 | `service` | Call other services through the gateway, as the service or for a user | Done, for built-in services and for apps |
-| `db` | PostgreSQL: queries, transactions, advisory locks, migrations | Planned |
+| `db` | PostgreSQL: queries, transactions, advisory locks, migrations | Done |
 | `blobs` | Object storage with conditional writes | Planned |
 | `queue` | Publish, lease, ack, nack | Planned |
 | `secrets` | Secrets and envelope encryption | Planned |

package/dist/db.d.ts

@@ -0,0 +1,63 @@
+import type { ServiceClient } from "./service.js";
+export interface QueryResult<Row> {
+    readonly rows: Row[];
+    readonly rowCount: number;
+}
+/** Something SQL can be run on: the database, or one transaction. */
+export interface Queryable {
+    /**
+     * Run a statement. Values go in `params` and are referred to as $1, $2
+     * and so on; never build them into the SQL. With no `params`, `sql` may
+     * hold several statements.
+     */
+    execute<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<QueryResult<Row>>;
+}
+export interface Database extends Queryable {
+    /** The service's schema, when the platform said which it is. Unqualified names already mean this schema. */
+    readonly schema: string | undefined;
+    /** Run `fn` in one transaction. It commits if `fn` returns and rolls back if it throws. */
+    transaction<T>(fn: (tx: Queryable) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` in a transaction that holds a lock named `key`. Another
+     * instance of this service that asks for the same key waits until this
+     * transaction ends. The lock is this service's own: another service
+     * using the same name does not wait for it.
+     */
+    withAdvisoryLock<T>(key: string, fn: (tx: Queryable) => Promise<T>): Promise<T>;
+    /**
+     * Apply the migrations in `directory` that have not been applied: files
+     * named NNNN_name.sql, in order, once each. Safe to call from every
+     * instance at startup. Resolves with the versions this call applied.
+     */
+    migrate(directory: string): Promise<string[]>;
+    close(): Promise<void>;
+}
+/** What the platform holds for this service. See spec/registration.md, section 4. */
+export interface PlatformSettings {
+    readonly slug: string;
+    readonly database?: {
+        readonly url: string;
+        readonly schema: string;
+    };
+}
+export interface DatabaseOptions {
+    /** The service's client. The database settings are fetched with it. */
+    readonly service?: Pick<ServiceClient, "call">;
+    /**
+     * Connect to this URL and do not ask the platform. For tests and for
+     * running a service on its own. Needs `slug`.
+     */
+    readonly url?: string;
+    /** The service's slug. Only needed with `url`. */
+    readonly slug?: string;
+    /** The most connections to hold open. Default 10. */
+    readonly maxConnections?: number;
+}
+/** Ask the platform what it holds for this service. */
+export declare function fetchSettings(service: Pick<ServiceClient, "call">): Promise<PlatformSettings>;
+/**
+ * Connect to this service's database. With `service`, the platform is
+ * asked for the role and schema it made; the manifest must set
+ * permissions.db. Rejects if the database cannot be reached.
+ */
+export declare function connectDatabase(options: DatabaseOptions): Promise<Database>;

package/dist/db.js

@@ -0,0 +1,211 @@
+// PostgreSQL for a service: the role and schema the platform made for it.
+//
+// The platform gives each service that asks for one (permissions.db in the
+// manifest) a database role and a schema only that role can use. This
+// module asks the platform for them and connects. It needs the `pg`
+// package, which the service installs itself.
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { FinchlyError } from "./errors.js";
+/** Ask the platform what it holds for this service. */
+export async function fetchSettings(service) {
+    const response = await service.call("core", "/api/apps/self/config");
+    if (response.status !== 200) {
+        throw new FinchlyError("database_unavailable", "The platform did not give this service its settings", [
+            `GET /core/api/apps/self/config answered ${response.status}`,
+        ]);
+    }
+    const body = (await response.json().catch(() => null));
+    if (body === null || typeof body !== "object" || typeof body.slug !== "string") {
+        throw new FinchlyError("database_unavailable", "The platform's settings answer could not be read");
+    }
+    return body;
+}
+async function loadPg() {
+    // A variable, so that TypeScript does not look for pg's types.
+    const name = "pg";
+    try {
+        const loaded = (await import(name));
+        return loaded.default ?? loaded;
+    }
+    catch {
+        throw new FinchlyError("database_unavailable", "The db module needs the `pg` package", [
+            "Install it in the service: npm install pg",
+        ]);
+    }
+}
+function toResult(result) {
+    // Several statements in one call give one result each. The last is the answer.
+    const last = (Array.isArray(result) ? result[result.length - 1] : result);
+    return { rows: last?.rows ?? [], rowCount: last?.rowCount ?? 0 };
+}
+function queryable(target) {
+    return {
+        async execute(sql, params) {
+            return toResult(params === undefined ? await target.query(sql) : await target.query(sql, [...params]));
+        },
+    };
+}
+const MIGRATION_FILE = /^(\d{4})_([a-z0-9_]+)\.sql$/;
+async function readMigrations(directory) {
+    let files;
+    try {
+        files = (await readdir(directory)).filter((file) => file.endsWith(".sql")).sort();
+    }
+    catch {
+        throw new FinchlyError("migration_invalid", "The migrations directory could not be read", [directory]);
+    }
+    const problems = [];
+    const migrations = [];
+    for (const file of files) {
+        const match = MIGRATION_FILE.exec(file);
+        if (!match) {
+            problems.push(`${file} is not named NNNN_name.sql`);
+            continue;
+        }
+        const sql = await readFile(join(directory, file), "utf8");
+        if (migrations.at(-1)?.version === match[1]) {
+            problems.push(`Two migrations share the version ${match[1]}`);
+        }
+        migrations.push({
+            version: match[1],
+            name: match[2],
+            sql,
+            checksum: createHash("sha256").update(sql).digest("hex"),
+        });
+    }
+    if (problems.length > 0) {
+        throw new FinchlyError("migration_invalid", "The migrations cannot be applied", problems);
+    }
+    return migrations;
+}
+async function applyMigrations(tx, migrations) {
+    await tx.execute(`
+    CREATE TABLE IF NOT EXISTS platform_migrations (
+      version    text PRIMARY KEY,
+      name       text NOT NULL,
+      checksum   text NOT NULL,
+      applied_at timestamptz NOT NULL DEFAULT now()
+    )
+  `);
+    const { rows } = await tx.execute("SELECT version, checksum FROM platform_migrations ORDER BY version");
+    const applied = new Map(rows.map((row) => [row.version, row.checksum]));
+    const known = new Set(migrations.map((migration) => migration.version));
+    const newestApplied = rows.at(-1)?.version ?? "";
+    const problems = [];
+    for (const version of applied.keys()) {
+        if (!known.has(version)) {
+            problems.push(`The database has migration ${version}, which this release of the service does not have`);
+        }
+    }
+    for (const migration of migrations) {
+        const checksum = applied.get(migration.version);
+        if (checksum !== undefined && checksum !== migration.checksum) {
+            problems.push(`${migration.version}_${migration.name} has changed since it was applied. Add a new migration instead`);
+        }
+        if (checksum === undefined && migration.version < newestApplied) {
+            problems.push(`${migration.version}_${migration.name} is older than ${newestApplied}, which is already applied`);
+        }
+    }
+    if (problems.length > 0) {
+        throw new FinchlyError("migration_invalid", "The migrations cannot be applied", problems);
+    }
+    const done = [];
+    for (const migration of migrations) {
+        if (applied.has(migration.version))
+            continue;
+        await tx.execute(migration.sql);
+        await tx.execute("INSERT INTO platform_migrations (version, name, checksum) VALUES ($1, $2, $3)", [
+            migration.version,
+            migration.name,
+            migration.checksum,
+        ]);
+        done.push(migration.version);
+    }
+    return done;
+}
+/**
+ * Connect to this service's database. With `service`, the platform is
+ * asked for the role and schema it made; the manifest must set
+ * permissions.db. Rejects if the database cannot be reached.
+ */
+export async function connectDatabase(options) {
+    let url;
+    let slug;
+    let schema;
+    if (options.url !== undefined) {
+        if (!options.slug) {
+            throw new FinchlyError("database_unavailable", "connectDatabase needs `slug` when it is given `url`");
+        }
+        ({ url, slug } = { url: options.url, slug: options.slug });
+    }
+    else if (options.service) {
+        const settings = await fetchSettings(options.service);
+        if (!settings.database) {
+            throw new FinchlyError("database_not_granted", "The platform made no database for this service", [
+                "Set permissions.db to true in the manifest",
+            ]);
+        }
+        ({ url, schema } = settings.database);
+        slug = settings.slug;
+    }
+    else {
+        throw new FinchlyError("database_unavailable", "connectDatabase needs `service`, or `url` and `slug`");
+    }
+    const pg = await loadPg();
+    const pool = new pg.Pool({ connectionString: url, max: options.maxConnections ?? 10 });
+    // An idle connection that drops must not take the process down.
+    pool.on("error", () => { });
+    const onPool = queryable(pool);
+    try {
+        await pool.query("SELECT 1");
+    }
+    catch (err) {
+        await pool.end().catch(() => { });
+        // pg's message names the host and the role, never the password.
+        throw new FinchlyError("database_unavailable", "The database could not be reached", [err.message]);
+    }
+    async function transaction(fn) {
+        const client = await pool.connect();
+        let broken;
+        try {
+            await client.query("BEGIN");
+            const result = await fn(queryable(client));
+            await client.query("COMMIT");
+            return result;
+        }
+        catch (err) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch (rollbackError) {
+                // The connection is in an unknown state. Do not put it back.
+                broken = rollbackError;
+            }
+            throw err;
+        }
+        finally {
+            client.release(broken);
+        }
+    }
+    const withAdvisoryLock = (key, fn) => transaction(async (tx) => {
+        // Advisory locks are shared by everything in the database, so the
+        // name carries the service's slug.
+        await tx.execute("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`svc:${slug}:${key}`]);
+        return fn(tx);
+    });
+    return {
+        schema,
+        execute: onPool.execute,
+        transaction,
+        withAdvisoryLock,
+        async migrate(directory) {
+            const migrations = await readMigrations(directory);
+            // One transaction: instances starting together take turns, and a
+            // migration that fails leaves nothing behind.
+            return withAdvisoryLock("migrate", (tx) => applyMigrations(tx, migrations));
+        },
+        close: () => pool.end(),
+    };
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type FinchlyErrorCode = "config_invalid" | "manifest_invalid" | "manifest_unreadable" | "identity_invalid" | "gateway_unreachable" | "platform_api_unsupported" | "service_call_invalid" | "service_key_rejected" | "app_registration_refused" | "app_pending_approval";
+export type FinchlyErrorCode = "config_invalid" | "manifest_invalid" | "manifest_unreadable" | "identity_invalid" | "gateway_unreachable" | "platform_api_unsupported" | "service_call_invalid" | "service_key_rejected" | "app_registration_refused" | "app_pending_approval" | "database_unavailable" | "database_not_granted" | "migration_invalid";
 /**
  * Every error this SDK throws on purpose. `code` is stable and safe to
  * branch on; `problems` lists each thing that was wrong, so a caller can

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
 export type { PlatformConfig } from "./config.js";
+export { connectDatabase, fetchSettings } from "./db.js";
+export type { Database, DatabaseOptions, PlatformSettings, QueryResult, Queryable } from "./db.js";
 export { FinchlyError, IdentityError } from "./errors.js";
 export type { FinchlyErrorCode, IdentityRejection } from "./errors.js";
 export { IDENTITY_HEADER, createIdentityVerifier } from "./identity.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
+export { connectDatabase, fetchSettings } from "./db.js";
 export { FinchlyError, IdentityError } from "./errors.js";
 export { IDENTITY_HEADER, createIdentityVerifier } from "./identity.js";
 export { checkManifest, loadManifest } from "./manifest.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firetail/finchly",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Node SDK for the Finchly platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.json",
-    "test": "npm run build && node --test \"test/**/*.test.mjs\"",
+    "test": "npm run build && node test/support/with-postgres.mjs node --test \"test/**/*.test.mjs\"",
     "prepublishOnly": "npm test"
   },
   "repository": {
@@ -34,9 +34,18 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "~5.9.3"
+    "typescript": "~5.9.3",
+    "pg": "^8.11.0"
   },
   "dependencies": {
     "jose": "^6.2.17"
+  },
+  "peerDependencies": {
+    "pg": "^8.11.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
   }
 }