akanjs 3.0.0 → 3.0.2-rc.0

package/service/predefinedAdaptor/sql/types.ts

@@ -5,6 +5,7 @@ import type {
   DocumentQuery,
   DocumentQueryNode,
   DocumentSchema,
+  DocumentScopeOptions,
   DocumentUpdateInput,
   DocumentUpdateOperator,
   DocumentUpdateOptions,
@@ -65,6 +66,7 @@ export interface DocumentStore {
   updateManyByQuery(
     query: DocumentQuery,
     update: DocumentUpdateInput,
+    options?: DocumentScopeOptions,
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;
   removeManyByQuery(
     query: DocumentQuery,
@@ -76,19 +78,13 @@ export interface DocumentStore {
     operations: { updateOne: { filter: DocumentQuery; update: DocumentUpdateInput; upsert?: boolean } }[],
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number; upsertedId: string | null }>;
   find(query?: DocumentQuery, options?: FindManyOptions): Promise<any[]>;
-  findIds(
-    query?: DocumentQuery,
-    options?: { sort?: SortOption; skip?: number | null; limit?: number | null; sample?: number },
-  ): Promise<string[]>;
+  findIds(query?: DocumentQuery, options?: Omit<FindManyOptions, "select">): Promise<string[]>;
   findOne(query?: DocumentQuery, options?: FindOneOptions): Promise<any | null>;
-  findId(
-    query?: DocumentQuery,
-    options?: { sort?: SortOption; skip?: number | null; sample?: boolean },
-  ): Promise<string | null>;
+  findId(query?: DocumentQuery, options?: FindIdOptions): Promise<string | null>;
   pickOne(query?: DocumentQuery, options?: FindOneOptions): Promise<any>;
   pickById(id: string): Promise<any>;
-  exists(query?: DocumentQuery): Promise<string | null>;
-  count(query?: DocumentQuery): Promise<number>;
+  exists(query?: DocumentQuery, options?: DocumentScopeOptions): Promise<string | null>;
+  count(query?: DocumentQuery, options?: DocumentScopeOptions): Promise<number>;
   insight(query?: DocumentQuery): Promise<any>;
   hydrate(data: DocumentRecord, originalData?: DocumentRecord, options?: { track?: boolean }): any;
   /** A document as text that another process turns back into the same document. */
@@ -156,14 +152,20 @@ export type MutableDocumentRecord = Record<string, unknown>;
 export type FieldMap = Record<string, { getProps: () => Record<string, unknown>; [key: string]: unknown }>;
 export type SortOption = Record<string, 1 | -1> | null | undefined;
 export type ProjectionOption = Partial<Record<string, boolean>> | null | undefined;
-export type FindManyOptions = {
+export type FindManyOptions = DocumentScopeOptions & {
   sort?: SortOption;
   skip?: number | null;
   limit?: number | null;
   sample?: number;
   select?: ProjectionOption;
 };
-export type FindOneOptions = { sort?: SortOption; skip?: number | null; sample?: boolean; select?: ProjectionOption };
+export type FindOneOptions = DocumentScopeOptions & {
+  sort?: SortOption;
+  skip?: number | null;
+  sample?: boolean;
+  select?: ProjectionOption;
+};
+export type FindIdOptions = DocumentScopeOptions & { sort?: SortOption; skip?: number | null; sample?: boolean };
 export type WriteHookOptions = { runSaveHooks?: boolean; crudType?: "update" | "remove" };
 export type QueryOperatorName = Extract<DocumentQueryNode, { kind: "op" }>["op"];
 export interface SqliteDocumentRow {

package/service/rateLimiter.ts

@@ -0,0 +1,80 @@
+import { type Dayjs, dayjs } from "akanjs/base";
+import { Logger } from "akanjs/common";
+
+export interface RateCounter {
+  incr(topic: string, key: string, by?: number, option?: { expireAt?: Dayjs }): Promise<number>;
+}
+
+export interface RateBudget {
+  calls: number;
+  windowMs: number;
+}
+
+export type RateVerdict = { ok: true } | { ok: false; retryAfterMs: number };
+
+interface RateWindow {
+  start: number;
+  count: number;
+  windowMs: number;
+}
+
+export class RateLimiter {
+  static readonly #logger = new Logger("RateLimiter");
+  static readonly #sweepEveryMs = 60_000;
+
+  readonly #topic: string;
+  readonly #shared: RateCounter | null;
+  readonly #windows = new Map<string, RateWindow>();
+  #sweptAt = 0;
+  #sharedFailed = false;
+
+  constructor(shared: RateCounter | null = null, { topic = "rate" }: { topic?: string } = {}) {
+    this.#shared = shared;
+    this.#topic = topic;
+  }
+
+  get isShared() {
+    return this.#shared !== null;
+  }
+
+  async consume(key: string, budget: RateBudget, now = Date.now()): Promise<RateVerdict> {
+    const calls = Math.max(1, Math.floor(budget.calls));
+    const windowMs = Math.max(1, Math.floor(budget.windowMs));
+    this.#sweep(now);
+    if (this.#shared) {
+      const window = Math.floor(now / windowMs);
+      const end = (window + 1) * windowMs;
+      try {
+        const count = await this.#shared.incr(this.#topic, `${key}:${windowMs}:${window}`, 1, {
+          expireAt: dayjs(end + windowMs),
+        });
+        this.#sharedFailed = false;
+        return count > calls ? { ok: false, retryAfterMs: Math.max(1, end - now) } : { ok: true };
+      } catch (error) {
+        if (!this.#sharedFailed)
+          RateLimiter.#logger.warn(
+            `Rate limit "${this.#topic}" cannot reach the cache, so each instance counts its own window until it can: ${String(error)}`,
+          );
+        this.#sharedFailed = true;
+      }
+    }
+    const bucket = this.#windowOf(`${key}:${windowMs}`, windowMs, now);
+    if (bucket.count >= calls) return { ok: false, retryAfterMs: Math.max(1, bucket.start + windowMs - now) };
+    bucket.count += 1;
+    return { ok: true };
+  }
+
+  #windowOf(key: string, windowMs: number, now: number) {
+    const found = this.#windows.get(key);
+    if (found && now - found.start < windowMs) return found;
+    const bucket: RateWindow = { start: now, count: 0, windowMs };
+    this.#windows.set(key, bucket);
+    return bucket;
+  }
+
+  #sweep(now: number) {
+    if (now - this.#sweptAt < RateLimiter.#sweepEveryMs) return;
+    this.#sweptAt = now;
+    for (const [key, bucket] of this.#windows) if (now - bucket.start >= bucket.windowMs) this.#windows.delete(key);
+  }
+}

package/signal/base.signal.ts

@@ -2,6 +2,7 @@ import { FetchClient } from "akanjs/fetch";
 import { srv } from "akanjs/service";
 import { agent } from "./agent.signal";
 import { endpoint } from "./endpoint";
+import { Public } from "./guards";
 import { internal } from "./internal";
 import { serverSignal } from "./serverSignal";
 import { SignalRegistry } from "./signalRegistry";
@@ -9,20 +10,20 @@ import { SignalRegistry } from "./signalRegistry";
 export class BaseInternal extends internal(srv.base, ({ interval, cron }) => ({})) {}
 
 export class BaseEndpoint extends endpoint(srv.base, ({ query, mutation, message, pubsub }) => ({
-  ping: query(String, { cache: 3000 }).exec(() => "ping"),
-  pingBody: mutation(String)
+  ping: query(String, { cache: 3000, guards: [Public], mcp: false }).exec(() => "ping"),
+  pingBody: mutation(String, { guards: [Public], mcp: false })
     .body("data", String)
     .exec((data) => `pingBody: ${data}`),
-  pingParam: query(String, { cache: 10000 })
+  pingParam: query(String, { cache: 10000, guards: [Public], mcp: false })
     .param("id", String)
     .exec((id) => `pingParam: ${id}`),
-  pingQuery: query(String, { nullable: true })
+  pingQuery: query(String, { nullable: true, guards: [Public], mcp: false })
     .search("id", String)
     .exec((id) => `pingQuery: ${id}`),
-  wsPing: message(String)
+  wsPing: message(String, { guards: [Public], mcp: false })
     .msg("data", String, { nullable: true })
     .exec((data) => `wsPing: ${data}`),
-  pubsubPing: pubsub(String).exec(() => {
+  pubsubPing: pubsub(String, { guards: [Public], mcp: false }).exec(() => {
   }),
 })) {}
 

package/signal/endpointRateLimit.ts

@@ -0,0 +1,159 @@
+import { Logger } from "akanjs/common";
+import { CacheAdaptorRole, type RateCounter, RateLimiter } from "akanjs/service";
+import type { EndpointInfo } from "./endpointInfo";
+import { Exception } from "./exception";
+import type { SignalContext } from "./signalContext";
+
+export interface RateLimitBudget {
+  calls: number;
+  /** 60_000 when unset. */
+  windowMs?: number;
+  /** `ip` (default) counts the caller's address; `account` counts `accountKey(account)`, else the address. */
+  by?: "ip" | "account";
+}
+
+export interface RateLimitSetting {
+  /** `false` lets every budget stand aside, as for a deployment rate-limited at its edge. */
+  enabled?: boolean;
+  /** The budget of every endpoint that declares none; unset leaves those unlimited. */
+  budget?: RateLimitBudget;
+  /** By endpoint key, over what the endpoint declares (a lib's included); `false` exempts it. */
+  endpoints?: { [key: string]: Partial<RateLimitBudget> | false };
+  /** Who `by: "account"` counts; nothing returned counts the caller's address instead. */
+  accountKey?: (account: unknown) => string | null | undefined;
+}
+
+type ResolvedBudget = Required<RateLimitBudget>;
+
+export class EndpointRateLimit {
+  static readonly #logger = new Logger("EndpointRateLimit");
+  static readonly #defaultWindowMs = 60_000;
+  static #enabled: boolean | undefined;
+  static #budget: RateLimitBudget | null = null;
+  static #endpoints: NonNullable<RateLimitSetting["endpoints"]> = {};
+  static #accountKey: NonNullable<RateLimitSetting["accountKey"]> = (account) => EndpointRateLimit.#claimOf(account);
+  static readonly #limiters = new WeakMap<object, RateLimiter>();
+  static #localLimiter: RateLimiter | null = null;
+  static readonly #warned = new Set<string>();
+
+  /** Merges over what an earlier call set, so libs configure in mount order and the app's `option.ts` goes last. */
+  static configure(setting: RateLimitSetting | false) {
+    if (setting === false) {
+      EndpointRateLimit.#enabled = false;
+      return;
+    }
+    if (setting.enabled !== undefined) EndpointRateLimit.#enabled = setting.enabled;
+    if (setting.budget) EndpointRateLimit.#budget = setting.budget;
+    if (setting.endpoints) EndpointRateLimit.#endpoints = { ...EndpointRateLimit.#endpoints, ...setting.endpoints };
+    if (setting.accountKey) EndpointRateLimit.#accountKey = setting.accountKey;
+  }
+
+  /**
+   * `off` wins over the code, `on` turns budgets on in a local environment, and `<calls>[/<seconds>]` is the default
+   * budget wherever the code names none. Unset, budgets apply everywhere but `local`.
+   */
+  static applyEnv(value: string | undefined, environment: string) {
+    const raw = value?.trim().toLowerCase() ?? "";
+    if (raw === "off" || raw === "false" || raw === "0") {
+      EndpointRateLimit.#enabled = false;
+      return;
+    }
+    const [calls, seconds] = raw.split("/").map((part) => Number(part));
+    const budget = Number.isInteger(calls) && calls > 0 ? { calls, windowMs: (seconds || 60) * 1000 } : null;
+    if (budget && !EndpointRateLimit.#budget) EndpointRateLimit.#budget = budget;
+    const switchedOn = raw === "on" || raw === "true" || raw === "1" || !!budget;
+    EndpointRateLimit.#enabled ??= switchedOn || environment !== "local";
+  }
+
+  static reset() {
+    EndpointRateLimit.#enabled = undefined;
+    EndpointRateLimit.#budget = null;
+    EndpointRateLimit.#endpoints = {};
+    EndpointRateLimit.#accountKey = (account) => EndpointRateLimit.#claimOf(account);
+    EndpointRateLimit.#localLimiter = null;
+    EndpointRateLimit.#warned.clear();
+  }
+
+  static budgetOf(key: string, endpointInfo: EndpointInfo): ResolvedBudget | null {
+    if (EndpointRateLimit.#enabled === false) return null;
+    const override = EndpointRateLimit.#endpoints[key];
+    if (override === false) return null;
+    const declared = endpointInfo.signalOption.rateLimit;
+    const base = declared === false ? null : (declared ?? EndpointRateLimit.#budget);
+    const merged = override ? { ...base, ...override } : base;
+    const calls = Math.floor(Number(merged?.calls));
+    if (!merged || !(calls >= 1)) return null;
+    const windowMs = Math.floor(Number(merged.windowMs ?? EndpointRateLimit.#defaultWindowMs));
+    return {
+      calls,
+      windowMs: windowMs >= 1 ? windowMs : EndpointRateLimit.#defaultWindowMs,
+      by: merged.by === "account" ? "account" : "ip",
+    };
+  }
+
+  /** `ip` runs before the request body is read; `account` after the middlewares resolved the caller. */
+  static async admit(context: SignalContext, phase: "ip" | "account") {
+    const budget = EndpointRateLimit.budgetOf(context.key, context.endpointInfo);
+    if (!budget || budget.by !== phase) return;
+    const caller =
+      (phase === "account" ? EndpointRateLimit.#accountOf(context) : null) ?? EndpointRateLimit.#ipOf(context);
+    const verdict = await EndpointRateLimit.#limiterOf(context).consume(`${context.key}:${caller}`, budget);
+    if (verdict.ok) return;
+    EndpointRateLimit.#warnOnce(
+      `refused:${context.key}`,
+      `"${context.key}" refused a caller over its budget of ${budget.calls} calls / ${Math.round(budget.windowMs / 1000)}s by ${budget.by}; later refusals are not logged.`,
+    );
+    throw new Exception(429, "base.error.tooManyRequests", undefined, {
+      seconds: Math.max(1, Math.ceil(verdict.retryAfterMs / 1000)),
+    });
+  }
+
+  static #accountOf(context: SignalContext) {
+    const key = EndpointRateLimit.#accountKey(context.get("account"));
+    return typeof key === "string" && key ? `account:${key}` : null;
+  }
+
+  static #ipOf(context: SignalContext) {
+    const ip = context.getClientIp();
+    if (ip) return `ip:${ip}`;
+    EndpointRateLimit.#warnOnce(
+      "unknown-ip",
+      `Rate limit cannot resolve the caller's address (first on "${context.key}"), so every such caller shares one budget. Check that the proxy in front records X-Real-IP or X-Forwarded-For and is trusted (AKAN_TRUSTED_PROXIES).`,
+    );
+    return "ip:unknown";
+  }
+
+  static #limiterOf(context: SignalContext) {
+    const cache = EndpointRateLimit.#cacheOf(context);
+    if (!cache) {
+      EndpointRateLimit.#localLimiter ??= new RateLimiter(null, { topic: "endpointRate" });
+      return EndpointRateLimit.#localLimiter;
+    }
+    const found = EndpointRateLimit.#limiters.get(cache);
+    if (found) return found;
+    const limiter = new RateLimiter(cache, { topic: "endpointRate" });
+    EndpointRateLimit.#limiters.set(cache, limiter);
+    return limiter;
+  }
+
+  static #cacheOf(context: SignalContext): (RateCounter & object) | null {
+    try {
+      return context.getAdaptor(CacheAdaptorRole) as unknown as RateCounter & object;
+    } catch {
+      return null;
+    }
+  }
+
+  static #claimOf(account: unknown) {
+    if (!account || typeof account !== "object") return null;
+    const { id, sub, sid } = account as { id?: unknown; sub?: unknown; sid?: unknown };
+    const claim = [id, sub, sid].find((value) => typeof value === "string" && value);
+    return typeof claim === "string" ? claim : null;
+  }
+
+  static #warnOnce(key: string, message: string) {
+    if (EndpointRateLimit.#warned.has(key)) return;
+    EndpointRateLimit.#warned.add(key);
+    EndpointRateLimit.#logger.warn(message);
+  }
+}

package/signal/index.ts

@@ -7,6 +7,7 @@ export * from "./base.signal";
 export { CrossSiteGuard, type CrossSiteOption } from "./CrossSiteGuard";
 export * from "./endpoint";
 export * from "./endpointInfo";
+export * from "./endpointRateLimit";
 export * from "./exception";
 export * from "./guard";
 export * from "./guards";

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 {