@spfn/core 0.3.0-beta.24 → 0.3.0-beta.26

package/dist/{router-ZDV1ISTo.d.ts → router-D5B0cpVN.d.ts}

@@ -21,6 +21,18 @@ interface PubSubCache {
  * Event handler function type
  */
 type EventHandler<TPayload> = (payload: TPayload) => void | Promise<void>;
+/**
+ * Options for `EventDef.subscribe`.
+ */
+interface EventSubscribeOptions {
+    /**
+     * Run only for an `emit` made in this process, never for a delivery the
+     * cache transport received from another pod. For a handler whose work must
+     * happen once per emit, not once per pod (it would otherwise run on every
+     * pod the event is cached to). Without a cache it runs on every `emit`.
+     */
+    localOnly?: boolean;
+}
 /**
  * Job queue sender function type (used by job module)
  */
@@ -87,15 +99,24 @@ interface FrameContext {
  * the connection asked for and never reads storage.
  */
 type FramePredicate<TPayload> = (payload: TPayload, ctx: FrameContext) => boolean;
+/**
+ * Which of a subject's connections a `grant` / `revoke` reaches: those whose
+ * connect query carries every named field with exactly that value. A
+ * connection that declared no such field never matches. Plain JSON, so it
+ * travels to other pods unchanged.
+ */
+interface SubscriptionMatch {
+    query: Record<string, string>;
+}
 /**
  * How an SSE handler lets `grant` / `revoke` reach its open connections.
  * Each handler registers one per router key of the event.
  */
 interface SubscriptionControl {
-    /** Activate the event on every open connection of `subject` where it is denied. */
-    grant: (subject: string) => void;
-    /** Deactivate the event on every open connection of `subject` where it is allowed. */
-    revoke: (subject: string) => void;
+    /** Activate the event on every open connection of `subject` (matching `match`, when given) where it is denied. */
+    grant: (subject: string, match?: SubscriptionMatch) => void;
+    /** Deactivate the event on every open connection of `subject` (matching `match`, when given) where it is allowed. */
+    revoke: (subject: string, match?: SubscriptionMatch) => void;
 }
 /**
  * Event definition interface
@@ -163,11 +184,13 @@ interface EventDef<TPayload = void> {
      */
     filter: (predicate: FramePredicate<TPayload>) => EventDef<TPayload>;
     /**
-     * Subscribe to this event (in-memory handler)
+     * Subscribe to this event (in-memory handler). With the cache transport a
+     * handler runs on every pod for every emit, unless `{ localOnly: true }`
+     * keeps it to emits made in this process.
      */
-    subscribe: (handler: EventHandler<TPayload>) => () => void;
+    subscribe: (handler: EventHandler<TPayload>, options?: EventSubscribeOptions) => () => void;
     /**
-     * Unsubscribe all handlers
+     * Unsubscribe all handlers, `localOnly` ones included
      */
     unsubscribeAll: () => void;
     /**
@@ -181,16 +204,22 @@ interface EventDef<TPayload = void> {
      * Reaches every pod when the cache transport is attached. Never re-runs
      * `canSubscribe`: it is an operator's statement about an open connection.
      * An event the connection never requested cannot be granted.
+     *
+     * With `match`, only the connections whose connect query carries every
+     * field of `match.query` with that value are activated.
      */
-    grant: (subject: string) => Promise<void>;
+    grant: (subject: string, match?: SubscriptionMatch) => Promise<void>;
     /**
      * Deactivate this event on every open SSE connection of `subject` where it
      * is allowed; the client receives a `subscription.revoked` frame.
      *
      * Reaches every pod when the cache transport is attached. Affects open
      * connections only — the next connect asks `canSubscribe` afresh.
+     *
+     * With `match`, only the connections whose connect query carries every
+     * field of `match.query` with that value are deactivated.
      */
-    revoke: (subject: string) => Promise<void>;
+    revoke: (subject: string, match?: SubscriptionMatch) => Promise<void>;
     /**
      * Enable cache-based pub/sub for multi-instance support
      * Must await before emitting events to ensure subscription is ready
@@ -346,4 +375,4 @@ type InferEventPayloads<T extends EventRouterBase<any>> = T['_types'];
  */
 declare function defineEventRouter<TEvents extends Record<string, EventDef<any>>>(events: TEvents): EventRouterDef<TEvents>;
 
-export { type EventRouterDef as E, type FrameContext as F, type InferEventNames as I, type JobQueueSender as J, type PubSubCache as P, type SubscribeContext as S, type EventDef as a, type EventContract as b, type EventHandler as c, type EventRouterContract as d, type FramePredicate as e, type InferEventPayload$1 as f, type InferEventPayloads as g, type InferEventPayload as h, type SubscribePredicate as i, type SubscribeRequest as j, defineEventRouter as k, type EventRouterBase as l };
+export { type EventRouterDef as E, type FrameContext as F, type InferEventNames as I, type JobQueueSender as J, type PubSubCache as P, type SubscribeContext as S, type EventDef as a, type EventContract as b, type EventHandler as c, type EventRouterContract as d, type EventSubscribeOptions as e, type FramePredicate as f, type InferEventPayload$1 as g, type InferEventPayloads as h, type InferEventPayload as i, type SubscribePredicate as j, type SubscribeRequest as k, type SubscriptionMatch as l, defineEventRouter as m, type EventRouterBase as n };

package/dist/server/index.d.ts

@@ -6,9 +6,9 @@ import { NamedMiddleware, Router } from '@spfn/core/route';
 import { OnErrorContext, ProxyGuardConfig, RateLimitOptions } from '@spfn/core/middleware';
 import { SafeFetchPolicy } from '@spfn/core/security';
 import { c as JobRouter, f as BossOptions } from '../boss-BiDCbbAQ.js';
-import { E as EventRouterDef, a as EventDef } from '../router-ZDV1ISTo.js';
-import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-C_g6gD-w.js';
-import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-cwMX0cyJ.js';
+import { E as EventRouterDef, a as EventDef } from '../router-D5B0cpVN.js';
+import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-04gu3uMj.js';
+import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-CqTsDETV.js';
 import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';

package/dist/server/index.js

@@ -475,7 +475,7 @@ function createConnectionRegistry() {
   const bySubject = /* @__PURE__ */ new Map();
   const pendingBySubject = /* @__PURE__ */ new Map();
   const beginAdmission = (subject, signal) => {
-    const changes = /* @__PURE__ */ new Map();
+    const changes = [];
     addToSet(pendingBySubject, subject, changes);
     const end = endOnce(signal, () => removeFromSet(pendingBySubject, subject, changes));
     return {
@@ -490,11 +490,15 @@ function createConnectionRegistry() {
       }
     };
   };
-  const change = (kind, subject, eventName) => {
+  const change = (kind, subject, eventName, match) => {
     const pending = pendingBySubject.get(subject);
     const connections = bySubject.get(subject);
-    pending?.forEach((changes) => changes.set(eventName, kind));
-    connections?.forEach((connection) => (kind === "grant" ? grantOn : revokeOn)(connection, eventName));
+    pending?.forEach((changes) => changes.push({ kind, eventName, match }));
+    connections?.forEach((connection) => {
+      if (matchesRequest(match, connection.request)) {
+        (kind === "grant" ? grantOn : revokeOn)(connection, eventName);
+      }
+    });
     if (!pending && !connections) {
       registryLogger.debug("SSE subscription change for a subject with no open connection ignored", {
         event: eventName,
@@ -512,8 +516,8 @@ function createConnectionRegistry() {
     /** Open connections only — a pending admission is not counted. */
     count: (subject) => bySubject.get(subject)?.size ?? 0,
     pendingCount: (subject) => pendingBySubject.get(subject)?.size ?? 0,
-    grant: (subject, eventName) => change("grant", subject, eventName),
-    revoke: (subject, eventName) => change("revoke", subject, eventName)
+    grant: (subject, eventName, match) => change("grant", subject, eventName, match),
+    revoke: (subject, eventName, match) => change("revoke", subject, eventName, match)
   };
 }
 function endOnce(signal, remove) {
@@ -545,8 +549,14 @@ function removeFromSet(map, key, value) {
     map.delete(key);
   }
 }
+function matchesRequest(match, request) {
+  return match === void 0 || Object.entries(match.query).every(([field, value]) => Object.hasOwn(request.query, field) && request.query[field] === value);
+}
 function applyRecorded(connection, changes) {
-  changes.forEach((kind, eventName) => {
+  changes.forEach(({ kind, eventName, match }) => {
+    if (!matchesRequest(match, connection.request)) {
+      return;
+    }
     const [from, to] = kind === "grant" ? [connection.denied, connection.allowed] : [connection.allowed, connection.denied];
     if (from.delete(eventName)) {
       to.add(eventName);
@@ -635,8 +645,8 @@ function createSSEHandler(router, config = {}, tokenManager) {
 function registerSubscriptionControls(router, registry) {
   for (const eventName of router.eventNames) {
     router.events[eventName]._registerSubscriptionControl({
-      grant: (subject) => registry.grant(subject, eventName),
-      revoke: (subject) => registry.revoke(subject, eventName)
+      grant: (subject, match) => registry.grant(subject, eventName, match),
+      revoke: (subject, match) => registry.revoke(subject, eventName, match)
     });
   }
 }