@kumiai/hub-server 0.6.0 → 0.8.0

package/README.md

@@ -31,10 +31,13 @@ another sender. The `identity` param is required for that reason.
 
 Authorization is two layers, and only the second one knows about topics: `accessRules` gate the
 procedures (the default lets any authenticated DID call them), and the optional
-`authorize(request)` hook decides publish and subscribe per topic. It takes one discriminated
-`AuthorizeRequest` — narrow on `request.action` — and returns `AuthorizeDecision`, either a boolean
-or `{ allow, reason?, code?, retryAfterMs? }`. `AuthorizeRequest` names seven actions, but only
-`publish` and `subscribe` are dispatched today. The default allows any authenticated DID.
+`authorize(request)` hook decides the rest. It takes one discriminated `AuthorizeRequest` — narrow
+on `request.action` — and returns `AuthorizeDecision`, either a boolean or
+`{ allow, reason?, code?, retryAfterMs? }`. `AuthorizeRequest` names nine actions, of which only
+`unsubscribe` is not dispatched today; the two `wake/*` actions gate push registration, which is the
+one durable per-device identifier the hub stores. The default allows any authenticated DID, and a
+hook should allow any action it does not recognise, so that a hook written before a variant shipped
+does not start refusing a procedure that used to be ungated.
 
 ## Durable subscription, ephemeral connection
 

package/lib/handlers.d.ts

@@ -1,11 +1,12 @@
 import { type ProcedureHandlers } from '@enkaku/server';
-import type { HubProtocol, HubStore } from '@kumiai/hub-protocol';
+import type { HubProtocol, HubStore, WakeRegistry } from '@kumiai/hub-protocol';
 import { type RateLimitConfig } from './rateLimit.js';
 import type { HubClientRegistry } from './registry.js';
+import type { WakeDispatcher } from './wake.js';
 /**
- * A single request to authorize. All seven variants ship even though only `publish` and
- * `subscribe` are currently enforced: the union is the exhaustive-switch surface a host's own
- * `switch (req.action)` closes over.
+ * A single request to authorize. All nine variants ship even though `unsubscribe` is not yet
+ * dispatched: the union is the exhaustive-switch surface a host's own `switch (req.action)` closes
+ * over, and widening it after a release is a break for every host that closed over it.
  *
  * A host's `switch` need not handle every action today — an unrecognized action should default to
  * allow, so a hook written before a new variant shipped doesn't silently start refusing a
@@ -43,6 +44,32 @@ export type AuthorizeRequest = {
 } | {
     action: 'keypackage/status';
     did: string;
+}
+/**
+ * A device registering a push endpoint. `kind` (the opaque sender tag) and `expiresAt` (the
+ * caller-supplied registration lifetime cap, when given) are the only details a host can usefully
+ * gate on — `endpoint`, `publicKey` and `authSecret` are deliberately absent, since a hook that
+ * saw them would be a second place the endpoint gets read, and the hub's rule is that it never
+ * interprets one.
+ *
+ * This is the durable cross-group per-device identifier wake introduces, so it is the one a host
+ * is most likely to want a say over.
+ */
+ | {
+    action: 'wake/register';
+    did: string;
+    kind: string;
+    expiresAt?: number;
+} | {
+    action: 'wake/unregister';
+    did: string;
+} | {
+    action: 'receive';
+    did: string;
+} | {
+    action: 'receive/deliver';
+    did: string;
+    topicID: string;
 };
 /**
  * A plain `boolean` is shorthand for `{ allow: boolean }`, with no reason, code, or retry hint.
@@ -89,6 +116,12 @@ export type HubStoreErrorEvent = {
     method: 'getSubscribers';
     topicID: string;
     error: unknown;
+}
+/** The DID whose wake dispatch (send, or the registry read/delete around it) failed. */
+ | {
+    method: 'wake';
+    did: string;
+    error: unknown;
 };
 export type HubStoreErrorHook = (event: HubStoreErrorEvent) => void;
 /**
@@ -124,6 +157,12 @@ export declare const DEFAULT_KEYPACKAGE_FETCH_LIMITS: KeyPackageFetchLimits;
  * writer health. The default of 256 is safely above it.
  */
 export declare const DEFAULT_RECEIVE_BUFFER_LIMIT = 256;
