@podosoft/podokit 1.1.6 → 1.2.0

package/dist/templates/modules/sse/files/tests/api/events.api.spec.ts

@@ -1,87 +1,198 @@
-import { expect, test } from "@playwright/test";
+import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const secondaryApi = process.env.E2E_SECONDARY_API_URL;
 const origin = { origin: base };
+// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
+// spec also compiles in apps that do not install that module.
+const admin = {
+  email: "admin@example.com",
+  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
+};
 
-async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
-  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+type Playwright = PlaywrightWorkerArgs["playwright"];
+
+interface SessionUser {
+  id: string;
+  roles: string[];
+}
+
+function newContext(playwright: Playwright): Promise<APIRequestContext> {
+  return playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+}
+
+async function sessionUser(ctx: APIRequestContext): Promise<SessionUser | undefined> {
+  const response = await ctx.get("/api/auth/get-session");
+  if (!response.ok()) return undefined;
+  const session = await response.json() as { user?: { id?: string; role?: string | null } } | null;
+  if (!session?.user?.id) return undefined;
+  const roles = (session.user.role ?? "").split(",").map((role) => role.trim()).filter(Boolean);
+  return { id: session.user.id, roles };
+}
+
+/** Resolves undefined when the auth module is missing or sign-up does not start a session. */
+async function signUp(ctx: APIRequestContext): Promise<SessionUser | undefined> {
   const email = `sse-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "E" } }).catch(() => undefined);
-  return ctx;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "E" } });
+  return sessionUser(ctx);
+}
+
+/** Resolves false when no administrator session is available. */
+async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
+  return response.ok() && ((await sessionUser(ctx))?.roles ?? []).includes("admin");
+}
+
+async function cookieHeader(ctx: APIRequestContext): Promise<string> {
+  return (await ctx.storageState()).cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ");
+}
+
+function uniqueTopic(): string {
+  return `spec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+class EventStreamReader {
+  private readonly decoder = new TextDecoder();
+  private buffered = "";
+
+  private constructor(
+    private readonly reader: ReadableStreamDefaultReader<Uint8Array>,
+    private readonly controller: AbortController,
+  ) {}
+
+  /** Opens a stream and waits for its retry hint, which proves the subscription is live. */
+  static async open(ctx: APIRequestContext, topics: string): Promise<EventStreamReader> {
+    const controller = new AbortController();
+    const response = await fetch(`${base}/api/events/stream?topics=${encodeURIComponent(topics)}`, {
+      headers: { ...origin, cookie: await cookieHeader(ctx) },
+      signal: controller.signal,
+    });
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toContain("text/event-stream");
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("event stream has no body");
+    const stream = new EventStreamReader(reader, controller);
+    await stream.until("retry:");
+    return stream;
+  }
+
+  /** Returns everything received up to and including `text`. */
+  async until(text: string, timeoutMs = 8_000): Promise<string> {
+    const deadline = Date.now() + timeoutMs;
+    while (!this.buffered.includes(text)) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw new Error(`timed out waiting for ${text}`);
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<"timeout">((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), remaining);
+      });
+      const result = await Promise.race([this.reader.read(), timeout]);
+      clearTimeout(timer);
+      if (result === "timeout") continue;
+      if (result.done) throw new Error(`stream ended before ${text}`);
+      this.buffered += this.decoder.decode(result.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;
+  }
+
+  close(): void {
+    this.controller.abort();
+  }
 }
 
