@monosmith/plugin-sdk 0.1.0 → 0.2.0

package/README.md

@@ -68,8 +68,9 @@ serve (`PLUGIN_MEMBERS`), so a new method has to be given its place in the plugi
 | `protocol` | the generated types, the schema as data, `RpcError` |
 | `codec` | the wire form of the messages: key order, `omitempty`, sorted maps and escaping as the Go SDK writes them, so the bytes are equal; params shaped as the types promise |
 | `framing` | `Content-Length` framing over a byte stream |
-| `serve` | `serve`, `serveStreams`, the plugin interfaces, capability derivation |
-| `host` | `startPlugin`, `connectPlugin`, `connectInProcess`, `PluginClient`: the host side, for tests |
+| `serve` | `serve`, `serveStreams` (a bounded pool of workers, `cancel` and the plugin's `concurrency`), the plugin interfaces, capability derivation |
+| `concurrency` | what a declared `concurrency` means: one at a time by default, a count, or unlimited |
+| `host` | `startPlugin`, `connectPlugin`, `connectInProcess`, `PluginClient`: the host side, for tests; it keeps to the plugin's concurrency and cancels a call with an `AbortSignal` |
 | `conformance` | `checkPlugin`: the checks of `smith plugin check` |
 | `templating`, `jsondoc` | ports of the Go SDK's `templating` and `jsondoc` |
 | `tasks`, `scaffold`, `ci` | helpers to build the answers of contribute, generate and ci |

package/codec/index.d.ts

@@ -2,5 +2,5 @@ export { decodeParams, decodeResult, encodeParams, encodeResult } from './method
 export { EncodeError } from './encode-error.error.ts';
 export { ParamsError } from './params-error.error.ts';
 export { MessageParseError } from './message-parse.error.ts';
-export { parseRequest, parseResponse, writeFailure, writeRequest, writeResult } from './wire-message.mapper.ts';
+export { parseRequest, parseResponse, writeFailure, writeNotification, writeRequest, writeResult } from './wire-message.mapper.ts';
 export type { ReceivedRequest, ReceivedResponse } from './wire-message.mapper.ts';

package/codec/index.js

@@ -2,4 +2,4 @@ export { decodeParams, decodeResult, encodeParams, encodeResult } from './method
 export { EncodeError } from './encode-error.error.js';
 export { ParamsError } from './params-error.error.js';
 export { MessageParseError } from './message-parse.error.js';
-export { parseRequest, parseResponse, writeFailure, writeRequest, writeResult } from './wire-message.mapper.js';
+export { parseRequest, parseResponse, writeFailure, writeNotification, writeRequest, writeResult } from './wire-message.mapper.js';

package/codec/method-codec.algorithm.js

@@ -22,10 +22,10 @@ export function decodeResult(method, result) {
     return decode(method, 'result', result ?? {});
 }
 function encode(method, side, value) {
-    const row = rowOf(method);
-    return row === undefined ? encodeJsonValue(value, side) : encodeBySchema(protocolSchema, row[side], value, side);
+    const schema = rowOf(method)?.[side];
+    return schema === undefined || schema === null ? encodeJsonValue(value, side) : encodeBySchema(protocolSchema, schema, value, side);
 }
 function decode(method, side, value) {
-    const row = rowOf(method);
-    return row === undefined ? value : normalizeBySchema(protocolSchema, row[side], value, side);
+    const schema = rowOf(method)?.[side];
+    return schema === undefined || schema === null ? value : normalizeBySchema(protocolSchema, schema, value, side);
 }

package/codec/wire-message.mapper.d.ts

@@ -15,7 +15,9 @@ export interface ReceivedResponse {
 }
 /** A request as the Go SDK writes it: `jsonrpc`, `id`, `method`, `params`, the params left out when there are none. */
 export declare function writeRequest(id: number, method: string, paramsJson: string | undefined): string;
-/** A successful response: `id` is `null` only when the request could not be read. */
+/** A notification as the Go SDK writes it: a request with no `id`, which gets no response. */
+export declare function writeNotification(method: string, paramsJson: string): string;
+/** A successful response:`id` is `null` only when the request could not be read. */
 export declare function writeResult(id: number | null, resultJson: string): string;
 /** An error response. */
 export declare function writeFailure(id: number | null, code: number, message: string): string;

package/codec/wire-message.mapper.js

@@ -5,7 +5,11 @@ export function writeRequest(id, method, paramsJson) {
     const params = paramsJson === undefined ? '' : `,"params":${paramsJson}`;
     return `{"jsonrpc":"2.0","id":${id},"method":${encodeJsonString(method)}${params}}`;
 }
-/** A successful response: `id` is `null` only when the request could not be read. */
+/** A notification as the Go SDK writes it: a request with no `id`, which gets no response. */
+export function writeNotification(method, paramsJson) {
+    return `{"jsonrpc":"2.0","method":${encodeJsonString(method)},"params":${paramsJson}}`;
+}
+/** A successful response:`id` is `null` only when the request could not be read. */
 export function writeResult(id, resultJson) {
     return `{"jsonrpc":"2.0","id":${id === null ? 'null' : id},"result":${resultJson}}`;
 }

package/concurrency/concurrency.policy.d.ts

@@ -0,0 +1,21 @@
+/** The `concurrency` value that leaves the number of simultaneous requests to the host. */
+export declare const CONCURRENCY_UNLIMITED = -1;
+/** How many requests the host keeps in flight to a plugin that declared unlimited concurrency. */
+export declare const UNLIMITED_IN_FLIGHT = 32;
+/** The most workers a plugin that declared unlimited concurrency runs: the host decides, but the pool stays bounded. */
+export declare const UNLIMITED_WORKERS = 1024;
+/** Whether a declared concurrency is one the protocol defines: absent (0), a count (1 and above) or unlimited (-1). */
+export declare function isValidConcurrency(declared: number): boolean;
+/**
+ * Reads a declared concurrency: how many requests may be in flight at once,
+ * or `unlimited`. An absent, zero or invalid value is 1, the default of every
+ * plugin that says nothing.
+ */
+export declare function concurrencyLimit(declared: number | undefined): {
+    limit: number;
+    unlimited: boolean;
+};
+/** How many requests the host keeps in flight to a plugin that declared `declared`. */
+export declare function inFlightLimit(declared: number | undefined): number;
+/** How many requests a plugin that declared `declared` works on at once (its pool size). */
+export declare function workerLimit(declared: number | undefined): number;

package/concurrency/concurrency.policy.js

@@ -0,0 +1,30 @@
+/** The `concurrency` value that leaves the number of simultaneous requests to the host. */
+export const CONCURRENCY_UNLIMITED = -1;
+/** How many requests the host keeps in flight to a plugin that declared unlimited concurrency. */
+export const UNLIMITED_IN_FLIGHT = 32;
+/** The most workers a plugin that declared unlimited concurrency runs: the host decides, but the pool stays bounded. */
+export const UNLIMITED_WORKERS = 1024;
+/** Whether a declared concurrency is one the protocol defines: absent (0), a count (1 and above) or unlimited (-1). */
+export function isValidConcurrency(declared) {
+    return Number.isSafeInteger(declared) && declared >= CONCURRENCY_UNLIMITED;
+}
+/**
+ * Reads a declared concurrency: how many requests may be in flight at once,
+ * or `unlimited`. An absent, zero or invalid value is 1, the default of every
+ * plugin that says nothing.
+ */
+export function concurrencyLimit(declared) {
+    if (declared === CONCURRENCY_UNLIMITED)
+        return { limit: 0, unlimited: true };
+    return { limit: declared === undefined || !Number.isSafeInteger(declared) || declared < 1 ? 1 : declared, unlimited: false };
+}
+/** How many requests the host keeps in flight to a plugin that declared `declared`. */
+export function inFlightLimit(declared) {
+    const { limit, unlimited } = concurrencyLimit(declared);
+    return unlimited ? UNLIMITED_IN_FLIGHT : limit;
+}
+/** How many requests a plugin that declared `declared` works on at once (its pool size). */
+export function workerLimit(declared) {
+    const { limit, unlimited } = concurrencyLimit(declared);
+    return unlimited ? UNLIMITED_WORKERS : limit;
+}

package/concurrency/index.d.ts

@@ -0,0 +1 @@
+export { CONCURRENCY_UNLIMITED, UNLIMITED_IN_FLIGHT, UNLIMITED_WORKERS, concurrencyLimit, inFlightLimit, isValidConcurrency, workerLimit } from './concurrency.policy.ts';

package/concurrency/index.js

@@ -0,0 +1 @@
+export { CONCURRENCY_UNLIMITED, UNLIMITED_IN_FLIGHT, UNLIMITED_WORKERS, concurrencyLimit, inFlightLimit, isValidConcurrency, workerLimit } from './concurrency.policy.js';

package/conformance/check-plugin.use-case.d.ts

@@ -15,7 +15,8 @@ export interface CheckOptions {
  * itself, has a known kind and known roles, its roles match what it
  * implements, it names the slots it fills, its references and stacks are
  * well-formed, every advertised method answers a request with nothing in it,
- * and, with `workspace`, the projects it generates are found again by its own
+ * requests sent together are answered as the declared `concurrency` allows, a
+ * plugin that advertises `cancel` stops a cancelled request, and, with `workspace`, the projects it generates are found again by its own
  * `discover`. A port of the Go SDK's `conformance.Check`, with the same checks
  * under the same names. (`smith plugin check` adds one more, "shuts down when
  * asked", after closing the plugin: call {@link PluginClient.close} and add it

package/conformance/check-plugin.use-case.js

@@ -1,6 +1,7 @@
 import { describeRef, isEmptyRef } from '../plugin-refs/index.js';
 import { ROLES, effectiveRoles, isKnownRole } from '../plugin-roles/index.js';
 import { checkGeneration } from './check-generation.use-case.js';
+import { checkScheduling } from './check-scheduling.use-case.js';
 import { ConformanceReport } from './conformance-report.model.js';
 import { goList, goQuote } from './go-list.mapper.js';
 const CALL_TIMEOUT_MS = 20 * 60 * 1000;
@@ -9,7 +10,8 @@ const CALL_TIMEOUT_MS = 20 * 60 * 1000;
  * itself, has a known kind and known roles, its roles match what it
  * implements, it names the slots it fills, its references and stacks are
  * well-formed, every advertised method answers a request with nothing in it,
- * and, with `workspace`, the projects it generates are found again by its own
+ * requests sent together are answered as the declared `concurrency` allows, a
+ * plugin that advertises `cancel` stops a cancelled request, and, with `workspace`, the projects it generates are found again by its own
  * `discover`. A port of the Go SDK's `conformance.Check`, with the same checks
  * under the same names. (`smith plugin check` adds one more, "shuts down when
  * asked", after closing the plugin: call {@link PluginClient.close} and add it
@@ -52,6 +54,7 @@ export async function checkPlugin(client, options = {}) {
         report.add(`stack ${stack.name} is complete`, stack.name !== '' && stack.language !== '' && !names.has(stack.name), 'a stack needs a unique name and a language plugin');
         names.add(stack.name);
     }
+    await checkScheduling(client, report);
     const answers = async (check, method, params) => {
         if (!client.supports(method))
             return;

package/conformance/check-scheduling.use-case.d.ts

@@ -0,0 +1,11 @@
+import type { PluginClient } from '../host/index.ts';
+import type { ConformanceReport } from './conformance-report.model.ts';
+/** How long a plugin that advertised cancel has to answer a request the host cancelled. */
+export declare const CANCEL_BOUND_MS = 10000;
+/**
+ * Checks what a plugin says about how it is called: the concurrency it
+ * declares must be one the protocol defines and be accepted, and the cancel it
+ * advertises must stop a request within a bound and leave the plugin serving.
+ * The same checks, under the same names, as the Go SDK's.
+ */
+export declare function checkScheduling(client: PluginClient, report: ConformanceReport, cancelBoundMs?: number): Promise<void>;

package/conformance/check-scheduling.use-case.js

@@ -0,0 +1,98 @@
+import { CallInterruptedError } from '../host/index.js';
+import { ERROR_CODES } from '../protocol/index.js';
+import { inFlightLimit, isValidConcurrency } from '../concurrency/index.js';
+/** How long a plugin that advertised cancel has to answer a request the host cancelled. */
+export const CANCEL_BOUND_MS = 10_000;
+/** An id no request ever had. */
+const UNKNOWN_REQUEST = 2 ** 40;
+/** The cheapest call the plugin answers without doing work: a method that takes a list of projects or manifests, asked about none. */
+function probeOf(client) {
+    const timeoutMs = 2 * 60 * 1000;
+    if (client.supports('discover'))
+        return signal => client.call('discover', { manifests: [] }, { timeoutMs, signal });
+    if (client.supports('contribute'))
+        return signal => client.call('contribute', { projects: [] }, { timeoutMs, signal });
+    if (client.supports('ci'))
+        return signal => client.call('ci', { projects: [] }, { timeoutMs, signal });
+    return client.supports('doctor') ? signal => client.call('doctor', { projects: [] }, { timeoutMs, signal }) : undefined;
+}
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}
+/**
+ * Checks what a plugin says about how it is called: the concurrency it
+ * declares must be one the protocol defines and be accepted, and the cancel it
+ * advertises must stop a request within a bound and leave the plugin serving.
+ * The same checks, under the same names, as the Go SDK's.
+ */
+export async function checkScheduling(client, report, cancelBoundMs = CANCEL_BOUND_MS) {
+    const info = client.info;
+    report.add('declares a concurrency the protocol defines', isValidConcurrency(info.concurrency ?? 0), `concurrency ${info.concurrency} is below -1; it must be absent, 1 or more, or -1 for unlimited`);
+    const probe = probeOf(client);
+    if (probe === undefined)
+        return;
+    await checkConcurrency(client, probe, report);
+    if (info.capabilities.cancel === true)
+        await checkCancel(client, probe, report, cancelBoundMs);
+}
+/**
+ * Sends requests together. A plugin that declares nothing is sent them one at
+ * a time and must answer them all; one that declares a concurrency is sent that
+ * many at once (at most four, to keep the check cheap) and must answer them all.
+ */
+async function checkConcurrency(client, probe, report) {
+    const limit = inFlightLimit(client.info.concurrency);
+    let together = Math.min(limit, 4);
+    let name = `accepts ${together} requests at the same time`;
+    if (limit === 1) {
+        together = 3;
+        name = 'answers 3 requests sent together, one at a time';
+    }
+    const settled = await Promise.allSettled(Array.from({ length: together }, async () => await probe()));
+    const failed = settled.find((result) => result.status === 'rejected');
+    const peak = client.peakInFlight;
+    report.add(name, failed === undefined && peak <= limit, `${failed === undefined ? '<nil>' : messageOf(failed.reason)} (the host had ${peak} in flight, the plugin declared ${limit})`);
+}
+/** How a promise ended: with the error it rejected with, if any. */
+async function settle(promise) {
+    try {
+        await promise;
+        return {};
+    }
+    catch (error) {
+        return { error };
+    }
+}
+/** Cancels a request, then a request that does not exist. */
+async function checkCancel(client, probe, report, cancelBoundMs) {
+    const controller = new AbortController();
+    const began = Date.now();
+    const request = settle(probe(controller.signal));
+    await new Promise(resolve => setTimeout(resolve, 5)); // let the request leave; a cancel that wins the race is just as good an answer
+    controller.abort();
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => { resolve('late'); }, cancelBoundMs + client.cancelGraceMs);
+    });
+    const outcome = await Promise.race([request, late]);
+    clearTimeout(timer);
+    const error = outcome === 'late' ? new Error(`no answer within ${cancelBoundMs}ms of the cancel`) : outcome.error;
+    const stopped = outcome !== 'late' && (error === undefined || (error instanceof CallInterruptedError && !error.killed));
+    const detail = `${error === undefined ? '<nil>' : messageOf(error)} (a plugin that advertised cancel answers the request, with ${ERROR_CODES.RequestCancelled} if it stopped, within ${cancelBoundMs}ms)`;
+    report.add('answers a cancelled request with its result or the cancelled error', stopped && Date.now() - began < cancelBoundMs, detail);
+    let notifyError;
+    let followUp;
+    try {
+        await client.notify('cancel', { id: UNKNOWN_REQUEST });
+    }
+    catch (error_) {
+        notifyError = error_;
+    }
+    try {
+        await probe();
+    }
+    catch (error_) {
+        followUp = error_;
+    }
+    report.add('ignores a cancel for a request it does not know', notifyError === undefined && followUp === undefined, `${notifyError === undefined ? '<nil>' : messageOf(notifyError)}, then ${followUp === undefined ? '<nil>' : messageOf(followUp)}`);
+}

package/host/call-interrupted.error.d.ts

@@ -0,0 +1,16 @@
+import type { RpcError } from '../protocol/index.ts';
+/** Why the host stopped waiting for a call. */
+export type InterruptionReason = 'cancelled' | 'timeout';
+/**
+ * A call the host gave up on, because its `signal` aborted (`cancelled`) or its
+ * time ran out (`timeout`). `killed` says the plugin did not stop in time
+ * and was killed, which also fails every other call in flight to it. When the
+ * plugin answered while being stopped, `response` is its error (the
+ * request-cancelled code, usually).
+ */
+export declare class CallInterruptedError extends Error {
+    readonly reason: InterruptionReason;
+    readonly killed: boolean;
+    readonly response?: RpcError;
+    constructor(message: string, reason: InterruptionReason, killed: boolean, response?: RpcError);
+}

package/host/call-interrupted.error.js

@@ -0,0 +1,20 @@
+/**
+ * A call the host gave up on, because its `signal` aborted (`cancelled`) or its
+ * time ran out (`timeout`). `killed` says the plugin did not stop in time
+ * and was killed, which also fails every other call in flight to it. When the
+ * plugin answered while being stopped, `response` is its error (the
+ * request-cancelled code, usually).
+ */
+export class CallInterruptedError extends Error {
+    reason;
+    killed;
+    response;
+    constructor(message, reason, killed, response) {
+        super(message, response === undefined ? undefined : { cause: response });
+        this.name = 'CallInterruptedError';
+        this.reason = reason;
+        this.killed = killed;
+        if (response !== undefined)
+            this.response = response;
+    }
+}

package/host/host-options.contract.d.ts

@@ -7,6 +7,8 @@ export interface HostOptions {
     host?: Peer;
     /** How long `initialize` may take. Default: 30 seconds. */
     initializeTimeoutMs?: number;
+    /** How long a plugin has to answer after it was asked to stop (or, for one that cannot be asked, after the caller cancelled) before it is killed. Default: 5 seconds. */
+    cancelGraceMs?: number;
 }
 /** Options of {@link startPlugin}: a plugin process to launch. */
 export interface StartOptions extends HostOptions {
@@ -19,10 +21,14 @@ export interface StartOptions extends HostOptions {
     /** What happens to the plugin's standard error, where it logs. Default: it goes to this process's standard error. */
     stderr?: 'inherit' | 'ignore';
 }
+/** How long a plugin has to answer after it was asked to stop, before the host kills it. */
+export declare const DEFAULT_CANCEL_GRACE_MS = 5000;
 /** The longest a call may take unless the caller says otherwise: generate and publish run real toolchains. */
 export declare const DEFAULT_CALL_TIMEOUT_MS: number;
 /** Options of one {@link PluginClient.call}. */
 export interface CallOptions {
     /** How long the plugin may take. On expiry the plugin process is killed: its stream can no longer be trusted. Default: 2 minutes. */
     timeoutMs?: number;
+    /** Aborting it cancels the call: the plugin is sent `cancel` if it advertised it, and the call ends within the grace period. */
+    signal?: AbortSignal;
 }

package/host/host-options.contract.js

@@ -1,2 +1,4 @@
+/** How long a plugin has to answer after it was asked to stop, before the host kills it. */
+export const DEFAULT_CANCEL_GRACE_MS = 5000;
 /** The longest a call may take unless the caller says otherwise: generate and publish run real toolchains. */
 export const DEFAULT_CALL_TIMEOUT_MS = 2 * 60 * 1000;

package/host/index.d.ts

@@ -3,5 +3,7 @@ export type { PluginConnection } from './plugin-client.client.ts';
 export { startPlugin } from './start-plugin.use-case.ts';
 export { connectInProcess, connectPlugin } from './connect-plugin.use-case.ts';
 export type { PluginStreams } from './connect-plugin.use-case.ts';
-export { DEFAULT_CALL_TIMEOUT_MS } from './host-options.contract.ts';
+export { CallInterruptedError } from './call-interrupted.error.ts';
+export type { InterruptionReason } from './call-interrupted.error.ts';
+export { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_CANCEL_GRACE_MS } from './host-options.contract.ts';
 export type { CallOptions, HostOptions, StartOptions } from './host-options.contract.ts';

package/host/index.js

@@ -1,4 +1,5 @@
 export { PluginClient } from './plugin-client.client.js';
 export { startPlugin } from './start-plugin.use-case.js';
 export { connectInProcess, connectPlugin } from './connect-plugin.use-case.js';
-export { DEFAULT_CALL_TIMEOUT_MS } from './host-options.contract.js';
+export { CallInterruptedError } from './call-interrupted.error.js';
+export { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_CANCEL_GRACE_MS } from './host-options.contract.js';

package/host/plugin-client.client.d.ts

@@ -9,17 +9,20 @@ export interface PluginConnection {
         write: (chunk: Buffer, callback: (error?: Error | null) => void) => unknown;
         end: () => unknown;
     };
-    /** Called when a call timed out: ends the plugin, if it is a process. */
+    /** Called when the plugin did not answer in time: ends the plugin, if it is a process. */
     kill: () => void;
     /** Resolves once the plugin has gone, with the reason it did not end well (or `null`). Called by {@link PluginClient.close}. */
     finish: (graceMs: number) => Promise<string | null>;
 }
 /**
  * The host's side of a connection to one initialized plugin, for a plugin
- * author's tests (smith itself is the host in real use). Calls are serialised,
- * as smith serialises them, each with a timeout. Open one with {@link startPlugin}
- * (a process), {@link connectPlugin} (streams) or {@link connectInProcess}
- * (a plugin object served in this process).
+ * author's tests (smith itself is the host in real use). It never has more
+ * requests in flight than the plugin declared in `concurrency`, as smith does:
+ * with the default of one, calls are serialised, each waiting for the one
+ * before it to be answered. Each call has a timeout and may be cancelled with
+ * an `AbortSignal`. Open one with {@link startPlugin} (a process),
+ * {@link connectPlugin} (streams) or {@link connectInProcess} (a plugin object
+ * served in this process).
  */
 export declare class PluginClient {
     #private;
@@ -30,11 +33,27 @@ export declare class PluginClient {
     private constructor();
     /**
      * Sends one request and resolves with its decoded result. An error answer
-     * rejects with an {@link RpcError} carrying its code. If the plugin does not
-     * answer in time, the plugin is killed and the call rejects.
+     * rejects with an {@link RpcError} carrying its code. The call waits for a
+     * place first, so the plugin never has more requests in flight than it
+     * declared; the timeout counts from the moment the request is sent.
+     *
+     * When `options.signal` aborts or the time runs out the host stops waiting.
+     * A plugin that advertised `cancel` is sent the notification and has the
+     * grace period to answer: with the result it had already (the call resolves),
+     * or an error (the call rejects with a {@link CallInterruptedError} carrying
+     * it). A plugin that does not answer in time is killed, because its stream can
+     * no longer be trusted, and the call rejects; a plugin that cannot be asked
+     * to stop is killed at once on a timeout, and after the grace period when
+     * the caller cancelled.
      */
     call<M extends MethodName>(method: M, params: ParamsOf<M>, options?: CallOptions): Promise<ResultOf<M>>;
     call(method: string, params?: unknown, options?: CallOptions): Promise<unknown>;
+    /** How long the plugin has to answer after it was asked to stop. */
+    get cancelGraceMs(): number;
+    /** The most requests this client has had in flight at once. */
+    get peakInFlight(): number;
+    /** Sends a message that gets no answer, such as `cancel`. */
+    notify(method: string, params: unknown): Promise<void>;
     /** Whether the plugin advertised a method: `initialize` and `shutdown` always, the others by their capability. */
     supports(method: string): boolean;
     /** Asks the plugin to shut down and waits briefly for it to go. Rejects if it did not go quietly. */