akanjs 3.0.0-alpha.7 → 3.0.0-alpha.71

package/common/Logger.ts

@@ -1,17 +1,64 @@
 import dayjs from "dayjs";
+import { type LogContextSnapshot, readLogContext } from "./logContext";
 
-const logLevels = ["trace", "verbose", "debug", "log", "info", "warn", "error"] as const;
+export const logLevels = ["trace", "verbose", "debug", "info", "warn", "error"] as const;
 export type LogLevel = (typeof logLevels)[number];
+export type LogLevelInput = LogLevel | "log";
+
+export const logSeverity = { trace: 1, verbose: 3, debug: 5, info: 9, warn: 13, error: 17 } as const satisfies {
+  [key in LogLevel]: number;
+};
+
+/** `text` is the human console line; the `ndjson` pair make the container's stdout one JSON record per line. */
+export const logFormats = ["text", "ndjson", "ndjson-only"] as const;
+export type LogFormat = (typeof logFormats)[number];
+
+export type LogAttrValue = string | number | boolean | null;
+export interface LogAttrs {
+  [key: string]: LogAttrValue;
+}
+
+export interface LogRecord {
+  at: number;
+  /** Milliseconds since the producing process started — what the `+Nms` in the rendered line shows. */
+  elapsedMs: number;
+  level: LogLevel | null;
+  sev: number;
+  name: string;
+  context: string;
+  message: string;
+  stream: "stdout" | "stderr";
+  pid: number | null;
+  replicaIdx: number | null;
+  role: string | null;
+  origin: string | null;
+  traceId: string | null;
+  endpoint: string | null;
+  attrs?: LogAttrs;
+}
 
 export interface LoggerSinkEntry {
   stream: "stdout" | "stderr";
   level?: LogLevel;
   message: string;
   plainMessage: string;
+  record: LogRecord;
 }
 
 export type LoggerSink = (entry: LoggerSinkEntry) => void | Promise<void>;
 
