@openbrf/plugin-sdk 0.0.0-stage → 1.2.0

package/dist/entitlements.d.ts

@@ -0,0 +1,117 @@
+/**
+ * What a paid plugin reads about its licence (ADR 0042).
+ *
+ * The host holds the licences the board entered and verifies them offline,
+ * against the keys the plugin's manifest declares and the instance's own id
+ * and key, on the association's calendar day. A plugin gets the finding and
+ * never the file, and decides for itself what it withholds without an active
+ * entitlement: the host loads and serves it either way.
+ */
+/** The version of the licence file format this contract reads. */
+export declare const LICENCE_FORMAT = "openbrf-licence/1";
+/** The version of the presentation format `present()` writes. */
+export declare const LICENCE_PRESENTATION_FORMAT = "openbrf-licence-presentation/1";
+/** The largest licence file the host accepts, in bytes. */
+export declare const LICENCE_FILE_MAX_BYTES = 16384;
+/** The largest presentation a service has to read, in bytes. */
+export declare const LICENCE_PRESENTATION_MAX_BYTES = 24576;
+/**
+ * The finding for the entitlement the manifest names, judged today.
+ *
+ * Dates are `YYYY-MM-DD` on the association's calendar day, and inclusive: a
+ * licence valid until a day is active through the whole of it.
+ *
+ * - `active`: a licence one of the plugin's keys verified names the
+ *   entitlement, is bound to this instance, and covers today and this release.
+ * - `absent`: no licence the plugin's keys verified names the entitlement.
+ * - `expired`: today is after its `validUntil`.
+ * - `version-not-covered`: this release was published after its
+ *   `updatesUntil`. An earlier release stays covered.
+ * - `wrong-instance`: it was issued to another instance, by id or by key.
+ * - `tampered`: it verified when it was entered and no longer does.
+ * - `not-yet-valid`: it was issued after today, which is a wrong clock on
+ *   one side or the other.
+ *
+ * Without an active licence the finding is that of the licence entered most
+ * recently, so a board that has just entered the wrong file is told about
+ * that file.
+ */
+export type EntitlementState = {
+    status: "active";
+    licenceId: string;
+    validUntil: string | null;
+    updatesUntil: string | null;
+} | {
+    status: "absent";
+} | {
+    status: "expired";
+    licenceId: string;
+    validUntil: string;
+} | {
+    status: "version-not-covered";
+    licenceId: string;
+    updatesUntil: string;
+    released: string;
+} | {
+    status: "wrong-instance";
+    licenceId: string;
+} | {
+    status: "tampered";
+} | {
+    status: "not-yet-valid";
+    licenceId: string;
+    issuedOn: string;
+};
+export type EntitlementStatus = EntitlementState["status"];
+export declare const ENTITLEMENT_STATUSES: readonly ["active", "absent", "expired", "version-not-covered", "wrong-instance", "tampered", "not-yet-valid"];
+/**
+ * A licensed plugin's view of its entitlement.
+ *
+ * Read on every call rather than once at boot, so a licence the board enters,
+ * one that ends, and the next one taking over all reach a running plugin
+ * without a restart.
+ */
+export interface PluginEntitlements {
+    /** The entitlement the manifest names, judged today. */
+    get(): Promise<EntitlementState>;
+    /**
+     * The active licence with a fresh signature by the instance key, for one of
+     * the audiences the manifest declares, as the text to send that service.
+     * Null without an active licence.
+     *
+     * Signed without a network call; sending it is the plugin's. A presentation
+     * is good at its audience for five minutes and once, so make one per
+     * request rather than keeping one.
+     *
+     * Throws a RangeError for an audience the manifest does not declare, since
+     * that is a defect in the plugin rather than a state of the licence.
+     */
+    present(audience: string): Promise<string | null>;
+}
+export interface TestEntitlementsOptions {
+    /** What `get()` answers. */
+    state: EntitlementState;
+    /** The manifest's `licence.audiences`. None by default. */
+    audiences?: readonly string[];
+    /** What `present()` answers while the state is active. */
+    presentation?: (audience: string) => string;
+}
+/**
+ * A stand-in for `host.entitlements` in a plugin's own tests.
+ *
+ * It answers with the state it was given and keeps the host's two rules about
+ * presenting: an undeclared audience is refused, and nothing is presented
+ * without an active licence. A plugin that wants to test the service end of a
+ * presentation signs licences with a throwaway key generated in the test;
+ * nothing here needs one.
+ */
+export declare function createTestEntitlements(options: TestEntitlementsOptions): PluginEntitlements & {
+    state: EntitlementState;
+};
+/**
+ * The refusal of an audience the manifest does not declare, worded once for
+ * the host and its test double. The audience is left out: it is whatever the
+ * plugin passed.
+ */
+export declare function undeclaredAudienceError(): RangeError;
+//# sourceMappingURL=entitlements.d.ts.map

