akanjs 3.0.0-alpha.72 → 3.0.0-alpha.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.72",
+  "version": "3.0.0-alpha.74",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -18,6 +18,7 @@ import { LogHub } from "./logging/logHub";
 import { LogStreamRoute } from "./logging/logStreamRoute";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
+import { resolveStaticPath } from "./staticPath";
 import { getWebConfigFromEnv } from "./types";
 
 interface ChildState {
@@ -669,7 +670,7 @@ export class AkanApp {
     if (!this.#web.ssr) return null;
     const clientPrefix = "/_akan/client/";
     if (url.pathname.startsWith(clientPrefix)) {
-      const filePath = this.#safeResolve(
+      const filePath = resolveStaticPath(
         path.join(this.#artifactDir, "client"),
         url.pathname.slice(clientPrefix.length),
       );
@@ -684,7 +685,7 @@ export class AkanApp {
 
     for (const prefix of ["/_akan/styles/", "/_akan/fonts/"]) {
       if (!url.pathname.startsWith(prefix)) continue;
-      const filePath = this.#safeResolve(this.#artifactDir, url.pathname.slice("/_akan/".length));
+      const filePath = resolveStaticPath(this.#artifactDir, url.pathname.slice("/_akan/".length));
       if (!filePath) return new Response("Not Found", { status: 404 });
       const file = Bun.file(filePath);
       if (!(await file.exists())) return new Response("Not Found", { status: 404 });
@@ -831,6 +832,13 @@ export class AkanApp {
         this.#scheduleChildRestart(child, child.proc, "upstream-open-failed");
         return AkanApp.#unavailableResponse(req, "Federation child upstream is unreachable; restarting");
       }
+      if (req.signal.aborted) return AkanApp.#clientClosedResponse();
+      if (AkanApp.#isUpstreamMidFlightClose(error)) {
+        this.logger.warn(
+          `Child ${child.idx}/${child.role} closed the connection mid-request (${req.method} ${new URL(req.url).pathname})`,
+        );
+        return AkanApp.#badGatewayResponse(req);
+      }
       throw error;
     } finally {
       child.metrics.activeRequests = Math.max(0, (child.metrics.activeRequests ?? 1) - 1);
@@ -844,6 +852,43 @@ export class AkanApp {
     return candidate.code === "FailedToOpenSocket" || String(candidate.message ?? "").includes("FailedToOpenSocket");
   }
 
+  /**
+   * The socket opened and then died under us: the child crashed, or was recycled, while its response was still
+   * in flight. Distinct from `FailedToOpenSocket` — that one means the child was already gone when we dialled,
+   * and only that one implies the socket needs a restart, which the child's own exit handler schedules anyway.
+   * Rethrowing this instead reaches Bun as an unhandled route error, which answers 500 and prints the raw
+   * `TypeError` against whatever URL happened to be in flight — usually a browser background probe, which is
+   * how a dead child gets misread as a bug in the probed route.
+   */
+  static #isUpstreamMidFlightClose(error: unknown): boolean {
+    if (!error || typeof error !== "object") return false;
+    const candidate = error as { code?: unknown; message?: unknown };
+    if (candidate.code === "ECONNRESET" || candidate.code === "ConnectionClosed") return true;
+    return String(candidate.message ?? "").includes("connection was closed");
+  }
+
+  static #clientClosedResponse(): Response {
+    return new Response(null, { status: 499, headers: { "cache-control": "no-store" } });
+  }
+
+  static #badGatewayResponse(req: Request): Response {
+    const detail = "The replica closed the connection before it finished answering.";
+    if (req.headers.get("accept")?.includes("text/html")) {
+      return new Response(
+        AkanApp.#statusPageHtml({
+          heading: "Backend dropped the connection",
+          detail,
+          note: "The replica is restarting — this page reloads itself as soon as it answers.",
+        }),
+        { status: 502, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } },
+      );
+    }
+    return new Response(detail, {
+      status: 502,
+      headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+    });
+  }
+
   /**
    * A replica that is booting or restarting is normally back within a second or two, and a browser
    * handed a 503 stays on that dead page until somebody reloads by hand — so a request waits for the
@@ -1018,23 +1063,6 @@ export class AkanApp {
     return new Response(Bun.file(filePath).stream(), { headers });
   }
 
-  #safeResolve(baseDir: string, urlPath: string): string | null {
-    let decoded: string;
-    try {
-      decoded = decodeURIComponent(urlPath);
-    } catch {
-      return null;
-    }
-    if (decoded.includes("\0")) return null;
-    const normalizedBase = path.resolve(baseDir);
-    const rel = decoded.replace(/^[/\\]+/, "");
-    const resolved = path.resolve(normalizedBase, rel);
-    if (resolved === normalizedBase) return resolved;
-    const baseWithSep = normalizedBase.endsWith(path.sep) ? normalizedBase : `${normalizedBase}${path.sep}`;
-    if (!resolved.startsWith(baseWithSep)) return null;
-    return resolved;
-  }
-
   #makeProxyHeaders(req: Request, childIdx: number, server?: Bun.Server<GatewayWsData>) {
     return makeAkanChildProxyHeaders(req, childIdx, server?.requestIP(req));
   }

package/server/imageOptimizer.ts

@@ -5,6 +5,7 @@ import { Logger } from "akanjs/common";
 import { isAnimatedImage } from "./animatedImage";
 import { ImageOptimizerError } from "./imageOptimizerError";
 import { Semaphore } from "./semaphore";
+import { resolveStaticPath } from "./staticPath";
 import {
   type AkanImageConfig,
   type AkanImageFormat,
@@ -260,7 +261,7 @@ export class ImageOptimizer {
 
   async #readLocalImage(href: string): Promise<ImageSource> {
     const url = new URL(href, "http://local.akan");
-    const filePath = ImageOptimizer.#safeResolve(this.#publicDir, url.pathname);
+    const filePath = resolveStaticPath(this.#publicDir, url.pathname);
     if (!filePath) throw new ImageOptimizerError(400, '"url" parameter is not allowed');
     const file = Bun.file(filePath);
     if (!(await file.exists())) throw new ImageOptimizerError(404, "Image not found");
@@ -455,22 +456,6 @@ export class ImageOptimizer {
     }
   }
 
-  static #safeResolve(baseDir: string, urlPath: string): string | null {
-    let decoded: string;
-    try {
-      decoded = decodeURIComponent(urlPath);
-    } catch {
-      return null;
-    }
-    if (decoded.includes("\0")) return null;
-    const normalizedBase = path.resolve(baseDir);
-    const rel = decoded.replace(/^[/\\]+/, "");
-    const resolved = path.resolve(normalizedBase, rel);
-    if (resolved === normalizedBase) return resolved;
-    const baseWithSep = normalizedBase.endsWith(path.sep) ? normalizedBase : normalizedBase + path.sep;
-    return resolved.startsWith(baseWithSep) ? resolved : null;
-  }
-
   static async #readResponseBuffer(res: Response, maxBytes: number): Promise<Buffer> {
     const contentLength = Number.parseInt(res.headers.get("content-length") ?? "0", 10);
     if (contentLength > maxBytes) throw new ImageOptimizerError(413, "Remote image is too large");

package/server/lifecycle/shutdownManager.ts

@@ -4,7 +4,8 @@ export class ShutdownManager {
   /**
    * Registers process-level handlers that drive `onShutdown` on:
    *   - SIGTERM / SIGINT (graceful stop → exit(0) on success, exit(1) on error)
-   *   - uncaughtException / unhandledRejection (best-effort stop → exit(1))
+   *   - uncaughtException (best-effort stop → exit(1))
+   *   - unhandledRejection (logged at error, process kept alive; see `#isFatalUnhandledRejection`)
    *
    * Kept separate from `AkanServer` so the server class doesn't have to know about
    * Node-level process events, and so tests can opt out by not calling it.
@@ -37,6 +38,7 @@ export class ShutdownManager {
 
     process.on("unhandledRejection", async (reason) => {
       logger.error(`Unhandled rejection: ${ShutdownManager.#formatError(reason)}`);
+      if (!ShutdownManager.#isFatalUnhandledRejection()) return;
       try {
         await onShutdown();
         process.exit(1);
@@ -46,6 +48,19 @@ export class ShutdownManager {
     });
   }
 
+  /**
+   * A rejected promise nobody awaited is scoped to whatever built it, so it cannot leave the process in the
+   * unknown state an `uncaughtException` does — while exiting over one drops every other in-flight request,
+   * every websocket, and (under federation) restarts the replica. React's streaming SSR is the case that forced
+   * this: it rejects `stream.allReady` for a post-shell render failure and holds no handler of its own, so one
+   * page's boundary error used to kill a whole child. Set `AKAN_FATAL_UNHANDLED_REJECTION=1` to restore the
+   * exit for a deployment that would rather crash than serve on.
+   */
+  static #isFatalUnhandledRejection(): boolean {
+    const flag = process.env.AKAN_FATAL_UNHANDLED_REJECTION;
+    return flag === "1" || flag === "true";
+  }
+
   static #formatError(error: unknown): string {
     return error instanceof Error ? (error.stack ?? error.message) : String(error);
   }

