@kumiai/hub-store 0.10.1 → 0.12.0

package/README.md

@@ -10,8 +10,8 @@ server with a custom transport or when you need the store API separately.
 
 - `createHubStoreDefinition(options?)` -- the Hozon `StoreDefinition`, named `'kumiai-hub'`
   (`HUB_STORE`).
-- `getHubStore(provider)` -- the `HubStore` from a `HozonDB` or any Hozon `StoreProvider`.
-- `HubStoreOptions`.
+- `getHubStore(provider)` -- the `SQLHubStore` from a `HozonDB` or any Hozon `StoreProvider`.
+- `HubStoreOptions`, `HubSubscriptionReaper`, and `SQLHubStore` (`HubStore & HubSubscriptionReaper`).
 
 ```ts
 import { HozonDB } from '@hozon/db'
@@ -28,13 +28,13 @@ definition. Close the `HozonDB` when the host shuts down.
 
 ## Options
 
-| Option | Default | Meaning |
-|--------|---------|---------|
-| `defaultRetention` | `0` | Floor, in seconds, on how long a topic's frames are kept. |
-| `maxRetention` | `2592000` (30 days) | Ceiling, in seconds, a subscribe may request. Above it the subscribe is refused. |
-| `maxDepth` | `1000` | Retained log frames per topic. The oldest log frames are evicted first. |
-| `maxKeyPackagesPerDID` | `100` | Ordinary key packages one DID may hold. An upload past it is refused. |
-| `maxSubscriptionsPerDID` | `1000` | Distinct topics one DID may subscribe to. |
+| Option                   | Default             | Meaning                                                                          |
+| ------------------------ | ------------------- | -------------------------------------------------------------------------------- |
+| `defaultRetention`       | `0`                 | Floor, in seconds, on how long a topic's frames are kept.                        |
+| `maxRetention`           | `2592000` (30 days) | Ceiling, in seconds, a subscribe may request. Above it the subscribe is refused. |
+| `maxDepth`               | `1000`              | Retained log frames per topic. The oldest log frames are evicted first.          |
+| `maxKeyPackagesPerDID`   | `100`               | Ordinary key packages one DID may hold. An upload past it is refused.            |
+| `maxSubscriptionsPerDID` | `1000`              | Distinct topics one DID may subscribe to.                                        |
 
 Set `maxRetention` or `maxDepth` to `Infinity` to disable that bound explicitly.
 These defaults match the memory store. Periodic purge applies the age policy.
@@ -49,3 +49,10 @@ head advance in one transaction. The head advance is a conditional write, so two
 one Postgres database cannot both accept a publish at the same head.
 
 Concurrent retries of one publish ID wait for the accepting transaction and return its sequence ID with `deduped: true`.
+
+## Subscription reaping
+
+`store.purgeSubscriptions({ olderThan })` removes subscriptions inactive for strictly more than `olderThan` seconds.
+It returns exactly the deleted `{ topicID, subscriberDID }` pairs. A subscription refreshed at the boundary survives.
+The delete and return happen atomically, so a refreshed subscription is neither removed nor reported.
+This operation emits no event. `createHub` calls it after scheduled message purge when the store supports it.

package/lib/definition.d.ts

@@ -1,7 +1,6 @@
 import type { StoreDefinition, StoreProvider } from '@hozon/db';
-import type { HubStore } from '@kumiai/hub-protocol';
-import { type HubStoreOptions } from './store.js';
+import { type HubStoreOptions, type SQLHubStore } from './store.js';
 import type { HubTables } from './tables.js';
 export declare const HUB_STORE = "kumiai-hub";
-export declare function createHubStoreDefinition(options?: HubStoreOptions): StoreDefinition<HubTables, HubStore>;
-export declare function getHubStore(provider: StoreProvider): Promise<HubStore>;
+export declare function createHubStoreDefinition(options?: HubStoreOptions): StoreDefinition<HubTables, SQLHubStore>;
+export declare function getHubStore(provider: StoreProvider): Promise<SQLHubStore>;

package/lib/index.d.ts

@@ -1,2 +1,2 @@
 export { createHubStoreDefinition, getHubStore, HUB_STORE } from './definition.js';
-export type { HubStoreOptions } from './store.js';
+export type { HubStoreOptions, HubSubscriptionReaper, SQLHubStore } from './store.js';

package/lib/store.d.ts

@@ -28,4 +28,13 @@ export type CreateHubStoreParams = {
     adapter: Adapter;
     options?: HubStoreOptions;
 };
-export declare function createHubStore(params: CreateHubStoreParams): HubStore;
+export type HubSubscriptionReaper = {
+    purgeSubscriptions(params: {
+        olderThan: number;
+    }): Promise<Array<{
+        topicID: string;
+        subscriberDID: string;
+    }>>;
+};
+export type SQLHubStore = HubStore & HubSubscriptionReaper;
+export declare function createHubStore(params: CreateHubStoreParams): SQLHubStore;

package/lib/store.js

@@ -62,8 +62,9 @@ export function createHubStore(params) {
     // and only then evicts frames, so a sweep that deleted frames first and wrote the row after
     // would take the same two locks in the opposite order and deadlock on Postgres.
     async function lockTopic(trx, topicID) {
-        await trx.selectFrom('hub_topics').select('topic_id').where('topic_id', '=', topicID)// SQLite has no row locks (and rejects the clause); its one writer already serialises.
-        .$if(adapter.kind === 'postgres', (qb)=>qb.forUpdate()).execute();
+        const row = await trx.selectFrom('hub_topics').select('head').where('topic_id', '=', topicID)// SQLite has no row locks (and rejects the clause); its one writer already serialises.
+        .$if(adapter.kind === 'postgres', (qb)=>qb.forUpdate()).executeTakeFirst();
+        return row?.head ?? null;
     }
     // Mint the next sequenceID inside the accepting transaction, from a persistent global counter.
     // Fixed-width zero-padded so lexicographic order matches numeric order (`"10" > "9"`).
@@ -331,7 +332,7 @@ export function createHubStore(params) {
             const effective = Math.max(olderThan, subscriberRetention, defaultRetention);
             const threshold = now - effective * 1000;
             const ids = await withStoreTransaction(db, async (trx)=>{
-                await lockTopic(trx, topic_id);
+                const head = await lockTopic(trx, topic_id);
                 // Log removal is prefix-only by position. A clock that moved backwards can leave a due
                 // frame above one that is not; removing it would punch a hole a cursor cannot see.
                 const keptRow = await trx.selectFrom('hub_messages').select((eb)=>eb.fn.min('sequence_id').as('firstKept')).where('topic_id', '=', topic_id).where('retain', '=', 'log').where('stored_at', '>', threshold).executeTakeFirst();
@@ -340,15 +341,20 @@ export function createHubStore(params) {
                     'sequence_id',
                     'retain'
                 ]).where('topic_id', '=', topic_id).where((eb)=>{
+                    const mailbox = eb.and([
+                        eb('retain', '=', 'mailbox'),
+                        eb('stored_at', '<=', threshold)
+                    ]);
+                    // A mailbox-only topic has no row to lock. Never admit its first concurrent log.
+                    if (head == null) return mailbox;
+                    const log = [
+                        eb('retain', '=', 'log'),
+                        eb('sequence_id', '<=', head)
+                    ];
+                    if (firstKept != null) log.push(eb('sequence_id', '<', firstKept));
                     return eb.or([
-                        eb.and([
-                            eb('retain', '=', 'mailbox'),
-                            eb('stored_at', '<=', threshold)
-                        ]),
-                        firstKept == null ? eb('retain', '=', 'log') : eb.and([
-                            eb('retain', '=', 'log'),
-                            eb('sequence_id', '<', firstKept)
-                        ])
+                        mailbox,
+                        eb.and(log)
                     ]);
                 }).orderBy('sequence_id', 'asc').execute();
                 if (frames.length === 0) return [];
@@ -369,6 +375,17 @@ export function createHubStore(params) {
         });
         return removed;
     }
+    async function purgeSubscriptions({ olderThan }) {
+        // Strict boundary and atomic return: a refreshed subscriber is neither deleted nor reported.
+        const rows = await db.deleteFrom('hub_subscriptions').where('last_active_at', '<', Date.now() - olderThan * 1000).returning([
+            'topic_id',
+            'subscriber_did'
+        ]).execute();
+        return rows.map((row)=>({
+                topicID: row.topic_id,
+                subscriberDID: row.subscriber_did
+            }));
+    }
     async function deleteExpiredKeyPackages(ownerDID) {
         await db.deleteFrom('hub_key_packages').where('owner_did', '=', ownerDID).where('not_after', 'is not', null).where('not_after', '<=', nowSeconds()).execute();
     }
@@ -474,6 +491,7 @@ export function createHubStore(params) {
         fetchTopic,
         ack,
         purge,
+        purgeSubscriptions,
         trim,
         storeKeyPackage,
         fetchKeyPackages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumiai/hub-store",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "SQL hub store for Kumiai hubs, backed by Hozon",
   "keywords": [
     "hub",
@@ -25,21 +25,21 @@
     "lib/*"
   ],
   "dependencies": {
-    "@hozon/adapter": "^0.1.0",
-    "@hozon/db": "^0.2.2",
-    "@kumiai/hub-protocol": "^0.10.1",
-    "@sozai/event": "^0.1.5"
+    "@hozon/adapter": "^0.2.1",
+    "@hozon/db": "^0.5.0",
+    "@kumiai/hub-protocol": "^0.12.0",
+    "@sozai/event": "^0.1.6"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.21.3",
-    "@enkaku/protocol": "^0.21.4",
-    "@enkaku/transport": "^0.21.3",
-    "@hozon/node-sqlite": "^0.1.0",
-    "@hozon/postgres": "^0.1.0",
-    "@kokuin/token": "^0.5.1",
-    "@kumiai/hub-conformance": "^0.10.1",
-    "@kumiai/hub-server": "^0.10.3",
-    "@testcontainers/postgresql": "^12.1.0"
+    "@enkaku/client": "^0.22.2",
+    "@enkaku/protocol": "^0.22.2",
+    "@enkaku/transport": "^0.22.2",
+    "@hozon/node-sqlite": "^0.2.0",
+    "@hozon/postgres": "^0.2.0",
+    "@kokuin/token": "^0.6.2",
+    "@kumiai/hub-conformance": "^0.12.0",
+    "@kumiai/hub-server": "^0.12.0",
+    "@testcontainers/postgresql": "^12.2.1"
   },
   "engines": {
     "node": ">=24"