package/dist/entitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../src/entitlements.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kEAAkE;AAClE,eAAO,MAAM,cAAc,sBAAsB,CAAC;AAElD,iEAAiE;AACjE,eAAO,MAAM,2BAA2B,mCAAmC,CAAC;AAE5E,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,gEAAgE;AAChE,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,GACD;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5D;IACE,MAAM,EAAE,qBAAqB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;AAE3D,eAAO,MAAM,oBAAoB,gHAQgB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,GAAG,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,KAAK,EAAE,gBAAgB,CAAC;IACxB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,0DAA0D;IAC1D,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CAC7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,kBAAkB,GAAG;IAAE,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAkBlD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,UAAU,CAKpD"}

package/dist/entitlements.js

@@ -0,0 +1,62 @@
+/**
+ * What a paid plugin reads about its licence (ADR 0042).
+ *
+ * The host holds the licences the board entered and verifies them offline,
+ * against the keys the plugin's manifest declares and the instance's own id
+ * and key, on the association's calendar day. A plugin gets the finding and
+ * never the file, and decides for itself what it withholds without an active
+ * entitlement: the host loads and serves it either way.
+ */
+/** The version of the licence file format this contract reads. */
+export const LICENCE_FORMAT = "openbrf-licence/1";
+/** The version of the presentation format `present()` writes. */
+export const LICENCE_PRESENTATION_FORMAT = "openbrf-licence-presentation/1";
+/** The largest licence file the host accepts, in bytes. */
+export const LICENCE_FILE_MAX_BYTES = 16_384;
+/** The largest presentation a service has to read, in bytes. */
+export const LICENCE_PRESENTATION_MAX_BYTES = 24_576;
+export const ENTITLEMENT_STATUSES = [
+    "active",
+    "absent",
+    "expired",
+    "version-not-covered",
+    "wrong-instance",
+    "tampered",
+    "not-yet-valid",
+];
+/**
+ * A stand-in for `host.entitlements` in a plugin's own tests.
+ *
+ * It answers with the state it was given and keeps the host's two rules about
+ * presenting: an undeclared audience is refused, and nothing is presented
+ * without an active licence. A plugin that wants to test the service end of a
+ * presentation signs licences with a throwaway key generated in the test;
+ * nothing here needs one.
+ */
+export function createTestEntitlements(options) {
+    const audiences = new Set(options.audiences ?? []);
+    const double = {
+        state: options.state,
+        get: () => Promise.resolve(double.state),
+        present: (audience) => {
+            if (!audiences.has(audience)) {
+                return Promise.reject(undeclaredAudienceError());
+            }
+            if (double.state.status !== "active") {
+                return Promise.resolve(null);
+            }
+            return Promise.resolve(options.presentation?.(audience) ?? `test-presentation:${audience}`);
+        },
+    };
+    return double;
+}
+/**
+ * The refusal of an audience the manifest does not declare, worded once for
+ * the host and its test double. The audience is left out: it is whatever the
+ * plugin passed.
+ */
+export function undeclaredAudienceError() {
+    return new RangeError("present() was asked for an audience the plugin's manifest does not " +
+        "declare under licence.audiences.");
+}
+//# sourceMappingURL=entitlements.js.map

package/dist/entitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.js","sourceRoot":"","sources":["../src/entitlements.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kEAAkE;AAClE,MAAM,CAAC,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAElD,iEAAiE;AACjE,MAAM,CAAC,MAAM,2BAA2B,GAAG,gCAAgC,CAAC;AAE5E,2DAA2D;AAC3D,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C,gEAAgE;AAChE,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAC;AA4CrD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,qBAAqB;IACrB,gBAAgB;IAChB,UAAU;IACV,eAAe;CACgC,CAAC;AAoClD;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAgC;IAEhC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG,EAAE,GAA8B,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;QACnE,OAAO,EAAE,CAAC,QAAgB,EAA0B,EAAE;YACpD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,OAAO,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,CAAC,CAAC;YACnD,CAAC;YACD,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACrC,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CACpB,OAAO,CAAC,YAAY,EAAE,CAAC,QAAQ,CAAC,IAAI,qBAAqB,QAAQ,EAAE,CACpE,CAAC;QACJ,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,UAAU,CACnB,qEAAqE;QACnE,kCAAkC,CACrC,CAAC;AACJ,CAAC"}

