akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/common/CodeTranscript.ts

@@ -0,0 +1,325 @@
+import type {
+  CodeAgentApprovalRequest,
+  CodeAgentEvent,
+  CodeAgentQuestion,
+  CodeAgentSessionInfo,
+  CodeAgentStopReason,
+  CodeAgentSubagent,
+  CodeAgentToolOutcome,
+  CodeAgentToolSummary,
+} from "akanjs/common";
+
+export type CodeTranscriptPart =
+  | { kind: "user"; id: string; text: string; images?: number }
+  | { kind: "assistant"; id: string; text: string; streaming: boolean; truncated: boolean }
+  | { kind: "thinking"; id: string; text: string }
+  | {
+      kind: "tool";
+      id: string;
+      tool: CodeAgentToolSummary;
+      outcome?: CodeAgentToolOutcome;
+      output?: string;
+      progress?: string;
+    }
+  | { kind: "notice"; id: string; level: "info" | "warning" | "error"; text: string }
+  | { kind: "question"; id: string; question: CodeAgentQuestion; rendered?: string }
+  | { kind: "approval"; id: string; request: CodeAgentApprovalRequest; approved?: boolean }
+  | { kind: "host"; id: string; hostKind: string; text: string };
+
+export class CodeTranscript {
+  readonly #parts: CodeTranscriptPart[] = [];
+  readonly #indexById = new Map<string, number>();
+  #info: CodeAgentSessionInfo | undefined;
+  #context: { used: number; max: number | undefined } | undefined;
+  #streaming = false;
+  #compacting = false;
+  #question: CodeAgentQuestion | undefined;
+  #approval: CodeAgentApprovalRequest | undefined;
+  #stopReason: CodeAgentStopReason | undefined;
+  #queue = { steering: 0, followUp: 0 };
+  #subagents: CodeAgentSubagent[] = [];
+  #openAssistant: string | undefined;
+  #openThinking: string | undefined;
+  #nextId = 0;
+  #revision = 0;
+
+  get parts(): readonly CodeTranscriptPart[] {
+    return this.#parts;
+  }
+
+  get info() {
+    return this.#info;
+  }
+
+  get headline() {
+    if (!this.#info) return "starting…";
+    return [
+      this.#info.model?.name ?? "no model",
+      this.#info.contextTokens ? `${Math.round(this.#info.contextTokens / 1000)}k ctx` : "unknown ctx",
+      this.#info.profile,
+      this.#info.sessionId.slice(0, 8),
+    ].join(" · ");
+  }
+
+  get context() {
+    return this.#context;
+  }
+
+  get streaming() {
+    return this.#streaming;
+  }
+
+  get compacting() {
+    return this.#compacting;
+  }
+
+  get question() {
+    return this.#question;
+  }
+
+  get approval() {
+    return this.#approval;
+  }
+
+  get stopReason() {
+    return this.#stopReason;
+  }
+
+  get queue() {
+    return this.#queue;
+  }
+
+  get subagents() {
+    return this.#subagents;
+  }
+
+  /** Bumped on every applied event. */
+  get revision() {
+    return this.#revision;
+  }
+
+  /** Drops every row but keeps the session info; the model's own window is untouched. */
+  clear() {
+    this.#revision += 1;
+    this.#parts.length = 0;
+    this.#indexById.clear();
+    this.#openAssistant = undefined;
+    this.#openThinking = undefined;
+  }
+
+  /** A locally typed prompt, drawn before the engine echoes it back as a `message` matched by text. */
+  echo(text: string, images = 0) {
+    this.#revision += 1;
+    this.#push({ kind: "user", id: this.#id(), text, ...(images ? { images } : {}) });
+  }
+
+  note(level: "info" | "warning" | "error", text: string) {
+    this.#revision += 1;
+    this.#notice(level, text);
+  }
+
+  apply(event: CodeAgentEvent) {
+    this.#revision += 1;
+    switch (event.type) {
+      case "session":
+        this.#info = event.info;
+        return;
+      case "turn_start":
+        this.#streaming = true;
+        this.#stopReason = undefined;
+        return;
+      case "turn_end":
+        this.#streaming = false;
+        this.#stopReason = event.stopReason;
+        this.#closeStreams(event.stopReason === "truncated");
+        return;
+      case "text_delta":
+        return this.#appendAssistant(event.text);
+      case "thinking_delta":
+        return this.#appendThinking(event.text);
+      case "message":
+        return this.#message(event.role, event.text);
+      case "tool_start":
+        
+        this.#closeStreams(false);
+        return this.#upsertTool(event.tool, {});
+      case "tool_progress":
+        return this.#progress(event.toolCallId, event.text);
+      case "tool_end":
+        return this.#upsertTool(event.tool, { outcome: event.outcome, output: event.output });
+      case "question":
+        this.#question = event.question;
+        return this.#push({ kind: "question", id: event.question.questionId, question: event.question });
+      case "question_skipped":
+        return this.#push({
+          kind: "question",
+          id: event.question.questionId,
+          question: event.question,
+          rendered: `(${event.reason})`,
+        });
+      case "question_resolved":
+        if (this.#question?.questionId === event.questionId) this.#question = undefined;
+        return this.#patch(event.questionId, (part) => {
+          if (part.kind === "question") part.rendered = event.rendered;
+        });
+      case "approval":
+        this.#approval = event.request;
+        return this.#push({ kind: "approval", id: event.request.approvalId, request: event.request });
+      case "approval_resolved":
+        if (this.#approval?.approvalId === event.approvalId) this.#approval = undefined;
+        return this.#patch(event.approvalId, (part) => {
+          if (part.kind === "approval") part.approved = event.approved;
+        });
+      case "context":
+        this.#context = { used: event.used, max: event.max };
+        return;
+      case "compaction":
+        this.#compacting = event.phase === "start";
+        if (event.phase === "start") return;
+        
+        if ((event.error || event.aborted) && event.reason === "manual") return;
+        if (event.error) return this.#notice("warning", event.error);
+        if (event.aborted) return this.#notice("info", "Compaction cancelled.");
+        return this.#notice("info", `Compacted the conversation (${event.reason}).`);
+      case "retry":
+        return this.#notice(
+          "warning",
+          `Retrying (${event.attempt}/${event.maxAttempts}) in ${event.delayMs}ms — ${event.message}`,
+        );
+      case "queue":
+        this.#queue = { steering: event.steering.length, followUp: event.followUp.length };
+        return;
+      case "notice":
+        return this.#notice(event.level, event.message);
+      case "subagent":
+        this.#subagents = event.agents;
+        return;
+      case "error":
+        return this.#notice("error", event.message);
+      case "idle":
+        this.#streaming = false;
+        this.#queue = { steering: 0, followUp: 0 };
+        
+        this.#subagents = [];
+        this.#closeStreams(false);
+        return;
+      case "host":
+        return this.#host(event.kind, event.id, event.payload);
+      default:
+        return;
+    }
+  }
+
+  #id() {
+    this.#nextId += 1;
+    return `p${this.#nextId}`;
+  }
+
+  #push(part: CodeTranscriptPart) {
+    this.#indexById.set(part.id, this.#parts.length);
+    this.#parts.push(part);
+  }
+
+  #patch(id: string, mutate: (part: CodeTranscriptPart) => void) {
+    const index = this.#indexById.get(id);
+    if (index === undefined) return;
+    const part = this.#parts[index];
+    if (part) mutate(part);
+  }
+
+  #notice(level: "info" | "warning" | "error", text: string) {
+    this.#push({ kind: "notice", id: this.#id(), level, text });
+  }
+
+  #appendAssistant(text: string) {
+    if (this.#openAssistant === undefined) {
+      const id = this.#id();
+      this.#openAssistant = id;
+      this.#push({ kind: "assistant", id, text, streaming: true, truncated: false });
+      return;
+    }
+    this.#patch(this.#openAssistant, (part) => {
+      if (part.kind === "assistant") part.text += text;
+    });
+  }
+
+  #appendThinking(text: string) {
+    if (this.#openThinking === undefined) {
+      const id = this.#id();
+      this.#openThinking = id;
+      this.#push({ kind: "thinking", id, text });
+      return;
+    }
+    this.#patch(this.#openThinking, (part) => {
+      if (part.kind === "thinking") part.text += text;
+    });
+  }
+
+  #message(role: "user" | "assistant", text: string) {
+    if (role === "user") {
+      
+      const last = this.#parts.at(-1);
+      if (last?.kind === "user" && last.text === text) return;
+      this.#push({ kind: "user", id: this.#id(), text });
+      return;
+    }
+    if (this.#openAssistant !== undefined) {
+      const open = this.#openAssistant;
+      this.#openAssistant = undefined;
+      this.#patch(open, (part) => {
+        if (part.kind !== "assistant") return;
+        part.text = text;
+        part.streaming = false;
+      });
+      return;
+    }
+    this.#push({ kind: "assistant", id: this.#id(), text, streaming: false, truncated: false });
+  }
+
+  #closeStreams(truncated: boolean) {
+    this.#openThinking = undefined;
+    const open = this.#openAssistant;
+    this.#openAssistant = undefined;
+    if (open === undefined) return;
+    this.#patch(open, (part) => {
+      if (part.kind !== "assistant") return;
+      part.streaming = false;
+      part.truncated = truncated;
+    });
+  }
+
+  #upsertTool(tool: CodeAgentToolSummary, result: { outcome?: CodeAgentToolOutcome; output?: string }) {
+    const index = this.#indexById.get(tool.toolCallId);
+    if (index === undefined) {
+      this.#push({ kind: "tool", id: tool.toolCallId, tool, ...result });
+      return;
+    }
+    const part = this.#parts[index];
+    if (part?.kind !== "tool") return;
+    
+    part.tool = tool;
+    if (result.outcome) part.outcome = result.outcome;
+    if (result.output !== undefined) part.output = result.output;
+  }
+
+  #progress(toolCallId: string, text: string) {
+    this.#patch(toolCallId, (part) => {
+      if (part.kind === "tool") part.progress = text;
+    });
+  }
+
+  #host(hostKind: string, id: string | undefined, payload: unknown) {
+    const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+    if (id === undefined) {
+      this.#push({ kind: "host", id: this.#id(), hostKind, text });
+      return;
+    }
+    const index = this.#indexById.get(id);
+    if (index === undefined) {
+      this.#push({ kind: "host", id, hostKind, text });
+      return;
+    }
+    const part = this.#parts[index];
+    if (part?.kind === "host") part.text = text;
+  }
+}

