akanjs 3.0.1 → 3.0.2-rc.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # akanjs
 
+## 3.0.1
+
+### Minor Changes
+
+- 4871ae5: The default `robots.txt` no longer disallows AI crawlers. GPTBot, ClaudeBot, PerplexityBot, Google-Extended and the rest may read public pages like any other crawler; `/api` (the configured prefix), `/_akan`, `/admin`, `/manager` and `/private` stay disallowed. An app that wants to keep AI crawlers out puts its own `robots.txt` in `public/`, which is served ahead of the generated one.
+
+### Patch Changes
+
+- 4871ae5: Send crawlers the whole page. A request whose user agent names a search engine, an AI crawler or a link-preview fetcher (Googlebot, GPTBot, ClaudeBot, Yeti, facebookexternalhit and the like) now waits for every Suspense boundary and gets each one rendered in place. Before, it got the Loading fallback with the content parked in hidden segments that only a script reveals — and even `ssr: "block"` left a large boundary there. Browsers keep streaming, and the HTML result cache keeps the crawler page apart from the browser page.
+- 4871ae5: Drop the `robots.txt.tsx` special route. `/robots.txt` was always answered first by `public/robots.txt` or the generated file, so the page never rendered; a `robots.txt.tsx` file is now an ordinary page under the locale, and `isSpecialRouteLeaf` is gone from `akanjs/common`. Change the file by putting your own `robots.txt` in `public/`.
+
 ## 3.0.0
 
 ### Minor Changes

package/base/base.ts

@@ -27,7 +27,7 @@ export type EnumInstance<RefName extends string = string, T = string | number> =
 export const isEnum = (enumRef: Cls) => Object.getPrototypeOf(Object.getPrototypeOf(enumRef) ?? {}) === EnumPrototype;
 
 /** `type` is `String` for string values, else `Int` when every value is an integer, else `Float`. */
