@kumiai/hub-store 0.12.0 → 0.13.1

package/README.md

@@ -11,7 +11,7 @@ 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 `SQLHubStore` from a `HozonDB` or any Hozon `StoreProvider`.
-- `HubStoreOptions`, `HubSubscriptionReaper`, and `SQLHubStore` (`HubStore & HubSubscriptionReaper`).
+- `HubStoreOptions`, `HubSubscriptionReaper`, and `SQLHubStore` (the hub contract, subscription reaping, occupancy and persistent store identity).
 
 ```ts
 import { HozonDB } from '@hozon/db'
@@ -56,3 +56,21 @@ Concurrent retries of one publish ID wait for the accepting transaction and retu
 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.
+
+## Attribution migration and occupancy
+
+Migration `1-attribution` adds `payload_size`, nullable `account`, `actor` and `via` columns, plus the `hub_meta` table.
+It backfills payload sizes and persists a generated `storeID` in `hub_meta`.
+Existing message, retention and delivery semantics remain unchanged.
+
+`publish({ ..., attribution? })` accepts `{ account, actor, via: 'direct' | 'delegated' | 'group' }`.
+Without attribution, these columns remain null.
+Legacy and unattributed rows fall back to `sender_did` for both account and actor, with `via: 'direct'`.
+
+`store.occupancy()` returns retained payload bytes and frame counts grouped by account, actor and via.
+Each physical frame counts once, regardless of recipient count.
+Ack, trim, purge and unsubscribe affect occupancy through their existing frame deletion rules.
+`store.storeID()` returns the persistent identifier shared by processes using the same store.
+
+Publish results include `outcome` and `storedBytes`.
+Only `outcome: 'inserted'` contributes payload bytes. Deduplicated and no-recipient publishes report zero stored bytes.

package/lib/migrations.js

@@ -1,7 +1,39 @@
+import { sql } from '@hozon/db';
 export function hubStoreMigrations(ctx) {
     const t = ctx.types;
     const p = ctx.tablePrefix;
     return {
+        '1-attribution': {
+            async up (db) {
+                await db.schema.alterTable('hub_messages').addColumn('payload_size', 'integer', (col)=>col.notNull().defaultTo(0)).execute();
+                for (const column of [
+                    'account',
+                    'actor',
+                    'via'
+                ]){
+                    await db.schema.alterTable('hub_messages').addColumn(column, t.text).execute();
+                }
+                await db.updateTable('hub_messages').set({
+                    payload_size: sql`length(${sql.ref('payload')})`
+                }).execute();
+                await db.schema.createTable('hub_meta').addColumn('key', t.text, (col)=>col.notNull().primaryKey()).addColumn('value', t.text, (col)=>col.notNull()).execute();
+                await db.insertInto('hub_meta').values({
+                    key: 'storeID',
+                    value: crypto.randomUUID()
+                }).execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('hub_meta').execute();
+                for (const column of [
+                    'via',
+                    'actor',
+                    'account',
+                    'payload_size'
+                ]){
+                    await db.schema.alterTable('hub_messages').dropColumn(column).execute();
+                }
+            }
+        },
         '0-init': {
             async up (db) {
                 await db.schema.createTable('hub_messages').addColumn('sequence_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('sender_did', t.text, (col)=>col.notNull()).addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('payload', t.binary, (col)=>col.notNull()).addColumn('stored_at', t.bigint, (col)=>col.notNull()).addColumn('retain', t.text, (col)=>col.notNull().defaultTo('mailbox')).execute();

package/lib/store.d.ts

@@ -1,6 +1,6 @@
 import type { Adapter } from '@hozon/adapter';
-import { type Kysely } from '@hozon/db';
-import { type HubStore } from '@kumiai/hub-protocol';
+import type { Kysely } from '@hozon/db';
+import type { HubStore, OccupancyRow } from '@kumiai/hub-protocol';
 import type { HubTables } from './tables.js';
 export type HubStoreOptions = {
     /** Hub default retention in seconds: the floor for a topic's age bound. Default 0. */
@@ -36,5 +36,8 @@ export type HubSubscriptionReaper = {
         subscriberDID: string;
     }>>;
 };
-export type SQLHubStore = HubStore & HubSubscriptionReaper;
+export type SQLHubStore = HubStore & HubSubscriptionReaper & {
+    occupancy(): Promise<Array<OccupancyRow>>;
+    storeID(): Promise<string>;
+};
 export declare function createHubStore(params: CreateHubStoreParams): SQLHubStore;

package/lib/store.js

@@ -1,4 +1,4 @@
-import { withStoreTransaction } from '@hozon/db';
+import { sql, withStoreTransaction } from '@hozon/db';
 import { HeadMismatchError, KeyPackageQuotaExceededError, NotSubscribedError, RetentionExceededError, SubscriptionQuotaExceededError } from '@kumiai/hub-protocol';
 import { EventEmitter } from '@sozai/event';
 /**
@@ -110,7 +110,9 @@ export function createHubStore(params) {
                     if (existing.sequence_id == null) throw new Error('Incomplete publish-id record');
                     return {
                         sequenceID: existing.sequence_id,
-                        deduped: true
+                        deduped: true,
+                        outcome: 'deduplicated',
+                        storedBytes: 0
                     };
                 }
             }
@@ -128,12 +130,20 @@ export function createHubStore(params) {
             const recipients = subscriberRows.map((r)=>r.subscriber_did).filter((did)=>did !== senderDID);
             // 6. Append. A log frame is stored unconditionally (its reader may not exist yet). A mailbox
             // frame with zero recipients is not stored, but the sequenceID is still consumed.
-            if (retain === 'log' || recipients.length > 0) {
+            let storedBytes = 0;
+            const inserted = retain === 'log' || recipients.length > 0;
+            if (inserted) {
+                const payload = adapter.encodeBinary(publishParams.payload);
+                storedBytes = payload.byteLength;
                 await trx.insertInto('hub_messages').values({
                     sequence_id: sequenceID,
                     sender_did: senderDID,
                     topic_id: topicID,
-                    payload: adapter.encodeBinary(publishParams.payload),
+                    payload,
+                    payload_size: storedBytes,
+                    account: publishParams.attribution?.account ?? null,
+                    actor: publishParams.attribution?.actor ?? null,
+                    via: publishParams.attribution?.via ?? null,
                     stored_at: Date.now(),
                     retain
                 }).execute();
@@ -185,7 +195,9 @@ export function createHubStore(params) {
             }
             return {
                 sequenceID,
-                deduped: false
+                deduped: false,
+                outcome: inserted ? 'inserted' : 'no-recipients',
+                storedBytes
             };
         });
     }
@@ -484,7 +496,35 @@ export function createHubStore(params) {
         const rows = await db.selectFrom('hub_subscriptions').select('subscriber_did').where('topic_id', '=', topicID).execute();
         return rows.map((r)=>r.subscriber_did);
     }
+    async function occupancy() {
+        const rows = await db.selectFrom('hub_messages').select((eb)=>{
+            return [
+                eb.fn.coalesce('account', 'sender_did').as('account'),
+                eb.fn.coalesce('actor', 'sender_did').as('actor'),
+                eb.fn.coalesce(eb.ref('via'), sql`'direct'`).as('via'),
+                eb.fn.sum('payload_size').as('bytes'),
+                eb.fn.countAll().as('frames')
+            ];
+        }).groupBy((eb)=>{
+            return [
+                eb.fn.coalesce('account', 'sender_did'),
+                eb.fn.coalesce('actor', 'sender_did'),
+                eb.fn.coalesce(eb.ref('via'), sql`'direct'`)
+            ];
+        }).execute();
+        return rows.map((row)=>({
+                ...row,
+                bytes: Number(row.bytes),
+                frames: Number(row.frames)
+            }));
+    }
+    async function storeID() {
+        const row = await db.selectFrom('hub_meta').select('value').where('key', '=', 'storeID').executeTakeFirstOrThrow();
+        return row.value;
+    }
     return {
+        occupancy,
+        storeID,
         events,
         publish,
         fetch,

package/lib/tables.d.ts

@@ -1,9 +1,18 @@
 import type { ColumnType } from '@hozon/db';
+import type { HubAttribution } from '@kumiai/hub-protocol';
 export type HubTables = {
+    hub_meta: {
+        key: string;
+        value: string;
+    };
     hub_messages: {
         sequence_id: string;
         sender_did: string;
         topic_id: string;
+        payload_size: ColumnType<number, number | undefined, number>;
+        account: ColumnType<string | null, string | null | undefined, string | null>;
+        actor: ColumnType<string | null, string | null | undefined, string | null>;
+        via: ColumnType<HubAttribution['via'] | null, HubAttribution['via'] | null | undefined, HubAttribution['via'] | null>;
         payload: Uint8Array;
         stored_at: number;
         retain: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumiai/hub-store",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "SQL hub store for Kumiai hubs, backed by Hozon",
   "keywords": [
     "hub",
@@ -25,20 +25,20 @@
     "lib/*"
   ],
   "dependencies": {
-    "@hozon/adapter": "^0.2.1",
-    "@hozon/db": "^0.5.0",
-    "@kumiai/hub-protocol": "^0.12.0",
+    "@hozon/adapter": "^0.3.0",
+    "@hozon/db": "^0.5.1",
+    "@kumiai/hub-protocol": "^0.13.1",
     "@sozai/event": "^0.1.6"
   },
   "devDependencies": {
-    "@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",
+    "@enkaku/client": "^0.23.1",
+    "@enkaku/protocol": "^0.23.1",
+    "@enkaku/transport": "^0.23.1",
+    "@hozon/node-sqlite": "^0.3.0",
+    "@hozon/postgres": "^0.2.1",
+    "@kokuin/token": "^0.7.0",
+    "@kumiai/hub-conformance": "^0.13.0",
+    "@kumiai/hub-server": "^0.13.1",
     "@testcontainers/postgresql": "^12.2.1"
   },
   "engines": {