+/**
+ * Default TTL (ms) for a receive channel's per-(did, topicID) delivery-authorization decision.
+ * Bounds how long an already-resolved allow is reused before the hook is re-consulted — i.e. the
+ * maximum window a removed member can keep draining a topic. See the receive handler's `gate`.
+ */
+export declare const DEFAULT_RECEIVE_AUTH_CACHE_TTL = 5000;
 export type CreateHandlersParams = {
     registry: HubClientRegistry;
     store: HubStore;
@@ -133,6 +172,12 @@ export type CreateHandlersParams = {
     /** Max frames queued-but-unflushed on a receive channel. See {@link DEFAULT_RECEIVE_BUFFER_LIMIT}
      * for the >= 50-frame-page floor this should respect. Default: 256 */
     receiveBufferLimit?: number;
+    /**
+     * TTL (ms) for the per-(did, topicID) receive delivery-authorization cache. `0` disables reuse
+     * (the hook is consulted for every frame). Non-finite or negative values fall back to
+     * {@link DEFAULT_RECEIVE_AUTH_CACHE_TTL}. Default: 5000.
+     */
+    receiveAuthCacheTTL?: number;
     /**
      * Called when a `HubStore` operation fails at a point where the hub deliberately does not fail
      * the request. Fire-and-forget; a throw here is swallowed.
@@ -141,5 +186,13 @@ export type CreateHandlersParams = {
      * empty handler to silence it deliberately.
      */
     onStoreError?: HubStoreErrorHook;
+    /**
+     * Wake support. Absent: both wake procedures refuse. The registry is separate from the
+     * dispatcher because the handlers only ever store and remove; sending is the dispatcher's.
+     */
+    wake?: {
+        registry: WakeRegistry;
+        dispatcher?: WakeDispatcher;
+    };
 };
 export declare function createHandlers(params: CreateHandlersParams): ProcedureHandlers<HubProtocol>;

package/lib/handlers.js

@@ -1,5 +1,5 @@
 import { HandlerError } from '@enkaku/server';
-import { HUB_ERROR_CODES, hubErrorCodeOf, InvalidPayloadError, KeyPackageFetchLimitError, keyPackageDigest } from '@kumiai/hub-protocol';
+import { HUB_ERROR_CODES, hubErrorCodeOf, InvalidPayloadError, KeyPackageFetchLimitError, keyPackageDigest, wakeRecipientKeyProblem } from '@kumiai/hub-protocol';
 import { fromB64, toB64 } from '@sozai/codec';
 import { getReporter } from '@sozai/log';
 import { createRateLimiter } from './rateLimit.js';
@@ -21,7 +21,8 @@ function normalizeAuthorizeDecision(decision) {
     fetchLastResortKeyPackage: 'The fetch returned what the pool could serve, without the last-resort top-up. A read that ' + 'keeps failing means the availability floor the last-resort slot exists to provide is absent, ' + 'and joins fail downstream at the inviter with no signal here.',
     ack: 'The frame stays pending and the client re-acks on the next round. An ack that keeps failing ' + 'redelivers every frame forever.',
     purge: 'Retried on the next interval. A purge that keeps failing means the store grows without bound.',
-    getSubscribers: 'The frame is committed and queued, but the live push to connected subscribers was skipped: ' + 'each of them stops receiving new frames until it reconnects. A getSubscribers that keeps ' + 'failing means the hub has silently degraded from push to pull for every publish.'
+    getSubscribers: 'The frame is committed and queued, but the live push to connected subscribers was skipped: ' + 'each of them stops receiving new frames until it reconnects. A getSubscribers that keeps ' + 'failing means the hub has silently degraded from push to pull for every publish.',
+    wake: 'The offline device was not pinged for this frame. It still redelivers on the next reconnect ' + '(store-and-forward), so nothing is lost — but a wake that keeps failing means the device ' + 'stays asleep until something else wakes it.'
 };
 const reportStoreError = getReporter([
     'kumiai',
@@ -36,6 +37,7 @@ const reportStoreError = getReporter([
             return ` on topic ${event.topicID}`;
         case 'ack':
         case 'fetchLastResortKeyPackage':
+        case 'wake':
             return ` for ${event.did}`;
     }
 }
@@ -82,6 +84,11 @@ export const DEFAULT_KEYPACKAGE_FETCH_LIMITS = {
  * before awaiting, so a limit below 50 would trip the cap on the very first page regardless of
  * writer health. The default of 256 is safely above it.
  */ export const DEFAULT_RECEIVE_BUFFER_LIMIT = 256;
+/**
+ * Default TTL (ms) for a receive channel's per-(did, topicID) delivery-authorization decision.
+ * Bounds how long an already-resolved allow is reused before the hook is re-consulted — i.e. the
+ * maximum window a removed member can keep draining a topic. See the receive handler's `gate`.
+ */ export const DEFAULT_RECEIVE_AUTH_CACHE_TTL = 5000;
 function getClientDID(ctx) {
     const iss = ctx.message.payload.iss;
     if (typeof iss !== 'string' || iss.length === 0) {
@@ -103,6 +110,13 @@ function getClientDID(ctx) {
     }
     throw error;
 }
+function resolveReceiveAuthCacheTTL(value) {
+    if (value === undefined || !Number.isFinite(value) || value < 0) {
+        return DEFAULT_RECEIVE_AUTH_CACHE_TTL;
+    }
+    return value // 0 allowed: no reuse
+    ;
+}
 function toReceiveFrame(message) {
     return {
         sequenceID: message.sequenceID,
@@ -132,6 +146,7 @@ export function createHandlers(params) {
     const didLimiter = createRateLimiter(rateLimits.perDID);
     const topicLimiter = createRateLimiter(rateLimits.perTopic);
     const receiveBufferLimit = params.receiveBufferLimit ?? DEFAULT_RECEIVE_BUFFER_LIMIT;
+    const receiveAuthCacheTTL = resolveReceiveAuthCacheTTL(params.receiveAuthCacheTTL);
     const storeErrorReporter = createStoreErrorReporter(params.onStoreError);
     const fetchLimits = {
         ...DEFAULT_KEYPACKAGE_FETCH_LIMITS,
@@ -293,6 +308,29 @@ export function createHandlers(params) {
                             payload: payloadBytes,
                             ...logPosition
                         });
+                    } else {
+                        // No live channel: the frame is durably queued, so all that is missing is a nudge to
+                        // come and get it. Both retention classes wake — a commit-lane frame is log-class, and
+                        // a membership change is exactly what a sleeping device must learn.
+                        //
+                        // Guarded even though `notify` is documented never to throw: `dispatcher` is
+                        // caller-injectable (`CreateHandlersParams.wake.dispatcher`), and a misbehaving
+                        // third-party implementation must not abort this loop mid-way — that would cost live
+                        // delivery to every subscriber still to come, for a publish whose append already
+                        // committed.
+                        try {
+                            params.wake?.dispatcher?.notify({
+                                did: recipientDID,
+                                topicID,
+                                sequenceID
+                            });
+                        } catch (error) {
+                            storeErrorReporter({
+                                method: 'wake',
+                                did: recipientDID,
+                                error
+                            });
+                        }
                     }
                 }
             }
@@ -392,7 +430,43 @@ export function createHandlers(params) {
         'hub/v1/receive': async (ctx)=>{
             const clientDID = getClientDID(ctx);
             const { after } = ctx.param ?? {};
+            const connectDecision = normalizeAuthorizeDecision(await authorize({
+                action: 'receive',
+                did: clientDID
+            }));
+            if (!connectDecision.allow) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.authorizationDenied,
+                    message: connectDecision.reason ?? 'Not authorized to receive'
+                });
+            }
             registry.register(clientDID);
+            // Per-(did, topicID) delivery-authorization cache, local to this channel (torn down with it).
+            // Both allow AND deny are cached for the TTL, so re-grant is not immediate: a topic that was
+            // just re-authorized keeps being denied for up to `receiveAuthCacheTTL` ms, and a frame denied
+            // in-session redelivers on the recipient's next connect.
+            const authCache = new Map();
+            const gate = async (topicID)=>{
+                const key = `${clientDID}${topicID}`;
+                const now = Date.now();
+                const cached = authCache.get(key);
+                if (cached != null && cached.expiresAt > now) return cached.allow;
+                const decision = normalizeAuthorizeDecision(await authorize({
+                    action: 'receive/deliver',
+                    did: clientDID,
+                    topicID
+                }));
+                if (receiveAuthCacheTTL > 0) {
+                    // Expiry is measured from when the decision is stored, AFTER the hook resolves — so the
+                    // reuse window excludes the hook's own execution time. Re-read the clock here rather than
+                    // reusing `now` (captured before the await).
+                    authCache.set(key, {
+                        allow: decision.allow,
+                        expiresAt: Date.now() + receiveAuthCacheTTL
+                    });
+                }
+                return decision.allow;
+            };
             const writer = ctx.writable.getWriter();
             const reader = ctx.readable.getReader();
             let endEvicted;
@@ -439,6 +513,7 @@ export function createHandlers(params) {
                 writeChain = writeChain.then(async ()=>{
                     if (tornDown) return;
                     try {
+                        if (!await gate(frame.topicID)) return; // denied: skip, leave pending, no ack
                         await writer.ready;
                         await writer.write(frame);
                         if (frame.sequenceID > lastServed) lastServed = frame.sequenceID;
@@ -480,6 +555,8 @@ export function createHandlers(params) {
                 receiveToken = token;
                 // After the bind, so the lane is never unheld between the two.
                 evicted?.();
+                // The device is draining; a trailing summary would be noise it has already outrun.
+                params.wake?.dispatcher?.online(clientDID);
                 // Drain the backlog. Await each page so lastServed is exact before the flush.
                 let cursor = after;
                 while(!tornDown){
@@ -767,6 +844,111 @@ export function createHandlers(params) {
                 count,
                 lastResort: stored == null ? null : keyPackageDigest(stored)
             };
+        },
+        'hub/v1/wake/register': async (ctx)=>{
+            const clientDID = getClientDID(ctx);
+            const wake = params.wake;
+            if (wake == null) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.wakeNotSupported,
+                    message: 'This hub does not support wake notifications'
+                });
+            }
+            // After the not-supported refusal, before the rate limit — the order every enforced variant
+            // uses. Configuration is answered first because a hub with no wake support has nothing for a
+            // host to have an opinion about.
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'wake/register',
+                did: clientDID,
+                kind: ctx.param.kind,
+                expiresAt: ctx.param.expiresAt
+            }));
+            if (!decision.allow) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.authorizationDenied,
+                    message: decision.reason ?? 'Not authorized to register a wake endpoint'
+                });
+            }
+            if (!didLimiter.tryConsume(clientDID)) {
+                throw new HandlerError({
+                    code: 'EK01',
+                    message: 'Wake rate limit exceeded for DID'
+                });
+            }
+            // The param schema bounds the length (`minLength: 1`, `maxLength: 128`/`64`) but not the
+            // shape, which accepts key material the hub can never seal to. Storing it answers
+            // `registered: true` and then fails inside every single seal — one error per frame, forever,
+            // since a seal failure is not a `gone` verdict and nothing removes the entry. The device
+            // believes it is reachable and is never woken.
+            // The rule itself lives in hub-protocol next to RFC 8291, so the hub needs no curve of its
+            // own to know that a 65-byte value off the curve fails exactly as a 33-byte one does.
+            const keyProblem = wakeRecipientKeyProblem({
+                publicKey: ctx.param.publicKey,
+                authSecret: ctx.param.authSecret
+            });
+            if (keyProblem != null) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.invalidPayload,
+                    message: `Wake ${keyProblem}`
+                });
+            }
+            try {
+                await wake.registry.put({
+                    // The DID is the verified issuer, never a wire field — otherwise any member could
+                    // redirect another member's wakes to an endpoint they control.
+                    did: clientDID,
+                    kind: ctx.param.kind,
+                    endpoint: ctx.param.endpoint,
+                    publicKey: ctx.param.publicKey,
+                    authSecret: ctx.param.authSecret,
+                    ...ctx.param.expiresAt != null ? {
+                        expiresAt: ctx.param.expiresAt
+                    } : {}
+                });
+            } catch (error) {
+                rethrowAsHandlerError(error);
+            }
+            return {
+                registered: true
+            };
+        },
+        'hub/v1/wake/unregister': async (ctx)=>{
+            const clientDID = getClientDID(ctx);
+            const wake = params.wake;
+            if (wake == null) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.wakeNotSupported,
+                    message: 'This hub does not support wake notifications'
+                });
+            }
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'wake/unregister',
+                did: clientDID
+            }));
+            if (!decision.allow) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.authorizationDenied,
+                    message: decision.reason ?? 'Not authorized to unregister a wake endpoint'
+                });
+            }
+            // Matches `register` above and the subscribe/unsubscribe pair: both halves of a pair cost
+            // the same, or the uncounted half is the one an abusive caller uses.
+            if (!didLimiter.tryConsume(clientDID)) {
+                throw new HandlerError({
+                    code: 'EK01',
+                    message: 'Wake rate limit exceeded for DID'
+                });
+            }
+            let existed;
+            try {
+                existed = await wake.registry.get(clientDID) != null;
+                await wake.registry.delete(clientDID);
+            } catch (error) {
+                rethrowAsHandlerError(error);
+            }
+            return {
+                unregistered: existed
+            };
         }
     };
 }

