@c9up/ream 0.2.28 → 0.2.30

package/src/rpc/RpcRouter.ts

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   rpc.method('task.validate', handler).guard('jwt').role('cs_member')
- *   rpc.namespace('task', TaskController)  // every public method, DI-resolved per call
+ *   rpc.namespace('task', TaskController, ['show', 'update'])  // listed methods, DI-resolved per call
  *   rpc.group({ guard: 'jwt' }, (r) => { r.method('user.find', handler) })
  *
  * @implements MISS-27
@@ -15,11 +15,14 @@ import {
   buildSuccess,
   isNotification,
   isRpcShapedError,
+  type JsonRpcId,
   parseRequest as parseRpcRequest,
   buildError as rpcError,
 } from '@c9up/comet'
 import { currentNodeEnv } from '../env/nodeEnv.js'
+import { isReamError, ReamError } from '../errors/ReamError.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import { holdsPermissions } from '../http/permissions.js'
 import type { MiddlewareRegistry, RuntimeValidator } from '../middleware/Pipeline.js'
 import { composeMiddleware, runValidator } from '../middleware/Pipeline.js'
 
@@ -79,17 +82,58 @@ export class RpcMethodBuilder {
 }
 
 /**
- * Unwrap the `{ _body: [...] }` envelope `request.body()` puts around a
- * top-level JSON array (it only treats plain objects as the body verbatim). A
- * JSON-RPC batch arrives this way; a single request is a plain object and is
- * returned unchanged.
+ * A -32603 whose detail reaches the caller only outside production: an
+ * internal failure's message is where hosts, credentials and queries end up.
  */
-function unwrapBatchBody(value: unknown): unknown {
-  if (typeof value === 'object' && value !== null && '_body' in value) {
-    const inner = value._body
-    if (Array.isArray(inner)) return inner
+function internalError(detail: string, id: JsonRpcId) {
+  return rpcError(-32603, currentNodeEnv() !== 'production' ? detail : 'Internal error', id)
+}
+
+/** The public method names of a controller instance type. */
+export type ControllerMethodName<T> = {
+  [K in keyof T]: T[K] extends (...args: never[]) => unknown ? K : never
+}[keyof T] &
+  string
+
+/**
+ * Whether `name` is a plain method of the controller's own class chain.
+ * The walk stops before `Object.prototype` and reads descriptors, so
+ * neither `toString` nor a getter (whose read would run code) qualifies.
+ */
+function isControllerMethod(proto: unknown, name: unknown): boolean {
+  if (typeof name !== 'string' || name === '' || name === 'constructor') return false
+  let current: unknown = proto
+  while (typeof current === 'object' && current !== null && current !== Object.prototype) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, name)
+    if (descriptor) return typeof descriptor.value === 'function'
+    current = Object.getPrototypeOf(current)
   }
-  return value
+  return false
+}
+
+/**
+ * The JSON media types JSON-RPC over HTTP is sent with. None of them is a
+ * CORS-safelisted request type, so a foreign page cannot send one without a
+ * preflight.
+ */
+const DEFAULT_CONTENT_TYPES = [
+  'application/json',
+  'application/json-rpc',
+  'application/jsonrequest',
+]
+
+/** `Application/JSON; charset=utf-8` → `application/json`. */
+function mediaType(contentType: string | undefined): string {
+  return (contentType?.split(';')[0] ?? '').trim().toLowerCase()
+}
+
+export interface RpcRouterOptions {
+  /**
+   * Media types `handle()` accepts a request body under; anything else is
+   * answered 415 before the body is read. Default: `application/json`,
+   * `application/json-rpc`, `application/jsonrequest`.
+   */
+  contentTypes?: readonly string[]
 }
 
 /**
@@ -97,10 +141,10 @@ function unwrapBatchBody(value: unknown): unknown {
  * Returns the JSON-RPC error code+message to reject with, or undefined when the
  * caller is authorized.
  */
