@podosoft/podokit 0.17.4 → 1.0.2

package/dist/templates/modules/job-progress/files/apps/api/src/progress/job-progress.module.ts

@@ -1,13 +1,35 @@
-import { Module } from "@nestjs/common";
-import { BullModule } from "@nestjs/bullmq";
-import { ProgressController } from "./progress.controller";
+import { Queue } from "bullmq";
+import { Elysia, t } from "elysia";
+import type { AppPlugin, PodokitModule, ServiceKey } from "../core/services";
+import { EVENTS } from "../events/events.module";
+import { redisConnection } from "../jobs/queue";
+import { REDIS } from "../redis/redis.module";
 import { ProgressBridge } from "./progress.bridge";
 
-// API side: enqueue progress jobs and relay their progress to SSE.
-// RedisService and EventsService are provided globally by their modules.
-@Module({
-  imports: [BullModule.registerQueue({ name: "progress" })],
-  controllers: [ProgressController],
-  providers: [ProgressBridge],
-})
-export class JobProgressModule {}
+const PROGRESS_QUEUE = Symbol("progress-queue") as ServiceKey<Queue>;
+const PROGRESS_BRIDGE = Symbol("progress-bridge") as ServiceKey<ProgressBridge>;
+
+const progressPlugin: AppPlugin = ({ services }) => {
+  const queue = services.resolve(PROGRESS_QUEUE);
+  return new Elysia({ name: "podokit.job-progress" })
+    .post("/progress", async ({ body, set }) => {
+      const job = await queue.add("progress", { steps: body.steps ?? 5 });
+      set.status = 201;
+      return { jobId: job.id };
+    }, {
+      body: t.Object({ steps: t.Optional(t.Integer({ minimum: 1, maximum: 100 })) }),
+      detail: { tags: ["progress"], summary: "Start a progress job" },
+    });
+};
+
+export const jobProgressModule: PodokitModule = {
+  name: "job-progress",
+  configure: (_env, services): void => {
+    const queue = new Queue("progress", { connection: redisConnection() });
+    const bridge = new ProgressBridge(services.resolve(REDIS), services.resolve(EVENTS));
+    services.register(PROGRESS_QUEUE, queue, () => queue.close());
+    services.register(PROGRESS_BRIDGE, bridge, () => bridge.close());
+    services.onStart(() => bridge.connect());
+  },
+  plugin: progressPlugin,
+};

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.bridge.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, jest } from "@jest/globals";
+import { describe, expect, it, mock } from "bun:test";
 import type { EventsService } from "../events/events.service";
 import type { RedisService } from "../redis/redis.service";
 import { ProgressBridge } from "./progress.bridge";
