@podosoft/podokit 1.4.1 → 1.5.0

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

@@ -8,14 +8,18 @@ import type { RateLimitConfig } from "./rate-limit.config";
 /** A budget with its window resolved, or "exempt". */
 export type ResolvedRateLimitProfile = Required<RateLimitProfile> | "exempt";
 
+/** A literal path segment, or null for a `:name` parameter. */
+type Segment = string | null;
+
 interface RouteEntry {
   method?: string;
-  prefix: string;
+  segments: Segment[];
   profile: ResolvedRateLimitProfile;
 }
 
 const PROFILE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const METHOD = /^[A-Z]+$/;
+const PARAMETER = /^:[A-Za-z_][A-Za-z0-9_]*$/;
 
 function positiveInteger(value: number | undefined, label: string): void {
   if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) {
@@ -23,15 +27,47 @@ function positiveInteger(value: number | undefined, label: string): void {
   }
 }
 
-function normalizePrefix(prefix: string): string {
+function parsePrefix(prefix: string): Segment[] {
   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;
+  if (prefix.includes("*")) {
+    throw new Error(`Rate limit path prefix takes ":name" parameters, not wildcards: ${prefix}`);
+  }
+  const base = prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  return base === "/"
+    ? []
+    : base.slice(1).split("/").map((segment) => {
+        if (segment === "." || segment === "..") {
+          throw new Error(`Rate limit path prefix must not contain "." or ".." segments: ${prefix}`);
+        }
+        if (!segment.startsWith(":")) return segment;
+        if (!PARAMETER.test(segment)) {
+          throw new Error(`Rate limit path parameter must be ":" and a name such as ":hostId": ${prefix}`);
+        }
+        return null;
+      });
+}
+
+/** Whole-segment prefix match; a parameter matches one non-empty segment. */
+function covers(segments: Segment[], path: string[]): boolean {
+  return (
+    path.length >= segments.length &&
+    segments.every((segment, index) => (segment === null ? path[index] !== "" : segment === path[index]))
+  );
 }
 
-function covers(prefix: string, path: string): boolean {
-  return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
+/**
+ * Below zero when `a` is more specific: more segments, then, from the left, a
+ * literal segment before a parameter.
+ */
+function compareSpecificity(a: Segment[], b: Segment[]): number {
+  if (a.length !== b.length) return b.length - a.length;
+  for (let index = 0; index < a.length; index += 1) {
+    const literalA = a[index] !== null;
+    if (literalA !== (b[index] !== null)) return literalA ? -1 : 1;
+  }
+  return 0;
 }
 
 /**
@@ -50,24 +86,21 @@ export class RateLimitRoutes implements RateLimitRouteRegistry {
     if (method !== undefined && !METHOD.test(method)) {
       throw new Error(`Rate limit route method is invalid: ${route.method}`);
     }
-    const prefix = normalizePrefix(route.pathPrefix);
+    const segments = parsePrefix(route.pathPrefix);
     const profile = route.profile === "exempt" ? "exempt" : this.budget(route.profile);
-    this.entries.push({ ...(method ? { method } : {}), prefix, profile });
+    this.entries.push({ ...(method ? { method } : {}), segments, profile });
   }
 
   /** The most specific registered profile for a request, if any route matches. */
   resolve(method: string, path: string): ResolvedRateLimitProfile | undefined {
+    const pathSegments = path.split("/").slice(1);
     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))
-      ) {
+      if (!covers(entry.segments, pathSegments)) continue;
+      // The more specific prefix wins, then a route with a method, then the later one.
+      const order = best ? compareSpecificity(entry.segments, best.segments) : -1;
+      if (order < 0 || (order === 0 && (entry.method !== undefined || best?.method === undefined))) {
         best = entry;
       }
     }

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

@@ -70,7 +70,7 @@ test("rate limit: health probes stay available while ordinary routes return 429
   await ctx.dispose();
 });
 
