@coffre/db 0.12.1 → 0.14.0

package/dist/dialect.d.ts

@@ -56,9 +56,27 @@ export declare function isUniqueViolation(error: unknown): boolean;
 /**
  * Whether a query failed because the database could not be reached or
  * dropped the connection: an outage, not an answer. Postgres's connection
- * exceptions are class 08; pg and Workers' sockets say so in words.
+ * exceptions are class 08; pg and Workers' sockets say so in words, and so
+ * does Hyperdrive when it has no connection to the database to give: every
+ * one of its pool busy for 15 s ("Timed out while waiting for an open slot
+ * in the pool", FATAL 58000; "Failed to acquire a connection from the
+ * pool"), or none to be made ("Server connection attempt failed:
+ * destination_unavailable").
  */
 export declare function isUnreachable(error: unknown): boolean;
+/**
+ * Whether a statement gave up waiting, on a lock or past its bound: the
+ * database too busy to answer in time, or a transaction held too long,
+ * which a bug may be (one held across a vault call waits on the vault's
+ * decision, which waits on it).
+ */
+export declare function gaveUp(error: unknown): boolean;
+/**
+ * Whether a query failed for want of the database, not for anything the
+ * request asked: it could not be reached (`isUnreachable`), or a statement
+ * gave up waiting (`gaveUp`). The same request may well succeed in a moment.
+ */
+export declare function isUnavailable(error: unknown): boolean;
 /**
  * A consistent read of several statements that cannot write, such as
  * verifying the chain. SQLite ignores it: its transactions already see one

package/dist/dialect.js

@@ -73,7 +73,7 @@ function isUniqueViolation(error) {
 	}
 	return false;
 }
-/** The network's codes for a server that is not there, and Postgres's for one that will not take the connection. */
+/** The network's codes for a server that is not there, and Postgres's for one that will not take the connection, or has none left (53300). */
 const UNREACHABLE = /* @__PURE__ */ new Set([
 	"ECONNREFUSED",
 	"ECONNRESET",
@@ -83,24 +83,52 @@ const UNREACHABLE = /* @__PURE__ */ new Set([
 	"EHOSTUNREACH",
 	"ENETUNREACH",
 	"EPIPE",
+	"53300",
 	"57P01",
 	"57P02",
 	"57P03"
 ]);
+/** Hyperdrive's words for having no connection to give, beside pg's and Workers' for one lost. */
+const UNREACHABLE_WORDS = /connection terminated|network connection lost|connect(ion)? timeout|open slot in the pool|acquire a connection from the pool|server connection attempt failed/i;
 /**
 * Whether a query failed because the database could not be reached or
 * dropped the connection: an outage, not an answer. Postgres's connection
-* exceptions are class 08; pg and Workers' sockets say so in words.
+* exceptions are class 08; pg and Workers' sockets say so in words, and so
+* does Hyperdrive when it has no connection to the database to give: every
+* one of its pool busy for 15 s ("Timed out while waiting for an open slot
+* in the pool", FATAL 58000; "Failed to acquire a connection from the
+* pool"), or none to be made ("Server connection attempt failed:
+* destination_unavailable").
 */
 function isUnreachable(error) {
 	for (let cause = error; typeof cause === "object" && cause !== null;) {
 		const { code, message } = cause;
-		if (typeof code === "string" && (UNREACHABLE.has(code) || /^08[0-9A-Z]{3}$/.test(code))) return true;
-		if (typeof message === "string" && /connection terminated|network connection lost|connect(ion)? timeout/i.test(message)) return true;
+		if (typeof code === "string" && (UNREACHABLE.has(code) || /^08[0-9A-Z]{3}$/.test(code) && code !== "08P01")) return true;
+		if (typeof message === "string" && (typeof code !== "string" || code === "58000") && !message.includes("Failed query: ") && UNREACHABLE_WORDS.test(message)) return true;
 		cause = cause.cause;
 	}
 	return false;
 }
+/** Postgres's codes for a statement that gave up waiting: on a lock (55P03), or past its own bound (57014). */
+const GAVE_UP = /* @__PURE__ */ new Set(["55P03", "57014"]);
+/**
+* Whether a statement gave up waiting, on a lock or past its bound: the
+* database too busy to answer in time, or a transaction held too long,
+* which a bug may be (one held across a vault call waits on the vault's
+* decision, which waits on it).
+*/
+function gaveUp(error) {
+	for (let cause = error; typeof cause === "object" && cause !== null; cause = cause.cause) if (GAVE_UP.has(cause.code)) return true;
+	return false;
+}
+/**
+* Whether a query failed for want of the database, not for anything the
+* request asked: it could not be reached (`isUnreachable`), or a statement
+* gave up waiting (`gaveUp`). The same request may well succeed in a moment.
+*/
+function isUnavailable(error) {
+	return isUnreachable(error) || gaveUp(error);
+}
 /**
 * A consistent read of several statements that cannot write, such as
 * verifying the chain. SQLite ignores it: its transactions already see one
@@ -178,4 +206,4 @@ function canonicalTimestamp(raw) {
 	return `${(/* @__PURE__ */ new Date(Date.UTC(+year, +month - 1, +day, +hour, +minute, +second) - offsetMinutes * 6e4)).toISOString().slice(0, 19)}.${fraction.padEnd(6, "0")}Z`;
 }
 //#endregion
-export { SNAPSHOT, ahead, canonicalTimestamp, changedRows, clock, clockMillis, engineOf, forUpdate, insertIfAbsent, isUniqueViolation, isUnreachable, migrationLedger, rowsOf, tombstone, truth, upsert };
+export { SNAPSHOT, ahead, canonicalTimestamp, changedRows, clock, clockMillis, engineOf, forUpdate, gaveUp, insertIfAbsent, isUnavailable, isUniqueViolation, isUnreachable, migrationLedger, rowsOf, tombstone, truth, upsert };

package/dist/log.d.ts

@@ -11,7 +11,8 @@ import { LogKey, StoredEntry } from "@coffre/core/audit";
  * from any process take their numbers in one order. It then reads the
  * database clock, after the lock, and the log's last entry, which the head
  * must name: a head that does not was moved, or entries were deleted behind
- * it, and the append refuses.
+ * it, and the append refuses. The same statement says whether the log has
+ * moved on from the key it appends under (`KeyRetired`).
  *
  * This is deliberately not a queue and not best-effort: the entries go in
  * the caller's transaction, so if the append fails, what it records does
@@ -55,6 +56,21 @@ export declare class LogHeadMismatch extends Error {
 export declare class LogRewound extends Error {
   constructor(message: string);
 }
+/**
+ * An append under a key the log has moved on from: an entry of its
+ * author's, `key.reseal` or `key.rotate`, names it as the key it moves
+ * from (`MOVES_FROM`), and a key moved from writes no more.
+ */
+export declare class KeyRetired extends Error {
+  constructor(message: string);
+}
+/**
+ * The actions by which an author moves to a new key, each under the new one
+ * and naming the key it moves from as its subject: from the first, that key
+ * writes no more (`KeyRetired`). The app's key rotation writes them
+ * (packages/server/src/key-rotation.ts).
+ */
+export declare const MOVES_FROM: readonly ["key.reseal", "key.rotate"];
 /**
  * Forget every head written so far. For tests that empty the database
  * between cases, which is exactly what the check above refuses.
@@ -69,6 +85,13 @@ export declare function lockLogHead(tx: Transaction): Promise<{
   nextSeq: bigint;
   headHash: Buffer;
 }>;
+/**
+ * Lock the log's head if no one holds it, without waiting: whether it is
+ * held now. For work any caller may do, of which one at a time is enough,
+ * which a request that finds the head taken leaves to the one that has it.
+ * SQLite's transactions hold the whole file, so the head is always free.
+ */
+export declare function lockLogHeadIfFree(tx: Transaction): Promise<boolean>;
 /**
  * Append `entries` under `key`. `check`, when given, runs once the head is
  * locked and before anything is written: a writer's own condition on the

package/dist/log.js

@@ -23,6 +23,24 @@ var LogRewound = class extends Error {
 	}
 };
 /**
+* An append under a key the log has moved on from: an entry of its
+* author's, `key.reseal` or `key.rotate`, names it as the key it moves
+* from (`MOVES_FROM`), and a key moved from writes no more.
+*/
+var KeyRetired = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "KeyRetired";
+	}
+};
+/**
+* The actions by which an author moves to a new key, each under the new one
+* and naming the key it moves from as its subject: from the first, that key
+* writes no more (`KeyRetired`). The app's key rotation writes them
+* (packages/server/src/key-rotation.ts).
+*/
+const MOVES_FROM = ["key.reseal", "key.rotate"];
+/**
 * The newest head each writer has written, under each of its keys, while
 * the process lives. A head is remembered only once the transaction that
 * wrote it has committed, all the way out (commits.ts): one that rolls back
@@ -47,6 +65,14 @@ function forgetLogHeads() {
 	epoch += 1;
 }
 /**
+* The transactions that hold the head: an append in one reads what it
+* needs under the lock in one statement, where one that does not first
+* takes the lock in another. A savepoint's transaction is another to this
+* set, so a lock is marked on the object that took it, and an append made
+* through another object locks again, which is free.
+*/
+const holding = /* @__PURE__ */ new WeakSet();
+/**
 * Lock the log's head, and read it. A transaction that appends takes this
 * before any other row, so the lock order is the same everywhere; taking it
 * again in the same transaction is free.
@@ -54,8 +80,25 @@ function forgetLogHeads() {
 async function lockLogHead(tx) {
 	const [head] = await lockedHead(tx);
 	if (head === void 0) throw new Error("audit_chain_head is missing; refusing to write an unchained entry");
+	holding.add(tx);
 	return head;
 }
+/**
+* Lock the log's head if no one holds it, without waiting: whether it is
+* held now. For work any caller may do, of which one at a time is enough,
+* which a request that finds the head taken leaves to the one that has it.
+* SQLite's transactions hold the whole file, so the head is always free.
+*/
+async function lockLogHeadIfFree(tx) {
+	if (engineOf(tx) === "sqlite") {
+		const held = (await lockedHead(tx)).length > 0;
+		if (held) holding.add(tx);
+		return held;
+	}
+	const { rows } = await tx.execute(sql`SELECT next_seq FROM audit_chain_head WHERE only_row FOR UPDATE SKIP LOCKED`);
+	if (rows.length > 0) holding.add(tx);
+	return rows.length > 0;
+}
 const lockedHead = prepared((db) => {
 	const { auditChainHead } = tablesOf(db);
 	return forUpdate(db, db.select({
@@ -72,10 +115,11 @@ const lockedHead = prepared((db) => {
 async function appendEntries(tx, key, entries, check, locked) {
 	if (entries.length === 0) throw new Error("appendEntries called with no entries");
 	const { auditChainHead, auditLog } = tablesOf(tx);
-	const head = locked?.head ?? await lockLogHead(tx);
+	if (locked === void 0 && !holding.has(tx)) await lockLogHead(tx);
 	await check?.(tx);
-	const now = locked?.at ?? (await clockNow(tx))[0].now;
-	const last = locked === void 0 ? (await lastEntry(tx))[0] : locked.last ?? void 0;
+	const held = locked ?? await readUnderHead(tx, key);
+	const { head, at: now } = held;
+	const last = held.last ?? void 0;
 	const expected = last === void 0 ? {
 		nextSeq: 0n,
 		headHash: GENESIS_HASH
@@ -140,15 +184,53 @@ async function appendEntries(tx, key, entries, check, locked) {
 		occurredAt: now
 	};
 }
+/**
+* What an append reads under the head its transaction holds, in one
+* statement: the head, the clock and the log's last entry, all as of the
+* lock, since locking a head the transaction holds waits for nothing, and
+* after the append's `check`. The log's own last row says whether the log
+* has moved on from `key`.
+*/
+async function readUnderHead(tx, key) {
+	const [read] = await underHead(tx, {
+		author: key.author,
+		keyId: key.keyId
+	});
+	if (read === void 0) throw new Error("audit_chain_head is missing; refusing to write an unchained entry");
+	if (read.retired) throw new KeyRetired(`the log moved on from ${key.keyId}: a key the ${key.author} rotated from writes no more`);
+	return {
+		head: {
+			nextSeq: read.nextSeq,
+			headHash: read.headHash
+		},
+		last: read.lastSeq === null || read.lastHash === null ? null : {
+			seq: read.lastSeq,
+			hash: read.lastHash
+		},
+		at: read.now
+	};
+}
 /** Entries one statement inserts at most, at 21 parameters each: Postgres takes 65,535. */
 const ROWS_AT_ONCE = 3e3;
-const clockNow = prepared((db) => db.select({ now: clockMillis(db) }).from(tablesOf(db).auditChainHead));
-const lastEntry = prepared((db) => {
-	const { auditLog } = tablesOf(db);
-	return db.select({
-		seq: auditLog.seq,
-		hash: auditLog.hash
-	}).from(auditLog).orderBy(desc(auditLog.seq)).limit(1);
+/**
+* `readUnderHead`'s statement. Its `FOR UPDATE` waits for nothing in a
+* transaction that holds the head, and stays for one that would not: there
+* it waits, and if an append committed meanwhile, its head, read again
+* after the wait, disagrees with the last entry its snapshot saw before it,
+* so the append refuses (`LogHeadMismatch`) rather than writing unlocked.
+*/
+const underHead = prepared((db) => {
+	const { auditChainHead, auditLog } = tablesOf(db);
+	const moved = sql.raw(MOVES_FROM.map((action) => `'${action}'`).join(", "));
+	const newest = (column) => sql`(SELECT ${column} FROM audit_log ORDER BY seq DESC LIMIT 1)`;
+	return forUpdate(db, db.select({
+		nextSeq: auditChainHead.nextSeq,
+		headHash: auditChainHead.headHash,
+		now: clockMillis(db),
+		lastSeq: newest(sql`seq`).mapWith(auditLog.seq),
+		lastHash: newest(sql`hash`).mapWith(auditLog.hash),
+		retired: sql`EXISTS (SELECT 1 FROM audit_log moved WHERE moved.author = ${sql.placeholder("author")} AND moved.subject_principal = ${sql.placeholder("keyId")} AND moved.action IN (${moved}))`
+	}).from(auditChainHead).where(eq(auditChainHead.onlyRow, true)));
 });
 /** An entry's columns, as the chain's codec reads them (`StoredEntry`). */
 function entryColumns(db) {
@@ -306,4 +388,4 @@ async function newestAuthentic(page, check) {
 	return "unreached";
 }
 //#endregion
-export { BATCH_BYTES, LOOK_BACK, LogHeadMismatch, LogRewound, appendEntries, entryColumns, forgetLogHeads, lockLogHead, missingEntry, newestAuthentic, newestSeqQuery, newestVaultEntries, newestVaultSeq, withinBytes };
+export { BATCH_BYTES, KeyRetired, LOOK_BACK, LogHeadMismatch, LogRewound, MOVES_FROM, appendEntries, entryColumns, forgetLogHeads, lockLogHead, lockLogHeadIfFree, missingEntry, newestAuthentic, newestSeqQuery, newestVaultEntries, newestVaultSeq, withinBytes };

package/dist/migrations/postgres/0018_rotate_app_key.sql

@@ -0,0 +1,2 @@
+-- The app key's rotation (T105) signs every enrollment code again under the new key, as it does every other signed row. It only adds a grant: the release before writes no enrollment's MAC but at its insert.
+GRANT UPDATE (auth_mac) ON enrollments TO coffre_app;