@podosoft/podokit 1.2.0 → 1.4.0

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/queue.ts

@@ -1,7 +1,35 @@
-import { redisConnectionOptions, type RedisConnectionOptions } from "../config/redis.connection";
+import type { ConnectionOptions } from "bullmq";
+import { redisCommandTimeoutMs, redisConnectionOptions } from "../config/redis.connection";
 
 export const DEMO_QUEUE = "demo";
 
-export function redisConnection(): RedisConnectionOptions {
-  return redisConnectionOptions(process.env, { maxRetriesPerRequest: null });
+/** Wait before reconnect attempt `attempt`: 250 ms, doubling up to 5 seconds. */
+export function reconnectDelay(attempt: number): number {
+  return Math.min(250 * 2 ** Math.max(0, attempt - 1), 5_000);
+}
+
+/** Workers block on Redis, so BullMQ requires their commands to wait for a reply indefinitely. */
+export function redisConnection(env: NodeJS.ProcessEnv = process.env): ConnectionOptions {
+  return {
+    ...redisConnectionOptions(env, { maxRetriesPerRequest: null }),
+    retryStrategy: reconnectDelay,
+  };
+}
+
+/**
+ * The API's connection for adding and reading jobs. Commands fail at once while
+ * it is disconnected and wait at most `REDIS_COMMAND_TIMEOUT_MS` for a reply, so
+ * a request that enqueues a job cannot hang on Redis. It does not reconnect by
+ * itself: the service registry's supervisor reopens it.
+ */
+export function producerConnection(env: NodeJS.ProcessEnv = process.env): ConnectionOptions {
+  return {
+    ...redisConnectionOptions(env, {
+      lazyConnect: true,
+      enableOfflineQueue: false,
+      connectTimeout: 5_000,
+      commandTimeout: redisCommandTimeoutMs(env),
+    }),
+    retryStrategy: () => null,
+  };
 }

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

@@ -8,13 +8,17 @@
     "apps/api/src/config/providers.ts",
     "apps/api/src/config/redis.connection.ts"
   ],
