@podosoft/podokit 1.3.0 → 1.4.1

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -35,6 +35,12 @@
       "file": "apps/api/src/app.ts",
       "marker": "// podokit:end:modules",
       "text": "rateLimitModule,"
+    },
+    {
+      "file": "AGENTS.md",
+      "marker": "<!-- podokit:end:agents-modules -->",
+      "optional": true,
+      "text": "### rate-limit\n- Every request counts against a per-caller budget (general, `/api/auth`, or runtime reads); exceeded limits return 429 `RATE_LIMIT_EXCEEDED` with `Retry-After`.\n- Give routes that legitimately send many requests, such as upload chunks, their own budget instead of raising `RATE_LIMIT_MAX`: `services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method: \"PUT\", pathPrefix: \"/uploads\", profile: { name: \"uploads\", limit: 3000 } })` (`RATE_LIMIT_ROUTES` from `@podosoft/podokit-runtime`). Register from a module's `plugin` factory or `configureServices()` in `app.extensions.ts`; the most specific prefix wins, and `profile: \"exempt\"` skips limiting.\n- Prefixes are API paths (`/uploads`, not the web proxy's `/api/uploads`); Better Auth routes keep `/api/auth`.\n"
     }
   ],
   "instructions": [
@@ -47,6 +53,7 @@
     "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Cache failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
     "Register a RateLimitIdentityExtension under RATE_LIMIT_IDENTITY_EXTENSION in app.extensions.ts for another validated machine-key source.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",
+    "Give a route its own budget or exempt it with services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method, pathPrefix, profile }) from a module's plugin factory or configureServices() in app.extensions.ts; the most specific prefix wins.",
     "Redis counters are shared across replicas; memory counters require one API replica."
   ]
 }

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

@@ -1,9 +1,11 @@
+import type { RedisClient } from "bun";
 import { describe, expect, it, mock } from "bun:test";
 import {
   FIXED_WINDOW_SCRIPT,
   FIXED_WINDOW_SCRIPT_SHA,
   RedisCacheStore,
 } from "./redis-cache.store";
+import { RedisCommandTimeoutError } from "../config/redis.connection";
 import { RedisService } from "./redis.service";
 
 const redisUrl = process.env.REDIS_TEST_URL;
@@ -13,7 +15,7 @@ type Send = (command: string, args: string[]) => Promise<unknown>;
 type SetValue = (key: string, value: string, ...options: Array<string | number>) => Promise<"OK">;
 
 function storeWith(client: { send?: Send; set?: SetValue }): RedisCacheStore {
-  return new RedisCacheStore({ client } as unknown as RedisService);
+  return new RedisCacheStore(new RedisService(() => client as unknown as RedisClient));
 }
 
 function redisError(message: string): Error {
@@ -75,6 +77,17 @@ describe("RedisCacheStore set", () => {
     ]);
   });
 