package/lib/hub.d.ts

@@ -1,7 +1,7 @@
 import type { ServerTransportOf } from '@enkaku/protocol';
 import type { AccessRules, ResourceLimits, Server } from '@enkaku/server';
 import type { Identity } from '@kokuin/token';
-import { type HubProtocol, type HubStore } from '@kumiai/hub-protocol';
+import type { HubProtocol, HubStore, WakeRegistry, WakeSender } from '@kumiai/hub-protocol';
 import { type AuthorizeHook, type HubRateLimits, type HubStoreErrorHook, type KeyPackageFetchLimits } from './handlers.js';
 import { HubClientRegistry } from './registry.js';
 /**
@@ -30,7 +30,12 @@ export type CreateHubParams = {
     identity: Identity;
     /** Access rules enforced by the server. Defaults to {@link DEFAULT_HUB_ACCESS_RULES}. */
     accessRules?: AccessRules;
-    /** Per-procedure publish/subscribe authorization. Defaults to allow-any-authed. */
+    /**
+     * Per-action authorization hook. Consulted for publish, subscribe, topic/fetch, keypackage/*,
+     * wake/*, and receive — the coarse `receive` gate at channel open plus a per-frame
+     * `receive/deliver` gate by topic (see {@link CreateHubParams.receiveAuthCacheTTL}). Defaults to
+     * allow-any-authed.
+     */
     authorize?: AuthorizeHook;
     /** Publish rate limits. Merged over {@link DEFAULT_RATE_LIMITS}. */
     rateLimits?: Partial<HubRateLimits>;