+  "requiredProjectContents": {
+    "apps/api/src/core/services.ts": ["supervise(name: string, connection: SupervisedConnection): void {"],
+    "apps/api/src/config/redis.connection.ts": ["export function redisCommandTimeoutMs("]
+  },
   "managedGlobs": [
     "apps/api/src/jobs/**",
     "apps/api/src/main-worker.ts"
   ],
   "targetApp": "api",
   "dependencies": {
-    "bullmq": "^5.34.0"
+    "bullmq": "^5.57.0"
   },
   "scripts": {
     "start:worker": "bun dist/main-worker.js",

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

@@ -8,9 +8,7 @@ export const eventsRedisModule: PodokitModule = {
   configure: (_env, services): void => {
     if (PROVIDERS.events !== "redis") return;
     const events = new RedisEventBus();
-    services.register(EVENTS, events, async () => {
-      await events.close();
-    });
-    services.onStart(() => events.ready());
+    services.register(EVENTS, events, () => events.close());
+    services.supervise("events", events);
   },
 };

package/dist/templates/modules/events-redis/files/apps/api/src/events-provider-redis/redis-event.bus.spec.ts

@@ -0,0 +1,224 @@
+import type { RedisClient } from "bun";
+import { describe, expect, it } from "bun:test";
+import { RedisCommandTimeoutError } from "../config/redis.connection";
+import { RedisEventBus } from "./redis-event.bus";
+
+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 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();
+  }
+
+  deliver(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) {}
+
+  /** Never answers while the server is paused; closing the connection fails the command. */
+  private answer<T>(value: () => T): Promise<T> {
+    if (!this.server.paused) return Promise.resolve(value());
+    return new Promise<T>((_resolve, reject) => {
+      this.pending.add(reject);
+    });
+  }
+
+  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.connected ? this.answer(() => "PONG") : Promise.reject(new Error("Connection closed"));
+  }
+
+  publish(channel: string, message: string): Promise<number> {
+    if (!this.connected) {
+      return Promise.reject(new Error("Connection is closed and offline queue is disabled"));
+    }
+    return this.answer(() => this.server.deliver(channel, message));
+  }
+
+  subscribe(channel: string, listener: Listener): Promise<number> {
+    if (!this.connected) return Promise.reject(new Error("Connection closed"));
+    return this.answer(() => {
+      this.channels.add(channel);
+      this.listener = listener;
+      return this.channels.size;
+    });
+  }
+
+  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"));
+  }
+}
+
+function bus(server: FakeRedis): RedisEventBus {
+  return new RedisEventBus(
+    { EVENTS_REDIS_CHANNEL: "test:events", REDIS_COMMAND_TIMEOUT_MS: "50" },
+    () => server.client(),
+  );
+}
+
+describe("RedisEventBus reconnects", () => {
+  it("keeps handlers registered without Redis and delivers once the channel is subscribed", async () => {
+    const server = new FakeRedis();
+    server.up = false;
+    const events = bus(server);
+    let interruptions = 0;
+    events.onInterruption(() => { interruptions += 1; });
+    const received: unknown[] = [];
+    await events.subscribe("sse", (event) => { received.push(event); });
+
+    await expect(events.connect()).rejects.toThrow("Connection closed");
+    await expect(events.ready()).rejects.toThrow("not subscribed");
+    server.up = true;
+    await events.connect();
+    await events.ready();
+
+    await events.publish("sse", { id: 1 });
+    expect(received).toEqual([{ id: 1 }]);
+    // Streams opened before the first subscription may have missed events.
+    expect(interruptions).toBe(1);
+    events.close();
+  });
+
+  it("subscribes again after Redis drops the connections and reports one interruption", async () => {
+    const server = new FakeRedis();
+    const events = bus(server);
+    const lost: unknown[] = [];
+    events.onLost((reason) => { lost.push(reason); });
+    let interruptions = 0;
+    events.onInterruption(() => { interruptions += 1; });
+    const received: unknown[] = [];
+    await events.subscribe("config.changed", (event) => { received.push(event); });
+    await events.connect();
+    expect(interruptions).toBe(0);
+
+    server.stop();
+    expect(lost.length).toBeGreaterThan(0);
+    await expect(events.ready()).rejects.toThrow("not subscribed");
+    await expect(events.publish("config.changed", { origin: "a" })).rejects.toThrow("offline queue");
+    server.up = true;
+    await events.connect();
+
+    expect(interruptions).toBe(1);
+    await events.publish("config.changed", { origin: "b" });
+    expect(received).toEqual([{ origin: "b" }]);
+    events.close();
+  });
+
+  it("reports no interruption when only the publisher reconnects", async () => {
+    const server = new FakeRedis();
+    const events = bus(server);
+    let interruptions = 0;
+    events.onInterruption(() => { interruptions += 1; });
+    await events.connect();
+
+    server.clients[0]?.drop();
+    await events.connect();
+    expect(interruptions).toBe(0);
+    await events.ready();
+    events.close();
+  });
+
+  it("does not report connections it closes itself", async () => {
+    const server = new FakeRedis();
+    const events = bus(server);
+    const lost: unknown[] = [];
+    events.onLost((reason) => { lost.push(reason); });
+    await events.connect();
+
+    events.close();
+    expect(lost).toEqual([]);
+  });
+
+  it("fails a publish Redis does not answer and hands the publisher to the supervisor", async () => {
+    const server = new FakeRedis();
+    const events = bus(server);
+    const lost: unknown[] = [];
+    events.onLost((reason) => { lost.push(reason); });
+    let interruptions = 0;
+    events.onInterruption(() => { interruptions += 1; });
+    const received: unknown[] = [];
+    await events.subscribe("sse", (event) => { received.push(event); });
+    await events.connect();
+
+    server.paused = true;
+    const started = Date.now();
+    await expect(events.publish("sse", { id: 1 })).rejects.toBeInstanceOf(RedisCommandTimeoutError);
+    expect(Date.now() - started).toBeLessThan(1_000);
+    expect(lost.length).toBe(1);
+    await expect(events.ready()).rejects.toThrow("Connection closed");
+
+    server.paused = false;
+    await events.connect();
+    await events.publish("sse", { id: 2 });
+    expect(received).toEqual([{ id: 2 }]);
+    expect(interruptions).toBe(0);
+    events.close();
+  });
+
+  it("fails a subscription Redis does not confirm and subscribes on the next attempt", async () => {
+    const server = new FakeRedis();
+    server.paused = true;
+    const events = bus(server);
+    let interruptions = 0;
+    events.onInterruption(() => { interruptions += 1; });
+
+    await expect(events.connect()).rejects.toBeInstanceOf(RedisCommandTimeoutError);
+    await expect(events.ready()).rejects.toThrow("not subscribed");
+
+    server.paused = false;
+    await events.connect();
+    await events.ready();
+    expect(interruptions).toBe(1);
+    events.close();
+  });
+});

package/dist/templates/modules/events-redis/files/apps/api/src/events-provider-redis/redis-event.bus.ts

