akanjs 2.4.0-rc.1 → 2.4.0-rc.2

package/base/baseEnv.ts

@@ -104,7 +104,11 @@ export const getEnv = (): ClientEnv => {
   const clientHost =
     process.env.AKAN_PUBLIC_CLIENT_HOST ??
     (operationMode === "local" || side === "server" ? "localhost" : window.location.hostname);
-  const clientPort = parseInt(process.env.AKAN_PUBLIC_CLIENT_PORT ?? (operationMode === "local" ? "8282" : "443"));
+  const clientPort =
+    side === "server"
+      ? parseInt(process.env.AKAN_PUBLIC_CLIENT_PORT ?? (operationMode === "local" ? "8282" : "443"))
+      : parseInt(window.location.port || (window.location.protocol === "https:" ? "443" : "80"));
+
   const clientHttpProtocol =
     side === "client"
       ? (window.location.protocol as "http:" | "https:")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.0-rc.1",
+  "version": "2.4.0-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -112,10 +112,13 @@ export class AkanApp {
     this.#serverPath = AkanApp.#resolveServerPath(resolvedOptions.serverPath ?? serverPath);
     this.#artifactDir = path.resolve(path.dirname(this.#serverPath), ".akan", "artifact");
     this.#replica = AkanApp.#parseReplicaConfig(resolvedOptions.replica);
-    this.#runtimeDir =
-      (resolvedOptions.runtimeDir ?? process.env.AKAN_RUNTIME_DIR ?? process.env.NODE_ENV === "production")
-        ? path.resolve(process.cwd(), "runtime")
-        : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime");
+    this.#runtimeDir = path.resolve(
+      resolvedOptions.runtimeDir ??
+        process.env.AKAN_RUNTIME_DIR ??
+        (process.env.NODE_ENV === "production"
+          ? path.resolve(process.cwd(), "runtime")
+          : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime")),
+    );
     this.#port = Number(resolvedOptions.port ?? process.env.PORT ?? 8282);
     this.#wsBasePort = Number(resolvedOptions.wsBasePort ?? process.env.AKAN_WS_BASE_PORT ?? this.#port + 10_000);
     this.#openapi = resolvedOptions.openapi;
@@ -234,9 +237,10 @@ export class AkanApp {
       Promise.all([...this.#children.values()].map((child) => child.proc.exited.catch(() => undefined))),
       new Promise((resolve) => setTimeout(resolve, AkanApp.#childShutdownWaitMs())),
     ]);
-    for (const child of this.#children.values()) {
-      if (!child.proc.killed) child.proc.kill();
-    }
+
+    const stragglers = [...this.#children.values()].filter((child) => !child.proc.killed);
+    for (const child of stragglers) child.proc.kill("SIGKILL");
+    await Promise.all(stragglers.map((child) => child.proc.exited.catch(() => undefined)));
     this.#children.clear();
     await this.#stopFileLogging();
     this.#resolveStopped?.();
@@ -657,7 +661,7 @@ export class AkanApp {
   async #proxyHttp(req: Request): Promise<Response> {
     const child = this.#pickFederationChild();
     if (!child?.upstream || child.upstream.type !== "unix") {
-      return new Response("No healthy federation child is ready", { status: 503 });
+      return this.#respondWithCrashPage(req) ?? new Response("No healthy federation child is ready", { status: 503 });
     }
     const url = new URL(req.url);
     const upstreamUrl = `http://akan-child${url.pathname}${url.search}`;
@@ -697,6 +701,70 @@ export class AkanApp {
     return candidate.code === "FailedToOpenSocket" || String(candidate.message ?? "").includes("FailedToOpenSocket");
   }
 
+  /**
+   * Dev-only: every traffic replica is in the crashed terminal state, so a bare 503 would hide the
+   * boot error from the browser. Surface it, and reload once a fixed gateway takes over the port.
+   */
+  #respondWithCrashPage(req: Request): Response | null {
+    if (!this.#devHosted) return null;
+    const trafficChildren = [...this.#children.values()].filter((child) => child.role !== "batch");
+    if (trafficChildren.length === 0) return null;
+    if (!trafficChildren.every((child) => child.status === "crashed")) return null;
+    const detail =
+      trafficChildren.map((child) => child.lastErrorMessage ?? child.lastRestartReason).find(Boolean) ??
+      "unknown boot error";
+    const message = `Backend failed to start after ${AkanApp.#devMaxChildBootFailures} boot attempts: ${detail}`;
+    if (!req.headers.get("accept")?.includes("text/html")) {
+      return new Response(message, { status: 503, headers: { "cache-control": "no-store" } });
+    }
+    const html = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<title>Backend failed to start</title>
+<style>
+  body { margin: 0; padding: 48px 24px; background: #111827; color: #e5e7eb; font-family: ui-sans-serif, system-ui, sans-serif; }
+  main { max-width: 720px; margin: 0 auto; }
+  h1 { font-size: 20px; color: #f87171; }
+  pre { padding: 16px; border-radius: 8px; background: #1f2937; color: #fca5a5; white-space: pre-wrap; word-break: break-word; }
+  p { color: #9ca3af; font-size: 14px; }
+</style>
+</head>
+<body>
+<main>
+<h1>Backend failed to start</h1>
+<pre>${AkanApp.#escapeHtml(detail)}</pre>
+<p>The dev server stopped retrying after ${AkanApp.#devMaxChildBootFailures} failed boots. Fix the error and save &mdash; this page reloads automatically.</p>
+</main>
+<script>
+  const poll = async () => {
+    try {
+      const res = await fetch(location.href, { cache: "no-store" });
+      if (res.ok) { location.reload(); return; }
+    } catch {}
+    setTimeout(poll, 1000);
+  };
+  setTimeout(poll, 1000);
+</script>
+</body>
+</html>`;
+    return new Response(html, {
+      status: 503,
+      headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+    });
+  }
+
+  static #escapeHtml(text: string) {
+    const replacements: Record<string, string> = {
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;",
+    };
+    return text.replace(/[&<>"']/g, (ch) => replacements[ch] ?? ch);
+  }
+
   /**
    * Gateway-observed upstream round-trip time. The pure proxy overhead is this value
    * minus the child handler time captured in the per-request trace.

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0001.log

@@ -1,4 +0,0 @@
-[AkanApp] 39364 - 07/21/2026, 04:19:57 AM    INFO  AkanApp gateway is running on port http://localhost:32283 +499ms
-[AkanApp] 39364 - 07/21/2026, 04:19:57 AM VERBOSE  All 1 child process(es) are ready +512ms
-[AkanApp] 39364 - 07/21/2026, 04:19:57 AM   ERROR  Child 0/federation failed (exit:1); restarting in 1000ms (attempt 1) +565ms
-[AkanApp] 39364 - 07/21/2026, 04:19:58 AM VERBOSE  All 1 child process(es) are ready +1582ms

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0002.log

@@ -1,5 +0,0 @@
-[AkanApp] 39364 - 07/21/2026, 04:19:58 AM    INFO  AkanApp gateway is running on port http://localhost:30883 +1587ms
-[AkanApp] 39364 - 07/21/2026, 04:19:58 AM VERBOSE  All 1 child process(es) are ready +1599ms
-[AkanApp] 39364 - 07/21/2026, 04:19:58 AM   ERROR  Child 0/federation upstream is unreachable (/Users/kangminseon/github3/leading-flight-guidance/pkgs/akanjs/runtime/akan-child-39364-mru5abmz-0.sock); restarting +1740ms
-[AkanApp] 39364 - 07/21/2026, 04:19:58 AM   ERROR  Child 0/federation failed (upstream-open-failed); restarting in 1000ms (attempt 1) +1740ms
-[AkanApp] 39364 - 07/21/2026, 04:19:59 AM VERBOSE  All 1 child process(es) are ready +2760ms

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0003.log

@@ -1,7 +0,0 @@
-[AkanApp] 39364 - 07/21/2026, 04:19:59 AM    INFO  AkanApp gateway is running on port http://localhost:24583 +2773ms
-[AkanApp] 39364 - 07/21/2026, 04:19:59 AM   ERROR  intentional-boot-failure +2783ms
-[AkanApp] 39364 - 07/21/2026, 04:19:59 AM   ERROR  Child 0/federation failed (child-error); restarting in 1000ms (attempt 1) +2783ms
-[AkanApp] 39364 - 07/21/2026, 04:20:00 AM   ERROR  intentional-boot-failure +3799ms
-[AkanApp] 39364 - 07/21/2026, 04:20:00 AM   ERROR  Child 0/federation failed (child-error); restarting in 2000ms (attempt 2) +3799ms
-[AkanApp] 39364 - 07/21/2026, 04:20:02 AM   ERROR  intentional-boot-failure +5817ms
-[AkanApp] 39364 - 07/21/2026, 04:20:02 AM   ERROR  [child-crash-loop] Backend replica 0/federation failed 3 consecutive boots; waiting for a code change to retry: intentional-boot-failure +5817ms

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0004.log

@@ -1,2 +0,0 @@
-[AkanApp] 39364 - 07/21/2026, 04:20:03 AM    INFO  AkanApp gateway is running on port http://localhost:24132 +7360ms
-[AkanApp] 39364 - 07/21/2026, 04:20:03 AM VERBOSE  All 1 child process(es) are ready +7373ms