@procedures/client 0.17.4 → 0.18.1

package/src/adapters/websocket/shared/rpc.ts

@@ -17,6 +17,7 @@ import type { WebSocketMessage } from "../server/types.js";
 import { withoutInternalKeys } from "../../metadata.js";
 import { StreamSequence, gapOf, itemMetadata } from "../../sequence.js";
 import { DELIVERY_METADATA_KEY } from "../../../client/middleware/items.js";
+import { foldedErrorCode } from "../../../protocol.js";
 
 /**
  * A queue of response items that one reader takes in order: push, then end or fail. The reader
@@ -99,7 +100,11 @@ export class StreamCredit {
   }
 }
 
-/** The error of a failed stream or handler: its code (a string) and its retryable flag. */
+/**
+ * The error of a failed stream or handler: its code (a string) and its retryable flag. An error
+ * without a flag gets false, not the flag of its code: the end of a stream is in-band, and a retry
+ * can send the items again (CLI-58, `WIRE-PROTOCOL.md`, section "Error codes").
+ */
 export function errorStatus(error: unknown): { type: "error"; code: string; message: string; retryable: boolean } {
   const code = (error as { code?: unknown } | undefined)?.code;
   const retryable = (error as { retryable?: unknown } | undefined)?.retryable;
@@ -122,13 +127,14 @@ function textOf(value: unknown): string {
 export function itemOfFrame(frame: WebSocketMessage, messageId: string): ResponseItem<unknown> {
   let status: ResponseItem<unknown>["status"];
   if (frame.status && frame.status.type === "error") {
-    status = { type: "error", code: String(frame.status.code), message: textOf(frame.status.message), retryable: frame.status.retryable || false };
+    // A code of an older server becomes its code of wire v1 (CLI-4): "500" is INTERNAL_ERROR
+    status = { type: "error", code: foldedErrorCode(String(frame.status.code)).code, message: textOf(frame.status.message), retryable: frame.status.retryable || false };
   } else if (frame.status && frame.status.type === "success") {
     status = { type: "success", code: Number(frame.status.code) };
   } else if (frame.type === "error") {
     status = {
       type: "error",
-      code: String(frame.error?.code || "UNKNOWN_ERROR"),
+      code: foldedErrorCode(String(frame.error?.code || "UNKNOWN_ERROR")).code,
       message: textOf(frame.error?.message),
       retryable: frame.error?.retryable || false,
     };

package/src/browser.ts

@@ -134,6 +134,8 @@ export {
   collectionTopicPartition,
   collectionTopicTarget,
   collectionTopicRule,
+  // The refusal of a storage whose topic is the topic of a partition (roadmap CLI-57)
+  CollectionTopicCollisionError,
   // The rules of the rows of a collection (roadmap CLI-41)
   admittedStorage,
   admitsRow,

package/src/client/middleware/items.ts

@@ -55,6 +55,8 @@ export function retryAfterOf(item: ResponseItem<unknown>): number | undefined {
 const AVAILABILITY_CODES = new Set([
   "UNAVAILABLE",
   "TIMEOUT",
+  // The code of a stopped server before CLI-4. It is UNAVAILABLE now. The next breaking release
+  // of the client group removes it.
   "SERVER_STOPPED",
   "SERVICE_UNAVAILABLE",
   "BAD_GATEWAY",

package/src/procedures/collection/index.ts

@@ -72,6 +72,8 @@ export type { CollectionChangeEvent } from "./changes.js";
 
 // The partitions of a collection (roadmap CLI-17)
 export { PARTITION_PATTERN, collectionTopicPartition, collectionTopicTarget, partitionOfCall, storageOfCall, withPartition } from "./partition.js";
+// The refusal of a storage whose topic is the topic of a partition (roadmap CLI-57, decision D23)
+export { CollectionTopicCollisionError } from "./partition.js";
 // The topic rule of a collection for EventPublisher (roadmap CLI-42)
 export { collectionTopicRule } from "./topic.js";
 export type { CollectionPartitions, PartitionInput, PartitionResolver } from "./partition.js";

package/src/procedures/collection/partition.ts

@@ -14,11 +14,15 @@
  * - In the topic of a partition, the name encodes `%` and `.` (`topic.ts`, roadmap CLI-42). Thus
  *   the name of a collection with partitions can have a dot.
  * - A collection without partitions refuses a call or a topic with a partition.
+ * - The plain topic of a dotted name, `collections.a.b`, is also the topic of the partition `b` of
+ *   `a`. Thus the server refuses a storage of `a.b` while `a` has partitions (roadmap CLI-57,
+ *   decision D23).
  */
 import type { ZodLike } from "../../client/validation/types.js";
 import { InvocationError } from "../invoke.js";
 import type { ProcedureContext } from "../types.js";
 import type { CollectionStorage } from "./storage.js";
+import { collectionChangeTopic, collectionTopicPartition } from "./topic.js";
 
 /** The characters of a partition: letters, digits and `_ . : @ ~ + | / -`, 256 at most. */
 export const PARTITION_PATTERN: RegExp = /^[A-Za-z0-9_.:@~+|/-]{1,256}$/;
@@ -131,5 +135,76 @@ export function storageOfCall<T>(ctx: ProcedureContext, collection: string, part
   return repository.getPartitionStorage<T>(collection, partition);
 }
 
+/**
+ * The error of a server that serves two collections with the same topic (roadmap CLI-57, decision
+ * D23). The plain topic of a collection with a storage, `collections.a.b`, is also the topic of the
+ * partition `b` of the partitioned collection `a`. Thus the readers of `a.b` get the events of the
+ * tenant `b` of `a`. To correct it, rename the collection `a.b` to a name without the prefix `a.`.
+ */
+export class CollectionTopicCollisionError extends Error {
+  override readonly name = "CollectionTopicCollisionError";
+  /** The collection with a storage without a partition. Its topic is `collections.<collection>`. */
+  readonly collection: string;
+  /** The collection with partitions. */
+  readonly partitioned: string;
+  /** The partition of `partitioned` whose topic is the topic of `collection`. */
+  readonly partition: string;
+  /** The topic of the two. */
+  readonly topic: string;
+
+  constructor(collection: string, partitioned: string, partition: string) {
+    super(collisionMessage(collection, partitioned, partition));
+    this.collection = collection;
+    this.partitioned = partitioned;
+    this.partition = partition;
+    this.topic = collectionChangeTopic(collection);
+  }
+}
+
+/** The message of a `CollectionTopicCollisionError`: the two collections, the topic and the fix. */
+function collisionMessage(collection: string, partitioned: string, partition: string): string {
+  // The plain name is the encoded name of the partitioned collection, a dot and the partition
+  const prefix = collection.slice(0, collection.length - partition.length);
+  return (
+    `The collection "${collection}" and the partition "${partition}" of the collection "${partitioned}" have the same topic "${collectionChangeTopic(collection)}", ` +
+    `so the readers of "${collection}" get the events of that partition (roadmap CLI-57). ` +
+    `Rename the collection "${collection}" to a name that does not start with "${prefix}", for example "${collection.replace(/\./g, "_")}".`
+  );
+}
+
+/**
+ * This function gives the partition whose topic is the plain topic of a collection, or undefined
+ * (roadmap CLI-57). The plain topic of `a.b` is `collections.a.b`, the topic of the partition `b`
+ * of `a`. A name without a dot gives undefined. It uses the parse of the publisher, so the two agree.
+ *
+ * @example
+ * ```typescript
+ * partitionOfPlainTopic("a.b.c"); // { collection: "a", partition: "b.c" }
+ * partitionOfPlainTopic("a%2Eb.c"); // { collection: "a.b", partition: "c" }
+ * partitionOfPlainTopic("ab"); // undefined
+ * ```
+ */
+export function partitionOfPlainTopic(collection: string): { collection: string; partition: string } | undefined {
+  const target = collectionTopicPartition(collectionChangeTopic(collection));
+  return target?.partition === undefined ? undefined : { collection: target.collection, partition: target.partition };
+}
+
+/**
+ * This function refuses two collections with the same topic (roadmap CLI-57, decision D23). It
+ * examines each collection with a storage: its plain topic must not be the topic of a partition of
+ * a collection with partitions. `ProcedureServer` uses it for each new storage and for each new
+ * collection with partitions, in each order.
+ *
+ * @param plain - The collections with a storage without a partition
+ * @param hasPartitions - True for a collection with partitions
+ * @throws CollectionTopicCollisionError for the first pair with the same topic
+ */
+export function assertTopicsApart(plain: Iterable<string>, hasPartitions: (collection: string) => boolean): void {
+  for (const collection of plain) {
+    const shared = partitionOfPlainTopic(collection);
+    if (shared && hasPartitions(shared.collection)) throw new CollectionTopicCollisionError(collection, shared.collection, shared.partition);
+  }
+}
+
 // The parse of a topic lives in topic.ts, with the encode (roadmap CLI-42)
 export { collectionTopicPartition, collectionTopicTarget } from "./topic.js";

package/src/procedures/collection/topic.ts

@@ -16,6 +16,8 @@
  * - The topic of a collection whose name has a dot, `collections.a.b`, has the same form as the
  *   topic of the partition `b` of the collection `a`. Only the repository knows the collection, so
  *   `collectionTopicTarget()` decides with it.
+ * - `ProcedureServer` refuses a storage of `a.b` while `a` has partitions, in each order (roadmap
+ *   CLI-57, decision D23). Thus the readers of `a.b` do not get the events of a partition of `a`.
  */
 import type { RepositoryProvider } from "../types.js";
 

package/src/procedures/index.ts

@@ -134,6 +134,8 @@ export {
   collectionTopicPartition,
   collectionTopicTarget,
   collectionTopicRule,
+  // The refusal of a storage whose topic is the topic of a partition (roadmap CLI-57)
+  CollectionTopicCollisionError,
   // The rules of the rows of a collection (roadmap CLI-41)
   admittedStorage,
   admitsRow,

package/src/protocol.ts

@@ -101,6 +101,32 @@ export function errorCodeOf(error: unknown): string {
   return typeof code === "string" ? code : "HANDLER_ERROR";
 }
 
+/** The codes that a server before CLI-4 gave, and the code and the reason of wire v1 for each. */
+const FOLDED_ERROR_CODES: ReadonlyMap<string, { readonly code: ProtocolErrorCode; readonly reason?: string }> = new Map([
+  ["SERVER_STOPPED", { code: "UNAVAILABLE" }],
+  ["FORBIDDEN_HOST", { code: "FORBIDDEN", reason: "host-header-not-allowed" }],
+  ["FORBIDDEN_ORIGIN", { code: "FORBIDDEN", reason: "origin-not-allowed" }],
+  ["500", { code: "INTERNAL_ERROR" }],
+]);
+
+/**
+ * This function gives the code of wire v1 for an error code that a server before CLI-4 gave, and
+ * the reason of a `FORBIDDEN` error. For each other code, it gives the code and no reason. The
+ * client reads an old code as its new code, so an application can match the new code also with an
+ * older server.
+ *
+ * `METHOD_NOT_ALLOWED` and `UNSUPPORTED_MEDIA_TYPE` stay: they are also the codes of the HTTP
+ * statuses 405 and 415 of each server.
+ *
+ * The client reads the old codes for one release. The next breaking release of the client group
+ * removes this function.
+ *
+ * @internal
+ */
+export function foldedErrorCode(code: string): { readonly code: string; readonly reason?: string | undefined } {
+  return FOLDED_ERROR_CODES.get(code) ?? { code };
+}
+
 /** The HTTP status of an error code, or undefined for a code that is not in the list. */
 export function httpStatusOf(code: unknown): number | undefined {
   return isProtocolErrorCode(code) ? ERROR_CODES[code].http : undefined;

package/src/server/browser-guard.ts

@@ -18,6 +18,8 @@
  * - A request with ambient credentials (the cookies that a browser sends by itself) is trusted
  *   only from a named origin. `"*"` does not open the origin check for it (CSRF). A list or a
  *   function of origins still does.
+ *
+ * Each refusal is the error `FORBIDDEN` of wire v1, with the status 403 and a reason (CLI-4).
  */
 
 import type { IncomingHttpHeaders } from "node:http";
@@ -53,10 +55,28 @@ export interface GuardedRequest {
   socket?: { localAddress?: string | undefined } | undefined;
 }
 
-/** The result of the checks: the request passes, or the HTTP status and the error to send. */
+/**
+ * The result of the checks: the request passes, or the HTTP status and the error to send.
+ *
+ * A refusal is the error `FORBIDDEN` of wire v1 with the status 403. Its `reason` tells which
+ * check refused the request. Before CLI-4, the checks gave the codes `FORBIDDEN_HOST`,
+ * `FORBIDDEN_ORIGIN`, `METHOD_NOT_ALLOWED` (405) and `UNSUPPORTED_MEDIA_TYPE` (415).
+ */
 export type GuardResult =
   | { readonly ok: true }
-  | { readonly ok: false; readonly status: 403 | 405 | 415; readonly code: string; readonly message: string };
+  | {
+      readonly ok: false;
+      readonly status: 403;
+      readonly code: "FORBIDDEN";
+      /** The check that refused the request, as in `documentation/WIRE-PROTOCOL.md`. */
+      readonly reason: "host-header-not-allowed" | "origin-not-allowed" | "method-not-allowed" | "media-type-not-allowed";
+      readonly message: string;
+    };
+
+/** The refusal of a check: the error `FORBIDDEN` of wire v1 with its reason (CLI-4). */
+function refusal(reason: Extract<GuardResult, { ok: false }>["reason"], message: string): Extract<GuardResult, { ok: false }> {
+  return { ok: false, status: 403, code: "FORBIDDEN", reason, message };
+}
 
 /** True for a host name or a bind address that only this computer can reach. */
 export function isLoopbackHost(host: string): boolean {
@@ -159,29 +179,29 @@ export function checkBrowserRequest(
   if (options.allowedHosts !== "*" && isLoopbackAddress(req.socket?.localAddress)) {
     const name = hostNameOf(headers.host);
     if (!LOOPBACK_NAMES.has(name) && !(options.allowedHosts ?? []).includes(name)) {
-      return { ok: false, status: 403, code: "FORBIDDEN_HOST", message: `Forbidden: the host "${name}" is not allowed` };
+      return refusal("host-header-not-allowed", `Forbidden: the host "${name}" is not allowed`);
     }
   }
 
   const origin = typeof headers.origin === "string" ? headers.origin : undefined;
   if (origin !== undefined) {
     if (!sameOrigin(origin, headers.host) && !originAllowedBy(origin, options.allowedOrigins, ambient)) {
-      return { ok: false, status: 403, code: "FORBIDDEN_ORIGIN", message: `Forbidden: the origin "${origin}" is not allowed` };
+      return refusal("origin-not-allowed", `Forbidden: the origin "${origin}" is not allowed`);
     }
   } else {
     const site = headers["sec-fetch-site"];
     if ((site === "cross-site" || site === "same-site") && (options.allowedOrigins !== "*" || ambient)) {
-      return { ok: false, status: 403, code: "FORBIDDEN_ORIGIN", message: "Forbidden: a request from another site" };
+      return refusal("origin-not-allowed", "Forbidden: a request from another site");
     }
   }
 
   if (http) {
     const method = (req.method ?? "GET").toUpperCase();
     if ((method === "GET" || method === "HEAD") && !options.allowGet) {
-      return { ok: false, status: 405, code: "METHOD_NOT_ALLOWED", message: "Call a procedure with POST" };
+      return refusal("method-not-allowed", "Forbidden: call a procedure with POST");
     }
     if (hasBody(headers) && !isJsonType(headers["content-type"])) {
-      return { ok: false, status: 415, code: "UNSUPPORTED_MEDIA_TYPE", message: "The request body must be JSON (Content-Type: application/json)" };
+      return refusal("media-type-not-allowed", "Forbidden: the request body must be JSON (Content-Type: application/json)");
     }
   }
 

package/src/server/procedure-server.ts

@@ -19,7 +19,7 @@ import { ProcedureRegistry, PROCEDURE_REGISTRY } from "../procedures/registry.js
 import { createCollectionProcedures } from "../procedures/collection/procedures.js";
 import { InvocationError, invokeProcedure, type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
 import type { Capability, ClearanceOrder, ProcedureContext, ResourcesOf } from "../procedures/types.js";
-import type { CollectionPartitions } from "../procedures/collection/partition.js";
+import { assertTopicsApart, type CollectionPartitions } from "../procedures/collection/partition.js";
 import { VERSION_CONFLICTS_METADATA_KEY, versionConflictsOf } from "../procedures/collection/precondition.js";
 import { TIMEOUT_METADATA_KEY, effectsOf, joinNarrowing, narrowCapability } from "../procedures/capability.js";
 import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptions } from "../procedures/idempotency.js";
@@ -343,6 +343,8 @@ function withRequestTimeout(
  * (VALIDATION_ERROR, NOT_EXPOSED, ABORTED and so on). An error of the handler keeps its own code
  * when it is a string, as for a stream (`WIRE-PROTOCOL.md`). Without a code, it is HANDLER_ERROR.
  * An error without a retryable flag gets the flag of its code in `ERROR_CODES`, or false (CLI-48).
+ * This default applies only before the stream starts. An in-band end without a flag gets false
+ * (CLI-58, `WIRE-PROTOCOL.md`, section "Error codes").
  */
 export function errorResponse(id: string, error: unknown): ServerResponse<unknown> {
   // An error that says it is retryable stays retryable: before, every error lost the flag
@@ -495,7 +497,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     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
+    // Configure collections. A new server has no partitions yet: usePartitions() examines these
+    // storages for a shared topic (roadmap CLI-57)
     if (options.collections) {
       for (const [name, storage] of Object.entries(options.collections)) {
         this.storages.set(name, storage);
@@ -577,15 +580,31 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    * 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()`).
    *
+   * The server refuses partitions of `a` while it has a storage of `a.b` (roadmap CLI-57, decision
+   * D23). The plain topic of `a.b` is the topic of the partition `b` of `a`. `useStorage` refuses
+   * the other order.
+   *
    * @param name - Collection name
    * @param partitions - The storage of each partition, and the resolver
    * @returns this (for chaining)
+   * @throws CollectionTopicCollisionError when the topic of a partition is the topic of a collection with a storage
    */
   usePartitions<T>(name: string, partitions: CollectionPartitions<T>): this {
+    assertTopicsApart(this.storages.keys(), (collection) => collection === name);
     this.partitions.set(name, partitions as CollectionPartitions<unknown>);
     return this;
   }
 
+  /**
+   * The check of the topics of new storages (roadmap CLI-57, decision D23). The plain topic of each
+   * one must not be the topic of a partition of a collection with partitions.
+   *
+   * @throws CollectionTopicCollisionError for the first pair with the same topic
+   */
+  private assertPlainTopicsApart(names: Iterable<string>): void {
+    assertTopicsApart(names, (collection) => this.partitions.has(collection));
+  }
+
   // ===========================================================================
   // Storage Configuration
   // ===========================================================================
@@ -606,15 +625,21 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    *   that took the old storage, for the time of `grace` at most. Before, such a call could fail
    *   because the storage was closed.
    *
+   * The server refuses a storage of `a.b` while `a` has partitions (roadmap CLI-57, decision D23).
+   * The plain topic of `a.b` is the topic of the partition `b` of `a`. With options, the promise
+   * rejects, and the old storage stays as it is.
+   *
    * @param name - Collection name
    * @param storage - Storage backend
    * @param options - Drain and close the old storage
    * @returns this (for chaining), or a promise of it when options are given
+   * @throws CollectionTopicCollisionError when the topic of the collection is the topic of a partition
    */
   useStorage<T>(name: string, storage: CollectionStorage<T>): this;
   useStorage<T>(name: string, storage: CollectionStorage<T>, options: UseStorageOptions): Promise<this>;
   useStorage<T>(name: string, storage: CollectionStorage<T>, options?: UseStorageOptions): this | Promise<this> {
     if (options === undefined) {
+      this.assertPlainTopicsApart([name]);
       this.storages.set(name, storage as CollectionStorage<unknown>);
       return this;
     }
@@ -626,6 +651,9 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
    * the old storage, and close it.
    */
   private async replaceStorage(name: string, storage: CollectionStorage<unknown>, options: UseStorageOptions): Promise<this> {
+    // Before the flush: a refused storage changes nothing (roadmap CLI-57). With an old storage,
+    // usePartitions() sees the name during the flush. Without one, no await comes before the set.
+    this.assertPlainTopicsApart([name]);
     const graceMs = optionalMs(options.grace, "grace") ?? TIMER_DEFAULTS.server.storageGraceMs;
     const old = this.storages.get(name);
     const other = old !== undefined && old !== storage ? old : undefined;
@@ -697,10 +725,15 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   /**
    * Configure multiple storages at once.
    *
+   * The server examines all the names before it sets a storage: a refused name sets none (roadmap
+   * CLI-57, decision D23).
+   *
    * @param storages - Map of collection names to storage backends
    * @returns this (for chaining)
+   * @throws CollectionTopicCollisionError when the topic of a collection is the topic of a partition
    */
   useStorages(storages: Record<string, CollectionStorage<unknown>>): this {
+    this.assertPlainTopicsApart(Object.keys(storages));
     for (const [name, storage] of Object.entries(storages)) {
       this.storages.set(name, storage);
     }

package/src/server/server.ts

@@ -349,12 +349,13 @@ export class Server {
       };
     }
 
-    // Generic error
+    // Another error: the server failed outside a handler of the protocol. The code is of wire v1
+    // (CLI-4: before, the code was the string "500").
     return {
       id,
       status: {
         type: "error",
-        code: "500",
+        code: "INTERNAL_ERROR",
         message: error.message || "Internal server error",
         retryable: false,
       },

package/src/server/types.ts

@@ -265,12 +265,13 @@ export class HandlerNotFoundError extends Error {
 }
 
 /**
- * Server error with status code.
+ * A server error with an error code. The default code is `INTERNAL_ERROR` of wire v1 (CLI-4:
+ * before, the default was the string `"500"`).
  */
 export class ServerError extends Error {
   constructor(
     message: string,
-    public readonly code: string = "500",
+    public readonly code: string = "INTERNAL_ERROR",
     public readonly retryable: boolean = false
   ) {
     super(message);