@firetail/finchly 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -4,37 +4,39 @@ All notable changes to `@firetail/finchly`. Versions follow semver.
 
 ## Unreleased
 
-## 0.0.4 - 2026-11-12
+## 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.
 
-No change to the package. The first release published by the release
-workflow: 0.0.2 and 0.0.3 were tagged but did not reach npm, because the
-workflow published with a placeholder token in place of the trusted
-publisher. Everything listed under them arrives in this release.
+## 0.0.5 - 2026-11-12
 
-## 0.0.3 - 2026-11-12
+- The README covers using the SDK only. Notes for people working on the
+  SDK are no longer part of the package.
 
-Tagged but not published to npm.
+## 0.0.4 - 2026-11-12
 
 - Every request to the platform carries three headers: `x-platform-sdk`
   (the package name), `x-platform-sdk-version` (this release) and
   `x-platform-api-version` (the platform API version it speaks). A caller
   cannot replace them. Exported as `SDK_REQUEST_HEADERS`.
-
-## 0.0.2 - 2026-11-12
-
-Tagged but not published to npm.
-
 - An app can register itself: `createServiceClient` takes an `enrolment`
   (token, manifest, address) in place of a credential, and
   `enrolmentFrom(config, manifest)` builds one from the platform settings.
   Registration is what gets an app's instance key accepted.
 - New error codes: `app_pending_approval`, `app_registration_refused`.
 
+0.0.2 and 0.0.3 were not published.
+
 ## 0.0.1 - 2026-11-11
 
-The first release, published by hand so that the package exists and
-trusted publishing can be set up. Later releases come from the release
-workflow.
+The first release.
 
 - Package skeleton under its final name.
 - `loadConfig`: read and validate the `PLATFORM_*` settings.

package/README.md

@@ -1,15 +1,15 @@
 # @firetail/finchly
 
-Node SDK for the [Finchly](https://github.com/firetail-io/finchly) platform.
+Node SDK for the [Finchly](https://github.com/FireTail-io/finchly) platform.
 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
-`firetail-io/finchly` under `spec/`. This release speaks platform API `v1`
+`FireTail-io/finchly` under `spec/`. This release speaks platform API `v1`
 (draft).
 
 ## Install
@@ -69,7 +69,7 @@ try {
 A token is rejected unless it is signed with ES256 by a key the gateway
 publishes, names that gateway as issuer and this service as its only
 audience, and has not expired. The rules are in `spec/identity-token.md` in
-`firetail-io/finchly`.
+`FireTail-io/finchly`.
 
 No other header is ever consulted. On a path the manifest declares in
 `publicPaths` there is no token, and the service authenticates the request
@@ -115,7 +115,7 @@ The instance makes an ES256 key pair in memory the first time it is needed.
 The private half never leaves the process. The public half is registered
 with the gateway using the credential the service was deployed with, and
 extended by itself for as long as the instance runs. The rules are in
-`spec/service-token.md` and `spec/registration.md` in `firetail-io/finchly`.
+`spec/service-token.md` and `spec/registration.md` in `FireTail-io/finchly`.
 
 ### An app registers itself
 
@@ -153,13 +153,59 @@ exactly as it was loaded. What can come back:
 | `app_registration_refused` | The platform refused, and `problems` says why: a bad token, a manifest or address it will not accept, a lower version than the one running | Fix the deployment. Trying again will not help |
 | `gateway_unreachable` | The gateway could not be reached | Try again |
 
-The protocol is in `spec/registration.md` in `firetail-io/finchly`.
+The protocol is in `spec/registration.md` in `FireTail-io/finchly`.
 
 The other half of the `app` module is not built: serving the
 `/{slug}/_platform/*` endpoints, which let an administrator register an app
 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.4` |
+| `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 |
@@ -209,73 +255,6 @@ not leak them.
 The manifest check here is not the full schema. The platform runs the full
 check at registration and is the authority.
 
-## Develop
-
-```
-npm install
-npm test
-```
+## Changes
 
-`npm test` compiles with `tsc` and runs the tests in `test/` against the
-build, which is what a consumer imports.
-
-### Conformance vectors
-
-`test/conformance/` holds test vectors copied from `firetail-io/finchly`
-(`conformance/vectors/`). Both SDKs must reach the verdict each vector
-states. Do not edit them here: change them in `finchly`, regenerate, and
-copy the file to both SDK repositories. Until `finchly` publishes its
-conformance suite as an image, the copy is made by hand.
-
-## Release
-
-Each package version is semver, independent of the Python SDK and of the
-platform.
-
-1. Changes land on `main` by pull request. Each one adds a line to
-   `CHANGELOG.md` under "Unreleased".
-2. To release, set the version in `package.json`, move the changelog
-   entries under that version, merge, and tag the merge commit `vX.Y.Z`.
-3. The `release` workflow checks the tag matches `package.json`, runs the
-   tests, and publishes.
-4. A version with a pre-release part (`1.2.0-rc.1`) is published under the
-   `next` dist-tag. Anything else is published as `latest`.
-5. A bad release is deprecated with `npm deprecate` and followed by a patch
-   release. It is not unpublished.
-
-Publishing is meant to use npm trusted publishing: the workflow proves its
-identity to npm with its GitHub Actions token, so no npm token is stored,
-and npm attaches a provenance attestation.
-
-npm matches the trusted publisher against the identity GitHub issues to the
-workflow, and every field must match exactly, including case:
-
-| Field on npmjs.com   | Value         |
-| -------------------- | ------------- |
-| Organization or user | `FireTail-io` |
-| Repository           | `finchly-sdk-js` |
-| Workflow filename    | `release.yml` |
-| Environment name     | `npm`         |
-
-The organisation is `FireTail-io`, not `firetail-io`. GitHub accepts either
-spelling in a URL; npm does not, and answers "package not found" when the
-two differ. `repository.url` in `package.json` must use the same spelling.
-The workflow prints the identity it was issued, so a refusal can be compared
-with what npmjs.com holds. A trusted publisher's fields cannot be edited: to
-correct one, delete it and create another.
-
-The workflow can also be given a token, for a release that trusted
-publishing refuses:
-
-- `NPM_TOKEN`, a secret of the `npm` environment in this repository. It is
-  a granular access token that can publish `@firetail/finchly` and nothing
-  else, with a short expiry.
-- npm tries the trusted publisher first and uses the token only when that
-  is refused. Without the secret, nothing in the workflow needs to change.
-- While a token is in use, the package's "Publishing access" on npmjs.com
-  must allow a granular access token with bypass 2FA.
-- No provenance attestation is attached to a release published with the
-  token. npm also does not generate one from a private repository.
-
-Still to add: the conformance suite from `firetail-io/finchly`, run in CI on
-every change, once that suite exists.
+See `CHANGELOG.md`.

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.4",
+  "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
+    }
   }
 }