+export interface LoggerSinkOptions {
+  minLevel?: LogLevelInput;
+}
+
+export interface LoggerEmitInput {
+  level: LogLevel;
+  name: string;
+  message: string;
+  context?: string;
+  attrs?: LogAttrs;
+}
+
 const clc = {
   bold: (text: string) => `\x1B[1m${text}\x1B[0m`,
   green: (text: string) => `\x1B[32m${text}\x1B[39m`,
@@ -25,7 +72,6 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
   trace: clc.bold,
   verbose: clc.cyanBright,
   debug: clc.magentaBright,
-  log: clc.green,
   info: clc.green,
   warn: clc.yellow,
   error: clc.red,
@@ -33,36 +79,122 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
 
 const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
 
+const redactedAttrKey = /password|passwd|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key/i;
+
 /** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export class Logger {
-  static level: LogLevel = (process.env?.AKAN_PUBLIC_LOG_LEVEL as LogLevel | undefined) ?? "log";
-  static #levelIdx = logLevels.findIndex((l) => l === (process.env?.AKAN_PUBLIC_LOG_LEVEL ?? "log"));
-  static fileLevel: LogLevel = (process.env?.AKAN_LOG_FILE_LEVEL as LogLevel | undefined) ?? "trace";
-  static #fileLevelIdx = logLevels.findIndex((l) => l === (process.env?.AKAN_LOG_FILE_LEVEL ?? "trace"));
-  static #startAt = dayjs();
-  static #sinks = new Set<LoggerSink>();
-
-  static setLevel(level: LogLevel) {
-    Logger.level = level;
-    Logger.#levelIdx = logLevels.indexOf(level);
-  }
-  static addSink(sink: LoggerSink) {
-    Logger.#sinks.add(sink);
+  /** `AKAN_LOG_STDOUT_LEVEL` names what the container's stdout carries; without it the console level is that. */
+  static level: LogLevel = Logger.#levelFromEnv(
+    process.env?.AKAN_LOG_STDOUT_LEVEL,
+    Logger.#levelFromEnv(process.env?.AKAN_PUBLIC_LOG_LEVEL, "info"),
+  );
+  static fileLevel: LogLevel = Logger.#levelFromEnv(process.env?.AKAN_LOG_FILE_LEVEL, "trace");
+  static format: LogFormat = Logger.#formatFromEnv(process.env?.AKAN_LOG_FORMAT);
+  /** Which process this is (`gateway`, `all`, `batch`, `rsc-worker`); the owner sets it at boot. */
+  static role: string | null = process.env?.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.
+   */
+  static consoleOutput = true;
+  /** Set by the trace layer when a flight recorder or a per-request debug floor can be active. */
+  static contextGate = false;
+  static readonly startAt = Date.now();
+  static #consoleSev: number = logSeverity[Logger.level];
+  static #fileSev: number = logSeverity[Logger.fileLevel];
+  static #sinkFloorSev = Number.POSITIVE_INFINITY;
+  static #sinks = new Map<LoggerSink, number | null>();
+
+  static setLevel(level: LogLevelInput) {
+    Logger.level = Logger.normalizeLevel(level);
+    Logger.#consoleSev = logSeverity[Logger.level];
+  }
+  static setFileLevel(level: LogLevelInput) {
+    Logger.fileLevel = Logger.normalizeLevel(level);
+    Logger.#fileSev = logSeverity[Logger.fileLevel];
+    Logger.#refreshSinkFloor();
+  }
+  static addSink(sink: LoggerSink, { minLevel }: LoggerSinkOptions = {}) {
+    Logger.#sinks.set(sink, minLevel === undefined ? null : logSeverity[Logger.normalizeLevel(minLevel)]);
+    Logger.#refreshSinkFloor();
     return () => Logger.removeSink(sink);
   }
   static removeSink(sink: LoggerSink) {
     Logger.#sinks.delete(sink);
-  }
-  static setFileLevel(level: LogLevel) {
-    Logger.fileLevel = level;
-    Logger.#fileLevelIdx = logLevels.indexOf(level);
+    Logger.#refreshSinkFloor();
   }
   static isVerbose() {
-    return Logger.#levelIdx <= 1;
+    return Logger.#consoleSev <= logSeverity.verbose;
+  }
+  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: LogLevel) {
-    return Logger.#shouldLog(logLevel);
+  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";
+  }
+  static render(record: LogRecord): string {
+    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 timestampMsg = dayjs(record.at).format("MM/DD/YYYY, HH:mm:ss A");
+    const logLevelMsg = Logger.#colorize(level.toUpperCase().padStart(7, " "), level);
+    const contextMsg = record.context ? clc.yellow(`[${record.context}] `) : "";
+    const contentMsg = Logger.#colorize(record.message, level);
+    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(
+        ([key, value]) =>
+          `${key}=${typeof value === "string" && /\s/.test(value) ? JSON.stringify(value) : String(value)}`,
+      )
+      .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.
+   */
+  static isPromoted(record: LogRecord) {
+    return record.attrs?.flight === true || record.attrs?.debug === true;
+  }
+  static redactAttrs(attrs: LogAttrs): LogAttrs {
+    let redacted: LogAttrs | null = null;
+    for (const key of Object.keys(attrs)) {
+      if (!redactedAttrKey.test(key)) continue;
+      redacted ??= { ...attrs };
+      redacted[key] = "[redacted]";
+    }
+    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.
+   */
+  static replay(records: LogRecord[], { evicted = 0 }: { evicted?: number } = {}) {
+    records.forEach((record, idx) => {
+      const attrs: LogAttrs = { ...record.attrs, flight: true };
+      if (idx === 0 && evicted > 0) attrs.flightEvicted = evicted;
+      const entry = Logger.#entry({ ...record, attrs });
+      Logger.#emit(entry);
+      Logger.#writeConsole(entry);
+    });
   }
 
   name?: string;
@@ -70,25 +202,26 @@ export class Logger {
     this.name = name;
   }
   trace(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("trace")) Logger.#printMessages(name, msg, context, "trace");
+    if (Logger.#shouldLog("trace")) Logger.#write(name, msg, context, "trace");
   }
   verbose(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("verbose")) Logger.#printMessages(name, msg, context, "verbose");
+    if (Logger.#shouldLog("verbose")) Logger.#write(name, msg, context, "verbose");
   }
   debug(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("debug")) Logger.#printMessages(name, msg, context, "debug");
+    if (Logger.#shouldLog("debug")) Logger.#write(name, msg, context, "debug");
   }
+  /** @deprecated Emits at `info`; call `info()`. */
   log(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("log")) Logger.#printMessages(name, msg, context, "log");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   info(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("info")) Logger.#printMessages(name, msg, context, "info");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   warn(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("warn")) Logger.#printMessages(name, msg, context, "warn");
+    if (Logger.#shouldLog("warn")) Logger.#write(name, msg, context, "warn");
   }
   error(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
+    if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
   }
   raw(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
@@ -96,86 +229,166 @@ export class Logger {
   rawLog(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
   }
-  
   static trace(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("trace")) Logger.#printMessages(name, msg, context, "trace");
+    if (Logger.#shouldLog("trace")) Logger.#write(name, msg, context, "trace");
   }
   static verbose(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("verbose")) Logger.#printMessages(name, msg, context, "verbose");
+    if (Logger.#shouldLog("verbose")) Logger.#write(name, msg, context, "verbose");
   }
   static debug(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("debug")) Logger.#printMessages(name, msg, context, "debug");
+    if (Logger.#shouldLog("debug")) Logger.#write(name, msg, context, "debug");
   }
+  /** @deprecated Emits at `info`; call `info()`. */
   static log(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("log")) Logger.#printMessages(name, msg, context, "log");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   static info(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("info")) Logger.#printMessages(name, msg, context, "info");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   static warn(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("warn")) Logger.#printMessages(name, msg, context, "warn");
+    if (Logger.#shouldLog("warn")) Logger.#write(name, msg, context, "warn");
   }
   static error(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
+    if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
+  }
+  static #levelFromEnv(value: string | undefined, fallback: LogLevel): LogLevel {
+    if (value === "log") return "info";
+    return (logLevels as readonly string[]).includes(value ?? "") ? (value as LogLevel) : fallback;
+  }
+  static #formatFromEnv(value: string | undefined): LogFormat {
+    return (logFormats as readonly string[]).includes(value ?? "") ? (value as LogFormat) : "text";
+  }
+  static #refreshSinkFloor() {
+    let floor = Number.POSITIVE_INFINITY;
+    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) {
+  static stripAnsi(msg: string) {
     return msg.replace(ansiPattern, "");
   }
   static #shouldLog(logLevel: LogLevel) {
-    return Logger.#shouldWriteConsole(logLevel) || Logger.#shouldEmitSink(logLevel);
+    if (Logger.#shouldWriteConsole(logLevel) || Logger.#shouldEmitSink(logLevel)) return true;
+    return Logger.contextGate && Logger.#contextFloor(readLogContext()) <= logSeverity[logLevel];
   }
   static #shouldWriteConsole(logLevel: LogLevel) {
-    return Logger.#levelIdx <= logLevels.indexOf(logLevel);
+    return Logger.consoleOutput && logSeverity[logLevel] >= Logger.#consoleSev;
   }
   static #shouldEmitSink(logLevel: LogLevel) {
-    return Logger.#sinks.size > 0 && Logger.#fileLevelIdx <= logLevels.indexOf(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);
+  }
+  static #buildRecord(
+    name: string | undefined,
+    message: string,
+    context: string,
+    level: LogLevel | null,
+    stream: "stdout" | "stderr",
+    ctx: LogContextSnapshot | undefined,
+    attrs?: LogAttrs,
+  ): LogRecord {
+    const proc = process as unknown as NodeJS.Process | undefined;
+    const replicaIdx = Number(proc?.env?.AKAN_REPLICA_IDX ?? Number.NaN);
+    const at = Date.now();
+    return {
+      at,
+      elapsedMs: at - Logger.startAt,
+      level,
+      sev: level === null ? 0 : logSeverity[level],
+      name: name ?? "App",
+      context,
+      message,
+      stream,
+      pid: proc?.pid ?? null,
+      replicaIdx: Number.isNaN(replicaIdx) ? null : replicaIdx,
+      role: Logger.role,
+      origin: ctx?.origin ?? null,
+      traceId: ctx?.traceId ?? null,
+      endpoint: ctx?.endpoint ?? null,
+      ...(attrs ? { attrs: Logger.redactAttrs(attrs) } : {}),
+    };
+  }
+  static #entry(record: LogRecord, text?: string): LoggerSinkEntry {
+    let message = text;
+    let plainMessage: string | undefined;
+    return {
+      stream: record.stream,
+      level: record.level ?? undefined,
+      record,
+      get message() {
+        message ??= Logger.render(record);
+        return message;
+      },
+      get plainMessage() {
+        plainMessage ??= Logger.stripAnsi(this.message);
+        return plainMessage;
+      },
+    };
   }
   static #emit(entry: LoggerSinkEntry) {
