@podosoft/podokit 1.1.6 → 1.2.0

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;
+}

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.spec.ts

@@ -0,0 +1,203 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { AppException } from "@podosoft/podokit-contracts";
+import { MemoryEventBus } from "@podosoft/podokit-runtime";
+import { Elysia } from "elysia";
+import type { RequestIdentity } from "../core/services";
+import { ReadinessService } from "../health/readiness.service";
+import { eventsRoutes, requestEventIdentity, type EventIdentity } from "./events.module";
+import { EventsService } from "./events.service";
+
+/** Maps the `x-user`, `x-admin`, `x-roles`, and `x-org` test headers to the request identity. */
+const headerIdentity: RequestIdentity = {
+  userId: async (request) => request.headers.get("x-user") ?? undefined,
+  isAdmin: async (request) => request.headers.get("x-admin") === "true",
+  roles: async (request) => (request.headers.get("x-roles") ?? "").split(",").filter(Boolean),
+  activeOrganizationId: async (request) => request.headers.get("x-org") ?? undefined,
+};
+
+const opened: Array<{ events: EventsService; controllers: AbortController[] }> = [];
+
+async function setup(eventIdentity?: EventIdentity): Promise<{
+  events: EventsService;
+  send: (path: string, init?: RequestInit) => Promise<Response>;
+}> {
+  const events = new EventsService(new MemoryEventBus(), new ReadinessService());
+  await events.connect();
+  const controllers: AbortController[] = [];
+  opened.push({ events, controllers });
+  const app = new Elysia()
+    .onError(({ code, error, set }) => {
+      if (code === "VALIDATION") {
+        set.status = 400;
+        return { code: "VALIDATION_ERROR" };
+      }
+      if (!(error instanceof AppException)) return undefined;
+      set.status = error.statusCode;
+      return { code: error.code };
+    })
+    .use(eventsRoutes(events, headerIdentity, eventIdentity));
+  return {
+    events,
+    send: (path, init = {}) => {
+      const controller = new AbortController();
+      controllers.push(controller);
+      return app.handle(new Request(`http://localhost${path}`, { ...init, signal: controller.signal }));
+    },
+  };
+}
+
+function publish(
+  send: (path: string, init?: RequestInit) => Promise<Response>,
+  headers: Record<string, string>,
+  body: Record<string, unknown>,
+): Promise<Response> {
+  return send("/events", {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(body),
+  });
+}
+
+class SseReader {
+  private readonly reader: ReadableStreamDefaultReader<Uint8Array>;
+  private readonly decoder = new TextDecoder();
+  private buffered = "";
+
+  constructor(response: Response) {
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("missing body");
+    this.reader = reader;
+  }
+
+  /** Reads until `text` arrives and returns everything received up to it. */
+  async until(text: string): Promise<string> {
+    while (!this.buffered.includes(text)) {
+      const { value, done } = await this.reader.read();
+      if (done) throw new Error(`stream ended before ${text}`);
+      this.buffered += this.decoder.decode(value, { stream: true });
+    }
+    const end = this.buffered.indexOf(text) + text.length;
+    const seen = this.buffered.slice(0, end);
+    this.buffered = this.buffered.slice(end);
+    return seen;
+  }
+}
+
+afterEach(async () => {
+  for (const { events, controllers } of opened.splice(0)) {
+    for (const controller of controllers) controller.abort();
+    await events.close();
+  }
+});
+
+describe("events routes", () => {
+  it("requires a signed-in user to stream", async () => {
+    const { send } = await setup();
+    const response = await send("/events/stream");
+    expect(response.status).toBe(401);
+    expect(await response.json()).toEqual({ code: "AUTH_REQUIRED" });
+  });
+
+  it("rejects malformed topic lists", async () => {
+    const { send } = await setup();
+    for (const topics of ["", "a b", Array.from({ length: 33 }, (_, i) => `t${i}`).join(",")]) {
+      const response = await send(`/events/stream?topics=${encodeURIComponent(topics)}`, {
+        headers: { "x-user": "alice" },
+      });
+      expect(response.status).toBe(400);
+      expect(await response.json()).toEqual({ code: "EVENTS_TOPICS_INVALID" });
+    }
+  });
+
+  it("refuses a guarded topic the user may not read", async () => {
+    const { events, send } = await setup();
+    events.topics.register("ops", (subscriber) => subscriber.roles.includes("admin"));
+    const denied = await send("/events/stream?topics=ops", { headers: { "x-user": "alice" } });
+    expect(denied.status).toBe(403);
+    expect(await denied.json()).toEqual({ code: "EVENTS_TOPIC_FORBIDDEN" });
+    const allowed = await send("/events/stream?topics=ops", {
+      headers: { "x-user": "root", "x-admin": "true", "x-roles": "admin" },
+    });
+    expect(allowed.status).toBe(200);
+    expect(allowed.headers.get("content-type")).toContain("text/event-stream");
+  });
+
+  it("lets only administrators publish", async () => {
+    const { send } = await setup();
+    const anonymous = await publish(send, {}, { message: "hi" });
+    expect(anonymous.status).toBe(401);
+    const member = await publish(send, { "x-user": "alice" }, { message: "hi" });
+    expect(member.status).toBe(403);
+    expect(await member.json()).toEqual({ code: "ADMIN_REQUIRED" });
+    const admin = await publish(send, { "x-user": "root", "x-admin": "true" }, { message: "hi" });
+    expect(admin.status).toBe(201);
+    expect(await admin.json()).toEqual({ ok: true });
+  });
+
+  it("rejects an empty or unknown audience field", async () => {
+    const { send } = await setup();
+    const admin = { "x-user": "root", "x-admin": "true" };
+    expect((await publish(send, admin, { message: "x", audience: {} })).status).toBe(400);
+    expect((await publish(send, admin, { message: "x", audience: { team: "a" } })).status).toBe(400);
+    expect((await publish(send, admin, { message: "x", topic: "bad topic" })).status).toBe(400);
+  });
+
+  it("delivers an admin publish only to the addressed user", async () => {
+    const { send } = await setup();
+    const alice = new SseReader(await send("/events/stream?topics=notes", { headers: { "x-user": "alice" } }));
+    const bob = new SseReader(await send("/events/stream?topics=notes", { headers: { "x-user": "bob" } }));
+    expect(await alice.until("\n\n")).toBe("retry: 3000\n\n");
+    expect(await bob.until("\n\n")).toBe("retry: 3000\n\n");
+    const admin = { "x-user": "root", "x-admin": "true" };
+
+    await publish(send, admin, { topic: "notes", audience: { userIds: ["alice"] }, message: "secret" });
+    await publish(send, admin, { topic: "notes", message: "everyone" });
+
+    expect(await alice.until("everyone\"}}\n\n")).toBe(
+      'id: 1\ndata: {"topic":"notes","data":{"message":"secret"}}\n\n' +
+        'id: 2\ndata: {"topic":"notes","data":{"message":"everyone"}}\n\n',
+    );
+    expect(await bob.until("everyone")).not.toContain("secret");
+  });
+
+  it("matches roles and organizations from a registered event identity", async () => {
+    const identity: EventIdentity = {
+      subscriber: async (request) => {
+        const userId = request.headers.get("x-user");
+        if (!userId) return undefined;
+        return { userId, roles: ["member"], organizationId: request.headers.get("x-org") ?? undefined };
+      },
+    };
+    const { send } = await setup(identity);
+    const inside = new SseReader(await send("/events/stream?topics=org", {
+      headers: { "x-user": "a", "x-org": "o1" },
+    }));
+    const outside = new SseReader(await send("/events/stream?topics=org", {
+      headers: { "x-user": "b", "x-org": "o2" },
+    }));
+    const admin = { "x-user": "root", "x-admin": "true" };
+
+    await publish(send, admin, {
+      topic: "org",
+      audience: { organizationId: "o1", roles: ["member"] },
+      message: "o1 only",
+    });
+    await publish(send, admin, { topic: "org", message: "done" });
+
+    expect(await inside.until("done")).toContain("o1 only");
+    expect(await outside.until("done")).not.toContain("o1 only");
+  });
+});
+
+describe("default event identity", () => {
+  it("carries the request roles and active organization", async () => {
+    const identity = requestEventIdentity(headerIdentity);
+    const request = new Request("http://localhost/events/stream", {
+      headers: { "x-user": "u1", "x-roles": "admin,editor", "x-org": "org-1" },
+    });
+    expect(await identity.subscriber(request)).toEqual({ userId: "u1", roles: ["admin", "editor"], organizationId: "org-1" });
+    expect(await identity.subscriber(new Request("http://localhost/events/stream", { headers: { "x-user": "u2" } })))
+      .toEqual({ userId: "u2", roles: [] });
+    expect(await identity.subscriber(new Request("http://localhost/events/stream"))).toBeUndefined();
+  });
+});

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.ts