+  it("fails a write Redis does not answer within the command timeout", async () => {
+    const set = mock<SetValue>(() => new Promise<"OK">(() => undefined));
+    const close = mock(() => undefined);
+    const store = new RedisCacheStore(
+      new RedisService(() => ({ set, close }) as unknown as RedisClient, 50),
+    );
+
+    await expect(store.set("key", "value")).rejects.toBeInstanceOf(RedisCommandTimeoutError);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
   it("rejects an invalid TTL before writing", async () => {
     const set = mock<SetValue>(async () => "OK");
     const store = storeWith({ set });

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

@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto";
-import type { RedisClient } from "bun";
 import type {
   CacheSetOptions,
   CacheStore,
@@ -30,26 +29,24 @@ function resultNumber(value: unknown): number | undefined {
   return undefined;
 }
 
+/** Every command is bounded by `REDIS_COMMAND_TIMEOUT_MS` through `RedisService.command`. */
 export class RedisCacheStore implements CacheStore {
-  private readonly client: RedisClient;
-
-  constructor(private readonly redis: RedisService) {
-    this.client = redis.client;
-  }
+  constructor(private readonly redis: RedisService) {}
 
   get(key: string): Promise<string | null> {
     return this.redis.get(key);
   }
 
   async set(key: string, value: string, options: CacheSetOptions = {}): Promise<void> {
-    if (options.ttlMs === undefined) {
-      await this.client.set(key, value);
+    const ttlMs = options.ttlMs;
+    if (ttlMs === undefined) {
+      await this.redis.command((client) => client.set(key, value));
       return;
     }
-    if (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 1) {
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 1) {
       throw new Error("ttlMs must be a positive integer");
     }
-    await this.client.set(key, value, "PX", options.ttlMs);
+    await this.redis.command((client) => client.set(key, value, "PX", ttlMs));
   }
 
   async delete(key: string): Promise<boolean> {
@@ -84,11 +81,11 @@ 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]);
+      return await this.redis.command((client) => 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]);
+      return this.redis.command((client) => client.send("EVAL", [FIXED_WINDOW_SCRIPT, ...args]));
     }
   }
 

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

@@ -1,3 +1,4 @@
+import { AppException } from "@podosoft/podokit-contracts";
 import { Elysia, t } from "elysia";
 import { CACHE } from "@podosoft/podokit-runtime";
 import { PROVIDERS } from "../config/providers";
@@ -12,12 +13,22 @@ import { RedisCacheStore } from "./redis-cache.store";
 
 export const REDIS = Symbol("redis") as ServiceKey<RedisService>;
 
+/** Answers 503 CACHE_UNAVAILABLE while Redis cannot be reached; other Redis errors stay 500. */
+async function withCache<T>(redis: RedisService, run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (!redis.isUnavailable(error)) throw error;
+    throw new AppException("CACHE_UNAVAILABLE", "The cache is temporarily unavailable.", 503);
+  }
+}
+
 const cachePlugin: AppPlugin = ({ services }) => {
   if (PROVIDERS.cache !== "redis") return new Elysia({ name: "podokit.redis.inactive" });
   const redis = services.resolve(REDIS);
   return new Elysia({ name: "podokit.redis" })
     .put("/cache/:key", async ({ params, body }) => {
-      await redis.set(params.key, body.value, body.ttl);
+      await withCache(redis, () => redis.set(params.key, body.value, body.ttl));
       return { key: params.key };
     }, {
       params: t.Object({ key: t.String({ minLength: 1 }) }),
@@ -29,7 +40,7 @@ const cachePlugin: AppPlugin = ({ services }) => {
     })
     .get("/cache/:key", async ({ params }) => ({
       key: params.key,
-      value: await redis.get(params.key),
+      value: await withCache(redis, () => redis.get(params.key)),
     }), {
       params: t.Object({ key: t.String({ minLength: 1 }) }),
       detail: { tags: ["cache"], summary: "Read a cache value" },
@@ -40,10 +51,11 @@ export const redisModule: PodokitModule = {
   name: "redis",
   configure: (_env, services): void => {
     if (PROVIDERS.cache !== "redis") return;
-    const redis = new RedisService(services.resolve(READINESS));
+    const redis = new RedisService();
     services.register(REDIS, redis, () => redis.close());
     services.register(CACHE, new RedisCacheStore(redis));
-    services.onStart(() => redis.connect());
+    services.resolve(READINESS).register("redis", () => redis.ping());
+    services.supervise("redis", redis);
   },
   plugin: cachePlugin,
 };

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.service.spec.ts

@@ -1,23 +1,230 @@
+import type { RedisClient } from "bun";
 import { describe, expect, it } from "bun:test";
-import { ReadinessService } from "../health/readiness.service";
+import { RedisCommandTimeoutError } from "../config/redis.connection";
 import { RedisService } from "./redis.service";
 
+type Listener = (message: string, channel: string) => void;
+
+/**
+ * One Redis server shared by fake clients: it can go down, and it drops every
+ * connection when it does. While paused it keeps connections open and answers nothing.
+ */
+class FakeRedis {
+  up = true;
+  paused = false;
+  readonly values = new Map<string, string>();
+  readonly clients: FakeClient[] = [];
+
+  client(): RedisClient {
+    const client = new FakeClient(this);
+    this.clients.push(client);
+    return client as unknown as RedisClient;
+  }
+
+  stop(): void {
+    this.up = false;
+    for (const client of this.clients) client.drop();
+  }
+
+  publish(channel: string, message: string): number {
+    let receivers = 0;
+    for (const client of this.clients) {
+      if (!client.connected || !client.channels.has(channel)) continue;
+      receivers += 1;
+      client.listener?.(message, channel);
+    }
+    return receivers;
+  }
+}
+
+class FakeClient {
+  connected = false;
+  onclose: ((error: Error) => void) | null = null;
+  readonly channels = new Set<string>();
+  listener?: Listener;
+  private readonly pending = new Set<(error: Error) => void>();
+
+  constructor(private readonly server: FakeRedis) {}
+
+  /** Answers with `value` unless disconnected, or never while the server is paused; closing fails it. */
+  private reply<T>(value: () => T): Promise<T> {
+    if (!this.connected) return Promise.reject(new Error("Connection closed"));
+    if (!this.server.paused) return Promise.resolve(value());
+    return new Promise<T>((_resolve, reject) => {
+      this.pending.add(reject);
+    });
+  }
+
+  get(key: string): Promise<string | null> {
+    return this.reply(() => this.server.values.get(key) ?? null);
+  }
+
+  set(key: string, value: string): Promise<"OK"> {
+    return this.reply(() => {
+      this.server.values.set(key, value);
+      return "OK" as const;
+    });
+  }
+
+  connect(): Promise<void> {
+    if (!this.server.up) {
+      this.onclose?.(new Error("Connection closed"));
+      return Promise.reject(new Error("Connection closed"));
+    }
+    this.connected = true;
+    return Promise.resolve();
+  }
+
+  ping(): Promise<string> {
+    return this.reply(() => "PONG");
+  }
+
+  subscribe(channels: string | string[], listener: Listener): Promise<number> {
+    if (!this.connected) return Promise.reject(new Error("Connection closed"));
+    for (const channel of [channels].flat()) this.channels.add(channel);
+    this.listener = listener;
+    return Promise.resolve(this.channels.size);
+  }
+
+  unsubscribe(channel: string): Promise<void> {
+    this.channels.delete(channel);
+    return Promise.resolve();
+  }
+
+  drop(): void {
+    if (!this.connected) return;
+    // Bun forgets the server subscription but keeps its listener.
+    this.connected = false;
+    this.channels.clear();
+    this.onclose?.(new Error("Connection closed"));
+  }
+
+  close(): void {
+    if (!this.connected) return;
+    this.connected = false;
+    for (const reject of this.pending) reject(new Error("Connection closed"));
+    this.pending.clear();
+    this.onclose?.(new Error("Connection closed"));
+  }
+}
+
+describe("RedisService commands", () => {
+  it("fails a command Redis does not answer and hands the connection to the supervisor", async () => {
+    const server = new FakeRedis();
+    const service = new RedisService(() => server.client(), 50);
+    const lost: unknown[] = [];
+    service.onLost((reason) => { lost.push(reason); });
+    await service.connect();
+    await service.set("greeting", "hi");
+
+    server.paused = true;
+    const started = Date.now();
+    const error = await service.get("greeting").then(() => undefined, (reason: unknown) => reason);
+
+    expect(error).toBeInstanceOf(RedisCommandTimeoutError);
+    expect(Date.now() - started).toBeLessThan(1_000);
+    expect(service.isUnavailable(error)).toBe(true);
+    expect(service.client.connected).toBe(false);
+    expect(lost.length).toBe(1);
+    await expect(service.get("greeting")).rejects.toThrow("Connection closed");
+
+    server.paused = false;
+    await service.connect();
+    await expect(service.get("greeting")).resolves.toBe("hi");
+    expect(service.isUnavailable(new Error("WRONGTYPE Operation against a key"))).toBe(false);
+    service.close();
+  });
+
+  it("fails a reconnect attempt that Redis accepts but does not answer", async () => {
+    const server = new FakeRedis();
+    server.paused = true;
+    const service = new RedisService(() => server.client(), 50);
+
+    await expect(service.connect()).rejects.toBeInstanceOf(RedisCommandTimeoutError);
+    expect(service.client.connected).toBe(false);
+    service.close();
+  });
+});
+
+describe("RedisService subscriptions", () => {
+  it("subscribes once Redis becomes reachable after starting without it", async () => {
+    const server = new FakeRedis();
+    server.up = false;
+    const service = new RedisService(() => server.client());
+    const received: string[] = [];
+    await service.subscribe("orders", (message) => { received.push(message); });
+
+    await expect(service.connect()).rejects.toThrow("Connection closed");
+    server.up = true;
+    await service.connect();
+
+    expect(server.publish("orders", "created")).toBe(1);
+    expect(received).toEqual(["created"]);
+    service.close();
+  });
+
+  it("reports a dropped connection and restores every subscription on reconnect", async () => {
+    const server = new FakeRedis();
+    const service = new RedisService(() => server.client());
+    const lost: unknown[] = [];
+    service.onLost((reason) => { lost.push(reason); });
+    await service.connect();
+    const received: string[] = [];
+    await service.subscribe("orders", (message) => { received.push(`orders:${message}`); });
+    await service.subscribe("users", (message) => { received.push(`users:${message}`); });
+
+    server.stop();
+    expect(lost.length).toBeGreaterThan(0);
+    await expect(service.connect()).rejects.toThrow("Connection closed");
+    server.up = true;
+    await service.connect();
+
+    expect(server.publish("orders", "1")).toBe(1);
+    expect(server.publish("users", "2")).toBe(1);
+    expect(received).toEqual(["orders:1", "users:2"]);
+    service.close();
+  });
+
+  it("stops delivering after the last handler of a channel unsubscribes", async () => {
+    const server = new FakeRedis();
+    const service = new RedisService(() => server.client());
+    await service.connect();
+    const received: string[] = [];
+    const unsubscribe = await service.subscribe("orders", (message) => { received.push(message); });
+
+    await unsubscribe();
+    expect(server.publish("orders", "late")).toBe(0);
+    expect(received).toEqual([]);
+    service.close();
+  });
+
+  it("does not report connections it closes itself", async () => {
+    const server = new FakeRedis();
+    const service = new RedisService(() => server.client());
+    const lost: unknown[] = [];
+    service.onLost((reason) => { lost.push(reason); });
+    await service.connect();
+
+    service.close();
+    expect(lost).toEqual([]);
+  });
+});
+
 const redisUrl = process.env.REDIS_TEST_URL;
 const integrationTest = redisUrl ? it : it.skip;
 
 describe("RedisService integration", () => {
-  integrationTest("uses authenticated settings and registers readiness", async () => {
+  integrationTest("uses authenticated settings and answers pings", async () => {
     const previousUrl = process.env.REDIS_URL;
     process.env.REDIS_URL = redisUrl;
-    const readiness = new ReadinessService();
-    const service = new RedisService(readiness);
+    const service = new RedisService();
     const key = `podokit:test:${Date.now()}:${Math.random().toString(36).slice(2)}`;
 
     try {
       await service.connect();
       await service.set(key, "value", 10);
       await expect(service.get(key)).resolves.toBe("value");
-      await expect(readiness.run()).resolves.toEqual({ redis: "up" });
+      await expect(service.ping()).resolves.toBeUndefined();
       await service.del(key);
     } finally {
       service.close();
@@ -25,4 +232,25 @@ describe("RedisService integration", () => {
       else process.env.REDIS_URL = previousUrl;
     }
   });
+
+  integrationTest("delivers a published message to a subscriber", async () => {
+    const previousUrl = process.env.REDIS_URL;
+    process.env.REDIS_URL = redisUrl;
+    const service = new RedisService();
+    const channel = `podokit:test:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+
+    try {
+      await service.connect();
+      const received = new Promise<string>((resolve) => {
+        void service.subscribe(channel, resolve);
+      });
+      await Bun.sleep(50);
+      await service.publish(channel, "hello");
+      await expect(received).resolves.toBe("hello");
+    } finally {
+      service.close();
+      if (previousUrl === undefined) delete process.env.REDIS_URL;
+      else process.env.REDIS_URL = previousUrl;
+    }
+  });
 });

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.service.ts

@@ -1,62 +1,164 @@
 import { RedisClient } from "bun";
-import { redisConnectionUrl } from "../config/redis.connection";
-import { ReadinessService } from "../health/readiness.service";
+import {
+  RedisCommandTimeoutError,
+  redisCommandTimeoutMs,
+  redisConnectionUrl,
+  withReplyTimeout,
+} from "../config/redis.connection";
+import type { SupervisedConnection } from "../core/services";
 
-export class RedisService {
+export type RedisMessageHandler = (message: string) => void;
+
+/**
+ * Commands fail at once while the client is disconnected instead of queueing,
+ * and the service's supervisor reconnects instead of Bun, which gives up after
+ * a fixed number of attempts and never restores subscriptions.
+ */
+export function createRedisClient(): RedisClient {
+  return new RedisClient(redisConnectionUrl(), {
+    connectionTimeout: 5_000,
+    autoReconnect: false,
+    enableOfflineQueue: false,
+  });
+}
+
+export class RedisService implements SupervisedConnection {
   readonly client: RedisClient;
-  private readonly subscribers: RedisClient[] = [];
-  private unregisterReadiness?: () => void;
+  private readonly channels = new Map<string, Set<RedisMessageHandler>>();
+  // Channels the current subscriber connection holds on the server.
+  private readonly active = new Set<string>();
+  private subscriber?: RedisClient;
+  private opening?: Promise<RedisClient>;
+  private lostListener?: (reason: unknown) => void;
+  private closed = false;
+
+  constructor(
+    private readonly createClient: () => RedisClient = createRedisClient,
+    private readonly commandTimeoutMs = redisCommandTimeoutMs(),
+  ) {
+    this.client = createClient();
+    this.client.onclose = (error) => this.report(error);
+  }
 
-  constructor(private readonly readiness?: ReadinessService) {
-    this.client = new RedisClient(redisConnectionUrl(), {
-      connectionTimeout: 5_000,
-      enableOfflineQueue: false,
-      maxRetries: 1,
-    });
+  onLost(listener: (reason: unknown) => void): void {
+    this.lostListener = listener;
   }
 
+  /** Opens the command connection and restores every subscription. */
   async connect(): Promise<void> {
     if (!this.client.connected) await this.client.connect();
-    await this.client.ping();
-    this.unregisterReadiness ??= this.readiness?.register("redis", async () => {
-      await this.client.ping();
-    });
+    await this.ping();
+    if (this.channels.size > 0) await this.listen();
+  }
+
+  /**
+   * Runs `send` on the command connection. When Redis does not answer within
+   * `REDIS_COMMAND_TIMEOUT_MS`, it fails with `RedisCommandTimeoutError` and the
+   * connection is closed and reopened by the supervisor. Use it for commands
+   * this service does not wrap, instead of calling `client` directly.
+   */
+  async command<T>(send: (client: RedisClient) => Promise<T>): Promise<T> {
+    return withReplyTimeout(send(this.client), this.commandTimeoutMs, () => this.client.close());
+  }
+
+  /** Whether a failed command means Redis could not be reached, rather than that it refused the command. */
+  isUnavailable(error: unknown): boolean {
+    return error instanceof RedisCommandTimeoutError || !this.client.connected;
+  }
+
+  async ping(): Promise<void> {
+    await this.command((client) => client.ping());
   }
 
   get(key: string): Promise<string | null> {
-    return this.client.get(key);
+    return this.command((client) => client.get(key));
   }
 
   async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
-    await this.client.set(key, value);
-    if (ttlSeconds !== undefined) await this.client.expire(key, ttlSeconds);
+    await this.command((client) => client.set(key, value));
+    if (ttlSeconds !== undefined) await this.command((client) => client.expire(key, ttlSeconds));
   }
 
   del(key: string): Promise<number> {
-    return this.client.del(key);
+    return this.command((client) => client.del(key));
   }
 
   publish(channel: string, message: string): Promise<number> {
-    return this.client.publish(channel, message);
+    return this.command((client) => client.publish(channel, message));
   }
 
-  async subscribe(channel: string, handler: (message: string) => void): Promise<() => Promise<void>> {
-    const subscriber = await this.client.duplicate();
-    await subscriber.connect();
-    const listener = (message: string): void => handler(message);
-    await subscriber.subscribe(channel, listener);
-    this.subscribers.push(subscriber);
+  /**
+   * Calls `handler` for every message on `channel`. The subscription does not
+   * need Redis to be reachable now: it starts once Redis is, and comes back
+   * after every reconnect. Messages published while disconnected are lost.
+   */
+  async subscribe(channel: string, handler: RedisMessageHandler): Promise<() => Promise<void>> {
+    const handlers = this.channels.get(channel) ?? new Set<RedisMessageHandler>();
+    handlers.add(handler);
+    this.channels.set(channel, handlers);
+    if (this.client.connected) {
+      // A failure reaches the supervisor through onclose or below, and the
+      // next reconnect subscribes again.
+      await this.listen().catch((error: unknown) => this.report(error));
+    }
     return async () => {
-      const index = this.subscribers.indexOf(subscriber);
-      if (index >= 0) this.subscribers.splice(index, 1);
-      await subscriber.unsubscribe(channel, listener);
-      subscriber.close();
+      handlers.delete(handler);
+      if (handlers.size > 0 || this.channels.get(channel) !== handlers) return;
+      this.channels.delete(channel);
+      if (!this.active.delete(channel)) return;
+      await this.subscriber?.unsubscribe(channel).catch(() => undefined);
     };
   }
 
   close(): void {
-    this.unregisterReadiness?.();
-    for (const subscriber of this.subscribers) subscriber.close();
+    this.closed = true;
+    this.subscriber?.close();
+    this.subscriber = undefined;
+    this.active.clear();
     this.client.close();
   }
+
+  private readonly dispatch = (message: string, channel: string): void => {
+    for (const handler of this.channels.get(channel) ?? []) handler(message);
+  };
+
+  private async listen(): Promise<void> {
+    const subscriber = this.subscriber ?? await (this.opening ??= this.openSubscriber());
+    const missing = [...this.channels.keys()].filter((channel) => !this.active.has(channel));
+    if (missing.length === 0) return;
+    await withReplyTimeout(
+      subscriber.subscribe(missing, this.dispatch),
+      this.commandTimeoutMs,
+      () => subscriber.close(),
+    );
+    if (this.subscriber !== subscriber) return;
+    for (const channel of missing) this.active.add(channel);
+  }
+
+  /** A fresh connection, because Bun keeps the listeners of a dropped one without the server subscription. */
+  private async openSubscriber(): Promise<RedisClient> {
+    try {
+      const subscriber = this.createClient();
+      subscriber.onclose = (error) => {
+        if (this.subscriber !== subscriber) return;
+        this.subscriber = undefined;
+        this.active.clear();
+        this.report(error);
+      };
+      try {
+        await subscriber.connect();
+      } catch (error) {
+        subscriber.close();
+        throw error;
+      }
+      this.subscriber = subscriber;
+      return subscriber;
+    } finally {
+      this.opening = undefined;
+    }
+  }
+
+  private report(reason: unknown): void {
+    if (!this.closed) this.lostListener?.(reason);
+  }
 }

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

@@ -8,6 +8,10 @@
     "apps/api/src/config/redis.connection.ts",
     "apps/api/src/health/readiness.service.ts"
   ],
+  "requiredProjectContents": {
+    "apps/api/src/core/services.ts": ["supervise(name: string, connection: SupervisedConnection): void {"],
+    "apps/api/src/config/redis.connection.ts": ["export async function withReplyTimeout<T>("]
+  },
   "managedGlobs": [
     "apps/api/src/redis/**",
     "tests/api/redis.api.spec.ts"

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

@@ -76,11 +76,18 @@ export class EventStream {
   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.resync();
+      return;
     }
+    this.queue.push({ kind: "event", id: id ?? String(++this.sequence), data });
+    this.wake();
+  }
+
+  /** Drops the backlog and sends one `resync` frame, telling the client to reload its state. */
+  resync(): void {
+    if (this.closed) return;
+    this.queue.length = 0;
+    this.resyncPending = true;
     this.wake();
   }