package/dist/extensions.d.ts

@@ -0,0 +1,183 @@
+import type { PluginAbortSignal } from "./abort-signal.ts";
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+/**
+ * Plugins that extend plugins (ADR 0030).
+ *
+ * An extension point (utökningspunkt) is a named slot a plugin declares in its
+ * manifest and offers to other plugins; that plugin is the point's host plugin.
+ * An addon (utökning) is a plugin that extends another at one of its points,
+ * and what it registers there is a contribution (bidrag): a title and a
+ * handler. Each is a plugin in every other respect, installed, consented to and
+ * switched on by itself, and neither receives the other's permissions.
+ *
+ * The host carries every call between them. It validates the input against the
+ * host plugin's schema before the call and the output after it, copies both as
+ * JSON values so that nothing but data crosses, and answers for what the addon
+ * did in the result rather than by throwing: a screen that loses one source
+ * should go on with the others.
+ *
+ * Swedish domain terms follow GLOSSARY.md.
+ */
+/**
+ * What an extension point id may look like, in the manifest and at the host.
+ *
+ * Lowercase letters, digits and single hyphens, two to thirty-two characters:
+ * the shape a plugin id has, shorter, because it is shown beside one.
+ */
+export declare const EXTENSION_POINT_ID_PATTERN: RegExp;
+/** How many points a plugin may declare, and how many an addon may extend. */
+export declare const MAX_EXTENSION_POINTS = 8;
+/** How long a contribution may take when its point names no time of its own. */
+export declare const EXTENSION_TIMEOUT_MS = 5000;
+/** The longest a point may give a contribution. */
+export declare const EXTENSION_MAX_TIMEOUT_MS = 15000;
+/**
+ * The longest answer a contribution may give, in characters of its JSON text.
+ * A longer one is `output-invalid`, refused before it is parsed or validated.
+ */
+export declare const EXTENSION_MAX_OUTPUT_LENGTH = 1048576;
+/**
+ * Why `invoke` answered without a value.
+ *
+ * Everything an addon can do wrong, and the one state the host plugin cannot
+ * see from its own side, so a host plugin can tell a broken addon from one that
+ * is switched off without either being thrown at it.
+ */
+export declare const EXTENSION_RESULT_REASONS: readonly [
+/**
+ * The addon is not installed, not loaded, switched off, or has registered no
+ * contribution at this point.
+ */
+"not-serving", 
+/**
+ * The handler did not answer in time. Its signal was aborted.
+ *
+ * The time bounds only how long the host waits for the handler's promise.
+ * Work the handler does synchronously, and a `toJSON` or getter in its
+ * answer, runs on the host's one thread with no limit, as any plugin code
+ * does: a handler that loops stalls the instance.
+ */
+"timed-out", 
+/** The handler threw. What it threw is in the server log, never here. */
+"failed", 
+/**
+ * The answer does not meet the point's output schema, has no JSON form, or
+ * is longer than EXTENSION_MAX_OUTPUT_LENGTH as JSON.
+ */
+"output-invalid"];
+export type ExtensionResultReason = (typeof EXTENSION_RESULT_REASONS)[number];
+/** What the host plugin hands `define` for one point its manifest declares. */
+export interface ExtensionPointDefinition<Input = unknown, Output = unknown> {
+    /**
+     * What the host plugin sends a contribution. A strict object at every depth,
+     * built with the host's zod, with no record, catchall, `unknown` or `any`
+     * anywhere inside it.
+     */
+    readonly input: StandardSchemaV1<unknown, Input>;
+    /**
+     * What a contribution must answer. A strict object at every depth, built with
+     * the host's zod, with no record, catchall, `unknown` or `any` anywhere inside
+     * it: a key the schema does not name is a key an addon could hand over
+     * something nobody consented to in.
+     */
+    readonly output: StandardSchemaV1<unknown, Output>;
+    /**
+     * How long a contribution may take, in milliseconds.
+     * EXTENSION_TIMEOUT_MS by default, at most EXTENSION_MAX_TIMEOUT_MS.
+     */
+    readonly timeoutMs?: number;
+}
+/** What the host tells a contribution about the call it is answering. */
+export interface ExtensionContext {
+    /** The plugin whose point is being answered. */
+    readonly hostPlugin: string;
+    readonly point: string;
+    /** The point's major version, which is the one the addon named. */
+    readonly version: number;
+    /** For the logs, so a call can be followed from one plugin to the other. */
+    readonly requestId: string;
+    readonly now: Date;
+    /** Aborted when the call times out or the host plugin gives up on it. */
+    readonly signal: PluginAbortSignal;
+}
+/** What an addon hands `contribute` for one point its manifest extends. */
+export interface ExtensionContributionDefinition<Input = unknown, Output = unknown> {
+    /**
+     * A bare key in the addon's own namespace, as an action's is. The host
+     * qualifies it as `plugin-<addon>:<key>`.
+     */
+    readonly titleKey: string;
+    readonly descriptionKey?: string;
+    /**
+     * Answers one call.
+     *
+     * Runs with the addon's own host object, under the permissions the board
+     * consented to for the addon, and with no person behind it: an extension
+     * point is a call from one plugin to another, not somebody's request. It
+     * must accept input fields it does not know, because a host plugin may add
+     * an optional field to a point without raising its version.
+     */
+    readonly handler: (input: Input, context: ExtensionContext) => Promise<Output>;
+}
+/** One contribution that is serving at a point, as its host plugin sees it. */
+export interface ExtensionContributionSummary {
+    /** The addon's plugin id, which `invoke` takes. */
+    readonly addon: string;
+    /** Qualified into the addon's namespace, `plugin-<addon>:<key>`. */
+    readonly titleKey: string;
+    readonly descriptionKey: string | null;
+}
+/** What `invoke` answers: a value, or why there is none. */
+export type ExtensionResult<Output> = {
+    readonly ok: true;
+    readonly value: Output;
+} | {
+    readonly ok: false;
+    readonly reason: ExtensionResultReason;
+};
+/** The plugin and the point an addon contributes to. */
+export interface ExtensionTarget {
+    readonly plugin: string;
+    readonly point: string;
+}
+/**
+ * Extension points, as a plugin sees them.
+ *
+ * A host plugin uses `define`, `list` and `invoke`; an addon uses
+ * `contribute`. `define` and `contribute` are declarations, callable from the
+ * module factory onwards and buffered until the application exists, as
+ * `host.actions.register` is. A definition or contribution the host cannot
+ * accept - a point or target the manifest does not declare, a schema that is
+ * not a strict object built with the host's zod, a second one for the same
+ * point - is found when the buffer is flushed and stops the plugin with
+ * `extension-refused`, rather than throwing here.
+ *
+ * `list` and `invoke` keep the ordinary gate and work from `onModuleInit`
+ * onwards.
+ */
+export interface PluginExtensions {
+    /** Host plugin: the schemas of a point its manifest declares. */
+    define<Input, Output>(point: string, definition: ExtensionPointDefinition<Input, Output>): void;
+    /**
+     * Host plugin: the contributions to one of its points that are serving now,
+     * in addon id order.
+     *
+     * Throws for a point the manifest does not declare or the plugin has not
+     * defined.
+     */
+    list(point: string): Promise<readonly ExtensionContributionSummary[]>;
+    /**
+     * Host plugin: calls one addon's contribution.
+     *
+     * Throws for a mistake of the host plugin's own: a point its manifest does
+     * not declare or it has not defined, or an input its own schema refuses. An
+     * aborted `signal` rejects with the signal's reason. Everything the addon
+     * does is answered in the result.
+     */
+    invoke<Output>(point: string, addon: string, input: unknown, options?: {
+        signal?: PluginAbortSignal;
+    }): Promise<ExtensionResult<Output>>;
+    /** Addon: the handler for a point its manifest extends. Once per point. */
+    contribute<Input, Output>(target: ExtensionTarget, contribution: ExtensionContributionDefinition<Input, Output>): void;
+}
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAkC,CAAC;AAE1E,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,2BAA2B,UAAY,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;AACnC;;;GAGG;AACH,aAAa;AACb;;;;;;;GAOG;AACH,WAAW;AACX,yEAAyE;AACzE,QAAQ;AACR;;;GAGG;AACH,gBAAgB,CACR,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO;IACzE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED,2EAA2E;AAC3E,MAAM,WAAW,+BAA+B,CAC9C,KAAK,GAAG,OAAO,EACf,MAAM,GAAG,OAAO;IAEhB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,CAChB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,4BAA4B;IAC3C,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,4DAA4D;AAC5D,MAAM,MAAM,eAAe,CAAC,MAAM,IAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEnE,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,MAAM,CAAC,KAAK,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC,GAClD,IAAI,CAAC;IAER;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,4BAA4B,EAAE,CAAC,CAAC;IAEtE;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;KAAE,GACvC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IAEpC,2EAA2E;IAC3E,UAAU,CAAC,KAAK,EAAE,MAAM,EACtB,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,+BAA+B,CAAC,KAAK,EAAE,MAAM,CAAC,GAC3D,IAAI,CAAC;CACT"}

