akanjs 3.0.0-alpha.67 → 3.0.0-alpha.68

package/constant/crystalize.ts

@@ -11,6 +11,50 @@ import type { FieldProps } from ".";
 
 export type CrystalizeFunc<Model> = (self: GetStateObject<Model>, isChild?: boolean) => Model;
 
+/**
+ * The relation instances one hydration pass has already built, by model class and then document id.
+ *
+ * A listing hands the same relation to every row that references it — twenty users wearing one avatar — and
+ * each row would otherwise build its own copy of it, re-parsing every `Date` on the way. Sharing is safe
+ * because a constant model is `[immerable]`: a store write copies before it mutates.
+ *
+ * Module-scoped rather than passed down, because `crystalize` is reached through a model's own constructor,
+ * which has nowhere to carry it. A pass is wholly synchronous, so no other one can observe this mid-flight.
+ */
+let sharedInstances: Map<Cls, Map<string, object>> | null = null;
+
+/** Runs one hydration pass, sharing a relation instance across every value in it that names the same id. */
+export const withSharedInstances = <T>(hydrate: () => T): T => {
+  if (sharedInstances) return hydrate();
+  sharedInstances = new Map();
+  try {
+    return hydrate();
+  } finally {
+    sharedInstances = null;
+  }
+};
+
+type ModelCls = Cls<{ set: (obj: object) => object }>;
+
+const relationIdOf = (value: object): string | null => {
+  const id = (value as { id?: unknown }).id;
+  return typeof id === "string" && id ? id : null;
+};
+
+const crystalizeModel = (field: FieldProps, value: object): object => {
+  const modelRef = field.modelRef as ModelCls;
+
+  if (value instanceof modelRef) return value;
+
+  const id = field.isScalar ? null : relationIdOf(value);
+  if (!sharedInstances || !id) return new modelRef().set(value);
+  const byId = sharedInstances.get(modelRef) ?? new Map<string, object>();
+  if (!sharedInstances.has(modelRef)) sharedInstances.set(modelRef, byId);
+  const shared = byId.get(id) ?? new modelRef().set(value);
+  byId.set(id, shared);
+  return shared;
+};
+
 export const crystalize = (field: FieldProps, value: unknown): unknown => {
   if (value === undefined || value === null) return value as undefined | null;
   if (field.isArray && Array.isArray(value))
@@ -41,7 +85,7 @@ export const crystalize = (field: FieldProps, value: unknown): unknown => {
       ]),
     );
   }
-  if (field.isClass) return new (field.modelRef as Cls<{ set: (obj: object) => object }>)().set(value as object);
+  if (field.isClass) return crystalizeModel(field, value as object);
   if (field.modelRef === Date) return dayjs(value as Date);
   return crystalizeValue(value);
 };

package/constant/deserialize.ts