-    for (const sink of Logger.#sinks) {
+    for (const [sink, minSev] of Logger.#sinks) {
+      
+      if (
+        entry.record.level !== null &&
+        entry.record.sev < (minSev ?? Logger.#fileSev) &&
+        !Logger.isPromoted(entry.record)
+      )
+        continue;
       try {
         void Promise.resolve(sink(entry)).catch(() => undefined);
       } catch {
       }
     }
   }
-  static #printMessages(
-    name: string | undefined,
-    content: string,
-    context: string,
-    logLevel: LogLevel,
-    writeStreamType: "stdout" | "stderr" = logLevel === "error" ? "stderr" : "stdout",
-  ) {
-    const now = dayjs();
-    const replicaIdx = (process as unknown as NodeJS.Process | undefined)?.env?.AKAN_REPLICA_IDX;
-    const replicaMsg = replicaIdx === undefined ? "" : `#${replicaIdx} `;
-    const processMsg = Logger.#colorize(
-      `[${name ?? "App"}] ${replicaMsg}${(process as unknown as NodeJS.Process | undefined)?.pid ?? "window"} -`,
+  static #writeConsole(entry: LoggerSinkEntry) {
+    if (!Logger.consoleOutput) return;
+    if (typeof window === "undefined")
+      (process[entry.stream] as unknown as NodeJS.WriteStream | undefined)?.write(entry.message);
+    else console.log(entry.message);
+  }
+  static #write(name: string | undefined, message: string, context: string, logLevel: LogLevel, attrs?: LogAttrs) {
+    const stream = logLevel === "error" ? "stderr" : "stdout";
+    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,
+      message,
+      context,
       logLevel,