-function checkRpcAuthorization(
+async function checkRpcAuthorization(
   ctx: HttpContext,
   def: RpcMethodDefinition,
-): { code: number; message: string } | undefined {
+): Promise<{ code: number; message: string } | undefined> {
   const needsAuth = def.guards.length > 0 || def.roles.length > 0 || def.permissions.length > 0
   if (needsAuth && !ctx.auth?.isAuthenticated) {
     return { code: -32003, message: 'Unauthorized' }
@@ -113,9 +157,9 @@ function checkRpcAuthorization(
       return { code: -32003, message: 'Insufficient role' }
     }
   }
+  // A token-authenticated call also needs the token to allow each permission.
   if (def.permissions.length > 0) {
-    const userPerms = ctx.auth?.permissions ?? ctx.auth?.user?.permissions ?? []
-    if (!def.permissions.every((p: string) => userPerms.includes(p))) {
+    if (!(await holdsPermissions(ctx.auth, def.permissions))) {
       return { code: -32003, message: 'Insufficient permissions' }
     }
   }
@@ -126,6 +170,13 @@ export class RpcRouter {
   #methods: Map<string, RpcMethodDefinition> = new Map()
   #groupConfig: { guards: string[]; roles: string[]; middleware: string[] } | null = null
   #container?: RpcContainer
+  readonly #contentTypes: ReadonlySet<string>
+
+  constructor(options: RpcRouterOptions = {}) {
+    this.#contentTypes = new Set(
+      (options.contentTypes ?? DEFAULT_CONTENT_TYPES).map((type) => mediaType(type)),
+    )
+  }
 
   /**
    * Set the IoC container used to resolve `namespace()` controllers — mirrors
@@ -137,8 +188,23 @@ export class RpcRouter {
     this.#container = container
   }
 
-  /** Register an RPC method. */
+  /**
+   * Register an RPC method. JSON-RPC 2.0 §4 reserves names starting with
+   * `rpc.` for the protocol itself, so they are refused here, as an empty
+   * name is.
+   */
   method(name: string, handler: RpcHandler): RpcMethodBuilder {
+    if (typeof name !== 'string' || name === '') {
+      throw new ReamError(
+        'E_RPC_INVALID_METHOD_NAME',
+        'An RPC method name must be a non-empty string',
+      )
+    }
+    if (name.startsWith('rpc.')) {
+      throw new ReamError('E_RPC_RESERVED_METHOD_NAME', `'${name}' is a reserved RPC method name`, {
+        hint: 'JSON-RPC 2.0 reserves names starting with "rpc." for rpc-internal methods; pick another prefix.',
+      })
+    }
     const def: RpcMethodDefinition = {
       name,
       handler,
@@ -152,24 +218,28 @@ export class RpcRouter {
   }
 
   /**
-   * Register methods from a controller — auto-registers all public methods.
+   * Register the listed methods of a controller as `<prefix>.<method>`.
    *
-   * The parameter used to demand
-   * `new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>`,
-   * which NO real controller satisfies: a class with any non-method property
-   * fails the `Record`, and a method declared `bump(): number` fails the
-   * `unknown[]` parameters, which are compared contravariantly. So the
-   * documented call — `rpc.namespace('task', TaskController)` — did not
-   * typecheck, and nothing noticed because the tests were outside `tsc`.
-   *
-   * Any class, then. The body already checks that what it found is callable
-   * and names the method when it is not.
+   * The list is explicit, like a route binding one `[Controller, 'method']`
+   * pair: TypeScript `private`/`protected` vanish at runtime, so a namespace
+   * that published "every method on the prototype" made helpers the author
+   * never meant to expose remotely callable. The type admits only public
+   * method names; the runtime check refuses a name with no plain method
+   * behind it (a getter, `constructor`, anything from `Object.prototype`).
    */
-  namespace(prefix: string, controller: abstract new (...args: never[]) => object): void {
-    const proto = controller.prototype
-    const methods = Object.getOwnPropertyNames(proto).filter(
-      (m) => m !== 'constructor' && typeof proto[m] === 'function',
-    )
+  namespace<T extends object>(
+    prefix: string,
+    controller: abstract new (...args: never[]) => T,
+    methods: ReadonlyArray<ControllerMethodName<T>>,
+  ): void {
+    for (const methodName of methods) {
+      if (!isControllerMethod(controller.prototype, methodName)) {
+        throw new ReamError(
+          'E_RPC_UNKNOWN_CONTROLLER_METHOD',
+          `${controller.name} has no method '${String(methodName)}' to expose as an RPC method`,
+        )
+      }
+    }
     for (const methodName of methods) {
       this.method(`${prefix}.${methodName}`, async (ctx, params) => {
         // Resolve through the container on every call (fresh DI per request,
@@ -212,10 +282,26 @@ export class RpcRouter {
 
   /** Handle an incoming JSON-RPC request. */
   async handle(ctx: HttpContext): Promise<void> {
-    // `request.body()` wraps a top-level JSON array — a JSON-RPC batch — as its
-    // non-object envelope `{ _body: [...] }`. Unwrap it so batch detection works;
-    // a single request is a plain object and passes through untouched.
-    const body = unwrapBatchBody(ctx.request.body())
+    // A form post, a text/plain body or one with no Content-Type is a CORS
+    // simple request: a foreign page sends it with the victim's cookies and
+    // no preflight. Refused before the body is read, as JSON-RPC servers
+    // answer 415 to anything but JSON.
+    if (!this.#contentTypes.has(mediaType(ctx.request.header('content-type')))) {
+      ctx.response.status(415).send('')
+      return
+    }
+
+    // Parsed here, not through `request.body()`, which turns malformed JSON
+    // into `{}` — and §5.1 answers invalid JSON with -32700, not -32600.
+    // `raw()` stays outside the try: its 413 is not a parse error.
+    const raw = ctx.request.raw()
+    let body: unknown
+    try {
+      body = JSON.parse(raw)
+    } catch {
+      ctx.response.status(200).json(rpcError(-32700, 'Parse error', null))
+      return
+    }
 
     // Batch support (max 50 to prevent DoS)
     if (Array.isArray(body)) {
@@ -295,7 +381,7 @@ export class RpcRouter {
     if (!def) return rpcError(-32601, 'Method not found', id)
 
     try {
-      const denied = checkRpcAuthorization(ctx, def)
+      const denied = await checkRpcAuthorization(ctx, def)
       if (denied) return rpcError(denied.code, denied.message, id)
 
       // Run declared named middleware (e.g. guards) — they throw to deny, mapped
@@ -310,8 +396,7 @@ export class RpcRouter {
       if (def.validator) {
         const token = `validator:${def.validator}`
         if (!this.#container?.has(token)) {
-          return rpcError(
-            -32603,
+          return internalError(
             `Validator '${def.validator}' is not registered (bind container.singleton('${token}', () => schema)).`,
             id,
           )
@@ -324,9 +409,11 @@ export class RpcRouter {
         try {
           outcome = await runValidator(validator, params)
         } catch (err) {
-          return rpcError(
-            -32603,
-            err instanceof TypeError
+          // Caught here rather than below so a validator's error is never
+          // honoured as a domain error: a rule hitting the database throws
+          // whatever the driver throws.
+          return internalError(
+            isReamError(err, 'E_VALIDATOR_UNUSABLE')
               ? `Validator '${def.validator}' exposes no usable validate method.`
               : `Validator '${def.validator}' failed: ${err instanceof Error ? err.message : String(err)}`,
             id,
@@ -346,10 +433,7 @@ export class RpcRouter {
         const message = typeof err.message === 'string' ? err.message : 'RPC error'
         return rpcError(err.code, message, id, err.data)
       }
-      // Otherwise don't leak internal error details to the caller.
-      const isDev = currentNodeEnv() !== 'production'
-      const message = isDev && err instanceof Error ? err.message : 'Internal error'
-      return rpcError(-32603, message, id)
+      return internalError(err instanceof Error ? err.message : 'Internal error', id)
     }
   }
 

package/src/scheduler/Scheduler.ts

@@ -144,7 +144,7 @@ function loadNative(): NativeModule {
  * so scheduler context is never lost.
  */
 function translateNativeError(e: unknown): ReamError {
-  const asError = e as Error
+  const asError = e instanceof Error ? e : new Error(String(e))
   const parsed = ReamError.fromNapi(asError)
   // `fromNapi` returns an `E_UNKNOWN`-coded error when the message is not
   // a JSON payload. Preserve that context under a scheduler-specific

package/src/scheduler/locks/RedisLockBackend.ts

@@ -67,12 +67,20 @@ export class RedisLockBackend implements LockBackend {
     this.#prefix = options.prefix ?? 'ream:schedule:lock:'
   }
 
-  /** The client, resolved once and kept. */
+  /**
+   * The client, resolved once and kept. Only a success is kept: a lookup
+   * that fails (the connection is not registered yet at boot, Redis is
+   * briefly down) is forgotten so the next task retries it, instead of
+   * every lock failing with the same error until the process restarts.
+   */
   #client(): Promise<LockRedisClient> {
     if (!this.#resolved) {
-      this.#resolved = Promise.resolve(
-        typeof this.#source === 'function' ? this.#source() : this.#source,
-      )
+      const source = this.#source
+      const pending = (async () => (typeof source === 'function' ? source() : source))()
+      this.#resolved = pending
+      pending.catch(() => {
+        if (this.#resolved === pending) this.#resolved = undefined
+      })
     }
     return this.#resolved
   }

package/src/security/CookieSigner.ts

@@ -23,6 +23,11 @@
 import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto'
 import { hmacSign, hmacVerify } from './crypto.js'
 
+/** The 96-bit nonce GCM is specified for. */
+const GCM_IV_BYTES = 12
+/** The full 128-bit authentication tag — never a truncated one. */
+const GCM_TAG_BYTES = 16
+
 /** Raised when no APP_KEY is configured (AdonisJS `E_MISSING_APP_KEY`). */
 export class E_MISSING_APP_KEY extends Error {
   readonly code = 'E_MISSING_APP_KEY' as const
@@ -120,14 +125,22 @@ export class CookieSigner {
       return null
     }
     if (typeof parsed !== 'object' || parsed === null) return null
-    const envelope = parsed as Envelope
     // The KEY must be there, whatever it holds — that is what distinguishes an
     // envelope from an arbitrary JSON document, and a signed `null` or `0` is a
     // legitimate payload.
-    if (!('m' in envelope)) return null
-    if (envelope.e !== undefined && envelope.e < Date.now()) return null
-    if ((envelope.p ?? undefined) !== purpose) return null
-    return envelope.m
+    if (!('m' in parsed)) return null
+    // Each field checked for the type `#seal` writes before it is compared: an
+    // expiry that is not a number (`"e": "9999"`, `"e": null`) or a purpose
+    // that is not a string must not slip past the comparisons below.
+    const expiry: unknown = 'e' in parsed ? parsed.e : undefined
+    if (expiry !== undefined) {
+      if (typeof expiry !== 'number' || !Number.isFinite(expiry)) return null
+      if (expiry < Date.now()) return null
+    }
+    const sealedFor: unknown = 'p' in parsed ? parsed.p : undefined
+    if (sealedFor !== undefined && typeof sealedFor !== 'string') return null
+    if (sealedFor !== purpose) return null
+    return parsed.m
   }
 
   /**
@@ -217,8 +230,10 @@ export class CookieSigner {
   }
 
   encrypt(value: unknown, expiresIn?: number, purpose?: string): string {
-    const iv = randomBytes(12)
-    const cipher = createCipheriv('aes-256-gcm', this.#keyBuffer, iv)
+    const iv = randomBytes(GCM_IV_BYTES)
+    const cipher = createCipheriv('aes-256-gcm', this.#keyBuffer, iv, {
+      authTagLength: GCM_TAG_BYTES,
+    })
     const sealed = this.#seal(value, expiresIn, purpose)
     const encrypted = Buffer.concat([cipher.update(sealed, 'utf8'), cipher.final()])
     const tag = cipher.getAuthTag()
@@ -242,7 +257,14 @@ export class CookieSigner {
       const iv = Buffer.from(ivPart, 'base64url')
       const data = Buffer.from(dataPart, 'base64url')
       const tag = Buffer.from(tagPart, 'base64url')
-      const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv)
+      // GCM verifies only as many tag bytes as it is handed: a client that
+      // trims the tag to 4 bytes would cut forgery cost from 2^128 to 2^32
+      // guesses. Only what `encrypt` produces is accepted — a 12-byte IV and
+      // the full 16-byte tag — and the decipher is pinned to that length too.
+      if (iv.length !== GCM_IV_BYTES || tag.length !== GCM_TAG_BYTES) return null
+      const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv, {
+        authTagLength: GCM_TAG_BYTES,
+      })
       decipher.setAuthTag(tag)
       const raw = Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8')
       return this.#open(raw, purpose) as T | null

package/src/security/SignedUrl.ts

@@ -3,6 +3,7 @@
  * Uses Rust NAPI via crypto facade when available.
  */
 
+import { durationToSeconds } from '../helpers/duration.js'
 import { constantTimeEq, hmacSign } from './crypto.js'
 
 export interface SignedUrlConfig {
@@ -43,7 +44,12 @@ export class SignedUrl {
     if (!providedSig) return false
     const expires = url.searchParams.get('expires')
     if (expires && Math.floor(Date.now() / 1000) > parseInt(expires, 10)) return false
-    if (purpose && url.searchParams.get('purpose') !== purpose) return false
+    // Exact match both ways: a URL minted for `password-reset` must not pass a
+    // check that names no purpose (or another one), and a purpose-less URL
+    // must not pass a check that names one. An empty purpose is no purpose,
+    // as in `make`.
+    const signedPurpose = url.searchParams.get('purpose') || undefined
+    if (signedPurpose !== (purpose || undefined)) return false
 
     url.searchParams.delete('signature')
     const expectedSig = hmacSign(url.pathname + url.search, this.#secret)
@@ -51,22 +57,17 @@ export class SignedUrl {
   }
 }
 
+/**
+ * The lifetime of a signed URL in seconds. Read with the duration grammar
+ * used everywhere else (`'30 minutes'`, `'1 week'`, `'2h'`), and refused when
+ * it cannot be read: signing with a default instead turned "one week" into
+ * one hour without a word.
+ */
 function parseExpiry(value: string | number): number {
-  if (typeof value === 'number') return value
-  const match = value.match(/^(\d+)(s|m|h|d)$/)
-  if (!match) return 3600
-  const [, digits, unit] = match
-  const num = parseInt(digits ?? '0', 10)
-  switch (unit) {
-    case 's':
-      return num
-    case 'm':
-      return num * 60
-    case 'h':
-      return num * 3600
-    case 'd':
-      return num * 86400
-    default:
-      return 3600
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new Error(
+      `Cannot read ${value} as a signed URL expiry: it must be a finite number of seconds.`,
+    )
   }
+  return durationToSeconds(value, 'a signed URL expiry')
 }

package/src/server/Server.ts

@@ -37,12 +37,23 @@ export type MiddlewareEntry = LazyImport<MiddlewareClassConstructor> | Middlewar
 export interface GrpcCall {
   /** `/package.Service/Method`, as it arrived. */
   path: string
-  /** Request metadata, header names lowercased. */
-  metadata: Record<string, string>
+  /**
+   * Request metadata: the request headers, every value of a repeated one in
+   * order, names lowercased. Never the client's trailers. A `-bin` value is
+   * the base64 text that arrived: this is the HTTP/2 header layer, and the
+   * gRPC package that registers the handler decodes it, as a gRPC library's
+   * metadata class does over Node's HTTP/2 headers.
+   */
+  metadata: Record<string, string[]>
   /** The request message, still encoded. */
   message: Uint8Array
   /** Resolved client IP, by the same trusted-proxy rules as `request.ip()`. */
   ip: string
+  /**
+   * Aborted when the client gives up on the call — resets its stream or
+   * closes the connection — before the handler answered.
+   */
+  signal: AbortSignal
 }
 
 /** A reply message, still encoded — or a gRPC status code instead of one. */
@@ -50,6 +61,26 @@ export type GrpcReply = { message: Uint8Array } | { code: number; details: strin
 
 export type GrpcHandler = (call: GrpcCall) => Promise<GrpcReply>
 
+/**
+ * Message size bounds of the gRPC calls, in bytes; `-1` for none. A request
+ * past its bound is refused, `RESOURCE_EXHAUSTED`, before it is read; a reply
+ * past its bound is answered `RESOURCE_EXHAUSTED` instead.
+ */
+export interface GrpcLimits {
+  /** Default 4 MiB. */
+  maxReceiveMessageLength?: number
+  /** Default `-1`: no bound. */
+  maxSendMessageLength?: number
+}
+
+function checkGrpcLimit(name: string, value: number | undefined): void {
+  if (value === undefined || value === -1 || (Number.isSafeInteger(value) && value >= 0)) return
+  throw new ReamError(
+    'E_SERVER_GRPC_INVALID_LIMIT',
+    `${name} must be a whole number of bytes, or -1 for no limit — got ${value}.`,
+  )
+}
+
 export class Server {
   #router: Router
   #serverMiddleware: MiddlewareFunction[] = []
@@ -57,22 +88,31 @@ export class Server {
   #resolvedErrorHandler?: ExceptionHandler
   #trustedProxies: string[] = []
   #grpcHandler?: GrpcHandler
+  #grpcLimits: GrpcLimits = {}
 
   constructor(router: Router) {
     this.#router = router
   }
 
   /**
-   * Configure the trusted-proxy CIDR list. The Rust HyperServer uses it to
-   * pre-resolve `request.ip` once per request — JS reads the field, no CIDR
-   * matching in TS.
+   * Configure the trusted proxies. The Rust HyperServer uses them to
+   * pre-resolve `request.ip()` / `request.ips()` once per request — JS reads
+   * the fields, no CIDR matching in TS.
+   *
+   * The chain is the socket peer, then the `X-Forwarded-For` entries read
+   * right to left; it stops at the first hop that is not a trusted proxy, and
+   * its last entry is the client IP. Proxies append what they saw, so the
+   * left-most entry — the one a client writes itself — is only reached when
+   * every hop after it is trusted. `X-Real-IP` is never read.
    *
-   * Empty list (default, 2026-05+) is **strict fail-closed**: `X-Forwarded-For`
-   * and `X-Real-IP` are ignored entirely; only the socket peer is used.
-   * Apps deployed behind a reverse proxy must list the proxy's CIDR
-   * (`'10.0.0.0/8'`, `'192.0.2.0/24'`, etc.) or pass the `'*'` sentinel
-   * for permissive mode (accepts spoofing as the explicit trade-off when
-   * proxy CIDRs can't be enumerated).
+   * Entries: addresses or CIDR ranges, IPv4 or IPv6 (`'10.0.0.0/8'`,
+   * `'fd00::/8'`), IPv4 netmasks (`'10.0.0.0/255.0.0.0'`), the named ranges
+   * `'loopback'`, `'linklocal'`, `'uniquelocal'`, or `'*'` to trust every hop
+   * (the left-most entry wins — any client can choose its IP). An entry that is
+   * none of these makes the server refuse to start.
+   *
+   * Empty list (default) is **strict fail-closed**: `X-Forwarded-For` is
+   * ignored and only the socket peer is used.
    */
   trustedProxies(cidrs: string[]): this {
     this.#trustedProxies = [...cidrs]
@@ -99,16 +139,24 @@ export class Server {
    * One handler per server: a second one throws. Two packages both serving
    * gRPC is a conflict to resolve, not to settle by load order.
    */
-  grpc(handler: GrpcHandler): this {
+  grpc(handler: GrpcHandler, limits: GrpcLimits = {}): this {
     if (this.#grpcHandler) {
       throw new ReamError('E_SERVER_GRPC_ALREADY_SET', 'A gRPC handler is already registered.', {
         hint: 'Only one package can serve gRPC on the HTTP port.',
       })
     }
+    checkGrpcLimit('maxReceiveMessageLength', limits.maxReceiveMessageLength)
+    checkGrpcLimit('maxSendMessageLength', limits.maxSendMessageLength)
     this.#grpcHandler = handler
+    this.#grpcLimits = { ...limits }
     return this
   }
 
+  /** The message bounds given with the gRPC handler (consumed by Ignitor at boot). */
+  getGrpcLimits(): GrpcLimits {
+    return { ...this.#grpcLimits }
+  }
+
   /** The gRPC handler, if one is set (consumed by Ignitor at boot). */
   getGrpcHandler(): GrpcHandler | undefined {
     return this.#grpcHandler

package/src/server/nativeGrpc.ts

@@ -0,0 +1,59 @@
+/**
+ * The gRPC handler as the native server calls it.
+ *
+ * The native server numbers each call and, separately, reports the numbers
+ * of the calls a client gave up on — a reset stream or a closed connection —
+ * before the handler answered. This turns those reports into the `signal` of
+ * each {@link GrpcCall}, so that a handler can stop the work it started.
+ *
+ * Calls reach JavaScript in increasing id order, but a cancel travels on its
+ * own queue and can arrive before its call: one for an id not seen yet is
+ * kept until that call arrives; one for an id already seen and finished is
+ * dropped.
+ */
+
+import type { GrpcCall, GrpcHandler, GrpcReply } from './Server.js'
+
+/** A call as the native server hands it over: numbered, without a signal. */
+export interface NativeGrpcCall extends Omit<GrpcCall, 'signal'> {
+  id: number
+}
+
+export type NativeGrpcHandler = (call: NativeGrpcCall) => Promise<GrpcReply>
+
+export interface CancellableGrpc {
+  /** Give to the native server's `onGrpc`. */
+  onCall: NativeGrpcHandler
+  /** Give to the native server's `onGrpcCancel`. */
+  onCancel: (id: number) => void
+}
+
+export function cancellableGrpc(handler: GrpcHandler): CancellableGrpc {
+  const running = new Map<number, AbortController>()
+  // Cancels that arrived before their call.
+  const early = new Set<number>()
+  let lastSeen = 0
+
+  return {
+    async onCall({ id, ...call }) {
+      lastSeen = Math.max(lastSeen, id)
+      const controller = new AbortController()
+      for (const cancelled of early) {
+        if (cancelled > id) continue
+        early.delete(cancelled)
+        if (cancelled === id) controller.abort()
+      }
+      running.set(id, controller)
+      try {
+        return await handler({ ...call, signal: controller.signal })
+      } finally {
+        running.delete(id)
+      }
+    },
+    onCancel(id) {
+      const controller = running.get(id)
+      if (controller !== undefined) controller.abort()
+      else if (id > lastSeen) early.add(id)
+    },
+  }
+}