@@ -1,6 +1,6 @@
 import { Any, applyFnToArrayObjects, type Cls, FIELD_META, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
 
-import { type ConstantCls, type ConstantModelRef, ConstantRegistry, type FieldProps } from ".";
+import { type ConstantCls, type ConstantModelRef, ConstantRegistry, type FieldProps, withSharedInstances } from ".";
 
 const getDeserializeFn = (inputRef: ConstantModelRef | PrimitiveScalar) => {
   const deserializeFn = PrimitiveRegistry.has(inputRef as Cls)
@@ -66,5 +66,6 @@ export const deserialize = (
   if (nullable && (value === null || value === undefined)) return null;
   else if (!nullable && (value === null || value === undefined) && argRef !== Any)
     throw new Error(`Invalid Value (Nullable) in ${key} ${argRef} for value ${value}`);
-  return deserializeInput(value, argRef, arrDepth, convertFn) as object[];
+
+  return withSharedInstances(() => deserializeInput(value, argRef, arrDepth, convertFn)) as object[];
 };

package/constant/types.ts

@@ -30,7 +30,11 @@ export type DocumentModel<T> = unknown extends T
         : Docify<T>;
 
 export type FieldState<T> = T extends { id: string } ? T | null : T;
-export type DefaultOf<S> = GetStateObject<{ [K in keyof S]: FieldState<S[K]> }>;
+export type DefaultOf<S> = {
+  [K in keyof S as S[K] extends (...args: never[]) => unknown ? never : K extends "prototype" ? never : K]: FieldState<
+    S[K]
+  >;
+};
 
 export type DefaultOfSchema<Schema, RelationKey = never> = [RelationKey] extends [never]
   ? Schema

package/fetch/client/fetchClient.ts

@@ -1,6 +1,13 @@
 import { DataList, getEnv, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
 import { capitalize, type FetchPolicy, fileUploadContract, Logger, resolveFileUploadCapability } from "akanjs/common";
-import { type BaseInsight, type BaseObject, ConstantRegistry, deserialize, serialize } from "akanjs/constant";
+import {
+  type BaseInsight,
+  type BaseObject,
+  ConstantRegistry,
+  deserialize,
+  serialize,
+  withSharedInstances,
+} from "akanjs/constant";
 import type {
   DatabaseSignal,
   SerializedArg,
@@ -646,7 +653,9 @@ export class FetchClient {
         listFn(...fetchQueryArgs, skip, limit, sort, { ...option, crystalize: false }),
         fetchInsight ? insightFn(...fetchQueryArgs, { ...option, crystalize: false }) : null,
       ])) as unknown as [BaseObject[], BaseInsight];
-      const modelList = new DataList(modelObjList.map((modelObj) => new cnst.light(modelObj)));
+      const modelList = new DataList(
+        withSharedInstances(() => modelObjList.map((modelObj) => new cnst.light(modelObj))),
+      );
       const modelInsight = new cnst.insight(modelObjInsight);
       const lastPage = modelObjInsight?.count
         ? Math.max(Math.floor((modelObjInsight.count - 1) / (limit || 20)) + 1, 1)

package/fetch/fetchType/appliedReturn.type.ts

@@ -25,33 +25,45 @@ export interface QuerySetting {
   queryArgs?: unknown[] | (() => unknown[]);
 }
 
-export type ServerInit<
+type ServerInitShape<
   RefName extends string,
-  Light,
-  Insight = any,
-  QueryArgs = any,
-  Filter extends FilterInstance = any,
-  _CapitalizedRefName extends string = Capitalize<RefName>,
-  _LightObj = GetStateObject<Light>,
-  _InsightObj = GetStateObject<Insight>,
-  _Sort = ExtractSort<Filter>,
+  QueryArgs,
+  CapRefName extends string,
+  LightObj,
+  InsightObj,
+  Sort,
 > = SliceMeta & {
-  [K in `${RefName}ObjList`]: _LightObj[];
+  [K in `${RefName}ObjList`]: LightObj[];
 } & {
-  [K in `${RefName}ObjInsight`]: _InsightObj;
+  [K in `${RefName}ObjInsight`]: InsightObj;
 } & {
-  [K in `pageOf${_CapitalizedRefName}`]: number;
+  [K in `pageOf${CapRefName}`]: number;
 } & {
-  [K in `lastPageOf${_CapitalizedRefName}`]: number;
+  [K in `lastPageOf${CapRefName}`]: number;
 } & {
-  [K in `limitOf${_CapitalizedRefName}`]: number;
+  [K in `limitOf${CapRefName}`]: number;
 } & {
-  [K in `queryArgsOf${_CapitalizedRefName}`]: QueryArgs;
+  [K in `queryArgsOf${CapRefName}`]: QueryArgs;
 } & {
-  [K in `sortOf${_CapitalizedRefName}`]: _Sort;
+  [K in `sortOf${CapRefName}`]: Sort;
 } & {
   [K in `${RefName}InitAt`]: Date;
 };
+
+export type ServerInit<
+  RefName extends string,
+  Light,
+  Insight = any,
+  QueryArgs = any,
+  Filter extends FilterInstance = any,
+> = ServerInitShape<
+  RefName,
+  QueryArgs,
+  Capitalize<RefName>,
+  GetStateObject<Light>,
+  GetStateObject<Insight>,
+  ExtractSort<Filter>
+>;
 /** Client/server-friendly return type for initialized list and insight data. */
 export type ClientInit<
   RefName extends string,
@@ -59,13 +71,7 @@ export type ClientInit<
   Insight = any,
   QueryArgs = any,
   Filter extends FilterInstance = any,
-  _CapitalizedRefName extends string = Capitalize<RefName>,
-  _LightObj = GetStateObject<Light>,
-  _InsightObj = GetStateObject<Insight>,
-  _Sort = ExtractSort<Filter>,
-> = PromiseOrObject<
-  ServerInit<RefName, Light, Insight, QueryArgs, Filter, _CapitalizedRefName, _LightObj, _InsightObj, _Sort>
->;
+> = PromiseOrObject<ServerInit<RefName, Light, Insight, QueryArgs, Filter>>;
 
 export type ServerView<RefName extends string, Model> = { refName: RefName } & {
   [K in `${RefName}Obj`]: GetStateObject<Model>;
@@ -94,6 +100,18 @@ export type EditReturn<RefName extends string, Full> = {
   [K in `${RefName}Edit`]: ServerEdit<RefName, Full>;
 };
 
+type InitReturnShape<
+  RefName extends string,
+  CapSuffix extends string,
+  Init,
+  ListItem extends { id: string },
+  Insight,
+> = {
+  [K in `${RefName}Init${CapSuffix}`]: Init;
+} & {
+  [K in `${RefName}List${CapSuffix}`]: DataList<ListItem>;
+} & { [K in `${RefName}Insight${CapSuffix}`]: Insight };
+
 export type InitReturn<
   RefName extends string,
   Suffix extends string,
@@ -101,25 +119,11 @@ export type InitReturn<
   Insight,
   Args,
   Filter extends FilterInstance,
-  _CapitalizedRefName extends string = Capitalize<RefName>,
-  _CapitalizedSuffix extends string = Capitalize<Suffix>,
-  _Light extends { id: string } = Light extends { id: string } ? Light : { id: string },
-  _LightObj = GetStateObject<_Light>,
-  _InsightObj = GetStateObject<Insight>,
-  _Sort = ExtractSort<Filter>,
-> = {
-  [K in `${RefName}Init${_CapitalizedSuffix}`]: ServerInit<
-    RefName,
-    Light,
-    Insight,
-    Args,
-    Filter,
-    _CapitalizedRefName,
-    _LightObj,
-    _InsightObj,
-    _Sort
-  >;
-} & {
-  [K in `${RefName}List${_CapitalizedSuffix}`]: DataList<_Light>;
-} & { [K in `${RefName}Insight${_CapitalizedSuffix}`]: Insight };
+> = InitReturnShape<
+  RefName,
+  Capitalize<Suffix>,
+  ServerInit<RefName, Light, Insight, Args, Filter>,
+  Light extends { id: string } ? Light : { id: string },
+  Insight
+>;
 

package/fetch/fetchType/endpointFetch.type.ts

@@ -33,9 +33,12 @@ type EndpointClientReturns<E, SlceCls extends SliceCls | never> = [SlceCls] exte
       SlceCnstInsight<SlceCls>
     >;
 
-type EndpInfoReturns<E, SlceCls extends SliceCls | never> =
-  | EndpointClientReturns<E, SlceCls>
-  | (EndpInfoNullable<E> extends true ? null : never);
+type OrNull<T, Nullable> = Nullable extends true ? T | null : T;
+
+type EndpInfoReturns<E, SlceCls extends SliceCls | never> = OrNull<
+  EndpointClientReturns<E, SlceCls>,
+  EndpInfoNullable<E>
+>;
 
 type QueryOrMutationFetchFn<E, SlceCls extends SliceCls | never> = (
   ...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]

package/fetch/fetchType/sliceFetch.type.ts

@@ -1,10 +1,9 @@
-import type { GetStateObject, SLICE_META } from "akanjs/base";
+import type { SLICE_META } from "akanjs/base";
 import type { FetchPolicy } from "akanjs/common";
 import type { ConstantModel, DefaultOf, ProtoFile, PurifiedModel } from "akanjs/constant";
 import type { DatabaseModel, ExtractSort, FilterInstance } from "akanjs/document";
 import type {
   SlceCnstCapitalizedRefName,
-  SlceCnstDefaultInput,
   SlceCnstFull,
   SlceCnstInput,
   SlceCnstInsight,
@@ -26,11 +25,9 @@ type _Full<S extends SliceCls> = SlceCnstFull<S>;
 type _Light<S extends SliceCls> = SlceCnstLight<S>;
 type _Insight<S extends SliceCls> = SlceCnstInsight<S>;
 type _PurifiedInput<S extends SliceCls> = SlceCnstPurifiedInput<S>;
-type _DefaultInput<S extends SliceCls> = SlceCnstDefaultInput<S>;
 type _Filter<S extends SliceCls> = SlceDbFilter<S>;
 type _Sort<S extends SliceCls> = SlceDbSort<S>;
-type _LightWithId<S extends SliceCls> = _Light<S> extends { id: string } ? _Light<S> : { id: string };
-type _SliceFetchInitOption<S extends SliceCls> = FetchInitOption<_Input<S>, _Filter<S>, _DefaultInput<S>, _Sort<S>>;
+type SliceInitOption<S extends SliceCls> = FetchInitOption<_Input<S>, _Filter<S>>;
 
 type SliceListFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `${_RefName<S>}List${Capitalize<Suffix>}` : never]: (
@@ -50,43 +47,33 @@ type SliceInsightFetch<S extends SliceCls> = {
   ) => Promise<_Insight<S>>;
 };
 
+type SliceInit<S extends SliceCls, Suffix extends keyof _SliceMap<S>> = InitReturn<
+  _RefName<S>,
+  Suffix & string,
+  _Light<S>,
+  _Insight<S>,
+  SliceInfoArgs<_SliceMap<S>[Suffix]>,
+  _Filter<S>
+>;
+
+type SliceServerInit<S extends SliceCls, Suffix extends keyof _SliceMap<S>> = ServerInit<
+  _RefName<S>,
+  _Light<S>,
+  _Insight<S>,
+  SliceInfoArgs<_SliceMap<S>[Suffix]>,
+  _Filter<S>
+>;
+
 type SliceInitFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `init${_Cap<S>}${Capitalize<Suffix>}` : never]: (
-    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: _SliceFetchInitOption<S>]
-  ) => Promise<
-    InitReturn<
-      _RefName<S>,
-      Suffix & string,
-      _Light<S>,
-      _Insight<S>,
-      SliceInfoArgs<_SliceMap<S>[Suffix]>,
-      _Filter<S>,
-      _Cap<S>,
-      Suffix extends string ? Capitalize<Suffix> : never,
-      _LightWithId<S>,
-      GetStateObject<_LightWithId<S>>,
-      GetStateObject<_Insight<S>>,
-      _Sort<S>
-    >
-  >;
+    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: SliceInitOption<S>]
+  ) => Promise<SliceInit<S, Suffix>>;
 };
 
 type SliceGetInitFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `get${_Cap<S>}Init${Capitalize<Suffix>}` : never]: (
-    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: _SliceFetchInitOption<S>]
-  ) => Promise<
-    ServerInit<
-      _RefName<S>,
-      _Light<S>,
-      _Insight<S>,
-      SliceInfoArgs<_SliceMap<S>[Suffix]>,
-      _Filter<S>,
-      _Cap<S>,
-      GetStateObject<_LightWithId<S>>,
-      GetStateObject<_Insight<S>>,
-      _Sort<S>
-    >
-  >;
+    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: SliceInitOption<S>]
+  ) => Promise<SliceServerInit<S, Suffix>>;
 };
 
 export type GetFetchTypeFromSlice<SlceCls extends SliceCls> = SlceCls["srv"]["cnst"] extends ConstantModel
