akanjs 3.0.1 → 3.0.2-rc.0

package/service/predefinedAdaptor/sql/SqlDocumentStore.ts

@@ -1,11 +1,13 @@
 import { DEFAULT_VALUE, dayjs, FIELD_META } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import { type ConstantModel, freshPrimitiveValue, getDefault } from "akanjs/constant";
+import { Err } from "akanjs/dictionary";
 import {
   createDocumentId,
   type DatabaseModel,
   type DocumentQuery,
   type DocumentSchema,
+  type DocumentScopeOptions,
   type DocumentUpdate,
   type DocumentUpdateInput,
   type DocumentUpdateNode,
@@ -13,6 +15,7 @@ import {
   documentQueryHelper,
   isDocumentId,
   isDocumentUpdateNode,
+  LiveRowScope,
   NoDocumentError,
   resolveDocumentUpdate,
   sanitizeJson,
@@ -26,6 +29,7 @@ import {
   type DocumentDatabaseOwner,
   type DocumentRecord,
   type FieldMap,
+  type FindIdOptions,
   type FindManyOptions,
   type FindOneOptions,
   MODIFICATION_STATE,
@@ -59,6 +63,9 @@ interface DeclaredIndex {
   next: string;
   metaKey: string;
   hash: string;
+  fields: Record<string, unknown>;
+  /** A key ordered neither 1 nor -1, as MongoDB's `"text"`: no SQL index here stands for it. */
+  unbuilt: boolean;
   create: (name: string, concurrently: boolean) => string;
 }
 
@@ -79,6 +86,8 @@ export class SqlDocumentStore {
   static readonly #logger = new Logger("SqlDocumentStore");
   /** The row a document was read or last written as. */
   static readonly #storedRow = Symbol("akan.storedRow");
+  /** Set on a document read as removed, which only a `withRemoved` read hands out. */
+  static readonly #readRemoved = Symbol("akan.readRemoved");
 
   constructor(
     private readonly owner: DocumentDatabaseOwner,
@@ -102,7 +111,8 @@ export class SqlDocumentStore {
 
   async #ensure() {
     this.assertValidRefName(this.table);
-    const indexes = await this.#declaredIndexes();
+    const declared = await this.#declaredIndexes();
+    const indexes = declared.filter((index) => !index.unbuilt);
     const createSchema = async () => {
       const db = this.owner.getConnection();
       const existed = !!this.owner.buildIndexConcurrently && !!(await this.owner.hasTable?.(this.table));
@@ -121,6 +131,7 @@ export class SqlDocumentStore {
         `table:${this.table}`,
         await descriptorHash({ table: this.table, columns: ["id", "createdAt", "updatedAt", "removedAt", "_doc"] }),
       );
+      for (const index of declared) if (index.unbuilt) await this.#skipUnbuiltIndex(index, indexes);
       const concurrent: (DeclaredIndex & { replace: boolean })[] = [];
       for (const index of indexes) {
         const stored = await this.owner.getMeta(index.metaKey);
@@ -157,16 +168,21 @@ export class SqlDocumentStore {
         const declared = index.name ?? `${this.table}_${Object.keys(index.fields).map(toSafeRefName).join("_")}_${idx}`;
         this.assertValidRefName(declared);
         const name = this.dialect.indexName(declared);
-        const columns = Object.keys(index.fields).map((path) => ({
-          path,
-          expr: this.compiler.fieldExpr(path),
-          isArray: this.compiler.isArrayPath(path),
-        }));
+        const unbuilt = Object.values(index.fields).some((order) => order !== 1 && order !== -1);
+        const columns = unbuilt
+          ? []
+          : Object.keys(index.fields).map((path) => ({
+              path,
+              expr: this.compiler.fieldExpr(path),
+              isArray: this.compiler.isArrayPath(path),
+            }));
         return {
           name,
           next: this.dialect.indexName(`${declared}_next`),
           metaKey: `index:${this.table}:${name}`,
           hash: await descriptorHash(index),
+          fields: index.fields,
+          unbuilt,
           create: (target: string, concurrently: boolean) =>
             this.dialect.createIndex({
               name: target,
@@ -180,6 +196,23 @@ export class SqlDocumentStore {
     );
   }
 
+  async #skipUnbuiltIndex(index: DeclaredIndex, built: DeclaredIndex[]) {
+    const dropped =
+      (await this.owner.getMeta(index.metaKey)) === index.hash && !built.some(({ name }) => name === index.name);
+    if (dropped) {
+      await this.owner.getConnection().execute(`DROP INDEX IF EXISTS ${quoteIdent(index.name)}`);
+      
+      await this.owner.setMeta(index.metaKey, "");
+    }
+    const paths = Object.keys(index.fields);
+    SqlDocumentStore.#logger.warn(
+      `Index ${JSON.stringify(index.fields)} on ${this.table} is not built: only 1 and -1 order a key, and "text" is ` +
+        `MongoDB's text index, which as a B-tree would copy each whole value and fail long writes on Postgres. Search ` +
+        `${paths.join(", ")} through the full-text role, field(String, { text: "desc" }), or declare ` +
+        `{ ${paths[0]}: 1 } to look it up by equality.${dropped ? ` Dropped ${index.name}, which an earlier boot built from it.` : ""}`,
+    );
+  }
+
   async #replaceIndex(index: DeclaredIndex) {
     const rebuild = async () => {
       const db = this.owner.getConnection();
@@ -263,9 +296,22 @@ export class SqlDocumentStore {
   }
 
   async updateOneByQuery(query: DocumentQuery, update: DocumentUpdateInput, options: DocumentUpdateOptions = {}) {
+    if (options.upsert && options.withRemoved)
+      throw new Error(
+        `updateOneByQuery on "${this.table}" takes upsert or { withRemoved: true }, not both: a match would stay removed while a miss inserts a live row`,
+      );
+    return await this.#updateOne(query, update, options, "updateOneByQuery");
+  }
+
+  async #updateOne(
+    query: DocumentQuery,
+    update: DocumentUpdateInput,
+    options: DocumentUpdateOptions,
+    operation: string,
+  ) {
     const resolved = resolveDocumentUpdate(update);
     const { assignments, params } = this.compiledUpdate(resolved);
-    const { where, params: whereParams } = this.writeQuery(query, "updateOneByQuery");
+    const { where, params: whereParams } = this.writeQuery(query, operation, options);
     const subquery = `SELECT ${quoteIdent("id")} FROM ${quoteIdent(this.table)} WHERE ${where} ORDER BY ${this.compiler.orderBy()} LIMIT 1`;
     const sql = `UPDATE ${quoteIdent(this.table)} SET ${assignments.join(", ")} WHERE ${quoteIdent("id")} IN (${subquery})`;
     const changes = this.dialect.affectedRows(
@@ -282,9 +328,18 @@ export class SqlDocumentStore {
     return { acknowledged: true, matchedCount: 0, modifiedCount: 1, upsertedId: inserted.id };
   }
 
-  async updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput) {
+  async updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput, options: DocumentScopeOptions = {}) {
+    return await this.#updateMany(query, update, options, "updateManyByQuery");
+  }
+
+  async #updateMany(
+    query: DocumentQuery,
+    update: DocumentUpdateInput,
+    options: DocumentScopeOptions,
+    operation: string,
+  ) {
     const { assignments, params } = this.compiledUpdate(resolveDocumentUpdate(update));
-    const { where, params: whereParams } = this.writeQuery(query, "updateManyByQuery");
+    const { where, params: whereParams } = this.writeQuery(query, operation, options);
     const sql = `UPDATE ${quoteIdent(this.table)} SET ${assignments.join(", ")} WHERE ${where}`;
     const changes = this.dialect.affectedRows(
       await this.owner
@@ -297,12 +352,12 @@ export class SqlDocumentStore {
 
   async removeManyByQuery(query: DocumentQuery) {
     
-    return this.updateManyByQuery(query, { removedAt: dayjs() });
+    return await this.#updateMany(query, { removedAt: dayjs() }, {}, "removeManyByQuery");
   }
 
   async removeOneByQuery(query: DocumentQuery) {
     
-    return this.updateOneByQuery(query, { removedAt: dayjs() });
+    return await this.#updateOne(query, { removedAt: dayjs() }, {}, "removeOneByQuery");
   }
 
   private compiledUpdate(update: DocumentUpdate) {
@@ -339,20 +394,24 @@ export class SqlDocumentStore {
       const rows = await this.prepareStmt(
         `SELECT ${this.projectionSql(projection)} ${tail}`,
       ).all<ProjectedSqliteDocumentRow>(...args);
-      return rows.map((row) => this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }));
+      return rows.map((row) =>
+        this.#readAs(this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }), row),
+      );
     }
     const rows = await this.prepareStmt(`SELECT ${star} ${tail}`).all<SqliteDocumentRow>(...args);
-    return rows.map((row) => this.#withStoredRow(this.hydrate(this.fromRow(row), undefined, { track: false }), row));
+    return rows.map((row) =>
+      this.#readAs(this.#withStoredRow(this.hydrate(this.fromRow(row), undefined, { track: false }), row), row),
+    );
   }
 
   async findIds(query?: DocumentQuery, options: Omit<FindManyOptions, "select"> = {}) {
-    const { tail, args } = this.listQuery(query, options);
+    const { tail, args } = this.listQuery(query, options, "findIds");
     const rows = await this.prepareStmt(`SELECT ${quoteIdent(this.table)}."id" ${tail}`).all<{ id: string }>(...args);
     return rows.map((row) => row.id);
   }
 
-  private listQuery(query: DocumentQuery | undefined, options: FindManyOptions) {
-    const { where, params, joins } = this.safeQuery(query);
+  private listQuery(query: DocumentQuery | undefined, options: FindManyOptions, operation = "find") {
+    const { where, params, joins } = this.safeQuery(query, operation, options);
     const limitValue = Number(options.limit ?? 0);
     const skipValue = Number(options.skip ?? 0);
     const order = options.sample ? "ORDER BY random()" : `ORDER BY ${this.orderBy(options.sort, joins)}`;
@@ -369,7 +428,7 @@ export class SqlDocumentStore {
     return (await this.find(query, { ...options, limit: 1, sample: options.sample ? 1 : undefined })).at(0) ?? null;
   }
 
-  async findId(query?: DocumentQuery, options: { sort?: SortOption; skip?: number | null; sample?: boolean } = {}) {
+  async findId(query?: DocumentQuery, options: FindIdOptions = {}) {
     return (await this.findIds(query, { ...options, limit: 1, sample: options.sample ? 1 : undefined })).at(0) ?? null;
   }
 
@@ -385,12 +444,12 @@ export class SqlDocumentStore {
     return doc;
   }
 
-  async exists(query?: DocumentQuery) {
-    return this.findId(query);
+  async exists(query?: DocumentQuery, options: DocumentScopeOptions = {}) {
+    return this.findId(query, options);
   }
 
-  async count(query?: DocumentQuery) {
-    const { where, params, joins } = this.safeQuery(query);
+  async count(query?: DocumentQuery, options: DocumentScopeOptions = {}) {
+    const { where, params, joins } = this.safeQuery(query, "count", options);
     const row = await this.prepareStmt(
       `SELECT count(*) as count FROM ${quoteIdent(this.table)}${this.joinSql(joins)} WHERE ${where}`,
     ).get<{ count: number }>(...this.joinParams(joins), ...params);
@@ -416,12 +475,27 @@ export class SqlDocumentStore {
     return result;
   }
 
-  private safeQuery(query?: DocumentQuery) {
+  private safeQuery(
+    query: DocumentQuery | undefined,
+    operation: string,
+    { withRemoved = false }: DocumentScopeOptions,
+  ) {
+    if (withRemoved) {
+      const compiled = this.compiler.compile(query ?? {});
+      
+      if (compiled.joins.length) throw new Error(`q.search() cannot see removed rows on "${this.table}"`);
+      return compiled;
+    }
+    const conflict = LiveRowScope.conflictOf(query);
+    if (conflict)
+      throw new Error(
+        `${operation} on "${this.table}" can never match (${conflict}); ${operation.startsWith("remove") ? "a remove reaches live rows only" : "pass { withRemoved: true }"}`,
+      );
     return this.compiler.compile(documentQueryHelper.all(documentQueryHelper.empty("removedAt"), query ?? {}));
   }
 
-  private writeQuery(query: DocumentQuery | undefined, operation: string) {
-    const compiled = this.safeQuery(query);
+  private writeQuery(query: DocumentQuery | undefined, operation: string, options: DocumentScopeOptions) {
+    const compiled = this.safeQuery(query, operation, options);
     if (compiled.joins.length)
       throw new Error(`q.search() cannot be used in ${operation} on "${this.table}"; query-level writes take no join.`);
     return compiled;
@@ -738,6 +812,19 @@ export class SqlDocumentStore {
     return doc;
   }
 
+  #readAs<Doc extends object>(doc: Doc, { removedAt }: { removedAt?: unknown }): Doc {
+    if (removedAt != null)
+      Object.defineProperty(doc, SqlDocumentStore.#readRemoved, { value: true, configurable: true });
+    return doc;
+  }
+
+  #assertLiveRow(doc: DocumentRecord) {
+    if (!(doc as Record<symbol, unknown>)[SqlDocumentStore.#readRemoved]) return;
+    throw new Error(
+      `read-only: a removed ${this.table} is revived with updateById(id, { removedAt: null }, { withRemoved: true })`,
+    );
+  }
+
   #assertImmutableUnchanged(prepared: DocumentRecord, originalData: DocumentRecord) {
     this.#immutableKeys ??= Object.entries(this.database.doc[FIELD_META] as unknown as FieldMap)
       .filter(([, fieldMeta]) => fieldMeta.getProps().immutable)
@@ -746,8 +833,10 @@ export class SqlDocumentStore {
     const changed = this.#immutableKeys.filter((key) => jsonStr(prepared[key]) !== jsonStr(originalData[key]));
     if (!changed.length) return;
     
-    throw new Error(
-      `Cannot modify immutable field${changed.length > 1 ? "s" : ""} on ${this.table} (${String(prepared.id)}): ${changed.join(", ")}`,
+    throw new Err(
+      "base.error.immutableField",
+      { field: changed.join(", ") },
+      { details: { model: this.table, id: String(prepared.id) } },
     );
   }
 
@@ -887,13 +976,16 @@ export class SqlDocumentStore {
       },
       save: {
         async value(this: DocumentRecord) {
-          return this.id ? store.update(this.id as string, store.#changesOf(this)) : store.create(this);
+          if (!this.id) return store.create(this);
+          store.#assertLiveRow(this);
+          return store.update(this.id as string, store.#changesOf(this));
         },
       },
       refresh: {
         async value(this: DocumentRecord) {
           const fresh = (await store.pickById(this.id as string)) as DocumentRecord & Record<symbol, StoredRow>;
           Object.assign(this, fresh);
+          Reflect.deleteProperty(this, SqlDocumentStore.#readRemoved);
           return store.#withStoredRow(this, fresh[SqlDocumentStore.#storedRow]);
         },
       },

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";