@monosmith/plugin-sdk 0.1.0 → 0.2.0

package/serve/capabilities-of.algorithm.d.ts

@@ -6,7 +6,8 @@ export declare function implementsMethod(plugin: SmithPlugin, method: string): b
  * The capabilities a plugin advertises, derived from the methods it
  * implements: a plugin cannot advertise a method it lacks, or implement one
  * it does not advertise. The capability of each method is read from the
- * schema's methods table.
+ * schema's methods table; `cancel` comes from the plugin saying it is
+ * `cancellable`.
  */
 export declare function capabilitiesOf(plugin: SmithPlugin): Capabilities;
 /** Methods a plugin half-implements: a member of a pair (`install` without `uninstall`) that is not advertised for lack of the other. */

package/serve/capabilities-of.algorithm.js

@@ -9,7 +9,8 @@ export function implementsMethod(plugin, method) {
  * The capabilities a plugin advertises, derived from the methods it
  * implements: a plugin cannot advertise a method it lacks, or implement one
  * it does not advertise. The capability of each method is read from the
- * schema's methods table.
+ * schema's methods table; `cancel` comes from the plugin saying it is
+ * `cancellable`.
  */
 export function capabilitiesOf(plugin) {
     const capabilities = {};
@@ -18,6 +19,8 @@ export function capabilitiesOf(plugin) {
         if (row.capability !== null && implementsMethod(plugin, method))
             capabilities[row.capability] = true;
     }
+    if (plugin.cancellable === true)
+        capabilities.cancel = true;
     return capabilities;
 }
 /** Methods a plugin half-implements: a member of a pair (`install` without `uninstall`) that is not advertised for lack of the other. */

package/serve/dispatch-request.use-case.d.ts

@@ -9,6 +9,7 @@ export declare function messageOf(thrown: unknown): string;
  * MethodNotFound for a method the plugin does not implement, InvalidParams
  * for params of the wrong shape, PluginFailure for an exception the method
  * threw (its message is shown to the user), InternalError for a result that
- * cannot be written as the schema describes.
+ * cannot be written as the schema describes. `signal` is passed to the method as its
+ * second argument; it aborts when the host cancels the request.
  */
-export declare function dispatchRequest(plugin: SmithPlugin, request: ReceivedRequest): Promise<RequestOutcome>;
+export declare function dispatchRequest(plugin: SmithPlugin, request: ReceivedRequest, signal?: AbortSignal): Promise<RequestOutcome>;

package/serve/dispatch-request.use-case.js

@@ -13,9 +13,10 @@ export function messageOf(thrown) {
  * MethodNotFound for a method the plugin does not implement, InvalidParams
  * for params of the wrong shape, PluginFailure for an exception the method
  * threw (its message is shown to the user), InternalError for a result that
- * cannot be written as the schema describes.
+ * cannot be written as the schema describes. `signal` is passed to the method as its
+ * second argument; it aborts when the host cancels the request.
  */
-export async function dispatchRequest(plugin, request) {
+export async function dispatchRequest(plugin, request, signal = new AbortController().signal) {
     if (request.method === 'shutdown')
         return { ok: true, resultJson: '{}' };
     let params;
@@ -36,7 +37,7 @@ export async function dispatchRequest(plugin, request) {
         }
         else if (implementsMethod(plugin, request.method)) {
             const member = PLUGIN_MEMBERS[request.method].member;
-            result = await plugin[member].call(plugin, params);
+            result = await plugin[member].call(plugin, params, signal);
         }
         else {
             return { ok: false, code: ERROR_CODES.MethodNotFound, message: `method not supported: ${request.method}` };

package/serve/index.d.ts

@@ -1,4 +1,4 @@
 export { serve, serveStreams } from './serve.use-case.ts';
 export { capabilitiesOf, implementsMethod } from './capabilities-of.algorithm.ts';
-export type { Awaitable, CIContributor, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
+export type { Awaitable, Cancellable, CIContributor, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
 export type { FrameSink, ServeStreams } from './protocol-streams.contract.ts';

package/serve/plugin.contract.d.ts

@@ -10,56 +10,71 @@ export interface Plugin {
 }
 /** `discover`: describes the projects behind manifests. */
 export interface Discoverer {
-    discover: (params: DiscoverParams) => Awaitable<DiscoverResult>;
+    discover: (params: DiscoverParams, signal: AbortSignal) => Awaitable<DiscoverResult>;
 }
 /** `generate`: scaffolds a project. */
 export interface Generator {
-    generate: (params: GenerateParams) => Awaitable<GenerateResult>;
+    generate: (params: GenerateParams, signal: AbortSignal) => Awaitable<GenerateResult>;
 }
 /** `version/write`: records a release version in a manifest. */
 export interface Versioner {
-    writeVersion: (params: VersionParams) => Awaitable<VersionResult>;
+    writeVersion: (params: VersionParams, signal: AbortSignal) => Awaitable<VersionResult>;
 }
 /** `publish`: publishes a released project. */
 export interface Publisher {
-    publish: (params: PublishParams) => Awaitable<PublishResult>;
+    publish: (params: PublishParams, signal: AbortSignal) => Awaitable<PublishResult>;
 }
 /** `published`: the newest version a registry has of a project. */
 export interface RegistryReader {
-    published: (params: PublishedParams) => Awaitable<PublishedResult>;
+    published: (params: PublishedParams, signal: AbortSignal) => Awaitable<PublishedResult>;
 }
 /** `ci`: what a pipeline needs for the plugin's projects. */
 export interface CIContributor {
-    ci: (params: CIParams) => Awaitable<CIResult>;
+    ci: (params: CIParams, signal: AbortSignal) => Awaitable<CIResult>;
 }
 /** `doctor`: checks the plugin's projects. */
 export interface DoctorContributor {
-    doctor: (params: DoctorParams) => Awaitable<DoctorResult>;
+    doctor: (params: DoctorParams, signal: AbortSignal) => Awaitable<DoctorResult>;
 }
 /** `remove`: cleans up after a project is removed. */
 export interface Remover {
-    remove: (params: RemoveParams) => Awaitable<RemoveResult>;
+    remove: (params: RemoveParams, signal: AbortSignal) => Awaitable<RemoveResult>;
 }
 /** `dependencies/install` and `dependencies/uninstall`: both, or the capability is not advertised. */
 export interface DependencyManager {
-    install: (params: InstallParams) => Awaitable<DependencyResult>;
-    uninstall: (params: UninstallParams) => Awaitable<DependencyResult>;
+    install: (params: InstallParams, signal: AbortSignal) => Awaitable<DependencyResult>;
+    uninstall: (params: UninstallParams, signal: AbortSignal) => Awaitable<DependencyResult>;
 }
 /** `dependencies/declared` and `dependencies/rewrite`: both, or the capability is not advertised. */
 export interface DeclarationEditor {
-    declared: (params: DeclaredParams) => Awaitable<DeclaredResult>;
-    rewrite: (params: RewriteParams) => Awaitable<DependencyResult>;
+    declared: (params: DeclaredParams, signal: AbortSignal) => Awaitable<DeclaredResult>;
+    rewrite: (params: RewriteParams, signal: AbortSignal) => Awaitable<DependencyResult>;
 }
 /** `dependencies/latest`: the newest releases of dependencies and pinned tools. */
 export interface LatestReader {
-    latest: (params: LatestParams) => Awaitable<LatestResult>;
+    latest: (params: LatestParams, signal: AbortSignal) => Awaitable<LatestResult>;
 }
 /** `contribute`: a convention adds tasks to the projects it applies to. */
 export interface Contributor {
-    contribute: (params: ContributeParams) => Awaitable<ContributeResult>;
+    contribute: (params: ContributeParams, signal: AbortSignal) => Awaitable<ContributeResult>;
+}
+/**
+ * `cancellable: true` says the plugin's methods stop their work when the
+ * `AbortSignal` they are passed as their second argument aborts, which the
+ * serve loop does when the host sends the `cancel` notification for the
+ * request. The plugin then advertises the `cancel` capability. A method that
+ * stops throws (any error is answered with the request-cancelled code) or
+ * returns the result it already has. Without it the signal never aborts and
+ * the host is never sent a cancel: it waits for the answer, or kills the
+ * plugin.
+ */
+export interface Cancellable {
+    cancellable: true;
 }
 /**
  * A plugin as {@link serve} takes it: `describe`, and the methods it implements.
- * The capabilities it advertises are derived from which methods it has.
+ * The capabilities it advertises are derived from which methods it has, and
+ * from `cancellable`. How many requests it can work on at once is declared in
+ * `describe`'s `concurrency`: omit it for one at a time, in order.
  */
-export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & DependencyManager & DeclarationEditor & LatestReader & Contributor>;
+export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;

package/serve/request-pool.store.d.ts

@@ -0,0 +1,49 @@
+import type { ReceivedRequest } from '../codec/index.ts';
+/** The requests waiting for a worker are limited to this many; the host never has more in flight than the plugin declared, so more means a host that breaks the protocol. */
+export declare const MAX_QUEUED = 1024;
+/** One request from the moment it is read until it is answered. */
+export interface PooledRequest {
+    readonly request: ReceivedRequest & {
+        id: number;
+    };
+    /** Aborted when the host cancels the request (or the plugin is shutting down). */
+    readonly controller: AbortController;
+    /** Whether the host asked for the request to stop. */
+    cancelled: boolean;
+}
+/** What {@link RequestPool.submit} decided. */
+export type Admission = 'admitted' | 'duplicate' | 'full';
+/**
+ * The state of the serve loop: the requests in flight, the ones waiting for a
+ * worker, and a bounded number of workers running them. Requests start in the
+ * order they arrive and may finish in any order. The Go SDK's request pool,
+ * with the same rules.
+ */
+export declare class RequestPool {
+    #private;
+    /** `run` answers one request; if it throws, the first error is kept in {@link failure} and the pool goes on. */
+    constructor(run: (pooled: PooledRequest) => Promise<void>);
+    /** The first error a run threw, if any. */
+    get failure(): unknown;
+    /** How many workers may run at once. Raising it starts waiting requests; lowering it lets running ones finish. */
+    setLimit(limit: number): void;
+    /** Takes a request: it runs at once on a free worker, or waits its turn. */
+    submit(request: ReceivedRequest & {
+        id: number;
+    }): Admission;
+    /**
+     * Forgets an answered request; call it before the answer is written, so a
+     * host that reuses the id right away is not refused as a duplicate.
+     */
+    release(pooled: PooledRequest): void;
+    /**
+     * Stops the request with an id. One that had not started is taken out of
+     * the queue and returned, because no worker will ever answer it. An unknown
+     * id is ignored.
+     */
+    cancel(id: number): PooledRequest | undefined;
+    /** Stops every request. The ones that had not started are returned, to be answered. */
+    cancelAll(): PooledRequest[];
+    /** Resolves once no worker is running. */
+    idle(): Promise<void>;
+}

package/serve/request-pool.store.js

@@ -0,0 +1,110 @@
+/** The requests waiting for a worker are limited to this many; the host never has more in flight than the plugin declared, so more means a host that breaks the protocol. */
+export const MAX_QUEUED = 1024;
+/**
+ * The state of the serve loop: the requests in flight, the ones waiting for a
+ * worker, and a bounded number of workers running them. Requests start in the
+ * order they arrive and may finish in any order. The Go SDK's request pool,
+ * with the same rules.
+ */
+export class RequestPool {
+    #limit = 1;
+    #running = 0;
+    #queue = [];
+    #inflight = new Map();
+    #idle = [];
+    #run;
+    #failure;
+    /** `run` answers one request; if it throws, the first error is kept in {@link failure} and the pool goes on. */
+    constructor(run) {
+        this.#run = run;
+    }
+    #start(first) {
+        this.#running++;
+        void this.#work(first);
+    }
+    async #work(first) {
+        for (let pooled = first; pooled !== undefined; pooled = this.#next()) {
+            try {
+                await this.#run(pooled);
+            }
+            catch (error) {
+                this.#failure ??= error;
+            }
+        }
+    }
+    #next() {
+        if (this.#queue.length > 0 && this.#running <= this.#limit)
+            return this.#queue.shift();
+        this.#running--;
+        if (this.#running === 0)
+            for (const resolve of this.#idle.splice(0))
+                resolve();
+        return undefined;
+    }
+    /** The first error a run threw, if any. */
+    get failure() {
+        return this.#failure;
+    }
+    /** How many workers may run at once. Raising it starts waiting requests; lowering it lets running ones finish. */
+    setLimit(limit) {
+        this.#limit = Math.max(1, limit);
+        while (this.#running < this.#limit && this.#queue.length > 0)
+            this.#start(this.#queue.shift());
+    }
+    /** Takes a request: it runs at once on a free worker, or waits its turn. */
+    submit(request) {
+        if (this.#inflight.has(request.id))
+            return 'duplicate';
+        if (this.#running >= this.#limit && this.#queue.length >= MAX_QUEUED)
+            return 'full';
+        const pooled = { request, controller: new AbortController(), cancelled: false };
+        this.#inflight.set(request.id, pooled);
+        if (this.#running >= this.#limit)
+            this.#queue.push(pooled);
+        else
+            this.#start(pooled);
+        return 'admitted';
+    }
+    /**
+     * Forgets an answered request; call it before the answer is written, so a
+     * host that reuses the id right away is not refused as a duplicate.
+     */
+    release(pooled) {
+        this.#inflight.delete(pooled.request.id);
+    }
+    /**
+     * Stops the request with an id. One that had not started is taken out of
+     * the queue and returned, because no worker will ever answer it. An unknown
+     * id is ignored.
+     */
+    cancel(id) {
+        const pooled = this.#inflight.get(id);
+        if (pooled === undefined)
+            return undefined;
+        pooled.cancelled = true;
+        pooled.controller.abort();
+        const at = this.#queue.indexOf(pooled);
+        if (at === -1)
+            return undefined;
+        this.#queue.splice(at, 1);
+        this.#inflight.delete(id);
+        return pooled;
+    }
+    /** Stops every request. The ones that had not started are returned, to be answered. */
+    cancelAll() {
+        for (const pooled of this.#inflight.values()) {
+            pooled.cancelled = true;
+            pooled.controller.abort();
+        }
+        const waiting = this.#queue.splice(0);
+        for (const pooled of waiting)
+            this.#inflight.delete(pooled.request.id);
+        return waiting;
+    }
+    /** Resolves once no worker is running. */
+    idle() {
+        if (this.#running === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => { this.#idle.push(resolve); });
+    }
+}

package/serve/serve.use-case.d.ts

@@ -19,9 +19,13 @@ export declare function serve(plugin: SmithPlugin): Promise<never>;
  * or the input ends, then resolves. This is the loop {@link serve} runs, on
  * streams you choose: a test serves a plugin in-process over pipes with it.
  *
- * Semantics of the Go SDK's `serve.Serve`: requests are answered one at a time,
- * in order; a request before `initialize` is refused (InvalidRequest);
- * a notification (no `id`) gets no answer; an unreadable frame body is answered
- * with ParseError and the loop goes on; an unreadable header ends it with an error.
+ * Semantics of the Go SDK's `serve.Serve`: requests are answered by a bounded
+ * pool of as many at a time as the plugin declared in `concurrency` (one, in
+ * order, when it said nothing), and the answers may be written in any order;
+ * a request before `initialize` is refused (InvalidRequest); a notification
+ * (no `id`) gets no answer; an unreadable frame body is answered with
+ * ParseError and the loop goes on; an unreadable header ends it with an error.
+ * A `cancellable` plugin has the signal of a request aborted when the host
+ * sends `cancel` for it, and at shutdown or the end of the input.
  */
 export declare function serveStreams(plugin: SmithPlugin, streams: ServeStreams): Promise<void>;

package/serve/serve.use-case.js

@@ -1,9 +1,11 @@
-import { MessageParseError, parseRequest, writeFailure, writeResult } from '../codec/index.js';
+import { MessageParseError, ParamsError, decodeParams, parseRequest, writeFailure, writeResult } from '../codec/index.js';
+import { workerLimit } from '../concurrency/index.js';
 import { FrameReader, frameMessage } from '../framing/index.js';
 import { ERROR_CODES } from '../protocol/index.js';
 import { halfImplemented } from './capabilities-of.algorithm.js';
 import { claimStdout } from './claim-stdout.use-case.js';
 import { dispatchRequest } from './dispatch-request.use-case.js';
+import { RequestPool } from './request-pool.store.js';
 /**
  * Runs a plugin on the process's standard input and output, and exits when the
  * host sends `shutdown` or closes the stream. Use it as the whole body of the
@@ -36,10 +38,14 @@ export async function serve(plugin) {
  * or the input ends, then resolves. This is the loop {@link serve} runs, on
  * streams you choose: a test serves a plugin in-process over pipes with it.
  *
- * Semantics of the Go SDK's `serve.Serve`: requests are answered one at a time,
- * in order; a request before `initialize` is refused (InvalidRequest);
- * a notification (no `id`) gets no answer; an unreadable frame body is answered
- * with ParseError and the loop goes on; an unreadable header ends it with an error.
+ * Semantics of the Go SDK's `serve.Serve`: requests are answered by a bounded
+ * pool of as many at a time as the plugin declared in `concurrency` (one, in
+ * order, when it said nothing), and the answers may be written in any order;
+ * a request before `initialize` is refused (InvalidRequest); a notification
+ * (no `id`) gets no answer; an unreadable frame body is answered with
+ * ParseError and the loop goes on; an unreadable header ends it with an error.
+ * A `cancellable` plugin has the signal of a request aborted when the host
+ * sends `cancel` for it, and at shutdown or the end of the input.
  */
 export async function serveStreams(plugin, streams) {
     const log = streams.log ?? ((message) => process.stderr.write(`${message}\n`));
@@ -47,17 +53,27 @@ export async function serveStreams(plugin, streams) {
         log(`plugin: ${member} needs its pair (install with uninstall, declared with rewrite) to be advertised; it will not be called`);
     }
     const reader = new FrameReader();
-    const session = { initialized: false };
-    for await (const chunk of streams.input) {
-        for (const body of reader.push(chunk)) {
-            const shutdown = await answer(plugin, streams.output, session, body);
-            if (shutdown)
-                return;
+    const pool = new RequestPool(async (pooled) => { await run(session, pooled); });
+    const session = { initialized: false, plugin, output: streams.output, pool, cancellable: plugin.cancellable === true };
+    try {
+        for await (const chunk of streams.input) {
+            for (const body of reader.push(chunk)) {
+                if (pool.failure !== undefined)
+                    throw pool.failure;
+                const shutdown = await receive(session, body);
+                if (shutdown)
+                    return;
+            }
         }
     }
+    finally {
+        await drain(session);
+    }
+    if (pool.failure !== undefined)
+        throw pool.failure;
 }
-/** Answers one frame. Returns whether it was `shutdown`, after which the loop ends. */
-async function answer(plugin, output, session, body) {
+/** Handles one frame. Returns whether it was `shutdown`, after which the loop ends. */
+async function receive(session, body) {
     let request;
     try {
         request = parseRequest(body);
@@ -65,21 +81,92 @@ async function answer(plugin, output, session, body) {
     catch (error) {
         if (!(error instanceof MessageParseError))
             throw error;
-        await send(output, writeFailure(null, ERROR_CODES.ParseError, error.message));
+        await send(session.output, writeFailure(null, ERROR_CODES.ParseError, error.message));
         return false;
     }
-    // A notification has no reply; version 1 defines none for plugins.
-    if (request.id === null)
+    if (request.id === null) {
+        await notified(session, request);
         return false;
+    }
+    const id = request.id;
     if (!session.initialized && request.method !== 'initialize') {
-        await send(output, writeFailure(request.id, ERROR_CODES.InvalidRequest, 'initialize must come first'));
+        await send(session.output, writeFailure(id, ERROR_CODES.InvalidRequest, 'initialize must come first'));
+        return false;
+    }
+    if (request.method === 'initialize') {
+        const outcome = await dispatchRequest(session.plugin, request);
+        if (outcome.ok) {
+            session.initialized = true;
+            session.pool.setLimit(workerLimit(JSON.parse(outcome.resultJson).concurrency));
+        }
+        await send(session.output, outcome.ok ? writeResult(id, outcome.resultJson) : writeFailure(id, outcome.code, outcome.message));
         return false;
     }
-    const outcome = await dispatchRequest(plugin, request);
-    if (request.method === 'initialize' && outcome.ok)
-        session.initialized = true;
-    await send(output, outcome.ok ? writeResult(request.id, outcome.resultJson) : writeFailure(request.id, outcome.code, outcome.message));
-    return request.method === 'shutdown';
+    if (request.method === 'shutdown') {
+        // Everything read before shutdown, started or still waiting, is answered with its result first, as in the Go SDK; only a cancel message stops a request.
+        await session.pool.idle();
+        await send(session.output, writeResult(id, '{}'));
+        return true;
+    }
+    switch (session.pool.submit({ ...request, id })) {
+        case 'duplicate': {
+            await send(session.output, writeFailure(id, ERROR_CODES.InvalidRequest, `request id ${id} is already in flight`));
+            break;
+        }
+        case 'full': {
+            await send(session.output, writeFailure(id, ERROR_CODES.InvalidRequest, 'too many requests in flight: the host must not send more than the plugin\'s declared concurrency'));
+            break;
+        }
+        case 'admitted': {
+            break;
+        }
+    }
+    return false;
+}
+/**
+ * Handles a message without an `id`. `cancel` is the only one the protocol
+ * defines for a plugin; every other is ignored, and so is a `cancel` to a
+ * plugin that is not `cancellable`, or one that names no request.
+ */
+async function notified(session, request) {
+    if (request.method !== 'cancel' || !session.cancellable)
+        return;
+    let params;
+    try {
+        params = decodeParams('cancel', request.params);
+    }
+    catch (error) {
+        if (error instanceof ParamsError)
+            return;
+        throw error;
+    }
+    const waiting = session.pool.cancel(params.id);
+    if (waiting !== undefined)
+        await answerCancelled(session.output, waiting);
+}
+/** A worker's job: handle one request and answer it. */
+async function run(session, pooled) {
+    const outcome = await dispatchRequest(session.plugin, pooled.request, pooled.controller.signal);
+    const answer = !outcome.ok && outcome.code === ERROR_CODES.PluginFailure && pooled.cancelled
+        ? { ok: false, code: ERROR_CODES.RequestCancelled, message: `request cancelled: ${outcome.message}` }
+        : outcome;
+    session.pool.release(pooled);
+    await send(session.output, answer.ok ? writeResult(pooled.request.id, answer.resultJson) : writeFailure(pooled.request.id, answer.code, answer.message));
+}
+function answerCancelled(output, pooled) {
+    return send(output, writeFailure(pooled.request.id, ERROR_CODES.RequestCancelled, 'request cancelled before it started'));
+}
+/**
+ * Ends the work in flight when the loop returns (the input ended, the host is gone): a
+ * cancellable plugin is asked to stop and what had not started is refused;
+ * any other finishes what it is doing.
+ */
+async function drain(session) {
+    if (session.cancellable) {
+        for (const waiting of session.pool.cancelAll())
+            await answerCancelled(session.output, waiting);
+    }
+    await session.pool.idle();
 }
 function send(output, body) {
     return new Promise((resolve, reject) => {