@podosoft/podokit 1.3.0 → 1.4.0

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" },
+    });
+}