@@ -1,48 +1,83 @@
 import { RedisClient } from "bun";
 import type { EventBus, EventHandler, Unsubscribe } from "@podosoft/podokit-runtime";
-import { redisConnectionUrl } from "../config/redis.connection";
+import {
+  redisCommandTimeoutMs,
+  redisConnectionUrl,
+  withReplyTimeout,
+} from "../config/redis.connection";
+import type { SupervisedConnection } from "../core/services";
 
-export class RedisEventBus implements EventBus {
+/**
+ * Publishing fails at once while disconnected instead of queueing, and the
+ * supervisor reconnects instead of Bun, which gives up after a fixed number of
+ * attempts and never restores subscriptions.
+ */
+function redisClientFactory(env: NodeJS.ProcessEnv): () => RedisClient {
+  const url = redisConnectionUrl(env);
+  return () => new RedisClient(url, {
+    connectionTimeout: 5_000,
+    autoReconnect: false,
+    enableOfflineQueue: false,
+  });
+}
+
+/**
+ * Every replica subscribes to one Redis channel and dispatches to its local
+ * handlers by topic. Handlers are local, so they survive reconnects; the
+ * channel subscription is opened again on each reconnect.
+ */
+export class RedisEventBus implements EventBus, SupervisedConnection {
   private readonly publisher: RedisClient;
-  private readonly subscriber: RedisClient;
   private readonly channel: string;
   private readonly maxEventBytes: number;
+  private readonly commandTimeoutMs: number;
+  private readonly createClient: () => RedisClient;
   private readonly handlers = new Map<string, Set<EventHandler>>();
-  private listener?: (message: string) => void;
+  private readonly interruptionListeners = new Set<() => void>();
+  // Set while a connection holds the channel subscription.
+  private subscriber?: RedisClient;
+  // Whether events may have been missed since the channel was last subscribed.
+  private missedEvents = false;
+  private lostListener?: (reason: unknown) => void;
+  private closed = false;
 
-  constructor(env: NodeJS.ProcessEnv = process.env) {
-    this.publisher = new RedisClient(redisConnectionUrl(env), { connectionTimeout: 5_000 });
-    this.subscriber = new RedisClient(redisConnectionUrl(env), { connectionTimeout: 5_000 });
+  constructor(
+    env: NodeJS.ProcessEnv = process.env,
+    createClient: () => RedisClient = redisClientFactory(env),
+  ) {
+    this.createClient = createClient;
+    this.publisher = createClient();
+    this.publisher.onclose = (error) => this.report(error);
     this.channel = env.EVENTS_REDIS_CHANNEL?.trim() || "podokit:events";
     this.maxEventBytes = Number(env.SSE_MAX_EVENT_BYTES ?? 65_536);
     if (!Number.isSafeInteger(this.maxEventBytes) || this.maxEventBytes < 1) {
       throw new Error("SSE_MAX_EVENT_BYTES must be a positive integer");
     }
+    this.commandTimeoutMs = redisCommandTimeoutMs(env);
+  }
+
+  onLost(listener: (reason: unknown) => void): void {
+    this.lostListener = listener;
   }
 
+  /** Opens whichever connection is closed and subscribes the channel again. */
   async connect(): Promise<void> {
-    if (this.listener) return;
-    await Promise.all([this.publisher.connect(), this.subscriber.connect()]);
-    this.listener = (message: string): void => {
-      if (Buffer.byteLength(message, "utf8") > this.maxEventBytes) return;
-      try {
-        const envelope = JSON.parse(message) as unknown;
-        if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return;
-        const record = envelope as Record<string, unknown>;
-        if (typeof record.topic !== "string") return;
-        for (const handler of this.handlers.get(record.topic) ?? []) {
-          void Promise.resolve(handler(record.event)).catch(() => undefined);
-        }
-      } catch {
-        process.stderr.write("Discard malformed event transport message\n");
-      }
-    };
-    await this.subscriber.subscribe(this.channel, this.listener);
+    try {
+      if (!this.publisher.connected) await this.publisher.connect();
+      this.subscriber ??= await this.openSubscriber();
+    } catch (error) {
+      if (!this.subscriber) this.missedEvents = true;
+      throw error;
+    }
+    if (!this.missedEvents) return;
+    this.missedEvents = false;
+    for (const listener of [...this.interruptionListeners]) listener();
   }
 
+  /** Rejects until the channel is subscribed and while the publisher cannot reach Redis. */
   async ready(): Promise<void> {
-    await this.connect();
-    await this.publisher.ping();
+    if (!this.subscriber) throw new Error("Event transport is not subscribed");
+    await this.send(() => this.publisher.ping());
   }
 
   async publish(topic: string, event: unknown): Promise<void> {
@@ -51,25 +86,79 @@ export class RedisEventBus implements EventBus {
     if (Buffer.byteLength(message, "utf8") > this.maxEventBytes) {
       throw new Error(`Event exceeds maxEventBytes (${this.maxEventBytes})`);
     }
-    await this.publisher.publish(this.channel, message);
+    await this.send(() => this.publisher.publish(this.channel, message));
   }
 
-  async subscribe(topic: string, handler: EventHandler): Promise<Unsubscribe> {
-    await this.connect();
+  subscribe(topic: string, handler: EventHandler): Promise<Unsubscribe> {
     const handlers = this.handlers.get(topic) ?? new Set<EventHandler>();
     handlers.add(handler);
     this.handlers.set(topic, handlers);
-    return () => {
+    return Promise.resolve(() => {
       handlers.delete(handler);
-      if (handlers.size === 0) this.handlers.delete(topic);
+      if (handlers.size === 0 && this.handlers.get(topic) === handlers) this.handlers.delete(topic);
+    });
+  }
+
+  onInterruption(listener: () => void): () => void {
+    this.interruptionListeners.add(listener);
+    return () => {
+      this.interruptionListeners.delete(listener);
     };
   }
 
-  async close(): Promise<void> {
-    if (this.listener) await this.subscriber.unsubscribe(this.channel, this.listener);
+  close(): void {
+    this.closed = true;
     this.handlers.clear();
-    this.listener = undefined;
+    this.interruptionListeners.clear();
+    this.subscriber?.close();
+    this.subscriber = undefined;
     this.publisher.close();
-    this.subscriber.close();
+  }
+
+  /** Fails a publisher command Redis does not answer in time and closes the connection for the supervisor to reopen. */
+  private async send<T>(command: () => Promise<T>): Promise<T> {
+    return withReplyTimeout(command(), this.commandTimeoutMs, () => this.publisher.close());
+  }
+
+  private readonly receive = (message: string): void => {
+    if (Buffer.byteLength(message, "utf8") > this.maxEventBytes) return;
+    try {
+      const envelope = JSON.parse(message) as unknown;
+      if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return;
+      const record = envelope as Record<string, unknown>;
+      if (typeof record.topic !== "string") return;
+      for (const handler of this.handlers.get(record.topic) ?? []) {
+        void Promise.resolve(handler(record.event)).catch(() => undefined);
+      }
+    } catch {
+      process.stderr.write("Discard malformed event transport message\n");
+    }
+  };
+
+  /** A fresh connection, because Bun keeps the listeners of a dropped one without the server subscription. */
+  private async openSubscriber(): Promise<RedisClient> {
+    const subscriber = this.createClient();
+    subscriber.onclose = (error) => {
+      if (this.subscriber !== subscriber) return;
+      this.subscriber = undefined;
+      this.missedEvents = true;
+      this.report(error);
+    };
+    try {
+      await subscriber.connect();
+      await withReplyTimeout(
+        subscriber.subscribe(this.channel, this.receive),
+        this.commandTimeoutMs,
+        () => subscriber.close(),
+      );
+    } catch (error) {
+      subscriber.close();
+      throw error;
+    }
+    return subscriber;
+  }
+
+  private report(reason: unknown): void {
+    if (!this.closed) this.lostListener?.(reason);
   }
 }

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

@@ -7,6 +7,10 @@
     "apps/api/src/config/providers.ts",
     "apps/api/src/config/redis.connection.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/events-provider-redis/**"
   ],

package/dist/templates/modules/file-upload/files/apps/api/src/files/chunked-uploads.routes.ts

@@ -0,0 +1,136 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia, t } from "elysia";
+import type { ElysiaPlugin, RequestIdentity } from "../core/services";
+import type { ChunkedUploads } from "./chunked-uploads";
+
+const JSON_TYPE = "application/json";
+const BINARY_TYPE = "application/octet-stream";
+const CONTENT_TYPE = "^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+(\\s*;.*)?$";
+
+const uploadId = t.Object({ id: t.String({ minLength: 1, maxLength: 64 }) });
+
+/** The origins in CORS_ORIGIN, which a browser's Origin header must match. */
+export function allowedOrigins(corsOrigin: string | undefined): string[] {
+  return (corsOrigin ?? "")
+    .split(",")
+    .map((origin) => origin.trim())
+    .filter((origin) => origin.length > 0)
+    .map((origin) => {
+      try {
+        return new URL(origin).origin;
+      } catch {
+        return origin;
+      }
+    });
+}
+
+function mediaType(request: Request): string {
+  return (request.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+}
+
+/**
+ * Upload routes may be served on a direct API path, which skips the web
+ * server's cross-site form check. Requiring a JSON or binary content type makes
+ * every cross-origin browser request preflighted, which CORS refuses for other
+ * origins, and a browser Origin outside CORS_ORIGIN is rejected outright.
+ */
+function guard(origins: readonly string[], type?: string): (context: { request: Request }) => void {
+  return ({ request }) => {
+    const origin = request.headers.get("origin");
+    if (origins.length > 0 && origin !== null && !origins.includes(origin)) {
+      throw new AppException("ORIGIN_NOT_ALLOWED", "Requests from this origin cannot change uploads", 403);
+    }
+    if (type !== undefined && mediaType(request) !== type) {
+      throw new AppException("UNSUPPORTED_MEDIA_TYPE", `Send this request as ${type}`, 415);
+    }
+  };
+}
+
+function declaredLength(request: Request): number | null {
+  const value = request.headers.get("content-length");
+  if (value === null) return null;
+  return /^\d+$/.test(value.trim()) ? Number(value) : Number.NaN;
+}
+
+/**
+ * Resumable uploads: create a session, PUT its parts in any order (again to
+ * replace one), read the status to resume, then complete or delete it. Only the
+ * owner sees a session; others receive 404 so session ids cannot be probed.
+ */
+export function chunkedUploadRoutes(
+  uploads: ChunkedUploads,
+  identity: RequestIdentity,
+  origins: readonly string[],
+): ElysiaPlugin {
+  return new Elysia({ name: "podokit.files.uploads" })
+    .post("/files/uploads", async ({ request, body, set }) => {
+      const created = await uploads.create(await identity.userId(request), body);
+      set.status = 201;
+      return created;
+    }, {
+      transform: guard(origins, JSON_TYPE),
+      body: t.Object({
+        filename: t.String({ minLength: 1, maxLength: 255 }),
+        size: t.Integer({ minimum: 1 }),
+        contentType: t.Optional(t.String({ maxLength: 255, pattern: CONTENT_TYPE })),
+      }),
+      detail: {
+        tags: ["files"],
+        summary: "Start a resumable upload",
+        description:
+          "Returns the session id, the part size, and the part count. Send every part with PUT /files/uploads/{id}/parts/{partNumber}, then complete the upload.",
+      },
+    })
+    .get("/files/uploads/:id", async ({ request, params }) =>
+      uploads.status(await identity.userId(request), params.id), {
+      params: uploadId,
+      detail: {
+        tags: ["files"],
+        summary: "Read a resumable upload",
+        description: "Lists the stored part numbers, so a client can resume by sending the others.",
+      },
+    })
+    .put("/files/uploads/:id/parts/:partNumber", async ({ request, params }) =>
+      uploads.putPart(
+        await identity.userId(request),
+        params.id,
+        params.partNumber,
+        declaredLength(request),
+        request.body,
+      ), {
+      // The body is streamed to storage as it arrives, never parsed or buffered here.
+      parse: "none",
+      transform: guard(origins, BINARY_TYPE),
+      params: t.Object({ id: t.String({ minLength: 1, maxLength: 64 }), partNumber: t.Numeric() }),
+      detail: {
+        tags: ["files"],
+        summary: "Store one part of a resumable upload",
+        description:
+          "Send the raw bytes as application/octet-stream with a Content-Length equal to the part size (the last part holds the remainder). Sending a part again replaces it.",
+        requestBody: {
+          required: true,
+          content: { [BINARY_TYPE]: { schema: { type: "string", format: "binary" } } },
+        },
+      },
+    })
+    .post("/files/uploads/:id/complete", async ({ request, params }) =>
+      uploads.complete(await identity.userId(request), params.id), {
+      transform: guard(origins, JSON_TYPE),
+      params: uploadId,
+      body: t.Optional(t.Object({})),
+      detail: {
+        tags: ["files"],
+        summary: "Complete a resumable upload",
+        description:
+          "Joins the parts into the stored file once every part is present. Repeating the call returns the same result.",
+      },
+    })
+    .delete("/files/uploads/:id", async ({ request, params, set }) => {
+      await uploads.abort(await identity.userId(request), params.id);
+      set.status = 204;
+    }, {
+      transform: guard(origins),
+      params: uploadId,
+      detail: { tags: ["files"], summary: "Cancel a resumable upload and discard its parts" },
+    });
+}