@spfn/core 0.3.0-beta.3 → 0.3.0-beta.30

package/dist/event/sse/index.js

@@ -8,7 +8,15 @@ import { randomBytes, createHash } from 'crypto';
 function createBoundedWriter(stream, maxQueue, onClose) {
   const pending = [];
   let flushing = false;
+  let reserved = 0;
   let closed = false;
+  const overflows = () => {
+    if (pending.length + reserved <= maxQueue) {
+      return false;
+    }
+    onClose("outbound queue overflow (slow consumer)");
+    return true;
+  };
   const flush = async () => {
     if (flushing || closed) {
       return;
@@ -32,11 +40,19 @@ function createBoundedWriter(stream, maxQueue, onClose) {
         return;
       }
       pending.push(frame);
-      if (pending.length > maxQueue) {
-        onClose("outbound queue overflow (slow consumer)");
-        return;
+      if (!overflows()) {
+        void flush();
+      }
+    },
+    reserve() {
+      if (closed) {
+        return false;
       }
-      void flush();
+      reserved++;
+      return !overflows();
+    },
+    clearReserved() {
+      reserved = 0;
     },
     close() {
       closed = true;
@@ -47,6 +63,124 @@ function createBoundedWriter(stream, maxQueue, onClose) {
     }
   };
 }
+var registryLogger = logger.child("@spfn/core:sse");
+var SUBSCRIPTION_GRANTED = "subscription.granted";
+var SUBSCRIPTION_REVOKED = "subscription.revoked";
+function createConnectionRegistry() {
+  const bySubject = /* @__PURE__ */ new Map();
+  const pendingBySubject = /* @__PURE__ */ new Map();
+  const beginAdmission = (subject, signal) => {
+    const changes = [];
+    addToSet(pendingBySubject, subject, changes);
+    const end = endOnce(signal, () => removeFromSet(pendingBySubject, subject, changes));
+    return {
+      cancel: end,
+      open: (connection) => {
+        if (!end()) {
+          return false;
+        }
+        applyRecorded(connection, changes);
+        addToSet(bySubject, subject, connection);
+        return true;
+      }
+    };
+  };
+  const change = (kind, subject, eventName, match) => {
+    const pending = pendingBySubject.get(subject);
+    const connections = bySubject.get(subject);
+    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,
+        subject
+      });
+    }
+  };
+  return {
+    beginAdmission,
+    remove: (connection) => {
+      if (connection.subject) {
+        removeFromSet(bySubject, connection.subject, connection);
+      }
+    },
+    /** 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, match) => change("grant", subject, eventName, match),
+    revoke: (subject, eventName, match) => change("revoke", subject, eventName, match)
+  };
+}
+function endOnce(signal, remove) {
+  let ended = false;
+  const end = () => {
+    if (ended) {
+      return false;
+    }
+    ended = true;
+    signal.removeEventListener("abort", end);
+    remove();
+    return true;
+  };
+  signal.addEventListener("abort", end, { once: true });
+  if (signal.aborted) {
+    end();
+  }
+  return end;
+}
+function addToSet(map, key, value) {
+  const set = map.get(key) ?? /* @__PURE__ */ new Set();
+  set.add(value);
+  map.set(key, set);
+}
+function removeFromSet(map, key, value) {
+  const set = map.get(key);
+  set?.delete(value);
+  if (set?.size === 0) {
+    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, 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);
+    }
+  });
+}
+function grantOn(connection, eventName) {
+  if (!connection.denied.has(eventName)) {
+    return;
+  }
+  connection.unsubscribes.set(eventName, connection.subscribe(eventName));
+  connection.denied.delete(eventName);
+  connection.allowed.add(eventName);
+  connection.notify(SUBSCRIPTION_GRANTED, eventName);
+}
+function revokeOn(connection, eventName) {
+  if (!connection.allowed.has(eventName)) {
+    return;
+  }
+  connection.unsubscribes.get(eventName)?.();
+  connection.unsubscribes.delete(eventName);
+  connection.allowed.delete(eventName);
+  connection.denied.add(eventName);
+  connection.notify(SUBSCRIPTION_REVOKED, eventName);
+}
+function unsubscribeAll(connection) {
+  connection.unsubscribes.forEach((unsubscribe) => unsubscribe());
+  connection.unsubscribes.clear();
+}
 
 // src/event/sse/handler.ts
 var sseLogger = logger.child("@spfn/core:sse");