+      stream,
+      ctx,
+      promoted ? { ...attrs, debug: true } : attrs,
     );
-    const timestampMsg = now.format("MM/DD/YYYY, HH:mm:ss A");
-    const logLevelMsg = Logger.#colorize(logLevel.toUpperCase().padStart(7, " "), logLevel);
-    const contextMsg = context ? clc.yellow(`[${context}] `) : "";
-    const contentMsg = Logger.#colorize(content, logLevel);
-    const timeDiffMsg = clc.yellow(`+${now.diff(Logger.#startAt, "ms")}ms`);
-    const message = `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg} ${timeDiffMsg}\n`;
-    if (Logger.#shouldEmitSink(logLevel))
-      Logger.#emit({ stream: writeStreamType, level: logLevel, message, plainMessage: Logger.#stripAnsi(message) });
-    if (!Logger.#shouldWriteConsole(logLevel)) return;
-    if (typeof window === "undefined")
-      (process[writeStreamType] as unknown as NodeJS.WriteStream | undefined)?.write(message);
-    else console.log(message);
+    const toConsole = Logger.#shouldWriteConsole(logLevel) || (debug && Logger.consoleOutput);
+    const toSinks = Logger.#shouldEmitSink(logLevel) || debug;
+    ctx?.flight?.capture(record, toConsole || toSinks);
+    if (!toConsole && !toSinks) return;
+    const entry = Logger.#entry(record);
+    if (toSinks) Logger.#emit(entry);
+    if (toConsole) Logger.#writeConsole(entry);
   }
   static rawLog(msg = "", method?: "console" | "process", outputStream?: "log" | "error") {
     Logger.raw(`${msg}\n`, method, outputStream);
   }
   static raw(msg = "", method?: "console" | "process", outputStream?: "log" | "error") {
     const stream = outputStream === "error" ? "stderr" : "stdout";
-    Logger.#emit({ stream, message: msg, plainMessage: Logger.#stripAnsi(msg) });
+    Logger.#emit(Logger.#entry(Logger.#buildRecord(undefined, msg, "", null, stream, readLogContext()), msg));
+    if (!Logger.consoleOutput) return;
     if (typeof window === "undefined" && method !== "console" && (process as unknown as NodeJS.Process | undefined))
       process[stream].write(msg);
     else console[outputStream === "error" ? "error" : "log"](msg.trim());
   }
+  static {
+    if (process.env?.AKAN_PUBLIC_LOG_LEVEL === "log" && typeof window === "undefined")
+      Logger.warn("AKAN_PUBLIC_LOG_LEVEL=log is deprecated and now means info; set AKAN_PUBLIC_LOG_LEVEL=info.");
+  }
 }