@@ -1,27 +1,105 @@
 import { AppException } from "@podosoft/podokit-contracts";
 import { EVENTS } from "@podosoft/podokit-runtime";
-import { Elysia, sse, t } from "elysia";
+import { Elysia, t } from "elysia";
 import {
+  READINESS,
+  REQUEST_IDENTITY,
   type AppPlugin,
+  type ElysiaPlugin,
   type PodokitModule,
-  READINESS,
+  type RequestIdentity,
+  type ServiceKey,
 } from "../core/services";
+import {
+  EVENT_NAME_PATTERN,
+  InvalidEventError,
+  type EventEnvelope,
+  type EventSubscriber,
+} from "./event-envelope";
+import { eventStreamResponse } from "./event-stream";
+import { parseTopics } from "./event-topics";
 import { EventsService } from "./events.service";
 
-export const SSE_EVENTS = Symbol("sse-events") as import("../core/services").ServiceKey<EventsService>;
+export const SSE_EVENTS = Symbol("sse-events") as ServiceKey<EventsService>;
+
+/** Resolves who opens a stream. Register one in app.extensions.ts to replace the default. */
+export interface EventIdentity {
+  subscriber(request: Request): Promise<EventSubscriber | undefined>;
+}
+
+export const EVENT_IDENTITY = Symbol("event-identity") as ServiceKey<EventIdentity>;
+
+/** The default identity: the request user with their roles and active organization. */
+export function requestEventIdentity(identity: RequestIdentity): EventIdentity {
+  return {
+    subscriber: async (request) => {
+      const userId = await identity.userId(request);
+      if (!userId) return undefined;
+      const [roles, organizationId] = await Promise.all([
+        identity.roles(request),
+        identity.activeOrganizationId(request),
+      ]);
+      return organizationId === undefined ? { userId, roles } : { userId, roles, organizationId };
+    },
+  };
+}
 
