@spfn/core 0.3.0-beta.32 → 0.3.0-beta.34

package/dist/event/sse/index.js

@@ -66,22 +66,33 @@ function createBoundedWriter(stream, maxQueue, onClose) {
 var registryLogger = logger.child("@spfn/core:sse");
 var SUBSCRIPTION_GRANTED = "subscription.granted";
 var SUBSCRIPTION_REVOKED = "subscription.revoked";
+var KEY_REVOKED = "key revoked";
 function createConnectionRegistry() {
   const bySubject = /* @__PURE__ */ new Map();
+  const byKey = /* @__PURE__ */ new Map();
   const pendingBySubject = /* @__PURE__ */ new Map();
-  const beginAdmission = (subject, signal) => {
+  const pendingByKey = /* @__PURE__ */ new Map();
+  const beginAdmission = (subject, keyId, signal) => {
     const changes = [];
     addToSet(pendingBySubject, subject, changes);
-    const end = endOnce(signal, () => removeFromSet(pendingBySubject, subject, changes));
+    addToOptionalSet(pendingByKey, keyId, changes);
+    const end = endOnce(signal, () => {
+      removeFromSet(pendingBySubject, subject, changes);
+      removeFromOptionalSet(pendingByKey, keyId, changes);
+    });
     return {
       cancel: end,
       open: (connection) => {
         if (!end()) {
-          return false;
+          return "aborted during admission";
+        }
+        if (changes.some((change2) => change2.kind === "close")) {
+          return KEY_REVOKED;
         }
         applyRecorded(connection, changes);
         addToSet(bySubject, subject, connection);
-        return true;
+        addToOptionalSet(byKey, connection.keyId, connection);
+        return null;
       }
     };
   };
@@ -101,15 +112,25 @@ function createConnectionRegistry() {
       });
     }
   };
+  const closeByKey = (keyId) => {
+    const connections = [...byKey.get(keyId) ?? []];
+    pendingByKey.get(keyId)?.forEach((changes) => changes.push({ kind: "close" }));
+    connections.forEach((connection) => connection.close(KEY_REVOKED));
+    return connections.length;
+  };
   return {
     beginAdmission,
+    closeByKey,
     remove: (connection) => {
       if (connection.subject) {
         removeFromSet(bySubject, connection.subject, connection);
       }
+      removeFromOptionalSet(byKey, connection.keyId, connection);
     },
     /** Open connections only — a pending admission is not counted. */
     count: (subject) => bySubject.get(subject)?.size ?? 0,
+    /** Open connections whose token was minted with `keyId`. */
+    countByKey: (keyId) => byKey.get(keyId)?.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)
@@ -137,6 +158,16 @@ function addToSet(map, key, value) {
   set.add(value);
   map.set(key, set);
 }
