@procedures/client 0.15.0 → 0.16.0

package/src/server/procedure-server.ts

@@ -33,6 +33,8 @@ import { getGlobalEventBus } from "../events/bus.js";
 import type { CollectionProceduresOptions } from "../procedures/collection/procedures.js";
 import type { NarrowingNote } from "../procedures/narrowing.js";
 import type { ServerDebugReport } from "./types.js";
+import type { KeyedLimiter, LimiterStore } from "@mark1russell7/service/limiter";
+import { callLimiter, limitedCall, rateLimitedResponse, type CallLimit, type CallLimiter } from "./limits.js";
 
 // =============================================================================
 // Types
@@ -169,7 +171,8 @@ export interface ProcedureServerOptions extends ServerOptions {
    * The remote events of the server (`documentation/EVENTS.md`): a bus and its topic rule, or an
    * `EventPublisher`. The server pins the procedure `events.subscribe`, outside its registry, so a
    * peer can subscribe to the topics. The procedures of the server get this bus as `ctx.bus`.
-   * `stop()` ends each subscription first, with `UNAVAILABLE`.
+   * `stop()` ends each subscription first, with `UNAVAILABLE`. A publisher that the server makes
+   * from the options gets the clock of the server, unless the options give a clock (CLI-44).
    */
   events?: EventPublisherOptions | EventPublisher | undefined;
 
@@ -181,6 +184,21 @@ export interface ProcedureServerOptions extends ServerOptions {
    * @default false
    */
   debug?: boolean | ((report: ServerDebugReport) => void) | undefined;
+
+  /**
+   * The limits of the calls (CLI-40). Each limit is a keyed limiter of
+   * `@mark1russell7/service/limiter` on the clock of the server. The server takes one unit of each
+   * limit that covers a call, after the authentication and before the run, for each face. A
+   * refusal is `RATE_LIMITED` with the wait in `retry-after`: HTTP 429 with `Retry-After`. Without
+   * this option, the server limits nothing.
+   *
+   * The server takes the units in the sequence of the limits, and the first refusal stops the call.
+   * A limit before the refusal keeps its unit: the server does not give it back.
+   */
+  limits?: readonly CallLimit[] | undefined;
+
+  /** The stores that the replicas share, by the name of their dependency, for each limit with a shared store. */
+  limitStores?: Readonly<Record<string, LimiterStore>> | undefined;
 }
 
 /** The options of `registerProcedure()`, `registerProcedures()` and `registerModule()` (CLI-47). */
@@ -439,6 +457,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   readonly ambientCredentials: AmbientCredentials | undefined;
   /** The receiver of the debug reports, or undefined when the option `debug` is off. */
   private readonly debugReport: ((report: ServerDebugReport) => void) | undefined;
+  /** The limits of the calls (CLI-40), or undefined without the option `limits`. */
+  private readonly callLimits: CallLimiter | undefined;
 
   constructor(options: ProcedureServerOptions = {}) {
     super(options);
@@ -466,9 +486,13 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         : options.debug === true
           ? (report) => console.debug(`[ProcedureServer] ${report.topic} of ${report.requestId}: ${report.message}`)
           : undefined;
+    // The limits of the calls: one keyed limiter for each limit, on the clock of the server (CLI-40)
+    this.callLimits = options.limits && options.limits.length > 0 ? callLimiter(options.limits, { clock: this.clock, stores: options.limitStores }) : undefined;
     // The remote events: the server pins events.subscribe, as a host pins host.health (EVENTS.md).
-    // The topic rule is its expose rule, so the pin is always on (CLI-47).
-    this.publisher = options.events instanceof EventPublisher ? options.events : options.events ? new EventPublisher(options.events) : undefined;
+    // The topic rule is its expose rule, so the pin is always on (CLI-47). The publisher that the
+    // server makes gets the clock of the server for its re-checks (CLI-44).
+    const events = options.events;
+    this.publisher = events instanceof EventPublisher ? events : events ? new EventPublisher({ ...events, clock: events.clock ?? this.clock }) : undefined;
     if (this.publisher) this.registerProcedure(this.publisher.procedure, { alwaysOn: true });
 
     // Configure collections
@@ -550,16 +574,14 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    * for: the collection procedures and the subscriptions of `EventPublisher` use it. `storageOf`
    * gives the storage of a partition: give the same storage for the same partition each time.
    *
-   * @param name - Collection name, without a dot
+   * The name can have a dot (roadmap CLI-42). The topic of a partition encodes the name, so the
+   * name and the partition of a topic stay apart (`collectionChangeTopic()`).
+   *
+   * @param name - Collection name
    * @param partitions - The storage of each partition, and the resolver
    * @returns this (for chaining)
-   * @throws Error if the name has a dot
    */
   usePartitions<T>(name: string, partitions: CollectionPartitions<T>): this {
-    // The topic `collections.<name>.<partition>` names the partition after the first dot
-    if (name.includes(".")) {
-      throw new Error(`A collection with partitions cannot have a dot in its name: ${name}`);
-    }
     this.partitions.set(name, partitions as CollectionPartitions<unknown>);
     return this;
   }
@@ -798,6 +820,9 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     }
     const refusal = await this.admit(request);
     if (refusal) return refusal;
+    // The limits come after the authentication, so a key can read the principal (CLI-40)
+    const limited = await this.limit(procedure, request);
+    if (limited) return limited;
     this.calls++;
     let response: ServerResponse<unknown> | undefined;
     try {
@@ -873,6 +898,22 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     return undefined;
   }
 
+  /**
+   * The limits of a call (CLI-40): one unit of each limit that covers it. The function gives a
+   * `RATE_LIMITED` response, or undefined when the call passes. A key or a cover function that
+   * throws gives `INTERNAL_ERROR`, so a defect of a limit does not let a call in.
+   */
+  private async limit(procedure: AnyProcedure, request: ServerRequest<unknown>): Promise<ServerResponse<unknown> | undefined> {
+    if (!this.callLimits) return undefined;
+    try {
+      const refused = await this.callLimits.admit(limitedCall(procedure, request));
+      return refused ? rateLimitedResponse(request.id, refused) : undefined;
+    } catch (error) {
+      const message = `The limits of the server cannot admit the call: ${error instanceof Error ? error.message : String(error)}`;
+      return errorResponse(request.id, Object.assign(new Error(message), { code: "INTERNAL_ERROR" }));
+    }
+  }
+
   /** One call in flight ended: `drain()` can end when it was the last one. */
   private callEnded(): void {
     this.calls--;
@@ -1111,6 +1152,15 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     return this.resolveProcedure(method);
   }
 
+  /**
+   * This method gives the keyed limiters of the option `limits`, in its sequence (CLI-40). A host
+   * declares each one on its service with `svc.limiter(limiter.name, limiter.spec)`, so
+   * `describe()` and `lint()` see it.
+   */
+  limiters(): readonly KeyedLimiter[] {
+    return this.callLimits?.limiters ?? [];
+  }
+
   /**
    * This function publishes an event on the bus of the server: the bus of the option `events`, or
    * the global bus. Each subscription of the topic gets it (`documentation/EVENTS.md`).

package/src/server/request-auth.ts

@@ -40,9 +40,26 @@ export function withoutSecretHeaders(headers: Record<string, unknown>, secret?:
   return out;
 }
 
-/** The token of an `Authorization: Bearer <token>` header, or undefined. */
+/** The start of the header that `bearerOf` read before CLI-60: the scheme `Bearer` and one space. */
+const BEARER_PREFIX = "Bearer ";
+
+/**
+ * The other forms of a bearer credential (RFC 7235 and RFC 6750, CLI-60). Such a form has the
+ * scheme `Bearer` in any case, one or more spaces (`1*SP`) and the token. Spaces or tabs can come
+ * after the token. The token has no whitespace (`token68`). A tab is not `1*SP`.
+ */
+const BEARER_CREDENTIAL = /^bearer +(\S+)[ \t]*$/i;
+
+/**
+ * The token of an `Authorization: Bearer <token>` header, or undefined. A header that starts
+ * with `Bearer ` gives the rest of the header, as before CLI-60. A header with the scheme in
+ * another case, for example `bearer`, gives the token after one or more spaces.
+ */
 export function bearerOf(header: unknown): string | undefined {
-  return typeof header === "string" && header.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
+  if (typeof header !== "string") return undefined;
+  // The old form keeps its old result, so each header that passed before gives the same token
+  if (header.startsWith(BEARER_PREFIX)) return header.slice(BEARER_PREFIX.length);
+  return BEARER_CREDENTIAL.exec(header)?.[1];
 }
 
 /**