@kubun/plugin-service-server 0.17.0 → 0.18.0

package/lib/index.d.ts

@@ -1,9 +1,11 @@
 import { type Server } from '@enkaku/server';
 import { type DIDResolver, type MethodRegistry } from '@kokuin/token';
 import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
-import type { ServiceHandler, ServiceProtocol, ServiceServerServeParams } from '@kubun/plugin-service-api';
-export type { AccessRules, Handlers, ServiceAuthorizer, ServiceConfig, ServiceHandler, ServiceHandlerContext, ServiceProviderImpl, ServiceServerServeParams, } from '@kubun/plugin-service-api';
+import type { ServiceAuthorizer, ServiceHandler, ServiceProtocol, ServiceServerServeParams } from '@kubun/plugin-service-api';
+import { type LongLivedCallGate } from './long-lived-gate.js';
+export type { AccessRules, Handlers, ServiceAuthorizer, ServiceConfig, ServiceHandler, ServiceHandlerContext, ServiceProviderImpl, ServiceServerLimits, ServiceServerServeParams, } from '@kubun/plugin-service-api';
 export { type AuthorizeParams, type AuthorizeReadParams, authorizeRead, authorizeWrite, type CreateCallerMayActForParams, createCallerMayActFor, SERVICE_ACT_FOR_ACTION, ServiceAuthorizationError, serviceUserResource, } from './authorizer.js';
+export { createLongLivedCallGate, type LongLivedCallGate, type LongLivedCallGateParams, type ReleaseLongLivedCall, unverifiedCallerGate, } from './long-lived-gate.js';
 /**
  * A configured service name resolves to a `service` provider that was never
  * registered. `true`/`{ rules }` both require a provider; only `{ handlers }`
@@ -67,6 +69,19 @@ export type ServiceServerPluginAPI = {
  * verification (`methods = [controllerResolverFor(db)]`, pre-transaction).
  */
 export declare function createServiceServerPlugin(options?: ServiceServerPluginOptions): (params: PluginFactoryParams) => KubunPlugin;
+/** Params for {@link wrapHandler}. */
+export type WrapHandlerParams = {
+    /** Fully-qualified procedure name, e.g. `echo/ping`. */
+    procedure: string;
+    /** The service handler to wrap. */
+    handler: ServiceHandler;
+    /** The per-serve authorizer; absent falls back to {@link selfOnlyAuthorizer}. */
+    authorizer?: ServiceAuthorizer;
+    /** The per-serve group id, forwarded to the handler's context. */
+    groupID?: string;
+    /** Set for a long-lived procedure: each call holds a place for as long as it runs. */
+    gate?: LongLivedCallGate;
+};
 /**
  * Wrap a service handler so the host — not the caller — supplies the verified
  * `iss` and the `procedure` name to the per-serve authorizer, and so a forged
@@ -78,4 +93,4 @@ export declare function createServiceServerPlugin(options?: ServiceServerPluginO
  * receives a bound `authorize(subject)` that calls the per-serve authorizer with
  * host-supplied `{ iss, procedure }`; a handler cannot spoof either.
  */
-export declare function wrapHandler(procedure: string, handler: ServiceHandler, authorizer: ServiceServerServeParams['authorizer']): ServiceHandler;
+export declare function wrapHandler(params: WrapHandlerParams): ServiceHandler;

package/lib/index.js

@@ -2,9 +2,17 @@ import { serve } from '@enkaku/server';
 import { normalizeDID } from '@kokuin/token';
 import { toHandlerError } from '@kubun/protocol';
 import { ServiceAuthorizationError } from './authorizer.js';
+import { createLongLivedCallGate, unverifiedCallerGate } from './long-lived-gate.js';
 export { authorizeRead, authorizeWrite, createCallerMayActFor, SERVICE_ACT_FOR_ACTION, ServiceAuthorizationError, serviceUserResource } from './authorizer.js';
+export { createLongLivedCallGate, unverifiedCallerGate } from './long-lived-gate.js';
 // The registry kind under which service providers register.
 const SERVICE_KIND = 'service';
