akanjs 2.0.6 → 2.1.0-rc.0

package/README.ko.md

@@ -1,6 +1,6 @@
 # Akan.js
 
-[English](./README.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
+[English](https://unpkg.com/akanjs@latest/README.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
 
 **코드가 아니라, 비즈니스를 씁니다.**  
 **Write the business, not the plumbing.**
@@ -50,7 +50,7 @@ akan start <app-name> --open
 가장 작은 앱은 설정이 거의 없어도 시작할 수 있습니다.
 
 ```ts
-import type { AppConfig } from "akanjs/devkit";
+import type { AppConfig } from "akanjs";
 
 const config: AppConfig = {};
 
@@ -161,9 +161,9 @@ UI barrel import를 leaf import로 다시 써서 클라이언트 번들을 작
 | `akanjs/client` | client routing, cookie, storage, locale, device, CSR type, page helper. |
 | `akanjs/client` | Akan page runtime에서 사용하는 client bootstrap과 location helper. |
 | `akanjs/server` | server app runtime, route composition, SSR/RSC artifact, proxy, sitemap, server type. |
-| `akanjs/devkit` | build runner, config loader, code generation, scanner, transform, CLI helper, tooling. |
+| `@akanjs/devkit` | build runner, config loader, code generation, scanner, transform, CLI helper, tooling. |
 | `akanjs/test` | test helper와 sample generation utility. |
-| `akanjs/cli` | programmatic CLI entrypoint. 실행 명령은 `akan`입니다. |
+| `@akanjs/cli` | programmatic CLI entrypoint. 실행 명령은 `akan`입니다. |
 
 특수 public surface:
 
@@ -202,7 +202,7 @@ akan update
 routes, domains, base paths, mobile settings로 확장됩니다.
 
 ```ts
-import type { AppConfig } from "akanjs/devkit";
+import type { AppConfig } from "akanjs";
 
 const config: AppConfig = {
   routes: [

package/README.md

@@ -1,6 +1,6 @@
 # Akan.js
 
-[한국어](./README.ko.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
+[한국어](https://unpkg.com/akanjs@latest/README.ko.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
 
 **Write the business, not the plumbing.**
 
@@ -49,7 +49,7 @@ akan start <app-name> --open
 A minimal app can start with almost no configuration:
 
 ```ts
-import type { AppConfig } from "akanjs/devkit";
+import type { AppConfig } from "akanjs";
 
 const config: AppConfig = {};
 
@@ -159,9 +159,9 @@ frontend build to rewrite UI barrel imports into leaf imports.
 | `akanjs/client` | Client routing, cookies, storage, locale, device, CSR types, and page helpers. |
 | `akanjs/client` | Client bootstrapping and location helpers used by Akan page runtimes. |
 | `akanjs/server` | Server app runtime, route composition, SSR/RSC artifacts, proxying, sitemap, and server types. |
-| `akanjs/devkit` | Build runners, config loaders, code generation, scanners, transforms, CLI helpers, and tooling. |
+| `@akanjs/devkit` | Build runners, config loaders, code generation, scanners, transforms, CLI helpers, and tooling. |
 | `akanjs/test` | Test helpers and sample generation utilities. |
-| `akanjs/cli` | Programmatic CLI entrypoint. The executable command is `akan`. |
+| `@akanjs/cli` | Programmatic CLI entrypoint. The executable command is `akan`. |
 
 Special public surfaces:
 
@@ -200,7 +200,7 @@ Common areas:
 grow only when the app needs routes, domains, base paths, or mobile settings.
 
 ```ts
-import type { AppConfig } from "akanjs/devkit";
+import type { AppConfig } from "akanjs";
 
 const config: AppConfig = {
   routes: [

package/client/router.ts

@@ -62,6 +62,8 @@ function getServerRequestContext() {
 
 const getConfiguredBasePaths = () => new Set(parseBasePaths(process.env.AKAN_PUBLIC_BASE_PATHS));
 
+const shouldExposeBasePath = () => getEnv().operationMode === "local";
+
 const getServerBasePath = (reqPathname: string, lang: string, headerBasePath: string | undefined, fallback: string) => {
   return (
     getBasePathFromPathname(reqPathname, {
@@ -131,14 +133,16 @@ class Router {
       push: (href: string, routeOptions) => {
         const router = options.router;
         const pathInfo = this.#getPathInfo(href);
+        const navigationPathInfo = this.#getNavigationPathInfo(href);
         this.#postPathChange(pathInfo);
-        router.push(pathInfo.href, routeOptions);
+        router.push(navigationPathInfo.href, routeOptions);
       },
       replace: (href: string, routeOptions) => {
         const router = options.router;
         const pathInfo = this.#getPathInfo(href);
+        const navigationPathInfo = this.#getNavigationPathInfo(href);
         this.#postPathChange(pathInfo);
-        router.replace(pathInfo.href, routeOptions);
+        router.replace(navigationPathInfo.href, routeOptions);
       },
       back: () => {
         const router = options.router;
@@ -188,6 +192,9 @@ class Router {
   #getPathInfo(href: string, prefix = this.#prefix) {
     return getPathInfo(href, this.#lang, prefix);
   }
+  #getNavigationPathInfo(href: string) {
+    return this.#getPathInfo(href, shouldExposeBasePath() ? this.#prefix : "");
+  }
   #postPathChange({ path, pathname, hash }: { path: string; pathname: string; hash: string }) {
     Logger.log(`pathChange-start:${path}${hash ? `#${hash}` : ""}`);
     window.parent.postMessage({ type: "pathChange", path, pathname, hash }, "*");
@@ -224,7 +231,7 @@ class Router {
       const langFromPath = reqPathname.split("/").filter(Boolean)[0];
       const lang = (h.get("x-locale") ?? langFromPath ?? this.#lang) as string;
       const basePath = getServerBasePath(reqPathname, lang, h.get("x-base-path") ?? undefined, this.#prefix);
-      const { pathname, href: fullHref } = getPathInfo(href, lang, basePath);
+      const { pathname, href: fullHref } = getPathInfo(href, lang, shouldExposeBasePath() ? basePath : "");
       Logger.log(`redirect to:${pathname}`);
       throw new AkanRedirectError(fullHref, "replace");
     } else {

package/constant/serialize.ts

@@ -53,7 +53,7 @@ const serializeInput = <Input = unknown>(
     return Object.fromEntries(
       Object.entries(modelRef[FIELD_META]).map(([key, field]) => [
         key,
-        field.isClass && !field.isScalar
+        serializeType === "input" && field.isClass && !field.isScalar
           ? serialize(ID, field.arrDepth, getRelationId((value as Record<string, unknown>)?.[key]), serializeType, {
               nullable: field.nullable,
               key,

package/document/documentSchema.ts

@@ -13,6 +13,14 @@ export interface DocumentIndexDescriptor {
   where?: DocumentQuery;
 }
 
+export interface DocumentIndexBuilder<Schema> {
+  path(path: string, order?: 1 | -1): DocumentIndexBuilder<Schema>;
+  text(path: string): DocumentIndexBuilder<Schema>;
+  unique(): DocumentIndexBuilder<Schema>;
+  where(where: DocumentQuery | ((q: DocumentQueryHelper) => DocumentQuery)): DocumentIndexBuilder<Schema>;
+  done(): Schema;
+}
+
 export type DocumentSaveHook<Doc = unknown> = (
   this: Doc,
   next?: () => void,
@@ -58,7 +66,7 @@ export class DocumentSchema<Doc = unknown> {
     return this;
   }
 
-  createIndex(name: string) {
+  createIndex(name: string): DocumentIndexBuilder<this> {
     const schema = this;
     const descriptor: DocumentIndexDescriptor = { name, fields: {} };
     const api = {

package/index.ts

@@ -0,0 +1,187 @@
+import type { AkanI18nConfig } from "akanjs/common";
+import type { AkanImageConfig } from "akanjs/server";
+
+export const archs = ["amd64", "arm64"] as const;
+export type Arch = (typeof archs)[number];
+
+export interface DockerConfig {
+  content: string;
+  image: string | { [key in Arch]?: string };
+  preRuns: (string | { [key in Arch]?: string })[];
+  postRuns: (string | { [key in Arch]?: string })[];
+  command: string[];
+}
+
+export interface AkanRouteDomains {
+  main?: string[];
+  develop?: string[];
+  debug?: string[];
+  [branch: string]: string[] | undefined;
+}
+
+export interface AkanRouteConfig {
+  basePath?: string;
+  domains: AkanRouteDomains;
+}
+
+export type DatabaseMode = "single" | "multiple" | "cluster";
+export type MobileEnv = "local" | "debug" | "develop" | "main";
+export type MobilePermission = "camera" | "contacts" | "location" | "push";
+
+export interface AkanMobileTargetAssets {
+  icon?: string;
+  splash?: string;
+}
+
+export interface AkanMobileTargetLinks {
+  schemes?: string[];
+  associatedDomains?: string[];
+  androidHosts?: string[];
+}
+
+export interface AkanMobileTargetFiles {
+  ios?: Record<string, string>;
+  android?: Record<string, string>;
+}
+
+export interface AkanCapacitorLikeConfig {
+  plugins?: Record<string, unknown>;
+  android?: Record<string, unknown>;
+  ios?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface AkanMobileTargetConfig extends AkanCapacitorLikeConfig {
+  name: string;
+  basePath?: string;
+  appName: string;
+  appId: string;
+  version: string;
+  buildNum: number;
+  assets?: AkanMobileTargetAssets;
+  permissions?: MobilePermission[];
+  links?: AkanMobileTargetLinks;
+  files?: AkanMobileTargetFiles;
+}
+
+export interface AkanMobileConfig extends AkanCapacitorLikeConfig {
+  appName: string;
+  appId: string;
+  version: string;
+  buildNum: number;
+  targets: Record<string, AkanMobileTargetConfig>;
+}
+
+export interface AppConfigResult {
+  docker: DockerConfig;
+  defaultDatabaseMode: DatabaseMode;
+  routes?: AkanRouteConfig[];
+  externalLibs: string[];
+  barrelImports: string[];
+  optimizeImports: string[];
+  images: AkanImageConfig;
+  i18n: AkanI18nConfig;
+  publicEnv: string[];
+  mobile: AkanMobileConfig;
+}
+
+export interface LibConfigResult {
+  externalLibs: string[];
+}
+
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends unknown[] ? T[P] : T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+export interface AppConfigContext {
+  readonly name: string;
+  readonly type: "app";
+}
+
+export interface LibConfigContext {
+  readonly name: string;
+  readonly type: "lib";
+}
+
+export type AppConfig = DeepPartial<AppConfigResult> | ((app: AppConfigContext) => DeepPartial<AppConfigResult>);
+export type LibConfig = DeepPartial<LibConfigResult> | ((lib: LibConfigContext) => DeepPartial<LibConfigResult>);
+export type AkanConfigFile = object;
+
+export interface FileConventionScanResult {
+  constant: { databases: string[]; scalars: string[] };
+  dictionary: { databases: string[]; services: string[]; scalars: string[] };
+  document: { databases: string[]; scalars: string[] };
+  service: { databases: string[]; services: string[] };
+  signal: { databases: string[]; services: string[] };
+  store: { databases: string[]; services: string[] };
+  template: { databases: string[]; services: string[]; scalars: string[] };
+  unit: { databases: string[]; services: string[]; scalars: string[] };
+  util: { databases: string[]; services: string[]; scalars: string[] };
+  view: { databases: string[]; services: string[]; scalars: string[] };
+  zone: { databases: string[]; services: string[]; scalars: string[] };
+}
+
+export interface ScanResult {
+  name: string;
+  type: "app" | "lib";
+  repoName: string;
+  serveDomain: string;
+  files: FileConventionScanResult;
+  libDeps: string[];
+  pkgDeps: string[];
+  dependencies: string[];
+  devDependencies: string[];
+}
+
+export interface AppScanResult extends ScanResult {
+  akanConfig: AppConfigResult;
+  routes: string[];
+}
+
+export interface LibScanResult extends ScanResult {
+  akanConfig: LibConfigResult;
+}
+
+export interface PkgScanResult {
+  name: string;
+  pkgDeps: string[];
+  dependencies: string[];
+}
+
+export interface WorkspaceScanResult {
+  appNames: string[];
+  libNames: string[];
+  pkgNames: string[];
+  apps: { [key: string]: AppScanResult };
+  libs: { [key: string]: LibScanResult };
+  pkgs: { [key: string]: PkgScanResult };
+}
+
+export interface AppInfo {
+  readonly name: string;
+  readonly type: "app";
+  readonly database: Map<string, Set<string>>;
+  readonly service: Map<string, Set<string>>;
+  readonly scalar: Map<string, Set<string>>;
+  readonly file: FileConventionScanResult;
+  getLibs(): string[];
+  getLibInfos(): Map<string, LibInfo>;
+  getDatabaseModules(): string[];
+  getScalarModules(): string[];
+  getServiceModules(): string[];
+}
+
+export interface LibInfo {
+  readonly name: string;
+  readonly type: "lib";
+  readonly database: Map<string, Set<string>>;
+  readonly service: Map<string, Set<string>>;
+  readonly scalar: Map<string, Set<string>>;
+  readonly file: FileConventionScanResult;
+  getLibs(): string[];
+  getLibInfos(): Map<string, LibInfo>;
+  getLibInfo(libName: string): LibInfo | undefined;
+  getDatabaseModules(): string[];
+  getScalarModules(): string[];
+  getServiceModules(): string[];
+}

package/package.json

@@ -1,12 +1,8 @@
 {
   "name": "akanjs",
-  "version": "2.0.6",
+  "version": "2.1.0-rc.0",
   "sourceType": "module",
   "type": "module",
-  "bin": {
-    "akan": "./cli/index.js",
-    "akan2": "./cli/index.js"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -24,11 +20,6 @@
       "default": "./index.ts"
     },
     "./package.json": "./package.json",
-    "./capacitor.base.config": {
-      "types": "./types/devkit/capacitor.base.config.d.ts",
-      "import": "./devkit/capacitor.base.config.ts",
-      "default": "./devkit/capacitor.base.config.ts"
-    },
     "./base": {
       "types": "./types/base/index.d.ts",
       "import": "./base/index.ts",
@@ -139,21 +130,11 @@
       "import": "./dictionary/index.ts",
       "default": "./dictionary/index.ts"
     },
-    "./devkit": {
-      "types": "./types/devkit/index.d.ts",
-      "import": "./devkit/index.ts",
-      "default": "./devkit/index.ts"
-    },
     "./test": {
       "types": "./types/test/index.d.ts",
       "import": "./test/index.ts",
       "default": "./test/index.ts"
     },
-    "./cli": {
-      "types": "./types/cli/index.d.ts",
-      "import": "./cli/index.ts",
-      "default": "./cli/index.ts"
-    },
     "./ui/styles.css": "./ui/styles.css",
     "./server/rsc-worker": {
       "types": "./types/server/rscWorker.d.ts",
@@ -162,27 +143,10 @@
     }
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.4.3",
-    "@langchain/core": "^1.1.47",
-    "@langchain/deepseek": "^1.0.26",
-    "@langchain/openai": "^1.4.6",
-    "@trapezedev/project": "^7.1.4",
-    "chalk": "^5.6.2",
     "clsx": "^2.1.1",
-    "commander": "^14.0.3",
     "dayjs": "^1.11.20",
-    "fontaine": "^0.8.0",
-    "fonteditor-core": "^2.6.3",
-    "ignore": "^7.0.5",
     "immer": "^11.1.8",
-    "ink": "^6.8.0",
-    "js-yaml": "^4.1.1",
-    "ora": "^9.4.0",
-    "qrcode": "^1.5.4",
-    "sharp": "^0.34.5",
-    "ssh2": "^1.17.0",
-    "subset-font": "^2.5.0",
-    "tailwindcss": "^4.3.0"
+    "sharp": "^0.34.5"
   },
   "peerDependencies": {
     "@capacitor-community/contacts": "^7.2.0",
@@ -190,7 +154,6 @@
     "@capacitor/app": "^8.1.0",
     "@capacitor/browser": "^8.0.3",
     "@capacitor/camera": "^8.2.0",
-    "@capacitor/cli": "^8.3.4",
     "@capacitor/core": "^8.3.4",
     "@capacitor/device": "^8.0.2",
     "@capacitor/geolocation": "^8.2.0",
@@ -202,7 +165,7 @@
     "@libsql/client": "^0.17.3",
     "@playwright/test": "^1.60.0",
     "@radix-ui/react-dialog": "^1.1.15",
-    "@react-spring/web": "^9.7.5",
+    "@react-spring/web": "^10.1.0",
     "@use-gesture/react": "^10.3.1",
     "bullmq": "^5.76.10",
     "capacitor-plugin-safe-area": "^5.0.0",
@@ -211,27 +174,23 @@
     "croner": "^10.0.1",
     "daisyui": "^5.5.20",
     "file-saver": "^2.0.5",
-    "fontaine": "^0.8.0",
-    "fonteditor-core": "^2.6.3",
     "ioredis": "^5.10.1",
     "mermaid": "^11.15.0",
     "postgres": "^3.4.9",
     "protobufjs": "^8.4.0",
-    "react": "19.2.4",
+    "react": "19.2.6",
     "react-copy-to-clipboard": "^5.1.1",
     "react-datepicker": "^9.1.0",
     "react-device-detect": "^2.2.3",
-    "react-dom": "19.2.4",
+    "react-dom": "19.2.6",
     "react-icons": "^5.6.0",
     "react-refresh": "^0.18.0",
     "react-server-dom-webpack": "^19.2.6",
     "react-simple-pull-to-refresh": "^1.3.4",
-    "react-spring": "^9.7.5",
+    "react-spring": "^10.0.4",
     "scheduler": "^0.27.0",
     "sharp": "^0.34.5",
-    "subset-font": "^2.5.0",
     "tailwind-scrollbar": "^4.0.2",
-    "tailwindcss": "^4.3.0",
     "typescript": "^6.0.3"
   },
   "peerDependenciesMeta": {
@@ -250,9 +209,6 @@
     "@capacitor/camera": {
       "optional": true
     },
-    "@capacitor/cli": {
-      "optional": true
-    },
     "@capacitor/core": {
       "optional": true
     },

package/server/akanApp.ts

@@ -2,6 +2,8 @@ import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
+import { isTraceEnabled } from "akanjs/signal";
+import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
@@ -59,16 +61,6 @@ export class AkanApp {
   static readonly #childRestartBaseDelayMs = 1_000;
   static readonly #childRestartMaxDelayMs = 30_000;
   static readonly #childRestartGraceMs = 5_000;
-  static readonly #hopByHopHeaders = new Set([
-    "connection",
-    "keep-alive",
-    "proxy-authenticate",
-    "proxy-authorization",
-    "te",
-    "trailer",
-    "transfer-encoding",
-    "upgrade",
-  ]);
 
   readonly logger = new Logger("AkanApp");
   readonly #serverPath: string;
@@ -85,6 +77,7 @@ export class AkanApp {
   readonly #builderReqMap = new Map<number, { childIdx: number; childLocalId: number }>();
   #server: Bun.Server<GatewayWsData> | null = null;
   #rrIdx = 0;
+  #federationChildCache: ChildState[] | null = null;
   #snapshotTimer: Timer | null = null;
   #healthTimer: Timer | null = null;
   #metricsTimer: Timer | null = null;
@@ -93,6 +86,9 @@ export class AkanApp {
   readonly #childOutputBuffers = new Map<string, string>();
   static readonly #ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
   #gatewayMetrics: AkanMetricsReport = {};
+  #proxyHopCount = 0;
+  #proxyHopSumMs = 0;
+  #proxyHopMaxMs = 0;
   #resolveStopped: (() => void) | null = null;
   #exitAfterStop = false;
   #stopping = false;
@@ -248,6 +244,7 @@ export class AkanApp {
       lastRestartAt: previous?.lastRestartAt,
       lastRestartReason: previous?.lastRestartReason,
     });
+    this.#invalidateFederationChildCache();
     this.#pipeOutput(idx, role, proc.stdout, "stdout");
     this.#pipeOutput(idx, role, proc.stderr, "stderr");
     proc.exited.then((code) => this.#handleChildExit(idx, proc, code));
@@ -258,6 +255,7 @@ export class AkanApp {
     if (!child || child.proc !== proc) return;
     child.status = "exited";
     child.lastExitCode = code;
+    this.#invalidateFederationChildCache();
     this.#removeChildRooms(idx);
     if (this.#stopping) return;
     void this.#scheduleChildRestart(child, proc, `exit:${code ?? "unknown"}`);
@@ -276,6 +274,7 @@ export class AkanApp {
     child.status = reason === "health-timeout" ? "unhealthy" : "exited";
     child.upstream = undefined;
     child.healthPath = undefined;
+    this.#invalidateFederationChildCache();
     child.lastRestartReason = reason;
     child.lastRestartAt = Date.now();
     this.#removeChildRooms(child.idx);
@@ -403,6 +402,7 @@ export class AkanApp {
     const url = new URL(req.url);
     if (url.pathname === "/_akan/app/health") return Response.json(this.#getHealthStatus());
     if (url.pathname === "/_akan/app/metrics") return Response.json(this.#getMetricsStatus());
+    if (url.pathname === "/_akan/bench/ping") return new Response("ok");
     if (this.#isWebSocketPath(url.pathname)) return this.#upgradeWebSocket(req, server);
     const assetResponse = await this.#serveImmutableArtifact(req, url);
     if (assetResponse) return assetResponse;
@@ -526,6 +526,13 @@ export class AkanApp {
       rooms: this.#roomChildren.size,
       sockets: this.#socketRooms.size,
       gateway: this.#gatewayMetrics,
+      proxyHop: this.#proxyHopCount
+        ? {
+            count: this.#proxyHopCount,
+            meanMs: Math.round((this.#proxyHopSumMs / this.#proxyHopCount) * 1000) / 1000,
+            maxMs: Math.round(this.#proxyHopMaxMs * 1000) / 1000,
+          }
+        : null,
       children: [...this.#children.values()].map((child) => ({
         idx: child.idx,
         role: child.role,
@@ -551,6 +558,8 @@ export class AkanApp {
     const headers = this.#makeProxyHeaders(req, child.idx);
     child.metrics.activeRequests = (child.metrics.activeRequests ?? 0) + 1;
     child.metrics.totalRequests = (child.metrics.totalRequests ?? 0) + 1;
+    const traced = isTraceEnabled();
+    const hopStart = traced ? performance.now() : 0;
     try {
       const upstreamRes = await fetch(upstreamUrl, {
         unix: child.upstream.socketPath,
@@ -563,9 +572,20 @@ export class AkanApp {
       return this.#proxyResponse(upstreamRes);
     } finally {
       child.metrics.activeRequests = Math.max(0, (child.metrics.activeRequests ?? 1) - 1);
+      if (traced) this.#recordProxyHop(performance.now() - hopStart);
     }
   }
 
+  /**
+   * Gateway-observed upstream round-trip time. The pure proxy overhead is this value
+   * minus the child handler time captured in the per-request trace.
+   */
+  #recordProxyHop(durationMs: number) {
+    this.#proxyHopCount += 1;
+    this.#proxyHopSumMs += durationMs;
+    this.#proxyHopMaxMs = Math.max(this.#proxyHopMaxMs, durationMs);
+  }
+
   #proxyResponse(upstreamRes: Response): Response {
     const headers = new Headers(upstreamRes.headers);
 
@@ -650,29 +670,25 @@ export class AkanApp {
   }
 
   #makeProxyHeaders(req: Request, childIdx: number) {
-    const headers = new Headers(req.headers);
-    for (const key of AkanApp.#hopByHopHeaders) headers.delete(key);
-    const url = new URL(req.url);
-    const forwardedFor = headers.get("x-forwarded-for");
-    const clientAddress = headers.get("x-real-ip") ?? "127.0.0.1";
-    headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientAddress}` : clientAddress);
-    headers.set("x-forwarded-host", headers.get("host") ?? url.host);
-    headers.set("x-forwarded-proto", url.protocol.replace(":", ""));
-    headers.set("x-akan-child-idx", String(childIdx));
-    headers.set("x-request-id", headers.get("x-request-id") ?? crypto.randomUUID());
-    headers.set("host", "akan-child");
-    return headers;
+    return makeAkanChildProxyHeaders(req, childIdx);
+  }
+
+  #invalidateFederationChildCache() {
+    this.#federationChildCache = null;
   }
 
   #pickFederationChild() {
-    const candidates = [...this.#children.values()].filter(
-      (child) =>
-        (child.role === "federation" || child.role === "all") &&
-        child.ready &&
-        child.status !== "unhealthy" &&
-        child.status !== "exited" &&
-        !child.proc.killed,
-    );
+    const candidates =
+      this.#federationChildCache ??
+      [...this.#children.values()].filter(
+        (child) =>
+          (child.role === "federation" || child.role === "all") &&
+          child.ready &&
+          child.status !== "unhealthy" &&
+          child.status !== "exited" &&
+          !child.proc.killed,
+      );
+    this.#federationChildCache = candidates;
     if (candidates.length === 0) return null;
     const child = candidates[this.#rrIdx % candidates.length];
     this.#rrIdx++;
@@ -761,6 +777,7 @@ export class AkanApp {
     child.lastPongAt = Date.now();
     child.restartAttempts = 0;
     child.restartPending = false;
+    this.#invalidateFederationChildCache();
     if ([...this.#children.values()].every((item) => item.ready)) {
       process.send?.({ type: "backend-ready", pid: process.pid } satisfies AkanIpcMessage);
       this.logger.verbose(`All ${this.#children.size} child process(es) are ready`);
@@ -772,6 +789,7 @@ export class AkanApp {
     if (!child) return;
     child.status = "healthy";
     child.lastPongAt = Date.now();
+    this.#invalidateFederationChildCache();
   }
 
   #deliverPubsub(originIdx: number, message: Extract<AkanIpcMessage, { type: "pubsub.publish" }>) {
@@ -903,6 +921,7 @@ export class AkanApp {
       if (child.proc.killed || child.status === "exited") continue;
       if (child.lastPongAt && now - child.lastPongAt > 5_000) {
         child.status = "unhealthy";
+        this.#invalidateFederationChildCache();
         void this.#scheduleChildRestart(child, child.proc, "health-timeout");
         return;
       }