@cortexkit/common-auth 0.7.0 → 0.9.0

package/dist/logger/engine.d.ts

@@ -1,7 +1,9 @@
 import type { CaptureSink } from './capture-sink.js';
 import { type RedactionOptions } from './redact.js';
 export type Level = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/** A logger that writes to a file, and to a capture sink when one is given. */
 export interface InitLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed, alongside the file. */
     captureSink?: CaptureSink;
     /**
      * Path of the file lines are appended to, or a function returning it.
@@ -15,6 +17,25 @@ export interface InitLoggerOptions extends RedactionOptions {
     /** Level floor applied when no `setLogLevel` call has overridden it. */
     level?: Level | (() => Level | undefined);
 }
+/**
+ * A logger with no file: the capture sink is its only destination. Nothing
+ * is written to disk or printed, for a host that forwards records to its own
+ * log.
+ */
+export interface SinkOnlyLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed. */
+    captureSink: CaptureSink;
+    file?: undefined;
+    /** Level floor applied when no `setLogLevel` call has overridden it. */
+    level?: Level | (() => Level | undefined);
+}
+/**
+ * What a logger is configured with: a file (`InitLoggerOptions`, the shape
+ * every release before this one accepted, kept as its own interface so a
+ * caller deriving a type from it with `Pick` or `extends` keeps compiling) or
+ * a capture sink alone.
+ */
+export type LoggerOptions = InitLoggerOptions | SinkOnlyLoggerOptions;
 export interface ChannelLogger {
     error(message: string, data?: unknown): void;
     warn(message: string, data?: unknown): void;
@@ -37,7 +58,7 @@ export interface LoggerInstance {
      * alone, because it is the operator's explicit choice and outranks the
      * floor a host computed at start-up.
      */
-    configure(options: InitLoggerOptions): void;
+    configure(options: LoggerOptions): void;
     /** Operator override of the level floor; undefined removes it. */
     setLogLevel(level: Level | undefined): void;
     /**
@@ -53,14 +74,14 @@ export interface LoggerInstance {
  * uses this instead of `initLogger`, so neither replaces the other's file,
  * level, redaction or capture sink.
  */
-export declare function createLoggerInstance(options: InitLoggerOptions): LoggerInstance;
+export declare function createLoggerInstance(options: LoggerOptions): LoggerInstance;
 /**
  * Point the module's default logger at a host's file and level, and return
  * it. Idempotent: calling it again replaces both. A runtime level installed
  * by `setLogLevel` is deliberately left alone, because it is the operator's
  * explicit choice and outranks the floor a host computed at start-up.
  */
-export declare function initLogger(options: InitLoggerOptions): LoggerInstance;
+export declare function initLogger(options: LoggerOptions): LoggerInstance;
 export declare function setLogLevel(l: Level | undefined): void;
 /**
  * Write whatever the default logger has buffered. Safe to call synchronously

package/dist/logger/engine.js

@@ -126,7 +126,8 @@ function createEngine(options) {
             }, 500);
     }
     function emit(channel, level, message, data) {
-        if (logFileSource === undefined)
+        // Unconfigured (neither a file nor a sink) stays a silent no-op.
+        if (logFileSource === undefined && captureSink === undefined)
             return;
         try {
             if (ORDER[level] > ORDER[configuredLevel()])
@@ -152,6 +153,9 @@ function createEngine(options) {
                 });
             }
             catch { }
+            // A sink-only logger has no file to buffer lines for.
+            if (logFileSource === undefined)
+                return;
             buffer.push(line);
             if (buffer.length >= 50)
                 flushLogs();

package/dist/logger/index.d.ts

@@ -1,6 +1,6 @@
 export type { CaptureSink, LogTestRecord } from './capture-sink.js';
 export { createCaptureSink } from './capture-sink.js';
-export type { ChannelLogger, InitLoggerOptions, Level, LoggerInstance, } from './engine.js';
+export type { ChannelLogger, InitLoggerOptions, Level, LoggerInstance, LoggerOptions, SinkOnlyLoggerOptions, } from './engine.js';
 export { createLogger, createLoggerInstance, flushForTest, flushLogs, initLogger, resetLoggerForTest, setLogLevel, } from './engine.js';
 export type { RedactionOptions, Redactor } from './redact.js';
 export { createRedactor, redact, redactStrings } from './redact.js';

package/dist/logger/redact.js

@@ -1,6 +1,18 @@
 const SECRET_KEY_EXACT = /^(authorization|x-api-key|cookie|set-cookie|refresh|access|token)$/i;
 const TOKEN_VALUE = /\b(Bearer\s+[\w.-]+|sk-[\w-]+|eyJ[\w.-]+)\b|ckh_[A-Za-z0-9_-]{20,}/g;
 const MASK = '***REDACTED***';
+// How many errors deep a cause chain is followed. A chain this long is
+// already unreadable in a log line, and an unbounded one (each cause a fresh
+// object, so the cycle check never trips) must not grow the line forever.
+const MAX_ERROR_DEPTH = 8;
+// Error's own fields are non-enumerable, so a plain entry walk renders an
+// Error as `{}` and the name, message and stack a plugin logged are lost.
+// The tag check also recognises an Error from another realm (a worker or a
+// vm context), whose prototype is not this realm's Error.
+function isError(value) {
+    return (value instanceof Error ||
+        Object.prototype.toString.call(value) === '[object Error]');
+}
 export function createRedactor(options = {}) {
     const patterns = [TOKEN_VALUE, ...(options.extraValuePatterns ?? [])].map((pattern) => new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`));
     function isSecretKey(key) {
@@ -12,7 +24,27 @@ export function createRedactor(options = {}) {
             (normalized.endsWith('token') && !normalized.endsWith('tokens')) ||
             !!options.extraSecretKeys?.(normalized));
     }
-    function walk(value, keys, seen) {
+    // The fields every log reader wants first, then whatever else the error
+    // carries as its own enumerable properties (which is all an Error rendered
+    // as before). Every entry goes through the same key and string scrubbing as
+    // any other object, so a token in a message or stack is still masked.
+    function errorEntries(error) {
+        const fields = error;
+        const entries = [
+            ['name', error.name],
+            ['message', error.message],
+            ['stack', error.stack],
+        ];
+        for (const key of ['code', 'status', 'cause'])
+            if (fields[key] !== undefined)
+                entries.push([key, fields[key]]);
+        const listed = new Set(entries.map(([key]) => key));
+        for (const entry of Object.entries(error))
+            if (!listed.has(entry[0]))
+                entries.push(entry);
+        return entries;
+    }
+    function walk(value, keys, seen, errorDepth = 0) {
         if (typeof value === 'string') {
             return patterns.reduce((text, pattern) => text.replace(pattern, MASK), value);
         }
@@ -23,11 +55,17 @@ export function createRedactor(options = {}) {
         seen.add(value);
         try {
             if (Array.isArray(value))
-                return value.map((item) => walk(item, keys, seen));
+                return value.map((item) => walk(item, keys, seen, errorDepth));
+            const error = isError(value);
+            if (error && errorDepth >= MAX_ERROR_DEPTH)
+                return '[Truncated]';
+            const childDepth = error ? errorDepth + 1 : errorDepth;
             // Define own properties so a diagnostic __proto__ key cannot change the output prototype.
-            return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            return Object.fromEntries((error ? errorEntries(value) : Object.entries(value)).map(([key, item]) => [
                 key,
-                keys && isSecretKey(key) ? MASK : walk(item, keys, seen),
+                keys && isSecretKey(key)
+                    ? MASK
+                    : walk(item, keys, seen, childDepth),
             ]));
         }
         finally {

package/dist/rpc/notifications.d.ts

@@ -35,6 +35,24 @@ export interface NotificationScope {
      * session, which plugins that drain from one process-wide TUI rely on.
      */
     requireSession?: boolean;
+    /**
+     * What a drain with no session id returns, and what it acknowledges.
+     *
+     * - `'all'` (default): every queued notification, broadcasts and every
+     *   session's targeted ones; a sessionless acknowledgement removes
+     *   nothing. A plugin that drains from one process-wide TUI relies on this.
+     * - `'broadcast-only'`: broadcasts only (notifications pushed without a
+     *   session), never a session's targeted ones, for a TUI that polls before
+     *   it knows its session. A sessionless acknowledgement removes the
+     *   acknowledged broadcasts and leaves every targeted notification queued.
+     *   It also answers `isTuiConnected(scope, undefined)`: true while any
+     *   drain on the queue, with or without a session, happened within the
+     *   connection window.
+     *
+     * The option governs each call made with this scope; it does not split the
+     * queue, so a push through a scope without it lands in the same queue.
+     */
+    sessionlessDrain?: 'all' | 'broadcast-only';
 }
 /** A strict notification scope was used without a session id. */
 export declare class RpcSessionRequiredError extends Error {
@@ -45,5 +63,11 @@ export declare class RpcSessionRequiredError extends Error {
 export declare function isSessionId(value: unknown): value is string;
 export declare function pushNotification(scope: NotificationScope, payload: OpenDialogPayload, sessionId?: string): void;
 export declare function drainNotifications(scope: NotificationScope, lastReceivedId?: number, sessionId?: string): RpcNotification[];
-export declare function isTuiConnected(scope: NotificationScope, sessionId: string): boolean;
+/**
+ * True when a TUI drained within the last 3000 ms. With a session id, that
+ * session drained. Without one, a broadcast-only scope answers whether any
+ * drain happened; a default scope answers false, since it only tracks
+ * sessions.
+ */
+export declare function isTuiConnected(scope: NotificationScope, sessionId: string | undefined): boolean;
 export declare function resetNotificationsForTest(scope: NotificationScope): void;

package/dist/rpc/notifications.js

@@ -21,7 +21,12 @@ function state(scope) {
     ]);
     let value = queues.get(key);
     if (!value) {
-        value = { queue: [], nextId: 1, lastDrainAtBySession: new Map() };
+        value = {
+            queue: [],
+            nextId: 1,
+            lastDrainAtBySession: new Map(),
+            lastDrainAtAny: 0,
+        };
         queues.set(key, value);
     }
     return value;
@@ -49,25 +54,41 @@ export function drainNotifications(scope, lastReceivedId = 0, sessionId) {
         throw new RpcSessionRequiredError('drain');
     const value = state(scope);
     const now = Date.now();
+    value.lastDrainAtAny = now;
     if (sessionId !== undefined)
         value.lastDrainAtBySession.set(sessionId, now);
-    const matches = (n) => sessionId === undefined ||
-        n.sessionId === undefined ||
-        n.sessionId === sessionId;
+    const broadcastOnly = scope.sessionlessDrain === 'broadcast-only';
+    const matches = (n) => sessionId === undefined
+        ? !broadcastOnly || n.sessionId === undefined
+        : n.sessionId === undefined || n.sessionId === sessionId;
     if (lastReceivedId > 0) {
         value.queue = value.queue.filter((n) => {
             if (n.id > lastReceivedId)
                 return true;
+            // A sessionless ack in broadcast-only mode consumes the broadcasts it
+            // was shown; in the default mode it consumes nothing, since it was
+            // shown targeted notifications other sessions still have to receive.
             if (sessionId === undefined)
-                return true;
+                return !broadcastOnly || n.sessionId !== undefined;
             return n.sessionId !== sessionId;
         });
     }
     return value.queue.filter((n) => n.id > lastReceivedId && matches(n));
 }
+/**
+ * True when a TUI drained within the last 3000 ms. With a session id, that
+ * session drained. Without one, a broadcast-only scope answers whether any
+ * drain happened; a default scope answers false, since it only tracks
+ * sessions.
+ */
 export function isTuiConnected(scope, sessionId) {
     const now = Date.now();
-    const at = state(scope).lastDrainAtBySession.get(sessionId) ?? 0;
+    const value = state(scope);
+    const at = sessionId !== undefined
+        ? (value.lastDrainAtBySession.get(sessionId) ?? 0)
+        : scope.sessionlessDrain === 'broadcast-only'
+            ? value.lastDrainAtAny
+            : 0;
     return at > 0 && now - at < TUI_CONNECTED_WINDOW_MS;
 }
 export function resetNotificationsForTest(scope) {
@@ -75,4 +96,5 @@ export function resetNotificationsForTest(scope) {
     value.queue = [];
     value.nextId = 1;
     value.lastDrainAtBySession.clear();
+    value.lastDrainAtAny = 0;
 }

package/dist/rpc/port-file.d.ts

@@ -17,4 +17,13 @@ export declare function writePortFile(dir: string, entry: {
     beforeWrite?: () => void | Promise<void>;
 }): Promise<string>;
 export declare function sweepRpcState(root: string, activeDir: string, isManagedDir: (name: string) => boolean, log?: RpcLogChannel): Promise<void>;
-export declare function discoverPortFile(dir: string, expectedPid?: number): Promise<PortFileEntry | null>;
+export interface DiscoverPortFileOptions {
+    /**
+     * Return only the expected PID's entry, or null; never fall back to
+     * another live server. Without an expected PID nothing matches, so the
+     * result is null. Off by default, when a missing or unmatched expected PID
+     * falls back to the newest live entry.
+     */
+    exactPid?: boolean;
+}
+export declare function discoverPortFile(dir: string, expectedPid?: number, options?: DiscoverPortFileOptions): Promise<PortFileEntry | null>;

package/dist/rpc/port-file.js

@@ -1,7 +1,17 @@
 import { createHash } from 'node:crypto';
 import { chmod, mkdir, readdir, readFile, rename, rmdir, unlink, writeFile, } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+/**
+ * A PID a liveness probe may address. `process.kill(0 | negative, 0)` signals
+ * a process group rather than a process, and an unsafe integer cannot name a
+ * real process, so neither is ever probed.
+ */
+function isProbeablePid(pid) {
+    return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0;
+}
 function pidAlive(pid) {
+    if (!isProbeablePid(pid))
+        return false;
     try {
         process.kill(pid, 0);
         return true;
@@ -23,14 +33,29 @@ export function getRpcDir(rpcRoot, directoryPrefix, projectDirectory) {
     return join(rpcRoot, directoryPrefix +
         createHash('sha256').update(projectDirectory).digest('hex').slice(0, 16));
 }
-function isUsablePortFileEntry(value) {
-    return (value !== null &&
-        typeof value === 'object' &&
-        !Array.isArray(value) &&
-        typeof value.pid === 'number' &&
-        Number.isFinite(value.pid) &&
-        typeof value.port === 'number' &&
-        Number.isFinite(value.port));
+/** The PID a port file's name claims, or undefined for a malformed name. */
+function filenamePid(name) {
+    const match = /^port-(\d+)\.json$/.exec(name);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * An entry a client may connect to: its PID is probeable and matches the PID
+ * in its file name (a mismatch means the file was not written by the server
+ * it names), its port is a real TCP port, and its token is non-empty (an
+ * absent token would otherwise be sent as `Bearer undefined`).
+ */
+function isUsablePortFileEntry(value, name) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const { pid, port, token } = value;
+    return (isProbeablePid(pid) &&
+        filenamePid(name) === pid &&
+        typeof port === 'number' &&
+        Number.isInteger(port) &&
+        port >= 1 &&
+        port <= 65_535 &&
+        typeof token === 'string' &&
+        token.length > 0);
 }
 async function removeCorruptPortFile(portFile, log) {
     log?.debug('rpc corrupt port file', { pid: process.pid, portFile });
@@ -53,11 +78,18 @@ export async function writePortFile(dir, entry, options = {}) {
         const full = { ...entry, startedAt: Date.now() };
         const target = join(dir, `port-${entry.pid}.json`);
         const tmp = `${target}.${process.pid}.tmp`;
-        await writeFile(tmp, JSON.stringify(full), {
-            encoding: 'utf8',
-            mode: 0o600,
-        });
-        await rename(tmp, target);
+        try {
+            await writeFile(tmp, JSON.stringify(full), {
+                encoding: 'utf8',
+                mode: 0o600,
+            });
+            await rename(tmp, target);
+        }
+        catch (error) {
+            // The staged file carries the server token; never leave it behind.
+            await unlink(tmp).catch(() => { });
+            throw error;
+        }
         return target;
     };
     try {
@@ -116,7 +148,7 @@ export async function sweepRpcState(root, activeDir, isManagedDir, log) {
                 await removeCorruptPortFile(portFile, log);
                 continue;
             }
-            if (!isUsablePortFileEntry(parsed)) {
+            if (!isUsablePortFileEntry(parsed, name)) {
                 await removeCorruptPortFile(portFile, log);
                 continue;
             }
@@ -128,7 +160,7 @@ export async function sweepRpcState(root, activeDir, isManagedDir, log) {
             await rmdir(dir).catch(() => { });
     }
 }
-export async function discoverPortFile(dir, expectedPid) {
+export async function discoverPortFile(dir, expectedPid, options = {}) {
     let names;
     try {
         names = await readdir(dir);
@@ -142,7 +174,7 @@ export async function discoverPortFile(dir, expectedPid) {
             continue;
         try {
             const parsed = JSON.parse(await readFile(join(dir, name), 'utf8'));
-            if (isUsablePortFileEntry(parsed)) {
+            if (isUsablePortFileEntry(parsed, name)) {
                 if (pidAlive(parsed.pid))
                     live.push(parsed);
                 else
@@ -156,6 +188,8 @@ export async function discoverPortFile(dir, expectedPid) {
     const candidates = expectedPid !== undefined && expectedPid >= 1
         ? live.filter((entry) => entry.pid === expectedPid)
         : [];
+    if (options.exactPid === true && candidates.length === 0)
+        return null;
     const entries = candidates.length > 0 ? candidates : live;
     const sortTime = (entry) => typeof entry.startedAt === 'number' && Number.isFinite(entry.startedAt)
         ? entry.startedAt

package/dist/rpc/rpc-client.d.ts

@@ -1,8 +1,25 @@
 import type { ApplyRequest, ApplyResult, RpcNotification } from './notifications.js';
-import { type PortFileEntry } from './port-file.js';
+import { type DiscoverPortFileOptions, type PortFileEntry } from './port-file.js';
 export interface RpcClient {
-    pending: (lastReceivedId: number, sessionId?: string) => Promise<RpcNotification[]>;
+    pending: (lastReceivedId: number, sessionId?: string, timeoutMs?: number) => Promise<RpcNotification[]>;
     apply: (request: ApplyRequest, timeoutMs?: number) => Promise<ApplyResult>;
 }
 export declare const DEFAULT_RPC_TIMEOUT_MS = 2000;
-export declare function createRpcClient(dir: string, expectedPid?: number, onSelected?: (entry: PortFileEntry | null) => void): RpcClient;
+/**
+ * `exactPid`: every call goes only to the expected PID's server. With no
+ * such server (or no expected PID) a call returns its fallback without
+ * opening a socket, on every call. Off by default, when a call falls back to
+ * the newest live server.
+ */
+export type RpcClientOptions = DiscoverPortFileOptions;
+/**
+ * A client for the server in `dir`, preferring `expectedPid`'s.
+ *
+ * `onSelected` reports the first selection: it is told which entry (or null)
+ * discovery chose, until one call of it returns normally. It is a report, not
+ * a gate: an observer that throws rejects that call before any request is
+ * sent and is asked again on the next call, but nothing stops a later call
+ * once an observer has returned. A caller that must never reach another
+ * server passes `{ exactPid: true }`.
+ */
+export declare function createRpcClient(dir: string, expectedPid?: number, onSelected?: (entry: PortFileEntry | null) => void, options?: RpcClientOptions): RpcClient;

package/dist/rpc/rpc-client.js

@@ -1,48 +1,150 @@
-import { discoverPortFile } from './port-file.js';
+import { connect } from 'node:net';
+import { discoverPortFile, } from './port-file.js';
 export const DEFAULT_RPC_TIMEOUT_MS = 2_000;
-async function call(dir, expectedPid, onSelected, method, params, timeoutMs = DEFAULT_RPC_TIMEOUT_MS) {
-    const entry = await discoverPortFile(dir, expectedPid);
+async function call(dir, expectedPid, discoverOptions, onSelected, method, params, timeoutMs = DEFAULT_RPC_TIMEOUT_MS) {
+    const entry = await discoverPortFile(dir, expectedPid, discoverOptions);
     onSelected?.(entry);
     if (!entry)
         return null;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const res = await fetch(`http://127.0.0.1:${entry.port}/rpc/${method}`, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                authorization: `Bearer ${entry.token}`,
-            },
-            body: JSON.stringify(params),
-            signal: controller.signal,
-        });
-        if (!res.ok)
-            return null;
-        return (await res.json());
-    }
-    catch {
-        return null;
-    }
-    finally {
-        clearTimeout(timer);
-    }
+    // A raw loopback socket never consults runtime HTTP proxy settings, which
+    // otherwise can expose the bearer token to a configured proxy. timeoutMs is
+    // a total deadline for connect, request and the full response, not idle time.
+    return new Promise((resolve) => {
+        let socket;
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket?.destroy();
+            resolve(value);
+        };
+        const timer = setTimeout(() => done(null), timeoutMs);
+        try {
+            const body = JSON.stringify(params);
+            socket = connect({ host: '127.0.0.1', port: entry.port });
+            socket.on('connect', () => {
+                // HTTP/1.0 avoids chunked responses; explicitly request connection close
+                // because older Bun servers can keep delayed HTTP/1.0 replies open.
+                socket?.write(`POST /rpc/${method} HTTP/1.0\r\n` +
+                    `Host: 127.0.0.1:${entry.port}\r\n` +
+                    'Connection: close\r\n' +
+                    'Content-Type: application/json\r\n' +
+                    `Content-Length: ${Buffer.byteLength(body)}\r\n` +
+                    `Authorization: Bearer ${entry.token}\r\n\r\n` +
+                    body);
+            });
+            const chunks = [];
+            let bytes = 0;
+            let headerBytes;
+            let contentLength;
+            let prefix = Buffer.alloc(0);
+            const finishBody = () => {
+                if (headerBytes === undefined)
+                    return done(null);
+                try {
+                    const payload = Buffer.concat(chunks).subarray(headerBytes);
+                    done(JSON.parse(payload.toString('utf8')));
+                }
+                catch {
+                    done(null);
+                }
+            };
+            socket.on('data', (chunk) => {
+                if (settled)
+                    return;
+                bytes += chunk.length;
+                chunks.push(chunk);
+                if (headerBytes === undefined) {
+                    prefix = Buffer.concat([prefix, chunk]);
+                    const separator = prefix.indexOf('\r\n\r\n');
+                    if (separator >= 0)
+                        headerBytes = separator + 4;
+                    if ((headerBytes ?? prefix.length) > 16 * 1024)
+                        return done(null);
+                    if (headerBytes !== undefined) {
+                        const headers = prefix
+                            .subarray(0, separator)
+                            .toString('latin1')
+                            .split('\r\n');
+                        const status = /^HTTP\/1\.[01] (\d{3})(?: |$)/.exec(headers[0] ?? '');
+                        if (!status || Number(status[1]) < 200 || Number(status[1]) >= 300)
+                            return done(null);
+                        for (const header of headers.slice(1)) {
+                            const colon = header.indexOf(':');
+                            const name = header.slice(0, colon).toLowerCase();
+                            const value = header.slice(colon + 1).trim();
+                            if (name === 'transfer-encoding')
+                                return done(null);
+                            if (name === 'content-length') {
+                                if (contentLength !== undefined || !/^\d+$/.test(value))
+                                    return done(null);
+                                contentLength = Number(value);
+                                if (!Number.isSafeInteger(contentLength) ||
+                                    contentLength > 8 * 1024 * 1024)
+                                    return done(null);
+                            }
+                        }
+                        prefix = Buffer.alloc(0);
+                    }
+                }
+                const bodyBytes = bytes - (headerBytes ?? bytes);
+                if (bodyBytes > 8 * 1024 * 1024)
+                    return done(null);
+                if (contentLength !== undefined) {
+                    if (bodyBytes > contentLength)
+                        return done(null);
+                    // Bun 1.3.14 can keep an async HTTP/1.0 reply open after sending
+                    // its complete Content-Length body; don't wait for EOF in that case.
+                    if (bodyBytes === contentLength)
+                        finishBody();
+                }
+            });
+            socket.on('end', () => {
+                if (contentLength !== undefined &&
+                    bytes - (headerBytes ?? 0) !== contentLength)
+                    return done(null);
+                finishBody();
+            });
+            socket.on('error', () => done(null));
+            socket.on('close', () => done(null));
+        }
+        catch {
+            done(null);
+        }
+    });
 }
-export function createRpcClient(dir, expectedPid, onSelected) {
+/**
+ * A client for the server in `dir`, preferring `expectedPid`'s.
+ *
+ * `onSelected` reports the first selection: it is told which entry (or null)
+ * discovery chose, until one call of it returns normally. It is a report, not
+ * a gate: an observer that throws rejects that call before any request is
+ * sent and is asked again on the next call, but nothing stops a later call
+ * once an observer has returned. A caller that must never reach another
+ * server passes `{ exactPid: true }`.
+ */
+export function createRpcClient(dir, expectedPid, onSelected, options = {}) {
+    const discoverOptions = {
+        exactPid: options.exactPid,
+    };
     let reportedSelection = false;
     const reportSelected = (entry) => {
         if (reportedSelection)
             return;
-        reportedSelection = true;
         onSelected?.(entry);
+        // Counted only after the observer returns, so a throwing one is not
+        // silently skipped on later calls.
+        reportedSelection = true;
     };
     return {
-        async pending(lastReceivedId, sessionId) {
-            const out = await call(dir, expectedPid, reportSelected, 'pending-notifications', { lastReceivedId, sessionId });
+        async pending(lastReceivedId, sessionId, timeoutMs) {
+            const out = await call(dir, expectedPid, discoverOptions, reportSelected, 'pending-notifications', { lastReceivedId, sessionId }, timeoutMs);
             return out?.messages ?? [];
         },
         async apply(request, timeoutMs) {
-            const out = await call(dir, expectedPid, reportSelected, 'apply', {
+            const out = await call(dir, expectedPid, discoverOptions, reportSelected, 'apply', {
                 ...request,
             }, timeoutMs);
             return out ?? { text: 'apply failed', knobs: {} };

package/dist/rpc/rpc-server.d.ts

@@ -23,5 +23,23 @@ export interface RpcServerOptions {
     requireSession?: boolean;
     timeoutMs?: number;
     receiptTimeoutMs?: number;
+    /**
+     * Answer an `apply` call whose handler is still running after this many
+     * milliseconds with 504 `{error: 'handler deadline exceeded'}`. The handler
+     * is not cancelled; its eventual result is discarded. Unset by default,
+     * when only the socket inactivity timeout (`timeoutMs`) bounds a handler,
+     * by destroying the socket.
+     */
+    applyDeadlineMs?: number;
+}
+/**
+ * Thrown by an `apply` or `drain` handler to refuse a request with a 4xx
+ * status. Its message is sent on the wire as `{error: message}`, so it must
+ * be written for the client and never quote a credential. Any other error a
+ * handler throws answers 500 with a fixed code.
+ */
+export declare class RpcRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
 }
 export declare function startRpcServer(options: RpcServerOptions): Promise<RpcServerHandle>;