@procedures/client 0.8.1 → 0.9.1

package/src/adapters/http/server/handler.ts

@@ -27,8 +27,9 @@ import { PROTOCOL_HEADER, PROTOCOL_VERSION, httpStatusOf, protocolVersionOf } fr
 import { realClock, type Cancel, type Clock } from "../../../clock.js";
 import { ms, type Duration } from "../../../duration.js";
 import { NDJSON_MEDIA_TYPE as NDJSON, defaultNdjsonError as errorOf, keepAliveMsOf, writeNdjsonStream } from "./ndjson.js";
-import { createPatternServerUrlStrategy } from "./strategies.js";
 import { applyCors, corsOrigins, corsPolicy, type CorsOptions, type CorsPolicy } from "./cors.js";
+import { urlAddressing, type Addressing } from "./addressing.js";
+import { NARROWING_METADATA_KEY, addNarrowing } from "../../../procedures/narrowing.js";
 
 /** The parts of a request that a URL strategy of `procedureHandler` reads. */
 export interface UrlRequest {
@@ -58,9 +59,16 @@ export interface ProcedureHandlerOptions extends BrowserGuardOptions {
   readonly basePath?: string | undefined;
   /**
    * The method of a request. The default reads the URL format of `HttpTransport`:
-   * `{basePath}/{service}/{operation}`.
+   * `{basePath}/{service}/{operation}`. The option `addressing` replaces it.
    */
   readonly urlStrategy?: NodeUrlStrategy | undefined;
+  /**
+   * The addressing of a request (CLI-31): a hook of the request and its body that gives the
+   * method and the payload of the call. `bodyPathAddressing()` reads the path from the body of a
+   * single endpoint.
+   * @default urlAddressing({ basePath, urlStrategy })
+   */
+  readonly addressing?: Addressing | undefined;
   /**
    * The CORS headers of the requests on the path. `true` uses the defaults: each origin, without
    * credentials. The permitted origins of the browser checks follow the CORS origins.
@@ -207,6 +215,19 @@ const GUARD_REASONS: Record<string, string> = {
   UNSUPPORTED_MEDIA_TYPE: "media-type-not-allowed",
 };
 
+/** This function sets a key as an own property, also the key `__proto__` (the `put` of the query language). */
+function put(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
+
+/**
+ * This function sets a key at the root of the metadata. Each source of the narrowing key adds to
+ * the key, so no source replaces another (CLI-30).
+ */
+function setMetadata(metadata: Metadata, key: string, value: unknown): void {
+  metadata[key] = key === NARROWING_METADATA_KEY ? addNarrowing(metadata[key], value) : value;
+}
+
 /** This function writes a JSON response without a framework. */
 function writeJson(res: NodeResponse, status: number, body: unknown): void {
   const text = JSON.stringify(body);
@@ -286,14 +307,14 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
   assertNamedOrigins(compat.face?.name ?? "procedureHandler", ambientMode, guard.allowedOrigins, compat.face?.originOption ?? "cors.origin");
   const secretHeaders = headerNames(options.secretHeaders);
   const secretQuery = new Set(options.secretQuery ?? (legacy ? [] : ["token"]));
-  const strategy = options.urlStrategy ?? createPatternServerUrlStrategy(basePath);
-  const methodOf =
-    compat.methodOf ??
-    ((req: IncomingMessage): Method | null => {
-      const { path, query } = urlParts(req.url);
-      const view: UrlRequest = { method: (req.method ?? "GET").toUpperCase(), path, url: req.url ?? "/", headers: req.headers, query: queryRecord(query) };
-      return strategy(view, req);
-    });
+  // The addressing of a request (CLI-31): the option, or the URL strategy of the shim, or the URL
+  // format of HttpTransport
+  const compatMethodOf = compat.methodOf;
+  const addressing: Addressing =
+    options.addressing ??
+    urlAddressing(compatMethodOf ? { urlStrategy: (_view, req) => compatMethodOf(req) } : { basePath, urlStrategy: options.urlStrategy });
+  // A single endpoint (the path in the body) is the base path itself
+  const bareBase = prefix.slice(0, -1);
   const sendJson = compat.sendJson ?? writeJson;
 
   /** The controllers of the requests in progress: close() aborts them (deep dive TRN-15) */
@@ -309,7 +330,11 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     for (const waiter of waiters) waiter();
   };
 
-  const matches = (req: IncomingMessage): boolean => compat.matchAll === true || pathOf(req).startsWith(prefix);
+  const matches = (req: IncomingMessage): boolean => {
+    if (compat.matchAll === true) return true;
+    const path = pathOf(req);
+    return path.startsWith(prefix) || (addressing.takesBasePath === true && path === bareBase);
+  };
 
   /** The error body of wire v1: the message, the code, the retryable flag and the more fields. */
   const sendError = (res: NodeResponse, status: number, message: string, code: string, retryable = false, more: Record<string, unknown> = {}): void => {
@@ -349,16 +374,23 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     }
   };
 
-  /** This function converts an HTTP request to a `ServerRequest`, or null when the URL names no method. */
+  /**
+   * This function converts an HTTP request to a `ServerRequest`, or gives null when the addressing
+   * finds no call in the request.
+   */
   const toServerRequest = (req: IncomingMessage, body: unknown): ServerRequest | null => {
-    const method = methodOf(req);
-    if (!method) return null;
+    const { path, query: urlQuery } = urlParts(req.url);
+    const view: UrlRequest = { method: (req.method ?? "GET").toUpperCase(), path, url: req.url ?? "/", headers: req.headers, query: queryRecord(urlQuery) };
+    const address = addressing(view, body, req);
+    if (!address) return null;
+    const method = address.method;
 
     const id = (req.headers["x-request-id"] as string | undefined) ?? `req-${Date.now()}-${Math.random()}`;
 
     // The query without its secret parameters: they go into the credentials (CLI-2a)
+    // An own property for each key, also `__proto__`: a key of the request changes no prototype
     const query: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(queryOf(req))) if (!secretQuery.has(key)) query[key] = value;
+    for (const [key, value] of Object.entries(queryOf(req))) if (!secretQuery.has(key)) put(query, key, value);
     const params = paramsOf(req);
 
     // The metadata of the headers and of the query. The query parameters cannot replace headers,
@@ -370,17 +402,21 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
       params,
     };
     for (const [key, value] of Object.entries(query)) {
-      if (!RESERVED_METADATA.has(key) && !key.startsWith("__")) metadata[key] = value;
+      if (!RESERVED_METADATA.has(key) && !key.startsWith("__")) setMetadata(metadata, key, value);
     }
 
     // The custom headers at the root of the metadata, as the client's metadataToHeaders() sends
     // them. A secret header (Cookie too) does not go there.
     for (const [key, value] of Object.entries(req.headers)) {
       const lower = key.toLowerCase();
-      if (STANDARD_HEADERS.has(lower) || isSecretHeader(lower, secretHeaders) || typeof value !== "string") continue;
+      if (STANDARD_HEADERS.has(lower) || isSecretHeader(lower, secretHeaders) || typeof value !== "string" || lower === NARROWING_METADATA_KEY) continue;
       const normalizedKey = HEADER_MAPPINGS[lower] ?? key;
       if (!RESERVED_METADATA.has(normalizedKey) && !normalizedKey.startsWith("__")) metadata[normalizedKey] = value;
     }
+    // Each value of the narrowing header is one source, also each line of a repeated header. No
+    // source replaces another: a gateway's header and the client's key of X-Metadata both apply (CLI-30)
+    const narrowingHeader = req.headersDistinct?.[NARROWING_METADATA_KEY] ?? req.headers[NARROWING_METADATA_KEY];
+    for (const value of [narrowingHeader].flat()) if (typeof value === "string") setMetadata(metadata, NARROWING_METADATA_KEY, value);
 
     // The custom metadata of the HTTP client: any JSON value, any key (deep dive TRN-11)
     const encoded = req.headers["x-metadata"];
@@ -391,15 +427,13 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
       const custom = decodeMetadataHeader(encoded);
       if (!custom) throw new BodyError("The X-Metadata header is not URI-encoded JSON of an object", 400);
       for (const [key, value] of Object.entries(custom)) {
-        if (!RESERVED_METADATA.has(key) && key !== "auth" && !key.startsWith("__")) metadata[key] = value;
+        if (!RESERVED_METADATA.has(key) && key !== "auth" && !key.startsWith("__")) setMetadata(metadata, key, value);
       }
     }
 
