akanjs 3.0.1 → 3.0.2-rc.0

package/signal/middleware.ts

@@ -1,6 +1,6 @@
 import type { BackendEnv, Cls, PromiseOrObject } from "akanjs/base";
 import { Logger } from "akanjs/common";
-import { Exception } from "./exception";
+import { Exception, isExceptionLike } from "./exception";
 import type { SignalContext } from "./signalContext";
 
 export interface Middleware<Env extends BackendEnv = BackendEnv> {
@@ -34,10 +34,11 @@ export class Logging extends middleware("logging") {
         }
         return result;
       } catch (error) {
-        const duration = Date.now() - start;
-        context.adaptor.logger.error(
-          `Error ${context.endpointInfo.type}-${context.key} / ${duration}ms: ${String(error)}`,
-        );
+        const line = `Error ${context.endpointInfo.type}-${context.key} / ${Date.now() - start}ms: ${String(error)}`;
+        
+        if (isExceptionLike(error) && error.statusCode === 429) {
+          if (debug) context.adaptor.logger.debug(line);
+        } else context.adaptor.logger.error(line);
         throw error;
       }
     };

package/signal/serializer/fetch.serializer.ts

@@ -8,6 +8,7 @@ import type {
   EndpointArgProps,
   EndpointCls,
   EndpointInfo,
+  ResolvedSliceCrud,
   SerializedArg,
   SerializedEndpoint,
   SerializedFilter,
@@ -157,6 +158,7 @@ export class FetchSerializer {
         sliceCls.removeGuards !== sliceCls.cruGuards,
       ),
       ...FetchSerializer.#serializeSliceMcp(sliceCls),
+      ...FetchSerializer.#serializeSliceCrud(sliceCls),
       ...FetchSerializer.#serializeSliceAgents(sliceCls),
       endpoint: FetchSerializer.#serializeEndpoints(endpointCls),
     };
@@ -186,12 +188,21 @@ export class FetchSerializer {
   }
 
   static #serializeSliceMcp(sliceCls: SliceCls): { mcp?: SerializedSignalMcp } {
-    const mcp = Object.fromEntries(
-      Object.entries(sliceCls.mcp ?? {})
-        .filter(([, published]) => !published)
+    const mcp = FetchSerializer.#offVerbs(sliceCls.mcp);
+    return Object.keys(mcp).length ? { mcp } : {};
+  }
+
+  static #serializeSliceCrud(sliceCls: SliceCls): { crud?: SerializedSignalMcp } {
+    const crud = FetchSerializer.#offVerbs(sliceCls.crud);
+    return Object.keys(crud).length ? { crud } : {};
+  }
+
+  static #offVerbs(verbs: ResolvedSliceCrud | undefined): SerializedSignalMcp {
+    return Object.fromEntries(
+      Object.entries(verbs ?? {})
+        .filter(([, on]) => !on)
         .map(([verb]) => [verb, false]),
     ) as SerializedSignalMcp;