package/dist/extensions.js

@@ -0,0 +1,67 @@
+/**
+ * Plugins that extend plugins (ADR 0030).
+ *
+ * An extension point (utökningspunkt) is a named slot a plugin declares in its
+ * manifest and offers to other plugins; that plugin is the point's host plugin.
+ * An addon (utökning) is a plugin that extends another at one of its points,
+ * and what it registers there is a contribution (bidrag): a title and a
+ * handler. Each is a plugin in every other respect, installed, consented to and
+ * switched on by itself, and neither receives the other's permissions.
+ *
+ * The host carries every call between them. It validates the input against the
+ * host plugin's schema before the call and the output after it, copies both as
+ * JSON values so that nothing but data crosses, and answers for what the addon
+ * did in the result rather than by throwing: a screen that loses one source
+ * should go on with the others.
+ *
+ * Swedish domain terms follow GLOSSARY.md.
+ */
+/**
+ * What an extension point id may look like, in the manifest and at the host.
+ *
+ * Lowercase letters, digits and single hyphens, two to thirty-two characters:
+ * the shape a plugin id has, shorter, because it is shown beside one.
+ */
+export const EXTENSION_POINT_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** How many points a plugin may declare, and how many an addon may extend. */
+export const MAX_EXTENSION_POINTS = 8;
+/** How long a contribution may take when its point names no time of its own. */
+export const EXTENSION_TIMEOUT_MS = 5_000;
+/** The longest a point may give a contribution. */
+export const EXTENSION_MAX_TIMEOUT_MS = 15_000;
+/**
+ * The longest answer a contribution may give, in characters of its JSON text.
+ * A longer one is `output-invalid`, refused before it is parsed or validated.
+ */
+export const EXTENSION_MAX_OUTPUT_LENGTH = 1_048_576;
+/**
+ * Why `invoke` answered without a value.
+ *
+ * Everything an addon can do wrong, and the one state the host plugin cannot
+ * see from its own side, so a host plugin can tell a broken addon from one that
+ * is switched off without either being thrown at it.
+ */
+export const EXTENSION_RESULT_REASONS = [
+    /**
+     * The addon is not installed, not loaded, switched off, or has registered no
+     * contribution at this point.
+     */
+    "not-serving",
+    /**
+     * The handler did not answer in time. Its signal was aborted.
+     *
+     * The time bounds only how long the host waits for the handler's promise.
+     * Work the handler does synchronously, and a `toJSON` or getter in its
+     * answer, runs on the host's one thread with no limit, as any plugin code
+     * does: a handler that loops stalls the instance.
+     */
+    "timed-out",
+    /** The handler threw. What it threw is in the server log, never here. */
+    "failed",
+    /**
+     * The answer does not meet the point's output schema, has no JSON form, or
+     * is longer than EXTENSION_MAX_OUTPUT_LENGTH as JSON.
+     */
+    "output-invalid",
+];
+//# sourceMappingURL=extensions.js.map

package/dist/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,+BAA+B,CAAC;AAE1E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C,mDAAmD;AACnD,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,SAAS,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC;;;OAGG;IACH,aAAa;IACb;;;;;;;OAOG;IACH,WAAW;IACX,yEAAyE;IACzE,QAAQ;IACR;;;OAGG;IACH,gBAAgB;CACR,CAAC"}