-export const enumOf = <RefName extends string, T = string | number>(
+export const enumOf = <RefName extends string, const T = string | number>(
   refName: RefName,
   values: readonly T[],
 ): EnumInstance<RefName, T> => {

package/client/cookie.ts

@@ -46,19 +46,17 @@ export const cookies = (): Map<string, { name: string; value: string }> => {
 export const setCookie = (
   key: string,
   value: string,
-  options: CookieOptions = { path: "/", sameSite: "none", secure: true },
+  { path = "/", sameSite = "lax", secure = true }: CookieOptions = {},
 ) => {
   if (getEnv().side === "server") return;
   if (!pageKeepsCookies()) {
     writeCookieJar({ ...readCookieJar(), [key]: value });
     return;
   }
-  const encoded = `${key}=${value}`;
-  const path = options.path ? `; path=${options.path}` : "";
-  const sameSite = options.sameSite ? `; SameSite=${options.sameSite}` : "";
-  const secure = options.secure ? "; Secure" : "";
+  const pathAttr = path ? `; path=${path}` : "";
+  const secureAttr = secure ? "; Secure" : "";
   
-  document.cookie = `${encoded}${path}${sameSite}${secure}`;
+  document.cookie = `${key}=${value}${pathAttr}; SameSite=${sameSite}${secureAttr}`;
 };
 
 /** Reads through `cookies()` on both sides: a hand-rolled `split("=")` cuts base64 padding and skips the `j:` form. */

package/common/Logger.ts

@@ -169,6 +169,16 @@ export class Logger {
   static isPromoted(record: LogRecord) {
     return record.attrs?.flight === true || record.attrs?.debug === true;
   }
+  /** `value` as one line of JSON for a message, a secret-named key masked at any depth and the text cut at `max`. */
+  static inlineData(value: unknown, max = 500): string {
+    let text: string;
+    try {
+      text = JSON.stringify(value, (key, val) => (key && redactedAttrKey.test(key) ? "[redacted]" : val)) ?? "";
+    } catch {
+      text = "[unserializable]";
+    }
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+  }
   static redactAttrs(attrs: LogAttrs): LogAttrs {
     let redacted: LogAttrs | null = null;
     for (const key of Object.keys(attrs)) {

package/dictionary/base.dictionary.ts

@@ -40,10 +40,15 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "The server took too long to answer. Please try again in a moment.",
       "서버 응답이 지연되고 있습니다. 잠시 후 다시 시도해주세요.",
     ],
+    tooManyRequests: [
+      "Too many requests. Please try again in {seconds} seconds.",
+      "요청이 너무 많습니다. {seconds}초 후 다시 시도해주세요.",
+    ],
     unexpectedResponse: [
       "The server returned an unexpected response ({status}).",
       "서버가 예상하지 못한 응답을 보냈습니다. ({status})",
     ],
+    immutableField: ["{field} cannot be changed after creation.", "{field}은(는) 생성 후에는 바꿀 수 없습니다."],
   })
   .translate({
     somethingWrong: ["Something's wrong!", "문제가 생겼어요!"],
@@ -69,6 +74,8 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     phoneInvalidError: ["Phone is not valid", "유효하지 않은 전화번호입니다."],
     ok: ["OK", "확인"],
     cancel: ["Cancel", "취소"],
+    retry: ["Try again", "다시 시도"],
+    pageLoadFailed: ["This page could not be loaded.", "이 화면을 불러오지 못했습니다."],
     unauthorized: ["Unauthorized", "권한 없음"],
     agent: ["Agent", "에이전트"],
     agentIntro: ["Ask about this page or tell the agent what to do.", "이 화면에 대해 묻거나 할 일을 지시해 보세요."],

package/dictionary/trans.ts

@@ -1,5 +1,5 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
-import { interpolateTranslation, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
+import { interpolateTranslation, Logger, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
 
 import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
@@ -122,6 +122,12 @@ export const makeTrans = <
       this.timestamp = option.timestamp;
     }
 
+    override toString() {
+      return this.data === undefined
+        ? `${this.name}: ${this.message}`
+        : `${this.name}: ${this.message} ${Logger.inlineData(this.data)}`;
+    }
+
     toJSON() {
       return {
         error: this.message,

package/document/documentQuery.ts

@@ -101,7 +101,12 @@ export type DocumentUpdate<T = any> = {
   [K in DocumentPath<T>]?: DocumentUpdateValue;
 };
 
-export interface DocumentUpdateOptions {
+/** Server-only: no endpoint or slice builds it from a request, so a caller can never widen a read to removed rows. */
+export interface DocumentScopeOptions {
+  withRemoved?: boolean;
+}
+
+export interface DocumentUpdateOptions extends DocumentScopeOptions {
   upsert?: boolean;
 }
 

package/document/index.ts

@@ -6,6 +6,7 @@ export * from "./documentQuery";
 export * from "./documentSchema";
 export * from "./filterMeta";
 export * from "./into";
+export * from "./liveRowScope";
 export * from "./loaderInfo";
 export * from "./noDocumentError";
 export * from "./queryEvaluator";

package/document/into.ts

@@ -4,7 +4,7 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { FilterCls, FilterQueryOf, FilterSortOf, SchemaOf } from ".";
 import type { CacheDatabase, QueryMethodPart } from "./database";
 import type { DataLoader } from "./dataLoader";
-import type { DocumentQuery, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery";
+import type { DocumentQuery, DocumentScopeOptions, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery";
 import { type LoaderBuilder, type ModelCls, makeLoaderBuilder } from "./loaderInfo";
 import type { DocumentProjection } from "./types";
 
@@ -61,18 +61,26 @@ export type Mdl<
 > = DefaultMdlStats<Doc, _RawDoc, Partial<_RawDoc>, _RawQuery, _Projection> & {
   refName: string;
   new (data: Partial<_RawDoc> | Partial<Doc>): Doc;
-  find(query: _RawQuery, projection?: _Projection): FindManyChain<Doc>;
-  findOne(query: _RawQuery, projection?: _Projection): FindOneChain<Doc>;
-  findById(id: string | undefined, projection?: _Projection): Promise<Doc | null>;
-  count(query: _RawQuery): Promise<number>;
-  exists(query: _RawQuery): Promise<string | null>;
+  find(query: _RawQuery, projection?: _Projection | null, options?: DocumentScopeOptions): FindManyChain<Doc>;
+  findOne(query: _RawQuery, projection?: _Projection | null, options?: DocumentScopeOptions): FindOneChain<Doc>;
+  findById(
+    id: string | undefined,
+    projection?: _Projection | null,
+    options?: DocumentScopeOptions,
+  ): Promise<Doc | null>;
+  count(query: _RawQuery, options?: DocumentScopeOptions): Promise<number>;
+  exists(query: _RawQuery, options?: DocumentScopeOptions): Promise<string | null>;
 
   updateOne(
     query: _RawQuery,
     update: DocumentUpdateInput<_RawDoc>,
     options?: DocumentUpdateOptions,
   ): Promise<UpdateResult>;
-  updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>): Promise<UpdateResult>;
+  updateMany(
+    query: _RawQuery,
+    update: DocumentUpdateInput<_RawDoc>,
+    options?: DocumentScopeOptions,
+  ): Promise<UpdateResult>;
   removeOne(query: _RawQuery): Promise<UpdateResult>;
   removeMany(query: _RawQuery): Promise<UpdateResult>;
   updateById(id: string, update: DocumentUpdateInput<_RawDoc>, options?: DocumentUpdateOptions): Promise<UpdateResult>;

package/document/liveRowScope.ts

@@ -0,0 +1,79 @@
+import {
+  type DocumentQuery,
+  type DocumentQueryNode,
+  type DocumentQueryOperator,
+  queryOperatorKeys,
+} from "./documentQuery";
+
+type RemovedAtTest = "isNull" | "isNotNull" | "value";
+
+/**
+ * Why a query can never match a live row, or null: without `withRemoved` every read and write is scoped to
+ * `removedAt IS NULL`. `q.raw()` is SQL this walk cannot read, so it goes unchecked.
+ */
+export class LiveRowScope {
+  static conflictOf(query: DocumentQuery | undefined, negated = false): string | null {
+    if (!query || typeof query !== "object") return null;
+    if (LiveRowScope.#isNode(query)) {
+      if (query.kind === "all" || query.kind === "any")
+        return query.queries.reduce<string | null>(
+          (found, sub) => found ?? LiveRowScope.conflictOf(sub, negated),
+          null,
+        );
+      if (query.kind === "not") return LiveRowScope.conflictOf(query.query, !negated);
+      return null;
+    }
+    return Object.entries(query).reduce<string | null>(
+      (found, [path, value]) => found ?? LiveRowScope.#fieldConflict(path, value, negated),
+      null,
+    );
+  }
+
+  static #fieldConflict(path: string, value: unknown, negated: boolean): string | null {
+    if (LiveRowScope.#isNode(value) && value.kind !== "op") return LiveRowScope.conflictOf(value, negated);
+    if (path !== "removedAt") return null;
+    for (const [test, spelled] of LiveRowScope.#testsOf(value)) {
+      const named = negated ? `not(removedAt ${spelled})` : `removedAt ${spelled}`;
+      
+      if (test === "value") return `${named} compares a value no live row holds`;
+      if ((test === "isNotNull") !== negated) return `${named} asks for removed rows`;
+    }
+    return null;
+  }
+
+  static #testsOf(value: unknown): [RemovedAtTest, string][] {
+    if (value === undefined) return [];
+    if (value === null) return [["isNull", "null"]];
+    if (LiveRowScope.#isNode(value) && value.kind === "op") {
+      const test = LiveRowScope.#testOf(value.op, value.value);
+      return test ? [test] : [];
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const operators = value as Record<string, unknown>;
+      const keys = Object.keys(operators).filter((key) => queryOperatorKeys.has(key));
+      if (keys.length)
+        return keys.flatMap((key): [RemovedAtTest, string][] => {
+          const spelled = `{ ${key}: ${String(operators[key])} }`;
+          
+          if (key === "exists") return [[operators.exists ? "isNotNull" : "isNull", spelled]];
+          if (key === "missing" || key === "empty") return [[operators[key] ? "isNull" : "isNotNull", spelled]];
+          const test = LiveRowScope.#testOf(key as DocumentQueryOperator, operators[key]);
+          return test ? [test] : [];
+        });
+    }
+    return [["value", "eq"]];
+  }
+
+  static #testOf(op: DocumentQueryOperator, operand: unknown): [RemovedAtTest, string] | null {
+    if (op === "exists") return ["isNotNull", op];
+    if (op === "missing" || op === "empty") return ["isNull", op];
+    if ((op === "eq" || op === "ne") && operand === null) return [op === "eq" ? "isNull" : "isNotNull", `${op}(null)`];
+    
+    if ((op === "oneOf" || op === "notOneOf") && !(operand as unknown[] | undefined)?.length) return null;
+    return ["value", op];
+  }
+
+  static #isNode(value: unknown): value is DocumentQueryNode {
+    return !!value && typeof value === "object" && "kind" in value;
+  }
+}

package/fetch/client/fetchClient.ts

@@ -92,6 +92,9 @@ export class FetchClient {
   readonly #handlerStore: Record<string, FetchHandler> = {};
   readonly #handlerFactory = new Map<string, FetchHandlerFactory>();
   #sharedRegistryAppliedVersion = 0;
+  #clientIp: string | null = null;
+  static #testClientIps = false;
+  static #testClientIpSeq = 0;
   serializedSignal: { [key: string]: SerializedSignal } = {};
   jwt: string | null = null;
 
@@ -120,6 +123,19 @@ export class FetchClient {
     sharedClientState.proxy = null;
     sharedClientState.origin = null;
   }
+  /**
+   * In a signal test every agent reaches the test server from loopback, so an IP rate limit would count them all as
+   * one caller: from here on each clone names its own address (RFC 2544's benchmarking range), which loopback is
+   * trusted to report.
+   */
+  static useTestClientIps(enabled = true) {
+    FetchClient.#testClientIps = enabled;
+    FetchClient.#testClientIpSeq = 0;
+  }
+  static #nextTestClientIp() {
+    const seq = ++FetchClient.#testClientIpSeq;
+    return `198.${18 + ((seq >> 16) & 1)}.${(seq >> 8) & 255}.${seq & 255}`;
+  }
   static #resolveSharedClientProxy(origin: string, Err?: ErrorConstructor) {
     if (typeof window === "undefined") return null;
     
@@ -238,8 +254,22 @@ export class FetchClient {
     for (const ws of this.#originWs.values()) ws.destroy();
     this.#originWs.clear();
   }
-  clone({ origin, connect = true, jwt }: { origin?: string; connect?: boolean; jwt?: string } = {}) {
+  
+  clone({
+    origin,
+    connect = !(origin && typeof window === "undefined"),
+    jwt,
+    clientIp,
+  }: {
+    origin?: string;
+    connect?: boolean;
+    jwt?: string;
+    /** Sent as `x-real-ip`, which a server believes only from a trusted proxy — a test's loopback is one. */
+    clientIp?: string | null;
+  } = {}) {
     const instance = new FetchClient(origin ?? this.origin, {}, this.serializedSignal, this.ErrorCls);
+    instance.#clientIp =
+      clientIp !== undefined ? clientIp : FetchClient.#testClientIps ? FetchClient.#nextTestClientIp() : this.#clientIp;
     Object.entries(this.handler).forEach(([key, handler]) => {
       if (!(key in instance.handler)) instance.handler[key] = handler;
     });
@@ -265,6 +295,21 @@ export class FetchClient {
     ws.connect();
     return ws;
   }
+  #makeRequestHeaders(option?: FetchPolicy): Record<string, string> {
+    const clientIp = this.#clientIp ? { "x-real-ip": this.#clientIp } : FetchClient.#forwardedClientIp(option);
+    return { ...this.#makeAuthHeaders(option), ...clientIp };
+  }
+
+  static #forwardedClientIp(option?: FetchPolicy): Record<string, string> {
+    if (option?.origin) return {};
+    try {
+      if (getEnv().side !== "server") return {};
+      const clientIp = requestHeaders().get("x-real-ip");
+      return clientIp ? { "x-real-ip": clientIp } : {};
+    } catch {
+      return {};
+    }
+  }
   #makeAuthHeaders(option?: FetchPolicy): Record<string, string> {
     if (option?.token) return { Authorization: `Bearer ${option.token}` };
     try {
@@ -299,7 +344,7 @@ export class FetchClient {
       case "query":
         return async (...argData: unknown[]) => {
           const { option, argMap, url } = requestOf(argData);
-          const headers = this.#makeAuthHeaders(option);
+          const headers = this.#makeRequestHeaders(option);
           const baseUrl = this.#baseUrlOf(endpoint, option?.origin);
           const timeout = option?.timeout ?? endpoint.timeout;
           
@@ -318,7 +363,7 @@ export class FetchClient {
           const { option, argMap, url } = requestOf(argData);
           const body = HttpClient.makeBody(bodyArgs, uploadArgs, argMap);
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
-            headers: this.#makeAuthHeaders(option),
+            headers: this.#makeRequestHeaders(option),
             baseUrl: this.#baseUrlOf(endpoint, option?.origin),
             timeout: option?.timeout ?? endpoint.timeout,
           });
@@ -429,16 +474,16 @@ export class FetchClient {
       modelId: `${refName}Id`,
       lightModel: `light${capRefName}`,
     };
-    const createGuards = signal.createGuards ?? signal.cruGuards;
-    const updateGuards = signal.updateGuards ?? signal.cruGuards;
-    const removeGuards = signal.removeGuards ?? signal.cruGuards;
+    const createGuards = FetchClient.#mountedGuards(signal, "create");
+    const updateGuards = FetchClient.#mountedGuards(signal, "update");
+    const removeGuards = FetchClient.#mountedGuards(signal, "remove");
     
     const mcp = (verb: keyof NonNullable<SerializedSignal["mcp"]>) => ({
       ...(signal.mcp?.[verb] === false ? { mcp: false as const } : {}),
       ...(signal.agents?.[verb] === false ? { agents: false as const } : {}),
     });
     const endpoint: { [key: string]: SerializedEndpoint } = {};
-    if (signal.getGuards) {
+    if (FetchClient.#mountedGuards(signal, "get")) {
       endpoint[names.model] = {
         type: "query",
         args: [{ type: "param", name: names.modelId, refName: "ID" }],
@@ -486,6 +531,11 @@ export class FetchClient {
     }
     return endpoint;
   }
+  static #mountedGuards(signal: SerializedSignal, verb: "get" | "create" | "update" | "remove") {
+    if (signal.crud?.[verb] === false) return undefined;
+    if (verb === "get") return signal.getGuards;
+    return signal[`${verb}Guards`] ?? signal.cruGuards;
+  }
   #registerModelBaseEndpoint(refName: string, signal: SerializedSignal) {
     const capRefName = capitalize(refName);
     const names = {
@@ -503,15 +553,17 @@ export class FetchClient {
       this.#setHandlerFactory(key, () => this.#makeHttpFn(key, value, signal.prefix));
     });
 
-    const anyCruGuards = signal.cruGuards ?? signal.createGuards ?? signal.updateGuards ?? signal.removeGuards;
-    const updateGuards = signal.updateGuards ?? signal.cruGuards;
-    if (signal.getGuards) {
+    const getGuards = FetchClient.#mountedGuards(signal, "get");
+    const updateGuards = FetchClient.#mountedGuards(signal, "update");
+    const anyCruGuards =
+      FetchClient.#mountedGuards(signal, "create") ?? updateGuards ?? FetchClient.#mountedGuards(signal, "remove");
+    if (getGuards) {
       this.#setHandlerFactory(names.viewModel, () =>
         this.#makeModelHandleFn(refName, names.model, names.viewModel, `${refName}View`),
       );
       this.#setHandlerFactory(names.getModelView, () => this.#makeModelObjFn(refName, names.getModelView));
     }
-    if (signal.getGuards && anyCruGuards) {
+    if (getGuards && anyCruGuards) {
       this.#setHandlerFactory(names.editModel, () =>
         this.#makeModelHandleFn(refName, names.model, names.editModel, `${refName}Edit`),
       );
@@ -547,7 +599,7 @@ export class FetchClient {
           if (parentId) formData.append(fields.parentId, parentId);
           const url = FetchClient.makeHttpUrl(cap.endpointKey, endpoint, cap.prefix, new Map());
           return await this.http.post(url, formData, {
-            headers: this.#makeAuthHeaders(option),
+            headers: this.#makeRequestHeaders(option),
             baseUrl: this.#baseUrlOf(endpoint),
           });
         }) as FetchHandler,

package/fetch/client/httpClient.ts

@@ -16,6 +16,7 @@ const jsonContentType = /^application\/(?:[\w.+-]+\+)?json\b/i;
 
 const transportErrorKeyMap = {
   408: "base.error.gatewayTimeout",
+  429: "base.error.tooManyRequests",
   502: "base.error.serverUnavailable",
   503: "base.error.serverUnavailable",
   504: "base.error.gatewayTimeout",
@@ -130,12 +131,12 @@ export class HttpClient {
       try {
         return (await res.json()) as unknown;
       } catch (error) {
-        throw this.#transportError(res.status, String(error));
+        throw this.#transportError(res, String(error));
       }
     }
     const raw = await res.text();
     const parsed = HttpClient.#parseJson(raw);
-    if (parsed === undefined) throw this.#transportError(res.status, raw);
+    if (parsed === undefined) throw this.#transportError(res, raw);
     return parsed;
   }
 
@@ -147,9 +148,17 @@ export class HttpClient {
     }
   }
 
-  #transportError(status: number, detail: string): RestoredError {
+  #transportError(res: Response, detail: string): RestoredError {
+    const { status } = res;
     const error = transportErrorKeyMap[status as keyof typeof transportErrorKeyMap] ?? unexpectedResponseKey;
-    return this.#restoreError({ error, data: { status }, details: detail.slice(0, transportDetailLimit) }, status);
+    const data = status === 429 ? { status, seconds: HttpClient.#retryAfterSeconds(res) } : { status };
+    return this.#restoreError({ error, data, details: detail.slice(0, transportDetailLimit) }, status);
+  }
+
+  static #retryAfterSeconds(res: Response): number {
+    const header = res.headers.get("retry-after")?.trim() ?? "";
+    const seconds = /^\d+$/.test(header) ? Number(header) : Math.ceil((Date.parse(header) - Date.now()) / 1000);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : 60;
   }
 
   #restoreError(body: unknown, fallbackStatusCode: number): RestoredError {

package/index.ts

@@ -213,6 +213,28 @@ export interface AkanNativeDesktopConfig {
    * for a native addon signed by another team. Read when the app is signed with a team (a Developer ID).
    */
   entitlements?: Record<string, AkanNativeValue>;
+  /**
+   * macOS: the Finder window `build-desktop --installer` opens its dmg in — no toolbar or sidebar, the app's and the
+   * Applications link's icons on a background, the app's icon on the mounted disk. Without it the window is 660×400 pt
+   * on the framework's background, an arrow from the app at (180, 170) to Applications at (480, 170). A position is an
+   * icon's center in points from the window's top left; the default background lines up with the default positions.
+   */
+  dmg?: AkanNativeDmgConfig;
+}
+
+export interface AkanNativeDmgConfig {
+  /** A PNG (or TIFF) the size of the window in points, relative to the app folder; `false` for a plain window. */
+  background?: string | false;
+  /** The same picture at twice the pixels, for a Retina display. */
+  background2x?: string;
+  /** The area under the title bar, in points. Default the background's size, at 200, 120 on the screen. */
+  window?: { x?: number; y?: number; width?: number; height?: number };
+  /** Default 128. */
+  iconSize?: number;
+  /** Default 13. */
+  textSize?: number;
+  app?: { x: number; y: number };
+  applications?: { x: number; y: number };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.1",
+  "version": "3.0.2-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanOption.ts

@@ -1,6 +1,13 @@
 import type { BackendEnv, PromiseOrObject } from "akanjs/base";
 import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
-import type { AgentQuotaHook, AgentUsageHook, CrossSiteOption, GuardCls, MiddlewareCls } from "akanjs/signal";
+import type {
+  AgentQuotaHook,
+  AgentUsageHook,
+  CrossSiteOption,
+  GuardCls,
+  MiddlewareCls,
+  RateLimitSetting,
+} from "akanjs/signal";
 import type { McpServerOption } from "./akanServer";
 import type { WebProxyRegistration } from "./proxy";
 import { HostBasePathWebProxy, LocaleWebProxy } from "./proxy";
@@ -21,6 +28,7 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   #agentUsage: AgentUsageHook | null | undefined;
   #agentQuota: AgentQuotaHook | null | undefined;
   #crossSite: CrossSiteOption | undefined;
+  #getRateLimit: ((env: Env) => RateLimitSetting | false) | undefined;
   use(fnOrObject: ((env: Env) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>) {
     if (typeof fnOrObject === "function")
       this.#getUses.push(fnOrObject as (env: Env) => Record<string, PromiseOrObject<unknown>>);
@@ -65,6 +73,14 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
     this.#crossSite = crossSite;
     return this;
   }
+  /**
+   * Endpoint budgets: a default for endpoints that declare none, overrides by endpoint key, and who `by: "account"`
+   * counts. Merged in mount order, the app's last; `AKAN_RATE_LIMIT=off` still turns them all off.
+   */
+  setRateLimit(settingOrFn: RateLimitSetting | false | ((env: Env) => RateLimitSetting | false)) {
+    this.#getRateLimit = typeof settingOrFn === "function" ? settingOrFn : () => settingOrFn;
+    return this;
+  }
   /** Injected into the `LlmAdaptorRole` adaptor as the `llmOption` use; merged in mount order, the app's last. */
   setLlm<Option extends LlmOption>(llmOrFn: Option | ((env: Env) => Option)) {
     if (typeof llmOrFn === "function") this.#getLlms.push(llmOrFn);
@@ -99,6 +115,9 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   getCrossSite(): CrossSiteOption | undefined {
     return this.#crossSite;
   }
+  getRateLimit(env: Env): RateLimitSetting | false | undefined {
+    return this.#getRateLimit?.(env);
+  }
   getLlm(env: Env): LlmOption {
     return Object.assign({}, ...this.#getLlms.map((fn) => fn(env)));
   }

package/server/akanServer.ts

@@ -15,6 +15,7 @@ import type {
 import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs/signal";
 import { AgentMeter } from "../signal/agentMeter";
 import { CrossSiteGuard } from "../signal/CrossSiteGuard";
+import { EndpointRateLimit } from "../signal/endpointRateLimit";
 import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
@@ -189,6 +190,7 @@ export class AkanServer {
     this.env = { ...env };
     this.openapi = options?.openapi ?? this.openapi;
     
+    EndpointRateLimit.reset();
     libs.forEach((lib) => {
       const mcp = lib.option.getMcp(this.env);
       if (mcp !== undefined) this.setMcp(mcp);
@@ -198,7 +200,10 @@ export class AkanServer {
       if (usage !== undefined || quota !== undefined) AgentMeter.use({ usage, quota });
       const crossSite = lib.option.getCrossSite();
       if (crossSite !== undefined) CrossSiteGuard.configure(crossSite);
+      const rateLimit = lib.option.getRateLimit(this.env);
+      if (rateLimit !== undefined) EndpointRateLimit.configure(rateLimit);
     });
+    EndpointRateLimit.applyEnv(process.env.AKAN_RATE_LIMIT, getEnv().environment);
     this.setMcp(options?.mcp ?? this.mcp);
     this.serverMode = serverMode;
     

package/server/mcp/McpAuth.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { PromiseOrObject } from "akanjs/base";
-import { clientAddressFromHeaders } from "akanjs/common";
+import { SignalContext } from "../../signal/signalContext";
 import type { HttpRoutes } from "../types";
 
 export interface McpAuthOption {
@@ -157,7 +157,8 @@ export class McpAuth {
 
   static callerKey(req: Request): string {
     const token = McpAuth.#bearer(req);
-    if (!token) return `ip:${clientAddressFromHeaders(req.headers) ?? "anonymous"}`;
+    
+    if (!token) return `ip:${SignalContext.clientIpOf(req) ?? "anonymous"}`;
     const claims = McpAuth.#claims(token);
     const id = [claims?.sid, claims?.jti, claims?.sub].find((value) => typeof value === "string" && value);
     return typeof id === "string" ? `token:${id}` : `token:${createHash("sha256").update(token).digest("base64url")}`;

package/server/mcp/McpExecutionContext.ts

@@ -19,23 +19,24 @@ export class McpExecutionContext extends HttpExecutionContext {
     this.#arguments = args;
   }
 
-  override async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
+  override async readArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
     const declared = new Set(endpointInfo.args.filter(McpExecutionContext.#describable).map((arg) => arg.name));
     const undeclared = Object.keys(this.#arguments).find((name) => !declared.has(name));
     if (undeclared) throw new McpArgumentError(`Unknown argument "${undeclared}".`);
-    return endpointInfo.args.map((arg) => {
-      const value = McpExecutionContext.#lift(arg, this.#arguments[arg.name] ?? null);
-      try {
-        return deserialize(arg.argRef, arg.arrDepth, value, {
-          key: arg.name,
-          nullable: arg.option?.nullable,
-          enum: arg.enum,
-        });
-      } catch {
-        
-        throw new McpArgumentError(McpExecutionContext.#argumentMessage(arg, value));
-      }
-    });
+    return endpointInfo.args.map((arg) => McpExecutionContext.#lift(arg, this.#arguments[arg.name] ?? null));
+  }
+
+  override parseArg(arg: McpArg, value: unknown): unknown {
+    try {
+      return deserialize(arg.argRef, arg.arrDepth, value, {
+        key: arg.name,
+        nullable: arg.option?.nullable,
+        enum: arg.enum,
+      });
+    } catch {
+      
+      throw new McpArgumentError(McpExecutionContext.#argumentMessage(arg, value));
+    }
   }
 
   override makeResponse(result: unknown, endpointInfo: EndpointInfo) {