-    return Object.keys(mcp).length ? { mcp } : {};
   }
 
   static serializeServiceSignal(endpointCls: EndpointCls): SerializedSignal {

package/signal/signalContext.ts

@@ -1,6 +1,7 @@
 import {
   Any,
   type BackendEnv,
+  Binary,
   type Cls,
   FIELD_META,
   INTERNAL_META,
@@ -21,8 +22,9 @@ import type { Internal, InternalCls, InternalInfo, MiddlewareCls } from ".";
 import { CrossSiteGuard } from "./CrossSiteGuard";
 import { EndpointCache } from "./endpointCache";
 import type { ArgInfo, EndpointInfo, EndpointType } from "./endpointInfo";
+import { EndpointRateLimit } from "./endpointRateLimit";
 import { Exception, isExceptionLike } from "./exception";
-import { type GuardCls, guardOf } from "./guard";
+import { type GuardCls, type GuardScope, guardOf } from "./guard";
 import { SignalFailure } from "./SignalFailure";
 import { getCurrentTrace, runTraced, SignalTrace, type TraceOrigin, traceSpan } from "./trace";
 
@@ -46,6 +48,21 @@ type MiddlewareHandler = (context: SignalContext, next: () => Promise<unknown>)
 /** Request-scoped: the outermost `resolveReturn` starts one and every recursion threads it down. */
 type ResolveCache = Map<ConstantFieldTypeInput, Map<string, Promise<unknown>>>;
 
+interface SignalContextOption<Ctx, Env extends BackendEnv> {
+  endpointInfo: EndpointInfo;
+  adaptor: Adaptor;
+  registry: InjectRegistry;
+  env: Env;
+  live: LiveRegistry;
+  middleware: Map<string, MiddlewareCls>;
+  /** A caller-built context: MCP's arguments arrive as one named object, not in a URL. */
+  ctx?: Ctx;
+  /** Defaults to the transport. */
+  origin?: TraceOrigin;
+  /** Unset, the context joins the current trace or opens one that `exec()` closes. */
+  trace?: SignalTrace | null;
+}
+
 export class SignalContext<
   Ctx extends HttpExecutionContext | WebSocketExecutionContext = HttpExecutionContext | WebSocketExecutionContext,
   Env extends BackendEnv = BackendEnv,
@@ -57,40 +74,22 @@ export class SignalContext<
   adaptor: Adaptor;
   /** `mcp` for a call through the MCP endpoint. Held here, not on the trace: a null trace would let a guard fail open. */
   readonly origin: TraceOrigin;
-  args: unknown[] = [];
   internalArgs: unknown[] = [];
   trace: SignalTrace | null = null;
+  readonly #request: Bun.BunRequest | WebSocketRequest;
+  readonly #option: SignalContextOption<Ctx, Env>;
+  #rawArgs: unknown[] | null = null;
+  #args: unknown[] | null = null;
   #registry: InjectRegistry;
   #env: Env;
   #live: LiveRegistry;
   #middleware: Map<string, MiddlewareCls>;
   static #reported = new WeakSet<object>();
-  constructor(
-    key: string,
-    reqOrWsReq: Bun.BunRequest | WebSocketRequest,
-    {
-      endpointInfo,
-      adaptor,
-      registry,
-      env,
-      live,
-      middleware,
-      ctx,
-      origin,
-    }: {
-      endpointInfo: EndpointInfo;
-      adaptor: Adaptor;
-      registry: InjectRegistry;
-      env: Env;
-      live: LiveRegistry;
-      middleware: Map<string, MiddlewareCls>;
-      /** A caller-built context: MCP's arguments arrive as one named object, not in a URL. */
-      ctx?: Ctx;
-      /** Defaults to the transport. */
-      origin?: TraceOrigin;
-    },
-  ) {
+  constructor(key: string, reqOrWsReq: Bun.BunRequest | WebSocketRequest, option: SignalContextOption<Ctx, Env>) {
+    const { endpointInfo, adaptor, registry, env, live, middleware, ctx, origin, trace } = option;
     this.key = key;
+    this.#request = reqOrWsReq;
+    this.#option = option;
     this.transport = httpEndpointTypes.has(endpointInfo.type) ? "http" : "websocket";
     this.origin = origin ?? this.transport;
     this.endpointInfo = endpointInfo;
@@ -103,7 +102,10 @@ export class SignalContext<
     this.#live = live;
     this.#middleware = middleware;
     
-    this.trace = getCurrentTrace() ?? SignalTrace.create(key, endpointInfo.type, origin ?? this.transport);
+    this.trace =
+      trace !== undefined
+        ? trace
+        : (getCurrentTrace() ?? SignalTrace.create(key, endpointInfo.type, origin ?? this.transport));
     if (this.trace && this.transport === "http")
       this.trace.applyDebugHeader((reqOrWsReq as { headers?: Headers }).headers?.get?.("x-akan-debug"));
   }
@@ -120,28 +122,61 @@ export class SignalContext<
     if (!service) throw new Exception.Error(`Service "${refName}" not found in live registry`);
     return service as T;
   }
+  /** Reads the request but parses no argument: that waits for the account guards in `exec()`. */
   async init() {
 
     if (this.endpointInfo.type === "mutation" && this.transport === "http") {
       const httpCtx = this.getHttpContext();
       CrossSiteGuard.assertOrigin(httpCtx.req, httpCtx.url, this.key);
     }
+    
+    if (!this.#isLeavingRoom()) await EndpointRateLimit.admit(this, "ip");
     const start = this.trace ? performance.now() : 0;
-    this.args = await this.ctx.getArgs(this.endpointInfo);
-    this.trace?.recordSpan("argParse", performance.now() - start);
+    this.#rawArgs = await this.ctx.readArgs(this.endpointInfo);
+    this.trace?.recordSpan("argRead", performance.now() - start);
     return this;
   }
+  /** Parsed on first read, so a guard or middleware that reads one still gets it; a parser runs at most once per call. */
+  get args(): unknown[] {
+    this.#args ??= this.#parseArgs();
+    return this.#args;
+  }
+  set args(args: unknown[]) {
+    this.#args = args;
+  }
+  #parseArgs(): unknown[] {
+    const raw = this.#rawArgs;
+    if (!raw) return [];
+    const start = this.trace ? performance.now() : 0;
+    const args = this.endpointInfo.args.map((arg, idx) => this.ctx.parseArg(arg, raw[idx]));
+    this.trace?.recordSpan("argParse", performance.now() - start);
+    return args;
+  }
+  #isLeavingRoom() {
+    return this.transport === "websocket" && this.getWebSocketContext().eventType === "unsubscribe";
+  }
   
-  async #checkGuards() {
+  async #checkGuards(scope?: GuardScope) {
     for (const GuardCls of this.endpointInfo.signalOption.guards ?? []) {
+      if (scope && (GuardCls.scope === "account" ? "account" : "resource") !== scope) continue;
       if (!(await guardOf(GuardCls).canPass(this)))
         throw new Exception.Forbidden(`Access denied by guard: ${GuardCls.name}`);
     }
   }