@@ -39,6 +44,11 @@ export type CreateHubParams = {
      * {@link DEFAULT_KEYPACKAGE_FETCH_LIMITS}.
      */
     keyPackageFetchLimits?: Partial<KeyPackageFetchLimits>;
+    /**
+     * TTL (ms) for the per-(did, topicID) receive delivery-authorization cache. `0` consults the
+     * hook for every frame. Forwarded to {@link createHandlers}. Default: 5000.
+     */
+    receiveAuthCacheTTL?: number;
     /**
      * Called when a `HubStore` operation fails where the hub deliberately does not fail the
      * request. Forwarded to {@link createHandlers} and used by the purge timer. Fire-and-forget.
@@ -52,6 +62,17 @@ export type CreateHubParams = {
      * `controllerTimeoutMs` and from the `maxConcurrentHandlers` cap.
      */
     limits?: Partial<ResourceLimits>;
+    /**
+     * Wake notifications. Absent: `hub/v1/wake/*` refuse with `WakeNotSupportedError` — refusing is
+     * the only honest answer, since accepting a registration the hub will never act on leaves the
+     * device believing it is reachable.
+     */
+    wake?: {
+        registry: WakeRegistry;
+        sender: WakeSender;
+        /** Coalescing window in milliseconds. Default: 10 000. */
+        debounceMs?: number;
+    };
 };
 export type HubInstance = {
     registry: HubClientRegistry;

package/lib/hub.js

@@ -2,6 +2,7 @@ import { serve } from '@enkaku/server';
 import { hubProtocol } from '@kumiai/hub-protocol';
 import { createHandlers, createStoreErrorReporter } from './handlers.js';
 import { HubClientRegistry } from './registry.js';
+import { createWakeDispatcher } from './wake.js';
 /**
  * Default access rules: any authenticated DID may call hub procedures.
  * The hub is a blind relay — per-procedure authorization (the `authorize`
@@ -17,13 +18,28 @@ export function createHub(params) {
     // wrapper delegates to this instance rather than building a second one from the same hook —
     // which matters the moment a reporter holds state, as the throttling the README names would.
     const storeErrorReporter = createStoreErrorReporter(params.onStoreError);
+    const wakeDispatcher = params.wake == null ? undefined : createWakeDispatcher({
+        registry: params.wake.registry,
+        sender: params.wake.sender,
+        debounceMs: params.wake.debounceMs,
+        onError: ({ did, error })=>storeErrorReporter({
+                method: 'wake',
+                did,
+                error
+            })
+    });
     const handlers = createHandlers({
         registry,
         store: params.store,
         authorize: params.authorize,
         rateLimits: params.rateLimits,
         keyPackageFetchLimits: params.keyPackageFetchLimits,
-        onStoreError: storeErrorReporter
+        receiveAuthCacheTTL: params.receiveAuthCacheTTL,
+        onStoreError: storeErrorReporter,
+        wake: params.wake == null ? undefined : {
+            registry: params.wake.registry,
+            dispatcher: wakeDispatcher
+        }
     });
     const limits = {
         ...params.limits,
@@ -58,6 +74,9 @@ export function createHub(params) {
         }, interval);
         server.disposed.then(()=>clearInterval(purgeTimer));
     }
+    if (wakeDispatcher != null) {
+        server.disposed.then(()=>wakeDispatcher.dispose());
+    }
     return {
         registry,
         server

package/lib/index.d.ts

@@ -6,3 +6,4 @@ export { createMemoryStore, type MemoryStoreOptions } from './memoryStore.js';
 export { createRateLimiter, type RateLimitConfig, type RateLimiter } from './rateLimit.js';
 export type { ClientEntry } from './registry.js';
 export { HubClientRegistry } from './registry.js';
+export { createWakeDispatcher, type WakeDispatcher, type WakeDispatcherParams, type WakeNotifyParams, } from './wake.js';

package/lib/index.js

@@ -3,3 +3,4 @@ export { createHub, DEFAULT_HUB_ACCESS_RULES } from './hub.js';
 export { createMemoryStore } from './memoryStore.js';
 export { createRateLimiter } from './rateLimit.js';
 export { HubClientRegistry } from './registry.js';
+export { createWakeDispatcher } from './wake.js';

package/lib/wake.d.ts

@@ -0,0 +1,33 @@
+import { type WakeRegistry, type WakeSender } from '@kumiai/hub-protocol';
+export type WakeDispatcherParams = {
+    registry: WakeRegistry;
+    sender: WakeSender;
+    /** Coalescing window in milliseconds. Default: 10 000. */
+    debounceMs?: number;
+    /** Reports a transient send failure or a throwing sender. Fire-and-forget. */
+    onError?: (params: {
+        did: string;
+        error: unknown;
+    }) => void;
+};
+export type WakeNotifyParams = {
+    did: string;
+    topicID: string;
+    sequenceID: string;
+};
+export type WakeDispatcher = {
+    /** A frame was queued for an OFFLINE subscriber. Never throws, never awaited by the caller. */
+    notify(params: WakeNotifyParams): void;
+    /** The device bound a receive channel: drop any pending trailing ping. */
+    online(did: string): void;
+    dispose(): void;
+};
+/**
+ * Coalesces wake pings per DID on a LEADING edge: the first frame pings immediately, then a window
+ * opens and everything inside it collapses into one trailing summary.
+ *
+ * Leading rather than trailing because the timer map is in-process. A hub restart drops pending
+ * windows; on a leading edge that loses at most a summary, whereas trailing-only would lose the
+ * notification itself every time a restart landed inside a window.
+ */
+export declare function createWakeDispatcher(params: WakeDispatcherParams): WakeDispatcher;

