@podosoft/podokit 1.0.1 → 1.1.2

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -3,7 +3,7 @@ import { expect, test } from "@playwright/test";
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
 
-async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]): Promise<import("@playwright/test").APIRequestContext> {
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const email = `storage-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
   await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "S" } }).catch(() => undefined);
@@ -12,17 +12,25 @@ async function session(playwright: import("@playwright/test").PlaywrightWorkerAr
 
 test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
   const ctx = await session(playwright);
-  const key = `obj-${Date.now()}`;
-  const put = await ctx.put(`/api/storage/${key}`, { data: { content: "hello world" } });
-  test.skip(put.status() >= 500, "object storage (MinIO/S3) not reachable");
-  expect(put.ok()).toBeTruthy();
-  expect(await put.json()).toMatchObject({ key });
+  const key = `obj-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  try {
+    const put = await ctx.put(`/api/storage/${key}`, { data: { content: "hello world" } });
+    test.skip(!process.env.S3_ENDPOINT && put.status() >= 500, "optional S3-compatible service not configured");
+    expect(put.ok()).toBeTruthy();
+    expect(await put.json()).toMatchObject({ key });
 
-  const got = await (await ctx.get(`/api/storage/${key}`)).json();
-  expect(got).toMatchObject({ key, content: "hello world" });
+    const read = await ctx.get(`/api/storage/${key}`);
+    expect(read.ok()).toBeTruthy();
+    expect(await read.json()).toMatchObject({ key, content: "hello world" });
 
-  const pre = await (await ctx.get(`/api/storage/${key}/presigned`)).json();
-  expect(String(pre.url)).toContain(key);
-
-  await ctx.dispose();
+    const presigned = await ctx.get(`/api/storage/${key}/presigned`);
+    expect(presigned.ok()).toBeTruthy();
+    const pre = await presigned.json() as { url: string };
+    expect(new URL(pre.url).pathname).toContain(key);
+    const download = await ctx.get(pre.url);
+    expect(download.ok()).toBeTruthy();
+    expect(await download.text()).toBe("hello world");
+  } finally {
+    await ctx.dispose();
+  }
 });

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