package/server/rscWorker.tsx

@@ -850,6 +850,32 @@ export class RscRenderer {
     this.#send({ type: "metrics", metrics });
   }
 
+  /**
+   * An error raised after the first Flight chunk has left the worker can no longer become a status code or a
+   * system error page — `sendLateRedirect` is the only control the host can still act on, so the render
+   * control is dropped. Logging here is the only record that the request failed at all; without it a page
+   * whose boundary died mid-stream is indistinguishable from one that rendered.
+   */
+  #reportRenderError(error: unknown, pathname?: string): void {
+    const description = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    const scope = pathname ? ` path=${pathname}` : "";
+    if (RscRenderer.#isExpectedRequestAbort(error)) {
+      this.#logger.debug(`[rsc] render aborted${scope}: ${description}`);
+      return;
+    }
+    this.#logger.error(`[rsc] render failed${scope}: ${description}`);
+  }
+
+  /** A client that navigated away, or a stream the host cancelled: expected, and not the replica's problem. */
+  static #isExpectedRequestAbort(error: unknown): boolean {
+    if (!(error instanceof Error)) return false;
+    return (
+      error.name === "AbortError" ||
+      error.message === "Connection closed." ||
+      error.message.includes("The connection was closed")
+    );
+  }
+
   async #renderFlightElement(
     element: ReactNode,
     clientManifest: ClientManifest,