package/common/Logger.ts

@@ -81,28 +81,18 @@ const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`,
 
 const redactedAttrKey = /password|passwd|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key/i;
 
-/**
- * `process.env?.X` guards only `env` being absent, never `process` itself — an undeclared `process` is a
- * ReferenceError, and at module scope that takes the whole client bundle with it. This is the most widely
- * imported file in `common/`, and the unguarded form works today only because the browser build ships a shim.
- */
 const envValue = (key: string): string | undefined => (typeof process === "undefined" ? undefined : process.env?.[key]);
 
-/** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export class Logger {
-  /** `AKAN_LOG_STDOUT_LEVEL` names what the container's stdout carries; without it the console level is that. */
   static level: LogLevel = Logger.#levelFromEnv(
     envValue("AKAN_LOG_STDOUT_LEVEL"),
     Logger.#levelFromEnv(envValue("AKAN_PUBLIC_LOG_LEVEL"), "info"),
   );
   static fileLevel: LogLevel = Logger.#levelFromEnv(envValue("AKAN_LOG_FILE_LEVEL"), "trace");
   static format: LogFormat = Logger.#formatFromEnv(envValue("AKAN_LOG_FORMAT"));
-  /** Which process this is (`gateway`, `all`, `batch`, `rsc-worker`); the owner sets it at boot. */
+  /** `gateway`, `all`, `batch` or `rsc-worker`; the owner sets it at boot. */
   static role: string | null = envValue("SERVER_MODE") ?? null;
-  /**
-   * Whether this process writes its own lines to the terminal. Off in every server process of an ndjson
-   * deployment: the hub owner writes the one JSON stream, and a text line from anyone would corrupt it.
-   */
+  /** Off in every server process of an ndjson deployment but the hub owner, whose JSON stream a text line corrupts. */
   static consoleOutput = true;
   /** Set by the trace layer when a flight recorder or a per-request debug floor can be active. */
   static contextGate = false;
@@ -136,14 +126,12 @@ export class Logger {
   static get isNdjson() {
     return Logger.format !== "text";
   }
-  /** For hot-path callers that would otherwise build a message the level is about to discard. */
   static shouldLog(logLevel: LogLevelInput) {
     return Logger.#shouldLog(Logger.normalizeLevel(logLevel));
   }
   static normalizeLevel(level: LogLevelInput): LogLevel {
     return level === "log" ? "info" : level;
   }
-  /** The lowest named level whose severity is at least `sev`. */
   static levelAtOrAbove(sev: number): LogLevel {
     return logLevels.find((level) => logSeverity[level] >= sev) ?? "error";
   }
@@ -151,16 +139,15 @@ export class Logger {
     const level = record.level;
     if (level === null) return record.message;
     const replicaMsg = record.replicaIdx === null ? "" : `#${record.replicaIdx} `;
