@fedify/postgres 2.4.0-pr.936.41 → 2.4.0

package/README.md

@@ -25,6 +25,15 @@ const federation = createFederation({
 });
 ~~~~
 
+`PostgresKvStore` uses a crash-safe logged table by default.  For transient
+data where losing the table contents after a PostgreSQL crash is acceptable,
+pass `{ unlogged: true }` as its second constructor argument.
+
+When a store created by an earlier version still uses an unlogged table, its
+next initialization converts that table to logged storage.  PostgreSQL rewrites
+the table and takes an `ACCESS EXCLUSIVE` lock during this one-time migration,
+so schedule the upgrade accordingly for a large or busy table.
+
 [JSR badge]: https://jsr.io/badges/@fedify/postgres
 [JSR]: https://jsr.io/@fedify/postgres
 [npm badge]: https://img.shields.io/npm/v/@fedify/postgres?logo=npm

package/dist/kv.cjs

@@ -1,13 +1,18 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("./_virtual/_rolldown/runtime.cjs");
+const require_index = require("./node_modules/.pnpm/temporal-polyfill@1.0.1/node_modules/temporal-polyfill/index.cjs");
 const require_utils = require("./utils.cjs");
+let _logtape_logtape = require("@logtape/logtape");
 //#region src/kv.ts
