@cortexkit/subc-client 0.11.1 → 0.13.0

package/src/client.ts

@@ -22,12 +22,15 @@ import {
   FrameType,
   hasBinary,
   Priority,
+  SUBSCRIPTION_FLAG,
   type Frame,
 } from "./envelope.js";
 import {
   belongsToConnection,
   createRouteHandle,
   newConnectionToken,
+  reverseRequestHandler,
+  ReverseRequestRegistry,
   RouteHandle,
   sameRouteHandle,
   StaleRouteHandleError,
@@ -45,7 +48,7 @@ import {
 const debug = debuglog("subc-client");
 
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
-const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 // When a request-timeout timer fires, its reply may already be sitting in the
 // socket read buffer, unprocessed only because the event loop was starved (Node
 // runs the TIMERS phase before the POLL phase, so an expired timer can beat an
@@ -56,8 +59,8 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 // one loop turn. This is a demux tiebreak for a reply that RACED the deadline,
 // NOT a deadline extension: an absent reply still settles right after the check
 // phase. Capped so it can never approach BODY_READ_TIMEOUT_MS.
-const TIMEOUT_ARBITRATION_GRACE_MS = 50;
-const LIVENESS_PROBE_WINDOW_MS = 2000;
+export const TIMEOUT_ARBITRATION_GRACE_MS = 50;
+export const LIVENESS_PROBE_WINDOW_MS = 2000;
 // Internal marker set as the `code` on the SubcError a request-deadline timeout
 // rejects with, so the managed classifier can tell a deadline (reply may simply
 // not have been read in time) from an actual connection drop. Never surfaced to
@@ -79,7 +82,7 @@ const DEADLINE_NO_DROP_CODE = "deadline_exceeded_no_drop_observed";
 // rejects with module_timeout, so the deadline must leave room for MULTIPLE
 // full relay waits or one slow bind exhausts the whole retry clock. 30s allows
 // ~2 full relay timeouts plus backoff before surfacing not_sent.
-const ROUTE_OPEN_RETRY_DEADLINE_MS = 30_000;
+export const ROUTE_OPEN_RETRY_DEADLINE_MS = 30_000;
 // Once a header arrives, its body must follow promptly; bound it so a truncated
 // frame cannot wedge the read loop forever.
 const BODY_READ_TIMEOUT_MS = 30_000;
@@ -109,8 +112,11 @@ export interface ConsumerIdentity {
 export interface RouteOpenOptions {
   /** Optional override for the consumer identity; by default the SUBC_MODULE_ID and SUBC_LAUNCH_NONCE environment variables are used when both are non-empty. Set null to send route.open without consumer_identity. */
   consumerIdentity?: ConsumerIdentity | null;
-  /** Optional consumer-declared reverse-request capabilities for this route.open. This is a declaration, not a verified privilege; providers must treat an omitted field as no reverse-request capability. Known MCP method-family values today are "elicitation", "sampling", and "roots". */
-  consumerCapabilities?: string[];
+  /**
+   * Handlers prepared before route.open. The client derives consumer_capabilities
+   * from this registry; callers cannot declare a capability without a handler.
+   */
+  reverseRequests?: ReverseRequestRegistry;
 }
 
 export interface CatalogCapabilityRequirement {
@@ -168,6 +174,22 @@ export interface RequestOptions {
   binary?: boolean;
   /** Called for each interim PUSH / StreamData frame before the terminal reply. */
   onProgress?: (body: Uint8Array) => void;
+  /**
+   * Abort the request: when this fires while the request is still in flight, the
+   * client emits a CANCEL frame carrying that request's own corr.
+   *
+   * The signal exists instead of exposing corr because corr lifetime is already
+   * tracked here to settle replies; handing it out would make every caller keep a
+   * second map that can disagree with this one, and would let a caller cancel a
+   * corr it does not own.
+   *
+   * Cancellation is best-effort by the wire's construction: the daemon forwards
+   * the frame on a live route and silently drops it on a departed one, and no
+   * acknowledgement exists at any layer. Only the module's own reply proves what
+   * happened, so the promise is NOT rejected here -- it settles however the module
+   * answers, which may be a normal completion that beat the cancel.
+   */
+  signal?: AbortSignal;
 }
 
 export interface ManagedCallOptions extends RequestOptions {
@@ -177,6 +199,8 @@ export interface ManagedCallOptions extends RequestOptions {
   targetKind?: ManagedRouteKind;
   /** Optional override for the consumer identity; by default the SUBC_MODULE_ID and SUBC_LAUNCH_NONCE environment variables are used when both are non-empty. Set null to send route.open without consumer_identity. */
   consumerIdentity?: ConsumerIdentity | null;
+  /** Reverse-request handlers used by the managed route and all of its reconnect reopens. */
+  reverseRequests?: ReverseRequestRegistry;
 }
 
 export interface SubscribeOptions {
@@ -205,6 +229,8 @@ export interface CloseRouteOptions {
 export interface ManagedCloseRouteOptions extends CloseRouteOptions {
   /** Consumer identity used by the cached managed route. */
   consumerIdentity?: ConsumerIdentity | null;
+  /** The registry whose derived capability set identifies the cached route. */
+  reverseRequests?: ReverseRequestRegistry;
 }
 
 /**
@@ -452,6 +478,7 @@ interface CachedRoute {
   target: Extract<RouteTarget, { kind: ManagedRouteKind }>;
   identity: BindIdentity;
   consumerIdentity?: ConsumerIdentity;
+  reverseRequests: ReverseRequestRegistry;
   handle: RouteHandle | null;
   opening: Promise<RouteHandle> | null;
   /**
@@ -550,13 +577,15 @@ export class SubcClient {
   /** Open a route and return its connection-bound immutable handle. */
   async routeOpen(target: RouteTarget, identity: BindIdentity, opts: RouteOpenOptions = {}): Promise<RouteHandle> {
     const consumerIdentity = routeOpenConsumerIdentity(opts);
-    const consumerCapabilities = opts.consumerCapabilities;
+    const reverseRequests = opts.reverseRequests ?? new ReverseRequestRegistry();
+    reverseRequests.seal();
+    const consumerCapabilities = reverseRequests.capabilities();
     const body = this.encode({
       op: "route.open",
       target,
       identity,
       ...(consumerIdentity ? { consumer_identity: consumerIdentity } : {}),
-      ...(consumerCapabilities !== undefined ? { consumer_capabilities: consumerCapabilities } : {}),
+      ...(consumerCapabilities.length > 0 ? { consumer_capabilities: consumerCapabilities } : {}),
     });
 
     let installed: RouteHandle | null = null;
@@ -566,7 +595,7 @@ export class SubcClient {
       if (typeof parsed.route_channel !== "number" || typeof parsed.route_epoch !== "number") {
         throw new SubcError(`route.open returned no route handle: ${JSON.stringify(parsed)}`);
       }
-      installed = this.installRoute(parsed.route_channel, parsed.route_epoch);
+      installed = this.installRoute(parsed.route_channel, parsed.route_epoch, reverseRequests);
       return true;
     };
     const closeLateRoute = (frame: Frame): void => {
@@ -605,6 +634,7 @@ export class SubcClient {
       undefined,
       undefined,
       binary,
+      opts.signal,
     );
     return this.decodeReply(reply);
   }
@@ -732,7 +762,7 @@ export class SubcClient {
       this.pending.set(key, subscriptionPending);
       const frame = buildFrame(
         FrameType.Request,
-        buildFlags(false, priority, false, admission),
+        buildFlags(false, priority, false, admission) | SUBSCRIPTION_FLAG,
         handle.channel,
         handle.epoch,
         corr,
@@ -754,6 +784,39 @@ export class SubcClient {
     return { unsubscribe, closed };
   }
 
+  /**
+   * Emit CANCEL for one in-flight request when its caller's signal fires.
+   *
+   * Emits only while the request is unsettled by this client's own book, which is
+   * a fact it owns and can check without racing. It deliberately does NOT check
+   * whether the route still exists: that would be a guess, and a wrong guess turns
+   * a frame the daemon would harmlessly drop into a frame never sent -- removing
+   * the caller's only chance at the cost of saving nothing.
+   */
+  private attachCancelSignal(
+    signal: AbortSignal,
+    key: string,
+    handle: RouteHandle | null,
+    corr: bigint,
+    priority: Priority,
+  ): void {
+    if (!handle) return;
+    const emit = (): void => {
+      if (!this.pending.has(key)) return;
+      try {
+        this.cancel(handle, corr, priority);
+      } catch {
+        // A stale handle or a closed socket cannot be acted on, and the caller
+        // already treats an unanswered cancel as unknown rather than as failure.
+      }
+    };
+    if (signal.aborted) {
+      emit();
+      return;
+    }
+    signal.addEventListener("abort", emit, { once: true });
+  }
+
   /** Send a pure-header cancellation for an in-flight request. */
   cancel(handle: RouteHandle, corr: bigint, priority: Priority = Priority.Interactive): void {
     this.assertLiveHandle(handle);
@@ -807,7 +870,12 @@ export class SubcClient {
     identity: BindIdentity,
     opts: ManagedCloseRouteOptions = {},
   ): Promise<void> {
-    const key = routeCacheKey(target, identity, routeOpenConsumerIdentity(opts));
+    const key = routeCacheKey(
+      target,
+      identity,
+      routeOpenConsumerIdentity(opts),
+      (opts.reverseRequests ?? new ReverseRequestRegistry()).capabilities(),
+    );
     const cached = this.routes.get(key);
     if (!cached) return;
     cached.closed = true;
@@ -899,6 +967,7 @@ export class SubcClient {
     acceptFrame?: (frame: Frame) => boolean,
     onLateResponse?: (frame: Frame) => void,
     binary = false,
+    signal?: AbortSignal,
   ): Promise<Frame> {
     if (handle) this.assertLiveHandle(handle);
     if (this.closedErr) return Promise.reject(this.closedErr);
@@ -933,6 +1002,7 @@ export class SubcClient {
       };
       pending.timer = setTimeout(() => this.arbitrateTimeout(key, pending, channel, corr, ms), ms);
       this.pending.set(key, pending);
+      if (signal) this.attachCancelSignal(signal, key, handle, corr, priority);
       writeBorrowed(this.sock, encodeFrame(frame), Date.now() + ms).catch((error) => {
         const current = this.pending.get(key);
         if (current) this.rejectPending(key, current, error instanceof Error ? error : new SubcError(String(error)));
@@ -991,6 +1061,7 @@ export class SubcClient {
         opts.timeoutMs,
         opts.onProgress,
         binary,
+        opts.signal,
       );
       return this.decodeReply(reply);
     } catch (error) {
@@ -1007,6 +1078,7 @@ export class SubcClient {
     timeoutMs: number | undefined,
     onProgress: ((body: Uint8Array) => void) | undefined,
     binary = false,
+    signal?: AbortSignal,
   ): Promise<Frame> {
     try {
       this.assertLiveHandle(handle);
@@ -1061,6 +1133,7 @@ export class SubcClient {
       };
       pending.timer = setTimeout(() => this.arbitrateTimeout(key, pending, handle.channel, corr, ms), ms);
       this.pending.set(key, pending);
+      if (signal) this.attachCancelSignal(signal, key, handle, corr, priority);
       const write = writeTrackedBorrowed(this.sock, encodeFrame(frame), Date.now() + ms);
       handedToSocket = write.queued;
       write.completed.catch((error) => {
@@ -1084,7 +1157,9 @@ export class SubcClient {
       { kind: ManagedRouteKind }
     >;
     const consumerIdentity = routeOpenConsumerIdentity(opts);
-    const key = routeCacheKey(target, identity, consumerIdentity);
+    const reverseRequests = opts.reverseRequests ?? new ReverseRequestRegistry();
+    reverseRequests.seal();
+    const key = routeCacheKey(target, identity, consumerIdentity, reverseRequests.capabilities());
     let cached = this.routes.get(key);
     if (!cached) {
       cached = {
@@ -1093,6 +1168,7 @@ export class SubcClient {
         target,
         identity,
         consumerIdentity,
+        reverseRequests,
         handle: null,
         opening: null,
       };
@@ -1123,6 +1199,7 @@ export class SubcClient {
       try {
         const handle = await this.routeOpen(cached.target, cached.identity, {
           consumerIdentity: cached.consumerIdentity ?? null,
+          reverseRequests: cached.reverseRequests,
         });
         if (cached.closed) {
           this.liveRoutes.delete(handle.channel);
@@ -1346,6 +1423,7 @@ export class SubcClient {
       try {
         const handle = await this.routeOpen(cached.target, cached.identity, {
           consumerIdentity: cached.consumerIdentity ?? null,
+          reverseRequests: cached.reverseRequests,
         });
         if (cached.closed) {
           this.liveRoutes.delete(handle.channel);
@@ -1449,6 +1527,11 @@ export class SubcClient {
       }
     }
 
+    if (frame.header.ty === FrameType.Request && handle) {
+      this.dispatchReverseRequest(frame, handle);
+      return;
+    }
+
     const key = pendingKey(handle, frame.header.corr);
     const pending = this.pending.get(key);
     if (pending) {
@@ -1552,6 +1635,109 @@ export class SubcClient {
     this.settle(key, pending, () => pending.reject(pending.classifyFailure?.(err) ?? err));
   }
 
+  private dispatchReverseRequest(frame: Frame, handle: RouteHandle): void {
+    const method = reverseRequestMethod(frame.body);
+    const methodFamily = method?.split("/", 1)[0];
+    const handler = methodFamily ? reverseRequestHandler(handle, methodFamily) : undefined;
+    const sock = this.sock;
+    const generation = this.generation;
+
+    // ONE CODE, TWO SITES, ON PURPOSE. `reverse_request_unhandled` is emitted
+    // both here (no handler registered) and below (a handler that threw), with
+    // different MESSAGES and the same CODE. That is a ruling, not an oversight:
+    // the distinction between "nobody listening" and "the listener broke" is
+    // ours to log, and every provider's decision is identical for both -- not
+    // granted, retry later. A second code would be a second thing every
+    // consumer's decoder must learn for a branch none of them takes. If one ever
+    // needs it, the message carries it. (Settled with prefrontal, the lane's
+    // first consumer, before anyone pinned on it.)
+    //
+    // What must NOT join them: a handler that RETURNS bytes declining the
+    // request answers with an ordinary Response in the provider's own
+    // vocabulary. Error means "the consumer did not answer", never "the consumer
+    // said no" -- that separation is the reason this lane exists.
+    const reply = async (): Promise<void> => {
+      if (!handler || !method) {
+        await this.sendReverseError(
+          frame,
+          handle,
+          "reverse_request_unhandled",
+          methodFamily
+            ? `no reverse-request handler is registered for ${methodFamily}`
+            : "reverse request has no valid method",
+          sock,
+          generation,
+        );
+        return;
+      }
+
+      let body: Uint8Array;
+      try {
+        body = await handler(frame.body, { corr: frame.header.corr, method });
+        if (!(body instanceof Uint8Array)) {
+          throw new TypeError("reverse-request handler must return a Uint8Array");
+        }
+      } catch (error) {
+        await this.sendReverseError(
+          frame,
+          handle,
+          "reverse_request_unhandled",
+          error instanceof Error ? error.message : String(error),
+          sock,
+          generation,
+        );
+        return;
+      }
+
+      await this.sendReverseReply(frame, handle, FrameType.Response, body, sock, generation);
+    };
+
+    void reply().catch((error) => {
+      if (this.sock === sock && this.generation === generation && !this.closeStarted) {
+        debug("failed to answer reverse request: %s", causeMessage(error));
+      }
+    });
+  }
+
+  private async sendReverseError(
+    request: Frame,
+    handle: RouteHandle,
+    code: string,
+    message: string,
+    sock: SubcSocket,
+    generation: number,
+  ): Promise<void> {
+    await this.sendReverseReply(request, handle, FrameType.Error, this.encode({ code, message }), sock, generation);
+  }
+
+  private async sendReverseReply(
+    request: Frame,
+    handle: RouteHandle,
+    type: FrameType.Response | FrameType.Error,
+    body: Uint8Array,
+    sock: SubcSocket,
+    generation: number,
+  ): Promise<void> {
+    if (
+      this.sock !== sock ||
+      this.generation !== generation ||
+      !this.isLiveHandle(handle) ||
+      this.closeStarted ||
+      this.closedErr
+    ) {
+      return;
+    }
+    const frame = buildFrame(
+      type,
+      buildFlags(false, Priority.Interactive, false),
+      handle.channel,
+      handle.epoch,
+      request.header.corr,
+      body,
+    );
+    await writeBorrowed(sock, encodeFrame(frame), Date.now() + DEFAULT_REQUEST_TIMEOUT_MS);
+  }
+
   private errorFromFrame(frame: Frame): SubcError {
     try {
       const parsed = JSON.parse(Buffer.from(frame.body).toString("utf8")) as {
@@ -1608,8 +1794,12 @@ export class SubcClient {
     return this.ingressEpochDropCount;
   }
 
-  private installRoute(channel: number, epoch: number): RouteHandle {
-    const handle = createRouteHandle(channel, epoch, this.connectionToken);
+  private installRoute(
+    channel: number,
+    epoch: number,
+    reverseRequests = new ReverseRequestRegistry(),
+  ): RouteHandle {
+    const handle = createRouteHandle(channel, epoch, this.connectionToken, reverseRequests);
     this.liveRoutes.set(channel, handle);
     return handle;
   }
@@ -1758,12 +1948,14 @@ export function isValidCapabilityIdentifier(identifier: string): boolean {
 function routeCacheKey(
   target: Extract<RouteTarget, { kind: ManagedRouteKind }>,
   identity: BindIdentity,
-  consumerIdentity?: ConsumerIdentity,
+  consumerIdentity: ConsumerIdentity | undefined,
+  consumerCapabilities: readonly string[],
 ): string {
   const consumerPart = consumerIdentity
     ? `${consumerIdentity.module_id}\0${consumerIdentity.launch_nonce}`
     : "";
-  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}\0${consumerPart}`;
+  const capabilitiesPart = [...consumerCapabilities].sort().join("\0");
+  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}\0${consumerPart}\0${capabilitiesPart}`;
 }
 
 function routeOpenConsumerIdentity(opts: RouteOpenOptions = {}): ConsumerIdentity | undefined {
@@ -1790,3 +1982,12 @@ function causeMessage(cause: unknown): string {
 function pendingKey(handle: RouteHandle | null, corr: bigint): string {
   return handle ? `${handle.channel}:${handle.epoch}:${corr}` : `0:0:${corr}`;
 }
+
+function reverseRequestMethod(body: Uint8Array): string | undefined {
+  try {
+    const parsed = JSON.parse(Buffer.from(body).toString("utf8")) as { method?: unknown };
+    return typeof parsed.method === "string" && parsed.method.length > 0 ? parsed.method : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/envelope.ts

@@ -51,7 +51,8 @@ const FLAG_LAST = 0b0000_1000;
 const FLAG_ADMISSION_MASK = 0b0011_0000;
 const FLAG_ADMISSION_SHIFT = 4;
 export const DAEMON_ORIGIN_FLAG = 0x40;
-const FLAG_RESERVED_MASK = 0b1000_0000;
+export const SUBSCRIPTION_FLAG = 0x80;
+const FLAG_RESERVED_MASK = 0;
 
 /** Build flags from typed components. Admission defaults to NORMAL. */
 export function buildFlags(

package/src/index.ts

@@ -35,7 +35,14 @@ export {
   type RoutePollKind,
   type RoutePollResult,
 } from "./client.js";
-export { RouteHandle, StaleRouteHandleError } from "./route-handle.js";
+export {
+  ReverseRequestRegistry,
+  ReverseRequestRegistrationError,
+  RouteHandle,
+  StaleRouteHandleError,
+  type ReverseRequestContext,
+  type ReverseRequestHandler,
+} from "./route-handle.js";
 export {
   readConnectionFile,
   ConnectionFileError,
@@ -47,6 +54,7 @@ export {
   Priority,
   AdmissionClass,
   DAEMON_ORIGIN_FLAG,
+  SUBSCRIPTION_FLAG,
   PROTOCOL_VERSION,
   HEADER_LEN,
   buildFrame,

package/src/route-handle.ts

@@ -1,4 +1,61 @@
 const connectionToken = new WeakMap<RouteHandle, object>();
+const reverseRequests = new WeakMap<RouteHandle, ReverseRequestRegistry>();
+
+export interface ReverseRequestContext {
+  readonly corr: bigint;
+  readonly method: string;
+}
+
+export type ReverseRequestHandler = (
+  body: Uint8Array,
+  ctx: ReverseRequestContext,
+) => Promise<Uint8Array> | Uint8Array;
+
+/** A reverse-request registration cannot add a capability after route.open declared its set. */
+export class ReverseRequestRegistrationError extends Error {
+  readonly code = "reverse_request_capability_not_declared";
+
+  constructor(readonly methodFamily: string) {
+    super(`reverse-request capability ${JSON.stringify(methodFamily)} was not registered before route.open`);
+    this.name = "ReverseRequestRegistrationError";
+  }
+}
+
+/**
+ * Mutable handler registry prepared before route.open. The client derives
+ * consumer_capabilities from its method families and seals that set when the
+ * route opens; handlers for declared families may still be replaced afterward.
+ */
+export class ReverseRequestRegistry {
+  private readonly handlers = new Map<string, ReverseRequestHandler>();
+  private declaredFamilies: ReadonlySet<string> | null = null;
+
+  onRequest(methodFamily: string, handler: ReverseRequestHandler): void {
+    if (!isMethodFamily(methodFamily)) {
+      throw new TypeError(`reverse-request method family must be a capability identifier, got ${JSON.stringify(methodFamily)}`);
+    }
+    if (typeof handler !== "function") throw new TypeError("reverse-request handler must be a function");
+    if (this.declaredFamilies && !this.declaredFamilies.has(methodFamily)) {
+      throw new ReverseRequestRegistrationError(methodFamily);
+    }
+    this.handlers.set(methodFamily, handler);
+  }
+
+  /** @internal */
+  capabilities(): string[] {
+    return [...this.handlers.keys()].sort();
+  }
+
+  /** @internal */
+  handler(methodFamily: string): ReverseRequestHandler | undefined {
+    return this.handlers.get(methodFamily);
+  }
+
+  /** @internal */
+  seal(): void {
+    this.declaredFamilies ??= new Set(this.handlers.keys());
+  }
+}
 
 /**
  * Immutable identity for one route binding on one live socket. Only channel and
@@ -8,7 +65,7 @@ export class RouteHandle {
   readonly channel: number;
   readonly epoch: number;
 
-  private constructor(channel: number, epoch: number, token: object) {
+  private constructor(channel: number, epoch: number, token: object, registry: ReverseRequestRegistry) {
     if (!Number.isInteger(channel) || channel <= 0 || channel > 0xffff) {
       throw new RangeError(`route channel must be an integer in 1..65535, got ${channel}`);
     }
@@ -17,21 +74,47 @@ export class RouteHandle {
     }
     this.channel = channel;
     this.epoch = epoch;
+    registry.seal();
     connectionToken.set(this, token);
+    reverseRequests.set(this, registry);
     Object.freeze(this);
   }
 
-  private static create(channel: number, epoch: number, token: object): RouteHandle {
-    return new RouteHandle(channel, epoch, token);
+  /** Replace the handler for a capability declared when this route opened. */
+  onRequest(methodFamily: string, handler: ReverseRequestHandler): void {
+    reverseRequests.get(this)!.onRequest(methodFamily, handler);
+  }
+
+  private static create(
+    channel: number,
+    epoch: number,
+    token: object,
+    registry: ReverseRequestRegistry,
+  ): RouteHandle {
+    return new RouteHandle(channel, epoch, token, registry);
   }
 }
 
 /** @internal SDK factory; not re-exported from the package surface. */
-export function createRouteHandle(channel: number, epoch: number, token: object): RouteHandle {
+export function createRouteHandle(
+  channel: number,
+  epoch: number,
+  token: object,
+  registry = new ReverseRequestRegistry(),
+): RouteHandle {
   const factory = RouteHandle as unknown as {
-    create(channel: number, epoch: number, token: object): RouteHandle;
+    create(channel: number, epoch: number, token: object, registry: ReverseRequestRegistry): RouteHandle;
   };
-  return factory.create(channel, epoch, token);
+  return factory.create(channel, epoch, token, registry);
+}
+
+/** @internal */
+export function reverseRequestHandler(handle: RouteHandle, methodFamily: string): ReverseRequestHandler | undefined {
+  return reverseRequests.get(handle)?.handler(methodFamily);
+}
+
+function isMethodFamily(value: string): boolean {
+  return /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value);
 }
 
 /** A route handle belongs to another connection or is no longer installed. */