-    const processMsg = Logger.#colorize(`[${record.name}] ${replicaMsg}${record.pid ?? "window"} -`, level);
+    const processMsg = colorizeMap[level](`[${record.name}] ${replicaMsg}${record.pid ?? "window"} -`);
     const timestampMsg = dayjs(record.at).format("MM/DD/YYYY, HH:mm:ss A");
-    const logLevelMsg = Logger.#colorize(level.toUpperCase().padStart(7, " "), level);
+    const logLevelMsg = colorizeMap[level](level.toUpperCase().padStart(7, " "));
     const contextMsg = record.context ? clc.yellow(`[${record.context}] `) : "";
-    const contentMsg = Logger.#colorize(record.message, level);
+    const contentMsg = colorizeMap[level](record.message);
     const attrsMsg = record.attrs ? Logger.formatAttrs(record.attrs) : "";
     const timeDiffMsg = clc.yellow(`+${record.elapsedMs}ms`);
     return `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg}${attrsMsg ? ` ${attrsMsg}` : ""} ${timeDiffMsg}\n`;
   }
-  /** `key=value` pairs; a string with whitespace is quoted so the line stays splittable. */
   static formatAttrs(attrs: LogAttrs): string {
     return Object.entries(attrs)
       .map(
@@ -169,10 +156,7 @@ export class Logger {
       )
       .join(" ");
   }
-  /**
-   * A record somebody asked for below the level — a failed call's flight recorder, a request carrying
-   * `x-akan-debug` — passes every floor between here and the reader; the floors exist to drop what nobody asked for.
-   */
+  /** A flight-recorder or `x-akan-debug` record passes every floor between here and the reader. */
   static isPromoted(record: LogRecord) {
     return record.attrs?.flight === true || record.attrs?.debug === true;
   }
@@ -185,15 +169,10 @@ export class Logger {
     }
     return redacted ?? attrs;
   }