package/lib/wake.js

@@ -0,0 +1,112 @@
+import { sealWakeHint } from '@kumiai/hub-protocol';
+import { fromB64U } from '@sozai/codec';
+const DEFAULT_DEBOUNCE_MS = 10_000;
+/**
+ * Coalesces wake pings per DID on a LEADING edge: the first frame pings immediately, then a window
+ * opens and everything inside it collapses into one trailing summary.
+ *
+ * Leading rather than trailing because the timer map is in-process. A hub restart drops pending
+ * windows; on a leading edge that loses at most a summary, whereas trailing-only would lose the
+ * notification itself every time a restart landed inside a window.
+ */ export function createWakeDispatcher(params) {
+    const debounceMs = params.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const pending = new Map();
+    let disposed = false;
+    function report(did, error) {
+        try {
+            params.onError?.({
+                did,
+                error
+            });
+        } catch  {
+        // A reporter that throws must not take the dispatcher with it.
+        }
+    }
+    function send(did, topicID, sequenceID, count) {
+        // Deliberately not awaited: a slow or hanging provider must never delay the publish fan-out
+        // this is called from.
+        void (async ()=>{
+            try {
+                const registration = await params.registry.get(did);
+                if (registration == null) return;
+                const body = sealWakeHint({
+                    topicID,
+                    sequenceID,
+                    count
+                }, {
+                    publicKey: fromB64U(registration.publicKey),
+                    authSecret: fromB64U(registration.authSecret)
+                });
+                const verdict = await params.sender.send({
+                    registration,
+                    body
+                });
+                switch(verdict){
+                    case 'delivered':
+                        break;
+                    case 'gone':
+                        await params.registry.delete(did);
+                        break;
+                    case 'retry':
+                        report(did, new Error('Wake send failed transiently'));
+                        break;
+                    default:
+                        // Exhaustive over WakeVerdict: a future verdict must be handled explicitly here rather
+                        // than silently falling through as 'delivered'.
+                        verdict;
+                }
+            } catch (error) {
+                report(did, error);
+            }
+        })();
+    }
+    function openWindow(did) {
+        const entry = {
+            timer: setTimeout(()=>{
+                const current = pending.get(did);
+                pending.delete(did);
+                if (current?.latest == null) return;
+                send(did, current.latest.topicID, current.latest.sequenceID, current.count);
+                // Traffic is still flowing, so a fresh window opens behind the summary rather than letting
+                // the next frame ping immediately and undo the coalescing.
+                pending.set(did, openWindow(did));
+            }, debounceMs),
+            latest: null,
+            count: 0
+        };
+        // A pending wake must never hold a process open by itself. `.unref` is a Node timer method
+        // absent from the DOM `Timeout` type; it only typechecks here because this package's
+        // tsconfig.json (unlike its siblings') sets `"types": ["node"]`. If hub-server is ever
+        // aligned to drop that, this line needs `(entry.timer as NodeJS.Timeout).unref?.()` or an
+        // equivalent cast.
+        entry.timer.unref?.();
+        return entry;
+    }
+    return {
+        notify ({ did, topicID, sequenceID }) {
+            if (disposed) return;
+            const entry = pending.get(did);
+            if (entry == null) {
+                pending.set(did, openWindow(did));
+                send(did, topicID, sequenceID, 1);
+                return;
+            }
+            entry.latest = {
+                topicID,
+                sequenceID
+            };
+            entry.count += 1;
+        },
+        online (did) {
+            const entry = pending.get(did);
+            if (entry == null) return;
+            clearTimeout(entry.timer);
+            pending.delete(did);
+        },
+        dispose () {
+            disposed = true;
+            for (const entry of pending.values())clearTimeout(entry.timer);
+            pending.clear();
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumiai/hub-server",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Hub server for Enkaku E2EE group message routing",
   "keywords": [
     "hub",
@@ -26,17 +26,18 @@
   ],
   "dependencies": {
     "@enkaku/protocol": "^0.21.0",
-    "@enkaku/server": "^0.21.0",
-    "@kokuin/token": "^0.4.0",
+    "@enkaku/server": "^0.21.2",
+    "@kokuin/token": "^0.5.0",
+    "@kumiai/hub-protocol": "^0.8.0",
     "@sozai/codec": "^0.4.0",
     "@sozai/event": "^0.1.3",
-    "@sozai/log": "^0.3.1",
-    "@kumiai/hub-protocol": "^0.6.0"
+    "@sozai/log": "^0.3.1"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.21.0",
+    "@enkaku/client": "^0.21.1",
     "@enkaku/transport": "^0.21.0",
-    "@kumiai/hub-conformance": "^0.6.0"
+    "@kumiai/hub-conformance": "^0.8.0",
+    "@kumiai/hub-wake": "^0.8.0"
   },
   "publishConfig": {
     "access": "public"