@@ -1,7 +1,9 @@
 {
+  "manifestVersion": 3,
   "name": "object-storage-s3",
-  "description": "Bun-native S3-compatible object storage for AWS S3 or MinIO with a StorageService and presigned URLs.",
+  "description": "Bun-native S3-compatible object storage for AWS S3 or MinIO-compatible services with a StorageService and presigned URLs.",
   "requires": [],
+  "provides": { "object-storage": "s3" },
   "requiredProjectFiles": [
     "apps/api/src/health/readiness.service.ts"
   ],
@@ -21,7 +23,7 @@
     { "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",
+    "Start Silo for local dev:  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
     "Store an object:  curl -XPUT localhost:5002/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
     "Read it back:     curl localhost:5002/storage/hello",
     "Presigned URL:    curl localhost:5002/storage/hello/presigned",

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

@@ -1,7 +1,8 @@
 import { describe, expect, mock, test } from "bun:test";
 import type { RequestGuardContext } from "../core/services";
 import type { RateLimitIdentity } from "./rate-limit.identity";
-import { RateLimiter, type RateLimitStorage } from "./rate-limit.module";
+import { CacheRateLimitStorage, RateLimiter, type RateLimitStorage } from "./rate-limit.module";
+import { MemoryCacheStore } from "@podosoft/podokit-runtime";
 
 const config = {
   keyPrefix: "podokit:test:rate-limit",
@@ -32,6 +33,15 @@ function context(path: string, method = "GET"): {
 }
 
 describe("RateLimiter", () => {
+  test("uses the selected cache fixed-window primitive", async () => {
+    let now = 1_000;
+    const storage = new CacheRateLimitStorage(new MemoryCacheStore({ now: () => now }));
+    expect(await storage.increment("user", 60)).toMatchObject({ count: 1 });
+    expect(await storage.increment("user", 60)).toMatchObject({ count: 2 });
+    now += 60_000;
+    expect(await storage.increment("user", 60)).toMatchObject({ count: 1 });
+  });
+
   test("applies general, authentication, and runtime profiles", async () => {
     const increment = mock(async (_key: string, _ttlSeconds: number) => ({
       count: 1,
@@ -44,17 +54,20 @@ describe("RateLimiter", () => {
     );
     await limiter.enforce(context("/ordinary").value);
     await limiter.enforce(context("/api/auth/sign-in", "POST").value);
+    await limiter.enforce(context("/api/auth/get-session").value);
     await limiter.enforce(context("/site/settings").value);
 
     expect(increment.mock.calls.map((call) => call.slice(1))).toEqual([
       [60],
       [60],
       [60],
+      [60],
     ]);
     expect(increment.mock.calls.map((call) => call[0])).toEqual([
       "podokit:test:rate-limit:general:user:test",
       "podokit:test:rate-limit:auth:user:test",
       "podokit:test:rate-limit:runtime:user:test",
+      "podokit:test:rate-limit:runtime:user:test",
     ]);
   });
 

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

@@ -1,4 +1,4 @@
-import type { RedisClient } from "bun";
+import { CACHE, type CacheStore } from "@podosoft/podokit-runtime";
 import { AppException } from "../common/app-exception";
 import { API_KEY_VERIFIER } from "../api-key/api-key.module";
 import {
@@ -7,7 +7,6 @@ import {
   type RequestGuardContext,
   type ServiceKey,
 } from "../core/services";
-import { REDIS } from "../redis/redis.module";
 import { rateLimitConfig, type RateLimitConfig } from "./rate-limit.config";
 import { RateLimitIdentity } from "./rate-limit.identity";
 
@@ -20,39 +19,18 @@ export interface RateLimitStorage {
   increment(key: string, ttlSeconds: number): Promise<RateLimitIncrement>;
 }
 
-const INCREMENT_SCRIPT = `
-local count = redis.call('INCR', KEYS[1])
-if count == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
-local ttl = redis.call('TTL', KEYS[1])
-return { count, ttl }
-`;
-
-function resultNumber(value: unknown): number | undefined {
-  if (typeof value === "number") return value;
-  if (typeof value === "string") {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
-  }
-  return undefined;
-}
-
-export class RedisRateLimitStorage implements RateLimitStorage {
-  constructor(private readonly client: RedisClient) {}
+export class CacheRateLimitStorage implements RateLimitStorage {
+  constructor(private readonly cache: CacheStore) {}
 
   async increment(key: string, ttlSeconds: number): Promise<RateLimitIncrement> {
-    const result = await this.client.send("EVAL", [
-      INCREMENT_SCRIPT,
-      "1",
-      key,
-      String(ttlSeconds),
-    ]);
-    if (!Array.isArray(result)) throw new Error("Redis returned an invalid rate-limit result");
-    const count = resultNumber(result[0]);
-    const retryAfterSeconds = resultNumber(result[1]);
-    if (count === undefined || retryAfterSeconds === undefined) {
-      throw new Error("Redis returned an invalid rate-limit counter");
-    }
-    return { count, retryAfterSeconds: Math.max(1, retryAfterSeconds) };
+    const result = await this.cache.incrementFixedWindow(key, {
+      windowMs: ttlSeconds * 1_000,
+      limit: Number.MAX_SAFE_INTEGER,
+    });
+    return {
+      count: result.count,
+      retryAfterSeconds: Math.max(1, Math.ceil((result.resetAt - Date.now()) / 1_000)),
+    };
   }
 }
 
@@ -117,12 +95,15 @@ 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 };
+    }
     if (path === "/api/auth" || path.startsWith("/api/auth/")) {
       return { name: "auth", ttlSeconds: this.config.authTtlSeconds, limit: this.config.authLimit };
     }
-    if (method === "GET" && path === "/site/settings") {
-      return { name: "runtime", ttlSeconds: this.config.ttlSeconds, limit: this.config.runtimeLimit };
-    }
     return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
   }
 
@@ -152,7 +133,7 @@ export const rateLimitModule: PodokitModule = {
     const limiter = new RateLimiter(
       rateLimitConfig(),
       new RateLimitIdentity(services.resolve(API_KEY_VERIFIER), services),
-      new RedisRateLimitStorage(services.resolve(REDIS).client),
+      new CacheRateLimitStorage(services.resolve(CACHE)),
     );
     services.register(RATE_LIMITER, limiter);
     services.resolve(REQUEST_GUARDS).register((context) => limiter.enforce(context));

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

@@ -12,6 +12,7 @@ const origin = { origin: base };
 // value so the window is crossed in a handful of requests); otherwise fall back
 // to the module default and allow a little headroom.
 const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
+const authLimit = Number(process.env.RATE_LIMIT_AUTH_MAX ?? 20);
 
 async function session(
   playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
@@ -63,3 +64,14 @@ test("rate limit: health probes stay available while ordinary routes return 429
   });
   await ctx.dispose();
 });
+
+test("rate limit: session reads do not consume the strict authentication budget", async ({
+  playwright,
+}) => {
+  const ctx = await session(playwright);
+  for (let i = 0; i < authLimit + 5; i++) {
+    const response = await ctx.get("/api/auth/get-session");
+    expect(response.status(), `session request ${i + 1}`).toBe(200);
+  }
+  await ctx.dispose();
+});

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

@@ -1,7 +1,9 @@
 {
   "name": "rate-limit",
-  "description": "Distributed Elysia request limiting by authenticated user, validated API key, or trusted-proxy client address. Uses Bun Redis across replicas and returns stable 429/503 errors.",
-  "requires": ["redis", "api-key-auth"],
+  "manifestVersion": 3,
+  "description": "Provider-neutral Elysia request limiting by authenticated user, validated API key, or trusted-proxy client address.",
+  "requires": ["api-key-auth"],
+  "requiresCapabilities": ["cache"],
   "targetApp": "api",
   "managedGlobs": [
     "apps/api/src/rate-limit/**",
@@ -15,7 +17,7 @@
     "# stricter authentication endpoint ceiling",
     "RATE_LIMIT_AUTH_TTL=60",
     "RATE_LIMIT_AUTH_MAX=20",
-    "# higher ceiling for SSR runtime settings reads",
+    "# 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",
@@ -36,14 +38,14 @@
     }
   ],
   "instructions": [
-    "Ensure Redis is running: docker compose -f infra/docker/docker-compose.yml up -d",
+    "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.",
     "Authenticated users and validated X-API-Key clients receive independent opaque counters; other traffic uses the trusted client address.",
-    "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Redis failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
+    "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.",
-    "The atomic counter is shared across API replicas in Redis."
+    "Redis counters are shared across replicas; memory counters require one API replica."
   ]
 }

package/dist/templates/modules/redis/files/apps/api/src/redis/redis-cache.store.ts

@@ -0,0 +1,82 @@
+import type { RedisClient } from "bun";
+import type {
+  CacheSetOptions,
+  CacheStore,
+  FixedWindowOptions,
+  FixedWindowResult,
+} from "@podosoft/podokit-runtime";
+import type { RedisService } from "./redis.service";
+
+const FIXED_WINDOW_SCRIPT = `
+local count = redis.call('INCR', KEYS[1])
+if count == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local ttl = redis.call('PTTL', KEYS[1])
+return { count, ttl }
+`;
+
+function resultNumber(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+export class RedisCacheStore implements CacheStore {
+  private readonly client: RedisClient;
+
+  constructor(private readonly redis: RedisService) {
+    this.client = redis.client;
+  }
+
+  get(key: string): Promise<string | null> {
+    return this.redis.get(key);
+  }
+
+  async set(key: string, value: string, options: CacheSetOptions = {}): Promise<void> {
+    await this.client.set(key, value);
+    if (options.ttlMs !== undefined) {
+      if (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 1) {
+        throw new Error("ttlMs must be a positive integer");
+      }
+      await this.client.send("PEXPIRE", [key, String(options.ttlMs)]);
+    }
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return (await this.redis.del(key)) > 0;
+  }
+
+  async incrementFixedWindow(
+    key: string,
+    options: FixedWindowOptions,
+  ): Promise<FixedWindowResult> {
+    if (!Number.isSafeInteger(options.windowMs) || options.windowMs < 1) {
+      throw new Error("windowMs must be a positive integer");
+    }
+    if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+      throw new Error("limit must be a positive integer");
+    }
+    const result = await this.client.send("EVAL", [
+      FIXED_WINDOW_SCRIPT,
+      "1",
+      key,
+      String(options.windowMs),
+    ]);
+    if (!Array.isArray(result)) throw new Error("Redis returned an invalid cache counter");
+    const count = resultNumber(result[0]);
+    const ttlMs = resultNumber(result[1]);
+    if (count === undefined || ttlMs === undefined) {
+      throw new Error("Redis returned an invalid cache counter");
+    }
+    return {
+      allowed: count <= options.limit,
+      count,
+      remaining: Math.max(0, options.limit - count),
+      resetAt: Date.now() + Math.max(1, ttlMs),
+    };
+  }
+
+  close(): void {}
+}

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

@@ -1,4 +1,6 @@
 import { Elysia, t } from "elysia";
+import { CACHE } from "@podosoft/podokit-runtime";
+import { PROVIDERS } from "../config/providers";
 import {
   type AppPlugin,
   type PodokitModule,
@@ -6,10 +8,12 @@ import {
   type ServiceKey,
 } from "../core/services";
 import { RedisService } from "./redis.service";
+import { RedisCacheStore } from "./redis-cache.store";
 
 export const REDIS = Symbol("redis") as ServiceKey<RedisService>;
 
 const cachePlugin: AppPlugin = ({ services }) => {
+  if (PROVIDERS.cache !== "redis") return new Elysia({ name: "podokit.redis.inactive" });
   const redis = services.resolve(REDIS);
   return new Elysia({ name: "podokit.redis" })
     .put("/cache/:key", async ({ params, body }) => {
@@ -35,8 +39,10 @@ const cachePlugin: AppPlugin = ({ services }) => {
 export const redisModule: PodokitModule = {
   name: "redis",
   configure: (_env, services): void => {
+    if (PROVIDERS.cache !== "redis") return;
     const redis = new RedisService(services.resolve(READINESS));
     services.register(REDIS, redis, () => redis.close());
+    services.register(CACHE, new RedisCacheStore(redis));
     services.onStart(() => redis.connect());
   },
   plugin: cachePlugin,

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

@@ -1,7 +1,9 @@
 {
+  "manifestVersion": 3,
   "name": "redis",
   "description": "Bun native Redis client with get/set/del and publish/subscribe, plus demo cache endpoints.",
   "requires": [],
+  "provides": { "cache": "redis" },
   "requiredProjectFiles": [
     "apps/api/src/config/redis.connection.ts",
     "apps/api/src/health/readiness.service.ts"

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

@@ -1,18 +1,17 @@
 import { AppException } from "@podosoft/podokit-contracts";
+import { EVENTS } from "@podosoft/podokit-runtime";
 import { Elysia, sse, t } from "elysia";
 import {
   type AppPlugin,
   type PodokitModule,
   READINESS,
-  type ServiceKey,
 } from "../core/services";
 import { EventsService } from "./events.service";
-import { createEventsTransport } from "./events.transport";
 
-export const EVENTS = Symbol("events") as ServiceKey<EventsService>;
+export const SSE_EVENTS = Symbol("sse-events") as import("../core/services").ServiceKey<EventsService>;
 
 const eventsPlugin: AppPlugin = ({ services }) => {
-  const events = services.resolve(EVENTS);
+  const events = services.resolve(SSE_EVENTS);
   return new Elysia({ name: "podokit.events" })
     .get("/events/stream", async function* ({ request }) {
       for await (const data of events.stream(request.signal)) yield sse({ data });
@@ -40,8 +39,8 @@ const eventsPlugin: AppPlugin = ({ services }) => {
 export const eventsModule: PodokitModule = {
   name: "sse",
   configure: (_env, services): void => {
-    const events = new EventsService(createEventsTransport(), services.resolve(READINESS));
-    services.register(EVENTS, events, () => events.close());
+    const events = new EventsService(services.resolve(EVENTS), services.resolve(READINESS));
+    services.register(SSE_EVENTS, events, () => events.close());
     services.onStart(() => events.connect());
   },
   plugin: eventsPlugin,

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.spec.ts

@@ -1,12 +1,12 @@
 import { describe, expect, it } from "bun:test";
 import { ReadinessService } from "../health/readiness.service";
+import { MemoryEventBus } from "@podosoft/podokit-runtime";
 import { EventsService } from "./events.service";
-import { MemoryEventsTransport } from "./events.transport";
 
 describe("EventsService", () => {
   it("publishes through the transport and delivers locally", async () => {
     const readiness = new ReadinessService();
-    const service = new EventsService(new MemoryEventsTransport(), readiness);
+    const service = new EventsService(new MemoryEventBus(), readiness);
     const received: unknown[] = [];
     service.subscribe((data) => received.push(data));
     await service.connect();
@@ -18,12 +18,12 @@ describe("EventsService", () => {
 
   it("rejects events larger than the configured limit", async () => {
     const service = new EventsService(
-      new MemoryEventsTransport({ SSE_MAX_EVENT_BYTES: "8" }),
+      new MemoryEventBus({ maxEventBytes: 8 }),
       new ReadinessService(),
     );
     await service.connect();
     await expect(service.publishAsync({ message: "too large" })).rejects.toThrow(
-      "Event data exceeds SSE_MAX_EVENT_BYTES",
+      "Event exceeds maxEventBytes",
     );
     await service.close();
   });

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.ts

@@ -1,19 +1,20 @@
 import { ReadinessService } from "../health/readiness.service";
-import type { EventsTransport } from "./events.transport";
+import type { EventBus, Unsubscribe } from "@podosoft/podokit-runtime";
 
 type LocalHandler = (data: unknown) => void;
 
 export class EventsService {
   private readonly handlers = new Set<LocalHandler>();
   private unregisterReadiness?: () => void;
+  private unsubscribe?: Unsubscribe;
 
   constructor(
-    private readonly transport: EventsTransport,
+    private readonly transport: EventBus,
     private readonly readiness: ReadinessService,
   ) {}
 
   async connect(): Promise<void> {
-    await this.transport.connect((data) => this.publishLocal(data));
+    this.unsubscribe = await this.transport.subscribe("sse", (data) => this.publishLocal(data));
     this.unregisterReadiness = this.readiness.register("events", () => this.transport.ready());
   }
 
@@ -25,7 +26,7 @@ export class EventsService {
   }
 
   publishAsync(data: unknown): Promise<void> {
-    return this.transport.publish(data);
+    return this.transport.publish("sse", data);
   }
 
   publishLocal(data: unknown): void {
@@ -66,7 +67,7 @@ export class EventsService {
 
   async close(): Promise<void> {
     this.unregisterReadiness?.();
+    await this.unsubscribe?.();
     this.handlers.clear();
-    await this.transport.close();
   }
 }

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

@@ -1,16 +1,14 @@
 {
+  "manifestVersion": 3,
   "name": "sse",
   "description": "Server-Sent Events with memory or Redis transport for multi-replica delivery.",
-  "requires": [],
+  "requiresCapabilities": ["events"],
   "requiredProjectFiles": [
-    "apps/api/src/config/redis.connection.ts",
     "apps/api/src/health/readiness.service.ts"
   ],
   "targetApp": "api",
   "env": [
-    "# Server-Sent Events transport: memory for one API replica, redis for multiple replicas",
-    "SSE_TRANSPORT=memory",
-    "SSE_REDIS_CHANNEL=podokit:events",
+    "# Maximum encoded Server-Sent Event payload",
     "SSE_MAX_EVENT_BYTES=65536"
   ],
   "inject": [
@@ -20,7 +18,7 @@
   "instructions": [
     "Stream events:  curl -N localhost:5002/events/stream",
     "Publish a message (in another terminal):  curl -XPOST localhost:5002/events -H 'content-type: application/json' -d '{\"message\":\"hello\"}'",
-    "Set SSE_TRANSPORT=redis for delivery across API replicas; Redis uses the shared REDIS_URL or individual Redis settings.",
+    "Select events=redis for multiple replicas or events=memory for a single process.",
     "Inject EventsService and call publishAsync for confirmed delivery, publish for best-effort delivery, or publishLocal for events already fanned out to every replica."
   ]
 }

package/dist/templates/todo/AGENTS.md

@@ -73,7 +73,7 @@ Useful commands:
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `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. 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`.
+- `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; 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`.
 - `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions

package/dist/templates/todo/README.md

@@ -40,7 +40,7 @@ In a second terminal, apply the included Todo migration and use the lifecycle he
 ```
 
 `dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
-`storage`, and `queue` when installed modules require Redis, MinIO, or a worker.
+`storage`, and `queue` when installed modules require Redis, Silo, or a worker.
 `dev up` uses the same shared gateway and module profiles without keeping Compose
 Watch attached.
 You can still activate an additional Compose profile explicitly:
@@ -90,6 +90,11 @@ a sample Todo repository and initial migration are included.
 
 Docker Compose lives in `infra/docker`; the basic k3s manifests in `infra/k3s`
 route every public path through the web proxy. Use `podo deploy init`, `doctor`,
-and `plan` for an exact-image Helm release on an existing cluster. Applying or
-rolling back requires the exact confirmation hash from a fresh plan. See the
+and `plan` for an exact-image release on Kubernetes or one Docker host. Applying
+or rolling back requires the exact confirmation hash from a fresh plan. See the
 PodoKit [deployment guide](https://github.com/podosoft-dev/podokit/blob/main/docs/deployment.md).
+
+For a Docker Compose deployment with API WebSockets, list their exact paths under
+`exposure.webSocketPaths`. The driver keeps one published port, routes those paths
+to API, and sends every other request to web. If an external reverse proxy supplies
+forwarding headers, list only its direct CIDR blocks in `exposure.trustedProxyCidrs`.

package/dist/toolchain.d.ts

@@ -11,3 +11,4 @@ export declare function resolveToolchain(runtime?: string, packageManager?: stri
 export declare function toolchainTemplateVars(toolchain: Toolchain): TemplateVars;
 export declare function isRuntime(value: string): value is Runtime;
 export declare function toolchainMigrationCommand(_toolchain: Toolchain): string[];
+export declare function toolchainWorkerCommand(_toolchain: Toolchain): string[];

package/dist/toolchain.js

@@ -5,6 +5,7 @@ exports.resolveToolchain = resolveToolchain;
 exports.toolchainTemplateVars = toolchainTemplateVars;
 exports.isRuntime = isRuntime;
 exports.toolchainMigrationCommand = toolchainMigrationCommand;
+exports.toolchainWorkerCommand = toolchainWorkerCommand;
 exports.BUN_VERSION = "1.4.0";
 function resolveToolchain(runtime = "bun", packageManager) {
     if (runtime !== "bun") {
@@ -42,3 +43,6 @@ function isRuntime(value) {
 function toolchainMigrationCommand(_toolchain) {
     return ["bun", "run", "migrate:all"];
 }
+function toolchainWorkerCommand(_toolchain) {
+    return ["bun", "dist/main-worker.js"];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "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,6 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@podosoft/podokit-runtime": "^0.2.0",
     "@podosoft/podokit-template-engine": "^0.4.2"
   }
 }

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

@@ -1,32 +0,0 @@
-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.
-export class ProgressBridge {
-  private unsubscribe?: () => Promise<void>;
-
-  constructor(
-    private readonly redis: RedisService,
-    private readonly events: EventsService,
-  ) {}
-
-  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)) {
-          process.stderr.write("Discard invalid job progress event\n");
-          return;
-        }
-        this.events.publishLocal({ type: "job-progress", ...parsed });
-      } catch {
-        process.stderr.write("Discard malformed job progress event\n");
-      }
-    });
-  }
-
-  async close(): Promise<void> {
-    await this.unsubscribe?.();
-  }
-}

package/dist/templates/modules/mailer/files/apps/api/src/mail/db.ts

@@ -1,13 +0,0 @@
-import { Pool } from "pg";
-
-// The mailer's own pg pool, in its own module so the mailer stays independent of
-// any other module. Used only to read the optional admin-configured SMTP settings
-// from `auth_config` when the auth module is present; with no such table the read
-// fails softly and the mailer falls back to SMTP_* env (see mailer.ts).
-export const pool = new Pool({
-  host: process.env.POSTGRES_HOST ?? "localhost",
-  port: Number(process.env.POSTGRES_PORT ?? 5432),
-  user: process.env.POSTGRES_USER ?? "podokit",
-  password: process.env.POSTGRES_PASSWORD ?? "podokit",
-  database: process.env.POSTGRES_DB ?? "podokit",
-});