-  /** Re-checks the guards of a subscribed room outside a request; only global middlewares (account resolution) run. */
+  /**
+   * Re-checks the guards of a subscribed room outside a request; only global middlewares (account resolution) run. On
+   * a fresh context, so a guard that memoizes per context cannot replay the verdict it gave at subscribe.
+   */
   async authorize(): Promise<boolean> {
+    const fresh = new SignalContext<Ctx, Env>(this.key, this.#request, {
+      ...this.#option,
+      ctx: undefined,
+      trace: null,
+    });
+    fresh.#rawArgs = this.#rawArgs;
+    fresh.#args = this.#args;
     try {
-      await this.#withMiddleware(async () => await this.#checkGuards(), { endpointMiddlewares: false })();
+      await fresh.#withMiddleware(async () => await fresh.#checkGuards(), { endpointMiddlewares: false })();
       return true;
     } catch {
       return false;
@@ -239,11 +274,16 @@ export class SignalContext<
     if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
     const coreExec = async () => {
       if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
+      await EndpointRateLimit.admit(this, "account");
       if (this.trace) {
-        await traceSpan("guards", () => this.#checkGuards());
+        await traceSpan("guards", () => this.#checkGuards("account"));
         const account = this.get<{ id?: unknown }>("account");
         if (typeof account?.id === "string") this.trace.setAttr("userId", account.id);
-      } else await this.#checkGuards();
+      } else await this.#checkGuards("account");
+      
+      this.#args ??= this.#parseArgs();
+      if (this.trace) await traceSpan("resourceGuards", () => this.#checkGuards("resource"));
+      else await this.#checkGuards("resource");
       if (this.endpointInfo.internalArgs.length > 0) {
         this.internalArgs = await Promise.all(
           this.endpointInfo.internalArgs.map((arg) => {
@@ -271,11 +311,21 @@ export class SignalContext<
     };
     if (!this.trace) {
       const resolved = await SignalContext.resolveReturn(result, resolveOption);
-      return this.ctx.makeResponse(this.#settleUndefined(resolved), this.endpointInfo);
+      return this.ctx.makeResponse(this.#settle(resolved), this.endpointInfo);
     }
     const resolved = await traceSpan("resolveReturn", () => SignalContext.resolveReturn(result, resolveOption));
-    return await traceSpan("serialize", async () =>
-      this.ctx.makeResponse(this.#settleUndefined(resolved), this.endpointInfo),
+    return await traceSpan("serialize", async () => this.ctx.makeResponse(this.#settle(resolved), this.endpointInfo));
+  }
+  #settle(resolved: unknown) {
+    this.#refuseBytesThroughAny(resolved);
+    return this.#settleUndefined(resolved);
+  }
+  
+  #refuseBytesThroughAny(resolved: unknown) {
+    if (this.endpointInfo.returns.returnRef !== Any) return;
+    if (!(resolved instanceof ArrayBuffer) && !ArrayBuffer.isView(resolved)) return;
+    throw new Error(
+      `${this.endpointInfo.type} ${this.key} returns bytes through Any, which JSON cannot carry: declare Binary as its return`,
     );
   }
 
@@ -332,12 +382,17 @@ export class SignalContext<
             path: endpointInfo.getPath(key),
             timestamp: new Date().toISOString(),
           }),
-          { status: error.statusCode, headers: { "Content-Type": "application/json" } },
+          { status: error.statusCode, headers: SignalContext.#exceptionHeaders(error) },
         );
       }
       return SignalFailure.response(error, { path: endpointInfo.getPath(key) });
     }
   }
+  static #exceptionHeaders(error: { statusCode: number }): Record<string, string> {
+    const seconds = (error as { data?: { seconds?: unknown } }).data?.seconds;
+    if (error.statusCode !== 429 || typeof seconds !== "number") return { "Content-Type": "application/json" };
+    return { "Content-Type": "application/json", "Retry-After": String(Math.max(1, Math.ceil(seconds))) };
+  }
   static async resolveReturn(
     value: unknown,
     {
@@ -573,16 +628,24 @@ export class SignalContext<
    * `::ffff:`; `null`, never a placeholder, when neither is known.
    */
   getClientIp(): string | null {
-    if (this.transport === "http") {
-      const { req } = this.getHttpContext();
-      
-      const peer = SignalContext.#httpPeer?.(req);
-      return TrustedProxy.clientAddress(req.headers, peer === undefined ? undefined : (peer?.address ?? null));
-    }
+    if (this.transport === "http") return SignalContext.clientIpOf(this.getHttpContext().req);
     const { ws } = this.getWebSocketContext<{ headers?: Headers }>();
     if (!ws.data.headers) return ws.remoteAddress ? normalizeIpAddress(ws.remoteAddress) : null;
     return TrustedProxy.clientAddress(ws.data.headers, ws.remoteAddress);
   }
+  static #carriedIps = new WeakMap<Request, string | null>();
+  /** A request a proxy rebuilt has no socket behind it for `requestIP`, so it keeps the address its original resolved. */
+  static carryClientIp(target: Request, source: Request) {
+    if (target !== source) SignalContext.#carriedIps.set(target, SignalContext.clientIpOf(source));
+  }
+  /** `getClientIp` for a request no context wraps, as the MCP router and the page renderer hold one. */
+  static clientIpOf(req: Request): string | null {
+    const carried = SignalContext.#carriedIps.get(req);
+    if (carried !== undefined) return carried;
+    
+    const peer = SignalContext.#httpPeer?.(req);
+    return TrustedProxy.clientAddress(req.headers, peer === undefined ? undefined : (peer?.address ?? null));
+  }
   /** The caller's source port as the nearest proxy recorded it, else this socket's own. */
   getClientPort(): number | null {
     if (this.transport === "http") {
@@ -668,6 +731,11 @@ export class HttpExecutionContext<Appended = unknown> {
     }
   }
   async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
+    const raw = await this.readArgs(endpointInfo);
+    return endpointInfo.args.map((arg, idx) => this.parseArg(arg, raw[idx]));
+  }
+  /** Each argument as the request carries it; `parseArg` turns one into its declared type. */
+  async readArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
     if (endpointInfo.args.length === 0) return [];
     this.params = this.req.params;
     const hasBodyArgs = endpointInfo.args.some((arg) => arg.type === "body");
@@ -694,29 +762,42 @@ export class HttpExecutionContext<Appended = unknown> {
       }
     }
 
-    const args = endpointInfo.args.map((arg) => {
+    return endpointInfo.args.map((arg) => {
       switch (arg.type) {
         case "param":
-          return deserializeArg(arg, this.params[arg.name]);
+          return this.params[arg.name];
         case "body":
-          if (arg.argRef === Upload) return this.body[arg.name];
-          return deserializeArg(arg, this.body[arg.name]);
-        case "search": {
-          const raw = arg.arrDepth ? this.url.searchParams.getAll(arg.name) : this.url.searchParams.get(arg.name);
-          const value = arg.argRef === Any ? HttpExecutionContext.#parseAny(arg.name, raw) : raw;
-          const result = deserializeArg(arg, value);
-          this.searchParams[arg.name] = result;
-          return result;
-        }
+          return this.body[arg.name];
+        case "search":
+          return arg.arrDepth ? this.url.searchParams.getAll(arg.name) : this.url.searchParams.get(arg.name);
         default:
           return undefined;
       }
     });
-    return args;
+  }
+  parseArg(arg: ArgInfo, raw: unknown): unknown {
+    switch (arg.type) {
+      case "param":
+        return deserializeArg(arg, raw);
+      case "body":
+        return arg.argRef === Upload ? raw : deserializeArg(arg, raw);
+      case "search": {
+        const value =
+          arg.argRef === Any ? HttpExecutionContext.#parseAny(arg.name, raw as string | string[] | null) : raw;
+        const result = deserializeArg(arg, value);
+        this.searchParams[arg.name] = result;
+        return result;
+      }
+      default:
+        return undefined;
+    }
   }
   makeResponse(result: unknown, endpointInfo: EndpointInfo) {
     if (result instanceof Response) return result;
     if (endpointInfo.returns.arrDepth === 0 && PrimitiveRegistry.has(endpointInfo.returns.returnRef as Cls)) {
+      
+      if (endpointInfo.returns.returnRef === Binary && result instanceof Uint8Array)
+        return this.res.json(Binary.serializeValue(result));
       return this.res.json(result);
     }
     const value = serialize(endpointInfo.returns.returnRef, endpointInfo.returns.arrDepth, result, "object", {
@@ -740,16 +821,16 @@ export class WebSocketExecutionContext<Appended = unknown> {
     this.eventType = wsReq.eventType;
   }
   async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
-    const args = endpointInfo.args.map((arg, idx) => {
-      switch (arg.type) {
-        case "msg":
-        case "room":
-          return deserializeArg(arg, this.data[idx]);
-        default:
-          return undefined;
-      }
-    });
-    return args;
+    const raw = await this.readArgs(endpointInfo);
+    return endpointInfo.args.map((arg, idx) => this.parseArg(arg, raw[idx]));
+  }
+  async readArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
+    return endpointInfo.args.map((arg, idx) =>
+      arg.type === "msg" || arg.type === "room" ? this.data[idx] : undefined,
+    );
+  }
+  parseArg(arg: ArgInfo, raw: unknown): unknown {
+    return arg.type === "msg" || arg.type === "room" ? deserializeArg(arg, raw) : undefined;
   }
   makeResponse(result: unknown, endpointInfo: EndpointInfo) {
     return serialize(endpointInfo.returns.returnRef, endpointInfo.returns.arrDepth, result, "object", {

package/signal/slice.ts

@@ -39,6 +39,7 @@ export type SliceCls<
   updateGuards: GuardCls[];
   removeGuards: GuardCls[];
   mcp: ResolvedSliceMcp;
+  crud: ResolvedSliceCrud;
 };
 
 /** `root` is absent: it rides on the root slice itself. */
@@ -49,14 +50,26 @@ export interface ResolvedSliceMcp {
   remove: boolean;
 }
 
+/** Which generated verbs the server mounts: a verb whose guards resolve to none (or `false`) has no route at all. */
+export interface ResolvedSliceCrud {
+  get: boolean;
+  create: boolean;
+  update: boolean;
+  remove: boolean;
+}
+
 interface RootSliceOption {
+  /**
+   * `false` (or no guard at all) mounts no generated endpoint for that verb, which is the only way to take one off
+   * HTTP: `mcp: { cru: false }` merely keeps it off the agent shelf. `create`/`update`/`remove` fall back to `cru`.
+   */
   guards?: {
     root?: GuardCls | GuardCls[];
-    get?: GuardCls | GuardCls[];
-    cru?: GuardCls | GuardCls[];
-    create?: GuardCls | GuardCls[];
-    update?: GuardCls | GuardCls[];
-    remove?: GuardCls | GuardCls[];
+    get?: GuardCls | GuardCls[] | false;
+    cru?: GuardCls | GuardCls[] | false;
+    create?: GuardCls | GuardCls[] | false;
+    update?: GuardCls | GuardCls[] | false;
+    remove?: GuardCls | GuardCls[] | false;
   };
   /**
    * Keyed like `guards`, for the root slice and generated CRUD only; `create`/`update`/`remove` fall back to `cru`
@@ -148,14 +161,21 @@ export function slice<
   if (!srv.cnst || !srv.db) throw new Error("cnst and db are required");
   const filterRef = srv.db.filter;
   const init = buildSlice(srv.srv.refName, srv.cnst.input, srv.cnst.full, srv.cnst.light, srv.cnst.insight, filterRef);
-  const toGuards = (guard?: GuardCls | GuardCls[]) => (guard ? (Array.isArray(guard) ? guard : [guard]) : []);
+  const toGuards = (guard?: GuardCls | GuardCls[] | false) => (guard ? (Array.isArray(guard) ? guard : [guard]) : []);
   const rootGuards = toGuards(option.guards?.root);
   const getGuards = toGuards(option.guards?.get);
   const cruGuards = toGuards(option.guards?.cru);
   
-  const createGuards = option.guards?.create ? toGuards(option.guards.create) : cruGuards;
-  const updateGuards = option.guards?.update ? toGuards(option.guards.update) : cruGuards;
-  const removeGuards = option.guards?.remove ? toGuards(option.guards.remove) : cruGuards;
+  const createGuards = option.guards?.create !== undefined ? toGuards(option.guards.create) : cruGuards;
+  const updateGuards = option.guards?.update !== undefined ? toGuards(option.guards.update) : cruGuards;
+  const removeGuards = option.guards?.remove !== undefined ? toGuards(option.guards.remove) : cruGuards;
+
+  const crud: ResolvedSliceCrud = {
+    get: getGuards.length > 0,
+    create: createGuards.length > 0,
+    update: updateGuards.length > 0,
+    remove: removeGuards.length > 0,
+  };
   const mcpOption =
     typeof option.mcp === "boolean" ? { root: option.mcp, get: option.mcp, cru: option.mcp } : option.mcp;
   const cruMcp = mcpOption?.cru !== false;
@@ -179,6 +199,7 @@ export function slice<
     static updateGuards = updateGuards;
     static removeGuards = removeGuards;
     static mcp = mcp;
+    static crud = crud;
     
     static [SLICE_META] = Object.assign(
       {},

package/signal/types.ts

@@ -1,5 +1,6 @@
 import type { DefaultPrimitiveName, UnCls } from "akanjs/base";
 import type { ServiceModel } from "akanjs/service";
+import type { RateLimitBudget } from "./endpointRateLimit";
 import type { GuardCls } from "./guard";
 import type { MiddlewareCls } from "./middleware";
 import type { SliceCls } from "./slice";
@@ -94,6 +95,11 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
    * internal argument may carry one (those answer per caller), and the lookup runs after the guards.
    */
   cache?: number;
+  /**
+   * Calls per caller per window, refused with 429 `base.error.tooManyRequests`. `by: "ip"` is counted before the body
+   * is read, `by: "account"` after the middlewares and before the guards; `false` exempts it from the app's default.
+   */
+  rateLimit?: RateLimitBudget | false;
   guards?: GuardCls[];
   middlewares?: MiddlewareCls[];
   prefix?: false | string;
@@ -181,6 +187,8 @@ export interface SerializedSignal {
   removeGuards?: string[];
   /** Generated CRUD verbs kept off the agent shelf, carried here because `FetchClient.getBaseEndpoint` synthesizes them. */
   mcp?: SerializedSignalMcp;
+  /** Generated CRUD verbs the server does not mount at all, so no client synthesizes them. */
+  crud?: SerializedSignalMcp;
   /** Which generated CRUD verbs a person-only guard protects, by the same verb map; only the `false` keys travel. */
   agents?: SerializedSignalMcp;
 }

package/test/signalTestRuntime.ts

@@ -1,5 +1,5 @@
 import type { BackendEnv, BaseEnv } from "akanjs/base";
-import type { FetchProxy } from "akanjs/fetch";
+import { FetchClient, type FetchProxy } from "akanjs/fetch";
 import type { AkanLib } from "akanjs/server";
 import { type TestEnv, TestServer, type TestServerOptions } from "./testServer";
 
@@ -113,6 +113,7 @@ export const setupSignalTestTarget = async <Fetch = FetchProxy>(
       storage: "memory",
       ...resolvedOptions,
     });
+    FetchClient.useTestClientIps();
     await testServer.init();
     currentContext = {
       fetch: target.fetch,

package/types/base/base.d.ts

@@ -23,7 +23,7 @@ export type EnumInstance<RefName extends string = string, T = string | number> =
 /** True for a `class X extends enumOf(...) {}`, not for the bare `enumOf(...)` result. */
 export declare const isEnum: (enumRef: Cls) => boolean;
 /** `type` is `String` for string values, else `Int` when every value is an integer, else `Float`. */
-export declare const enumOf: <RefName extends string, T = string | number>(refName: RefName, values: readonly T[]) => EnumInstance<RefName, T>;
+export declare const enumOf: <RefName extends string, const T = string | number>(refName: RefName, values: readonly T[]) => EnumInstance<RefName, T>;
 export declare class DataList<Light extends {
     id: string;
 }> {

package/types/client/cookie.d.ts

@@ -9,7 +9,7 @@ export declare const cookies: () => Map<string, {
     name: string;
     value: string;
 }>;
-export declare const setCookie: (key: string, value: string, options?: CookieOptions) => void;
+export declare const setCookie: (key: string, value: string, { path, sameSite, secure }?: CookieOptions) => void;
 /** Reads through `cookies()` on both sides: a hand-rolled `split("=")` cuts base64 padding and skips the `j:` form. */
 export declare const getCookie: (key: string) => string | undefined;
 export declare const removeCookie: (key: string, options?: {

package/types/common/Logger.d.ts

@@ -77,6 +77,8 @@ export declare class Logger {
     static formatAttrs(attrs: LogAttrs): string;
     /** A flight-recorder or `x-akan-debug` record passes every floor between here and the reader. */
     static isPromoted(record: LogRecord): boolean;
+    /** `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?: number): string;
     static redactAttrs(attrs: LogAttrs): LogAttrs;
     static emit({ level, name, message, context, attrs }: LoggerEmitInput): void;
     /** Writes a failed request's flight-recorder records past the console level, each marked `flight`. */

package/types/dictionary/base.dictionary.d.ts

@@ -1 +1 @@
-export declare const baseDictionary: import("./dictInfo.d.ts").ServiceDictInfo<[string, string], "ping" | "pingBody" | "pingParam" | "pingQuery" | "wsPing" | "pubsubPing", "serverUnreachable" | "serverUnavailable" | "gatewayTimeout" | "unexpectedResponse", "edit" | "error" | "ok" | "approve" | "remove" | "unauthorized" | "save" | "refresh" | "password" | "agent" | "skip" | "stop" | "send" | "success" | "somethingWrong" | "connecting" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentToolCard" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachReading" | "agentReferenceRemove" | "agentReferenceFailed" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentQueue" | "agentQueuePlaceholder" | "agentQueued" | "agentQueueEdit" | "agentQueueCancel" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentTokensOf" | "agentCompactsAt" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "noSelection" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "draftConflict" | "draftApplied" | "draftRestore" | "draftDiscard" | "draftStartOver" | "new" | "view">;
+export declare const baseDictionary: import("./dictInfo.d.ts").ServiceDictInfo<[string, string], "ping" | "pingBody" | "pingParam" | "pingQuery" | "wsPing" | "pubsubPing", "serverUnreachable" | "serverUnavailable" | "gatewayTimeout" | "tooManyRequests" | "unexpectedResponse" | "immutableField", "edit" | "error" | "ok" | "retry" | "approve" | "remove" | "unauthorized" | "save" | "refresh" | "password" | "agent" | "skip" | "stop" | "send" | "success" | "somethingWrong" | "connecting" | "connected" | "serverDisconnected" | "refreshing" | "tryReconnecting" | "serverHasProblem" | "checkServerStatus" | "cameraPromptHeader" | "cameraPromptPhoto" | "cameraPromptPicture" | "cameraPromptCancel" | "failed" | "processing" | "processed" | "noData" | "invalidValueError" | "emailInvalidError" | "phoneInvalidError" | "cancel" | "pageLoadFailed" | "agentIntro" | "agentPlaceholder" | "agentClear" | "agentQuestion" | "agentToolCard" | "agentAnswer" | "agentListen" | "agentVoiceFailed" | "agentAttach" | "agentAttachRemove" | "agentAttachReading" | "agentReferenceRemove" | "agentReferenceFailed" | "agentAttachTooLarge" | "agentAttachUnsupported" | "agentAttachDuplicate" | "agentAttachTooMany" | "agentAttachTooMuch" | "agentAnswerNeeded" | "agentQueue" | "agentQueuePlaceholder" | "agentQueued" | "agentQueueEdit" | "agentQueueCancel" | "agentToolDone" | "agentToolFailed" | "agentToolRunning" | "agentToolResult" | "agentTokens" | "agentTokensOf" | "agentCompactsAt" | "agentSummarizing" | "agentContinue" | "agentKeepGoing" | "agentCmdNew" | "agentCmdRetry" | "agentCmdCompact" | "agentCmdCopy" | "agentCmdHelp" | "agentCmdTools" | "agentHelpIntro" | "agentHelpNote" | "agentNothingToRetry" | "agentNothingToCompact" | "agentCompacted" | "agentSummary" | "agentBusy" | "agentCopied" | "agentCopyFailed" | "agentToolsHead" | "agentToolsState" | "decline" | "confirmClose" | "textTooShortError" | "textTooLongError" | "selectTooShortError" | "selectTooLongError" | "numberTooSmallError" | "numberTooBigError" | "passwordNotMatchError" | "selectDateError" | "priceUnit" | "passwordConfirm" | "noOptions" | "noSelection" | "addModel" | "createModel" | "createSuccess" | "updateModel" | "removeModel" | "updateSuccess" | "removeSuccess" | "sureToRemove" | "irreversibleOps" | "typeNameToRemove" | "yesRemove" | "removeMsg" | "confirmMsg" | "perPage" | "cardView" | "tableView" | "exportCsv" | "exportJson" | "actions" | "draftConflict" | "draftApplied" | "draftRestore" | "draftDiscard" | "draftStartOver" | "new" | "view">;