@podosoft/podokit 0.15.0 → 0.16.0

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

@@ -1,14 +1,35 @@
-import { Injectable, type OnModuleDestroy } from "@nestjs/common";
+import {
+  Injectable,
+  Optional,
+  type OnModuleDestroy,
+  type OnModuleInit,
+} from "@nestjs/common";
 import Redis from "ioredis";
+import { redisConnectionOptions } from "../config/redis.connection";
+import { ReadinessService } from "../health/readiness.service";
 
 @Injectable()
-export class RedisService implements OnModuleDestroy {
-  readonly client = new Redis({
-    host: process.env.REDIS_HOST ?? "localhost",
-    port: Number(process.env.REDIS_PORT ?? 6379),
-    maxRetriesPerRequest: null,
-  });
+export class RedisService implements OnModuleInit, OnModuleDestroy {
+  readonly client = new Redis(redisConnectionOptions(process.env, {
+    lazyConnect: true,
+    enableReadyCheck: true,
+    enableOfflineQueue: false,
+    maxRetriesPerRequest: 1,
+    connectTimeout: 5_000,
+    commandTimeout: 5_000,
+  }));
   private readonly subscribers: Redis[] = [];
+  private unregisterReadiness?: () => void;
+
+  constructor(@Optional() private readonly readiness?: ReadinessService) {}
+
+  async onModuleInit(): Promise<void> {
+    await this.client.connect();
+    await this.client.ping();
+    this.unregisterReadiness = this.readiness?.register("redis", async () => {
+      await this.client.ping();
+    });
+  }
 
   get(key: string): Promise<string | null> {
     return this.client.get(key);
@@ -27,17 +48,37 @@ export class RedisService implements OnModuleDestroy {
     return this.client.publish(channel, message);
   }
 
-  // Subscribe on a dedicated connection (ioredis can't mix subscribe + commands).
-  subscribe(channel: string, handler: (message: string) => void): void {
-    const sub = this.client.duplicate();
+  async subscribe(
+    channel: string,
+    handler: (message: string) => void,
+  ): Promise<() => Promise<void>> {
+    const sub = new Redis(redisConnectionOptions(process.env, {
+      lazyConnect: true,
+      enableReadyCheck: true,
+      maxRetriesPerRequest: null,
+      connectTimeout: 5_000,
+    }));
+    try {
+      await sub.connect();
+      await sub.subscribe(channel);
+    } catch (error) {
+      await sub.quit().catch(() => undefined);
+      throw error;
+    }
     this.subscribers.push(sub);
-    void sub.subscribe(channel);
     sub.on("message", (ch, message) => {
       if (ch === channel) handler(message);
     });
+    return async () => {
+      const index = this.subscribers.indexOf(sub);
+      if (index >= 0) this.subscribers.splice(index, 1);
+      await sub.unsubscribe(channel);
+      await sub.quit();
+    };
   }
 
   async onModuleDestroy(): Promise<void> {
+    this.unregisterReadiness?.();
     await Promise.allSettled([this.client.quit(), ...this.subscribers.map((s) => s.quit())]);
   }
 }

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

@@ -2,12 +2,26 @@
   "name": "redis",
   "description": "Redis client (ioredis) with get/set/del and publish/subscribe, plus demo cache endpoints.",
   "requires": [],
+  "requiredProjectFiles": [
+    "apps/api/src/config/redis.connection.ts",
+    "apps/api/src/health/readiness.service.ts"
+  ],
+  "requiredProjectContents": {
+    "apps/api/src/config/redis.connection.ts": [
+      "connectTimeout?: number;",
+      "commandTimeout?: number;"
+    ]
+  },
+  "managedGlobs": [
+    "apps/api/src/redis/**",
+    "tests/api/redis.api.spec.ts"
+  ],
   "targetApp": "api",
   "dependencies": {
     "ioredis": "^5.4.1"
   },
   "env": [
-    "# redis (REDIS_HOST / REDIS_PORT already defined above)"
+    "# redis uses REDIS_URL or the REDIS_HOST / REDIS_PORT / REDIS_USERNAME / REDIS_PASSWORD / REDIS_DB settings defined above"
   ],
   "inject": [
     { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { RedisModule } from \"./redis/redis.module\";" },
@@ -15,6 +29,7 @@
   ],
   "instructions": [
     "Start Redis:  docker compose -f infra/docker/docker-compose.yml up -d",
+    "For production, prefer REDIS_URL; authenticated host settings are also supported.",
     "Set a value:  curl -XPUT localhost:5002/cache/greeting -H 'content-type: application/json' -d '{\"value\":\"hi\",\"ttl\":60}'",
     "Read it back: curl localhost:5002/cache/greeting"
   ]

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

@@ -1,4 +1,11 @@
-import { Body, Controller, Post, Sse, type MessageEvent } from "@nestjs/common";
+import {
+  Body,
+  Controller,
+  Post,
+  ServiceUnavailableException,
+  Sse,
+  type MessageEvent,
+} from "@nestjs/common";
 import { ApiTags } from "@nestjs/swagger";
 import { interval, map, merge, type Observable } from "rxjs";
 import { EventsService } from "./events.service";
@@ -18,8 +25,15 @@ export class EventsController {
   }
 
   @Post()
-  publish(@Body() dto: PublishEventDto): { ok: true } {
-    this.events.publish({ type: "message", message: dto.message });
+  async publish(@Body() dto: PublishEventDto): Promise<{ ok: true }> {
+    try {
+      await this.events.publishAsync({ type: "message", message: dto.message });
+    } catch {
+      throw new ServiceUnavailableException({
+        code: "EVENTS_TRANSPORT_UNAVAILABLE",
+        message: "Event transport is unavailable",
+      });
+    }
     return { ok: true };
   }
 }

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

@@ -1,12 +1,19 @@
 import { Global, Module } from "@nestjs/common";
 import { EventsController } from "./events.controller";
-import { EventsService } from "./events.service";
+import { EVENTS_TRANSPORT, EventsService } from "./events.service";
+import { createEventsTransport } from "./events.transport";
 
 // Global so any module can inject EventsService to broadcast updates.
 @Global()
 @Module({
   controllers: [EventsController],
-  providers: [EventsService],
+  providers: [
+    {
+      provide: EVENTS_TRANSPORT,
+      useFactory: () => createEventsTransport(),
+    },
+    EventsService,
+  ],
   exports: [EventsService],
 })
 export class EventsModule {}

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "@jest/globals";
+import { firstValueFrom, take } from "rxjs";
+import { ReadinessService } from "../health/readiness.service";
+import { EventsService } from "./events.service";
+import type { EventHandler, EventsTransport } from "./events.transport";
+
+class TestTransport implements EventsTransport {
+  handler?: EventHandler;
+  published: unknown[] = [];
+  available = true;
+
+  connect(handler: EventHandler): Promise<void> {
+    this.handler = handler;
+    return Promise.resolve();
+  }
+
+  publish(data: unknown): Promise<void> {
+    if (!this.available) return Promise.reject(new Error("unavailable"));
+    this.published.push(data);
+    this.handler?.(data);
+    return Promise.resolve();
+  }
+
+  ready(): Promise<void> {
+    return this.available ? Promise.resolve() : Promise.reject(new Error("unavailable"));
+  }
+
+  close(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+describe("EventsService", () => {
+  it("publishes through the transport and exposes local delivery", async () => {
+    const transport = new TestTransport();
+    const readiness = new ReadinessService();
+    const service = new EventsService(transport, readiness);
+    await service.onModuleInit();
+
+    const next = firstValueFrom(service.asObservable().pipe(take(1)));
+    await service.publishAsync({ type: "changed" });
+    await expect(next).resolves.toEqual({ data: { type: "changed" } });
+    expect(transport.published).toEqual([{ type: "changed" }]);
+
+    await expect(readiness.run()).resolves.toEqual({ events: "up" });
+    await service.onModuleDestroy();
+    await expect(readiness.run()).resolves.toEqual({});
+  });
+
+  it("reports a failed transport through publishAsync and readiness", async () => {
+    const transport = new TestTransport();
+    const readiness = new ReadinessService();
+    const service = new EventsService(transport, readiness);
+    await service.onModuleInit();
+    transport.available = false;
+
+    await expect(service.publishAsync({ type: "changed" })).rejects.toThrow("unavailable");
+    await expect(readiness.run()).resolves.toEqual({ events: "down" });
+    await service.onModuleDestroy();
+  });
+});

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

@@ -1,17 +1,57 @@
-import { Injectable, type MessageEvent } from "@nestjs/common";
+import {
+  Inject,
+  Injectable,
+  Logger,
+  type MessageEvent,
+  type OnModuleDestroy,
+  type OnModuleInit,
+} from "@nestjs/common";
 import { Observable, Subject } from "rxjs";
+import { ReadinessService } from "../health/readiness.service";
+import type { EventsTransport } from "./events.transport";
+
+export const EVENTS_TRANSPORT = Symbol("EVENTS_TRANSPORT");
 
 @Injectable()
-export class EventsService {
+export class EventsService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(EventsService.name);
   private readonly subject = new Subject<MessageEvent>();
+  private unregisterReadiness?: () => void;
+
+  constructor(
+    @Inject(EVENTS_TRANSPORT) private readonly transport: EventsTransport,
+    private readonly readiness: ReadinessService,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    await this.transport.connect((data) => this.publishLocal(data));
+    this.unregisterReadiness = this.readiness.register("events", () => this.transport.ready());
+  }
 
-  // Push an event to all connected clients. Inject this service anywhere
-  // (e.g. a queue processor) to broadcast progress or notifications.
   publish(data: unknown): void {
+    void this.publishAsync(data).catch((error: unknown) => {
+      this.logger.error(
+        "Failed to publish event",
+        error instanceof Error ? error.stack : undefined,
+      );
+    });
+  }
+
+  publishAsync(data: unknown): Promise<void> {
+    return this.transport.publish(data);
+  }
+
+  publishLocal(data: unknown): void {
     this.subject.next({ data } as MessageEvent);
   }
 
   asObservable(): Observable<MessageEvent> {
     return this.subject.asObservable();
   }
+
+  async onModuleDestroy(): Promise<void> {
+    this.unregisterReadiness?.();
+    this.subject.complete();
+    await this.transport.close();
+  }
 }

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "@jest/globals";
+import { RedisEventsTransport } from "./events.transport";
+
+const redisUrl = process.env.REDIS_TEST_URL;
+const integrationTest = redisUrl ? it : it.skip;
+
+describe("RedisEventsTransport integration", () => {
+  integrationTest("delivers once to every connected replica", async () => {
+    const channel = `podokit:test:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+    const env = {
+      REDIS_URL: redisUrl,
+      SSE_REDIS_CHANNEL: channel,
+      SSE_MAX_EVENT_BYTES: "1024",
+    };
+    const first = new RedisEventsTransport(env);
+    const second = new RedisEventsTransport(env);
+    const firstEvents: unknown[] = [];
+    const secondEvents: unknown[] = [];
+
+    try {
+      await first.connect((data) => firstEvents.push(data));
+      await second.connect((data) => secondEvents.push(data));
+      await first.publish({ type: "replica-test" });
+
+      const deadline = Date.now() + 3000;
+      while (
+        Date.now() < deadline &&
+        (firstEvents.length < 1 || secondEvents.length < 1)
+      ) {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(firstEvents).toEqual([{ type: "replica-test" }]);
+      expect(secondEvents).toEqual([{ type: "replica-test" }]);
+      await expect(first.ready()).resolves.toBeUndefined();
+      await expect(second.ready()).resolves.toBeUndefined();
+    } finally {
+      await Promise.all([first.close(), second.close()]);
+    }
+  });
+});

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

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "@jest/globals";
+import {
+  MemoryEventsTransport,
+  RedisEventsTransport,
+  type RedisClientFactory,
+} from "./events.transport";
+import type { RedisConnectionOptions } from "../config/redis.connection";
+
+class FakeRedisClient {
+  status = "wait";
+  readonly published: Array<{ channel: string; message: string }> = [];
+  readonly subscriptions: string[] = [];
+  private messageListener?: (channel: string, message: string) => void;
+
+  connect(): Promise<void> {
+    this.status = "ready";
+    return Promise.resolve();
+  }
+
+  publish(channel: string, message: string): Promise<number> {
+    this.published.push({ channel, message });
+    return Promise.resolve(1);
+  }
+
+  subscribe(channel: string): Promise<number> {
+    this.subscriptions.push(channel);
+    return Promise.resolve(1);
+  }
+
+  ping(): Promise<string> {
+    return this.status === "ready" ? Promise.resolve("PONG") : Promise.reject(new Error("down"));
+  }
+
+  quit(): Promise<string> {
+    this.status = "end";
+    return Promise.resolve("OK");
+  }
+
+  on(_event: "message", listener: (channel: string, message: string) => void): this {
+    this.messageListener = listener;
+    return this;
+  }
+
+  off(_event: "message", listener: (channel: string, message: string) => void): this {
+    if (this.messageListener === listener) this.messageListener = undefined;
+    return this;
+  }
+
+  emit(channel: string, message: string): void {
+    this.messageListener?.(channel, message);
+  }
+}
+
+describe("events transports", () => {
+  it("delivers memory events through the configured handler", async () => {
+    const transport = new MemoryEventsTransport({ SSE_MAX_EVENT_BYTES: "128" });
+    const received: unknown[] = [];
+    await transport.connect((data) => received.push(data));
+    await transport.publish({ type: "changed" });
+    expect(received).toEqual([{ type: "changed" }]);
+  });
+
+  it("publishes Redis events only through the subscription echo", async () => {
+    const clients: FakeRedisClient[] = [];
+    const factory: RedisClientFactory = (_options: RedisConnectionOptions) => {
+      const client = new FakeRedisClient();
+      clients.push(client);
+      return client;
+    };
+    const transport = new RedisEventsTransport(
+      {
+        REDIS_URL: "redis://user:password@cache.example.com:6379/2",
+        SSE_REDIS_CHANNEL: "events:test",
+      },
+      factory,
+    );
+    const received: unknown[] = [];
+
+    await transport.connect((data) => received.push(data));
+    await transport.publish({ type: "changed" });
+    expect(received).toEqual([]);
+    expect(clients[0]?.published).toEqual([
+      { channel: "events:test", message: '{"type":"changed"}' },
+    ]);
+
+    clients[1]?.emit("events:test", '{"type":"changed"}');
+    expect(received).toEqual([{ type: "changed" }]);
+  });
+
+  it("rejects events larger than the configured limit", async () => {
+    const transport = new MemoryEventsTransport({ SSE_MAX_EVENT_BYTES: "8" });
+    await transport.connect(() => undefined);
+    await expect(transport.publish({ message: "too large" })).rejects.toThrow(
+      "Event data exceeds SSE_MAX_EVENT_BYTES",
+    );
+  });
+});

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

@@ -0,0 +1,165 @@
+import { Logger } from "@nestjs/common";
+import Redis from "ioredis";
+import {
+  redisConnectionOptions,
+  type RedisConnectionOptions,
+} from "../config/redis.connection";
+
+export type EventHandler = (data: unknown) => void;
+
+export interface EventsTransport {
+  connect(handler: EventHandler): Promise<void>;
+  publish(data: unknown): Promise<void>;
+  ready(): Promise<void>;
+  close(): Promise<void>;
+}
+
+interface RedisClient {
+  readonly status: string;
+  connect(): Promise<void>;
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(channel: string): Promise<unknown>;
+  ping(): Promise<string>;
+  quit(): Promise<string>;
+  on(event: "message", listener: (channel: string, message: string) => void): this;
+  off(event: "message", listener: (channel: string, message: string) => void): this;
+}
+
+export type RedisClientFactory = (options: RedisConnectionOptions) => RedisClient;
+
+function defaultRedisClientFactory(options: RedisConnectionOptions): RedisClient {
+  return new Redis(options);
+}
+
+function maxEventBytes(env: NodeJS.ProcessEnv): number {
+  const value = Number(env.SSE_MAX_EVENT_BYTES ?? 65_536);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("SSE_MAX_EVENT_BYTES must be a positive integer");
+  }
+  return value;
+}
+
+function encodedEvent(data: unknown, maximumBytes: number): string {
+  const message = JSON.stringify(data);
+  if (message === undefined) {
+    throw new Error("Event data must be JSON serializable");
+  }
+  if (Buffer.byteLength(message, "utf8") > maximumBytes) {
+    throw new Error("Event data exceeds SSE_MAX_EVENT_BYTES");
+  }
+  return message;
+}
+
+export class MemoryEventsTransport implements EventsTransport {
+  private handler?: EventHandler;
+  private readonly maximumBytes: number;
+
+  constructor(env: NodeJS.ProcessEnv = process.env) {
+    this.maximumBytes = maxEventBytes(env);
+  }
+
+  connect(handler: EventHandler): Promise<void> {
+    this.handler = handler;
+    return Promise.resolve();
+  }
+
+  async publish(data: unknown): Promise<void> {
+    const message = encodedEvent(data, this.maximumBytes);
+    this.handler?.(JSON.parse(message) as unknown);
+  }
+
+  ready(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  close(): Promise<void> {
+    this.handler = undefined;
+    return Promise.resolve();
+  }
+}
+
+export class RedisEventsTransport implements EventsTransport {
+  private readonly logger = new Logger(RedisEventsTransport.name);
+  private readonly publisher: RedisClient;
+  private readonly subscriber: RedisClient;
+  private readonly channel: string;
+  private readonly maximumBytes: number;
+  private handler?: EventHandler;
+
+  constructor(
+    env: NodeJS.ProcessEnv = process.env,
+    createClient: RedisClientFactory = defaultRedisClientFactory,
+  ) {
+    this.channel = env.SSE_REDIS_CHANNEL?.trim() || "podokit:events";
+    this.maximumBytes = maxEventBytes(env);
+    this.publisher = createClient(
+      redisConnectionOptions(env, {
+        lazyConnect: true,
+        enableReadyCheck: true,
+        maxRetriesPerRequest: 1,
+        connectTimeout: 5_000,
+        commandTimeout: 5_000,
+      }),
+    );
+    this.subscriber = createClient(
+      redisConnectionOptions(env, {
+        lazyConnect: true,
+        enableReadyCheck: true,
+        maxRetriesPerRequest: null,
+        connectTimeout: 5_000,
+      }),
+    );
+  }
+
+  private readonly onMessage = (channel: string, message: string): void => {
+    if (channel !== this.channel) return;
+    if (Buffer.byteLength(message, "utf8") > this.maximumBytes) {
+      this.logger.warn("Discarded oversized event transport message");
+      return;
+    }
+    try {
+      this.handler?.(JSON.parse(message) as unknown);
+    } catch {
+      this.logger.warn("Discarded malformed event transport message");
+    }
+  };
+
+  async connect(handler: EventHandler): Promise<void> {
+    this.handler = handler;
+    this.subscriber.on("message", this.onMessage);
+    try {
+      await Promise.all([this.publisher.connect(), this.subscriber.connect()]);
+      await this.subscriber.subscribe(this.channel);
+      await this.ready();
+    } catch (error) {
+      this.subscriber.off("message", this.onMessage);
+      this.handler = undefined;
+      await Promise.allSettled([this.publisher.quit(), this.subscriber.quit()]);
+      throw error;
+    }
+  }
+
+  async publish(data: unknown): Promise<void> {
+    await this.publisher.publish(this.channel, encodedEvent(data, this.maximumBytes));
+  }
+
+  async ready(): Promise<void> {
+    if (this.subscriber.status !== "ready") {
+      throw new Error("Redis event subscriber is not ready");
+    }
+    await this.publisher.ping();
+  }
+
+  async close(): Promise<void> {
+    this.subscriber.off("message", this.onMessage);
+    this.handler = undefined;
+    await Promise.allSettled([this.publisher.quit(), this.subscriber.quit()]);
+  }
+}
+
+export function createEventsTransport(env: NodeJS.ProcessEnv = process.env): EventsTransport {
+  const name = env.SSE_TRANSPORT?.trim().toLowerCase() || "memory";
+  if (name === "memory") return new MemoryEventsTransport(env);
+  if (name === "redis") return new RedisEventsTransport(env);
+  throw new Error('SSE_TRANSPORT must be either "memory" or "redis"');
+}

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

@@ -1,6 +1,7 @@
 import { expect, test } 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 };
 
 async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
@@ -44,3 +45,43 @@ test("sse: a published message is delivered over the event stream @smoke", async
   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;
+  }
+  ac.abort();
+  expect(seen).toBe(1);
+  await ctx.dispose();
+});