@podosoft/podokit 1.1.6 → 1.2.0

package/dist/templates/modules/sse/files/apps/web/src/lib/events.test.ts

@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { EventStreamClient, type StreamMessage } from "./events";
+
+class FakeEventSource extends EventTarget {
+  static instances: FakeEventSource[] = [];
+  closed = false;
+
+  constructor(readonly url: string) {
+    super();
+    FakeEventSource.instances.push(this);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  get topics(): string | null {
+    return new URL(this.url, "http://localhost").searchParams.get("topics");
+  }
+
+  emitOpen(): void {
+    this.dispatchEvent(new Event("open"));
+  }
+
+  emitMessage(topic: string, data: unknown, lastEventId = ""): void {
+    this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ topic, data }), lastEventId }));
+  }
+
+  emitResync(): void {
+    this.dispatchEvent(new MessageEvent("resync", { data: "{}" }));
+  }
+
+  emitError(): void {
+    this.dispatchEvent(new Event("error"));
+  }
+}
+
+function latest(): FakeEventSource {
+  const source = FakeEventSource.instances.at(-1);
+  if (!source) throw new Error("no EventSource was opened");
+  return source;
+}
+
+function recorder(): { handler: (message: StreamMessage) => void; messages: StreamMessage[] } {
+  const messages: StreamMessage[] = [];
+  return { handler: (message) => messages.push(message), messages };
+}
+
+beforeEach(() => {
+  FakeEventSource.instances = [];
+  vi.useFakeTimers();
+  vi.stubGlobal("EventSource", FakeEventSource);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("EventStreamClient", () => {
+  it("shares one EventSource and routes messages by topic", () => {
+    const client = new EventStreamClient();
+    const orders = recorder();
+    const jobs = recorder();
+    client.subscribe("orders", orders.handler);
+    client.subscribe("job-progress", jobs.handler);
+    vi.runOnlyPendingTimers();
+
+    expect(FakeEventSource.instances).toHaveLength(1);
+    expect(latest().url.startsWith("/api/events/stream?")).toBe(true);
+    expect(latest().topics).toBe("job-progress,orders");
+
+    latest().emitOpen();
+    latest().emitMessage("orders", { id: 1 }, "7");
+    latest().emitMessage("unknown", "ignored");
+    latest().dispatchEvent(new MessageEvent("message", { data: "not json" }));
+
+    expect(orders.messages).toEqual([{ resync: false, topic: "orders", id: "7", data: { id: 1 } }]);
+    expect(jobs.messages).toEqual([]);
+  });
+
+  it("keeps the stream across a same-tick resubscribe and closes after the last one leaves", () => {
+    const client = new EventStreamClient();
+    const first = client.subscribe("orders", () => undefined);
+    vi.runOnlyPendingTimers();
+    const source = latest();
+
+    first();
+    const second = client.subscribe("orders", () => undefined);
+    vi.runOnlyPendingTimers();
+    expect(FakeEventSource.instances).toHaveLength(1);
+    expect(source.closed).toBe(false);
+
+    second();
+    second();
+    vi.runOnlyPendingTimers();
+    expect(source.closed).toBe(true);
+    expect(FakeEventSource.instances).toHaveLength(1);
+  });
+
+  it("reconnects for a new topic and resyncs only subscribers that were already live", () => {
+    const client = new EventStreamClient();
+    const orders = recorder();
+    client.subscribe("orders", orders.handler);
+    vi.runOnlyPendingTimers();
+    const first = latest();
+    first.emitOpen();
+    expect(orders.messages).toEqual([]);
+
+    const jobs = recorder();
+    client.subscribe("job-progress", jobs.handler);
+    vi.runOnlyPendingTimers();
+    const second = latest();
+    expect(first.closed).toBe(true);
+    expect(second.topics).toBe("job-progress,orders");
+
+    first.emitMessage("orders", "stale");
+    second.emitOpen();
+    expect(orders.messages).toEqual([{ resync: true, topic: "orders" }]);
+    expect(jobs.messages).toEqual([]);
+  });
+
+  it("does not reconnect when a topic is already on the stream", () => {
+    const client = new EventStreamClient();
+    client.subscribe("orders", () => undefined);
+    vi.runOnlyPendingTimers();
+    latest().emitOpen();
+    const late = recorder();
+    client.subscribe("orders", late.handler);
+    vi.runOnlyPendingTimers();
+    expect(FakeEventSource.instances).toHaveLength(1);
+    latest().emitMessage("orders", 1, "1");
+    expect(late.messages).toEqual([{ resync: false, topic: "orders", id: "1", data: 1 }]);
+  });
+
+  it("passes a server resync to every subscriber", () => {
+    const client = new EventStreamClient();
+    const orders = recorder();
+    const jobs = recorder();
+    client.subscribe("orders", orders.handler);
+    client.subscribe("job-progress", jobs.handler);
+    vi.runOnlyPendingTimers();
+    latest().emitOpen();
+
+    latest().emitResync();
+
+    expect(orders.messages).toEqual([{ resync: true, topic: "orders" }]);
+    expect(jobs.messages).toEqual([{ resync: true, topic: "job-progress" }]);
+  });
+
+  it("reconnects with exponential backoff and resyncs after reconnecting", () => {
+    const client = new EventStreamClient({ minBackoffMs: 1_000, maxBackoffMs: 4_000, random: () => 1 });
+    const orders = recorder();
+    client.subscribe("orders", orders.handler);
+    vi.runOnlyPendingTimers();
+    latest().emitOpen();
+
+    const delays: number[] = [];
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      const failing = latest();
+      failing.emitError();
+      expect(failing.closed).toBe(true);
+      const count = FakeEventSource.instances.length;
+      let waited = 0;
+      while (FakeEventSource.instances.length === count) {
+        vi.advanceTimersByTime(250);
+        waited += 250;
+      }
+      delays.push(waited);
+    }
+    expect(delays).toEqual([1_000, 2_000, 4_000, 4_000]);
+    expect(orders.messages).toEqual([]);
+
+    latest().emitOpen();
+    expect(orders.messages).toEqual([{ resync: true, topic: "orders" }]);
+
+    latest().emitError();
+    vi.advanceTimersByTime(1_000);
+    expect(FakeEventSource.instances).toHaveLength(6);
+  });
+
+  it("stops retrying once every subscriber has left", () => {
+    const client = new EventStreamClient({ random: () => 0 });
+    const unsubscribe = client.subscribe("orders", () => undefined);
+    vi.runOnlyPendingTimers();
+    latest().emitError();
+    unsubscribe();
+    vi.runAllTimers();
+    expect(FakeEventSource.instances).toHaveLength(1);
+  });
+
+  it("isolates a failing subscriber from the others", () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const client = new EventStreamClient();
+    const healthy = recorder();
+    client.subscribe("orders", () => {
+      throw new Error("boom");
+    });
+    client.subscribe("orders", healthy.handler);
+    vi.runOnlyPendingTimers();
+    latest().emitMessage("orders", 1, "1");
+    expect(healthy.messages).toHaveLength(1);
+    expect(error).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects invalid topics and does nothing without EventSource", () => {
+    const client = new EventStreamClient();
+    expect(() => client.subscribe("a,b", () => undefined)).toThrow("Invalid event topic");
+    vi.unstubAllGlobals();
+    vi.stubGlobal("EventSource", undefined);
+    const unsubscribe = client.subscribe("orders", () => undefined);
+    vi.runOnlyPendingTimers();
+    unsubscribe();
+    expect(FakeEventSource.instances).toHaveLength(0);
+  });
+});