-const logger = (0, require("@logtape/logtape").getLogger)([
+const Temporal = require_index.Temporal;
+const logger = (0, _logtape_logtape.getLogger)([
 	"fedify",
 	"postgres",
 	"kv"
 ]);
+function quoteIdentifier(identifier) {
+	return `"${identifier.replaceAll("\"", "\"\"").replaceAll(".", "\".\"")}"`;
+}
 /**
 * A key–value store that uses PostgreSQL as the underlying storage.
 *
@@ -26,7 +31,10 @@ const logger = (0, require("@logtape/logtape").getLogger)([
 var PostgresKvStore = class {
 	#sql;
 	#tableName;
-	#initialized;
+	#unlogged;
+	#skipDdl;
+	#initialized = false;
+	#initializing;
 	#driverSerializesJson = false;
 	/**
 	* Creates a new PostgreSQL key–value store.
@@ -36,7 +44,8 @@ var PostgresKvStore = class {
 	constructor(sql, options = {}) {
 		this.#sql = sql;
 		this.#tableName = options.tableName ?? "fedify_kv_v2";
-		this.#initialized = options.initialized ?? false;
+		this.#unlogged = options.unlogged ?? false;
+		this.#skipDdl = options.initialized ?? false;
 	}
 	async #expire() {
 		await this.#sql`
@@ -56,7 +65,7 @@ var PostgresKvStore = class {
 	}
 	async set(key, value, options) {
 		await this.initialize();
-		const ttl = options?.ttl == null ? null : options.ttl.toString();
+		const ttl = options?.ttl == null ? null : Temporal.Duration.from(options.ttl).toString();
 		await this.#sql`
       INSERT INTO ${this.#sql(this.#tableName)} (key, value, ttl)
       VALUES (
@@ -65,7 +74,10 @@ var PostgresKvStore = class {
         ${ttl}
       )
       ON CONFLICT (key)
-        DO UPDATE SET value = EXCLUDED.value, ttl = EXCLUDED.ttl;
+        DO UPDATE SET
+          value = EXCLUDED.value,
+          created = CURRENT_TIMESTAMP,
+          ttl = EXCLUDED.ttl;
     `;
 		await this.#expire();
 	}
@@ -78,6 +90,54 @@ var PostgresKvStore = class {
 		await this.#expire();
 	}
 	/**
+	* {@inheritDoc KvStore.cas}
+	* @since 2.4.0
+	*/
+	async cas(key, expectedValue, newValue, options) {
+		await this.initialize();
+		const ttl = options?.ttl == null ? null : Temporal.Duration.from(options.ttl).toString();
+		if (expectedValue === void 0 && newValue === void 0) return await this.get(key) === void 0;
+		let result;
+		if (expectedValue === void 0) result = await this.#sql`
+        INSERT INTO ${this.#sql(this.#tableName)} AS existing
+          (key, value, created, ttl)
+        VALUES (
+          ${key},
+          ${this.#json(newValue)},
+          CURRENT_TIMESTAMP,
+          ${ttl}
+        )
+        ON CONFLICT (key)
+          DO UPDATE SET
+            value = EXCLUDED.value,
+            created = EXCLUDED.created,
+            ttl = EXCLUDED.ttl
+          WHERE existing.ttl IS NOT NULL
+            AND existing.created + existing.ttl <= CURRENT_TIMESTAMP
+        RETURNING key;
+      `;
+		else if (newValue === void 0) result = await this.#sql`
+        DELETE FROM ${this.#sql(this.#tableName)}
+        WHERE key = ${key}
+          AND (ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP)
+          AND value = ${this.#json(expectedValue)}
+        RETURNING key;
+      `;
+		else result = await this.#sql`
+        UPDATE ${this.#sql(this.#tableName)}
+        SET
+          value = ${this.#json(newValue)},
+          created = CURRENT_TIMESTAMP,
+          ttl = ${ttl}
+        WHERE key = ${key}
+          AND (ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP)
+          AND value = ${this.#json(expectedValue)}
+        RETURNING key;
+      `;
+		await this.#expire();
+		return result.length > 0;
+	}
+	/**
 	* {@inheritDoc KvStore.list}
 	* @since 1.10.0
 	*/
@@ -112,18 +172,46 @@ var PostgresKvStore = class {
 	*/
 	async initialize() {
 		if (this.#initialized) return;
-		logger.debug("Initializing the key–value store table {tableName}...", { tableName: this.#tableName });
-		await this.#sql`
-      CREATE UNLOGGED TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
-        key text[] PRIMARY KEY,
-        value jsonb NOT NULL,
-        created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
-        ttl interval
-      );
-    `;
-		this.#driverSerializesJson = await require_utils.driverSerializesJson(this.#sql);
-		this.#initialized = true;
-		logger.debug("Initialized the key–value store table {tableName}.", { tableName: this.#tableName });
+		this.#initializing ??= (async () => {
+			logger.debug("Initializing the key–value store table {tableName}...", { tableName: this.#tableName });
+			if (!this.#skipDdl) await this.#initializeTable();
+			this.#driverSerializesJson = await require_utils.driverSerializesJson(this.#sql);
+			this.#initialized = true;
+			logger.debug("Initialized the key–value store table {tableName}.", { tableName: this.#tableName });
+		})();
+		try {
+			await this.#initializing;
+		} catch (error) {
+			this.#initializing = void 0;
+			throw error;
+		}
+	}
+	async #initializeTable() {
+		if (this.#unlogged) await this.#sql`
+        CREATE UNLOGGED TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
+          key text[] PRIMARY KEY,
+          value jsonb NOT NULL,
+          created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+          ttl interval
+        );
+      `;
+		else {
+			await this.#sql`
+        CREATE TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
+          key text[] PRIMARY KEY,
+          value jsonb NOT NULL,
+          created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+          ttl interval
+        );
+      `;
+			if ((await this.#sql`
+        SELECT relpersistence
+        FROM pg_class
+        WHERE oid = to_regclass(${quoteIdentifier(this.#tableName)});
+      `)[0]?.relpersistence === "u") await this.#sql`
+          ALTER TABLE ${this.#sql(this.#tableName)} SET LOGGED;
+        `;
+		}
 	}
 	/**
 	* Drops the table used by the key–value store.  Does nothing if the table
@@ -133,6 +221,7 @@ var PostgresKvStore = class {
 		await this.#sql`DROP TABLE IF EXISTS ${this.#sql(this.#tableName)};`;
 	}
 	#json(value) {
+		if (value === null) return this.#sql`'null'::jsonb`;
 		if (this.#driverSerializesJson) return this.#sql.json(value);
 		return this.#sql.json(JSON.stringify(value));
 	}

package/dist/kv.d.cts

@@ -15,9 +15,20 @@ interface PostgresKvStoreOptions {
   readonly tableName?: string;
   /**
   * Whether the table has been initialized.  `false` by default.
+  *
+  * This skips only the table's schema DDL.  Driver-specific runtime setup,
+  * such as detecting whether the driver serializes JSON parameters on its
+  * own, still runs before the first key is read or written.
   * @default `false`
   */
   readonly initialized?: boolean;
+  /**
+  * Whether to use an unlogged table.  Unlogged tables are faster, but are
+  * truncated after a PostgreSQL crash and are not replicated.  `false` by
+  * default.
+  * @default `false`
+  */
+  readonly unlogged?: boolean;
 }
 /**
 * A key–value store that uses PostgreSQL as the underlying storage.
@@ -46,6 +57,11 @@ declare class PostgresKvStore implements KvStore {
   set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
   delete(key: KvKey): Promise<void>;
   /**
+  * {@inheritDoc KvStore.cas}
+  * @since 2.4.0
+  */
+  cas(key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions): Promise<boolean>;
+  /**
   * {@inheritDoc KvStore.list}
   * @since 1.10.0
   */

package/dist/kv.d.ts

@@ -15,9 +15,20 @@ interface PostgresKvStoreOptions {
   readonly tableName?: string;
   /**
   * Whether the table has been initialized.  `false` by default.
+  *
+  * This skips only the table's schema DDL.  Driver-specific runtime setup,
+  * such as detecting whether the driver serializes JSON parameters on its
+  * own, still runs before the first key is read or written.
   * @default `false`
   */
   readonly initialized?: boolean;
+  /**
+  * Whether to use an unlogged table.  Unlogged tables are faster, but are
+  * truncated after a PostgreSQL crash and are not replicated.  `false` by
+  * default.
+  * @default `false`
+  */
+  readonly unlogged?: boolean;
 }
 /**
 * A key–value store that uses PostgreSQL as the underlying storage.
@@ -46,6 +57,11 @@ declare class PostgresKvStore implements KvStore {
   set(key: KvKey, value: unknown, options?: KvStoreSetOptions | undefined): Promise<void>;
   delete(key: KvKey): Promise<void>;
   /**
+  * {@inheritDoc KvStore.cas}
+  * @since 2.4.0
+  */
+  cas(key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions): Promise<boolean>;
+  /**
   * {@inheritDoc KvStore.list}
   * @since 1.10.0
   */

package/dist/kv.js

@@ -7,6 +7,9 @@ const logger = getLogger([
 	"postgres",
 	"kv"
 ]);
+function quoteIdentifier(identifier) {
+	return `"${identifier.replaceAll("\"", "\"\"").replaceAll(".", "\".\"")}"`;
+}
 /**
 * A key–value store that uses PostgreSQL as the underlying storage.
 *
@@ -25,7 +28,10 @@ const logger = getLogger([
 var PostgresKvStore = class {
 	#sql;
 	#tableName;
-	#initialized;
+	#unlogged;
+	#skipDdl;
+	#initialized = false;
+	#initializing;
 	#driverSerializesJson = false;
 	/**
 	* Creates a new PostgreSQL key–value store.
@@ -35,7 +41,8 @@ var PostgresKvStore = class {
 	constructor(sql, options = {}) {
 		this.#sql = sql;
 		this.#tableName = options.tableName ?? "fedify_kv_v2";
-		this.#initialized = options.initialized ?? false;
+		this.#unlogged = options.unlogged ?? false;
+		this.#skipDdl = options.initialized ?? false;
 	}
 	async #expire() {
 		await this.#sql`
@@ -55,7 +62,7 @@ var PostgresKvStore = class {
 	}
 	async set(key, value, options) {
 		await this.initialize();
-		const ttl = options?.ttl == null ? null : options.ttl.toString();
+		const ttl = options?.ttl == null ? null : Temporal.Duration.from(options.ttl).toString();
 		await this.#sql`
       INSERT INTO ${this.#sql(this.#tableName)} (key, value, ttl)
       VALUES (
@@ -64,7 +71,10 @@ var PostgresKvStore = class {
         ${ttl}
       )
       ON CONFLICT (key)
-        DO UPDATE SET value = EXCLUDED.value, ttl = EXCLUDED.ttl;
+        DO UPDATE SET
+          value = EXCLUDED.value,
+          created = CURRENT_TIMESTAMP,
+          ttl = EXCLUDED.ttl;
     `;
 		await this.#expire();
 	}
@@ -77,6 +87,54 @@ var PostgresKvStore = class {
 		await this.#expire();
 	}
 	/**
+	* {@inheritDoc KvStore.cas}
+	* @since 2.4.0
+	*/
+	async cas(key, expectedValue, newValue, options) {
+		await this.initialize();
+		const ttl = options?.ttl == null ? null : Temporal.Duration.from(options.ttl).toString();
+		if (expectedValue === void 0 && newValue === void 0) return await this.get(key) === void 0;
+		let result;
+		if (expectedValue === void 0) result = await this.#sql`
+        INSERT INTO ${this.#sql(this.#tableName)} AS existing
+          (key, value, created, ttl)
+        VALUES (
+          ${key},
+          ${this.#json(newValue)},
+          CURRENT_TIMESTAMP,
+          ${ttl}
+        )
+        ON CONFLICT (key)
+          DO UPDATE SET
+            value = EXCLUDED.value,
+            created = EXCLUDED.created,
+            ttl = EXCLUDED.ttl
+          WHERE existing.ttl IS NOT NULL
+            AND existing.created + existing.ttl <= CURRENT_TIMESTAMP
+        RETURNING key;
+      `;
+		else if (newValue === void 0) result = await this.#sql`
+        DELETE FROM ${this.#sql(this.#tableName)}
+        WHERE key = ${key}
+          AND (ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP)
+          AND value = ${this.#json(expectedValue)}
+        RETURNING key;
+      `;
+		else result = await this.#sql`
+        UPDATE ${this.#sql(this.#tableName)}
+        SET
+          value = ${this.#json(newValue)},
+          created = CURRENT_TIMESTAMP,
+          ttl = ${ttl}
+        WHERE key = ${key}
+          AND (ttl IS NULL OR created + ttl > CURRENT_TIMESTAMP)
+          AND value = ${this.#json(expectedValue)}
+        RETURNING key;
+      `;
+		await this.#expire();
+		return result.length > 0;
+	}
+	/**
 	* {@inheritDoc KvStore.list}
 	* @since 1.10.0
 	*/
@@ -111,18 +169,46 @@ var PostgresKvStore = class {
 	*/
 	async initialize() {
 		if (this.#initialized) return;
-		logger.debug("Initializing the key–value store table {tableName}...", { tableName: this.#tableName });
-		await this.#sql`
-      CREATE UNLOGGED TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
-        key text[] PRIMARY KEY,
-        value jsonb NOT NULL,
-        created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
-        ttl interval
-      );
-    `;
-		this.#driverSerializesJson = await driverSerializesJson(this.#sql);
-		this.#initialized = true;
-		logger.debug("Initialized the key–value store table {tableName}.", { tableName: this.#tableName });
+		this.#initializing ??= (async () => {
+			logger.debug("Initializing the key–value store table {tableName}...", { tableName: this.#tableName });
+			if (!this.#skipDdl) await this.#initializeTable();
+			this.#driverSerializesJson = await driverSerializesJson(this.#sql);
+			this.#initialized = true;
+			logger.debug("Initialized the key–value store table {tableName}.", { tableName: this.#tableName });
+		})();
+		try {
+			await this.#initializing;
+		} catch (error) {
+			this.#initializing = void 0;
+			throw error;
+		}
+	}
+	async #initializeTable() {
+		if (this.#unlogged) await this.#sql`
+        CREATE UNLOGGED TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
+          key text[] PRIMARY KEY,
+          value jsonb NOT NULL,
+          created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+          ttl interval
+        );
+      `;
+		else {
+			await this.#sql`
+        CREATE TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
+          key text[] PRIMARY KEY,
+          value jsonb NOT NULL,
+          created timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+          ttl interval
+        );
+      `;
+			if ((await this.#sql`
+        SELECT relpersistence
+        FROM pg_class
+        WHERE oid = to_regclass(${quoteIdentifier(this.#tableName)});
+      `)[0]?.relpersistence === "u") await this.#sql`
+          ALTER TABLE ${this.#sql(this.#tableName)} SET LOGGED;
+        `;
+		}
 	}
 	/**
 	* Drops the table used by the key–value store.  Does nothing if the table
@@ -132,6 +218,7 @@ var PostgresKvStore = class {
 		await this.#sql`DROP TABLE IF EXISTS ${this.#sql(this.#tableName)};`;
 	}
 	#json(value) {
+		if (value === null) return this.#sql`'null'::jsonb`;
 		if (this.#driverSerializesJson) return this.#sql.json(value);
 		return this.#sql.json(JSON.stringify(value));
 	}

package/dist/mq.cjs

@@ -1,8 +1,8 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_runtime = require("./_virtual/_rolldown/runtime.cjs");
-const require_utils = require("./utils.cjs");
 const require_index = require("./node_modules/.pnpm/temporal-polyfill@1.0.1/node_modules/temporal-polyfill/index.cjs");
+const require_utils = require("./utils.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 let postgres = require("postgres");
 postgres = require_runtime.__toESM(postgres, 1);
@@ -57,12 +57,14 @@ function getCreatedIndexName(tableName) {
 * ```
 */
 var PostgresMessageQueue = class {
+	atomicEnqueueMany = false;
 	#sql;
 	#tableName;
 	#channelName;
 	#pollIntervalMs;
 	#handlerTimeoutMs;
-	#initialized;
+	#skipDdl;
+	#initialized = false;
 	#initPromise;
 	#driverSerializesJson = false;
 	constructor(sql, options = {}) {
@@ -71,7 +73,7 @@ var PostgresMessageQueue = class {
 		this.#channelName = options?.channelName ?? "fedify_channel";
 		this.#pollIntervalMs = Temporal.Duration.from(options?.pollInterval ?? { seconds: 5 }).total("millisecond");
 		this.#handlerTimeoutMs = Temporal.Duration.from(options?.handlerTimeout ?? { seconds: 60 }).total("millisecond");
-		this.#initialized = options?.initialized ?? false;
+		this.#skipDdl = options?.initialized ?? false;
 	}
 	async enqueue(message, options) {
 		await this.initialize();
@@ -159,6 +161,7 @@ var PostgresMessageQueue = class {
 	async listen(handler, options = {}) {
 		await this.initialize();
 		const { signal } = options;
+		if (signal?.aborted) return;
 		const poll = async () => {
 			while (!signal?.aborted) {
 				let processed = false;
@@ -252,6 +255,7 @@ var PostgresMessageQueue = class {
 		};
 		const timeouts = /* @__PURE__ */ new Set();
 		const listen = await this.#sql.listen(this.#channelName, async (delay) => {
+			if (signal?.aborted) return;
 			try {
 				const durationMs = Temporal.Duration.from(delay).total("millisecond");
 				if (durationMs < 1) await safeSerializedPoll("notify-immediate");
@@ -275,31 +279,35 @@ var PostgresMessageQueue = class {
 			timeouts.clear();
 		};
 		signal?.addEventListener("abort", clearTimeouts, { once: true });
-		let unlistenError;
 		try {
 			while (!signal?.aborted) {
-				let timeout;
 				await new Promise((resolve) => {
-					signal?.addEventListener("abort", resolve, { once: true });
-					timeout = setTimeout(() => {
-						signal?.removeEventListener("abort", resolve);
-						resolve(0);
+					const onAbort = () => {
+						clearTimeout(timeout);
+						signal?.removeEventListener("abort", onAbort);
+						resolve();
+					};
+					const timeout = setTimeout(() => {
+						signal?.removeEventListener("abort", onAbort);
+						resolve();
 					}, this.#pollIntervalMs);
-					timeouts.add(timeout);
+					signal?.addEventListener("abort", onAbort, { once: true });
 				});
-				if (timeout != null) timeouts.delete(timeout);
 				await safeSerializedPoll("interval");
 			}
 		} finally {
 			signal?.removeEventListener("abort", clearTimeouts);
 			clearTimeouts();
+			await pollLock;
 			try {
 				await listen.unlisten();
 			} catch (error) {
-				if (!isConnectionDestroyedError(error)) unlistenError = error;
+				if (!isConnectionDestroyedError(error)) logger.error("Error while unlistening from channel {channelName}: {error}", {
+					channelName: this.#channelName,
+					error
+				});
 			}
 		}
-		if (unlistenError != null) throw unlistenError;
 	}
 	/**
 	* Initializes the message queue table if it does not already exist.
@@ -310,6 +318,12 @@ var PostgresMessageQueue = class {
 	}
 	async #doInitialize() {
 		logger.debug("Initializing the message queue table {tableName}...", { tableName: this.#tableName });
+		if (!this.#skipDdl) await this.#initializeTable();
+		this.#driverSerializesJson = await require_utils.driverSerializesJson(this.#sql);
+		this.#initialized = true;
+		logger.debug("Initialized the message queue table {tableName}.", { tableName: this.#tableName });
+	}
+	async #initializeTable() {
 		for (let attempt = 1; attempt <= INITIALIZE_MAX_ATTEMPTS; attempt++) try {
 			await this.#sql`
       CREATE TABLE IF NOT EXISTS ${this.#sql(this.#tableName)} (
@@ -344,9 +358,6 @@ var PostgresMessageQueue = class {
 			});
 			await sleep(backoffMs);
 		}
-		this.#driverSerializesJson = await require_utils.driverSerializesJson(this.#sql);
-		this.#initialized = true;
-		logger.debug("Initialized the message queue table {tableName}.", { tableName: this.#tableName });
 	}
 	/**
 	* Drops the message queue table if it exists.

package/dist/mq.d.cts

@@ -21,6 +21,10 @@ interface PostgresMessageQueueOptions {
   readonly channelName?: string;
   /**
   * Whether the table has been initialized.  `false` by default.
+  *
+  * This skips only the table's schema DDL.  Driver-specific runtime setup,
+  * such as detecting whether the driver serializes JSON parameters on its
+  * own, still runs before the first message is enqueued.
   * @default `false`
   */
   readonly initialized?: boolean;
@@ -62,6 +66,7 @@ interface PostgresMessageQueueOptions {
 */
 declare class PostgresMessageQueue implements MessageQueue {
   #private;
+  readonly atomicEnqueueMany = false;
   constructor(sql: Sql<{}>, options?: PostgresMessageQueueOptions);
   enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
   enqueueMany(messages: readonly any[], options?: MessageQueueEnqueueOptions): Promise<void>;

package/dist/mq.d.ts

@@ -21,6 +21,10 @@ interface PostgresMessageQueueOptions {
   readonly channelName?: string;
   /**
   * Whether the table has been initialized.  `false` by default.
+  *
+  * This skips only the table's schema DDL.  Driver-specific runtime setup,
+  * such as detecting whether the driver serializes JSON parameters on its
+  * own, still runs before the first message is enqueued.
   * @default `false`
   */
   readonly initialized?: boolean;
@@ -62,6 +66,7 @@ interface PostgresMessageQueueOptions {
 */
 declare class PostgresMessageQueue implements MessageQueue {
   #private;
+  readonly atomicEnqueueMany = false;
   constructor(sql: Sql<{}>, options?: PostgresMessageQueueOptions);
   enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
   enqueueMany(messages: readonly any[], options?: MessageQueueEnqueueOptions): Promise<void>;