@@ -888,6 +914,7 @@ export class RscRenderer {
           return error.digest;
         }
         controlRef.current = { type: "error", error };
+        this.#reportRenderError(error, options.trace?.pathname);
         return error instanceof Error ? error.message : String(error);
       },
     });

package/server/ssrFromRscRenderer.tsx

@@ -1,4 +1,5 @@
 import { Readable } from "node:stream";
+import { Logger } from "akanjs/common";
 import { type AkanRequestStore, type AkanTheme, pushRequestFallback, requestStorage } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
@@ -575,6 +576,8 @@ export class SsrFromRscRenderer {
     SsrFromRscRenderer.#installWebpackShims();
   }
 
+  static readonly #logger = new Logger("SsrFromRscRenderer");
+
   static getChunkRegistryStats(): SsrChunkRegistryStats {
     return { ...SsrFromRscRenderer.#chunkRegistryStats };
   }
@@ -599,8 +602,14 @@ export class SsrFromRscRenderer {
       const root = await thenable;
       const stream = await renderToReadableStream(root, {
         bootstrapScriptContent: bootstrap,
+        onError: (error) => SsrFromRscRenderer.#reportRenderError(error, input),
       });
       if (waitForAllReady) await stream.allReady;
+      else {
+        SsrFromRscRenderer.holdPostShellErrors(stream, (error) =>
+          SsrFromRscRenderer.#reportRenderError(error, input, "post-shell"),
+        );
+      }
       return stream;
     };
     const requestContext = input.requestStore ?? input.request;
@@ -657,6 +666,47 @@ export class SsrFromRscRenderer {
     };
   }
 