@@ -77,125 +211,329 @@ function createSSEHandler(router, config = {}, tokenManager) {
     auth: authConfig,
     maxQueue = DEFAULT_MAX_QUEUE
   } = config;
-  return async (c) => {
-    const subject = await authenticateToken(c, tokenManager);
-    if (subject === false) {
-      return c.json({ error: "Missing token parameter" }, 401);
+  const registry = createConnectionRegistry();
+  registerSubscriptionControls(router, registry);
+  const streamConfig = { router, authConfig, registry, pingInterval, maxQueue };
+  const handler = async (c) => {
+    const admission = await admitConnection(c, streamConfig, tokenManager);
+    if (admission instanceof Response) {
+      return admission;
     }
-    if (subject === null) {
-      return c.json({ error: "Invalid or expired token" }, 401);
+    if (c.req.raw.signal.aborted) {
+      admission.pending?.cancel();
+      return new Response(null, { status: 499 });
     }
-    if (subject) {
-      c.set("sseSubject", subject);
-    }
-    const requestedEvents = parseRequestedEvents(c);
-    if (!requestedEvents) {
-      return c.json({ error: "Missing events parameter" }, 400);
-    }
-    const validEventNames = router.eventNames;
-    const invalidEvents = requestedEvents.filter((e) => !validEventNames.includes(e));
-    if (invalidEvents.length > 0) {
-      return c.json({
-        error: "Invalid event names",
-        invalidEvents,
-        validEvents: validEventNames
-      }, 400);
+    c.header("X-Accel-Buffering", "no");
+    return streamSSE(c, (stream) => runStream(c, stream, admission, streamConfig), async (err) => {
+      sseLogger.error("SSE stream error", {
+        error: err.message
+      });
+    });
+  };
+  return Object.assign(handler, {
+    /** @internal Open registered connections of a subject (tests). */
+    _openConnections: (subject) => registry.count(subject),
+    /** @internal Connects of a subject still in admission (tests). */
+    _pendingAdmissions: (subject) => registry.pendingCount(subject)
+  });
+}
+function registerSubscriptionControls(router, registry) {
+  for (const eventName of router.eventNames) {
+    router.events[eventName]._registerSubscriptionControl({
+      grant: (subject, match) => registry.grant(subject, eventName, match),
+      revoke: (subject, match) => registry.revoke(subject, eventName, match)
+    });
+  }
+}
+async function admitConnection(c, config, tokenManager) {
+  const { router, authConfig, registry } = config;
+  const subject = await authenticateToken(c, tokenManager);
+  if (subject === false) {
+    return c.json({ error: "Missing token parameter" }, 401);
+  }
+  if (subject === null) {
+    return c.json({ error: "Invalid or expired token" }, 401);
+  }
+  if (subject) {
+    c.set("sseSubject", subject);
+  }
+  const requested = parseRequestedEvents(c);
+  if (!requested) {
+    return c.json({ error: "Missing events parameter" }, 400);
+  }
+  const validEventNames = router.eventNames;
+  const invalidEvents = requested.filter((e) => !validEventNames.includes(e));
+  if (invalidEvents.length > 0) {
+    return c.json({
+      error: "Invalid event names",
+      invalidEvents,
+      validEvents: validEventNames
+    }, 400);
+  }
+  return whilePending(
+    subject ? registry.beginAdmission(subject, c.req.raw.signal) : void 0,
+    () => authorizeConnection(c, router, authConfig, subject, requested)
+  );
+}
+async function whilePending(pending, check) {
+  let outcome;
+  try {
+    outcome = await check();
+    return outcome instanceof Response ? outcome : { ...outcome, pending };
+  } finally {
+    if (!outcome || outcome instanceof Response) {
+      pending?.cancel();
     }
-    const allowedEvents = await authorizeEvents(subject, requestedEvents, authConfig);
-    if (allowedEvents === null) {
-      return c.json({ error: "Not authorized for any requested events" }, 403);
+  }
+}
+async function authorizeConnection(c, router, authConfig, subject, requested) {
+  const authorized = await authorizeEvents(subject, requested, authConfig);
+  if (authorized === null) {
+    return c.json({ error: "Not authorized for any requested events" }, 403);
+  }
+  const request = { query: c.req.query(), headers: c.req.header() };
+  const resolved = await resolveConnectionPrincipal(subject, request, authConfig);
+  if (!resolved) {
+    return c.json({ error: "Principal could not be resolved" }, 403);
+  }
+  const allowed = subject ? await checkCanSubscribe(router, authorized, { subject, principal: resolved.principal, request }) : authorized;
+  const denied = requested.filter((e) => !allowed.includes(e));
+  sseLogger.debug("SSE connection requested", {
+    events: allowed,
+    deniedEvents: denied,
+    subject: subject || void 0,
+    clientIp: c.req.header("x-forwarded-for") || c.req.header("x-real-ip")
+  });
+  return { subject, requested, allowed, denied, request, principal: resolved.principal };
+}
+async function resolveConnectionPrincipal(subject, request, authConfig) {
+  if (!subject || !authConfig?.resolvePrincipal) {
+    return { principal: void 0 };
+  }
+  try {
+    return { principal: await authConfig.resolvePrincipal(subject, request) };
+  } catch {
+    sseLogger.warn("SSE principal could not be resolved \u2014 connection refused", { subject });
+    return null;
+  }
+}
+async function checkCanSubscribe(router, events, ctx) {
+  const verdicts = await Promise.all(events.map((eventName) => askCanSubscribe(eventName, router.events[eventName], ctx)));
+  return events.filter((_, i) => verdicts[i]);
+}
+async function askCanSubscribe(eventName, eventDef, ctx) {
+  if (!eventDef) {
+    return false;
+  }
+  if (!eventDef._canSubscribe) {
+    return true;
+  }
+  try {
+    return await eventDef._canSubscribe(ctx) === true;
+  } catch {
+    sseLogger.warn("SSE canSubscribe threw \u2014 event denied on this connection", {
+      event: eventName,
+      subject: ctx.subject
+    });
+    return false;
+  }
+}
+async function runStream(c, stream, admission, config) {
+  const { allowed, denied, subject, request } = admission;
+  let connectionDead = false;
+  let pingTimer;
+  let onClosed;
+  const cleanup = (reason) => {
+    if (connectionDead) return;
+    connectionDead = true;
+    clearInterval(pingTimer);
+    unsubscribeAll(connection);
+    config.registry.remove(connection);
+    writer.close();
+    onClosed?.();
+    sseLogger.info("SSE dead connection cleaned up", {
+      events: [...connection.allowed],
+      reason
+    });
+  };
+  const writer = createBoundedWriter(stream, config.maxQueue, (reason) => {
+    sseLogger.warn("SSE connection closed", { events: [...connection.allowed], reason });
+    cleanup(reason);
+  });
+  const hold = createFrameHold(writer);
+  const subscriberContext = {
+    router: config.router,
+    authConfig: config.authConfig,
+    subject,
+    request,
+    writeFrame: createFrameWriter(writer),
+    send: hold.send,
+    isDead: () => connectionDead
+  };
+  const connection = {
+    subject,
+    requested: admission.requested,
+    allowed: new Set(allowed),
+    denied: new Set(denied),
+    unsubscribes: /* @__PURE__ */ new Map(),
+    request,
+    subscribe: createEventSubscriber(subscriberContext),
+    notify: (frame, eventName) => {
+      if (connectionDead) return;
+      hold.send(() => writer.enqueue({ event: frame, data: JSON.stringify({ event: eventName }) }));
     }
-    sseLogger.debug("SSE connection requested", {
-      events: allowedEvents,
-      subject: subject || void 0,
-      clientIp: c.req.header("x-forwarded-for") || c.req.header("x-real-ip")
+  };
+  if (admission.pending?.open(connection) === false) {
+    cleanup("aborted during admission");
+    return;
+  }
+  void openSubscriptions(connection, writer, hold, {
+    ...subscriberContext,
+    principal: admission.principal
+  });
+  pingTimer = setInterval(() => {
+    if (connectionDead) return;
+    hold.send(() => writer.enqueue({
+      event: "ping",
+      data: JSON.stringify({ timestamp: Date.now() })
+    }));
+  }, config.pingInterval);
+  await waitForDisconnect(c.req.raw.signal, () => connectionDead, (resolve) => {
+    onClosed = resolve;
+  });
+  cleanup();
+}
+async function openSubscriptions(connection, writer, hold, ctx) {
+  const connected = { subscribedEvents: [...connection.allowed], deniedEvents: [...connection.denied] };
+  const producing = connected.subscribedEvents.filter((eventName) => ctx.router.events[eventName]._initial);
+  if (!ctx.subject || producing.length === 0) {
+    enqueueConnected(writer, { ...connected, initial: [] });
+    subscribeAllowed(connection);
+    return;
+  }
+  hold.hold();
+  subscribeAllowed(connection);
+  const served = await produceInitialFrames(producing, ctx.router, {
+    subject: ctx.subject,
+    principal: ctx.principal,
+    request: ctx.request
+  });
+  if (ctx.isDead()) {
+    return;
+  }
+  enqueueConnected(writer, { ...connected, initial: served.map(({ eventName }) => eventName) });
+  served.forEach(({ eventName, frames }) => frames.forEach((data) => ctx.writeFrame(eventName, data)));
+  hold.release();
+}
+function enqueueConnected(writer, connected) {
+  writer.enqueue({
+    event: "connected",
+    data: JSON.stringify({ ...connected, timestamp: Date.now() })
+  });
+}
+function subscribeAllowed(connection) {
+  for (const eventName of connection.allowed) {
+    connection.unsubscribes.set(eventName, connection.subscribe(eventName));
+  }
+  sseLogger.info("SSE connection established", {
+    events: [...connection.allowed],
+    deniedEvents: [...connection.denied],
+    subscriptionCount: connection.unsubscribes.size
+  });
+}
+async function produceInitialFrames(events, router, ctx) {
+  const results = await Promise.all(events.map((eventName) => askInitial(eventName, router.events[eventName], ctx)));
+  return results.filter((frames) => frames !== null);
+}
+async function askInitial(eventName, eventDef, ctx) {
+  try {
+    const payloads = await eventDef._initial(ctx);
+    return { eventName, frames: payloads.map((payload) => serializeFrame(eventName, payload)) };
+  } catch {
+    sseLogger.warn("SSE initial frames could not be produced \u2014 none sent for this event", {
+      event: eventName,
+      subject: ctx.subject
     });
-    c.header("X-Accel-Buffering", "no");
-    return streamSSE(c, async (stream) => {
-      const unsubscribes = [];
-      let messageId = 0;
-      let connectionDead = false;
-      let pingTimer;
-      let writer;
-      let onClosed;
-      const cleanup = (reason) => {
-        if (connectionDead) return;
-        connectionDead = true;
-        clearInterval(pingTimer);
-        unsubscribes.forEach((fn) => fn());
-        writer?.close();
-        onClosed?.();
-        sseLogger.info("SSE dead connection cleaned up", {
-          events: allowedEvents,
-          reason
-        });
-      };
-      writer = createBoundedWriter(stream, maxQueue, (reason) => {
-        sseLogger.warn("SSE connection closed", { events: allowedEvents, reason });
-        cleanup(reason);
-      });
-      writer.enqueue({
-        event: "connected",
-        data: JSON.stringify({
-          subscribedEvents: allowedEvents,
-          timestamp: Date.now()
-        })
-      });
-      for (const eventName of allowedEvents) {
-        const eventDef = router.events[eventName];
-        if (!eventDef) {
-          continue;
-        }
-        const unsubscribe = eventDef.subscribe((payload) => {
-          if (connectionDead) return;
-          if (subject && authConfig?.filter?.[eventName]) {
-            if (!authConfig.filter[eventName](subject, payload)) {
-              return;
-            }
-          }
-          messageId++;
-          sseLogger.debug("SSE sending event", {
-            event: eventName,
-            messageId
-          });
-          writer.enqueue({
-            id: String(messageId),
-            event: eventName,
-            data: serializeFrame(eventName, payload)
-          });
-        });
-        unsubscribes.push(unsubscribe);
+    return null;
+  }
+}
+function createFrameHold(writer) {
+  let pending = null;
+  return {
+    send: (write) => {
+      if (!pending) {
+        write();
+      } else if (writer.reserve()) {
+        pending.push(write);
       }
-      sseLogger.info("SSE connection established", {
-        events: allowedEvents,
-        subscriptionCount: unsubscribes.length
-      });
-      pingTimer = setInterval(() => {
-        if (connectionDead) return;
-        writer.enqueue({
-          event: "ping",
-          data: JSON.stringify({ timestamp: Date.now() })
-        });
-      }, pingInterval);
-      const abortSignal = c.req.raw.signal;
-      if (!abortSignal.aborted && !connectionDead) {
-        await new Promise((resolve) => {
-          const onAbort = () => resolve();
-          abortSignal.addEventListener("abort", onAbort, { once: true });
-          onClosed = () => {
-            abortSignal.removeEventListener("abort", onAbort);
-            resolve();
-          };
-        });
+    },
+    hold: () => {
+      pending = [];
+    },
+    release: () => {
+      const held = pending ?? [];
+      pending = null;
+      writer.clearReserved();
+      held.forEach((write) => write());
+    }
+  };
+}
+function createFrameWriter(writer) {
+  let messageId = 0;
+  return (eventName, data) => {
+    messageId++;
+    sseLogger.debug("SSE sending event", {
+      event: eventName,
+      messageId
+    });
+    writer.enqueue({ id: String(messageId), event: eventName, data });
+  };
+}
+async function waitForDisconnect(abortSignal, isDead, onServerClose) {
+  if (abortSignal.aborted || isDead()) {
+    return;
+  }
+  await new Promise((resolve) => {
+    const onAbort = () => resolve();
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    onServerClose(() => {
+      abortSignal.removeEventListener("abort", onAbort);
+      resolve();
+    });
+  });
+}
+function createEventSubscriber(ctx) {
+  return (eventName) => {
+    const eventDef = ctx.router.events[eventName];
+    let active = true;
+    const unsubscribe = eventDef.subscribe((payload) => {
+      if (!active || ctx.isDead() || !passesFrameFilters(eventName, eventDef, payload, ctx)) {
+        return;
       }
-      cleanup();
-    }, async (err) => {
-      sseLogger.error("SSE stream error", {
-        error: err.message
-      });
+      const data = serializeFrame(eventName, payload);
+      ctx.send(() => ctx.writeFrame(eventName, data));
     });
+    return () => {
+      active = false;
+      unsubscribe();
+    };
   };
 }
+function passesFrameFilters(eventName, eventDef, payload, ctx) {
+  const globalFilter = ctx.authConfig?.filter?.[eventName];
+  if (ctx.subject && globalFilter && !globalFilter(ctx.subject, payload)) {
+    return false;
+  }
+  if (!eventDef._filter) {
+    return true;
+  }
+  try {
+    return eventDef._filter(payload, { subject: ctx.subject, request: ctx.request }) === true;
+  } catch {
+    sseLogger.warn("SSE event filter threw \u2014 frame dropped", { event: eventName, subject: ctx.subject });
+    return false;
+  }
+}
 async function authenticateToken(c, tokenManager) {
   if (!tokenManager) {
     return void 0;
@@ -211,7 +549,7 @@ function parseRequestedEvents(c) {
   if (!eventsParam) {
     return null;
   }
-  return eventsParam.split(",").map((e) => e.trim());
+  return [...new Set(eventsParam.split(",").map((e) => e.trim()))];
 }
 async function authorizeEvents(subject, requestedEvents, authConfig) {
   if (!subject || !authConfig?.authorize) {