@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/modules/redis/files/apps/api/src/redis/redis-cache.store.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { RedisClient } from "bun";
 import type {
   CacheSetOptions,
@@ -7,13 +8,19 @@ import type {
 } from "@podosoft/podokit-runtime";
 import type { RedisService } from "./redis.service";
 
-const FIXED_WINDOW_SCRIPT = `
+export const FIXED_WINDOW_SCRIPT = `
 local count = redis.call('INCR', KEYS[1])
 if count == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
 local ttl = redis.call('PTTL', KEYS[1])
 return { count, ttl }
 `;
 
+export const FIXED_WINDOW_SCRIPT_SHA = createHash("sha1").update(FIXED_WINDOW_SCRIPT).digest("hex");
+
+function isMissingScript(error: unknown): boolean {
+  return error instanceof Error && error.message.startsWith("NOSCRIPT");
+}
+
 function resultNumber(value: unknown): number | undefined {
   if (typeof value === "number") return value;
   if (typeof value === "string") {
@@ -35,13 +42,14 @@ export class RedisCacheStore implements CacheStore {
   }
 
   async set(key: string, value: string, options: CacheSetOptions = {}): Promise<void> {
-    await this.client.set(key, value);
-    if (options.ttlMs !== undefined) {
-      if (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 1) {
-        throw new Error("ttlMs must be a positive integer");
-      }
-      await this.client.send("PEXPIRE", [key, String(options.ttlMs)]);
+    if (options.ttlMs === undefined) {
+      await this.client.set(key, value);
+      return;
+    }
+    if (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 1) {
+      throw new Error("ttlMs must be a positive integer");
     }
+    await this.client.set(key, value, "PX", options.ttlMs);
   }
 
   async delete(key: string): Promise<boolean> {
@@ -58,12 +66,7 @@ export class RedisCacheStore implements CacheStore {
     if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
       throw new Error("limit must be a positive integer");
     }
-    const result = await this.client.send("EVAL", [
-      FIXED_WINDOW_SCRIPT,
-      "1",
-      key,
-      String(options.windowMs),
-    ]);
+    const result = await this.runFixedWindow(key, options.windowMs);
     if (!Array.isArray(result)) throw new Error("Redis returned an invalid cache counter");
     const count = resultNumber(result[0]);
     const ttlMs = resultNumber(result[1]);
@@ -78,5 +81,16 @@ export class RedisCacheStore implements CacheStore {
     };
   }
 
+  private async runFixedWindow(key: string, windowMs: number): Promise<unknown> {
+    const args = ["1", key, String(windowMs)];
+    try {
+      return await this.client.send("EVALSHA", [FIXED_WINDOW_SCRIPT_SHA, ...args]);
+    } catch (error) {
+      // Redis forgets scripts on restart, failover, or SCRIPT FLUSH; EVAL reloads it.
+      if (!isMissingScript(error)) throw error;
+      return this.client.send("EVAL", [FIXED_WINDOW_SCRIPT, ...args]);
+    }
+  }
+
   close(): void {}
 }

package/dist/templates/modules/sse/files/apps/api/src/events/event-envelope.ts

@@ -0,0 +1,123 @@
+/** Every listed field must match. Within a list, any entry matches. */
+export interface EventAudience {
+  userIds?: string[];
+  roles?: string[];
+  organizationId?: string;
+}
+
+export interface EventEnvelope<T = unknown> {
+  topic: string;
+  /** Omit to deliver to every stream subscribed to the topic. */
+  audience?: EventAudience;
+  data: T;
+  /** Sent as the SSE `id:`. Defaults to a per-connection sequence number. */
+  id?: string;
+}
+
+/** The identity a stream was opened with, resolved once at connect. */
+export interface EventSubscriber {
+  userId: string;
+  roles: readonly string[];
+  organizationId?: string;
+}
+
+/** Topics and event ids share one charset so they can never break SSE framing. */
+export const EVENT_NAME_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$";
+const EVENT_NAME = new RegExp(EVENT_NAME_PATTERN);
+
+export class InvalidEventError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidEventError";
+  }
+}
+
+export function isEventName(value: unknown): value is string {
+  return typeof value === "string" && EVENT_NAME.test(value);
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function stringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const items: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string" || item.length === 0) return undefined;
+    items.push(item);
+  }
+  return items;
+}
+
+function readAudience(value: unknown): EventAudience | string {
+  const source = record(value);
+  if (!source) return "audience must be an object";
+  const audience: EventAudience = {};
+  if (source.userIds !== undefined) {
+    const userIds = stringList(source.userIds);
+    if (!userIds) return "audience.userIds must be a list of non-empty strings";
+    audience.userIds = userIds;
+  }
+  if (source.roles !== undefined) {
+    const roles = stringList(source.roles);
+    if (!roles) return "audience.roles must be a list of non-empty strings";
+    audience.roles = roles;
+  }
+  if (source.organizationId !== undefined) {
+    if (typeof source.organizationId !== "string" || source.organizationId.length === 0) {
+      return "audience.organizationId must be a non-empty string";
+    }
+    audience.organizationId = source.organizationId;
+  }
+  // An empty audience is almost always a recipient list that failed to resolve;
+  // treating it as a broadcast would leak the event.
+  if (
+    audience.userIds === undefined &&
+    audience.roles === undefined &&
+    audience.organizationId === undefined
+  ) {
+    return "audience must set userIds, roles, or organizationId";
+  }
+  return audience;
+}
+
+/** Normalizes an envelope, or returns why it is invalid. */
+export function readEnvelope(value: unknown): EventEnvelope | string {
+  const source = record(value);
+  if (!source) return "event must be an object";
+  if (!isEventName(source.topic)) return `topic must match ${EVENT_NAME_PATTERN}`;
+  if (source.id !== undefined && !isEventName(source.id)) {
+    return `id must match ${EVENT_NAME_PATTERN}`;
+  }
+  const envelope: EventEnvelope = { topic: source.topic, data: source.data };
+  if (source.id !== undefined) envelope.id = source.id;
+  if (source.audience !== undefined) {
+    const audience = readAudience(source.audience);
+    if (typeof audience === "string") return audience;
+    envelope.audience = audience;
+  }
+  return envelope;
+}
+
+export function validEnvelope(value: EventEnvelope): EventEnvelope {
+  const envelope = readEnvelope(value);
+  if (typeof envelope === "string") throw new InvalidEventError(`Invalid event: ${envelope}`);
+  return envelope;
+}
+
+export type AudienceMatcher = (subscriber: EventSubscriber) => boolean;
+
+export function audienceMatcher(audience: EventAudience | undefined): AudienceMatcher {
+  if (!audience) return () => true;
+  const userIds = audience.userIds ? new Set(audience.userIds) : undefined;
+  const roles = audience.roles ? new Set(audience.roles) : undefined;
+  const organizationId = audience.organizationId;
+  if (!userIds && !roles && organizationId === undefined) return () => false;
+  return (subscriber) =>
+    (!userIds || userIds.has(subscriber.userId)) &&
+    (!roles || subscriber.roles.some((role) => roles.has(role))) &&
+    (organizationId === undefined || subscriber.organizationId === organizationId);
+}

package/dist/templates/modules/sse/files/apps/api/src/events/event-stream.ts

@@ -0,0 +1,191 @@
+import type { EventSubscriber } from "./event-envelope";
+
+export type StreamFrame =
+  | { kind: "event"; id: string; data: string }
+  | { kind: "resync" }
+  | { kind: "heartbeat" };
+
+type EventFrame = Extract<StreamFrame, { kind: "event" }>;
+
+const RESYNC: StreamFrame = { kind: "resync" };
+const HEARTBEAT: StreamFrame = { kind: "heartbeat" };
+
+export interface Scheduler {
+  /** Runs `task` every `intervalMs` until the returned function is called. */
+  every(intervalMs: number, task: () => void): () => void;
+}
+
+export const timerScheduler: Scheduler = {
+  every: (intervalMs, task) => {
+    const timer = setInterval(task, intervalMs);
+    timer.unref();
+    return () => clearInterval(timer);
+  },
+};
+
+export interface EventStreamOptions {
+  queueLimit: number;
+  heartbeatMs: number;
+  maxConnectionMs: number;
+  scheduler: Scheduler;
+  now: () => number;
+}
+
+/**
+ * One subscriber connection. Frames are pulled by the response body, so a slow
+ * client fills the bounded queue; on overflow the backlog is dropped and the
+ * client receives a single `resync` frame telling it to refetch state.
+ */
+export class EventStream {
+  private readonly queue: EventFrame[] = [];
+  private readonly openedAt: number;
+  private readonly onAbort = (): void => this.close();
+  private resyncPending = false;
+  private heartbeatPending = false;
+  private sequence = 0;
+  private closed = false;
+  private waiter?: () => void;
+  private stopHeartbeat?: () => void;
+  private signal?: AbortSignal;
+
+  constructor(
+    readonly subscriber: EventSubscriber,
+    readonly topics: ReadonlySet<string> | undefined,
+    private readonly options: EventStreamOptions,
+    private readonly onClose: (stream: EventStream) => void,
+  ) {
+    this.openedAt = options.now();
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  /** Binds the stream to its request. An already aborted signal closes it at once. */
+  start(signal: AbortSignal): void {
+    if (this.closed) return;
+    if (signal.aborted) {
+      this.close();
+      return;
+    }
+    this.signal = signal;
+    signal.addEventListener("abort", this.onAbort, { once: true });
+    this.stopHeartbeat = this.options.scheduler.every(this.options.heartbeatMs, () => this.tick());
+  }
+
+  offer(data: string, id: string | undefined): void {
+    if (this.closed) return;
+    if (this.queue.length >= this.options.queueLimit) {
+      this.queue.length = 0;
+      this.resyncPending = true;
+    } else {
+      this.queue.push({ kind: "event", id: id ?? String(++this.sequence), data });
+    }
+    this.wake();
+  }
+
+  /** Resolves the next frame, or undefined once the stream is closed. Single consumer. */
+  async next(): Promise<StreamFrame | undefined> {
+    while (!this.closed) {
+      const frame = this.take();
+      if (frame) return frame;
+      await new Promise<void>((resolve) => {
+        this.waiter = resolve;
+      });
+    }
+    return undefined;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.queue.length = 0;
+    this.stopHeartbeat?.();
+    this.stopHeartbeat = undefined;
+    this.signal?.removeEventListener("abort", this.onAbort);
+    this.signal = undefined;
+    this.onClose(this);
+    this.wake();
+  }
+
+  private take(): StreamFrame | undefined {
+    if (this.resyncPending) {
+      this.resyncPending = false;
+      return RESYNC;
+    }
+    const event = this.queue.shift();
+    if (event) {
+      this.heartbeatPending = false;
+      return event;
+    }
+    if (this.heartbeatPending) {
+      this.heartbeatPending = false;
+      return HEARTBEAT;
+    }
+    return undefined;
+  }
+
+  private tick(): void {
+    // The identity was resolved at connect. Ending long-lived streams makes the
+    // client reconnect and re-authenticate, so revoked sessions and roles lapse.
+    if (this.options.now() - this.openedAt >= this.options.maxConnectionMs) {
+      this.close();
+      return;
+    }
+    this.heartbeatPending = true;
+    this.wake();
+  }
+
+  private wake(): void {
+    const waiter = this.waiter;
+    this.waiter = undefined;
+    waiter?.();
+  }
+}
+
+/**
+ * Data events use the default `message` type with `{ topic, data }` as JSON, so
+ * `EventSource.onmessage` keeps working. Control frames use a named event or a
+ * comment and never reach `onmessage`.
+ */
+export function encodeFrame(frame: StreamFrame): string {
+  switch (frame.kind) {
+    case "event":
+      return `id: ${frame.id}\ndata: ${frame.data}\n\n`;
+    case "resync":
+      return "event: resync\ndata: {}\n\n";
+    case "heartbeat":
+      return ": heartbeat\n\n";
+  }
+}
+
+export function eventStreamResponse(stream: EventStream, retryMs: number): Response {
+  const encoder = new TextEncoder();
+  const body = new ReadableStream<Uint8Array>({
+    start(controller): void {
+      controller.enqueue(encoder.encode(`retry: ${retryMs}\n\n`));
+    },
+    async pull(controller): Promise<void> {
+      const frame = await stream.next();
+      if (frame) {
+        controller.enqueue(encoder.encode(encodeFrame(frame)));
+        return;
+      }
+      try {
+        controller.close();
+      } catch {
+        // The body was cancelled while this pull was waiting.
+      }
+    },
+    cancel(): void {
+      stream.close();
+    },
+  });
+  return new Response(body, {
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      "x-accel-buffering": "no",
+    },
+  });
+}

package/dist/templates/modules/sse/files/apps/api/src/events/event-topics.ts

@@ -0,0 +1,64 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { EVENT_NAME_PATTERN, isEventName, type EventSubscriber } from "./event-envelope";
+
+export const MAX_STREAM_TOPICS = 32;
+
+export type TopicAuthorizer = (
+  subscriber: EventSubscriber,
+  topic: string,
+) => boolean | Promise<boolean>;
+
+interface PrefixAuthorizer {
+  prefix: string;
+  authorize: TopicAuthorizer;
+}
+
+/**
+ * Restricts who may subscribe to a topic. A topic without an authorizer is open to
+ * every signed-in user. A pattern ending in `*` guards every topic with that prefix,
+ * and every authorizer that matches a topic must allow the subscriber.
+ */
+export class TopicAuthorizers {
+  private readonly exact = new Map<string, TopicAuthorizer[]>();
+  private readonly prefixes: PrefixAuthorizer[] = [];
+
+  register(pattern: string, authorize: TopicAuthorizer): void {
+    if (pattern.endsWith("*")) {
+      const prefix = pattern.slice(0, -1);
+      if (!isEventName(prefix)) throw new TypeError(`Topic prefix must match ${EVENT_NAME_PATTERN}`);
+      this.prefixes.push({ prefix, authorize });
+      return;
+    }
+    if (!isEventName(pattern)) throw new TypeError(`Topic must match ${EVENT_NAME_PATTERN}`);
+    this.exact.set(pattern, [...(this.exact.get(pattern) ?? []), authorize]);
+  }
+
+  guarded(topic: string): boolean {
+    return this.exact.has(topic) || this.prefixes.some(({ prefix }) => topic.startsWith(prefix));
+  }
+
+  async allows(subscriber: EventSubscriber, topic: string): Promise<boolean> {
+    const authorizers = [
+      ...(this.exact.get(topic) ?? []),
+      ...this.prefixes.filter(({ prefix }) => topic.startsWith(prefix)).map(({ authorize }) => authorize),
+    ];
+    for (const authorize of authorizers) {
+      if (!(await authorize(subscriber, topic))) return false;
+    }
+    return true;
+  }
+}
+
+/** Parses `?topics=a,b`. Undefined means every topic that has no authorizer. */
+export function parseTopics(value: string | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  const topics = [...new Set(value.split(",").map((topic) => topic.trim()).filter(Boolean))];
+  if (topics.length === 0 || topics.length > MAX_STREAM_TOPICS || !topics.every(isEventName)) {
+    throw new AppException(
+      "EVENTS_TOPICS_INVALID",
+      `topics must list 1 to ${MAX_STREAM_TOPICS} comma-separated names matching ${EVENT_NAME_PATTERN}`,
+      400,
+    );
+  }
+  return topics;
+}