+  /**
+   * React rejects `stream.allReady` for any fatal error raised after the shell flushed — an abort landing
+   * mid-flush, a `flushCompletedQueues` invariant — and it attaches a handler to that promise itself only on
+   * the shell-error path, because `completeShell` replaces `onShellError` with a noop. Shell-first streaming
+   * never reads `allReady`, so an unheld rejection reaches `process.on("unhandledRejection")`, and under
+   * federation that took the whole replica down over one request's render.
+   *
+   * Holding it keeps the failure scoped to the stream that raised it. The response cannot become a 5xx — the
+   * shell's headers and markup are already on the wire — so the client gets a truncated document and the stack
+   * goes to the log; every other request and socket on the replica survives.
+   */
+  static holdPostShellErrors(stream: { allReady: Promise<void> }, report: (error: unknown) => void): void {
+    void stream.allReady.catch(report);
+  }
+
+  static #reportRenderError(error: unknown, input: SsrFromRscInput, phase = "render"): void {
+    const description = SsrFromRscRenderer.#describeError(error);
+    if (SsrFromRscRenderer.#isExpectedRequestAbort(error)) {
+      SsrFromRscRenderer.#logger.debug(`[SSR] ${phase} aborted: ${description}`);
+      return;
+    }
+    const path = input.request ? new URL(input.request.url).pathname : "unknown";
+    SsrFromRscRenderer.#logger.error(`[SSR] ${phase} failed path=${path}: ${description}`);
+  }
+
+  static #describeError(error: unknown): string {
+    if (!(error instanceof Error)) return String(error);
+    return error.stack ?? error.message;
+  }
+
+  /** A client that navigated away, or a stream we cancelled ourselves: expected, and not the replica's problem. */
+  static #isExpectedRequestAbort(error: unknown): boolean {
+    if (!(error instanceof Error)) return false;
+    return (
+      error.name === "AbortError" ||
+      error.name === "AkanRedirectError" ||
+      error.message === "Connection closed." ||
+      error.message.includes("The connection was closed")
+    );
+  }
+
   static #suppressExpectedLateRedirectError(
     thenable: PromiseLike<ReactNode>,
     lateControl?: Promise<SsrLateRedirect | null>,

package/server/staticPath.ts

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 
 /**
@@ -9,9 +8,13 @@ import path from "node:path";
  * then a NUL check (a truncating byte in a path), then `path.resolve` to collapse the traversal, then
  * containment against the base **with a separator** — without it `/public-secrets` passes a `/public` check.
  *
- * `path.resolve` works on the string and does not follow links, so a symlink inside the tree can still point
- * out of it. Callers check existence after this, so a path that resolves to nothing is handed back and 404s
- * there; only a link that really leads outside is refused.
+ * Symlinks are followed, like nginx and `serve-static` do: `akan sync` builds `public/libs/<lib>` as a link to
+ * `<workspaceRoot>/libs/<lib>/public`, so a link out of the tree is how a lib ships its assets, not an attack.
+ * Refusing those would 404 every lib asset under `akan start` and nothing else — `akan build` copies `public/`
+ * with `dereference: true`, so a built app has no links left to refuse. Traversal is what the string checks
+ * above stop, and they run before any of this touches the filesystem.
+ *
+ * Callers check existence after this, so a path that resolves to nothing is handed back and 404s there.
  */
 export const resolveStaticPath = (baseDir: string, urlPath: string): string | null => {
   let decoded: string;
@@ -27,13 +30,5 @@ export const resolveStaticPath = (baseDir: string, urlPath: string): string | nu
   if (resolved === normalizedBase) return resolved;
   const baseWithSep = normalizedBase.endsWith(path.sep) ? normalizedBase : normalizedBase + path.sep;
   if (!resolved.startsWith(baseWithSep)) return null;
-  try {
-
-    const realBase = fs.realpathSync(normalizedBase);
-    const realBaseWithSep = realBase.endsWith(path.sep) ? realBase : realBase + path.sep;
-    const real = fs.realpathSync(resolved);
-    if (real !== realBase && !real.startsWith(realBaseWithSep)) return null;
-  } catch {
-  }
   return resolved;
 };