-    // The payload: the body, or the id of a RESTful GET. Only an absent payload becomes {}: 0,
-    // false, "" and null stay (deep dive TRN-10)
-    let payload: unknown = body;
-    if (req.method === "GET" && params["id"]) payload = { id: params["id"] };
-    if (payload === undefined) payload = {};
+    // The payload of the addressing (the body, or the id of a RESTful GET). Only an absent payload
+    // becomes {}: 0, false, "" and null stay (deep dive TRN-10)
+    const payload: unknown = address.payload === undefined ? {} : address.payload;
 
     return {
       id,

package/src/adapters/http/server/strategies.ts

@@ -71,10 +71,17 @@ export function defaultServerUrlStrategy(req: RoutedRequest): Method | null {
  * Maps:
  * - POST /rpc/users/get → { service: "users", operation: "get" }
  * - POST /rpc/users/list → { service: "users", operation: "list" }
+ * - POST /rpc/morning → { service: "", operation: "morning" } (a path of one segment, CLI-28)
  */
 export function rpcServerUrlStrategy(req: RoutedRequest): Method | null {
   const path = req.path;
 
+  // A path of one segment: /rpc/:operation, with the empty service (CLI-28)
+  const single = path.match(/^\/rpc\/([^/]+)\/?$/);
+  if (single?.[1]) {
+    return { service: "", operation: single[1] };
+  }
+
   // Match pattern: /rpc/:service/:operation
   const match = path.match(/^\/rpc\/([^/]+)\/([^/]+)/);
   if (!match) {

package/src/adapters/http/server/transport.ts

@@ -42,7 +42,7 @@ export class HttpServerTransport implements ServerTransport {
 
   private app: Express;
   private httpServer: HttpServer | null = null;
-  private options: { port: number; host: string; basePath: string; cors: boolean; httpServer: HttpServer | undefined };
+  private options: { port: number; host: string; basePath: string; cors: boolean; httpServer: HttpServer | undefined; takesBasePath: boolean };
   /** The procedure handler that does the work of each request (CLI-3) */
   private readonly handler: NodeProcedureHandler;
   /** The CORS of the app, or undefined when it is off */
@@ -58,6 +58,8 @@ export class HttpServerTransport implements ServerTransport {
       basePath,
       cors: options.cors ?? false,
       httpServer: options.httpServer,
+      // A single endpoint with the path in the body is the base path itself (CLI-31)
+      takesBasePath: options.addressing?.takesBasePath === true,
     };
     // Route by URL path so the raw server matches the HTTP client's default URL format instead of
     // inferring the operation from the verb (BUGS-2026-07 C3, bug 16)
@@ -77,6 +79,7 @@ export class HttpServerTransport implements ServerTransport {
         allowGet: options.allowGet,
         secretHeaders: options.secretHeaders,
         secretQuery: options.secretQuery,
+        addressing: options.addressing,
       },
       {
         legacy: true,
@@ -116,9 +119,11 @@ export class HttpServerTransport implements ServerTransport {
       });
     }
 
-    // Catch-all route for RPC - use regex to match any path under basePath
+    // Catch-all route for RPC - use regex to match any path under basePath, and the base path
+    // itself for an addressing that takes it
+    const base = this.options.basePath.replace(/\//g, "\\/");
     this.app.all(
-      new RegExp(`^${this.options.basePath.replace(/\//g, "\\/")}\\/.*`),
+      new RegExp(this.options.takesBasePath ? `^${base.replace(/\\\/$/, "")}(?:\\/.*)?$` : `^${base}\\/.*`),
       async (req, res) => {
         await this.handler.handle(req, res);
       }

package/src/adapters/http/server/types.ts

@@ -10,6 +10,7 @@ import type { Method } from "../../../client/types.js";
 import type { BrowserGuardOptions } from "../../../server/browser-guard.js";
 import type { Clock } from "../../../clock.js";
 import type { Duration } from "../../../duration.js";
+import type { Addressing } from "./addressing.js";
 
 /**
  * URL strategy for converting HTTP requests to RPC methods.
@@ -51,6 +52,13 @@ export interface HttpServerTransportOptions extends BrowserGuardOptions {
    */
   urlStrategy?: HttpUrlStrategy;
 
+  /**
+   * The addressing of a request (CLI-31): a hook of the request and its body that gives the
+   * method and the payload of the call. It replaces `urlStrategy`. With `bodyPathAddressing()`,
+   * the route takes the base path itself too.
+   */
+  addressing?: Addressing;
+
   /**
    * Base path for RPC endpoints.
    * @default "/api"

package/src/adapters/http/shared/strategies.ts

@@ -60,6 +60,13 @@ export interface UrlPattern {
  * Examples:
  * - { service: "users", operation: "get" } → "/users/get"
  * - { service: "users", operation: "get", version: "v2" } → "/v2/users/get"
+ * - { service: "", operation: "morning" } → "/morning" (a path of one segment, CLI-28)
+ *
+ * A path gives one URL segment (a path of one segment) or two (the service with dots, and the
+ * operation). Each URL segment is URI-encoded, so a path segment does not make a URL separator.
+ * Thus only the version makes three URL segments, and the forms do not collide. A path of one
+ * segment has no version in the URL: `/{version}/{operation}` reads as `/{service}/{operation}`.
+ * The server ignores the version (wire protocol v1).
  */
 export const defaultUrlPattern: UrlPattern = {
   template: "/{version?}/{service}/{operation}",
@@ -67,11 +74,13 @@ export const defaultUrlPattern: UrlPattern = {
   format(method: Method, baseUrl: string): string {
     const parts = [baseUrl.replace(/\/$/, "")];
 
-    if (method.version) {
-      parts.push(method.version);
+    // The version needs a service: without one, it reads as the service (CLI-28)
+    if (method.version && method.service !== "") {
+      parts.push(encodeURIComponent(method.version));
     }
 
-    parts.push(method.service, method.operation);
+    if (method.service !== "") parts.push(encodeURIComponent(method.service));
+    parts.push(encodeURIComponent(method.operation));
 
     return parts.join("/");
   },
@@ -79,11 +88,11 @@ export const defaultUrlPattern: UrlPattern = {
   parse(url: string, _httpMethod: HTTPMethod): Method | null {
     // Remove base URL and query params
     const path = url.split("?")[0];
-    const segments = path?.split("/").filter(Boolean) ?? [];
+    const segments = (path?.split("/").filter(Boolean) ?? []).map(decodeSegment);
 
-    // Minimum: /service/operation (2 segments)
-    if (segments.length < 2) {
-      return null;
+    // A path of one segment: /operation, with the empty service (CLI-28)
+    if (segments.length === 1) {
+      return { service: "", operation: segments[0]! };
     }
 
     // Pattern: [version?]/service/operation
@@ -106,6 +115,15 @@ export const defaultUrlPattern: UrlPattern = {
   },
 };
 
+/** A URL segment without its URI encoding. A segment that is not valid URI encoding stays as it is. */
+function decodeSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
 /**
  * RESTful URL Pattern: /{version?}/{service}/{id?}
  *

package/src/adapters/local/client/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Message, Method } from "../../../client/types.js";
+import { methodName } from "../../../server/method.js";
 import type { ProcedureRegistry } from "../../../procedures/registry.js";
 import type { Interceptor } from "../../../procedures/invoke.js";
 import type { Capability, ClearanceOrder } from "../../../procedures/types.js";
@@ -23,7 +24,8 @@ export type Handler<TReq = unknown, TRes = unknown> = (
  */
 export function methodKey(method: Method): string {
   const version = method.version || "";
-  return `${version}:${method.service}.${method.operation}`;
+  // A path of one segment has the key of its operation: "morning", not ".morning" (CLI-28)
+  return `${version}:${methodName(method)}`;
 }
 
 /**

package/src/adapters/websocket/client/transport.ts

@@ -578,18 +578,10 @@ export class WebSocketTransport implements Transport {
       return;
     }
 
-    // The frame type `event` is reserved: no side of protocol v1 sends it. A server outside this
-    // repository can send it, so the frame still goes to onEvent (EVENTS.md).
-    if (message.type === "event") {
-      if (this.options.onEvent && message.topic && message.subscriptionId) {
-        try {
-          this.options.onEvent(message.topic, message.data, message.subscriptionId);
-        } catch (error) {
-          console.error(`[${this.name}] Event handler error:`, error);
-        }
-      }
-      return;
-    }
+    // The frame type `event` is reserved: no side of protocol v1 sends it. The client ignores it,
+    // as a frame of an unknown type. Before 0.9.0, it gave the frame to onEvent, for a server
+    // outside this repository (EVENTS.md). onEvent gets the events of the subscriptions only.
+    if (message.type === "event") return;
 
     // Handle response
     const pending = this.pendingRequests.get(message.id);

package/src/browser.ts

@@ -87,7 +87,7 @@ export {
   HandlerNotFoundError,
   ServerError,
 } from "./server/types.js";
-export { pathToMethod, methodToPath } from "./server/method.js";
+export { pathToMethod, methodToPath, methodName } from "./server/method.js";
 export type {
   ServerRequest,
   ServerResponse,
@@ -124,6 +124,10 @@ export {
   // The change events of the collection writes (roadmap CLI-15)
   collectionChangeTopic,
   collectionTopicReads,
+  // The partitions of a collection (roadmap CLI-17)
+  PARTITION_PATTERN,
+  collectionTopicPartition,
+  collectionTopicTarget,
   // The query language of the collection storages (roadmap CLI-14, CLI-34)
   DEFAULT_FIND_LIMIT,
   DEFAULT_QUERY_OPERATORS,
@@ -275,6 +279,9 @@ export type {
   StorageQueryPolicy,
   CollectionProceduresOptions,
   CollectionChangeEventsOptions,
+  CollectionPartitions,
+  PartitionInput,
+  PartitionResolver,
   CollectionChangeEvent,
   ProcedureModule,
   ModuleInput,
@@ -373,6 +380,10 @@ export type { ProtocolErrorCode, ErrorCodeInfo } from "./protocol.js";
 export { STREAM_GAP_METADATA_KEY, STREAM_ITEM_METADATA_KEY } from "./adapters/sequence.js";
 // The deadline of a call: the remaining time goes as procedure-timeout (roadmap R10)
 export { TIMEOUT_METADATA_KEY, DEADLINE_METADATA_KEY } from "./client/deadline.js";
+// The narrowing key of a call: the call asks for a narrower capability on each face (CLI-30)
+export { NARROWING_METADATA_KEY, NARROWING_HEADER, narrowingOf, narrowWithin, addNarrowing } from "./procedures/narrowing.js";
+export type { NarrowingNote, WireNarrowing, NarrowedCapability } from "./procedures/narrowing.js";
+export type { ServerDebugReport } from "./server/types.js";
 // Typed durations: each public option that is a time takes a Duration (roadmap R11)
 export { ms, seconds, minutes, hours, toMs, optionalMs, isDuration } from "./duration.js";
 export type { Duration, TimeUnit } from "./duration.js";

package/src/client/client.ts

@@ -171,13 +171,20 @@ export interface ExecOptions {
    * (`observeHydration()` gets the events of every program in the process.)
    */
   onRef?: ((event: HydrationEvent) => void) | undefined;
+  /**
+   * The metadata of the program. A local procedure gets it as `ctx.metadata`, and a remote call
+   * sends it. The narrowing key `procedure-narrowing` narrows the capability of each call of the
+   * program, local or remote (CLI-30).
+   */
+  metadata?: Record<string, unknown> | undefined;
 }
 
-/** The caller context of `exec()` and `execStream()`: the observer and the signal. */
+/** The caller context of `exec()` and `execStream()`: the observer, the signal and the metadata. */
 function callerOf(options: ExecOptions): CallerContext {
   const caller: CallerContext = {};
   if (options.onRef) caller.onRef = options.onRef;
   if (options.signal) caller.signal = options.signal;
+  if (options.metadata) caller.metadata = options.metadata;
   return caller;
 }
 

package/src/client/errors/factory.ts

@@ -13,6 +13,7 @@ import {
 import { getErrorMetadata } from "./registry.js";
 import { httpStatusToErrorCode } from "./http-errors.js";
 import { ErrorCode } from "./codes.js";
+import { methodName } from "../../server/method.js";
 
 /**
  * Create a rich error from an error code.
@@ -226,9 +227,7 @@ export function formatError(error: RichError, includeStack = false): string {
 
   if (error.context.method) {
     const m = error.context.method;
-    const methodStr = m.version
-      ? `${m.version}:${m.service}.${m.operation}`
-      : `${m.service}.${m.operation}`;
+    const methodStr = m.version ? `${m.version}:${methodName(m)}` : methodName(m);
     lines.push(`  Method: ${methodStr}`);
   }
 

package/src/client/middleware/cache.ts

@@ -11,6 +11,7 @@ import { LruMap } from "./lru.js";
 import { isDuration, optionalMs, type Duration } from "../../duration.js";
 import type { Effects } from "../../procedures/types.js";
 import { TIMER_DEFAULTS } from "../../timers.js";
+import { methodName } from "../../server/method.js";
 
 /**
  * Cache middleware options.
@@ -287,7 +288,7 @@ export function createCacheMiddleware(options: CacheOptions): TypedClientMiddlew
   const cacheable =
     typeof methods === "function"
       ? methods
-      : ((names: ReadonlySet<string>) => (method: Method): boolean => names.has(`${method.service}.${method.operation}`))(
+      : ((names: ReadonlySet<string>) => (method: Method): boolean => names.has(methodName(method)))(
           new Set(methods),
         );
   const effectsOf = options.effects;

package/src/events/publisher.ts

@@ -28,8 +28,10 @@ import { z } from "zod";
 import { createProcedure } from "../procedures/define.js";
 import { InvocationError } from "../procedures/invoke.js";
 import { capabilityRefusal } from "../procedures/capability.js";
-import { collectionTopicReads } from "../procedures/collection/changes.js";
+import { collectionChangeTopic, collectionTopicReads } from "../procedures/collection/changes.js";
+import { collectionTopicTarget, partitionOfCall } from "../procedures/collection/partition.js";
 import type { AnyProcedure, Capability, ProcedureContext } from "../procedures/types.js";
+import type { Principal } from "../server/types.js";
 import type { EventBus, Unsubscribe } from "./types.js";
 import { getGlobalEventBus } from "./bus.js";
 import { EVENTS_SUBSCRIBE_PATH, type EventItem, type SubscribeInput } from "./remote.js";
@@ -53,6 +55,8 @@ export interface TopicCall {
   readonly capability: Capability;
   /** The metadata of the call: the connection id and the headers of a network request. */
   readonly metadata: Readonly<Record<string, unknown>>;
+  /** The principal of the call, from the authentication of the host. */
+  readonly principal?: Principal | undefined;
 }
 
 /** The options of an `EventPublisher`. */
@@ -77,7 +81,12 @@ export interface EventPublisherOptions {
    * The resources that a subscriber of a topic reads (roadmap CLI-15). The publisher refuses a
    * topic whose reads the capability of the call does not permit, as for a procedure that reads
    * them: `FORBIDDEN` with the reason `effects-exceeded`.
-   * @default `collectionTopicReads`: a topic `collections.<name>` reads `collection:<name>`
+   *
+   * A custom function gets only the topic. For a topic of a collection, give the read of the
+   * collection that the publisher listens to: the collection of `collectionTopicTarget(topic,
+   * repository)` with the repository of the host. A function that reads the first part of the
+   * topic alone checks `collection:a` for the dotted collection `a.b`.
+   * @default the read of the collection of `collectionTopicTarget()`, with the repository of the call
    */
   reads?: ((topic: string) => readonly string[]) | undefined;
 }
@@ -161,17 +170,18 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
 
   constructor(
     bus: EventBus,
-    topics: readonly string[],
+    /** The topics of the subscriber, each with the topic of the bus that it listens to */
+    routes: ReadonlyArray<readonly [topic: string, busTopic: string]>,
     private readonly buffer: number,
     private readonly signal: AbortSignal | undefined,
     private readonly onClose: (subscription: TopicSubscription) => void,
     /** The output filter of the host for this subscriber: each row of a value passes it */
     private readonly admit: ((item: unknown) => Promise<boolean>) | undefined,
   ) {
-    this.confirmation = { type: "subscribed", topics };
+    this.confirmation = { type: "subscribed", topics: routes.map(([topic]) => topic) };
     // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
-    this.unsubscribes = topics.map((topic) =>
-      bus.on(topic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
+    this.unsubscribes = routes.map(([topic, busTopic]) =>
+      bus.on(busTopic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
     );
     signal?.addEventListener("abort", this.onAbort, { once: true });
   }
@@ -304,6 +314,8 @@ export class EventPublisher {
   private readonly known: (topic: string) => boolean;
   private readonly allow: EventPublisherOptions["allow"];
   private readonly reads: (topic: string) => readonly string[];
+  /** True when the reads come from the topic rule of the collections (no option `reads`) */
+  private readonly defaultReads: boolean;
   private readonly buffer: number;
   private readonly open = new Set<TopicSubscription>();
 
@@ -312,6 +324,7 @@ export class EventPublisher {
     this.known = topicMatcher(options.topics);
     this.allow = options.allow;
     this.reads = options.reads ?? collectionTopicReads;
+    this.defaultReads = options.reads === undefined;
     this.buffer = Math.max(1, Math.floor(options.buffer ?? 1024));
     this.procedure = createProcedure()
       .path([...EVENTS_SUBSCRIBE_PATH])
@@ -344,31 +357,57 @@ export class EventPublisher {
     for (const subscription of [...this.open]) subscription.fail(stoppedError());
   }
 
+  /**
+   * The topic of the bus for a topic of a subscriber (roadmap CLI-17). A topic of a partitioned
+   * collection names the partition that the subscriber asks for, as the input of a procedure does:
+   * the resolver of the repository gives the partition, so a subscriber cannot name the topic of
+   * another tenant. A collection without partitions refuses a topic with a partition.
+   */
+  private async busTopic(topic: string, ctx: ProcedureContext): Promise<string> {
+    const target = collectionTopicTarget(topic, ctx.repository);
+    if (!target) return topic;
+    const partition = await partitionOfCall(ctx, target.collection, target.partition);
+    return collectionChangeTopic(target.collection, partition);
+  }
+
+  /**
+   * The resources that a subscriber of a topic reads. The default reads the collection of the
+   * topic with the rule of the listener (`collectionTopicTarget`), so the read check and the
+   * listener name the same collection.
+   */
+  private readsOf(topic: string, ctx: ProcedureContext): readonly string[] {
+    if (!this.defaultReads) return this.reads(topic);
+    const target = collectionTopicTarget(topic, ctx.repository);
+    return target ? [`collection:${target.collection}`] : [];
+  }
+
   /**
    * The stream of one subscription. The publisher examines each topic before it adds a listener:
-   * the topic rule first, then `allow`. A call with one bad topic makes no subscription.
+   * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
    */
-  private subscribe(topics: readonly string[], ctx: ProcedureContext): TopicSubscription {
+  private async subscribe(topics: readonly string[], ctx: ProcedureContext): Promise<TopicSubscription> {
     const unique = [...new Set(topics)];
     for (const topic of unique) {
       if (!this.known(topic)) throw new TopicNotFoundError(`The host has no topic "${topic}"`);
     }
     // A subscriber of a topic reads its resources: the capability of the call must permit them
     for (const topic of unique) {
-      const reads = this.reads(topic);
+      const reads = this.readsOf(topic, ctx);
       if (reads.length === 0) continue;
       const refusal = capabilityRefusal(topicReader(reads), ctx.capability);
       if (refusal) throw new InvocationError("FORBIDDEN", `The topic "${topic}": ${refusal.message}`, ctx.path, refusal.reason);
     }
     if (this.allow) {
-      const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata };
+      const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata, ...(ctx.principal ? { principal: ctx.principal } : {}) };
       for (const topic of unique) {
         if (!this.allow(topic, call)) {
           throw new InvocationError("FORBIDDEN", `The capability of the call does not permit the topic "${topic}"`, ctx.path, "topic-not-allowed");
         }
       }
     }
-    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit);
+    const routes: Array<readonly [string, string]> = [];
+    for (const topic of unique) routes.push([topic, await this.busTopic(topic, ctx)]);
+    const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit);
     this.open.add(subscription);
     return subscription.closeIfAborted();
   }

package/src/node.ts

@@ -14,6 +14,10 @@
  * gives a request handler `(req, res) => boolean`, and `upgradeHandler(server, options)` gives an
  * upgrade handler `(req, socket, head) => boolean`. Each one takes the requests of its path and
  * gives `false` for the others, so the routes of the application share the listener.
+ *
+ * The option `addressing` of `procedureHandler` gives the method and the payload of a request
+ * (CLI-31). `urlAddressing()` is the default, and `bodyPathAddressing()` reads the path from the
+ * body of a single endpoint.
  */
 
 export { WebSocketTransport } from "./adapters/websocket/client/node.js";
@@ -25,6 +29,9 @@ export type { ProcedureHandlerOptions, NodeProcedureHandler, NodeUrlStrategy, Ur
 export type { CorsOptions } from "./adapters/http/server/cors.js";
 export type { RoutedRequest } from "./adapters/http/server/strategies.js";
 export { defaultServerUrlStrategy, rpcServerUrlStrategy } from "./adapters/http/server/strategies.js";
+// The addressing of a request: the URL (the default), or the path in the body of a single endpoint (CLI-31)
+export { urlAddressing, bodyPathAddressing } from "./adapters/http/server/addressing.js";
+export type { Addressing, CallAddress, UrlAddressingOptions, BodyPathAddressingOptions } from "./adapters/http/server/addressing.js";
 export { upgradeHandler } from "./adapters/websocket/server/upgrade.js";
 export type { UpgradeHandlerOptions, NodeUpgradeHandler } from "./adapters/websocket/server/upgrade.js";
 export { WebSocketServerTransport } from "./adapters/websocket/server/transport.js";

package/src/procedures/collection/changes.ts

@@ -56,11 +56,11 @@ export interface CollectionChangeEvent {
 }
 
 /**
- * This function gives the topic of the change events of a collection: `collections.<name>`. The
- * partition of roadmap CLI-17 comes after the name, with the option `topic` of the procedures.
+ * This function gives the topic of the change events of a collection: `collections.<name>`, or
+ * `collections.<name>.<partition>` for a partition (roadmap CLI-17).
  */
-export function collectionChangeTopic(collection: string): string {
-  return `collections.${collection}`;
+export function collectionChangeTopic(collection: string, partition?: string): string {
+  return partition === undefined ? `collections.${collection}` : `collections.${collection}.${partition}`;
 }
 
 /**

package/src/procedures/collection/index.ts

@@ -70,6 +70,10 @@ export type { CollectionProceduresOptions, CollectionChangeEventsOptions } from
 export { collectionChangeTopic, collectionTopicReads } from "./changes.js";
 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";
+export type { CollectionPartitions, PartitionInput, PartitionResolver } from "./partition.js";
+
 // The storage interface of the core (the shape of client-collections' CollectionStorage)
 export type {
   CollectionStorage,