-test("rate limit: each signed session has its own counter and forged sessions do not", async ({
+test("rate limit: a user's sessions share one counter and forged sessions do not get one", async ({
   playwright,
 }) => {
   const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
@@ -81,21 +81,31 @@ test("rate limit: each signed session has its own counter and forged sessions do
   test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
   const remaining = (response: APIResponse): number => Number(response.headers()["ratelimit-remaining"]);
   const ceiling = Number(probe.headers()["ratelimit-limit"]);
-  expect(remaining(probe)).toBe(ceiling - 1);
 
-  // The signed bearer form of the same session shares its counter.
+  // A second sign-in of the same user, and the signed bearer form of the first
+  // session. The probe requires a session, so each request below resolves it; a
+  // session counts under its user from the request after the API first resolves
+  // it (or from that request when authentication runs before the limiter).
+  const second = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  expect((await second.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBeTruthy();
   const cookie = (await first.storageState()).cookies.find((c) => c.name.endsWith("session_token"));
   expect(cookie, "sign-up set a session cookie").toBeTruthy();
   const bearer = await playwright.request.newContext({
     baseURL: base,
     extraHTTPHeaders: { ...origin, authorization: `Bearer ${cookie?.value ?? ""}` },
   });
-  expect(remaining(await bearer.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 2);
+  await second.get("/api/cache/rate-limit-probe");
 
-  // Counters follow the session, not the user: signing in again starts a new one.
-  const second = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  expect((await second.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBeTruthy();
-  expect(remaining(await second.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 1);
+  // Both sessions now draw from one budget: each request lowers what the next
+  // one, from either session, has left.
+  const fromFirst = remaining(await first.get("/api/cache/rate-limit-probe"));
+  expect(remaining(await second.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 1);
+  expect(remaining(await bearer.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 2);
+  expect(remaining(await first.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 3);
+
+  // Another user has a budget of their own.
+  const other = await session(playwright);
+  expect(remaining(await other.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 1);
 
   // A session cookie without a valid signature is counted with anonymous traffic
   // from the same client address instead of receiving a fresh counter. The cache
@@ -113,12 +123,13 @@ test("rate limit: each signed session has its own counter and forged sessions do
     expect(remaining(after)).toBeLessThan(remaining(before));
   }).toPass({ timeout: 10_000 });
 
-  for (const context of [first, bearer, second, forged, anonymous]) await context.dispose();
+  for (const context of [first, second, bearer, other, forged, anonymous]) await context.dispose();
 });
 
 test("rate limit: session reads do not consume the strict authentication budget", async ({
   playwright,
 }) => {
+  test.skip(authLimit > 1000, "the authentication budget is too large to exhaust here");
   const ctx = await session(playwright);
   for (let i = 0; i < authLimit + 5; i++) {
     const response = await ctx.get("/api/auth/get-session");

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "rate-limit",
   "manifestVersion": 3,
-  "description": "Provider-neutral Elysia request limiting by validated API key, signed-in session, or trusted-proxy client address.",
+  "description": "Provider-neutral Elysia request limiting by validated API key, signed-in user, or trusted-proxy client address.",
   "requires": ["api-key-auth"],
   "requiresCapabilities": ["cache"],
   "targetApp": "api",
@@ -19,9 +19,6 @@
     "RATE_LIMIT_AUTH_MAX=20",
     "# higher ceiling for SSR runtime settings and session reads",
     "RATE_LIMIT_RUNTIME_MAX=1000",
-    "# trust no proxy hop by default; set the exact production proxy depth",
-    "RATE_LIMIT_TRUSTED_PROXY_HOPS=0",
-    "RATE_LIMIT_PROXY_HEADER=x-forwarded-for",
     "RATE_LIMIT_STORAGE_TIMEOUT_MS=1000",
     "RATE_LIMIT_UNAVAILABLE_RETRY_AFTER=1"
   ],
@@ -40,20 +37,20 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### rate-limit\n- Every request counts against a per-caller budget (general, `/api/auth`, or runtime reads); exceeded limits return 429 `RATE_LIMIT_EXCEEDED` with `Retry-After`.\n- Give routes that legitimately send many requests, such as upload chunks, their own budget instead of raising `RATE_LIMIT_MAX`: `services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method: \"PUT\", pathPrefix: \"/uploads\", profile: { name: \"uploads\", limit: 3000 } })` (`RATE_LIMIT_ROUTES` from `@podosoft/podokit-runtime`). Register from a module's `plugin` factory or `configureServices()` in `app.extensions.ts`; the most specific prefix wins, and `profile: \"exempt\"` skips limiting.\n- Prefixes are API paths (`/uploads`, not the web proxy's `/api/uploads`); Better Auth routes keep `/api/auth`.\n"
+      "text": "### rate-limit\n- Every request counts against a per-caller budget (general, `/api/auth`, or runtime reads), keyed by API key, then signed-in user, then client address; exceeded limits return 429 `RATE_LIMIT_EXCEEDED` with `Retry-After`. A user's sessions share one budget once the API has resolved them for a request.\n- Give routes that legitimately send many requests, such as upload chunks, their own budget instead of raising `RATE_LIMIT_MAX`: `services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method: \"PUT\", pathPrefix: \"/uploads\", profile: { name: \"uploads\", limit: 3000 } })` (`RATE_LIMIT_ROUTES` from `@podosoft/podokit-runtime`). Register from a module's `plugin` factory or `configureServices()` in `app.extensions.ts`; the most specific prefix wins (more segments, then a literal segment over a `:name` parameter), and `profile: \"exempt\"` skips limiting.\n- Prefixes are API paths (`/uploads`, not the web proxy's `/api/uploads`); Better Auth routes keep `/api/auth`. A `:name` segment matches one path segment, as in `/hosts/:hostId/file-transfers`.\n"
     }
   ],
   "instructions": [
     "Configure the selected cache provider before enabling request limits.",
     "Tune the general, authentication, and runtime limits in .env.",
     "Give each deployment that shares Redis a distinct RATE_LIMIT_KEY_PREFIX.",
-    "Set RATE_LIMIT_TRUSTED_PROXY_HOPS to the exact number of trusted reverse proxies; keep 0 for direct API access.",
-    "Validated X-API-Key clients and signed-in sessions receive independent opaque counters; other traffic uses the trusted client address.",
-    "Sessions are recognized by verifying the Better Auth cookie or bearer signature with BETTER_AUTH_SECRET, without a database read, so limits apply per session rather than per user.",
+    "Requests without a validated API key or session count by the client address the API resolves from TRUSTED_PROXY_HOPS and TRUSTED_PROXY_HEADER, which audit entries and Better Auth sessions use too.",
+    "Validated X-API-Key clients and signed-in users receive independent opaque counters; other traffic uses the resolved client address.",
+    "Sessions are recognized by verifying the Better Auth cookie or bearer signature with BETTER_AUTH_SECRET, without a database read, and count under their user once the API has resolved them for a request, so limits apply per user.",
     "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Cache failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
     "Register a RateLimitIdentityExtension under RATE_LIMIT_IDENTITY_EXTENSION in app.extensions.ts for another validated machine-key source.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",
-    "Give a route its own budget or exempt it with services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method, pathPrefix, profile }) from a module's plugin factory or configureServices() in app.extensions.ts; the most specific prefix wins.",
+    "Give a route its own budget or exempt it with services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method, pathPrefix, profile }) from a module's plugin factory or configureServices() in app.extensions.ts; a :name segment matches one path segment, and the most specific prefix wins.",
     "Redis counters are shared across replicas; memory counters require one API replica."
   ]
 }

package/dist/templates/todo/AGENTS.md

@@ -10,8 +10,9 @@ A Bun 1.4 full-stack TypeScript monorepo ({{packageManager}} workspaces):
 
 - `apps/api` — **Elysia** backend (`{{projectName}}-api`), Bun.SQL + `{{databaseProvider}}`, merged OpenAPI at `/api-docs`.
 - `apps/web` — **SvelteKit** frontend (`{{projectName}}-web`), Tailwind v4 + shadcn-svelte + typesafe-i18n.
-- `infra/` — Docker Compose references for external services and example k3s manifests.
-- `.podokit/` — generation metadata plus application-owned development and deployment profiles.
+- `infra/` — provider-aware Docker Compose and example k3s manifests.
+- `.podokit/` — PodoKit generation metadata plus application-owned development and
+  deployment profiles (see "PodoKit tooling" below).
 - **Todo example**: `apps/api/src/todos/` (Elysia plugin, Bun.SQL repository, and migration) and the todo UI in `apps/web/src/routes/` show the end-to-end patterns to follow.
 
 ## Setup & commands
@@ -49,7 +50,32 @@ Merge added module settings from `.env.example` into an existing `.env`.
   managed lists. Cap a route's request body in the app-owned
   `apps/web/src/lib/server/body-limits.ts` (`APP_BODY_LIMITS`, 413
   `PAYLOAD_TOO_LARGE`). `BODY_SIZE_LIMIT` is the ceiling for every web route, so
-  uploads larger than it must use a direct API path (`apiPaths`) instead.
+  uploads larger than it must use a direct API path (`apiPaths`) instead. Give a
+  route a longer, shorter, or no response deadline in the app-owned
+  `apps/web/src/lib/server/proxy-timeouts.ts` (`APP_PROXY_TIMEOUTS`, `null` for
+  none); never edit the managed deadline. Both lists take path prefixes with
+  `:name` parameters, such as `/api/hosts/:hostId/file-transfers`, and the most
+  specific prefix wins.
+- Server-side API calls (`serverApiClient`) give up after `BACKEND_TIMEOUT_MS`
+  (2000), and the proxy answers 504 `BACKEND_TIMEOUT` when the API sends no
+  response headers within `BACKEND_PROXY_TIMEOUT_MS` (30000). Once the API's
+  `GET /health` stops answering too, calls throw `BackendUnavailableError` and the
+  proxy answers 503 `BACKEND_UNAVAILABLE` at once until it answers again. Handle
+  any non-`ApiError` failure in a load function as a temporary outage. The API
+  (`API_IDLE_TIMEOUT`) and the built web server (`CONNECTION_IDLE_TIMEOUT`) close
+  a connection that sends nothing for that many seconds (35 each): raise both
+  with any longer `BACKEND_PROXY_TIMEOUT_MS` or `APP_PROXY_TIMEOUTS` entry, more
+  than 4 above it, or set `0` when a route has no deadline. The proxy refuses to
+  load when `CONNECTION_IDLE_TIMEOUT` cannot cover a deadline.
+- Read a caller's address in the API with `clientAddressOf(request.headers)` from
+  `apps/api/src/core/client-address.ts`, never from `X-Forwarded-For` directly. The
+  API resolves it once per request from `TRUSTED_PROXY_HOPS` (1: the web proxy) and
+  `TRUSTED_PROXY_HEADER`; Better Auth sessions, audit entries, and rate limits use
+  the same address.
+- `GET /healthz` (`apps/web/src/routes/healthz/+server.ts`) is the web server's own
+  health route for the Kubernetes probes, the Compose healthcheck, and the image
+  `HEALTHCHECK`. Keep it free of API calls, so an API outage does not take the web
+  out of service.
 - When the root layout or a server hook fails, such as with 503 while the API is
   down, SvelteKit serves the app-owned `apps/web/src/error.html`. It is plain HTML
   with inline styles: no components, app CSS, scripts, or assets, and only the
@@ -96,15 +122,25 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations. Set Bun server options (`maxRequestBodySize`, `idleTimeout`) with its `apiServerOptions` export rather than editing `main.ts`; `API_MAX_REQUEST_BODY_SIZE` and `API_IDLE_TIMEOUT` apply when the export leaves them out.
 - **assembled** (e.g. `apps/api/src/app.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 
 Useful commands:
 
-- `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, storage, events, and jobs; set previews by default.
+- `podo dev watch|up|ps|logs|exec|down` — run container development through the
+  shared loopback gateway. `.podokit/dev.json` owns the local/public hosts and the
+  exact API WebSocket allowlist; never use a prefix or wildcard for that allowlist.
+  `podo dev up` rebuilds the images from the current source so a recreated
+  container never runs code older than the files Compose Watch synced.
+  `podo dev down` also stops this project's running `podo dev watch`; do not
+  kill Compose processes by hand.
+  The containers read the untracked `.env.docker`; `podo dev` creates it from the
+  committed `.env.docker.example` with generated secrets when it is missing. Never
+  commit `.env.docker` or put secrets in the example.
 - `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
+- `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, object storage, events, and jobs. Set is dry-run by default and never migrates or deletes provider data. Local providers require one API process.
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
 - `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist, and API routes that take bodies above the web server's `BODY_SIZE_LIMIT` (file uploads) in `exposure.apiPaths` (and `.podokit/dev.json` `apiPaths` for `podo dev`; `podo add` and `podo deploy init` fill in the paths modules declare), which reach the API without the web proxy, so the API must check their size, session, and `Origin` itself; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.

package/dist/templates/todo/README.md

@@ -131,7 +131,7 @@ Run each service in a separate terminal from the project root:
 ```
 
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
-- Web: http://localhost:5001
+- Web: http://localhost:5001 — its own health at `/healthz`, which never calls the API
 
 For multi-project routing, container profiles, and OAuth over a stable HTTPS
 tunnel, see the PodoKit [development guide](https://github.com/podosoft-dev/podokit/blob/main/docs/development.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,7 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@podosoft/podokit-runtime": "^0.4.0",
+    "@podosoft/podokit-runtime": "^0.4.1",
     "@podosoft/podokit-template-engine": "^0.4.2"
   }
 }