package/server/webRouter.ts

@@ -519,6 +519,12 @@ export class WebRouter {
         WebRouter.#deepLinkAssociationResponse(ANDROID_ASSET_LINKS_PATH, this.#artifact, {
           cacheControl: this.#prodMode ? "public, max-age=3600" : "no-store",
         }) ?? new Response("Not Found", { status: 404 }),
+
+      "/.well-known/*": () =>
+        new Response("Not Found", {
+          status: 404,
+          headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
+        }),
       [FIREBASE_MESSAGING_SW_PATH]: async () => {
         this.#requestStats.staticAsset += 1;
         const firebaseConfig = await WebRouter.#resolveFirebaseClientConfig();

package/types/server/lifecycle/shutdownManager.d.ts

@@ -4,7 +4,8 @@ export declare class ShutdownManager {
     /**
      * Registers process-level handlers that drive `onShutdown` on:
      *   - SIGTERM / SIGINT (graceful stop → exit(0) on success, exit(1) on error)
-     *   - uncaughtException / unhandledRejection (best-effort stop → exit(1))
+     *   - uncaughtException (best-effort stop → exit(1))
+     *   - unhandledRejection (logged at error, process kept alive; see `#isFatalUnhandledRejection`)
      *
      * Kept separate from `AkanServer` so the server class doesn't have to know about
      * Node-level process events, and so tests can opt out by not calling it.

package/types/server/ssrFromRscRenderer.d.ts

@@ -36,4 +36,18 @@ export declare class SsrFromRscRenderer {
     #private;
     static getChunkRegistryStats(): SsrChunkRegistryStats;
     render(input: SsrFromRscInput): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * React rejects `stream.allReady` for any fatal error raised after the shell flushed — an abort landing
+     * mid-flush, a `flushCompletedQueues` invariant — and it attaches a handler to that promise itself only on
+     * the shell-error path, because `completeShell` replaces `onShellError` with a noop. Shell-first streaming
+     * never reads `allReady`, so an unheld rejection reaches `process.on("unhandledRejection")`, and under
+     * federation that took the whole replica down over one request's render.
+     *
+     * Holding it keeps the failure scoped to the stream that raised it. The response cannot become a 5xx — the
+     * shell's headers and markup are already on the wire — so the client gets a truncated document and the stack
+     * goes to the log; every other request and socket on the replica survives.
+     */
+    static holdPostShellErrors(stream: {
+        allReady: Promise<void>;
+    }, report: (error: unknown) => void): void;
 }

package/types/server/staticPath.d.ts

@@ -6,8 +6,12 @@
  * then a NUL check (a truncating byte in a path), then `path.resolve` to collapse the traversal, then
  * containment against the base **with a separator** — without it `/public-secrets` passes a `/public` check.
  *
- * `path.resolve` works on the string and does not follow links, so a symlink inside the tree can still point
- * out of it. Callers check existence after this, so a path that resolves to nothing is handed back and 404s
- * there; only a link that really leads outside is refused.
+ * Symlinks are followed, like nginx and `serve-static` do: `akan sync` builds `public/libs/<lib>` as a link to
+ * `<workspaceRoot>/libs/<lib>/public`, so a link out of the tree is how a lib ships its assets, not an attack.
+ * Refusing those would 404 every lib asset under `akan start` and nothing else — `akan build` copies `public/`
+ * with `dereference: true`, so a built app has no links left to refuse. Traversal is what the string checks
+ * above stop, and they run before any of this touches the filesystem.
+ *
+ * Callers check existence after this, so a path that resolves to nothing is handed back and 404s there.
  */
 export declare const resolveStaticPath: (baseDir: string, urlPath: string) => string | null;

package/types/ui/Loading/index_.d.ts

@@ -0,0 +1,13 @@
+/**
+ * One named export per member, rather than the `Loading` namespace object itself, because the `"use client"`
+ * transform replaces a client module's *exports* with `registerClientReference` stubs. A namespace exported
+ * from here would reach a server component as one reference for the whole object, and `Loading.Skeleton` on it
+ * would read a property the stub does not have — `undefined`, which React reports as an invalid element type.
+ * The namespace is assembled in `index.ts`, which carries no directive, so each member crosses on its own.
+ */
+export declare const LoadingArea: import("react").ComponentType<Record<string, never>>;
+export declare const LoadingButton: import("react").ComponentType<import("./Button.d.ts").LoadingProps>;
+export declare const LoadingInput: import("react").ComponentType<import("./Input.d.ts").LoadingProps>;
+export declare const LoadingProgressBar: import("react").ComponentType<import("./ProgressBar.d.ts").ProgressBarProps>;
+export declare const LoadingSkeleton: import("react").ComponentType<import("./Skeleton.d.ts").SkeletonProps>;
+export declare const LoadingSpin: import("react").ComponentType<import("./Spin.d.ts").SpinProps>;

package/ui/Loading/index.ts

@@ -0,0 +1,15 @@
+import { LoadingArea, LoadingButton, LoadingInput, LoadingProgressBar, LoadingSkeleton, LoadingSpin } from "./index_";
+
+/**
+ * Loading indicators. Each member is an independent override slot (`LoadingSpin`, `LoadingSkeleton`,
+ * `LoadingProgressBar`, `LoadingButton`, `LoadingInput`, `LoadingArea`), resolved from the closest
+ * `page/**\/_overrides.tsx` in the route's ancestry, otherwise the shipped default.
+ */
+export const Loading = {
+  Area: LoadingArea,
+  Button: LoadingButton,
+  Input: LoadingInput,
+  ProgressBar: LoadingProgressBar,
+  Skeleton: LoadingSkeleton,
+  Spin: LoadingSpin,
+};

package/ui/Loading/index_.tsx

@@ -0,0 +1,22 @@
+"use client";
+import { createOverridable } from "../UiOverride";
+import { Area } from "./Area";
+import { Button } from "./Button";
+import { Input } from "./Input";
+import { ProgressBar } from "./ProgressBar";
+import { Skeleton } from "./Skeleton";
+import { Spin } from "./Spin";
+
+/**
+ * One named export per member, rather than the `Loading` namespace object itself, because the `"use client"`
+ * transform replaces a client module's *exports* with `registerClientReference` stubs. A namespace exported
+ * from here would reach a server component as one reference for the whole object, and `Loading.Skeleton` on it
+ * would read a property the stub does not have — `undefined`, which React reports as an invalid element type.
+ * The namespace is assembled in `index.ts`, which carries no directive, so each member crosses on its own.
+ */
+export const LoadingArea = createOverridable("LoadingArea", Area);
+export const LoadingButton = createOverridable("LoadingButton", Button);
+export const LoadingInput = createOverridable("LoadingInput", Input);
+export const LoadingProgressBar = createOverridable("LoadingProgressBar", ProgressBar);
+export const LoadingSkeleton = createOverridable("LoadingSkeleton", Skeleton);
+export const LoadingSpin = createOverridable("LoadingSpin", Spin);

package/ui/Loading/index.tsx

@@ -1,22 +0,0 @@
-"use client";
-import { createOverridable } from "../UiOverride";
-import { Area } from "./Area";
-import { Button } from "./Button";
-import { Input } from "./Input";
-import { ProgressBar } from "./ProgressBar";
-import { Skeleton } from "./Skeleton";
-import { Spin } from "./Spin";
-
-/**
- * Loading indicators. Each member is an independent override slot (`LoadingSpin`, `LoadingSkeleton`,
- * `LoadingProgressBar`, `LoadingButton`, `LoadingInput`, `LoadingArea`), resolved from the closest
- * `page/**\/_overrides.tsx` in the route's ancestry, otherwise the shipped default.
- */
-export const Loading = {
-  Area: createOverridable("LoadingArea", Area),
-  Button: createOverridable("LoadingButton", Button),
-  Input: createOverridable("LoadingInput", Input),
-  ProgressBar: createOverridable("LoadingProgressBar", ProgressBar),
-  Skeleton: createOverridable("LoadingSkeleton", Skeleton),
-  Spin: createOverridable("LoadingSpin", Spin),
-};