@podosoft/podokit 1.3.0 → 1.4.0

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

@@ -1,13 +1,24 @@
 import { S3Client, type S3Stats } from "bun";
 import {
+  IN_MEMORY_READ_BYTES,
+  objectBodyChunks,
   objectListLimit,
+  type CompletedPart,
   type ListObjectsOptions,
+  type ObjectBody,
   type ObjectData,
   type ObjectInfo,
   type ObjectPage,
+  type UploadedPart,
 } from "@podosoft/podokit-runtime";
 import { ReadinessService } from "../health/readiness.service";
-import { storageSettings } from "./storage.config";
+import { S3Multipart } from "./s3-multipart";
+import { storageSettings, type StorageSettings } from "./storage.config";
+
+/** Part size for streamed writes. */
+export const STREAM_PART_BYTES = 8 * 1024 * 1024;
+/** Parts of one streamed write that may be in flight at once. */
+const STREAM_QUEUE_SIZE = 2;
 
 function isMissingObject(error: unknown): boolean {
   return error instanceof Error && "code" in error && error.code === "NoSuchKey";
@@ -27,46 +38,56 @@ function objectInfo(key: string, stats: S3Stats): ObjectInfo {
   };
 }
 
-/**
- * Downloads on the first read, so an unread body costs no request. Bun's
- * `S3File.stream()` reads ahead without backpressure and would hold the rest of
- * the object for a slow client; a presigned GET through fetch is paced by the
- * socket instead, and If-Match keeps it on the version that was described.
- */
-function download(client: S3Client, key: string, etag: string): ReadableStream<Uint8Array> {
-  const abort = new AbortController();
-  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
-  return new ReadableStream<Uint8Array>({
-    async pull(controller): Promise<void> {
-      if (!reader) {
-        const response = await fetch(client.presign(key, { expiresIn: 60 }), {
-          headers: { "if-match": etag },
-          decompress: false,
-          signal: abort.signal,
-        });
-        if (!response.ok || !response.body) {
-          await response.body?.cancel();
-          throw new Error(
-            response.status === 404 || response.status === 412
-              ? `Object ${key} changed while it was being read`
-              : `Object ${key} download failed with status ${response.status}`,
-          );
-        }
-        reader = response.body.getReader();
-      }
-      const next = await reader.read();
-      if (next.done) controller.close();
-      else controller.enqueue(next.value);
-    },
-    async cancel(reason): Promise<void> {
-      abort.abort(reason);
-      await reader?.cancel(reason).catch(() => undefined);
+function downloadedObjectInfo(key: string, headers: Headers): ObjectInfo {
+  const length = headers.get("content-length");
+  const etag = headers.get("etag");
+  const lastModified = new Date(headers.get("last-modified") ?? "");
+  const contentType = headers.get("content-type");
+  if (length === null || !/^\d+$/.test(length) || !etag || Number.isNaN(lastModified.getTime())) {
+    throw new Error(`Object ${key} download lacks its length, entity tag, or modification time`);
+  }
+  return {
+    key,
+    size: Number(length),
+    ...(contentType ? { contentType } : {}),
+    etag: entityTag(etag),
+    lastModified,
+  };
+}
+
+/** The S3 error code of a failed request, such as NoSuchKey or NoSuchBucket. */
+async function errorCode(response: Response): Promise<string | undefined> {
+  const text = await response.text().catch(() => "");
+  return /<Code>([^<]+)<\/Code>/.exec(text)?.[1];
+}
+
+function multipartClient(settings: StorageSettings): S3Multipart | undefined {
+  if (!settings.accessKeyId || !settings.secretAccessKey) return undefined;
+  return new S3Multipart({
+    bucket: settings.bucket,
+    region: settings.region,
+    virtualHostedStyle: settings.virtualHostedStyle,
+    ...(settings.endpoint ? { endpoint: settings.endpoint } : {}),
+    credentials: {
+      accessKeyId: settings.accessKeyId,
+      secretAccessKey: settings.secretAccessKey,
+      ...(settings.sessionToken ? { sessionToken: settings.sessionToken } : {}),
     },
-  }, { highWaterMark: 0 });
+  });
+}
+
+/** S3 needs each part's length before it is sent, so a streamed part is collected first. */
+async function partBytes(body: ObjectBody): Promise<Uint8Array | Blob> {
+  if (body instanceof Uint8Array || body instanceof Blob) return body;
+  if (typeof body === "string") return new TextEncoder().encode(body);
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of objectBodyChunks(body)) chunks.push(chunk);
+  return Buffer.concat(chunks);
 }
 
 export class StorageService {
   private readonly client: S3Client;
+  private readonly multipartRequests: S3Multipart | undefined;
   private unregisterReadiness?: () => void;
 
   constructor(readiness: ReadinessService) {
@@ -78,14 +99,108 @@ export class StorageService {
       ...(settings.endpoint ? { endpoint: settings.endpoint } : {}),
       ...(settings.accessKeyId ? { accessKeyId: settings.accessKeyId } : {}),
       ...(settings.secretAccessKey ? { secretAccessKey: settings.secretAccessKey } : {}),
+      ...(settings.sessionToken ? { sessionToken: settings.sessionToken } : {}),
     });
+    this.multipartRequests = multipartClient(settings);
     this.unregisterReadiness = readiness.register("object-storage", async () => {
       await this.client.exists(".podokit-readiness");
     });
   }
 
-  async put(key: string, body: Uint8Array | string | Blob, contentType?: string): Promise<void> {
-    await this.client.file(key).write(body, contentType ? { type: contentType } : undefined);
+  /**
+   * Writes an object and resolves with its size. Bytes, strings, and small
+   * blobs are sent in one request. Streams, async iterables, and larger blobs
+   * (including files) are sent in parts, holding about three parts in memory
+   * however large the object is; a source that fails aborts the upload, so no
+   * partial object is left behind.
+   */
+  async put(key: string, body: ObjectBody, contentType?: string): Promise<number> {
+    const options = contentType ? { type: contentType } : undefined;
+    if (
+      typeof body === "string" ||
+      body instanceof Uint8Array ||
+      (body instanceof Blob && body.size <= STREAM_PART_BYTES)
+    ) {
+      await this.client.file(key).write(body, options);
+      return typeof body === "string" ? Buffer.byteLength(body) : body instanceof Blob ? body.size : body.byteLength;
+    }
+    // Bun's S3 write reads a whole Blob, file-backed ones included, into memory,
+    // and its streaming writer completes rather than aborts when ended with an
+    // error, so streamed bodies use explicit multipart requests.
+    const parts: CompletedPart[] = [];
+    const pending = new Set<Promise<void>>();
+    let failure: { error: unknown } | undefined;
+    let uploadId: string | undefined;
+    let nextPartNumber = 1;
+    // Part buffers are reused once their upload finishes, so a long stream
+    // allocates at most one buffer per queue slot plus the one being filled.
+    const spare: Uint8Array[] = [];
+    let part: Uint8Array = new Uint8Array(STREAM_PART_BYTES);
+    let filled = 0;
+    let size = 0;
+    const send = async (buffer: Uint8Array, length: number): Promise<void> => {
+      uploadId ??= await this.multipart().create(key, contentType);
+      const id = uploadId;
+      const partNumber = nextPartNumber++;
+      const upload: Promise<void> = this.multipart()
+        .uploadPart(key, id, partNumber, buffer.subarray(0, length))
+        .then((etag) => { parts.push({ partNumber, etag }); })
+        .catch((error: unknown) => { failure ??= { error }; })
+        .finally(() => {
+          pending.delete(upload);
+          spare.push(buffer);
+        });
+      pending.add(upload);
+      while (pending.size >= STREAM_QUEUE_SIZE) await Promise.race(pending);
+      if (failure) throw failure.error;
+    };
+    try {
+      for await (const chunk of objectBodyChunks(body)) {
+        size += chunk.byteLength;
+        for (let offset = 0; offset < chunk.byteLength;) {
+          const length = Math.min(chunk.byteLength - offset, STREAM_PART_BYTES - filled);
+          part.set(chunk.subarray(offset, offset + length), filled);
+          filled += length;
+          offset += length;
+          if (filled === STREAM_PART_BYTES) {
+            await send(part, filled);
+            part = spare.pop() ?? new Uint8Array(STREAM_PART_BYTES);
+            filled = 0;
+          }
+        }
+      }
+      if (uploadId === undefined) {
+        await this.client.file(key).write(part.subarray(0, filled), options);
+        return size;
+      }
+      if (filled > 0) await send(part, filled);
+      await Promise.all(pending);
+      if (failure) throw failure.error;
+      await this.multipart().complete(key, uploadId, parts.sort((left, right) => left.partNumber - right.partNumber));
+      return size;
+    } catch (error) {
+      await Promise.allSettled(pending);
+      if (uploadId !== undefined) await this.multipart().abort(key, uploadId).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async createMultipartUpload(key: string, contentType?: string): Promise<string> {
+    return this.multipart().create(key, contentType);
+  }
+
+  async uploadPart(key: string, uploadId: string, partNumber: number, body: ObjectBody): Promise<UploadedPart> {
+    const bytes = await partBytes(body);
+    const etag = await this.multipart().uploadPart(key, uploadId, partNumber, bytes);
+    return { etag, size: bytes instanceof Blob ? bytes.size : bytes.byteLength };
+  }
+
+  async completeMultipartUpload(key: string, uploadId: string, parts: readonly CompletedPart[]): Promise<void> {
+    await this.multipart().complete(key, uploadId, parts);
+  }
+
+  async abortMultipartUpload(key: string, uploadId: string): Promise<void> {
+    await this.multipart().abort(key, uploadId);
   }
 
   /** Reads a whole object into memory. Use `open()` for anything that can be large. */
@@ -105,14 +220,35 @@ export class StorageService {
   }
 
   /**
-   * Metadata plus a streamed body, or null when the key does not exist. The
-   * metadata request comes first because a missing key would otherwise only
-   * fail the stream, after a response has already started.
+   * Metadata plus a streamed body, or null when the key does not exist. One
+   * GET describes and streams the same version, so the metadata always matches
+   * the content. Objects up to `IN_MEMORY_READ_BYTES` are read before this
+   * resolves, so a response built from them keeps its Content-Length. Larger
+   * ones stream from the GET, paced by the socket; Bun's `S3File.stream()` reads
+   * ahead without backpressure and would hold the rest of the object for a slow
+   * client. That download is already open, so read the body to the end or
+   * cancel it.
    */
   async open(key: string): Promise<ObjectData | null> {
-    const info = await this.stat(key);
-    if (!info) return null;
-    return { ...info, body: download(this.client, key, info.etag) };
+    const response = await fetch(this.client.presign(key, { expiresIn: 60 }), { decompress: false });
+    if (!response.ok || !response.body) {
+      const code = await errorCode(response);
+      if (response.status === 404 && code === "NoSuchKey") return null;
+      throw new Error(`Object ${key} download failed with status ${response.status}${code ? ` (${code})` : ""}`);
+    }
+    let info: ObjectInfo;
+    try {
+      info = downloadedObjectInfo(key, response.headers);
+    } catch (error) {
+      await response.body.cancel().catch(() => undefined);
+      throw error;
+    }
+    if (info.size > IN_MEMORY_READ_BYTES) return { ...info, body: response.body };
+    const bytes = await response.bytes();
+    if (bytes.byteLength !== info.size) {
+      throw new Error(`Object ${key} download ended after ${bytes.byteLength} of ${info.size} bytes`);
+    }
+    return { ...info, body: new Blob([bytes]).stream() };
   }
 
   /** One page of the keys under `prefix`; the bucket is never listed in full. */
@@ -143,4 +279,11 @@ export class StorageService {
   close(): void {
     this.unregisterReadiness?.();
   }
+
+  private multipart(): S3Multipart {
+    if (!this.multipartRequests) {
+      throw new Error("Multipart uploads need S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY (or the AWS_* equivalents)");
+    }
+    return this.multipartRequests;
+  }
 }

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

@@ -23,7 +23,13 @@
   ],
   "inject": [
     { "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," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "storageModule," },
+    {
+      "file": "AGENTS.md",
+      "marker": "<!-- podokit:end:agents-modules -->",
+      "optional": true,
+      "text": "### object-storage-s3\n- Store files through `OBJECT_STORAGE` from `@podosoft/podokit-runtime` (`services.resolve(OBJECT_STORAGE)`), not the provider directly. `put(key, body, { contentType })` streams a `ReadableStream` such as `request.body`, a `Blob` or file, an async iterable, bytes, or a string without buffering it; a failed body leaves no partial object.\n- For uploads split across requests (resumable or chunked), use `createMultipartUpload`, `uploadPart` (parts numbered 1 to 10,000, each but the last at least `MIN_MULTIPART_PART_BYTES` = 5 MiB), `completeMultipartUpload`, and `abortMultipartUpload`. Branch on `MultipartUploadError.code` (`UPLOAD_NOT_FOUND`, `INVALID_PART`, `PART_TOO_SMALL`).\n- Multipart requests are signed with the `S3_*` (or `AWS_*`) credentials. A part passed as a stream is held in memory while it is sent, so keep parts to tens of MiB. On AWS, add an `AbortIncompleteMultipartUpload` bucket lifecycle rule.\n"
+    }
   ],
   "instructions": [
     "Start Silo for local dev:  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
@@ -32,6 +38,8 @@
     "Store an object:  curl -b cookies.txt -XPUT localhost:5002/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
     "Read it back:     curl -b cookies.txt localhost:5002/storage/hello",
     "Presigned URL:    curl -b cookies.txt localhost:5002/storage/hello/presigned",
-    "For AWS S3: set STORAGE_PROVIDER=aws, remove S3_ENDPOINT, set S3_FORCE_PATH_STYLE=false and real credentials/bucket."
+    "For AWS S3: set STORAGE_PROVIDER=aws, remove S3_ENDPOINT, set S3_FORCE_PATH_STYLE=false and real credentials/bucket.",
+    "OBJECT_STORAGE.put streams large or streamed bodies as a multipart upload; uploads split across requests use createMultipartUpload, uploadPart, completeMultipartUpload, and abortMultipartUpload.",
+    "On AWS, add a bucket lifecycle rule with AbortIncompleteMultipartUpload so abandoned multipart uploads are removed."
   ]
 }

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

@@ -1,4 +1,4 @@
-import { CACHE, type CacheStore } from "@podosoft/podokit-runtime";
+import { CACHE, RATE_LIMIT_ROUTES, type CacheStore } from "@podosoft/podokit-runtime";
 import { AppException } from "../common/app-exception";
 import { API_KEY_VERIFIER } from "../api-key/api-key.module";
 import {
@@ -13,6 +13,10 @@ import {
   type RateLimitConfig,
 } from "./rate-limit.config";
 import { RateLimitIdentity } from "./rate-limit.identity";
+import { defaultRateLimitRoutes, generalProfile, type RateLimitRoutes } from "./rate-limit.routes";
+
+export { RATE_LIMIT_ROUTES } from "@podosoft/podokit-runtime";
+export type { RateLimitProfile, RateLimitRoute, RateLimitRouteRegistry } from "@podosoft/podokit-runtime";
 
 export interface RateLimitIncrement {
   count: number;
@@ -38,13 +42,12 @@ export class CacheRateLimitStorage implements RateLimitStorage {
   }
 }
 
-type LimitProfile = { name: string; ttlSeconds: number; limit: number };
-
 export class RateLimiter {
   constructor(
     private readonly config: RateLimitConfig,
     private readonly identity: RateLimitIdentity,
     private readonly storage: RateLimitStorage,
+    readonly routes: RateLimitRoutes = defaultRateLimitRoutes(config),
   ) {}
 
   async enforce(context: RequestGuardContext): Promise<void> {
@@ -55,8 +58,9 @@ export class RateLimiter {
       ["/health", "/health/ready", "/api-docs", "/api-docs-json", "/api-docs-elysia-json"].includes(path)
     ) return;
 
+    const profile = this.routes.resolve(request.method, path) ?? generalProfile(this.config);
+    if (profile === "exempt") return;
     try {
-      const profile = this.profile(request.method, path);
       const tracker = await this.identity.resolve(request, context.remoteAddress, this.config);
       await this.enforceCustom(profile.name, tracker, profile.ttlSeconds, profile.limit, context.setHeader);
     } catch (error) {
@@ -98,24 +102,6 @@ export class RateLimiter {
     }
   }
 
-  private profile(method: string, path: string): LimitProfile {
-    if (
-      method === "GET" &&
-      (path === "/api/auth/get-session" || path === "/site/settings")
-    ) {
-      return { name: "runtime", ttlSeconds: this.config.ttlSeconds, limit: this.config.runtimeLimit };
-    }
-    // Admin reads need an admin session and are not credential attempts. The
-    // dashboard and organizations pages read users through Better Auth.
-    if (method === "GET" && path.startsWith("/api/auth/admin/")) {
-      return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
-    }
-    if (path === "/api/auth" || path.startsWith("/api/auth/")) {
-      return { name: "auth", ttlSeconds: this.config.authTtlSeconds, limit: this.config.authLimit };
-    }
-    return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
-  }
-
   private async withTimeout(operation: Promise<RateLimitIncrement>): Promise<RateLimitIncrement> {
     let timer: ReturnType<typeof setTimeout> | undefined;
     try {
@@ -149,6 +135,9 @@ export const rateLimitModule: PodokitModule = {
       new CacheRateLimitStorage(services.resolve(CACHE)),
     );
     services.register(RATE_LIMITER, limiter);
+    // Other modules may configure before this one, so they register routes
+    // from their plugin factory, and applications from configureServices.
+    services.register(RATE_LIMIT_ROUTES, limiter.routes);
     services.resolve(REQUEST_GUARDS).register((context) => limiter.enforce(context));
   },
 };

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

@@ -0,0 +1,113 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { RequestGuardContext } from "../core/services";
+import type { RateLimitIdentity } from "./rate-limit.identity";
+import { RateLimiter } from "./rate-limit.module";
+import { defaultRateLimitRoutes, RateLimitRoutes } from "./rate-limit.routes";
+
+const config = {
+  keyPrefix: "podokit:test:rate-limit",
+  ttlSeconds: 60,
+  limit: 300,
+  authTtlSeconds: 60,
+  authLimit: 20,
+  runtimeLimit: 1000,
+  trustedProxyHops: 0,
+  proxyHeader: "x-forwarded-for",
+  storageTimeoutMs: 100,
+  unavailableRetryAfterSeconds: 1,
+};
+
+const uploads = { name: "uploads", limit: 5000, ttlSeconds: 60 };
+
+function context(path: string, method = "GET"): { value: RequestGuardContext; headers: Record<string, string> } {
+  const headers: Record<string, string> = {};
+  return {
+    headers,
+    value: {
+      request: new Request(`http://localhost${path}`, { method }),
+      remoteAddress: "127.0.0.1",
+      setHeader: (name, value) => { headers[name.toLowerCase()] = value; },
+    },
+  };
+}
+
+describe("RateLimitRoutes", () => {
+  test("picks the longest prefix, then a matching method, then the latest registration", () => {
+    const routes = new RateLimitRoutes(60);
+    routes.register({ pathPrefix: "/files", profile: { name: "files", limit: 100 } });
+    routes.register({ pathPrefix: "/files/uploads", profile: uploads });
+    routes.register({ method: "put", pathPrefix: "/files/uploads/", profile: "exempt" });
+    routes.register({ pathPrefix: "/reports", profile: { name: "reports", limit: 10 } });
+    routes.register({ pathPrefix: "/reports", profile: { name: "reports-v2", limit: 20 } });
+
+    expect(routes.resolve("GET", "/files/a.txt")).toEqual({ name: "files", limit: 100, ttlSeconds: 60 });
+    expect(routes.resolve("POST", "/files/uploads")).toEqual(uploads);
+    expect(routes.resolve("POST", "/files/uploads/1/parts/2")).toEqual(uploads);
+    expect(routes.resolve("PUT", "/files/uploads/1/parts/2")).toBe("exempt");
+    expect(routes.resolve("GET", "/reports/daily")).toMatchObject({ name: "reports-v2" });
+    // Prefixes match whole segments only.
+    expect(routes.resolve("GET", "/files-archive")).toBeUndefined();
+    expect(routes.resolve("GET", "/other")).toBeUndefined();
+  });
+
+  test("rejects invalid routes and conflicting budgets under one name", () => {
+    const routes = new RateLimitRoutes(60);
+    expect(() => routes.register({ pathPrefix: "uploads", profile: "exempt" })).toThrow("absolute path");
+    expect(() => routes.register({ pathPrefix: "/a?b", profile: "exempt" })).toThrow("absolute path");
+    expect(() => routes.register({ pathPrefix: "/a//b", profile: "exempt" })).toThrow("absolute path");
+    expect(() => routes.register({ method: "GET /", pathPrefix: "/a", profile: "exempt" })).toThrow("method");
+    expect(() => routes.register({ pathPrefix: "/a", profile: { name: "a:b", limit: 1 } })).toThrow("name");
+    expect(() => routes.register({ pathPrefix: "/a", profile: { name: "a", limit: 0 } })).toThrow("limit");
+    expect(() => routes.register({ pathPrefix: "/a", profile: { name: "a", limit: 1, ttlSeconds: 1.5 } }))
+      .toThrow("ttlSeconds");
+
+    routes.register({ pathPrefix: "/a", profile: { name: "shared", limit: 10 } });
+    routes.register({ pathPrefix: "/b", profile: { name: "shared", limit: 10, ttlSeconds: 60 } });
+    expect(() => routes.register({ pathPrefix: "/c", profile: { name: "shared", limit: 11 } }))
+      .toThrow("already registered");
+  });
+
+  test("registers the built-in budgets as routes", () => {
+    const routes = defaultRateLimitRoutes(config);
+    expect(routes.resolve("GET", "/anything")).toMatchObject({ name: "general", limit: 300 });
+    expect(routes.resolve("POST", "/api/auth/sign-in/email")).toMatchObject({ name: "auth", limit: 20 });
+    expect(routes.resolve("GET", "/api/auth/admin/list-users")).toMatchObject({ name: "general" });
+    expect(routes.resolve("POST", "/api/auth/admin/ban-user")).toMatchObject({ name: "auth" });
+    expect(routes.resolve("GET", "/api/auth/get-session")).toMatchObject({ name: "runtime", limit: 1000 });
+    expect(routes.resolve("GET", "/site/settings")).toMatchObject({ name: "runtime" });
+    expect(routes.resolve("PUT", "/site/settings")).toMatchObject({ name: "general" });
+    // The built-in names keep their limits.
+    expect(() => routes.register({ pathPrefix: "/x", profile: { name: "auth", limit: 1000 } }))
+      .toThrow("already registered");
+  });
+});
+
+describe("RateLimiter route profiles", () => {
+  test("counts a registered route in its own bucket and skips exempt routes", async () => {
+    const increment = mock(async (_key: string, _ttlSeconds: number) => ({ count: 1, retryAfterSeconds: 30 }));
+    const limiter = new RateLimiter(
+      config,
+      { resolve: async () => "session:test" } as unknown as RateLimitIdentity,
+      { increment },
+    );
+    const shortWindow = { ...uploads, ttlSeconds: 30 };
+    limiter.routes.register({ pathPrefix: "/files/uploads", profile: shortWindow });
+    limiter.routes.register({ method: "GET", pathPrefix: "/files/uploads/status", profile: "exempt" });
+    // A more specific route can take a path out of the authentication budget.
+    limiter.routes.register({ method: "GET", pathPrefix: "/api/auth/list-sessions", profile: shortWindow });
+
+    const upload = context("/files/uploads/1/parts/1", "PUT");
+    await limiter.enforce(upload.value);
+    await limiter.enforce(context("/files/uploads/status").value);
+    await limiter.enforce(context("/api/auth/list-sessions").value);
+    await limiter.enforce(context("/api/auth/sign-out", "POST").value);
+
+    expect(increment.mock.calls).toEqual([
+      ["podokit:test:rate-limit:uploads:session:test", 30],
+      ["podokit:test:rate-limit:uploads:session:test", 30],
+      ["podokit:test:rate-limit:auth:session:test", 60],
+    ]);
+    expect(upload.headers["ratelimit-limit"]).toBe("5000");
+    expect(upload.headers["ratelimit-remaining"]).toBe("4999");
+  });
+});

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

@@ -0,0 +1,122 @@
+import type {
+  RateLimitProfile,
+  RateLimitRoute,
+  RateLimitRouteRegistry,
+} from "@podosoft/podokit-runtime";
+import type { RateLimitConfig } from "./rate-limit.config";
+
+/** A budget with its window resolved, or "exempt". */
+export type ResolvedRateLimitProfile = Required<RateLimitProfile> | "exempt";
+
+interface RouteEntry {
+  method?: string;
+  prefix: string;
+  profile: ResolvedRateLimitProfile;
+}
+
+const PROFILE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const METHOD = /^[A-Z]+$/;
+
+function positiveInteger(value: number | undefined, label: string): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+}
+
+function normalizePrefix(prefix: string): string {
+  if (!prefix.startsWith("/") || /[?#\s]/.test(prefix) || prefix.includes("//")) {
+    throw new Error(`Rate limit path prefix must be an absolute path: ${prefix}`);
+  }
+  return prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
+
+function covers(prefix: string, path: string): boolean {
+  return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
+}
+
+/**
+ * Route profiles for the rate limiter. The built-in authentication and runtime
+ * budgets are registered here too, so a module's more specific route takes
+ * precedence over them by the same rule as over any other route.
+ */
+export class RateLimitRoutes implements RateLimitRouteRegistry {
+  private readonly entries: RouteEntry[] = [];
+  private readonly budgets = new Map<string, Required<RateLimitProfile>>();
+
+  constructor(private readonly defaultTtlSeconds: number) {}
+
+  register(route: RateLimitRoute): void {
+    const method = route.method?.toUpperCase();
+    if (method !== undefined && !METHOD.test(method)) {
+      throw new Error(`Rate limit route method is invalid: ${route.method}`);
+    }
+    const prefix = normalizePrefix(route.pathPrefix);
+    const profile = route.profile === "exempt" ? "exempt" : this.budget(route.profile);
+    this.entries.push({ ...(method ? { method } : {}), prefix, profile });
+  }
+
+  /** The most specific registered profile for a request, if any route matches. */
+  resolve(method: string, path: string): ResolvedRateLimitProfile | undefined {
+    let best: RouteEntry | undefined;
+    for (const entry of this.entries) {
+      if (entry.method !== undefined && entry.method !== method) continue;
+      if (!covers(entry.prefix, path)) continue;
+      // The longer prefix wins, then a route with a method, then the later one.
+      if (
+        !best ||
+        entry.prefix.length > best.prefix.length ||
+        (entry.prefix.length === best.prefix.length &&
+          (entry.method !== undefined || best.method === undefined))
+      ) {
+        best = entry;
+      }
+    }
+    return best?.profile;
+  }
+
+  private budget(profile: RateLimitProfile): Required<RateLimitProfile> {
+    if (!PROFILE_NAME.test(profile.name)) {
+      throw new Error(`Rate limit profile name must be 1-64 letters, digits, "_" or "-": ${profile.name}`);
+    }
+    positiveInteger(profile.limit, `Rate limit profile ${profile.name} limit`);
+    positiveInteger(profile.ttlSeconds, `Rate limit profile ${profile.name} ttlSeconds`);
+    const budget = {
+      name: profile.name,
+      limit: profile.limit,
+      ttlSeconds: profile.ttlSeconds ?? this.defaultTtlSeconds,
+    };
+    const existing = this.budgets.get(budget.name);
+    if (existing && (existing.limit !== budget.limit || existing.ttlSeconds !== budget.ttlSeconds)) {
+      throw new Error(
+        `Rate limit profile ${budget.name} is already registered with a limit of ${existing.limit} per ${existing.ttlSeconds}s`,
+      );
+    }
+    this.budgets.set(budget.name, budget);
+    return budget;
+  }
+}
+
+/** The general budget, which applies when no route matches. */
+export function generalProfile(config: RateLimitConfig): Required<RateLimitProfile> {
+  return { name: "general", limit: config.limit, ttlSeconds: config.ttlSeconds };
+}
+
+/**
+ * The built-in profiles. Authentication writes get the strict auth budget,
+ * while administrator reads (the admin pages read users through Better Auth)
+ * stay on the general budget, and session and public site-settings reads get
+ * the higher runtime budget.
+ */
+export function defaultRateLimitRoutes(config: RateLimitConfig): RateLimitRoutes {
+  const routes = new RateLimitRoutes(config.ttlSeconds);
+  const runtime = { name: "runtime", limit: config.runtimeLimit, ttlSeconds: config.ttlSeconds };
+  routes.register({ pathPrefix: "/", profile: generalProfile(config) });
+  routes.register({
+    pathPrefix: "/api/auth",
+    profile: { name: "auth", limit: config.authLimit, ttlSeconds: config.authTtlSeconds },
+  });
+  routes.register({ method: "GET", pathPrefix: "/api/auth/admin", profile: generalProfile(config) });
+  routes.register({ method: "GET", pathPrefix: "/api/auth/get-session", profile: runtime });
+  routes.register({ method: "GET", pathPrefix: "/site/settings", profile: runtime });
+  return routes;
+}

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -11,8 +11,13 @@ const origin = { origin: base };
 // Honor RATE_LIMIT_MAX when the test runner has it (a dedicated app sets a small
 // value so the window is crossed in a handful of requests); otherwise fall back
 // to the module default and allow a little headroom.
+// A local stack that raises the limits to run the whole suite quickly sets
+// E2E_SKIP_RATE_LIMIT=true and runs this file separately against the defaults.
+test.skip(process.env.E2E_SKIP_RATE_LIMIT === "true", "assumes the configured limits; run it on its own");
+
 const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
 const authLimit = Number(process.env.RATE_LIMIT_AUTH_MAX ?? 20);
+const runtimeLimit = Number(process.env.RATE_LIMIT_RUNTIME_MAX ?? 1000);
 
 async function session(
   playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
@@ -121,3 +126,22 @@ test("rate limit: session reads do not consume the strict authentication budget"
   }
   await ctx.dispose();
 });
+
+test("rate limit: each route is counted in its most specific registered budget", async ({
+  playwright,
+}) => {
+  const ctx = await session(playwright);
+  const probe = await ctx.get("/api/account/capabilities");
+  test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
+  const ceiling = (response: APIResponse): number => Number(response.headers()["ratelimit-limit"]);
+
+  // Ordinary routes fall back to the general budget registered at "/".
+  expect(ceiling(probe)).toBe(limit);
+  // Longer GET prefixes inside "/api/auth" win over its authentication budget:
+  // session reads use the runtime budget and administrator reads the general one.
+  expect(ceiling(await ctx.get("/api/auth/get-session"))).toBe(runtimeLimit);
+  expect(ceiling(await ctx.get("/api/auth/admin/list-users"))).toBe(limit);
+  // Other "/api/auth" requests carry the strict authentication budget.
+  expect(ceiling(await ctx.post("/api/auth/sign-out", { data: {} }))).toBe(authLimit);
+  await ctx.dispose();
+});