-test("sse: publish accepts a message", async ({ playwright }) => {
-  const ctx = await session(playwright);
-  const pub = await ctx.post("/api/events", { data: { message: `hi-${Date.now()}` } });
-  expect(pub.ok()).toBeTruthy();
-  expect(await pub.json()).toMatchObject({ ok: true });
-  await ctx.dispose();
+test("sse: streams require a session and a valid topic list", async ({ playwright }) => {
+  const anonymous = await newContext(playwright);
+  const member = await newContext(playwright);
+  try {
+    test.skip(!(await signUp(member)), "requires the auth module");
+    const unauthenticated = await fetch(`${base}/api/events/stream?topics=message`, { headers: origin });
+    expect(unauthenticated.status).toBe(401);
+    const invalid = await member.get("/api/events/stream?topics=bad%20topic");
+    expect(invalid.status()).toBe(400);
+    expect((await invalid.json()).error.code).toBe("EVENTS_TOPICS_INVALID");
+  } finally {
+    await anonymous.dispose();
+    await member.dispose();
+  }
 });
 
-test("sse: a published message is delivered over the event stream @smoke", async ({ playwright }) => {
-  const ctx = await session(playwright);
-  // The stream is behind the auth guard — carry the session cookie on the raw fetch.
-  const cookies = (await ctx.storageState()).cookies.map((c) => `${c.name}=${c.value}`).join("; ");
-  const ac = new AbortController();
-  const stream = await fetch(`${base}/api/events/stream`, { headers: { ...origin, cookie: cookies }, signal: ac.signal }).catch(() => null);
-  test.skip(!stream || !stream.ok || !stream.body, "sse stream not reachable");
-  expect(stream!.headers.get("content-type")).toContain("text/event-stream");
-
-  // Subscriber is attached now; publish, then read until the message arrives.
-  const msg = `sse-${Date.now()}`;
-  await ctx.post("/api/events", { data: { message: msg } });
-
-  const reader = stream!.body!.getReader();
-  const decoder = new TextDecoder();
-  let seen = false;
-  const deadline = Date.now() + 8000;
-  while (Date.now() < deadline && !seen) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    if (decoder.decode(value).includes(msg)) seen = true;
+test("sse: only administrators may publish", async ({ playwright }) => {
+  const member = await newContext(playwright);
+  try {
+    test.skip(!(await signUp(member)), "requires the auth module");
+    const published = await member.post("/api/events", { data: { message: "hello" } });
+    expect(published.status()).toBe(403);
+    expect((await published.json()).error.code).toBe("ADMIN_REQUIRED");
+  } finally {
+    await member.dispose();
+  }
+});
+
+test("sse: an admin publish reaches only the addressed user @smoke", async ({ playwright }) => {
+  const adminCtx = await newContext(playwright);
+  const aliceCtx = await newContext(playwright);
+  const bobCtx = await newContext(playwright);
+  const streams: EventStreamReader[] = [];
+  try {
+    test.skip(!(await signInAdmin(adminCtx)), "requires the auth module and the seeded administrator");
+    const alice = await signUp(aliceCtx);
+    expect(alice).toBeDefined();
+    expect(await signUp(bobCtx)).toBeDefined();
+    const topic = uniqueTopic();
+    const aliceStream = await EventStreamReader.open(aliceCtx, topic);
+    const bobStream = await EventStreamReader.open(bobCtx, topic);
+    streams.push(aliceStream, bobStream);
+
+    const secret = `secret-${Date.now()}`;
+    const done = `done-${Date.now()}`;
+    const targeted = await adminCtx.post("/api/events", {
+      data: { topic, audience: { userIds: [alice?.id] }, message: secret },
+    });
+    expect(targeted.status()).toBe(201);
+    expect(await targeted.json()).toEqual({ ok: true });
+    expect((await adminCtx.post("/api/events", { data: { topic, message: done } })).status()).toBe(201);
+
+    const aliceSaw = await aliceStream.until(done);
+    expect(aliceSaw).toContain(JSON.stringify({ topic, data: { message: secret } }));
+    expect(await bobStream.until(done)).not.toContain(secret);
+  } finally {
+    for (const stream of streams) stream.close();
+    await adminCtx.dispose();
+    await aliceCtx.dispose();
+    await bobCtx.dispose();
   }
-  ac.abort();
-  expect(seen).toBe(true);
-  await ctx.dispose();
 });
 
 test("sse: a second API replica delivers through Redis", async ({ playwright }) => {
   test.skip(!secondaryApi, "a secondary API replica is not configured");
-  const ctx = await session(playwright);
-  const cookies = (await ctx.storageState()).cookies.map((c) => `${c.name}=${c.value}`).join("; ");
-  const ac = new AbortController();
-  const stream = await fetch(`${base}/api/events/stream`, {
-    headers: { ...origin, cookie: cookies },
-    signal: ac.signal,
-  });
-  expect(stream.ok).toBe(true);
-  expect(stream.body).not.toBeNull();
-
-  const msg = `replica-${Date.now()}`;
-  const published = await fetch(`${secondaryApi}/events`, {
-    method: "POST",
-    headers: {
-      ...origin,
-      cookie: cookies,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({ message: msg }),
-  });
-  expect(published.ok).toBe(true);
-
-  const reader = stream.body!.getReader();
-  const decoder = new TextDecoder();
-  let seen = 0;
-  let buffered = "";
-  const deadline = Date.now() + 8000;
-  while (Date.now() < deadline && seen === 0) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    buffered += decoder.decode(value, { stream: true });
-    seen = buffered.split(msg).length - 1;
+  const adminCtx = await newContext(playwright);
+  const memberCtx = await newContext(playwright);
+  let stream: EventStreamReader | undefined;
+  try {
+    test.skip(!(await signInAdmin(adminCtx)), "requires the auth module and the seeded administrator");
+    const member = await signUp(memberCtx);
+    expect(member).toBeDefined();
+    const topic = uniqueTopic();
+    stream = await EventStreamReader.open(memberCtx, topic);
+
+    const message = `replica-${Date.now()}`;
+    const published = await fetch(`${secondaryApi}/events`, {
+      method: "POST",
+      headers: { ...origin, cookie: await cookieHeader(adminCtx), "content-type": "application/json" },
+      body: JSON.stringify({ topic, audience: { userIds: [member?.id] }, message }),
+    });
+    expect(published.status).toBe(201);
+
+    const done = `done-${Date.now()}`;
+    expect((await adminCtx.post("/api/events", { data: { topic, message: done } })).status()).toBe(201);
+    const seen = await stream.until(done);
+    expect(seen.split(message).length - 1).toBe(1);
+  } finally {
+    stream?.close();
+    await adminCtx.dispose();
+    await memberCtx.dispose();
   }
-  ac.abort();
-  expect(seen).toBe(1);
-  await ctx.dispose();
 });

package/dist/templates/modules/sse/module.manifest.json

@@ -6,6 +6,14 @@
   "requiredProjectFiles": [
     "apps/api/src/health/readiness.service.ts"
   ],
+  "requiredProjectContents": {
+    "apps/api/src/core/services.ts": [
+      "isAdmin(request: Request): Promise<boolean>;",
+      "roles(request: Request): Promise<string[]>;",
+      "activeOrganizationId(request: Request): Promise<string | undefined>;",
+      "tryResolve<T>(key: ServiceKey<T>): T | undefined {"
+    ]
+  },
   "targetApp": "api",
   "env": [
     "# Maximum encoded Server-Sent Event payload",
@@ -16,9 +24,14 @@
     { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "eventsModule," }
   ],
   "instructions": [
-    "Stream events:  curl -N localhost:5002/events/stream",
-    "Publish a message (in another terminal):  curl -XPOST localhost:5002/events -H 'content-type: application/json' -d '{\"message\":\"hello\"}'",
-    "Select events=redis for multiple replicas or events=memory for a single process.",
-    "Inject EventsService and call publishAsync for confirmed delivery, publish for best-effort delivery, or publishLocal for events already fanned out to every replica."
+    "Stream as a signed-in user:  curl -N -b cookies.txt 'localhost:5002/events/stream?topics=message'",
+    "Publish as an administrator (in another terminal):  curl -b admin-cookies.txt -XPOST localhost:5002/events -H 'content-type: application/json' -d '{\"message\":\"hello\"}'",
+    "Each data event is a default SSE message whose data is {\"topic\",\"data\"}. A resync event means events were dropped, so reload state.",
+    "Publish from a module with EventsService.publish({ topic, audience, data }). An audience of userIds, roles, or organizationId limits who receives it.",
+    "Use publishAsync for confirmed delivery, publish for best-effort delivery, or publishLocal for events already fanned out to every replica.",
+    "Restrict who may subscribe to a topic with events.topics.register(topic, authorizer).",
+    "Streams take the subscriber's roles and active organization from the request identity. Register EVENT_IDENTITY in app.extensions.ts to derive them differently.",
+    "In the browser, subscribe(topic, handler) from $lib/events shares one EventSource per tab.",
+    "Select events=redis for multiple replicas or events=memory for a single process."
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,7 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@podosoft/podokit-runtime": "^0.2.0",
+    "@podosoft/podokit-runtime": "^0.3.0",
     "@podosoft/podokit-template-engine": "^0.4.2"
   }
 }