-const eventsPlugin: AppPlugin = ({ services }) => {
-  const events = services.resolve(SSE_EVENTS);
+const nameSchema = t.String({ pattern: EVENT_NAME_PATTERN });
+const idListSchema = t.Array(t.String({ minLength: 1, maxLength: 256 }), { maxItems: 1_000 });
+const audienceSchema = t.Object(
+  {
+    userIds: t.Optional(idListSchema),
+    roles: t.Optional(idListSchema),
+    organizationId: t.Optional(t.String({ minLength: 1, maxLength: 256 })),
+  },
+  { additionalProperties: false, minProperties: 1 },
+);
+
+async function requireAdmin(identity: RequestIdentity, request: Request): Promise<void> {
+  if (!(await identity.userId(request))) {
+    throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+  }
+  if (!(await identity.isAdmin(request))) {
+    throw new AppException("ADMIN_REQUIRED", "Administrator access is required", 403);
+  }
+}
+
+export function eventsRoutes(
+  events: EventsService,
+  identity: RequestIdentity,
+  eventIdentity: EventIdentity = requestEventIdentity(identity),
+): ElysiaPlugin {
   return new Elysia({ name: "podokit.events" })
-    .get("/events/stream", async function* ({ request }) {
-      for await (const data of events.stream(request.signal)) yield sse({ data });
+    .get("/events/stream", async ({ request, query }) => {
+      const subscriber = await eventIdentity.subscriber(request);
+      if (!subscriber) throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+      const stream = await events.open(subscriber, parseTopics(query.topics), request.signal);
+      return eventStreamResponse(stream, events.retryMs);
     }, {
-      detail: { tags: ["events"], summary: "Stream server-sent events" },
+      query: t.Object({ topics: t.Optional(t.String({ maxLength: 4_096 })) }),
+      detail: {
+        tags: ["events"],
+        summary: "Stream server-sent events",
+        description:
+          "Signed-in users only. `topics` is a comma-separated list; without it the stream " +
+          "carries every topic that has no authorizer. Each data event is a default " +
+          "`message` whose data is `{ topic, data }`. A `resync` event means events were " +
+          "dropped and the client should reload its state.",
+      },
     })
-    .post("/events", async ({ body, set }) => {
+    .post("/events", async ({ request, body, set }) => {
+      await requireAdmin(identity, request);
+      const event: EventEnvelope = {
+        topic: body.topic ?? "message",
+        data: { message: body.message },
+        ...(body.audience ? { audience: body.audience } : {}),
+      };
       try {
-        await events.publishAsync({ type: "message", message: body.message });
-      } catch {
+        await events.publishAsync(event);
+      } catch (error) {
+        if (error instanceof InvalidEventError) {
+          throw new AppException("EVENTS_INVALID", error.message, 400);
+        }
         throw new AppException(
           "EVENTS_TRANSPORT_UNAVAILABLE",
           "Event transport is unavailable",
@@ -31,10 +109,25 @@ const eventsPlugin: AppPlugin = ({ services }) => {
       set.status = 201;
       return { ok: true as const };
     }, {
-      body: t.Object({ message: t.String() }),
-      detail: { tags: ["events"], summary: "Publish an event" },
+      body: t.Object({
+        message: t.String({ maxLength: 4_096 }),
+        topic: t.Optional(nameSchema),
+        audience: t.Optional(audienceSchema),
+      }),
+      detail: {
+        tags: ["events"],
+        summary: "Publish an event",
+        description: "Administrators only. Publishes `{ message }` to `topic` (default `message`).",
+      },
     });
-};
+}
+
+const eventsPlugin: AppPlugin = ({ services }) =>
+  eventsRoutes(
+    services.resolve(SSE_EVENTS),
+    services.resolve(REQUEST_IDENTITY),
+    services.tryResolve(EVENT_IDENTITY),
+  );
 
 export const eventsModule: PodokitModule = {
   name: "sse",