@podosoft/podokit 1.1.6 → 1.3.0

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

@@ -1,87 +1,244 @@
-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)}`;
 }
 
-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();
+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: 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();
+  }
+});
+
+function openStream(cookie: string, controller: AbortController): Promise<Response> {
+  return fetch(`${base}/api/events/stream?topics=${uniqueTopic()}`, {
+    headers: { ...origin, cookie },
+    signal: controller.signal,
+  });
+}
+
+test("sse: a user's open streams are capped per replica", async ({ playwright }) => {
+  const member = await newContext(playwright);
+  const other = await newContext(playwright);
+  const controllers: AbortController[] = [];
+  try {
+    test.skip(!(await signUp(member)), "requires the auth module");
+    expect(await signUp(other)).toBeDefined();
+    const cookie = await cookieHeader(member);
+    // The limit is SSE_MAX_STREAMS_PER_USER on the server, so open until refused.
+    let refused: Response | undefined;
+    for (let attempt = 0; attempt < 64 && !refused; attempt += 1) {
+      const controller = new AbortController();
+      const response = await openStream(cookie, controller);
+      if (response.status === 200) controllers.push(controller);
+      else refused = response;
+    }
+    expect(controllers.length).toBeGreaterThan(0);
+    expect(refused?.status).toBe(429);
+    expect((await refused?.json()).error.code).toBe("EVENTS_STREAM_LIMIT");
+
+    // Another user is unaffected, and closing a stream frees its slot.
+    const otherController = new AbortController();
+    controllers.push(otherController);
+    expect((await openStream(await cookieHeader(other), otherController)).status).toBe(200);
+    controllers.shift()?.abort();
+    await expect.poll(async () => {
+      const controller = new AbortController();
+      const response = await openStream(cookie, controller);
+      if (response.status === 200) controllers.push(controller);
+      else controller.abort();
+      return response.status;
+    }, { timeout: 8_000 }).toBe(200);
+  } finally {
+    for (const controller of controllers) controller.abort();
+    await member.dispose();
+    await other.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,19 +6,34 @@
   "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",
-    "SSE_MAX_EVENT_BYTES=65536"
+    "SSE_MAX_EVENT_BYTES=65536",
+    "# Open event streams per user on each API replica",
+    "SSE_MAX_STREAMS_PER_USER=8"
   ],
   "inject": [
     { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { eventsModule } from \"./events/events.module\";" },
     { "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/dist/update.d.ts

@@ -1,5 +1,6 @@
 import { type TemplateVars } from "@podosoft/podokit-template-engine";
 import { type Tier } from "./lockfile";
+import type { ProviderCapability } from "@podosoft/podokit-runtime";
 import type { Toolchain } from "./toolchain";
 /**
  * `podo update` planner. For now it produces a dry-run plan only: it assembles
@@ -17,11 +18,23 @@ export interface FileChange {
     /** Why the action was chosen (for the report). */
     note: string;
 }
+/** A module the target version needs that the project does not record yet. */
+export interface AddedModule {
+    name: string;
+    /** Installed or added module that needs it. */
+    requiredBy: string;
+    /** Provider capability it implements, when added for a capability requirement. */
+    capability?: ProviderCapability;
+    /** Selected provider it implements. */
+    provider?: string;
+}
 export interface UpdatePlan {
     fromVersion: string;
     toVersion: string;
     template: string;
     modules: string[];
+    /** Modules the update adds, ordered ahead of the modules that need them. */
+    addedModules: AddedModule[];
     changes: FileChange[];
 }
 /**
@@ -51,6 +64,8 @@ export interface ApplyOptions {
     abortOnConflict?: boolean;
 }
 export interface ApplyResult {
+    /** Modules added because the target version requires them. */
+    addedModules: string[];
     written: string[];
     /** Files relocated by module update migrations. */
     moved: {
@@ -71,5 +86,7 @@ export interface ApplyResult {
  * stamps the new version.
  */
 export declare function applyUpdate(projectRoot: string, templatesDir: string, options?: ApplyOptions): ApplyResult;
+/** Why an update adds a module, for the plan report. */
+export declare function addedModuleReason(module: AddedModule): string;
 /** Count actions for a one-line summary. */
 export declare function summarize(plan: UpdatePlan): Record<Action, number>;

package/dist/update.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.planUpdate = planUpdate;
 exports.applyUpdate = applyUpdate;
+exports.addedModuleReason = addedModuleReason;
 exports.summarize = summarize;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -25,17 +26,21 @@ function diskContent(projectRoot, path) {
 }
 /**
  * Expand the recorded module list against the target manifests. A module may
- * gain a new requirement after it was first added to a project; updates must
- * apply that requirement before rebuilding the dependent module or the target
- * tree can contain imports and wiring for files that were never installed.
+ * gain a new requirement after it was first added to a project, either another
+ * module or a provider capability. Updates must apply that requirement before
+ * the dependent module: modules configure in this order, and the target tree
+ * would otherwise wire files that were never installed. A capability resolves
+ * to the module implementing the project's selected provider, as `podo add`
+ * would choose it.
  */
-function targetModules(projectRoot, templatesDir, modules) {
+function targetModules(projectRoot, templatesDir, modules, providers) {
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     const recorded = new Map(modules.map((module) => [module.name, module]));
     const ordered = [];
+    const added = [];
     const visiting = new Set();
     const visited = new Set();
-    const visit = (name, requiredBy) => {
+    const visit = (name, requiredBy, capability) => {
         if (visited.has(name))
             return;
         if (visiting.has(name)) {
@@ -52,12 +57,24 @@ function targetModules(projectRoot, templatesDir, modules) {
         const moduleManifest = (0, add_1.readModuleManifest)(resolved.dir);
         for (const required of moduleManifest.requires ?? [])
             visit(required, name);
+        for (const required of moduleManifest.requiresCapabilities ?? []) {
+            visit((0, add_1.selectedProviderModule)(modulesDir, projectRoot, providers, required), name, required);
+        }
         visiting.delete(name);
         visited.add(name);
+        if (!existing && requiredBy) {
+            added.push({
+                name: resolved.name,
+                requiredBy,
+                ...(capability ? { capability, provider: providers[capability] } : {}),
+            });
+        }
         ordered.push({
             ...(existing ?? {
                 name: resolved.name,
                 addedWith: (0, lockfile_1.podokitVersion)(),
+                // A freshly added module ships its current layout, as `podo add` records it.
+                appliedMigrations: (moduleManifest.migrations ?? []).map((migration) => migration.id),
             }),
             order: ordered.length,
             ...(resolved.packageName
@@ -71,7 +88,7 @@ function targetModules(projectRoot, templatesDir, modules) {
     for (const module of [...modules].sort((a, b) => a.order - b.order)) {
         visit(module.name);
     }
-    return ordered;
+    return { modules: ordered, added };
 }
 function targetManagedOverrides(projectRoot, templatesDir, modules, current = []) {
     const overrides = new Set(current);
@@ -102,7 +119,7 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
     const lock = (0, lockfile_1.readFilesLock)(projectRoot);
     if (!manifest || !lock)
         throw new inspect_1.NotAProjectError();
-    const modules = targetModules(projectRoot, templatesDir, manifest.modules);
+    const { modules, added } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
     const newTree = (0, assemble_1.assembleProject)({
         templatesDir,
         template: manifest.template,
@@ -210,6 +227,7 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
         toVersion: (0, lockfile_1.podokitVersion)(),
         template: manifest.template,
         modules: modules.map((module) => module.name),
+        addedModules: added,
         changes,
     };
 }
@@ -333,7 +351,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         forceManagedPaths: options.forceManagedPaths,
         onlyPaths: options.onlyPaths,
     });
-    const modules = targetModules(projectRoot, templatesDir, manifest.modules);
+    const { modules } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
     const newTree = (0, assemble_1.assembleProject)({
         templatesDir,
         template: manifest.template,
@@ -396,6 +414,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         }
     }
     const result = {
+        addedModules: plan.addedModules.map((module) => module.name),
         written: [],
         moved: (0, module_migrations_1.applyModuleMigrations)(projectRoot, migrationPlan),
         removed: [],
@@ -469,6 +488,12 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     });
     return result;
 }
+/** Why an update adds a module, for the plan report. */
+function addedModuleReason(module) {
+    return module.capability
+        ? `${module.capability} provider "${module.provider}" required by ${module.requiredBy}`
+        : `required by ${module.requiredBy}`;
+}
 /** Count actions for a one-line summary. */
 function summarize(plan) {
     const counts = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.1.6",
+  "version": "1.3.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"
   }
 }