@@ -7,20 +7,20 @@ import { PROGRESS_CHANNEL } from "./progress.processor";
 describe("ProgressBridge", () => {
   it("delivers worker fan-out locally without republishing it", async () => {
     let handler: ((message: string) => void) | undefined;
-    const unsubscribe = jest.fn<() => Promise<void>>(() => Promise.resolve());
-    const subscribe = jest.fn(
+    const unsubscribe = mock<() => Promise<void>>(() => Promise.resolve());
+    const subscribe = mock(
       (channel: string, listener: (message: string) => void): Promise<() => Promise<void>> => {
         expect(channel).toBe(PROGRESS_CHANNEL);
         handler = listener;
         return Promise.resolve(unsubscribe);
       },
     );
-    const publishLocal = jest.fn<(data: unknown) => void>();
+    const publishLocal = mock<(data: unknown) => void>();
     const redis = { subscribe } as unknown as RedisService;
     const events = { publishLocal } as unknown as EventsService;
     const bridge = new ProgressBridge(redis, events);
 
-    await bridge.onModuleInit();
+    await bridge.connect();
     handler?.('{"jobId":"1","progress":50}');
     handler?.("invalid");
 
@@ -30,7 +30,7 @@ describe("ProgressBridge", () => {
       jobId: "1",
       progress: 50,
     });
-    await bridge.onModuleDestroy();
+    await bridge.close();
     expect(unsubscribe).toHaveBeenCalledTimes(1);
   });
 });

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.bridge.ts

@@ -1,17 +1,9 @@
-import {
-  Injectable,
-  Logger,
-  type OnModuleDestroy,
-  type OnModuleInit,
-} from "@nestjs/common";
 import { RedisService } from "../redis/redis.service";
 import { EventsService } from "../events/events.service";
 import { PROGRESS_CHANNEL } from "./progress.processor";
 
 // Runs in the API process: relays worker progress (Redis pub/sub) to SSE.
-@Injectable()
-export class ProgressBridge implements OnModuleInit, OnModuleDestroy {
-  private readonly logger = new Logger(ProgressBridge.name);
+export class ProgressBridge {
   private unsubscribe?: () => Promise<void>;
 
   constructor(
@@ -19,22 +11,22 @@ export class ProgressBridge implements OnModuleInit, OnModuleDestroy {
     private readonly events: EventsService,
   ) {}
 
-  async onModuleInit(): Promise<void> {
+  async connect(): Promise<void> {
     this.unsubscribe = await this.redis.subscribe(PROGRESS_CHANNEL, (message) => {
       try {
         const parsed: unknown = JSON.parse(message);
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-          this.logger.warn("Discarded invalid job progress event");
+          process.stderr.write("Discard invalid job progress event\n");
           return;
         }
         this.events.publishLocal({ type: "job-progress", ...parsed });
       } catch {
-        this.logger.warn("Discarded malformed job progress event");
+        process.stderr.write("Discard malformed job progress event\n");
       }
     });
   }
 
-  async onModuleDestroy(): Promise<void> {
+  async close(): Promise<void> {
     await this.unsubscribe?.();
   }
 }

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.processor.ts

@@ -1,25 +1,18 @@
-import { Processor, WorkerHost } from "@nestjs/bullmq";
+import { RedisClient } from "bun";
 import type { Job } from "bullmq";
-import { RedisService } from "../redis/redis.service";
+import { redisConnectionUrl } from "../config/redis.connection";
 
 export const PROGRESS_CHANNEL = "job:progress";
 
-// Runs in the worker process. Reports progress both to BullMQ and, via Redis
-// pub/sub, to the API process (which relays it to SSE clients).
-@Processor("progress")
-export class ProgressProcessor extends WorkerHost {
-  constructor(private readonly redis: RedisService) {
-    super();
-  }
+const redis = new RedisClient(redisConnectionUrl());
 
-  async process(job: Job<{ steps?: number }>): Promise<{ done: true }> {
-    const steps = job.data.steps ?? 5;
-    for (let i = 1; i <= steps; i += 1) {
-      await new Promise((resolve) => setTimeout(resolve, 400));
-      const progress = Math.round((i / steps) * 100);
-      await job.updateProgress(progress);
-      await this.redis.publish(PROGRESS_CHANNEL, JSON.stringify({ jobId: job.id, progress }));
-    }
-    return { done: true };
+export async function processProgressJob(job: Job<{ steps?: number }>): Promise<{ done: true }> {
+  const steps = job.data.steps ?? 5;
+  for (let index = 1; index <= steps; index += 1) {
+    await Bun.sleep(400);
+    const progress = Math.round((index / steps) * 100);
+    await job.updateProgress(progress);
+    await redis.publish(PROGRESS_CHANNEL, JSON.stringify({ jobId: job.id, progress }));
   }
+  return { done: true };
 }

package/dist/templates/modules/job-progress/module.manifest.json

@@ -5,17 +5,14 @@
   "targetApp": "api",
   "env": [],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { JobProgressModule } from \"./progress/job-progress.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "JobProgressModule," },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-imports", "text": "import { ProgressProcessor } from \"../progress/progress.processor\";" },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-imports", "text": "import { RedisModule } from \"../redis/redis.module\";" },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-queues", "text": "RedisModule," },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-queues", "text": "BullModule.registerQueue({ name: \"progress\" })," },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-providers", "text": "ProgressProcessor," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { jobProgressModule } from \"./progress/job-progress.module\";" },
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "jobProgressModule," },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-imports", "text": "import { processProgressJob } from \"../progress/progress.processor\";" },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-processors", "text": "{ queue: \"progress\", processor: processProgressJob }," }
   ],
   "instructions": [
     "Start Redis + Postgres:  docker compose -f infra/docker/docker-compose.yml up -d",
-    "Run API and worker in separate terminals:  npm run dev   /   npm run dev:worker -w <app>-api",
+    "Run API and worker in separate terminals:  {{rootRun}} dev   /   {{apiRun}} dev:worker{{apiWorkspaceArg}}",
     "Watch progress:  curl -N localhost:5002/events/stream",
     "Start a job:     curl -XPOST localhost:5002/progress -H 'content-type: application/json' -d '{\"steps\":5}'",
     "The stream shows job-progress events 20 -> 40 -> ... -> 100 pushed from the worker via Redis."

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

@@ -1,29 +1,16 @@
-import { Module } from "@nestjs/common";
-import { randomUUID } from "node:crypto";
-import type { IncomingMessage, ServerResponse } from "node:http";
-import { LoggerModule } from "nestjs-pino";
+import pino from "pino";
+import { LOGGER, type PodokitModule } from "../core/services";
 
-const isProduction = process.env.NODE_ENV === "production";
-
-// Structured request logging with a correlation id. Importing this module
-// installs the pino-http middleware for all routes.
-@Module({
-  imports: [
-    LoggerModule.forRoot({
-      pinoHttp: {
-        level: process.env.LOG_LEVEL ?? "info",
-        // Pretty, single-line logs in dev; JSON in production.
-        transport: isProduction ? undefined : { target: "pino-pretty", options: { singleLine: true } },
-        autoLogging: true,
-        // One id per request; honor an inbound x-request-id and echo it back.
-        genReqId: (req: IncomingMessage, res: ServerResponse): string => {
-          const header = req.headers["x-request-id"];
-          const id = (Array.isArray(header) ? header[0] : header) ?? randomUUID();
-          res.setHeader("x-request-id", id);
-          return id;
-        },
-      },
-    }),
-  ],
-})
-export class LoggingModule {}
+export const loggingModule: PodokitModule = {
+  name: "logging",
+  configure: (_env, services): void => {
+    const isProduction = process.env.NODE_ENV === "production";
+    const logger = pino({
+      level: process.env.LOG_LEVEL ?? "info",
+      transport: isProduction
+        ? undefined
+        : { target: "pino-pretty", options: { singleLine: true } },
+    });
+    services.override(LOGGER, logger);
+  },
+};

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

@@ -1,11 +1,10 @@
 {
   "name": "logging",
-  "description": "Structured request logging (nestjs-pino) with a per-request correlation id (x-request-id). Pretty in dev, JSON in production.",
+  "description": "Structured Elysia request logging with a per-request correlation id (x-request-id). Pretty in dev, JSON in production.",
   "requires": [],
   "targetApp": "api",
   "dependencies": {
-    "nestjs-pino": "^4.3.0",
-    "pino-http": "^10.3.0"
+    "pino": "^9.6.0"
   },
   "devDependencies": {
     "pino-pretty": "^13.0.0"
@@ -15,13 +14,13 @@
     "LOG_LEVEL=info"
   ],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { LoggingModule } from \"./logging/logging.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "LoggingModule," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { loggingModule } from \"./logging/logging.module\";" },
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "loggingModule," }
   ],
   "instructions": [
     "Every HTTP request is now logged as structured JSON with a correlation id.",
     "Make a request and watch the API logs:  curl localhost:5002/health",
     "Set LOG_LEVEL (debug|info|warn|error) in .env. Logs are pretty in dev and JSON when NODE_ENV=production.",
-    "To route Nest's own logs through pino too, add to main.ts: NestFactory.create(AppModule, { bufferLogs: true }) then app.useLogger(app.get(Logger))."
+    "Resolve the logger through the startup service registry when adding application-specific infrastructure."
   ]
 }

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