+// An app holds a handful of subscriptions open; this leaves room for many while
+// keeping one caller from holding a serve's controllers.
+const DEFAULT_MAX_LONG_LIVED_CALLS_PER_CALLER = 64;
+// Enkaku's controller cap (10000) is shared with ordinary requests: long-lived
+// calls keep most of it free for them.
+const DEFAULT_MAX_LONG_LIVED_CALLS = 1000;
 /**
  * A configured service name resolves to a `service` provider that was never
  * registered. `true`/`{ rules }` both require a provider; only `{ handlers }`
@@ -67,7 +75,9 @@ const SERVICE_KIND = 'service';
         }
         return {
             handlers: provider.handlers,
-            rules: provider.accessRules ?? {}
+            rules: provider.accessRules ?? {},
+            longLivedProcedures: provider.longLivedProcedures ?? [],
+            protocol: provider.protocol
         };
     }
     // Discriminate the object form by EXPLICIT key, never by shape-sniffing.
@@ -79,7 +89,9 @@ const SERVICE_KIND = 'service';
         }
         return {
             handlers: config.handlers,
-            rules: config.rules ?? {}
+            rules: config.rules ?? {},
+            longLivedProcedures: config.longLivedProcedures ?? [],
+            protocol: config.protocol
         };
     }
     // `{ rules }` (override) or `{}` (≡ `true`): both require a provider.
@@ -88,7 +100,9 @@ const SERVICE_KIND = 'service';
     }
     return {
         handlers: provider.handlers,
-        rules: config.rules ?? provider.accessRules ?? {}
+        rules: config.rules ?? provider.accessRules ?? {},
+        longLivedProcedures: provider.longLivedProcedures ?? [],
+        protocol: provider.protocol
     };
 }
 /**
@@ -114,7 +128,7 @@ const SERVICE_KIND = 'service';
         ];
         const api = {
             serve: (serveParams)=>{
-                const { transport, services, authorizer, signal, requireAuth, cache } = serveParams;
+                const { transport, services, authorizer, signal, requireAuth, cache, groupID, limits } = serveParams;
                 const providerList = engine.getProvidersSync(SERVICE_KIND);
                 const providers = new Map();
                 for (const provider of providerList){
@@ -125,6 +139,16 @@ const SERVICE_KIND = 'service';
                 // handler's call context; a trivial handler simply ignores it.
                 const mergedHandlers = {};
                 const mergedRules = {};
+                const longLivedProcedures = new Set();
+                // Validation is all-or-nothing: one served service without a protocol
+                // would have its messages rejected as unknown, so it disables validation.
+                const mergedProtocol = {};
+                let allHaveProtocol = true;
+                const callGate = createLongLivedCallGate({
+                    maxPerCaller: limits?.maxLongLivedCallsPerCaller ?? DEFAULT_MAX_LONG_LIVED_CALLS_PER_CALLER,
+                    max: limits?.maxLongLivedCalls ?? DEFAULT_MAX_LONG_LIVED_CALLS
+                });
+                const gate = requireAuth === false ? unverifiedCallerGate(callGate) : callGate;
                 for (const [name, config] of Object.entries(services)){
                     const selected = resolveService(name, config, providers);
                     if (selected == null) {
@@ -134,10 +158,26 @@ const SERVICE_KIND = 'service';
                         if (procedure in mergedHandlers) {
                             throw new ServiceProcedureCollisionError(procedure);
                         }
-                        mergedHandlers[procedure] = wrapHandler(procedure, handler, authorizer);
+                        const longLived = selected.longLivedProcedures.includes(procedure);
+                        if (longLived) longLivedProcedures.add(procedure);
+                        mergedHandlers[procedure] = wrapHandler({
+                            procedure,
+                            handler,
+                            authorizer,
+                            groupID,
+                            ...longLived ? {
+                                gate
+                            } : {}
+                        });
                     }
                     Object.assign(mergedRules, selected.rules);
+                    if (selected.protocol == null) {
+                        allHaveProtocol = false;
+                    } else {
+                        Object.assign(mergedProtocol, selected.protocol);
+                    }
                 }
+                const validated = allHaveProtocol && Object.keys(mergedProtocol).length > 0;
                 // Build serve params exactly like the RPC plugin. The merged protocol is
                 // the union of the served services' procedures, unknown statically — the
                 // handler map is cast to Enkaku's `ProcedureHandlers` at this one seam,
@@ -145,6 +185,9 @@ const SERVICE_KIND = 'service';
                 const baseParams = {
                     runtime: params.runtime,
                     handlers: mergedHandlers,
+                    ...validated ? {
+                        protocol: mergedProtocol
+                    } : {},
                     logger: params.getLogger('service-server'),
                     signal,
                     transport,
@@ -152,7 +195,24 @@ const SERVICE_KIND = 'service';
                     methods,
                     // Roster-seeded cache from the caller (the service tunnel lane), so a
                     // co-member's short-form did:peer:4 issuer resolves on this Server.
-                    cache
+                    cache,
+                    // Every serve dedups against the engine's persisted ledger, so a signed
+                    // request replayed after a restart, or into another served Server, is
+                    // refused. There is deliberately no per-serve override: any other
+                    // cache, Enkaku's in-memory default included, would forget on restart.
+                    replay: {
+                        cache: params.replayCache
+                    },
+                    // Long-lived calls are not expired and skip the handler concurrency cap;
+                    // the gate bounds them instead.
+                    limits: {
+                        longLivedProcedures: [
+                            ...longLivedProcedures
+                        ],
+                        ...limits?.callTimeoutMs == null ? {} : {
+                            controllerTimeoutMs: limits.callTimeoutMs
+                        }
+                    }
                 };
                 // `requireAuth: false` serves the same merged procedures with no signature
                 // requirement (unauthenticated local mode); it omits `identity`/`accessRules`.
@@ -208,19 +268,22 @@ const selfOnlyAuthorizer = ({ iss, subject })=>subject == null || normalizeDID(i
  * rejected outright, mirroring the RPC plugin's `resolveViewerDID`. The handler
  * receives a bound `authorize(subject)` that calls the per-serve authorizer with
  * host-supplied `{ iss, procedure }`; a handler cannot spoof either.
- */ export function wrapHandler(procedure, handler, authorizer) {
+ */ export function wrapHandler(params) {
+    const { procedure, handler, authorizer, groupID, gate } = params;
     const check = authorizer ?? selfOnlyAuthorizer;
     return async (context)=>{
         // One gate: apply authz context, then translate on throw. A refusal carrying a
         // registered code (KB07 from `ServiceAuthorizationError`) forwards to the caller
         // as that well-known code; an uncoded internal throw stays opaque, its message
         // never leaving the device.
+        let release;
         try {
             const payload = context.message?.payload;
             const iss = payload?.iss;
             if (payload?.sub != null && payload.sub !== iss) {
                 throw new ServiceAuthorizationError('signed payload subject does not match issuer');
             }
+            release = gate?.enter(iss);
             const authorize = async (subject)=>{
                 // No verified caller (the `accessRules: false` local mode): a subject-scoped
                 // action cannot be authorized, so only self-acting (no subject) is allowed.
@@ -236,10 +299,13 @@ const selfOnlyAuthorizer = ({ iss, subject })=>subject == null || normalizeDID(i
             return await handler({
                 ...context,
                 iss,
-                authorize
+                authorize,
+                groupID
             });
         } catch (cause) {
             throw toHandlerError(cause);
+        } finally{
+            release?.();
         }
     };
 }

package/lib/long-lived-gate.d.ts

@@ -0,0 +1,28 @@
+export type LongLivedCallGateParams = {
+    /** Open calls one caller may hold. */
+    maxPerCaller: number;
+    /** Open calls all callers together may hold. */
+    max: number;
+};
+/** Frees the place a call took. Idempotent. */
+export type ReleaseLongLivedCall = () => void;
+export type LongLivedCallGate = {
+    /**
+     * Takes a place for one open call, or throws a `HandlerError` with Enkaku's
+     * handler-limit code (`EK04`). `caller` is the verified issuer; callers with none
+     * share one place count.
+     */
+    enter: (caller: string | undefined) => ReleaseLongLivedCall;
+};
+/**
+ * Bounds the long-lived calls a serve holds open. Enkaku exempts long-lived
+ * procedures from its handler concurrency cap, leaving only its controller cap,
+ * which ordinary requests share: without this, one caller could hold every
+ * controller open and starve the rest.
+ */
+export declare function createLongLivedCallGate(params: LongLivedCallGateParams): LongLivedCallGate;
+/**
+ * A gate for a serve that verifies no signatures: there, an issuer is whatever the
+ * caller wrote, so every call counts as one unverified caller's.
+ */
+export declare function unverifiedCallerGate(gate: LongLivedCallGate): LongLivedCallGate;

package/lib/long-lived-gate.js

@@ -0,0 +1,45 @@
+import { ErrorCodes } from '@enkaku/protocol';
+import { HandlerError } from '@enkaku/server';
+// The bucket of callers with no verified identity, kept apart from every DID.
+const UNVERIFIED = Symbol('unverified');
+/**
+ * Bounds the long-lived calls a serve holds open. Enkaku exempts long-lived
+ * procedures from its handler concurrency cap, leaving only its controller cap,
+ * which ordinary requests share: without this, one caller could hold every
+ * controller open and starve the rest.
+ */ export function createLongLivedCallGate(params) {
+    const { maxPerCaller, max } = params;
+    const open = new Map();
+    let total = 0;
+    return {
+        enter: (caller)=>{
+            const key = caller ?? UNVERIFIED;
+            const held = open.get(key) ?? 0;
+            if (held >= maxPerCaller || total >= max) {
+                throw new HandlerError({
+                    code: ErrorCodes.HANDLER_LIMIT,
+                    message: 'Too many open long-lived calls'
+                });
+            }
+            open.set(key, held + 1);
+            total++;
+            let released = false;
+            return ()=>{
+                if (released) return;
+                released = true;
+                total--;
+                const remaining = (open.get(key) ?? 1) - 1;
+                if (remaining === 0) open.delete(key);
+                else open.set(key, remaining);
+            };
+        }
+    };
+}
+/**
+ * A gate for a serve that verifies no signatures: there, an issuer is whatever the
+ * caller wrote, so every call counts as one unverified caller's.
+ */ export function unverifiedCallerGate(gate) {
+    return {
+        enter: ()=>gate.enter(undefined)
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-service-server",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "license": "see LICENSE.md",
   "sideEffects": false,
   "type": "module",
@@ -14,21 +14,21 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@enkaku/protocol": "^0.21.1",
-    "@enkaku/server": "^0.21.2",
-    "@kokuin/capability": "^0.3.0",
-    "@kokuin/token": "^0.5.0",
-    "@kubun/engine": "^0.17.0",
-    "@kubun/plugin-service-api": "^0.17.0",
-    "@kubun/protocol": "^0.17.0"
+    "@enkaku/protocol": "^0.21.5",
+    "@enkaku/server": "^0.21.5",
+    "@kokuin/capability": "^0.4.2",
+    "@kokuin/token": "^0.5.1",
+    "@kubun/engine": "^0.18.0",
+    "@kubun/plugin-service-api": "^0.18.0",
+    "@kubun/protocol": "^0.18.0"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.21.2",
-    "@enkaku/transport": "^0.21.0",
+    "@enkaku/client": "^0.21.5",
+    "@enkaku/transport": "^0.21.5",
     "@kokuin/controller": "^0.1.0",
-    "@kubun/db": "^0.17.0",
-    "@kubun/store-controller": "^0.17.0",
-    "@kubun/store-graph": "^0.17.0",
+    "@kubun/db": "^0.18.0",
+    "@kubun/store-controller": "^0.18.0",
+    "@kubun/store-graph": "^0.18.0",
     "@kubun/test-utils": "^0.0.0"
   },
   "publishConfig": {