package/dist/templates/modules/sse/files/apps/web/src/lib/events.ts

@@ -0,0 +1,207 @@
+// One shared EventSource per tab for the sse module's /events/stream.
+//
+// Subscribe from $effect or onMount so the stream only opens in the browser:
+//
+//   $effect(() => subscribe("job-progress", (message) => {
+//     if (message.resync) void reload();
+//     else progress = message.data;
+//   }));
+//
+// A resync message means events may have been missed (the server dropped a
+// backlog, or the stream reconnected). Reload the state the topic describes.
+
+const EVENT_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+export type StreamMessage =
+  | { resync: false; topic: string; id: string; data: unknown }
+  | { resync: true; topic: string };
+
+export type StreamHandler = (message: StreamMessage) => void;
+
+export interface EventStreamClientOptions {
+  url?: string;
+  minBackoffMs?: number;
+  maxBackoffMs?: number;
+  random?: () => number;
+  createSource?: (url: string) => EventSource;
+}
+
+interface Subscription {
+  topic: string;
+  handler: StreamHandler;
+  /** True once the subscription has been connected; a later reconnect owes it a resync. */
+  live: boolean;
+}
+
+function streamPayload(data: unknown): { topic: string; data: unknown } | undefined {
+  if (typeof data !== "string") return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const { topic, data: payload } = parsed as Record<string, unknown>;
+  return typeof topic === "string" ? { topic, data: payload } : undefined;
+}
+
+export class EventStreamClient {
+  private readonly subscriptions = new Map<string, Set<Subscription>>();
+  private source?: EventSource;
+  private sourceTopics = new Set<string>();
+  private open = false;
+  private attempt = 0;
+  private syncTimer?: ReturnType<typeof setTimeout>;
+  private retryTimer?: ReturnType<typeof setTimeout>;
+
+  constructor(private readonly options: EventStreamClientOptions = {}) {}
+
+  subscribe(topic: string, handler: StreamHandler): () => void {
+    if (!EVENT_NAME.test(topic)) throw new TypeError(`Invalid event topic: ${topic}`);
+    if (!this.options.createSource && typeof EventSource === "undefined") return () => undefined;
+    const subscription: Subscription = {
+      topic,
+      handler,
+      live: this.open && this.sourceTopics.has(topic),
+    };
+    const subscriptions = this.subscriptions.get(topic) ?? new Set<Subscription>();
+    subscriptions.add(subscription);
+    this.subscriptions.set(topic, subscriptions);
+    this.scheduleSync();
+    let subscribed = true;
+    return () => {
+      if (!subscribed) return;
+      subscribed = false;
+      subscriptions.delete(subscription);
+      if (subscriptions.size === 0 && this.subscriptions.get(topic) === subscriptions) {
+        this.subscriptions.delete(topic);
+      }
+      this.scheduleSync();
+    };
+  }
+
+  // Deferred so components that unsubscribe and resubscribe in one tick, or several
+  // components that subscribe together, cause at most one reconnect.
+  private scheduleSync(): void {
+    if (this.syncTimer !== undefined) return;
+    this.syncTimer = setTimeout(() => {
+      this.syncTimer = undefined;
+      this.sync();
+    }, 0);
+  }
+
+  private sync(): void {
+    const topics = [...this.subscriptions.keys()];
+    if (topics.length === 0) {
+      this.stop();
+      return;
+    }
+    // Topics that lost their last subscriber stay on the connection until the next
+    // reconnect; reconnecting only to drop them would cost every other topic a resync.
+    const connecting = this.source !== undefined || this.retryTimer !== undefined;
+    if (connecting && topics.every((topic) => this.sourceTopics.has(topic))) return;
+    this.connect(topics);
+  }
+
+  private connect(topics: string[]): void {
+    this.closeSource();
+    this.clearRetry();
+    this.sourceTopics = new Set(topics);
+    const query = new URLSearchParams({ topics: [...topics].sort().join(",") });
+    const createSource = this.options.createSource ?? ((url: string) => new EventSource(url));
+    const source = createSource(`${this.options.url ?? "/api/events/stream"}?${query}`);
+    this.source = source;
+    source.addEventListener("open", () => {
+      if (this.source === source) this.opened();
+    });
+    source.addEventListener("message", (event) => {
+      if (this.source === source) this.dispatch(event);
+    });
+    source.addEventListener("resync", () => {
+      if (this.source === source) this.resync(false);
+    });
+    source.addEventListener("error", () => {
+      if (this.source === source) this.failed();
+    });
+  }
+
+  private opened(): void {
+    this.open = true;
+    this.attempt = 0;
+    this.resync(true);
+  }
+
+  private resync(reconnected: boolean): void {
+    for (const subscriptions of [...this.subscriptions.values()]) {
+      for (const subscription of [...subscriptions]) {
+        if (!this.sourceTopics.has(subscription.topic)) continue;
+        const owed = !reconnected || subscription.live;
+        subscription.live = true;
+        if (owed) this.notify(subscription, { resync: true, topic: subscription.topic });
+      }
+    }
+  }
+
+  private dispatch(event: MessageEvent): void {
+    const payload = streamPayload(event.data);
+    if (!payload) return;
+    const subscriptions = this.subscriptions.get(payload.topic);
+    if (!subscriptions) return;
+    const message: StreamMessage = {
+      resync: false,
+      topic: payload.topic,
+      id: event.lastEventId,
+      data: payload.data,
+    };
+    for (const subscription of [...subscriptions]) this.notify(subscription, message);
+  }
+
+  // EventSource retries on its own at a fixed interval and gives up for good on an
+  // HTTP error, so close it and retry with exponential backoff instead.
+  private failed(): void {
+    this.closeSource();
+    const minimum = this.options.minBackoffMs ?? 1_000;
+    const maximum = this.options.maxBackoffMs ?? 30_000;
+    const ceiling = Math.min(maximum, minimum * 2 ** this.attempt);
+    const delay = Math.round(ceiling / 2 + (this.options.random ?? Math.random)() * (ceiling / 2));
+    this.attempt += 1;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = undefined;
+      const topics = [...this.subscriptions.keys()];
+      if (topics.length > 0) this.connect(topics);
+    }, delay);
+  }
+
+  private notify(subscription: Subscription, message: StreamMessage): void {
+    try {
+      subscription.handler(message);
+    } catch (error) {
+      console.error(error);
+    }
+  }
+
+  private closeSource(): void {
+    this.source?.close();
+    this.source = undefined;
+    this.open = false;
+  }
+
+  private clearRetry(): void {
+    if (this.retryTimer !== undefined) clearTimeout(this.retryTimer);
+    this.retryTimer = undefined;
+  }
+
+  private stop(): void {
+    this.closeSource();
+    this.clearRetry();
+    this.attempt = 0;
+    this.sourceTopics = new Set();
+  }
+}
+
+export const eventStream = new EventStreamClient();
+
+export function subscribe(topic: string, handler: StreamHandler): () => void {
+  return eventStream.subscribe(topic, handler);
+}