-  /** A structured record from a caller that has more than a sentence to say — the canonical request line. */
   static emit({ level, name, message, context = "", attrs }: LoggerEmitInput) {
     if (Logger.#shouldLog(level)) Logger.#write(name, message, context, level, attrs);
   }
-  /**
-   * Writes records that were captured below the gate and are now promoted — a failed request's flight
-   * recorder. They bypass the console level, since not showing them is what the recorder was for, and reach
-   * sinks under their own floors; each is marked `flight` so a reader knows why a trace line appears at info.
-   */
+  /** Writes a failed request's flight-recorder records past the console level, each marked `flight`. */
   static replay(records: LogRecord[], { evicted = 0 }: { evicted?: number } = {}) {
     records.forEach((record, idx) => {
       const attrs: LogAttrs = { ...record.attrs, flight: true };
@@ -231,7 +210,7 @@ export class Logger {
     if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
   }
   raw(msg: string, method?: "console" | "process") {
-    Logger.rawLog(msg, method);
+    Logger.raw(msg, method);
   }
   rawLog(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
@@ -270,9 +249,6 @@ export class Logger {
     for (const minSev of Logger.#sinks.values()) floor = Math.min(floor, minSev ?? Logger.#fileSev);
     Logger.#sinkFloorSev = floor;
   }
-  static #colorize(msg: string, logLevel: LogLevel) {
-    return colorizeMap[logLevel](msg);
-  }
   static stripAnsi(msg: string) {
     return msg.replace(ansiPattern, "");
   }
@@ -286,7 +262,6 @@ export class Logger {
   static #shouldEmitSink(logLevel: LogLevel) {
     return logSeverity[logLevel] >= Logger.#sinkFloorSev;
   }
-  /** The lowest severity the ambient request wants captured or shown, or +∞ outside one. */
   static #contextFloor(ctx: LogContextSnapshot | undefined) {
     if (!ctx) return Number.POSITIVE_INFINITY;
     return Math.min(ctx.flight?.minSev ?? Number.POSITIVE_INFINITY, ctx.debugSev ?? Number.POSITIVE_INFINITY);
@@ -364,7 +339,7 @@ export class Logger {
     const ctx = readLogContext();
     const sev = logSeverity[logLevel];
     const debug = ctx?.debugSev !== undefined && ctx.debugSev !== null && sev >= ctx.debugSev;
-
+    
     const promoted = debug && sev < Logger.#consoleSev;
     const record = Logger.#buildRecord(
       name,

package/common/TrustedProxy.ts

@@ -1,18 +1,5 @@
-import { normalizeIpAddress } from "./clientAddress";
+import { clientAddressFromHeaders, normalizeIpAddress } from "./clientAddress";
 
-/**
- * Whether the hop that connected is allowed to name the caller.
- *
- * `x-real-ip` and `x-forwarded-for` are just request headers: anyone can send them. They are the truth only when
- * the peer that sent them is a proxy we put there — otherwise a client forges its own address and walks past
- * every `.with(Ip)` guard, rate limit and audit line at once.
- *
- * The default trusts a private, loopback or link-local peer and nothing else, because that is exactly the shape
- * of a proxy on the same network: an ingress, a service mesh, the dev machine. A gateway reachable from the
- * internet sees a public peer, so a header from there is dropped rather than believed. `AKAN_TRUSTED_PROXIES`
- * takes a comma-separated CIDR list for the case the proxy is not private — and `*` for "the deployment
- * guarantees nothing untrusted can reach this port", which is the old behaviour, written down.
- */
 export class TrustedProxy {
   static #cidrs: { bytes: Uint8Array; bits: number }[] | null = null;
   static #trustAll: boolean | null = null;
@@ -48,31 +35,16 @@ export class TrustedProxy {
     return (TrustedProxy.#cidrs ?? []).some((cidr) => TrustedProxy.#inRange(bytes, cidr));
   }
 
-  /**
-   * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
-   * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
-   *
-   * `null` and `undefined` mean different things here. `null` is what `Server.requestIP` answers for a socket
-   * that has no address — a unix socket, which is how a gateway reaches its children — and only a process on
-   * this machine can open one, so the headers it wrote are a local proxy's and are believed. `undefined` is
-   * "nobody asked": no resolver was registered, and a header from an unknown peer is a header the client wrote.
-   */
+  /** A `null` peer is a unix socket, which only a local proxy opens, so its headers count; `undefined` is not. */
   static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null {
     if (peerAddress === null || TrustedProxy.isTrusted(peerAddress)) {
-      const realIp = headers.get("x-real-ip")?.trim();
-      if (realIp) return normalizeIpAddress(realIp);
-      const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
-      if (forwarded) return normalizeIpAddress(forwarded);
+      const recorded = clientAddressFromHeaders(headers);
+      if (recorded) return recorded;
     }
     return peerAddress ? normalizeIpAddress(peerAddress) : null;
   }
 
-  /**
-   * Whether an address is one no public name should resolve to: the local ranges `isTrusted` reads, plus the
-   * unspecified address, the carrier-grade NAT block `100.64/10`, multicast and the reserved top of IPv4. Used
-   * to refuse a fetch whose destination a caller chose by name, so it judges the address alone and never the
-   * configured proxy list — a trusted proxy is still not somewhere to send an outbound request.
-   */
+  /** For refusing an outbound fetch to a caller-chosen name: judges the address alone, never the proxy list. */
   static isPrivateAddress(address: string): boolean {
     const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
     if (!bytes) return true;
@@ -134,7 +106,7 @@ export class TrustedProxy {
   }
 
   static #ipv6ToBytes(address: string): Uint8Array | null {
-
+    
     const bare = address.split("%")[0] ?? "";
     const halves = bare.split("::");
     if (halves.length > 2) return null;

package/common/applyMixins.ts

@@ -1,7 +1,18 @@
-import { getAllPropertyDescriptors } from "./getAllPropertyDescriptors";
-
 type Cls<T = unknown> = new (...args: never[]) => T;
 
+export const getAllPropertyDescriptors = (objRef: Cls): { [key: string]: PropertyDescriptor } => {
+  const descriptors: Record<string, PropertyDescriptor> = {};
+  let current = objRef.prototype as object | null;
+  while (current) {
+    Object.getOwnPropertyNames(current).forEach((name) => {
+      const descriptor = Object.getOwnPropertyDescriptor(current, name);
+      if (descriptor) descriptors[name] ??= descriptor;
+    });
+    current = Object.getPrototypeOf(current) as Cls | object;
+  }
+  return descriptors;
+};
+
 export const applyMixins = (derivedCtor: Cls, constructors: (Cls | undefined)[], avoidKeys?: Set<string>) => {
   constructors.forEach((baseCtor) => {
     if (!baseCtor) return;

package/common/authToken.ts

@@ -4,11 +4,6 @@ import { decodeJwtPayload } from "./jwtDecode";
 /** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
 export const legacyAuthTokenKey = "jwt";
 
-/**
- * Cookies carry no port (RFC 6265), so every app served from one host shares a jar — which on localhost is
- * every app in the workspace at once. Under a global `jwt` key each signin overwrites the neighbour's
- * session, and the JWT's own `appName` check only turns the stolen cookie into a failing credential.
- */
 export const authTokenKey = (): string => `${legacyAuthTokenKey}:${getEnv().appName}`;
 
 /** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
@@ -17,11 +12,9 @@ export const isAuthTokenKey = (key: string): boolean =>
 
 const authCookiePattern = new RegExp(`(?:^|;\\s*)${legacyAuthTokenKey}(?::[^=\\s;]+)?=`);
 
-/** Whether a raw `cookie` header carries an auth token under either spelling. */
 export const cookieHeaderHasAuthToken = (cookieHeader: string | null | undefined): boolean =>
   !!cookieHeader && authCookiePattern.test(cookieHeader);
 
-/** Whether a token was minted for this app and environment — the same pair the server's account check makes. */
 export const isOwnAuthToken = (jwt: string): boolean => {
   const { appName, environment } = getEnv();
   try {
@@ -32,10 +25,6 @@ export const isOwnAuthToken = (jwt: string): boolean => {
   }
 };
 
-/**
- * Reads the app-scoped token, falling back to a leftover global one only when its payload names this app —
- * a neighbour's token would decode fine here and fail every guard, so adopting it is worse than none.
- */
 export const readAuthToken = (read: (key: string) => string | null | undefined): string | undefined => {
   const scoped = read(authTokenKey());
   if (scoped) return scoped;

package/common/capitalize.ts

@@ -1,4 +1,3 @@
-/** Uppercases only the first character of a string. */
-export const capitalize = (str: string) => {
-  return str.charAt(0).toUpperCase() + str.slice(1);
-};
+export const capitalize = (str: string) => str.charAt(0).toUpperCase() + str.slice(1);
+
+export const lowerlize = (str: string) => str.charAt(0).toLowerCase() + str.slice(1);

package/common/clamp.ts

@@ -1,2 +1 @@
-/** Constrains a value to `[min, max]`. */
 export const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);

package/common/clientAddress.ts

@@ -1,4 +1,3 @@
-/** Headers a proxy hop writes so the next hop can still name the original caller. */
 export const forwardedHeaders = [
   "x-real-ip",
   "x-forwarded-for",
@@ -7,25 +6,13 @@ export const forwardedHeaders = [
   "x-forwarded-proto",
 ] as const;
 
-/**
- * An IPv4 client reaching a dual-stack listener is reported as `::ffff:203.0.113.10`. That form is not a
- * valid destination for a `udp4` socket and does not compare equal to the same address written plainly, so
- * it is unwrapped at every boundary rather than at each call site that happens to remember.
- */
 export const normalizeIpAddress = (address: string): string => {
   const trimmed = address.trim();
   const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(trimmed);
   return mapped?.[1] ?? trimmed;
 };
 
-/**
- * The caller's address as the nearest proxy recorded it. `x-real-ip` is one hop's word for who the client is
- * and wins; `x-forwarded-for` is a chain appended left to right, so its *first* entry is the original client
- * and everything after it is a proxy.
- *
- * Returns `null` rather than a placeholder. A socket peer behind a proxy is the proxy, so `127.0.0.1` here
- * would be indistinguishable from a genuinely local caller — and that is the failure this exists to prevent.
- */
+/** `x-real-ip`, else the first `x-forwarded-for` entry; `null`, never a placeholder, when neither is set. */
 export const clientAddressFromHeaders = (headers: Headers): string | null => {
   const realIp = headers.get("x-real-ip")?.trim();
   if (realIp) return normalizeIpAddress(realIp);
@@ -33,7 +20,6 @@ export const clientAddressFromHeaders = (headers: Headers): string | null => {
   return forwarded ? normalizeIpAddress(forwarded) : null;
 };
 
-/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
 export const clientPortFromHeaders = (headers: Headers): number | null => {
   const port = Number(headers.get("x-forwarded-port"));
   return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;