@@ -164,23 +151,13 @@ type AppliedBaseSliceFetchType<
   ) => Promise<Full>;
 };
 
-export interface FetchInitForm<
-  Input,
-  Filter extends FilterInstance,
-  _DefaultInput = DefaultOf<Input>,
-  _Sort = ExtractSort<Filter>,
-> {
+export interface FetchInitForm<Input, Filter extends FilterInstance> {
   page?: number;
   limit?: number;
-  sort?: _Sort;
-  default?: Partial<_DefaultInput>;
+  sort?: ExtractSort<Filter>;
+  default?: Partial<DefaultOf<Input>>;
   invalidate?: boolean;
   insight?: boolean;
 }
 
-type FetchInitOption<
-  Input,
-  Filter extends FilterInstance,
-  _DefaultInput = DefaultOf<Input>,
-  _Sort = ExtractSort<Filter>,
-> = FetchPolicy & FetchInitForm<Input, Filter, _DefaultInput, _Sort>;
+type FetchInitOption<Input, Filter extends FilterInstance> = FetchPolicy & FetchInitForm<Input, Filter>;

package/index.ts

@@ -65,6 +65,27 @@ export interface AkanWebConfig {
  */
 export type AkanWebOption = boolean | { csr: boolean };
 
+/**
+ * How `akan build` trims the `public/` tree it copies into `dist`. Source trees are never touched: an app's
+ * and a lib's `public/` keep every file, and only the build's own copy is trimmed.
+ */
+export interface AkanAssetsConfig {
+  /**
+   * Drop font files from the build's `public/` that no built surface references. A font with `optimize` on is
+   * served from `/_akan/fonts` after subsetting, so its source is a build input the image never reads.
+   */
+  pruneFonts: boolean;
+  /**
+   * Font files to keep whatever the scan concludes, as globs relative to this app's or lib's own `public/`
+   * (`"fonts/Assistant-*.woff2"`). For the case a scan cannot see: a URL assembled at runtime. Declare it in
+   * the `akan.config.ts` that owns the font, so the reason travels with the lib rather than with the app.
+   */
+  keepFonts: string[];
+}
+
+/** A lib picks only which of its own fonts must survive; whether to prune at all belongs to the app. */
+export type LibAssetsConfig = Pick<AkanAssetsConfig, "keepFonts">;
+
 export type DatabaseMode = "single" | "multiple" | "cluster";
 export type MobileEnv = "local" | "debug" | "develop" | "main";
 export type MobilePermission = "camera" | "contacts" | "location" | "push" | "speech";
@@ -220,12 +241,16 @@ export interface AppConfigResult {
   publicEnv: string[];
   mobile: AkanMobileConfig;
   secrets: string[];
+  /** How the build trims the `public/` copy it ships. */
+  assets: AkanAssetsConfig;
 }
 
 export interface LibConfigResult {
   externalLibs: string[];
   /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
   docker: LibDockerConfig;
+  /** Which of this lib's own public fonts every app that mounts it must keep. */
+  assets: LibAssetsConfig;
 }
 
 export type DeepPartial<T> = {

package/package.json

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

package/server/akanApp.ts

@@ -8,6 +8,7 @@ import { isTraceEnabled } from "../signal/trace";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { resolveEncodedSidecar } from "./assetEncoding";
+import { compressResponse } from "./contentEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
@@ -107,6 +108,7 @@ export class AkanApp {
   /** Hosted by `akan start`: crash loops should yield to the dev host, which restarts on file edits. */
   readonly #devHosted = process.env.AKAN_COMMAND_TYPE === "start";
   readonly #healthTimeoutMs = AkanApp.#parseHealthTimeoutMs();
+  readonly #upstreamWaitMs = AkanApp.#parseUpstreamWaitMs();
   /** Child stderr is bundler/runtime noise the gateway cannot act on; it still reaches the rotating log file. */
   readonly #printChildStderr = process.env.AKAN_CHILD_STDERR === "1";
   readonly #serverPath: string;
@@ -230,6 +232,17 @@ export class AkanApp {
     return process.env.AKAN_COMMAND_TYPE === "start" ? 15_000 : 5_000;
   }
 
+  /**
+   * How long a request waits for a replica that is booting or restarting before the gateway answers
+   * 503. Dev pays first-touch transpiles on the boot path, so it gets the wider budget; `0` restores
+   * the old fail-immediately behavior.
+   */
+  static #parseUpstreamWaitMs() {
+    const configured = Number(process.env.AKAN_UPSTREAM_WAIT_MS);
+    if (Number.isFinite(configured) && configured >= 0) return configured;
+    return process.env.AKAN_COMMAND_TYPE === "start" ? 15_000 : 5_000;
+  }
+
   /**
    * Must exceed the child's own shutdown timeout (see `AkanServer.#defaultShutdownTimeoutMs`) so
    * children always get to exit on their own before this gateway stops waiting.
@@ -742,10 +755,8 @@ export class AkanApp {
   }
 
   async #proxyHttp(req: Request, server: Bun.Server<GatewayWsData>): Promise<Response> {
-    const child = this.#pickFederationChild();
-    if (!child?.upstream || child.upstream.type !== "unix") {
-      return this.#respondWithCrashPage(req) ?? new Response("No healthy federation child is ready", { status: 503 });
-    }
+    const child = await this.#pickReadyFederationChild(req);
+    if (!child?.upstream || child.upstream.type !== "unix") return this.#respondWithUnavailable(req);
     const url = new URL(req.url);
     const upstreamUrl = `http://akan-child${url.pathname}${url.search}`;
     const headers = this.#makeProxyHeaders(req, child.idx, server);
@@ -762,7 +773,7 @@ export class AkanApp {
         signal: req.signal,
         redirect: "manual",
       });
-      return this.#proxyResponse(upstreamRes);
+      return await this.#proxyResponse(req, upstreamRes);
     } catch (error) {
       if (AkanApp.#isUpstreamOpenFailure(error)) {
         this.logger.error(
@@ -785,26 +796,69 @@ export class AkanApp {
   }
 
   /**
-   * 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.
+   * 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
+   * upstream instead of failing at it. A dev crash loop is terminal, so it is answered immediately.
    */
-  #respondWithCrashPage(req: Request): Response | null {
+  async #pickReadyFederationChild(req: Request): Promise<ChildState | null> {
+    const ready = this.#pickFederationChild();
+    if (ready) return ready;
+    const deadline = performance.now() + this.#upstreamWaitMs;
+    while (performance.now() < deadline) {
+      if (this.#stopping || req.signal.aborted || this.#getCrashLoopDetail()) return null;
+      await Bun.sleep(50);
+      const child = this.#pickFederationChild();
+      if (child) return child;
+    }
+    return null;
+  }
+
+  /** Dev-only terminal state: every traffic replica gave up booting. The detail is the boot error. */
+  #getCrashLoopDetail(): string | 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 =
+    return (
       trafficChildren.map((child) => child.lastErrorMessage ?? child.lastRestartReason).find(Boolean) ??
-      "unknown boot error";
-    const message = `Backend failed to start after ${AkanApp.#devMaxChildBootFailures} boot attempts: ${detail}`;
+      "unknown boot error"
+    );
+  }
+
+  /**
+   * Both states answer 503, so an ingress or CDN reads them exactly as before; the HTML body is what
+   * a browser navigation needs, since nothing on a bare-text 503 can bring the page back on its own.
+   */
+  #respondWithUnavailable(req: Request): Response {
+    const crashDetail = this.#getCrashLoopDetail();
+    const page = crashDetail
+      ? {
+          heading: "Backend failed to start",
+          detail: crashDetail,
+          text: `Backend failed to start after ${AkanApp.#devMaxChildBootFailures} boot attempts: ${crashDetail}`,
+          note: `The dev server stopped retrying after ${AkanApp.#devMaxChildBootFailures} failed boots. Fix the error and save — this page reloads automatically.`,
+        }
+      : {
+          heading: "Backend is starting",
+          detail: "No healthy federation child is ready",
+          text: "No healthy federation child is ready",
+          note: "A replica is booting or restarting — this page reloads itself as soon as it answers.",
+        };
     if (!req.headers.get("accept")?.includes("text/html")) {
-      return new Response(message, { status: 503, headers: { "cache-control": "no-store" } });
+      return new Response(page.text, { status: 503, headers: { "cache-control": "no-store" } });
     }
-    const html = `<!doctype html>
+    return new Response(AkanApp.#statusPageHtml(page), {
+      status: 503,
+      headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+    });
+  }
+
+  static #statusPageHtml({ heading, detail, note }: { heading: string; detail: string; note: string }) {
+    return `<!doctype html>
 <html>
 <head>
 <meta charset="utf-8" />
-<title>Backend failed to start</title>
+<title>${AkanApp.#escapeHtml(heading)}</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; }
@@ -815,9 +869,9 @@ export class AkanApp {
 </head>
 <body>
 <main>
-<h1>Backend failed to start</h1>
+<h1>${AkanApp.#escapeHtml(heading)}</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>
+<p>${AkanApp.#escapeHtml(note)}</p>
 </main>
 <script>
   const poll = async () => {
@@ -831,10 +885,6 @@ export class AkanApp {
 </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) {
@@ -858,17 +908,23 @@ export class AkanApp {
     this.#proxyHopMaxMs = Math.max(this.#proxyHopMaxMs, durationMs);
   }
 
-  #proxyResponse(upstreamRes: Response): Response {
+  async #proxyResponse(req: Request, upstreamRes: Response): Promise<Response> {
     const headers = new Headers(upstreamRes.headers);
 
     headers.delete("content-encoding");
     headers.delete("content-length");
     this.#rewriteInternalLocation(headers);
-    return new Response(upstreamRes.body, {
+    const proxied = new Response(upstreamRes.body, {
       status: upstreamRes.status,
       statusText: upstreamRes.statusText,
       headers,
     });
+
+    return AkanApp.#isProxiedJson(headers) ? await compressResponse(req, proxied) : proxied;
+  }
+
+  static #isProxiedJson(headers: Headers): boolean {
+    return (headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase() === "application/json";
   }
 
   #rewriteInternalLocation(headers: Headers) {

package/server/akanAppHeaders.ts

@@ -34,6 +34,8 @@ export function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?:
     headers.get("x-forwarded-proto") ?? (req.url.startsWith("https:") ? "https" : "http"),
   );
   headers.set("x-akan-child-idx", String(childIdx));
+
+  headers.set("accept-encoding", "identity");
   if (!headers.has("x-request-id") && process.env.AKAN_BENCH_SKIP_REQUEST_ID !== "1") {
     headers.set("x-request-id", crypto.randomUUID());
   }