@kubun/store-engine 0.17.0 → 0.18.0

package/lib/api.d.ts

@@ -1,12 +1,43 @@
 import type { Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
 import type { EngineStoreTables } from './tables.js';
+/**
+ * How long past its expiry a replay entry is kept before a purge may drop it.
+ * The replay check refuses a message as stale only once the clock passes its
+ * expiry, so dropping the row at the boundary would reopen a window as wide as
+ * any clock disagreement between the check and the purge; this margin closes it.
+ */
+export declare const REPLAY_ENTRY_PURGE_GRACE_MS = 60000;
+export type RecordReplayEntryParams = {
+    /** The replay check's dedup key, `<normalized issuer>:<jti or signature>`. */
+    key: string;
+    /** Epoch milliseconds after which the message is stale and the entry may go. */
+    expiresAt: number;
+};
 export type EngineStoreAPI = {
     get(key: string): Promise<unknown | null>;
     setIfAbsent(key: string, value: unknown): Promise<{
         written: boolean;
         current: unknown;
     }>;
+    setIfEqual(key: string, expected: unknown, value: unknown): Promise<boolean>;
     set(key: string, value: unknown): Promise<void>;
+    /**
+     * Record a replay `key` unless an entry already holds it. Returns `true` when
+     * the message is fresh (recorded now), `false` when it is a replay.
+     *
+     * One statement, so two concurrent checks of the same message cannot both see
+     * it as fresh. A present row always refuses, expired or not: a `jti` is
+     * random and never legitimately reused, and an expired message is refused as
+     * stale before it reaches here anyway.
+     */
+    recordReplayEntry(params: RecordReplayEntryParams): Promise<boolean>;
+    /** Seed a bounded memory ledger, retaining the same expiry grace as purging. */
+    listReplayEntries(now: number, limit: number): Promise<Array<RecordReplayEntryParams>>;
+    /**
+     * Delete every replay entry that expired more than
+     * {@link REPLAY_ENTRY_PURGE_GRACE_MS} before `now`. Returns how many went.
+     */
+    purgeExpiredReplayEntries(now: number): Promise<number>;
 };
 export declare function createEngineStore(db: Kysely<EngineStoreTables>, adapter: Adapter): EngineStoreAPI;

package/lib/api.js

@@ -1,13 +1,21 @@
-// ParseJSONResultsPlugin usually parses the JSON column back to an object, but a
-// value can still arrive as a string (adapter/driver dependent). Handle both.
-function decodeValue(value) {
-    return typeof value === 'string' ? JSON.parse(value) : value;
+import { AbstractSQLiteAdapter } from '@kubun/db-adapter';
+/**
+ * How long past its expiry a replay entry is kept before a purge may drop it.
+ * The replay check refuses a message as stale only once the clock passes its
+ * expiry, so dropping the row at the boundary would reopen a window as wide as
+ * any clock disagreement between the check and the purge; this margin closes it.
+ */ export const REPLAY_ENTRY_PURGE_GRACE_MS = 60_000;
+// SQLite's encodeJSON writes JSON text; ParseJSONResultsPlugin already decodes
+// object and array text, but leaves JSON string scalars to us. Postgres writes
+// the value directly to jsonb and returns it decoded, including string scalars.
+function decodeValue(value, adapter) {
+    return adapter instanceof AbstractSQLiteAdapter && typeof value === 'string' ? JSON.parse(value) : value;
 }
 export function createEngineStore(db, adapter) {
     const api = {
         async get (key) {
             const row = await db.selectFrom('kubun_engine_metadata').select('value').where('key', '=', key).executeTakeFirst();
-            return row == null ? null : decodeValue(row.value);
+            return row == null ? null : decodeValue(row.value, adapter);
         },
         // `ON CONFLICT DO NOTHING` + read-back is the CAS: the insert is atomic per
         // connection under SQLite's write lock and Postgres's row lock, so whichever
@@ -28,9 +36,15 @@ export function createEngineStore(db, adapter) {
             const row = await db.selectFrom('kubun_engine_metadata').select('value').where('key', '=', key).executeTakeFirstOrThrow();
             return {
                 written: false,
-                current: decodeValue(row.value)
+                current: decodeValue(row.value, adapter)
             };
         },
+        async setIfEqual (key, expected, value) {
+            const result = await db.updateTable('kubun_engine_metadata').set({
+                value: adapter.encodeJSON(value)
+            }).where('key', '=', key).where('value', '=', adapter.encodeJSON(expected)).executeTakeFirst();
+            return result.numUpdatedRows > 0n;
+        },
         async set (key, value) {
             const encoded = adapter.encodeJSON(value);
             await db.insertInto('kubun_engine_metadata').values({
@@ -39,6 +53,27 @@ export function createEngineStore(db, adapter) {
             }).onConflict((oc)=>oc.column('key').doUpdateSet((eb)=>({
                         value: eb.ref('excluded.value')
                     }))).execute();
+        },
+        async recordReplayEntry (params) {
+            const row = await db.insertInto('kubun_engine_replay_entries').values({
+                key: params.key,
+                expires_at: params.expiresAt
+            }).onConflict((oc)=>oc.column('key').doNothing()).returning('key').executeTakeFirst();
+            return row != null;
+        },
+        async listReplayEntries (now, limit) {
+            const rows = await db.selectFrom('kubun_engine_replay_entries').select([
+                'key',
+                'expires_at'
+            ]).where('expires_at', '>=', now - REPLAY_ENTRY_PURGE_GRACE_MS).limit(limit).execute();
+            return rows.map((row)=>({
+                    key: row.key,
+                    expiresAt: Number(row.expires_at)
+                }));
+        },
+        async purgeExpiredReplayEntries (now) {
+            const result = await db.deleteFrom('kubun_engine_replay_entries').where('expires_at', '<', now - REPLAY_ENTRY_PURGE_GRACE_MS).executeTakeFirst();
+            return Number(result.numDeletedRows);
         }
     };
     return api;

package/lib/index.d.ts

@@ -1,8 +1,8 @@
 import type { StoreProvider } from '@kubun/db';
 import type { EngineStoreAPI } from './api.js';
-export type { EngineStoreAPI } from './api.js';
-export { createEngineStore } from './api.js';
+export type { EngineStoreAPI, RecordReplayEntryParams } from './api.js';
+export { createEngineStore, REPLAY_ENTRY_PURGE_GRACE_MS } from './api.js';
 export { engineStoreDefinition } from './definition.js';
 export declare const ENGINE_STORE: "engine";
 export declare function getEngineStore(provider: StoreProvider): Promise<EngineStoreAPI>;
-export type { EngineMetadataRow, EngineMetadataTable, EngineStoreTables, InsertEngineMetadata, } from './tables.js';
+export type { EngineMetadataRow, EngineMetadataTable, EngineStoreTables, InsertEngineMetadata, ReplayEntryTable, } from './tables.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { createEngineStore } from './api.js';
+export { createEngineStore, REPLAY_ENTRY_PURGE_GRACE_MS } from './api.js';
 export { engineStoreDefinition } from './definition.js';
 export const ENGINE_STORE = 'engine';
 export function getEngineStore(provider) {

package/lib/migrations.js

@@ -6,8 +6,15 @@ export function getEngineMigrations(ctx) {
             await db.schema.createTable('kubun_engine_metadata').ifNotExists().addColumn('key', t.text, (col)=>col.notNull()).addColumn('value', t.json, (col)=>col.notNull()).addPrimaryKeyConstraint('pk_engine_metadata', [
                 'key'
             ]).execute();
+            // Signed messages already accepted, keyed on the replay check's own
+            // `<issuer>:<jti or signature>` key. Lives in the database so a message
+            // replayed across a restart is still refused inside its freshness
+            // window. Indexed on expiry for the purge.
+            await db.schema.createTable('kubun_engine_replay_entries').ifNotExists().addColumn('key', t.text, (col)=>col.notNull().primaryKey()).addColumn('expires_at', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createIndex('idx_engine_replay_entries_expires').ifNotExists().on('kubun_engine_replay_entries').column('expires_at').execute();
         },
         async down (db) {
+            await db.schema.dropTable('kubun_engine_replay_entries').ifExists().execute();
             await db.schema.dropTable('kubun_engine_metadata').ifExists().execute();
         }
     };

package/lib/tables.d.ts

@@ -6,7 +6,12 @@ export type EngineMetadataTable = {
 };
 export type EngineMetadataRow = Selectable<EngineMetadataTable>;
 export type InsertEngineMetadata = Insertable<EngineMetadataTable>;
+export type ReplayEntryTable = {
+    key: string;
+    expires_at: number;
+};
 export type EngineStoreTables = {
     kubun_engine_metadata: EngineMetadataTable;
+    kubun_engine_replay_entries: ReplayEntryTable;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-engine",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,14 +15,14 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/db": "^0.17.0",
-    "@kubun/db-adapter": "^0.17.0",
-    "kysely": "^0.29.5"
+    "@kubun/db": "^0.18.0",
+    "@kubun/db-adapter": "^0.18.0",
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/db-postgres": "^0.17.0",
-    "@testcontainers/postgresql": "^12.1.0"
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/db-postgres": "^0.18.0",
+    "@testcontainers/postgresql": "^12.2.1"
   },
   "publishConfig": {
     "access": "public"