akanjs 3.0.1 → 3.0.2-rc.0

package/server/mcp/McpRateLimiter.ts

@@ -1,9 +1,6 @@
-import { type Dayjs, dayjs } from "akanjs/base";
-import { Logger } from "akanjs/common";
+import { type RateCounter, RateLimiter } from "akanjs/service";
 
-export interface McpSharedCounter {
-  incr(topic: string, key: string, by?: number, option?: { expireAt?: Dayjs }): Promise<number>;
-}
+export type McpSharedCounter = RateCounter;
 
 export interface McpRateLimitOption {
   /** Per caller per window; `0` turns the counter off. */
@@ -17,23 +14,14 @@ export type McpRateLimitVerdict =
   | { ok: true; release: () => void }
   | { ok: false; reason: "calls" | "concurrent"; retryAfterMs: number };
 
-interface McpRateBucket {
-  windowStart: number;
-  count: number;
-  inFlight: number;
-}
-
 export class McpRateLimiter {
   static readonly defaults = { calls: 120, windowMs: 60_000, concurrent: 8 } as const;
-  static readonly #logger = new Logger("McpRateLimiter");
 
   readonly calls: number;
   readonly windowMs: number;
   readonly concurrent: number;
-  readonly #shared: McpSharedCounter | null;
-  readonly #buckets = new Map<string, McpRateBucket>();
-  #sweptAt = 0;
-  #sharedFailed = false;
+  readonly #limiter: RateLimiter;
+  readonly #inFlight = new Map<string, number>();
 
   constructor(
     {
@@ -46,74 +34,37 @@ export class McpRateLimiter {
     this.calls = Math.max(0, Math.floor(calls));
     this.windowMs = Math.max(1, Math.floor(windowMs));
     this.concurrent = Math.max(0, Math.floor(concurrent));
-    this.#shared = shared;
+    this.#limiter = new RateLimiter(shared, { topic: "mcpRate" });
   }
 
   async acquire(key: string, now = Date.now()): Promise<McpRateLimitVerdict> {
-    this.#sweep(now);
-    const bucket = this.#bucketOf(key, now);
-    if (this.concurrent && bucket.inFlight >= this.concurrent)
-      return { ok: false, reason: "concurrent", retryAfterMs: 1_000 };
+    const held = this.#inFlight.get(key) ?? 0;
+    if (this.concurrent && held >= this.concurrent) return { ok: false, reason: "concurrent", retryAfterMs: 1_000 };
     
-    bucket.inFlight += 1;
+    this.#inFlight.set(key, held + 1);
     let released = false;
     const release = () => {
       if (released) return;
       released = true;
-      bucket.inFlight = Math.max(0, bucket.inFlight - 1);
+      const left = (this.#inFlight.get(key) ?? 1) - 1;
+      if (left > 0) this.#inFlight.set(key, left);
+      else this.#inFlight.delete(key);
     };
-    const retryAfterMs = this.calls ? await this.#spend(key, bucket, now) : null;
-    if (retryAfterMs === null) return { ok: true, release };
+    if (!this.calls) return { ok: true, release };
+    const verdict = await this.#limiter.consume(key, { calls: this.calls, windowMs: this.windowMs }, now);
+    if (verdict.ok) return { ok: true, release };
     release();
-    return { ok: false, reason: "calls", retryAfterMs };
+    return { ok: false, reason: "calls", retryAfterMs: verdict.retryAfterMs };
   }
 
   describe() {
-    const across = this.#shared ? " across instances" : "";
+    const shared = this.#limiter.isShared;
     const window = this.calls
-      ? `${this.calls} calls / ${Math.round(this.windowMs / 1000)}s${across}`
+      ? `${this.calls} calls / ${Math.round(this.windowMs / 1000)}s${shared ? " across instances" : ""}`
       : "unlimited calls";
     const inFlight = this.concurrent
-      ? `${this.concurrent} in flight${this.#shared ? " per instance" : ""}`
+      ? `${this.concurrent} in flight${shared ? " per instance" : ""}`
       : "unlimited in flight";
     return `${window}, ${inFlight}, per caller`;
   }
-
-  async #spend(key: string, bucket: McpRateBucket, now: number): Promise<number | null> {
-    if (this.#shared) {
-      const window = Math.floor(now / this.windowMs);
-      const end = (window + 1) * this.windowMs;
-      try {
-        const count = await this.#shared.incr("mcpRate", `${key}:${window}`, 1, {
-          expireAt: dayjs(end + this.windowMs),
-        });
-        this.#sharedFailed = false;
-        return count > this.calls ? Math.max(1, end - now) : null;
-      } catch (error) {
-        if (!this.#sharedFailed)
-          McpRateLimiter.#logger.warn(
-            `MCP rate limit cannot reach the cache, so each instance counts its own window until it can: ${String(error)}`,
-          );
-        this.#sharedFailed = true;
-      }
-    }
-    if (bucket.count >= this.calls) return Math.max(1, bucket.windowStart + this.windowMs - now);
-    bucket.count += 1;
-    return null;
-  }
-
-  #bucketOf(key: string, now: number) {
-    const found = this.#buckets.get(key);
-    if (found && now - found.windowStart < this.windowMs) return found;
-    const bucket: McpRateBucket = { windowStart: now, count: 0, inFlight: found?.inFlight ?? 0 };
-    this.#buckets.set(key, bucket);
-    return bucket;
-  }
-
-  #sweep(now: number) {
-    if (now - this.#sweptAt < this.windowMs) return;
-    this.#sweptAt = now;
-    for (const [key, bucket] of this.#buckets)
-      if (!bucket.inFlight && now - bucket.windowStart >= this.windowMs) this.#buckets.delete(key);
-  }
 }

package/server/proxy/webProxyRunner.ts

@@ -1,3 +1,4 @@
+import { SignalContext } from "../../signal/signalContext";
 import {
   WEB_PROXY_RESULT,
   type WebProxy,
@@ -9,6 +10,7 @@ import {
 } from "./types";
 
 export const copyBunRequestFields = (target: Request, source: Request): Request => {
+  SignalContext.carryClientIp(target, source);
   const sourceWithParams = source as Request & { params?: Record<string, string> };
   if (sourceWithParams.params) {
     Object.defineProperty(target, "params", {

package/server/resolver/database.resolver.ts

@@ -10,7 +10,9 @@ import {
   type DataInputOf,
   DataLoader,
   DocumentSchema,
+  type DocumentScopeOptions,
   type DocumentUpdateInput,
+  type DocumentUpdateOptions,
   documentQueryHelper,
   type FindQueryOption,
   getFilterMeta,
@@ -70,7 +72,7 @@ export class DatabaseResolver {
       sort: resolveSort(queryOption?.sort),
       skip: resolvePageSkip(queryOption?.skip),
 
-      limit: queryOption?.limit === undefined ? 0 : resolvePageLimit(queryOption.limit),
+      limit: queryOption?.limit === undefined || queryOption.limit === 0 ? 0 : resolvePageLimit(queryOption.limit),
       select: queryOption?.select,
       sample: queryOption?.sample,
     });
@@ -198,9 +200,13 @@ export class DatabaseResolver {
         function Model(this: any, data: Record<string, unknown>) {
           return store.hydrate(data);
         }
+        
+        const scopeOf = (options?: DocumentScopeOptions) => (options?.withRemoved ? { withRemoved: true } : {});
+        const scopeArgs = (options?: DocumentScopeOptions): [] | [DocumentScopeOptions] =>
+          options?.withRemoved ? [{ withRemoved: true }] : [];
         const createFindManyChain = (
           query: QueryOf<any>,
-          options: { sort?: any; skip?: number; limit?: number; select?: any } = {},
+          options: { sort?: any; skip?: number; limit?: number; select?: any; withRemoved?: boolean } = {},
         ) => {
           const chain: any = {
             sort(sort: any) {
@@ -225,7 +231,10 @@ export class DatabaseResolver {
           };
           return chain;
         };
-        const createFindOneChain = (query: QueryOf<any>, options: { sort?: any; skip?: number; select?: any } = {}) => {
+        const createFindOneChain = (
+          query: QueryOf<any>,
+          options: { sort?: any; skip?: number; select?: any; withRemoved?: boolean } = {},
+        ) => {
           const chain: any = {
             sort(sort: any) {
               return createFindOneChain(query, { ...options, sort });
@@ -261,21 +270,27 @@ export class DatabaseResolver {
           pickAndWrite: async (id: string, rawData: any) => await (await pickById(id)).set(rawData).save(),
           pickOneAndWrite: async (query: QueryOf<any>, rawData: any) =>
             await (await timedQuery(() => store.pickOne(query))).set(rawData).save(),
-          exists: async (query: QueryOf<any>) => await timedQuery(() => store.exists(query)),
+          exists: async (query: QueryOf<any>, options?: DocumentScopeOptions) =>
+            await timedQuery(() => store.exists(query, ...scopeArgs(options))),
           sample: (query: QueryOf<any>, size = 1) => timedQuery(() => store.find(query, { sample: size, limit: size })),
           sampleOne: (query: QueryOf<any>) => timedQuery(() => store.findOne(query, { sample: true })),
-          find: (query: QueryOf<any>, projection?: any) => createFindManyChain(query, { select: projection }),
-          findOne: (query: QueryOf<any>, projection?: any) => createFindOneChain(query, { select: projection }),
-          findById: (id: string | undefined, projection?: any) =>
-            id ? timedQuery(() => store.findOne({ id }, { select: projection })) : Promise.resolve(null),
-          count: (query: QueryOf<any>) => timedQuery(() => store.count(query)),
-          updateOne: (query: QueryOf<any>, update: DocumentUpdateInput, options?: { upsert?: boolean }) =>
+          find: (query: QueryOf<any>, projection?: any, options?: DocumentScopeOptions) =>
+            createFindManyChain(query, { select: projection, ...scopeOf(options) }),
+          findOne: (query: QueryOf<any>, projection?: any, options?: DocumentScopeOptions) =>
+            createFindOneChain(query, { select: projection, ...scopeOf(options) }),
+          findById: (id: string | undefined, projection?: any, options?: DocumentScopeOptions) =>
+            id
+              ? timedQuery(() => store.findOne({ id }, { select: projection, ...scopeOf(options) }))
+              : Promise.resolve(null),
+          count: (query: QueryOf<any>, options?: DocumentScopeOptions) =>
+            timedQuery(() => store.count(query, ...scopeArgs(options))),
+          updateOne: (query: QueryOf<any>, update: DocumentUpdateInput, options?: DocumentUpdateOptions) =>
             timedQuery(() => store.updateOneByQuery(query, update, options)),
-          updateMany: (query: QueryOf<any>, update: DocumentUpdateInput) =>
-            timedQuery(() => store.updateManyByQuery(query, update)),
+          updateMany: (query: QueryOf<any>, update: DocumentUpdateInput, options?: DocumentScopeOptions) =>
+            timedQuery(() => store.updateManyByQuery(query, update, ...scopeArgs(options))),
           removeOne: (query: QueryOf<any>) => timedQuery(() => store.removeOneByQuery(query)),
           removeMany: (query: QueryOf<any>) => timedQuery(() => store.removeManyByQuery(query)),
-          updateById: (id: string, update: DocumentUpdateInput, options?: { upsert?: boolean }) =>
+          updateById: (id: string, update: DocumentUpdateInput, options?: DocumentUpdateOptions) =>
             timedQuery(() => store.updateOneByQuery({ id }, update, options)),
           removeById: (id: string) => timedQuery(() => store.removeOneByQuery({ id })),
           

package/server/resolver/signal.resolver.ts

@@ -15,7 +15,14 @@ import {
   SLICE_META,
 } from "akanjs/base";
 import { capitalize, cookieHeaderHasAuthToken, Logger } from "akanjs/common";
-import { type ConstantField, deserialize, resolvePageLimit, resolvePageSkip, serialize } from "akanjs/constant";
+import {
+  type ConstantField,
+  deserialize,
+  MAX_PAGE_SIZE,
+  resolvePageLimit,
+  resolvePageSkip,
+  serialize,
+} from "akanjs/constant";
 import { baseDocumentColumns, documentQueryHelper, getFilterSortByKey, type QueryFieldMap } from "akanjs/document";
 import {
   type AkanJob,
@@ -30,6 +37,7 @@ import {
 import { websocketRoomContract } from "../../common/websocketContract";
 import { type Endpoint, type EndpointCls, sliceEndpoint } from "../../signal/endpoint";
 import type { EndpointInfo } from "../../signal/endpointInfo";
+import { EndpointRateLimit } from "../../signal/endpointRateLimit";
 import type { Internal, InternalCls } from "../../signal/internal";
 import type { InternalInfo } from "../../signal/internalInfo";
 import type { MiddlewareCls } from "../../signal/middleware";
@@ -65,6 +73,7 @@ export class SignalResolver {
   };
   static readonly #coalescingRooms = new Set<string>();
   static readonly #liveRoutes = new Map<string, { store: DocumentStore; route: LiveRoute }>();
+  static readonly #everyRowAsked = new Set<string>();
 
   static coalescesRoom(roomId: string): boolean {
     const separator = roomId.indexOf("-");
@@ -325,6 +334,17 @@ export class SignalResolver {
     else SignalResolver.logger.warn(message);
   }
 
+  static #clientPageLimit(listKey: string, asked: unknown) {
+    if (asked !== 0) return resolvePageLimit(asked);
+    if (!SignalResolver.#everyRowAsked.has(listKey)) {
+      SignalResolver.#everyRowAsked.add(listKey);
+      SignalResolver.logger.warn(
+        `${listKey} was asked for limit: 0 and served ${MAX_PAGE_SIZE} rows, the most a client may take; paginate, or name a page size`,
+      );
+    }
+    return MAX_PAGE_SIZE;
+  }
+
   static #getJobArgs(key: string, internalInfo: InternalInfo, job: AkanJob): unknown[] {
     const data = Array.isArray(job.data) ? (job.data as unknown[]) : job.data === undefined ? [] : [job.data];
     return internalInfo.args.map((arg, idx) =>
@@ -371,7 +391,7 @@ export class SignalResolver {
           .exec(async function (this: any, ...requestArgs: any) {
             const args = requestArgs.slice(0, argLength);
             const skip = resolvePageSkip(requestArgs[argLength]);
-            const limit = resolvePageLimit(requestArgs[argLength + 1]);
+            const limit = SignalResolver.#clientPageLimit(listKey, requestArgs[argLength + 1]);
             const sort = requestArgs[argLength + 2] ?? "latest";
             const internalArgs = requestArgs.slice(argLength + 3);
             const query = assertSliceQuery(
@@ -437,41 +457,46 @@ export class SignalResolver {
           });
       });
 
-      endpointObj[refName] = (builder as any)
-        .query(cnst.full, { guards: sliceCls.getGuards })
-        .param(`${refName}Id`, ID)
-        .exec(async function (this: any, id: string) {
-          return await this[serviceName][`get${capitalizedRefName}`](id);
-        });
+      if (sliceCls.crud.get) {
+        endpointObj[refName] = (builder as any)
+          .query(cnst.full, { guards: sliceCls.getGuards })
+          .param(`${refName}Id`, ID)
+          .exec(async function (this: any, id: string) {
+            return await this[serviceName][`get${capitalizedRefName}`](id);
+          });
 
-      endpointObj[`light${capitalizedRefName}`] = (builder as any)
-        .query(cnst.light, { guards: sliceCls.getGuards })
-        .param(`${refName}Id`, ID)
-        .exec(async function (this: any, id: string) {
-          return await this[serviceName][`get${capitalizedRefName}`](id);
-        });
+        endpointObj[`light${capitalizedRefName}`] = (builder as any)
+          .query(cnst.light, { guards: sliceCls.getGuards })
+          .param(`${refName}Id`, ID)
+          .exec(async function (this: any, id: string) {
+            return await this[serviceName][`get${capitalizedRefName}`](id);
+          });
+      }
 
-      endpointObj[`create${capitalizedRefName}`] = (builder as any)
-        .mutation(cnst.full, { guards: sliceCls.createGuards })
-        .body("data", cnst.input)
-        .exec(async function (this: any, data: any) {
-          return await this[serviceName].__create(data);
-        });
+      if (sliceCls.crud.create)
+        endpointObj[`create${capitalizedRefName}`] = (builder as any)
+          .mutation(cnst.full, { guards: sliceCls.createGuards })
+          .body("data", cnst.input)
+          .exec(async function (this: any, data: any) {
+            return await this[serviceName].__create(data);
+          });
 
-      endpointObj[`update${capitalizedRefName}`] = (builder as any)
-        .mutation(cnst.full, { guards: sliceCls.updateGuards })
-        .param(`${refName}Id`, ID)
-        .body("data", cnst.input)
-        .exec(async function (this: any, id: string, data: any) {
-          return await this[serviceName].__update(id, data);
-        });
+      if (sliceCls.crud.update)
+        endpointObj[`update${capitalizedRefName}`] = (builder as any)
+          .mutation(cnst.full, { guards: sliceCls.updateGuards })
+          .param(`${refName}Id`, ID)
+          .body("data", cnst.input)
+          .exec(async function (this: any, id: string, data: any) {
+            return await this[serviceName].__update(id, data);
+          });
 
-      endpointObj[`remove${capitalizedRefName}`] = (builder as any)
-        .mutation(cnst.full, { guards: sliceCls.removeGuards })
-        .param(`${refName}Id`, ID)
-        .exec(async function (this: any, id: string) {
-          return await this[serviceName].__remove(id);
-        });
+      if (sliceCls.crud.remove)
+        endpointObj[`remove${capitalizedRefName}`] = (builder as any)
+          .mutation(cnst.full, { guards: sliceCls.removeGuards })
+          .param(`${refName}Id`, ID)
+          .exec(async function (this: any, id: string) {
+            return await this[serviceName].__remove(id);
+          });
       return endpointObj;
     }) {}
     return SliceEndpoint;
@@ -600,6 +625,7 @@ export class SignalResolver {
     const routeOptions: NonNullable<SignalRoutes["routeOptions"]> = {};
     const wsRoutes: WebsocketRoutes = {};
     const defaultPrefix = endpointCls.srv.cnst?.refName;
+    SignalResolver.#warnUnguarded(endpointMeta);
     Object.entries(endpointMeta).forEach(([key, endpointInfo]) => {
       const path = endpointInfo.getRoutePath(key, defaultPrefix);
       if (endpointInfo.signalOption.globalPrefix !== undefined) {
@@ -627,7 +653,7 @@ export class SignalResolver {
           SignalResolver.#mountHttpRoute(
             routes,
             path,
-            SignalResolver.#canUsePrimitiveQueryFastPath(endpointInfo, middleware)
+            SignalResolver.#canUsePrimitiveQueryFastPath(key, endpointInfo, middleware)
               ? {
                   GET: async (req) => {
                     if (req.headers.get("authorization") || cookieHeaderHasAuthToken(req.headers.get("cookie")))
@@ -733,6 +759,15 @@ export class SignalResolver {
     return { routes, wsRoutes, routeOptions };
   }
 
+  static #warnUnguarded(endpointMeta: { [key: string]: EndpointInfo }) {
+    const open = Object.entries(endpointMeta)
+      .filter(([, endpointInfo]) => !endpointInfo.signalOption.guards?.length)
+      .map(([key]) => key);
+    if (!open.length) return;
+    SignalResolver.logger.warn(
+      `${open.join(", ")} declare${open.length === 1 ? "s" : ""} no guards, so anyone can call ${open.length === 1 ? "it" : "them"} over HTTP and WebSocket. Name the guards, or \`guards: [Public]\` to keep one open on purpose.`,
+    );
+  }
   static #selectCache = new WeakMap<Cls, Record<string, true>>();
   static #selectForConstant(constant: Cls): Record<string, true> | undefined {
     const cached = SignalResolver.#selectCache.get(constant);
@@ -744,9 +779,14 @@ export class SignalResolver {
     return select;
   }
 
-  static #canUsePrimitiveQueryFastPath(endpointInfo: EndpointInfo, middleware: Map<string, MiddlewareCls>) {
+  static #canUsePrimitiveQueryFastPath(
+    key: string,
+    endpointInfo: EndpointInfo,
+    middleware: Map<string, MiddlewareCls>,
+  ) {
     return (
       process.env.AKAN_TRACE !== "1" &&
+      !EndpointRateLimit.budgetOf(key, endpointInfo) &&
       endpointInfo.args.length === 0 &&
       endpointInfo.internalArgs.length === 0 &&
       (endpointInfo.signalOption.guards?.length ?? 0) === 0 &&

package/server/rscWorkerHost.ts

@@ -452,13 +452,13 @@ export class RscWorker {
 
   renderWithMeta(
     req: Request,
-    options: { clientManifest?: ClientManifest; signal?: AbortSignal } = {},
+    options: { clientManifest?: ClientManifest; signal?: AbortSignal; clientIp?: string | null } = {},
   ): Promise<RscRenderResult> {
     const requestId = crypto.randomUUID();
     return createRscHostRenderStream({
       setPending: (pending) => this.#pending.set(requestId, pending),
       deletePending: () => this.#pending.delete(requestId),
-      sendRenderOrQueue: () => this.#sendRenderOrQueue(requestId, req, options.clientManifest),
+      sendRenderOrQueue: () => this.#sendRenderOrQueue(requestId, req, options.clientManifest, options.clientIp),
       cancelRender: () => this.#cancelRender(requestId),
       signal: options.signal,
       onPendingChunkOverflow: () => {
@@ -851,14 +851,23 @@ export class RscWorker {
     this.#pending.delete(requestId);
   }
 
-  #sendRenderOrQueue(requestId: string, req: Request, clientManifest?: ClientManifest): void {
+  /** The page request's headers as the worker sees them, `x-real-ip` being only the address the host resolved. */
+  static workerHeaders(req: Request, clientIp: string | null | undefined): Record<string, string> {
+    const headers: Record<string, string> = {};
+    req.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    
+    delete headers["x-real-ip"];
+    if (clientIp) headers["x-real-ip"] = clientIp;
+    return headers;
+  }
+
+  #sendRenderOrQueue(requestId: string, req: Request, clientManifest?: ClientManifest, clientIp?: string | null): void {
     const send = () => {
       if (!this.#pending.has(requestId)) return;
       try {
-        const headers: Record<string, string> = {};
-        req.headers.forEach((value, key) => {
-          headers[key] = value;
-        });
+        const headers = RscWorker.workerHeaders(req, clientIp);
         this.#proc.send({ type: "render", requestId, url: req.url, method: req.method, headers, clientManifest });
       } catch (err) {
         this.#resolvePending(requestId, (p) =>

package/server/webRouter.ts

@@ -13,6 +13,7 @@ import {
 import { type AkanRequestStore, createRequestStore, parseCookieHeader } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { PagePromptSource } from "../signal/mcp/pagePrompt";
+import { SignalContext } from "../signal/signalContext";
 import {
   type BuilderRpc,
   type MergedManifest,
@@ -502,6 +503,7 @@ export class WebRouter {
           const result = await this.#rsc.renderWithMeta(rscReq, {
             clientManifest: manifest.clientManifest,
             signal: req.signal,
+            clientIp: SignalContext.clientIpOf(req),
           });
           if (result.type === "redirect")
             return createRscRedirectResponse(result.location, result.method, result.status);
@@ -613,6 +615,7 @@ export class WebRouter {
           const rscResult = await this.#rsc.renderWithMeta(req, {
             clientManifest: manifest.clientManifest,
             signal: req.signal,
+            clientIp: SignalContext.clientIpOf(req),
           });
           if (rscResult.type === "redirect")
             return Response.redirect(new URL(rscResult.location, url.origin), rscResult.status);

package/service/index.ts

@@ -5,6 +5,7 @@ export * from "./injectInfo";
 export * from "./ipcTypes";
 export * from "./liveSyncHub";
 export * from "./predefinedAdaptor";
+export * from "./rateLimiter";
 export * from "./serve";
 export * from "./serviceModule";
 export * from "./serviceRegistry";

package/service/predefinedAdaptor/index.ts

@@ -10,6 +10,7 @@ export * from "./logging.adaptor";
 export * from "./openaiDialect";
 export * from "./openaiLlm";
 export * from "./queue.adaptor";
+export * from "./rateLimit.adaptor";
 export * from "./role.adaptor";
 export * from "./schedule.adaptor";
 export * from "./searchIndex";

package/service/predefinedAdaptor/rateLimit.adaptor.ts

@@ -0,0 +1,15 @@
+import { adapt } from "../adapt";
+import { type RateBudget, RateLimiter, type RateVerdict } from "../rateLimiter";
+import { CacheAdaptorRole } from "./role.adaptor";
+
+/** Counts a business key (a phone number, an email) across instances; unlike an endpoint's budget, no env turns it off. */
+export class RateLimit extends adapt("rateLimit", ({ plug }) => ({
+  cache: plug(CacheAdaptorRole),
+})) {
+  #limiter: RateLimiter | null = null;
+
+  async consume(key: string, budget: RateBudget): Promise<RateVerdict> {
+    this.#limiter ??= new RateLimiter(this.cache, { topic: "rateLimit" });
+    return await this.#limiter.consume(key, budget);
+  }
+}