package/common/clientAddress.ts

@@ -0,0 +1,40 @@
+/** Headers a proxy hop writes so the next hop can still name the original caller. */
+export const forwardedHeaders = [
+  "x-real-ip",
+  "x-forwarded-for",
+  "x-forwarded-port",
+  "x-forwarded-host",
+  "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.
+ */
+export const clientAddressFromHeaders = (headers: Headers): string | null => {
+  const realIp = headers.get("x-real-ip")?.trim();
+  if (realIp) return normalizeIpAddress(realIp);
+  const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+  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;
+};

package/common/deepObjectify.ts

@@ -1,9 +1,16 @@
 import { isDayjs } from "./isDayjs";
 
-export const deepObjectify = <T = unknown>(
-  obj: T | null | undefined,
-  option: { serializable?: boolean; convertDate?: "string" | "number" } = {},
-): T => {
+interface DeepObjectifyOption {
+  serializable?: boolean;
+  convertDate?: "string" | "number";
+}
+
+const objectifyChild = (value: unknown, option: DeepObjectifyOption): unknown => {
+  const modelValue = value as { __ModelType__?: string } | null | undefined;
+  return modelValue?.__ModelType__ && !option.serializable ? value : deepObjectify(value, option);
+};
+
+export const deepObjectify = <T = unknown>(obj: T | null | undefined, option: DeepObjectifyOption = {}): T => {
   if (isDayjs(obj) || obj?.constructor === Date) {
     if (!option.serializable && !option.convertDate) return obj as T;
     if (option.convertDate === "string") return obj.toISOString() as T;
@@ -12,14 +19,22 @@ export const deepObjectify = <T = unknown>(
     else return (isDayjs(obj) ? obj.toDate() : obj) as T;
   } else if (Array.isArray(obj)) {
     return obj.map((o: unknown) => deepObjectify(o, option)) as T;
+  } else if (obj instanceof Map) {
+    
+    const entries = [...obj.entries()].map(
+      ([key, value]: [string, unknown]) => [key, objectifyChild(value, option)] as const,
+    );
+    return (option.serializable ? Object.fromEntries(entries) : new Map(entries)) as T;
+  } else if (obj instanceof Set) {
+    const values = [...obj.values()].map((value: unknown) => objectifyChild(value, option));
+    return (option.serializable ? values : new Set(values)) as T;
   } else if (obj && typeof obj === "object") {
     const val: Record<string, unknown> = {};
     const objRecord = obj as Record<string, unknown>;
-    Object.keys(obj).forEach((key) => {
-      const fieldValue = objRecord[key] as { __ModelType__: string } | null | undefined;
-      if (fieldValue?.__ModelType__ && !option.serializable) val[key] = fieldValue;
-      else if (typeof objRecord[key] !== "function") val[key] = deepObjectify(fieldValue, option);
-    });
+    
+    for (const key in objRecord) {
+      if (typeof objRecord[key] !== "function") val[key] = objectifyChild(objRecord[key], option);
+    }
     return val as T;
   } else {
     return obj as unknown as T;

package/common/index.ts

@@ -1,5 +1,11 @@
 export { applyMixins } from "./applyMixins";
 export { capitalize } from "./capitalize";
+export {
+  clientAddressFromHeaders,
+  clientPortFromHeaders,
+  forwardedHeaders,
+  normalizeIpAddress,
+} from "./clientAddress";
 export { deepObjectify } from "./deepObjectify";
 export {
   type FileUploadCapability,
@@ -18,7 +24,22 @@ export { isQueryEqual } from "./isQueryEqual";
 export { isThenable } from "./isThenable";
 export { isValidDate } from "./isValidDate";
 export { decodeJwtPayload } from "./jwtDecode";
-export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger";
+export {
+  type LogAttrs,
+  type LogAttrValue,
+  type LogFormat,
+  Logger,
+  type LoggerEmitInput,
+  type LoggerSink,
+  type LoggerSinkEntry,
+  type LoggerSinkOptions,
+  type LogLevel,
+  type LogLevelInput,
+  type LogRecord,
+  logFormats,
+  logLevels,
+  logSeverity,
+} from "./Logger";
 export {
   type AkanI18nConfig,
   type AkanI18nConfigInput,
@@ -26,16 +47,35 @@ export {
   parseAkanI18nEnv,
   resolveAkanI18nConfig,
 } from "./localeConfig";
+export {
+  type LogContextReader,
+  type LogContextSnapshot,
+  type LogFlightRecorder,
+  readLogContext,
+  registerLogContextReader,
+} from "./logContext";
 export { lowerlize } from "./lowerlize";
+export {
+  isMcpDescribableArg,
+  type McpExposureEndpoint,
+  type McpExposureOption,
+  mcpBaseVerbOf,
+  mcpHintsOf,
+  mcpPromptRefusalOf,
+  mcpRefusalOf,
+} from "./mcpExposure";
 export { mergeVersion } from "./mergeVersion";
 export { objectify } from "./objectify";
 export { pathGet } from "./pathGet";
+export { pathGetLoose } from "./pathGetLoose";
 export { pathSet } from "./pathSet";
+export { plainFieldsOf } from "./plainFieldsOf";
 export { randomPick } from "./randomPick";
 export { randomPicks } from "./randomPicks";
 export {
   assertUniqueRoutePatterns,
   compareRouteSpecificity,
+  getPageSourceFileViolation,
   getRouteExports,
   isRouteSourceFile,
   isSpecialRouteLeaf,
@@ -65,3 +105,4 @@ export {
   type WebsocketAuthRequest,
   websocketAuthContract,
 } from "./websocketAuth";
+export { type WebsocketBinaryFrame, websocketBinaryFrameContract } from "./websocketBinaryFrame";

package/common/logContext.ts

@@ -0,0 +1,27 @@
+import type { LogRecord } from "./Logger";
+
+/** A per-request ring the Logger hands every record to; the trace decides at its end whether any of it is shown. */
+export interface LogFlightRecorder {
+  minSev: number;
+  capture(record: LogRecord, written: boolean): void;
+}
+
+export interface LogContextSnapshot {
+  traceId: string | null;
+  endpoint: string | null;
+  origin: string | null;
+  flight?: LogFlightRecorder | null;
+  /** A per-request floor below the process level (`x-akan-debug`); `null` when the request asked for nothing. */
+  debugSev?: number | null;
+}
+
+export type LogContextReader = () => LogContextSnapshot | undefined;
+
+const slot: { __akanLogContextReader?: LogContextReader | null } =
+  typeof process === "undefined" ? {} : (process as unknown as { __akanLogContextReader?: LogContextReader | null });
+
+export const registerLogContextReader = (reader: LogContextReader | null) => {
+  slot.__akanLogContextReader = reader;
+};
+
+export const readLogContext = () => slot.__akanLogContextReader?.();