@@ -4,12 +4,12 @@
   "requires": [],
   "targetApp": "api",
   "dependencies": {
-    "nodemailer": "^7.0.9",
+    "nodemailer": "^9.0.5",
     "@podosoft/podokit-auth": "^0.3.0",
     "pg": "^8.12.0"
   },
   "devDependencies": {
-    "@types/nodemailer": "^7.0.4",
+    "@types/nodemailer": "^8.0.1",
     "@types/pg": "^8.11.10"
   },
   "env": [

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.config.spec.ts

@@ -0,0 +1,20 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { storageSettings } from "./storage.config";
+
+const original = { ...process.env };
+
+afterEach(() => {
+  process.env = { ...original };
+});
+
+describe("storageSettings", () => {
+  it("uses path-style MinIO settings by default", () => {
+    process.env.STORAGE_PROVIDER = "minio";
+    process.env.S3_ENDPOINT = "http://localhost:9000";
+    expect(storageSettings()).toMatchObject({
+      provider: "minio",
+      endpoint: "http://localhost:9000",
+      virtualHostedStyle: false,
+    });
+  });
+});

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.config.ts

@@ -1,31 +1,27 @@
-import type { S3ClientConfig } from "@aws-sdk/client-s3";
-
 export interface StorageSettings {
   provider: "minio" | "aws";
   bucket: string;
+  region: string;
+  endpoint?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  virtualHostedStyle: boolean;
 }
 
 export function storageSettings(): StorageSettings {
   const provider = process.env.STORAGE_PROVIDER === "aws" ? "aws" : "minio";
-  return { provider, bucket: process.env.S3_BUCKET ?? "podokit" };
-}
-
-// Build an S3 client config that works for both AWS S3 and MinIO.
-// MinIO needs a custom endpoint and path-style addressing; AWS does not.
-export function storageClientConfig(): S3ClientConfig {
-  const { provider } = storageSettings();
-  const region = process.env.S3_REGION ?? "us-east-1";
-
+  const endpoint = process.env.S3_ENDPOINT;
   const accessKeyId = process.env.S3_ACCESS_KEY_ID;
   const secretAccessKey = process.env.S3_SECRET_ACCESS_KEY;
-  const credentials = accessKeyId && secretAccessKey ? { accessKeyId, secretAccessKey } : undefined;
-
-  const forcePathStyle = process.env.S3_FORCE_PATH_STYLE
-    ? process.env.S3_FORCE_PATH_STYLE === "true"
-    : provider === "minio";
-
-  const config: S3ClientConfig = { region, forcePathStyle };
-  if (credentials) config.credentials = credentials;
-  if (process.env.S3_ENDPOINT) config.endpoint = process.env.S3_ENDPOINT;
-  return config;
+  return {
+    provider,
+    bucket: process.env.S3_BUCKET ?? "podokit",
+    region: process.env.S3_REGION ?? "us-east-1",
+    virtualHostedStyle: process.env.S3_FORCE_PATH_STYLE
+      ? process.env.S3_FORCE_PATH_STYLE !== "true"
+      : provider === "aws",
+    ...(endpoint ? { endpoint } : {}),
+    ...(accessKeyId ? { accessKeyId } : {}),
+    ...(secretAccessKey ? { secretAccessKey } : {}),
+  };
 }

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.module.ts

@@ -1,11 +1,45 @@
-import { Global, Module } from "@nestjs/common";
-import { StorageController } from "./storage.controller";
+import { Elysia, t } from "elysia";
+import {
+  type AppPlugin,
+  type PodokitModule,
+  READINESS,
+  type ServiceKey,
+} from "../core/services";
 import { StorageService } from "./storage.service";
 
-@Global()
-@Module({
-  controllers: [StorageController],
-  providers: [StorageService],
-  exports: [StorageService],
-})
-export class StorageModule {}
+export const STORAGE = Symbol("storage") as ServiceKey<StorageService>;
+
+const storagePlugin: AppPlugin = ({ services }) => {
+  const storage = services.resolve(STORAGE);
+  return new Elysia({ name: "podokit.storage" })
+    .put("/storage/:key", async ({ params, body }) => {
+      await storage.put(params.key, body.content, "text/plain");
+      return { key: params.key };
+    }, {
+      params: t.Object({ key: t.String({ minLength: 1 }) }),
+      body: t.Object({ content: t.String() }),
+      detail: { tags: ["storage"], summary: "Store an object" },
+    })
+    .get("/storage/:key/presigned", async ({ params }) => ({
+      url: await storage.presignedGetUrl(params.key),
+    }), {
+      params: t.Object({ key: t.String({ minLength: 1 }) }),
+      detail: { tags: ["storage"], summary: "Presign an object download" },
+    })
+    .get("/storage/:key", async ({ params }) => ({
+      key: params.key,
+      content: (await storage.get(params.key)).toString("utf8"),
+    }), {
+      params: t.Object({ key: t.String({ minLength: 1 }) }),
+      detail: { tags: ["storage"], summary: "Read an object" },
+    });
+};
+
+export const storageModule: PodokitModule = {
+  name: "object-storage-s3",
+  configure: (_env, services): void => {
+    const storage = new StorageService(services.resolve(READINESS));
+    services.register(STORAGE, storage, () => storage.close());
+  },
+  plugin: storagePlugin,
+};

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.service.ts

@@ -1,56 +1,47 @@
-import { Injectable, type OnModuleDestroy, type OnModuleInit } from "@nestjs/common";
-import {
-  DeleteObjectCommand,
-  GetObjectCommand,
-  HeadBucketCommand,
-  PutObjectCommand,
-  S3Client,
-} from "@aws-sdk/client-s3";
-import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { S3Client } from "bun";
 import { ReadinessService } from "../health/readiness.service";
-import { storageClientConfig, storageSettings } from "./storage.config";
+import { storageSettings } from "./storage.config";
 
-@Injectable()
-export class StorageService implements OnModuleInit, OnModuleDestroy {
-  private readonly client = new S3Client(storageClientConfig());
-  private readonly bucket = storageSettings().bucket;
+export class StorageService {
+  private readonly client: S3Client;
   private unregisterReadiness?: () => void;
 
-  constructor(private readonly readiness: ReadinessService) {}
-
-  onModuleInit(): void {
-    this.unregisterReadiness = this.readiness.register("object-storage", async () => {
-      await this.client.send(
-        new HeadBucketCommand({ Bucket: this.bucket }),
-        { abortSignal: AbortSignal.timeout(3_000) },
-      );
+  constructor(readiness: ReadinessService) {
+    const settings = storageSettings();
+    this.client = new S3Client({
+      bucket: settings.bucket,
+      region: settings.region,
+      virtualHostedStyle: settings.virtualHostedStyle,
+      ...(settings.endpoint ? { endpoint: settings.endpoint } : {}),
+      ...(settings.accessKeyId ? { accessKeyId: settings.accessKeyId } : {}),
+      ...(settings.secretAccessKey ? { secretAccessKey: settings.secretAccessKey } : {}),
+    });
+    this.unregisterReadiness = readiness.register("object-storage", async () => {
+      await this.client.exists(".podokit-readiness");
     });
   }
 
-  async put(key: string, body: Buffer | string, contentType?: string): Promise<void> {
-    await this.client.send(
-      new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body, ContentType: contentType }),
-    );
+  async put(key: string, body: Uint8Array | string | Blob, contentType?: string): Promise<void> {
+    await this.client.file(key).write(body, contentType ? { type: contentType } : undefined);
   }
 
   async get(key: string): Promise<Buffer> {
-    const res = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));
-    const bytes = await res.Body?.transformToByteArray();
-    return Buffer.from(bytes ?? new Uint8Array());
+    return Buffer.from(await this.client.file(key).bytes());
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return this.client.exists(key);
   }
 
   presignedGetUrl(key: string, expiresIn = 3600): Promise<string> {
-    return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), {
-      expiresIn,
-    });
+    return Promise.resolve(this.client.presign(key, { expiresIn }));
   }
 
   async delete(key: string): Promise<void> {
-    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+    await this.client.delete(key);
   }
 
-  onModuleDestroy(): void {
+  close(): void {
     this.unregisterReadiness?.();
-    this.client.destroy();
   }
 }

package/dist/templates/modules/object-storage-s3/module.manifest.json

@@ -1,15 +1,11 @@
 {
   "name": "object-storage-s3",
-  "description": "S3-compatible object storage (AWS S3 or MinIO, chosen by STORAGE_PROVIDER) with a StorageService and presigned URLs.",
+  "description": "Bun-native S3-compatible object storage for AWS S3 or MinIO with a StorageService and presigned URLs.",
   "requires": [],
   "requiredProjectFiles": [
     "apps/api/src/health/readiness.service.ts"
   ],
   "targetApp": "api",
-  "dependencies": {
-    "@aws-sdk/client-s3": "^3.700.0",
-    "@aws-sdk/s3-request-presigner": "^3.700.0"
-  },
   "env": [
     "# object storage — STORAGE_PROVIDER: minio | aws",
     "STORAGE_PROVIDER=minio",
@@ -21,8 +17,8 @@
     "S3_FORCE_PATH_STYLE=true"
   ],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { StorageModule } from \"./storage/storage.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "StorageModule," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { storageModule } from \"./storage/storage.module\";" },
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "storageModule," }
   ],
   "instructions": [
     "Start MinIO for local dev:  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.config.spec.ts

@@ -1,13 +1,14 @@
-import { describe, expect, it } from "@jest/globals";
+import { describe, expect, test } from "bun:test";
 import {
   clientAddressFromProxy,
   rateLimitConfig,
 } from "./rate-limit.config";
 
 describe("rate limit configuration", () => {
-  it("validates route limits and proxy settings", () => {
+  test("validates route limits and proxy settings", () => {
     expect(
       rateLimitConfig({
+        RATE_LIMIT_KEY_PREFIX: "podokit:tenant-a:rate-limit",
         RATE_LIMIT_TTL: "30",
         RATE_LIMIT_MAX: "250",
         RATE_LIMIT_AUTH_TTL: "45",
@@ -19,6 +20,7 @@ describe("rate limit configuration", () => {
         RATE_LIMIT_UNAVAILABLE_RETRY_AFTER: "3",
       }),
     ).toEqual({
+      keyPrefix: "podokit:tenant-a:rate-limit",
       ttlSeconds: 30,
       limit: 250,
       authTtlSeconds: 45,
@@ -38,9 +40,13 @@ describe("rate limit configuration", () => {
     expect(() =>
       rateLimitConfig({ RATE_LIMIT_PROXY_HEADER: "invalid header" }),
     ).toThrow("must be a valid HTTP header name");
+    expect(() => rateLimitConfig({ RATE_LIMIT_KEY_PREFIX: "invalid prefix!" })).toThrow(
+      "RATE_LIMIT_KEY_PREFIX must be 1-128 characters",
+    );
+    expect(rateLimitConfig({}).keyPrefix).toBe("podokit:rate-limit");
   });
 
-  it("selects only the address outside the configured trusted proxy depth", () => {
+  test("selects only the address outside the configured trusted proxy depth", () => {
     const headers = {
       "x-forwarded-for": "203.0.113.7, 198.51.100.8",
     };
@@ -64,7 +70,7 @@ describe("rate limit configuration", () => {
     ).toBe("10.0.0.9");
   });
 
-  it("ignores malformed or incomplete forwarded chains", () => {
+  test("ignores malformed or incomplete forwarded chains", () => {
     expect(
       clientAddressFromProxy(
         { "x-forwarded-for": "attacker-controlled" },

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.config.ts

@@ -1,6 +1,7 @@
 import { isIP } from "node:net";
 
 export interface RateLimitConfig {
+  keyPrefix: string;
   ttlSeconds: number;
   limit: number;
   authTtlSeconds: number;
@@ -12,6 +13,16 @@ export interface RateLimitConfig {
   unavailableRetryAfterSeconds: number;
 }
 
+function keyPrefix(value: string | undefined): string {
+  const normalized = (value || "podokit:rate-limit").trim();
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9:_-]{0,127}$/.test(normalized)) {
+    throw new Error(
+      "RATE_LIMIT_KEY_PREFIX must be 1-128 characters using letters, numbers, colons, underscores, or hyphens",
+    );
+  }
+  return normalized;
+}
+
 function positiveInteger(name: string, value: string | undefined, fallback: number): number {
   if (value === undefined || value === "") return fallback;
   const parsed = Number(value);
@@ -40,6 +51,7 @@ function headerName(value: string | undefined): string {
 
 export function rateLimitConfig(env: NodeJS.ProcessEnv = process.env): RateLimitConfig {
   return {
+    keyPrefix: keyPrefix(env.RATE_LIMIT_KEY_PREFIX),
     ttlSeconds: positiveInteger("RATE_LIMIT_TTL", env.RATE_LIMIT_TTL, 60),
     limit: positiveInteger("RATE_LIMIT_MAX", env.RATE_LIMIT_MAX, 300),
     authTtlSeconds: positiveInteger(
@@ -82,6 +94,7 @@ function normalizeIp(value: string | undefined): string | undefined {
 }
 
 function headerValue(headers: unknown, name: string): string | undefined {
+  if (headers instanceof Headers) return headers.get(name) ?? undefined;
   if (!headers || typeof headers !== "object") return undefined;
   const value = (headers as Record<string, unknown>)[name];
   if (typeof value === "string") return value;