+function addToOptionalSet(map, key, value) {
+  if (key) {
+    addToSet(map, key, value);
+  }
+}
+function removeFromOptionalSet(map, key, value) {
+  if (key) {
+    removeFromSet(map, key, value);
+  }
+}
 function removeFromSet(map, key, value) {
   const set = map.get(key);
   set?.delete(value);
@@ -148,10 +179,11 @@ 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)) {
+  changes.forEach((change) => {
+    if (change.kind === "close" || !matchesRequest(change.match, connection.request)) {
       return;
     }
+    const { kind, eventName } = change;
     const [from, to] = kind === "grant" ? [connection.denied, connection.allowed] : [connection.allowed, connection.denied];
     if (from.delete(eventName)) {
       to.add(eventName);
@@ -181,6 +213,24 @@ function unsubscribeAll(connection) {
   connection.unsubscribes.forEach((unsubscribe) => unsubscribe());
   connection.unsubscribes.clear();
 }
+var keyCloseLogger = logger.child("@spfn/core:sse");
+var REGISTRIES_KEY = Symbol.for("@spfn/core:sse-key-close-registries");
+var registries = globalThis[REGISTRIES_KEY] ??= /* @__PURE__ */ new Set();
+function registerKeyCloseRegistry(registry) {
+  registries.add(registry);
+}
+function applyKeyClose(keyId) {
+  let closed = 0;
+  registries.forEach((registry) => {
+    closed += registry.closeByKey(keyId);
+  });
+  if (closed > 0) {
+    keyCloseLogger.info("SSE connections closed", { count: closed, reason: "key revoked" });
+  } else {
+    keyCloseLogger.debug("SSE key close reached no open connection", { reason: "key revoked" });
+  }
+  return closed;
+}
 
 // src/event/sse/handler.ts
 var sseLogger = logger.child("@spfn/core:sse");
@@ -213,6 +263,7 @@ function createSSEHandler(router, config = {}, tokenManager) {
   } = config;
   const registry = createConnectionRegistry();
   registerSubscriptionControls(router, registry);
+  registerKeyCloseRegistry(registry);
   const streamConfig = { router, authConfig, registry, pingInterval, maxQueue };
   const handler = async (c) => {
     const admission = await admitConnection(c, streamConfig, tokenManager);
@@ -234,7 +285,9 @@ function createSSEHandler(router, config = {}, tokenManager) {
     /** @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)
+    _pendingAdmissions: (subject) => registry.pendingCount(subject),
+    /** @internal Open registered connections whose token was minted with a key (tests). */
+    _openConnectionsByKey: (keyId) => registry.countByKey(keyId)
   });
 }
 function registerSubscriptionControls(router, registry) {
@@ -246,17 +299,37 @@ function registerSubscriptionControls(router, registry) {
   }
 }
 async function admitConnection(c, config, tokenManager) {
-  const { router, authConfig, registry } = config;
-  const subject = await authenticateToken(c, tokenManager);
-  if (subject === false) {
+  const token = await takeToken(c, tokenManager);
+  if (token === false) {
     return c.json({ error: "Missing token parameter" }, 401);
   }
-  if (subject === null) {
-    return c.json({ error: "Invalid or expired token" }, 401);
+  if (token === null) {
+    return invalidToken(c);
+  }
+  return whilePending(
+    token?.subject ? config.registry.beginAdmission(token.subject, token.keyId, c.req.raw.signal) : void 0,
+    () => checkConnection(c, config, token, tokenManager)
+  );
+}
+function invalidToken(c) {
+  return c.json({ error: "Invalid or expired token" }, 401);
+}
+async function checkConnection(c, config, token, tokenManager) {
+  if (token && tokenManager && !await tokenManager.checkKey(token)) {
+    return invalidToken(c);
   }
+  const subject = token?.subject;
   if (subject) {
     c.set("sseSubject", subject);
   }
+  const requested = validateRequestedEvents(c, config.router);
+  if (requested instanceof Response) {
+    return requested;
+  }
+  const authorized = await authorizeConnection(c, config.router, config.authConfig, subject, requested);
+  return authorized instanceof Response ? authorized : { ...authorized, keyId: token?.keyId };
+}
+function validateRequestedEvents(c, router) {
   const requested = parseRequestedEvents(c);
   if (!requested) {
     return c.json({ error: "Missing events parameter" }, 400);
@@ -270,10 +343,7 @@ async function admitConnection(c, config, tokenManager) {
       validEvents: validEventNames
     }, 400);
   }
-  return whilePending(
-    subject ? registry.beginAdmission(subject, c.req.raw.signal) : void 0,
-    () => authorizeConnection(c, router, authConfig, subject, requested)
-  );
+  return requested;
 }
 async function whilePending(pending, check) {
   let outcome;
@@ -372,6 +442,7 @@ async function runStream(c, stream, admission, config) {
   };
   const connection = {
     subject,
+    keyId: admission.keyId,
     requested: admission.requested,
     allowed: new Set(allowed),
     denied: new Set(denied),
@@ -381,10 +452,12 @@ async function runStream(c, stream, admission, config) {
     notify: (frame, eventName) => {
       if (connectionDead) return;
       hold.send(() => writer.enqueue({ event: frame, data: JSON.stringify({ event: eventName }) }));
-    }
+    },
+    close: cleanup
   };
-  if (admission.pending?.open(connection) === false) {
-    cleanup("aborted during admission");
+  const refusal = admission.pending?.open(connection);
+  if (refusal) {
+    cleanup(refusal);
     return;
   }
   void openSubscriptions(connection, writer, hold, {
@@ -534,7 +607,7 @@ function passesFrameFilters(eventName, eventDef, payload, ctx) {
     return false;
   }
 }
-async function authenticateToken(c, tokenManager) {
+async function takeToken(c, tokenManager) {
   if (!tokenManager) {
     return void 0;
   }
@@ -542,7 +615,7 @@ async function authenticateToken(c, tokenManager) {
   if (!token) {
     return false;
   }
-  return await tokenManager.verify(token);
+  return tokenManager.take(token);
 }
 function parseRequestedEvents(c) {
   const eventsParam = c.req.query("events");
@@ -561,6 +634,7 @@ async function authorizeEvents(subject, requestedEvents, authConfig) {
   }
   return allowed;
 }
+var tokenLogger = logger.child("@spfn/core:sse");
 function hashToken(token) {
   return createHash("sha256").update(token).digest("hex");
 }
@@ -623,10 +697,12 @@ var CacheTokenStore = class {
 var SSETokenManager = class {
   store;
   ttl;
+  verifyKey;
   cleanupTimer = null;
   constructor(config) {
     this.ttl = config?.ttl ?? 3e4;
     this.store = config?.store ?? new InMemoryTokenStore();
+    this.verifyKey = config?.verifyKey;
     const cleanupInterval = config?.cleanupInterval ?? 6e4;
     this.cleanupTimer = setInterval(() => void this.store.cleanup(), cleanupInterval);
     this.cleanupTimer.unref();
@@ -641,13 +717,16 @@ var SSETokenManager = class {
     return this.ttl;
   }
   /**
-   * Issue a new one-time-use token for the given subject
+   * Issue a new one-time-use token for the given subject. `keyId` tags it
+   * with the device key it is minted for; an empty one leaves it untagged.
    */
-  async issue(subject) {
+  async issue(subject, options) {
     const token = randomBytes(32).toString("hex");
+    const keyId = options?.keyId || void 0;
     await this.store.set(token, {
       subject,
-      expiresAt: Date.now() + this.ttl
+      expiresAt: Date.now() + this.ttl,
+      ...keyId ? { keyId } : {}
     });
     return token;
   }
@@ -656,11 +735,43 @@ var SSETokenManager = class {
    * @returns subject string if valid, null if invalid/expired/already consumed
    */
   async verify(token) {
+    return (await this.consume(token))?.subject ?? null;
+  }
+  /**
+   * Consume a token and answer what it was minted with: `null` when it is
+   * unknown, expired, already consumed, or its key no longer holds
+   * (`verifyKey`). The token is gone either way. `take` + `checkKey`.
+   */
+  async consume(token) {
+    const data = await this.take(token);
+    return data && await this.checkKey(data) ? data : null;
+  }
+  /**
+   * The store half of `consume`: take the token out of the store and answer
+   * what it was minted with, `null` when it is unknown, expired or already
+   * consumed — its key is not checked yet (`checkKey`). For a caller that
+   * has to register the connection before the key check, so a revocation
+   * landing during the check reaches it.
+   */
+  async take(token) {
     const data = await this.store.consume(token);
-    if (!data || data.expiresAt <= Date.now()) {
-      return null;
+    return data && data.expiresAt > Date.now() ? data : null;
+  }
+  /**
+   * The key half of `consume`: `verifyKey` on a tagged token; an untagged
+   * one, or no verifier, holds without a call. A throw refuses and is warned
+   * without its text — it may carry what the verifier read.
+   */
+  async checkKey(data) {
+    if (!data.keyId || !this.verifyKey) {
+      return true;
+    }
+    try {
+      return await this.verifyKey(data.keyId) === true;
+    } catch {
+      tokenLogger.warn("SSE token key check threw \u2014 token refused");
+      return false;
     }
-    return data.subject;
   }
   /**
    * Cleanup timer and resources
@@ -672,7 +783,305 @@ var SSETokenManager = class {
     }
   }
 };
+var transportLogger = logger.child("@spfn/core:event-transport");
+var DEFAULT_CHANNEL_PREFIX = "spfn:sse:";
+var PUBLISH_TIMEOUT_MS = 5e3;
+var SUBSCRIBE_TIMEOUT_MS = 5e3;
+var WARN_THROTTLE_MS = 3e4;
+var PUBLISH_BREAKER_COOLDOWN_MS = 1e4;
+var KEY_CLOSE_RETRY_MS = PUBLISH_BREAKER_COOLDOWN_MS + 500;
+var PENDING_KEY_CLOSE_CAP = 1e3;
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
+var warnThrottle = /* @__PURE__ */ new Map();
+function throttledWarn(key, message, fields) {
+  const now = Date.now();
+  const entry = warnThrottle.get(key);
+  if (entry && now - entry.last < WARN_THROTTLE_MS) {
+    entry.suppressed++;
+    return;
+  }
+  transportLogger.warn(message, entry && entry.suppressed > 0 ? { ...fields, suppressedSinceLast: entry.suppressed } : fields);
+  warnThrottle.set(key, { last: now, suppressed: 0 });
+}
+var STATE_KEY = Symbol.for("@spfn/core:event-transport");
+var state = globalThis[STATE_KEY] ??= {
+  pubSubCache: void 0,
+  subscriber: void 0,
+  channelPrefix: void 0,
+  wired: /* @__PURE__ */ new Map(),
+  keyCloseDeferrals: /* @__PURE__ */ new Map()
+};
+function createKeyCloseDeferral(resend) {
+  const pending = /* @__PURE__ */ new Map();
+  let timer;
+  let flushing = false;
+  let disposed = false;
+  const arm = () => {
+    if (timer || disposed) {
+      return;
+    }
+    timer = setTimeout(() => {
+      timer = void 0;
+      void flush();
+    }, KEY_CLOSE_RETRY_MS);
+    timer.unref?.();
+  };
+  const disarm = () => {
+    clearTimeout(timer);
+    timer = void 0;
+  };
+  const flush = async () => {
+    if (flushing || pending.size === 0) {
+      return;
+    }
+    flushing = true;
+    const snapshot = [...pending.values()];
+    pending.clear();
+    for (const message of snapshot) {
+      await resend(message);
+    }
+    flushing = false;
+    if (pending.size > 0) {
+      arm();
+    } else {
+      disarm();
+    }
+  };
+  return {
+    defer: (message) => {
+      if (disposed) {
+        return;
+      }
+      pending.delete(message.keyId);
+      pending.set(message.keyId, message);
+      dropOldestPastCap(pending);
+      throttledWarn("key-close-deferred", "SSE key close deferred \u2014 re-sent when the pub/sub transport recovers", {
+        channel: CONTROL_CHANNEL,
+        pending: pending.size
+      });
+      arm();
+    },
+    flush,
+    dispose: () => {
+      disposed = true;
+      disarm();
+      pending.clear();
+    },
+    keyIds: () => [...pending.keys()]
+  };
+}
+function dropOldestPastCap(pending) {
+  const dropped = pending.size - PENDING_KEY_CLOSE_CAP;
+  if (dropped <= 0) {
+    return;
+  }
+  [...pending.keys()].slice(0, dropped).forEach((keyId) => pending.delete(keyId));
+  throttledWarn("key-close-dropped", "SSE key closes dropped \u2014 too many waiting to be re-sent", { dropped });
+}
+function resolveChannelPrefix(override) {
+  return process.env.SPFN_SSE_CHANNEL_PREFIX ?? DEFAULT_CHANNEL_PREFIX;
+}
+function createRedisPubSubCache(client, channelPrefix, onSubscriber) {
+  let subscriber;
+  const handlers = /* @__PURE__ */ new Map();
+  let degradedUntil = 0;
+  const ensureSubscriber = () => {
+    if (subscriber) {
+      return subscriber;
+    }
+    subscriber = client.duplicate();
+    onSubscriber?.(subscriber);
+    subscriber.on("message", (channel, raw) => {
+      const handler = handlers.get(channel);
+      if (!handler) {
+        return;
+      }
+      let payload;
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        transportLogger.warn("Pub/sub message parse failed \u2014 dropped", { channel });
+        return;
+      }
+      void handler(payload);
+    });
+    subscriber.on("error", (err) => {
+      throttledWarn("subscriber-error", "Pub/sub subscriber error", { error: err.message });
+    });
+    return subscriber;
+  };
+  const subscriberHealthy = () => !!subscriber && (subscriber.status === void 0 || subscriber.status === "ready");
+  const deliverLocal = (channel, message) => {
+    const handler = handlers.get(channel);
+    if (handler) {
+      void handler(message);
+    }
+  };
+  let keyCloses;
+  const deferIfKeyClose = (name, message) => {
+    if (name === CONTROL_CHANNEL && isKeyCloseMessage(message)) {
+      keyCloses.defer(message);
+    }
+  };
+  const cache = {
+    publish: async (name, message) => {
+      const channel = channelPrefix + name;
+      let serialized;
+      try {
+        serialized = JSON.stringify(message ?? null);
+      } catch (err) {
+        transportLogger.warn("Pub/sub payload serialization failed \u2014 local delivery only", {
+          channel,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        deliverLocal(channel, message ?? null);
+        return;
+      }
+      if (serialized === void 0) {
+        transportLogger.warn("Pub/sub payload not serializable (function/symbol) \u2014 local delivery only", {
+          channel
+        });
+        deliverLocal(channel, message ?? null);
+        return;
+      }
+      const ready = client.status === void 0 || client.status === "ready";
+      const now = Date.now();
+      if (!ready || degradedUntil > 0 && now < degradedUntil) {
+        deferIfKeyClose(name, message);
+        deliverLocal(channel, JSON.parse(serialized));
+        return;
+      }
+      if (degradedUntil > 0) {
+        degradedUntil = now + PUBLISH_TIMEOUT_MS;
+      }
+      try {
+        await withTimeout(client.publish(channel, serialized), PUBLISH_TIMEOUT_MS, "pub/sub publish");
+        degradedUntil = 0;
+        void keyCloses.flush();
+        if (!subscriberHealthy()) {
+          throttledWarn("subscriber-down", "Subscriber connection down \u2014 same-pod local fallback", {
+            channel
+          });
+          deliverLocal(channel, JSON.parse(serialized));
+        }
+      } catch {
+        degradedUntil = Date.now() + PUBLISH_BREAKER_COOLDOWN_MS;
+        throttledWarn(`publish-failed:${channel}`, "Pub/sub publish failed \u2014 local delivery only", { channel });
+        deferIfKeyClose(name, message);
+        deliverLocal(channel, JSON.parse(serialized));
+      }
+    },
+    subscribe: async (name, handler) => {
+      const channel = channelPrefix + name;
+      const sub = ensureSubscriber();
+      try {
+        await withTimeout(sub.subscribe(channel), SUBSCRIBE_TIMEOUT_MS, "pub/sub subscribe");
+      } catch (err) {
+        if (handlers.size === 0 && subscriber === sub) {
+          subscriber = void 0;
+          void sub.quit?.().catch(() => void 0);
+        }
+        throw err;
+      }
+      handlers.set(channel, handler);
+    }
+  };
+  keyCloses = createKeyCloseDeferral((message) => cache.publish(CONTROL_CHANNEL, message));
+  state.keyCloseDeferrals.set(cache, keyCloses);
+  return cache;
+}
+var CONTROL_CHANNEL = "$control";
+var controlBindings = /* @__PURE__ */ new WeakMap();
+function ensureControlBinding(cache) {
+  let binding = controlBindings.get(cache);
+  if (!binding) {
+    binding = {
+      origin: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`,
+      events: /* @__PURE__ */ new Map(),
+      subscribing: void 0
+    };
+    controlBindings.set(cache, binding);
+  }
+  return binding;
+}
+function isKeyCloseMessage(message) {
+  const candidate = message;
+  return !!candidate && candidate.kind === "close" && typeof candidate.keyId === "string" && candidate.keyId !== "" && typeof candidate.origin === "string";
+}
+async function publishKeyClose(cache, keyId) {
+  const message = { kind: "close", keyId, origin: ensureControlBinding(cache).origin };
+  await cache.publish(CONTROL_CHANNEL, message).catch(() => {
+    throttledWarn("key-close-publish-failed", "SSE key close publish failed \u2014 closed on this pod only", {
+      channel: CONTROL_CHANNEL
+    });
+  });
+}
+async function resolveEventPubSubCache() {
+  return state.pubSubCache ?? await resolvePubSubCache();
+}
+async function resolvePubSubCache(channelPrefix) {
+  const resolvedPrefix = resolveChannelPrefix();
+  if (state.pubSubCache) {
+    if (state.channelPrefix !== resolvedPrefix) {
+      transportLogger.warn("Conflicting channelPrefix ignored \u2014 the transport prefix is process-global (first wiring wins).", {
+        active: state.channelPrefix,
+        ignored: resolvedPrefix
+      });
+    }
+    return state.pubSubCache;
+  }
+  let client;
+  try {
+    const { getCache } = await import('@spfn/core/cache');
+    client = getCache();
+  } catch {
+    return void 0;
+  }
+  if (!client) {
+    return void 0;
+  }
+  if (!process.env.SPFN_SSE_CHANNEL_PREFIX) {
+    transportLogger.warn(
+      "Event fan-out is on the default channel prefix (spfn:sse:). Apps sharing one Redis must set channelPrefix or SPFN_SSE_CHANNEL_PREFIX to avoid cross-app leakage."
+    );
+  }
+  state.channelPrefix = resolvedPrefix;
+  state.pubSubCache = createRedisPubSubCache(
+    client,
+    resolvedPrefix,
+    (connection) => {
+      state.subscriber = connection;
+    }
+  );
+  return state.pubSubCache;
+}
+
+// src/event/sse/close-by-key.ts
+async function closeSSEConnectionsByKey(keyId) {
+  applyKeyClose(keyId);
+  const cache = await resolveEventPubSubCache();
+  if (cache) {
+    await publishKeyClose(cache, keyId);
+  }
+}
 
-export { CacheTokenStore, SSETokenManager, createSSEHandler };
+export { CacheTokenStore, SSETokenManager, closeSSEConnectionsByKey, createSSEHandler };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map