@podosoft/podokit 1.4.2 → 1.6.0

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.ts

@@ -1,5 +1,6 @@
 import { APP_BODY_LIMITS } from "./body-limits";
 import { APP_FORWARDED_REQUEST_HEADERS, APP_RELAYED_RESPONSE_HEADERS } from "./proxy-headers";
+import { APP_PROXY_TIMEOUTS } from "./proxy-timeouts";
 
 // Server-side proxy boundary. The browser never talks to the API directly:
 // requests go through SvelteKit server routes, which forward an allowlist of
@@ -118,46 +119,115 @@ export interface BodyLimit {
   maxBytes: number;
 }
 
-const BODY_LIMIT_PREFIX = /^\/api(?:\/[A-Za-z0-9._~!$&'()+,;=:@-]+)*\/?$/;
+/** A literal path segment, or null for a `:name` parameter. */
+type PathSegment = string | null;
 
-/** Validate application body limits and order them so the longest prefix
- *  matches first. Prefixes are stored without a trailing slash. */
-export function sortedBodyLimits(limits: ReadonlyArray<BodyLimit>): BodyLimit[] {
-  const seen = new Set<string>();
-  const sorted = limits.map(({ pathPrefix, maxBytes }) => {
-    if (
-      !BODY_LIMIT_PREFIX.test(pathPrefix) ||
-      pathPrefix.split("/").some((segment) => segment === "." || segment === "..")
-    ) {
+/** An application path rule with its prefix split into segments. */
+export type PathRule<T extends { pathPrefix: string }> = T & { readonly segments: readonly PathSegment[] };
+
+const LITERAL_SEGMENT = /^[A-Za-z0-9._~!$&'()+,;=:@-]+$/;
+const PARAMETER_SEGMENT = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The segments of a prefix under /api/, or undefined when it is not one. */
+function parsePathPrefix(pathPrefix: string): PathSegment[] | undefined {
+  const base = pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix;
+  const [root, ...segments] = base.split("/");
+  if (root !== "" || segments[0] !== "api") return undefined;
+  const parsed: PathSegment[] = [];
+  for (const segment of segments) {
+    if (PARAMETER_SEGMENT.test(segment)) {
+      parsed.push(null);
+    } else if (LITERAL_SEGMENT.test(segment) && !segment.startsWith(":") && segment !== "." && segment !== "..") {
+      parsed.push(segment);
+    } else {
+      return undefined;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Below zero when `a` is more specific: more segments, then, from the left, a
+ * literal segment before a parameter.
+ */
+function compareSpecificity(a: readonly PathSegment[], b: readonly PathSegment[]): number {
+  if (a.length !== b.length) return b.length - a.length;
+  for (let index = 0; index < a.length; index += 1) {
+    const literal = a[index] !== null;
+    if (literal !== (b[index] !== null)) return literal ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Validate an application list of /api path prefixes and order it so the
+ *  most specific prefix matches first. Prefixes are stored without a trailing
+ *  slash. */
+function sortedByPrefix<T extends { pathPrefix: string }>(
+  entries: ReadonlyArray<T>,
+  listName: string,
+  example: string,
+  check: (entry: T) => void,
+): PathRule<T>[] {
+  const seen = new Map<string, string>();
+  const rules = entries.map((entry) => {
+    const { pathPrefix } = entry;
+    const segments = parsePathPrefix(pathPrefix);
+    if (!segments) {
       throw new Error(
-        `APP_BODY_LIMITS pathPrefix must be a static path under /api/, such as "/api/feedback/": ${JSON.stringify(pathPrefix)}`,
+        `${listName} pathPrefix must be a path under /api/ made of literal segments and ":name" parameters, ` +
+          `such as "${example}": ${JSON.stringify(pathPrefix)}`,
       );
     }
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
-      throw new Error(`APP_BODY_LIMITS maxBytes for ${pathPrefix} must be a positive whole number of bytes.`);
+    check(entry);
+    // Parameter names do not change which paths a prefix covers.
+    const key = segments.map((segment) => segment ?? ":").join("/");
+    const listed = seen.get(key);
+    if (listed !== undefined) {
+      throw new Error(
+        `${listName} lists the same paths twice: ${JSON.stringify(listed)} and ${JSON.stringify(pathPrefix)}.`,
+      );
     }
-    const base = pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix;
-    if (seen.has(base)) throw new Error(`APP_BODY_LIMITS lists ${pathPrefix} more than once.`);
-    seen.add(base);
-    return { pathPrefix: base, maxBytes };
+    seen.set(key, pathPrefix);
+    return { ...entry, pathPrefix: pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix, segments };
   });
-  return sorted.sort((left, right) => right.pathPrefix.length - left.pathPrefix.length);
+  return rules.sort((left, right) => compareSpecificity(left.segments, right.segments));
 }
 
-const bodyLimits = sortedBodyLimits(APP_BODY_LIMITS);
-
-/** The body limit for a request path, matched on the decoded path so an encoded
- *  segment cannot step around a prefix. */
-export function bodyLimitFor(pathname: string, limits: readonly BodyLimit[] = bodyLimits): number | undefined {
+/** The most specific rule for a request path. Prefixes match whole segments of
+ *  the decoded path, so an encoded segment cannot step around them, and a
+ *  parameter matches exactly one non-empty segment. */
+function entryFor<T extends { pathPrefix: string }>(
+  pathname: string,
+  rules: readonly PathRule<T>[],
+): PathRule<T> | undefined {
   let path = pathname;
   try {
     path = decodeURIComponent(pathname);
   } catch {
     // Keep the raw path when it holds a malformed escape.
   }
-  return limits.find(
-    ({ pathPrefix }) => path === pathPrefix || path.startsWith(`${pathPrefix}/`),
-  )?.maxBytes;
+  const segments = path.split("/").slice(1);
+  return rules.find(
+    (rule) =>
+      rule.segments.length <= segments.length &&
+      rule.segments.every((segment, index) =>
+        segment === null ? segments[index] !== "" : segment === segments[index],
+      ),
+  );
+}
+
+export function sortedBodyLimits(limits: ReadonlyArray<BodyLimit>): PathRule<BodyLimit>[] {
+  return sortedByPrefix(limits, "APP_BODY_LIMITS", "/api/feedback/", ({ pathPrefix, maxBytes }) => {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+      throw new Error(`APP_BODY_LIMITS maxBytes for ${pathPrefix} must be a positive whole number of bytes.`);
+    }
+  });
+}
+
+const bodyLimits = sortedBodyLimits(APP_BODY_LIMITS);
+
+export function bodyLimitFor(pathname: string, limits: readonly PathRule<BodyLimit>[] = bodyLimits): number | undefined {
+  return entryFor(pathname, limits)?.maxBytes;
 }
 
 /** Read a request body, or return null as soon as it exceeds maxBytes. The rest
@@ -220,13 +290,15 @@ export function backendBaseUrl(): string {
 
 /**
  * Milliseconds one server-side API call may take, response body included, and
- * how long the proxy waits for response headers before it checks whether the
- * API still answers at all.
+ * how often the proxy checks whether the API still answers at all while it waits
+ * for response headers.
  */
 const DEFAULT_BACKEND_TIMEOUT_MS = 2_000;
 /**
- * Milliseconds the proxy waits for the API's response headers, matching the
- * API's default idle timeout. Streamed bodies are not cut off once they start.
+ * Milliseconds the proxy waits for the API's response headers, unless
+ * APP_PROXY_TIMEOUTS lists the path. The API's default idle timeout of 35
+ * seconds outlasts it.
+ * Streamed bodies are not cut off once they start.
  */
 const DEFAULT_BACKEND_PROXY_TIMEOUT_MS = 30_000;
 /** Seconds between checks while the API is unreachable, also sent as Retry-After. */
@@ -259,10 +331,101 @@ function backendProxyTimeoutMs(): number {
 backendTimeoutMs();
 backendProxyTimeoutMs();
 
+export interface ProxyTimeout {
+  pathPrefix: string;
+  /** Milliseconds to wait for response headers, or null for no deadline. */
+  timeoutMs: number | null;
+}
+
+export function sortedProxyTimeouts(timeouts: ReadonlyArray<ProxyTimeout>): PathRule<ProxyTimeout>[] {
+  return sortedByPrefix(timeouts, "APP_PROXY_TIMEOUTS", "/api/exports/", ({ pathPrefix, timeoutMs }) => {
+    if (timeoutMs !== null && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMER_MS)) {
+      throw new Error(
+        `APP_PROXY_TIMEOUTS timeoutMs for ${pathPrefix} must be null or a whole number of milliseconds from 1 to ${MAX_TIMER_MS}.`,
+      );
+    }
+  });
+}
+
+const proxyTimeouts = sortedProxyTimeouts(APP_PROXY_TIMEOUTS);
+
+/** How long the proxy waits for response headers on a request path, or null for no deadline. */
+export function proxyTimeoutFor(
+  pathname: string,
+  timeouts: readonly PathRule<ProxyTimeout>[] = proxyTimeouts,
+): number | null {
+  const entry = entryFor(pathname, timeouts);
+  return entry ? entry.timeoutMs : backendProxyTimeoutMs();
+}
+
+/**
+ * Bun's fetch fails a request whose connection sends nothing for its idle
+ * timeout, 300 seconds unless BUN_CONFIG_HTTP_IDLE_TIMEOUT sets another, even
+ * while the proxy still waits for response headers.
+ */
+const FETCH_IDLE_TIMEOUT_MS = 300_000;
+
+/**
+ * Bun's fetch options for a request that waits up to timeoutMs for response
+ * headers. A wait without a deadline, or one Bun's idle timeout would cut
+ * first, turns that timeout off, so only the deadline, the health checks, and
+ * the browser end it. Shorter waits keep Bun's default.
+ */
+export function upstreamFetchOptions(timeoutMs: number | null): { timeout?: false } {
+  return timeoutMs === null || timeoutMs >= FETCH_IDLE_TIMEOUT_MS ? { timeout: false } : {};
+}
+
+/** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
+const IDLE_TICK_SECONDS = 4;
+/** The longest idle timeout Bun accepts; 0 turns it off. */
+const MAX_IDLE_TIMEOUT_SECONDS = 255;
+
+/**
+ * Throw unless the web server keeps a silent connection open longer than the
+ * proxy waits for response headers. adapter-bun takes its idle timeout from
+ * CONNECTION_IDLE_TIMEOUT (Bun's 10 seconds when unset) and closes a connection
+ * that sends nothing for that long without a response, so neither the API's late
+ * answer nor the proxy's 504 would reach the browser.
+ */
+export function checkIdleTimeout(
+  idleTimeout: string | undefined,
+  defaultTimeoutMs: number,
+  timeouts: readonly ProxyTimeout[],
+): void {
+  // adapter-bun rejects a malformed value itself when it starts.
+  if (idleTimeout === undefined || !/^\d+$/.test(idleTimeout) || Number(idleTimeout) === 0) return;
+  let longest: { timeoutMs: number | null; source: string } = {
+    timeoutMs: defaultTimeoutMs,
+    source: "BACKEND_PROXY_TIMEOUT_MS",
+  };
+  for (const { pathPrefix, timeoutMs } of timeouts) {
+    if (longest.timeoutMs !== null && (timeoutMs === null || timeoutMs > longest.timeoutMs)) {
+      longest = { timeoutMs, source: `APP_PROXY_TIMEOUTS for ${pathPrefix}` };
+    }
+  }
+  const seconds = Number(idleTimeout);
+  if (longest.timeoutMs !== null && (seconds - IDLE_TICK_SECONDS) * 1000 > longest.timeoutMs) return;
+  const minimum =
+    longest.timeoutMs === null ? Infinity : Math.floor(longest.timeoutMs / 1000) + IDLE_TICK_SECONDS + 1;
+  const wait = longest.timeoutMs === null ? "no deadline" : `${longest.timeoutMs} ms`;
+  const fix =
+    minimum <= MAX_IDLE_TIMEOUT_SECONDS
+      ? `at least ${minimum}, or to 0 to turn the idle timeout off`
+      : `0 to turn the idle timeout off, since Bun allows at most ${MAX_IDLE_TIMEOUT_SECONDS} seconds`;
+  throw new Error(
+    `CONNECTION_IDLE_TIMEOUT=${seconds} lets the web server close a silent connection before the /api proxy ` +
+      `stops waiting for response headers (${wait}, ${longest.source}); Bun closes idle connections up to ` +
+      `${IDLE_TICK_SECONDS} seconds early. Set CONNECTION_IDLE_TIMEOUT to ${fix}.`,
+  );
+}
+
+checkIdleTimeout(process.env.CONNECTION_IDLE_TIMEOUT, backendProxyTimeoutMs(), proxyTimeouts);
+
 // The API counts as unreachable only when GET /health gets no HTTP answer
-// within BACKEND_TIMEOUT_MS. It is checked when a request gets no answer, or
-// when the proxy waits longer than that for response headers, so one slow
-// endpoint does not fail every request in the process. Once the API is found
+// within BACKEND_TIMEOUT_MS. It is checked when a request gets no answer, and
+// every BACKEND_TIMEOUT_MS while the proxy waits for response headers, so one
+// slow endpoint does not fail every request in the process, while an API that
+// stops answering still ends a long or unbounded wait. Once the API is found
 // unreachable, requests still waiting for it fail, new ones fail at once instead
 // of each waiting for a refused connection, a DNS lookup, or a hung server, and
 // a background check runs at most every BACKEND_RETRY_AFTER_SECONDS. Any HTTP
@@ -303,6 +466,11 @@ export function checkBackend(): Promise<void> {
   return pendingCheck;
 }
 
+/** Check the API unless a check is running or one ended within BACKEND_TIMEOUT_MS. */
+function recheckBackend(now = Date.now()): void {
+  if (!pendingCheck && now - lastCheckEnded >= backendTimeoutMs()) void checkBackend();
+}
+
 /** Record an HTTP answer from the API, whatever its status. */
 export function reportBackendAnswer(): void {
   answers += 1;
@@ -358,6 +526,40 @@ export function normalizeClientIp(address: string | undefined): string | undefin
   return address;
 }
 
+let publicOriginsSource: string | undefined;
+let publicOrigins: ReadonlySet<string> = new Set();
+
+/**
+ * The public web origins listed in CORS_ORIGIN. Wildcard patterns name no single
+ * origin and are skipped, as are entries that are not absolute URLs.
+ */
+export function configuredPublicOrigins(value = process.env.CORS_ORIGIN): ReadonlySet<string> {
+  if (value !== publicOriginsSource) {
+    publicOriginsSource = value;
+    publicOrigins = new Set(
+      (value ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => !entry.includes("*") && URL.canParse(entry))
+        .map((entry) => new URL(entry).origin),
+    );
+  }
+  return publicOrigins;
+}
+
+/**
+ * Tell the API which public origin a request came in on. SvelteKit resolves the
+ * request URL from the Host header, or from the gateway's forwarded headers that
+ * HOST_HEADER and PROTOCOL_HEADER name, so the value is sent only when that origin
+ * is listed in CORS_ORIGIN. The API can then build links for the origin a browser
+ * used without trusting a header a caller wrote.
+ */
+export function setForwardedOrigin(headers: Headers, url: URL): void {
+  if (!configuredPublicOrigins().has(url.origin)) return;
+  headers.set("x-forwarded-host", url.host);
+  headers.set("x-forwarded-proto", url.protocol.slice(0, -1));
+}
+
 export function resolveClientIp(getClientAddress: () => string): string | undefined {
   try {
     return normalizeClientIp(getClientAddress());
@@ -380,8 +582,10 @@ export async function proxyRequest(
   // Forward the resolved client IP so the API (better-auth) can record it.
   const forwardedIp = normalizeClientIp(clientAddress);
   if (forwardedIp) headers.set("x-forwarded-for", forwardedIp);
+  const requestUrl = new URL(request.url);
+  setForwardedOrigin(headers, requestUrl);
 
-  const { pathname } = new URL(request.url);
+  const { pathname } = requestUrl;
   if (!backendReachable()) {
     request.body?.cancel().catch(() => undefined);
     return backendFailure(pathname, 503);
@@ -400,15 +604,19 @@ export async function proxyRequest(
       body = limited;
     }
   }
-  // The deadline, the health check, and the outage signal cover only the wait
+  // The deadline, the health checks, and the outage signal cover only the wait
   // for response headers, so streamed bodies such as server-sent events are not
   // cut off.
   const waiting = new AbortController();
-  const deadline = setTimeout(
-    () => waiting.abort(new DOMException("The API did not respond in time", "TimeoutError")),
-    backendProxyTimeoutMs(),
-  );
-  const healthCheck = setTimeout(() => void checkBackend(), backendTimeoutMs());
+  const timeoutMs = proxyTimeoutFor(pathname);
+  const deadline =
+    timeoutMs === null
+      ? undefined
+      : setTimeout(
+          () => waiting.abort(new DOMException("The API did not respond in time", "TimeoutError")),
+          timeoutMs,
+        );
+  const healthChecks = setInterval(() => recheckBackend(), backendTimeoutMs());
   const outage = backendOutageSignal();
   const failOnOutage = (): void => waiting.abort(outage.reason);
   outage.addEventListener("abort", failOnOutage);
@@ -423,6 +631,7 @@ export async function proxyRequest(
       // closed EventSource or aborted request keeps its API socket open until Bun's
       // fetch pool is exhausted and the web process stops serving requests.
       signal: AbortSignal.any([request.signal, waiting.signal]),
+      ...upstreamFetchOptions(timeoutMs),
     });
   } catch (cause: unknown) {
     // Nobody waits for an answer to a request the browser abandoned.
@@ -432,7 +641,7 @@ export async function proxyRequest(
     return backendFailure(pathname, waiting.signal.aborted ? 504 : 503);
   } finally {
     clearTimeout(deadline);
-    clearTimeout(healthCheck);
+    clearInterval(healthChecks);
     outage.removeEventListener("abort", failOnOutage);
   }
   reportBackendAnswer();

package/dist/templates/fullstack/apps/web/src/lib/server/body-limits.ts

@@ -3,8 +3,11 @@
  * proxies to the API. An entry caps the body of every request whose path is
  * pathPrefix or below it, for example
  *   { pathPrefix: "/api/feedback/", maxBytes: 64 * 1024 }
- * and the longest matching prefix wins. Above the limit the proxy stops reading
- * and answers 413 PAYLOAD_TOO_LARGE without contacting the API.
+ *   { pathPrefix: "/api/hosts/:hostId/uploads", maxBytes: 1024 * 1024 }
+ * where a :name segment matches exactly one non-empty path segment. The most
+ * specific entry wins: more segments, then a literal segment over a parameter
+ * from the left. Above the limit the proxy stops reading and answers 413
+ * PAYLOAD_TOO_LARGE without contacting the API.
  *
  * BODY_SIZE_LIMIT remains the ceiling for every web route: Bun rejects a larger
  * body before this code runs, so a maxBytes above it has no effect. Routes that

package/dist/templates/fullstack/apps/web/src/lib/server/proxy-timeouts.ts

@@ -0,0 +1,23 @@
+/**
+ * Application-owned deadlines for /api requests that the web server proxies to
+ * the API. An entry replaces BACKEND_PROXY_TIMEOUT_MS for every request whose
+ * path is pathPrefix or below it, for example
+ *   { pathPrefix: "/api/exports/", timeoutMs: 120_000 }
+ *   { pathPrefix: "/api/hosts/:hostId/file-transfers", timeoutMs: null }
+ * where a :name segment matches exactly one non-empty path segment. The most
+ * specific entry wins: more segments, then a literal segment over a parameter
+ * from the left. timeoutMs is how long the proxy waits for the API's response
+ * headers before it answers 504 BACKEND_TIMEOUT; null waits as long as the API
+ * takes. Either way the proxy answers 503 BACKEND_UNAVAILABLE once the API's
+ * GET /health stops answering, and the deadline ends when the response headers
+ * arrive. For null or 300 seconds and more, the proxy also turns off Bun's fetch
+ * idle timeout, which would otherwise end a silent wait after 300 seconds.
+ *
+ * Bun closes a silent connection up to 4 seconds before its idle timeout, so a
+ * longer wait also needs the API's API_IDLE_TIMEOUT and the web server's
+ * CONNECTION_IDLE_TIMEOUT (35 seconds each by default) more than 4 seconds above
+ * the deadline, or 0 for null or anything above 250 seconds. The proxy refuses
+ * to load when CONNECTION_IDLE_TIMEOUT cannot cover an entry here.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const APP_PROXY_TIMEOUTS: ReadonlyArray<{ pathPrefix: string; timeoutMs: number | null }> = [];

package/dist/templates/fullstack/apps/web/tsconfig.json

@@ -6,5 +6,5 @@
     "esModuleInterop": true,
     "skipLibCheck": true
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src", "vite.config.ts", "vite.extensions.ts"]
 }

package/dist/templates/fullstack/apps/web/vite.config.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { webSocketProxy } from "./vite.config.ts";
+
+describe("dev-server WebSocket proxy", () => {
+  it("sends each exact path in .podokit/dev.json to the API", () => {
+    const proxy = webSocketProxy(
+      JSON.stringify({ hostname: "app.localhost", webSocketPaths: ["/events/ws", "/agent.v1/ws"] }),
+      "http://api:5002",
+    );
+
+    expect(proxy).toEqual({
+      "^/events/ws(?:\\?.*)?$": { target: "http://api:5002", ws: true, xfwd: true },
+      "^/agent\\.v1/ws(?:\\?.*)?$": { target: "http://api:5002", ws: true, xfwd: true },
+    });
+    const [events] = Object.keys(proxy).map((key) => new RegExp(key));
+    expect(events?.test("/events/ws")).toBe(true);
+    expect(events?.test("/events/ws?token=1")).toBe(true);
+    expect(events?.test("/events/ws/other")).toBe(false);
+    expect(events?.test("/events/wsx")).toBe(false);
+  });
+
+  it("proxies nothing without the file or its paths", () => {
+    expect(webSocketProxy(null)).toEqual({});
+    expect(webSocketProxy(JSON.stringify({ hostname: "app.localhost" }))).toEqual({});
+  });
+
+  it("rejects a path the gateway would reject", () => {
+    expect(() => webSocketProxy(JSON.stringify({ webSocketPaths: ["events/ws"] }))).toThrow(
+      'invalid path: "events/ws"',
+    );
+    expect(() => webSocketProxy(JSON.stringify({ webSocketPaths: "/events/ws" }))).toThrow("must be an array");
+  });
+});

package/dist/templates/fullstack/apps/web/vite.config.ts

@@ -1,8 +1,10 @@
+import { readFileSync } from "node:fs";
 import adapter from "@sveltejs/adapter-bun";
 import { sveltekit } from "@sveltejs/kit/vite";
 import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
 import tailwindcss from "@tailwindcss/vite";
-import { defineConfig } from "vite";
+import { defineConfig, mergeConfig, type ProxyOptions } from "vite";
+import { appSvelteKitConfig, appViteConfig } from "./vite.extensions.ts";
 
 // Inside the dev container, bind to all interfaces and accept local gateway or
 // HTTPS tunnel hostnames. Vite derives HMR's protocol, host, and port from the
@@ -10,16 +12,56 @@ import { defineConfig } from "vite";
 const inDocker = process.env.VITE_DOCKER === "1";
 const publicOrigin = process.env.PODOKIT_BUILD_ORIGIN;
 
-export default defineConfig({
-  plugins: [
-    tailwindcss(),
-    sveltekit({
-      adapter: adapter(),
-      preprocess: vitePreprocess(),
-      ...(publicOrigin ? { paths: { origin: publicOrigin } } : {}),
+/**
+ * Dev-server proxies for the exact WebSocket paths in `.podokit/dev.json`. A
+ * SvelteKit route cannot answer an upgrade, so `bun run dev` sends these paths to
+ * the API the way the `podo dev` gateway and a deployment's edge do. The API must
+ * authenticate each upgrade itself.
+ */
+export function webSocketProxy(
+  devConfig: string | null,
+  target = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002",
+): Record<string, ProxyOptions> {
+  if (devConfig === null) return {};
+  const { webSocketPaths = [] } = JSON.parse(devConfig) as { webSocketPaths?: unknown };
+  if (!Array.isArray(webSocketPaths)) throw new Error(".podokit/dev.json webSocketPaths must be an array of paths");
+  return Object.fromEntries(
+    webSocketPaths.map((path: unknown) => {
+      if (typeof path !== "string" || !/^\/[A-Za-z0-9._~!$&'()+,;=:@/-]+$/.test(path)) {
+        throw new Error(`.podokit/dev.json webSocketPaths has an invalid path: ${JSON.stringify(path)}`);
+      }
+      const exact = `^${path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\?.*)?$`;
+      return [exact, { target, ws: true, xfwd: true }];
     }),
-  ],
-  server: {
-    ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
-  },
-});
+  );
+}
+
+function readDevConfig(): string | null {
+  try {
+    return readFileSync(new URL("../../.podokit/dev.json", import.meta.url), "utf8");
+  } catch (cause) {
+    if ((cause as { code?: unknown }).code === "ENOENT") return null;
+    throw cause;
+  }
+}
+
+export default defineConfig((env) =>
+  mergeConfig(
+    {
+      plugins: [
+        tailwindcss(),
+        sveltekit({
+          adapter: adapter(),
+          preprocess: vitePreprocess(),
+          ...appSvelteKitConfig,
+          ...(publicOrigin ? { paths: { ...appSvelteKitConfig.paths, origin: publicOrigin } } : {}),
+        }),
+      ],
+      server: {
+        ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
+        ...(env.command === "serve" ? { proxy: webSocketProxy(readDevConfig()) } : {}),
+      },
+    },
+    typeof appViteConfig === "function" ? appViteConfig(env) : appViteConfig,
+  ),
+);

package/dist/templates/fullstack/apps/web/vite.extensions.ts

@@ -0,0 +1,23 @@
+import type { Config as SvelteKitConfig } from "@sveltejs/kit/vite";
+import type { UserConfig, UserConfigFnObject } from "vite";
+
+/**
+ * Application-owned additions to the managed vite.config.ts, combined with Vite's
+ * `mergeConfig`: lists such as `plugins` are appended and objects are merged key
+ * by key. Use it for dev-server warmup, dependency optimization, `define`
+ * constants, extra plugins, or extra allowed hosts instead of editing
+ * vite.config.ts. A function receives Vite's `{ command, mode }`. WebSocket paths
+ * listed in `.podokit/dev.json` already reach the API through the dev server.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const appViteConfig: UserConfig | UserConfigFnObject = {
+  // Transform the pages most sessions open first as soon as the dev server starts:
+  // server: { warmup: { clientFiles: ["./src/routes/+layout.svelte", "./src/routes/+page.svelte"] } },
+};
+
+/**
+ * Application-owned SvelteKit options, such as `alias`, `csrf`, or `prerender`.
+ * PodoKit sets `adapter` and `preprocess`, and `paths.origin` from
+ * PODOKIT_BUILD_ORIGIN at build time.
+ */
+export const appSvelteKitConfig: SvelteKitConfig = {};

package/dist/templates/fullstack/compose.dev.yaml

@@ -48,6 +48,7 @@ services:
         - { action: sync, path: ./apps/web/src, target: /app/apps/web/src }
         - { action: sync, path: ./apps/web/static, target: /app/apps/web/static }
         - { action: sync+restart, path: ./apps/web/vite.config.ts, target: /app/apps/web/vite.config.ts }
+        - { action: sync+restart, path: ./apps/web/vite.extensions.ts, target: /app/apps/web/vite.extensions.ts }
         - { action: rebuild, path: ./apps/web/package.json }
 
   api:
@@ -121,7 +122,7 @@ services:
     mem_limit: ${MINIO_MEM_LIMIT:-512m}
     memswap_limit: ${MINIO_MEM_LIMIT:-512m}
     profiles: [storage]
-    image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z
+    image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z@sha256:635197cb9f36d01bee221d34d1c7d7960f6a95c48b0b6c01d99cd13bdae51a46
     command: server /data --console-address ":9001"
     environment:
       MINIO_ROOT_USER: podokit
@@ -134,15 +135,17 @@ services:
     mem_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     memswap_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     profiles: [storage]
-    image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z
+    image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z@sha256:cfc83108c3abb371f8fb84d99c1fdc88f8c237e022409b0081fb7c0a3be634dd
     depends_on:
       minio: { condition: service_started }
+    # -e stops at the first failing command, so a bucket that cannot be
+    # created fails this service instead of leaving uploads to fail later.
     entrypoint:
       - sh
-      - -c
+      - -ec
       - |
         until mc alias set loc http://minio:9000 podokit podokitsecret; do sleep 1; done
-        mc mb -p loc/podokit || true
+        mc mb --ignore-existing loc/podokit
     networks: [podokit]
 
 networks:

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/SKILL.md

@@ -16,9 +16,9 @@ Read the profile's `driver` first and say which one you are operating.
 1. Run `{{packageExecutor}} @podosoft/podokit status`, `{{packageExecutor}} @podosoft/podokit diff`, and `{{packageExecutor}} @podosoft/podokit doctor`. Stop if managed-file conflicts or unsupported framework versions could make the image unreliable.
 2. Read [references/profile.md](references/profile.md) before creating or changing a deployment profile.
 3. Make sure the images exist for that tag. Read [references/release.md](references/release.md): tagging `vX.Y.Z` runs the release workflow, which builds and pushes both images and stops there. Never apply a release whose images were not published.
-4. Run `{{packageExecutor}} @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing secret values.
+4. Run `{{packageExecutor}} @podosoft/podokit deploy doctor --profile <name>`. Resolve every `FAIL` line and show the user every `warn` line, without printing secret values.
 5. Run `{{packageExecutor}} @podosoft/podokit deploy plan --profile <name> --release <stable-semver> --json`.
-6. Show the user the driver, the target (context plus namespace and Helm release, or Docker context plus Compose project), the fingerprint result, the exact image digests, the current revision, the actions, the migration warning, and the plan hash.
+6. Show the user the driver, the target (context plus namespace and Helm release, or Docker context plus Compose project), the fingerprint result, the exact image digests, the current revision, the actions, every plan warning, and the plan hash.
 7. Do not apply until the user explicitly approves that exact plan.
 8. Apply with `{{packageExecutor}} @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
 9. Run `{{packageExecutor}} @podosoft/podokit deploy status --profile <name> --json` and `{{packageExecutor}} @podosoft/podokit deploy verify --profile <name> --json`.

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/references/profile.md

@@ -24,9 +24,16 @@ Review these fields before planning:
   `stripPrefix` Middleware sends them to API without `/api`. It needs a
   Traefik-served IngressClass, and `/api/auth` is rejected. `podo deploy init`
   and `podo add` fill in the paths installed modules declare (file-upload:
-  `/api/files/uploads/`); keep them.
+  `/api/files/uploads/`); keep them. `edgeProxies` counts the reverse proxies in
+  front of the Ingress controller or NodePort (default 0); the web server then
+  trusts that many plus the controller in `X-Forwarded-For`. Never set
+  `XFF_DEPTH`, `ADDRESS_HEADER`, `TRUSTED_PROXY_HOPS`, or `TRUSTED_PROXY_HEADER`
+  in `runtimeConfig`; the profile refuses them.
 - `workloads`: API/web replicas and resources plus an optional worker
-- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage
+- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage.
+  PostgreSQL also takes `maxConnections` (default 100) and `appPools` for pools the
+  application opens itself; the doctor and the plan check the connection budget
+  against them, so lower `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
 - `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
 - `runtimeConfig`: non-sensitive environment values only
 - `verification`: HTTPS origin and checks with exact statuses and optional JSON fields
@@ -72,7 +79,9 @@ The fields that differ from the Kubernetes driver:
   it, sends exact WebSocket paths to API, sends `apiPaths` prefixes to API with
   `/api` removed, and sends every other request to web. Forwarding headers are trusted
   only from the direct proxy CIDRs in `trustedProxyCidrs`; leave it empty without an
-  external proxy. The bind address defaults to `127.0.0.1`, because the expected
+  external proxy. `edgeProxies` counts the reverse proxies in front of the published
+  port (default 1); with the gateway it must match `trustedProxyCidrs`, which the
+  doctor checks. The bind address defaults to `127.0.0.1`, because the expected
   front door is a trusted reverse proxy — binding every interface publishes the app
   before TLS exists.
 - `workloads`: replicas plus Compose `cpus` and `memory` limits