akanjs 3.0.0-alpha.73 → 3.0.0-alpha.75

package/fetch/client/fetchClient.ts

@@ -98,7 +98,7 @@ export class FetchClient {
     private ErrorCls?: ErrorConstructor,
   ) {
     this.origin = origin;
-    this.http = new HttpClient(origin, ErrorCls);
+    this.http = new HttpClient(origin, { ErrorCls });
     this.ws = new WsClient(FetchClient.#makeWsUri(origin), ErrorCls);
     Object.assign(this.#handlerStore, handler);
     this.handler = this.#makeHandlerProxy();

package/fetch/client/httpClient.ts

@@ -22,11 +22,15 @@ export interface ErrorConstructor {
   fromJSON: (payload: ErrorResponsePayload) => RestoredError;
 }
 
-interface FetchOptions {
+export interface HttpClientOptions {
   headers?: Record<string, string>;
-  baseUrl?: string;
   /** Milliseconds before the request is abandoned; `false` waits as long as the browser will. */
   timeout?: number | false;
+  ErrorCls?: ErrorConstructor;
+}
+
+interface FetchOptions extends Pick<HttpClientOptions, "headers" | "timeout"> {
+  baseUrl?: string;
 }
 
 const jsonContentType = /^application\/(?:[\w.+-]+\+)?json\b/i;
@@ -53,11 +57,14 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 
 export class HttpClient {
   readonly baseUrl: string;
-  constructor(
-    baseUrl: string,
-    private ErrorCls?: ErrorConstructor,
-  ) {
+  #headers: Record<string, string>;
+  #timeout?: number | false;
+  private ErrorCls?: ErrorConstructor;
+  constructor(baseUrl: string, options: HttpClientOptions = {}) {
     this.baseUrl = baseUrl;
+    this.#headers = options.headers ?? {};
+    this.#timeout = options.timeout;
+    this.ErrorCls = options.ErrorCls;
   }
 
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
@@ -70,13 +77,13 @@ export class HttpClient {
     return `${this.#resolveBaseUrl(options.baseUrl)}${url}`;
   }
 
-  static #makeHeaders(headers: Record<string, string>, options: FetchOptions) {
-    return { Accept: "application/json", ...headers, ...options.headers };
+  #makeHeaders(headers: Record<string, string>, options: FetchOptions) {
+    return { Accept: "application/json", ...this.#headers, ...headers, ...options.headers };
   }
   async get<Returns = unknown>(url: string, options: FetchOptions = {}): Promise<Returns> {
     return await this.#request<Returns>(
       this.#resolveUrl(url, options),
-      { headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options) },
+      { headers: this.#makeHeaders({ "Content-Type": "application/json" }, options) },
       options,
     );
   }
@@ -94,7 +101,7 @@ export class HttpClient {
     const { body, headers } = this.#makeReqContent(data);
     return await this.#request<Returns>(
       this.#resolveUrl(url, options),
-      { method, body, headers: HttpClient.#makeHeaders(headers, options) },
+      { method, body, headers: this.#makeHeaders(headers, options) },
       options,
     );
   }
@@ -115,13 +122,13 @@ export class HttpClient {
   async delete<Returns = unknown>(url: string, options: FetchOptions = {}): Promise<Returns> {
     return await this.#request<Returns>(
       this.#resolveUrl(url, options),
-      { method: "DELETE", headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options) },
+      { method: "DELETE", headers: this.#makeHeaders({ "Content-Type": "application/json" }, options) },
       options,
     );
   }
 
   async #request<Returns>(url: string, init: RequestInit, options: FetchOptions = {}): Promise<Returns> {
-    const res = await this.#fetch(url, HttpClient.#withTimeout(init, options));
+    const res = await this.#fetch(url, this.#withTimeout(init, options));
     return await this.#readJsonResponse<Returns>(res);
   }
 
@@ -130,8 +137,8 @@ export class HttpClient {
    * the request body is the only thing this side can tell that from. Everything else takes the default unless
    * the caller named one.
    */
-  static #withTimeout(init: RequestInit, options: FetchOptions): RequestInit {
-    const timeout = options.timeout ?? (init.body instanceof FormData ? false : DEFAULT_TIMEOUT_MS);
+  #withTimeout(init: RequestInit, options: FetchOptions): RequestInit {
+    const timeout = options.timeout ?? (init.body instanceof FormData ? false : (this.#timeout ?? DEFAULT_TIMEOUT_MS));
     if (timeout === false || !Number.isFinite(timeout) || timeout <= 0) return init;
     return { ...init, signal: AbortSignal.timeout(timeout) };
   }

package/package.json

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

package/server/akanApp.ts

@@ -832,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);
@@ -845,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

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/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/fetch/client/httpClient.d.ts

@@ -18,17 +18,20 @@ export interface RestoredError extends Error {
 export interface ErrorConstructor {
     fromJSON: (payload: ErrorResponsePayload) => RestoredError;
 }
-interface FetchOptions {
+export interface HttpClientOptions {
     headers?: Record<string, string>;
-    baseUrl?: string;
     /** Milliseconds before the request is abandoned; `false` waits as long as the browser will. */
     timeout?: number | false;
+    ErrorCls?: ErrorConstructor;
+}
+interface FetchOptions extends Pick<HttpClientOptions, "headers" | "timeout"> {
+    baseUrl?: string;
 }
 export declare class HttpClient {
     #private;
-    private ErrorCls?;
     readonly baseUrl: string;
-    constructor(baseUrl: string, ErrorCls?: ErrorConstructor | undefined);
+    private ErrorCls?;
+    constructor(baseUrl: string, options?: HttpClientOptions);
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
     get<Returns = unknown>(url: string, options?: FetchOptions): Promise<Returns>;
     send<Returns = unknown>(method: HttpMutationMethod, url: string, data: FormData | Record<string, unknown>, options?: FetchOptions): Promise<Returns>;

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/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),
-};