@coda-console/plugin-check 0.8.22 → 0.8.24
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/check/coda/adapters/plugin-command.mjs +5 -4
- package/check/coda/adapters/plugin-events.mjs +38 -0
- package/check/coda/adapters/plugin-modules.mjs +21 -9
- package/check/coda/adapters/plugin-test-host.d.mts +51 -2
- package/check/coda/adapters/plugin-test-host.mjs +50 -17
- package/check/coda/application/host-protocols.mjs +17 -0
- package/check/coda/builtin.json +1143 -78
- package/check/coda/components/plugins/plugin-extensions.mjs +46 -5
- package/check/coda/components/plugins/plugin-rules.mjs +41 -6
- package/check/coda/components/plugins/plugin-source-rules.mjs +16 -4
- package/check/coda/components/protocols/protocol-events.mjs +49 -0
- package/check/coda/components/workflows/contributions.mjs +2 -2
- package/check/coda/components/workflows/workflow-protocol-definitions.mjs +362 -0
- package/check/coda/contract.json +18 -11
- package/check/coda/kernel/plugin-protocol.mjs +56 -0
- package/check/coda/kernel/project-protocol.mjs +52 -0
- package/check/coda/kernel/thread-protocol.mjs +167 -0
- package/check/manifest.mjs +24 -2
- package/package.json +2 -2
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// The one runner of a plugin's commands (docs/plugins.md「命令的约定」):
|
|
1
|
+
// The one runner of a plugin's commands (docs/plugins.md「命令的约定」): the operations its commands implement
|
|
2
2
|
// (components/plugins/plugin-host.mjs `startCommand`), its resources' readings and actions,
|
|
3
3
|
// their logins and installers, its setup; and, bounded the same way, the programs Coda runs for a plugin itself (Git taking a
|
|
4
4
|
// plugin from its repository, components/plugins/plugin-sources.mjs; a repository's listing; what a plugin tells agents).
|
|
@@ -54,10 +54,11 @@ export const runBounded = (program, args, options) => startBounded(program, args
|
|
|
54
54
|
export const fileCommand = file => `./'${posix.normalize(file).replaceAll("'", "'\\''")}'`;
|
|
55
55
|
// What a command implementing an operation is told of its call in its environment, as a module's handler is in its `ctx`
|
|
56
56
|
// (docs/plugins.md「用命令实现操作」): its record (`ctx.record`, its key only of one its plugin holds here), its ID (`ctx.id`)
|
|
57
|
-
// and, when it has one, its deadline (`ctx.deadline`, milliseconds).
|
|
58
|
-
export const callEnv = ({ id, record, deadline }) => ({ CODA_RECORD_KIND: record.kind, CODA_RECORD_ID: record.id,
|
|
57
|
+
// and, when it has one, its deadline (`ctx.deadline`, milliseconds); made from a page, who is before it (`ctx.caller`, JSON).
|
|
58
|
+
export const callEnv = ({ id, record, deadline, caller }) => ({ CODA_RECORD_KIND: record.kind, CODA_RECORD_ID: record.id,
|
|
59
59
|
...(record.key === undefined ? {} : { CODA_RECORD_KEY: record.key }), CODA_CALL_ID: id,
|
|
60
|
-
...(deadline === null || deadline === undefined ? {} : { CODA_DEADLINE: String(deadline) })
|
|
60
|
+
...(deadline === null || deadline === undefined ? {} : { CODA_DEADLINE: String(deadline) }),
|
|
61
|
+
...(caller ? { CODA_CALLER: JSON.stringify(caller) } : {}) });
|
|
61
62
|
// A query's ID, as its handler is given it (`ctx.id`, adapters/plugin-modules.mjs): of its caller and its request's.
|
|
62
63
|
export const queryId = request => derivedUUID('query', request.parent, request.requestId);
|
|
63
64
|
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// A module's events (docs/plugins.md「事件」), as its `coda` has them (adapters/plugin-modules.mjs): `emit` publishes one of a
|
|
2
|
+
// protocol its plugin defines or implements, through the backend, which knows the plugin by the module's token (`asks`);
|
|
3
|
+
// `on` handles one its plugin subscribes to (`plugin.events`, the events of the event groups it uses, as the backend reckons
|
|
4
|
+
// them: components/plugins/plugin-events.mjs `subscribed`), as the backend delivers it (`deliver`). A handler that throws
|
|
5
|
+
// is said in the log, and is not handed the event again.
|
|
6
|
+
import { codaError } from './provider-api.mjs';
|
|
7
|
+
|
|
8
|
+
export function pluginEvents(plugin, asks, fire) {
|
|
9
|
+
const subscribed = new Set(plugin.events ?? []), handlers = new Map();
|
|
10
|
+
return {
|
|
11
|
+
api: {
|
|
12
|
+
// `emit(name, data, { subject, project })`: published once the backend has checked it, what is handed on after not
|
|
13
|
+
// waited for; refused with its code, nothing published.
|
|
14
|
+
async emit(name, data, { subject, project } = {}) {
|
|
15
|
+
if (typeof name !== 'string' || typeof subject !== 'string' || typeof project !== 'string') throw new TypeError('emit(事件名, data, { subject, project })');
|
|
16
|
+
await asks('emit', { name, data, subject, project });
|
|
17
|
+
},
|
|
18
|
+
// `on(name, fn)`: `fn` given each event of the name delivered (`{ name, kind, subject, project, data, publisher }`)
|
|
19
|
+
// until it is disposed, or the module stops.
|
|
20
|
+
on(name, fn) {
|
|
21
|
+
if (typeof name !== 'string' || typeof fn !== 'function') throw new TypeError('on(事件名, fn)');
|
|
22
|
+
if (!subscribed.has(name)) throw codaError('forbidden', `插件 ${plugin.id} 没有订事件 ${name}:须在清单的 uses 里写含有它的事件组`, { effects: 'none' });
|
|
23
|
+
// Each its own, however often the same `fn` is.
|
|
24
|
+
const entry = { fn, disposed: false };
|
|
25
|
+
if (!handlers.has(name)) handlers.set(name, new Set());
|
|
26
|
+
handlers.get(name).add(entry);
|
|
27
|
+
return { dispose: () => { entry.disposed = true; handlers.get(name)?.delete(entry); } };
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
// An event the backend delivers: to each handler of its name as it comes, once, but one disposed meanwhile; not to one
|
|
31
|
+
// added meanwhile.
|
|
32
|
+
deliver(event) {
|
|
33
|
+
for (const entry of [...handlers.get(event?.name) ?? []]) if (!entry.disposed) fire([entry.fn], event);
|
|
34
|
+
},
|
|
35
|
+
// The module stopped: its handlers go.
|
|
36
|
+
clear() { handlers.clear(); },
|
|
37
|
+
};
|
|
38
|
+
}
|
|
@@ -8,13 +8,14 @@
|
|
|
8
8
|
// `open { instance, plugin, view, context, caller }`, `query { plugin, request, deadline }`, `run { plugin, call }` and
|
|
9
9
|
// `resume { plugin, call }`, and `cancel { id, reason }` of any of them, `mode { plugin, mode, hook, context }` (a request
|
|
10
10
|
// each), and `message`, `callProgress { id, value }` (a `call`'s progress, by the request's ID), `context`, `close { instance, … }`, `changed { watch, events }`, `settingsChanged { plugin,
|
|
11
|
-
// settings }` (a notice, no answer: the plugin's own settings, as `Plugins.setSettings` wrote them),
|
|
11
|
+
// settings }` (a notice, no answer: the plugin's own settings, as `Plugins.setSettings` wrote them), `event { plugin, event }`
|
|
12
|
+
// (a notice: an event it subscribes to, adapters/plugin-events.mjs), and `output`, `exited`
|
|
12
13
|
// of a process it started (adapters/process-relay.mjs). To it: `post { instance, message }`, `change { instance,
|
|
13
14
|
// collection, type, id, object }`, `unwatch { watch }`, `cancel { id }` of a `query` or a `question`, `progress { run,
|
|
14
15
|
// value }` of a `run`, `drained`, `kill` of a process, and the requests `environment { of, project }`, `settings`
|
|
15
16
|
// (the plugin's own, as they are now), `watch { collection, selector }`, `tell { session, text }`, `part { part, method,
|
|
16
17
|
// args }`, `provider { method, args }`, `serviceRegister { id, port, secret }`, `serviceUnregister { id }`, `query { record,
|
|
17
|
-
// operation, input, timeout, deadline }`, `call { record, operation, input, id, timeout, deadline, under, progress }`, `spawn { under, process, command, args, cwd, env, name }`, each with the
|
|
18
|
+
// operation, input, timeout, deadline }`, `emit { name, data, subject, project }`, `call { record, operation, input, id, timeout, deadline, under, progress }`, `spawn { under, process, command, args, cwd, env, name }`, each with the
|
|
18
19
|
// module's `token`, by which the backend knows the plugin it is of, never by what it names; and `question { run,
|
|
19
20
|
// question }` and `input` of a process. A query's
|
|
20
21
|
// failure crosses as `failureOf` says it, as one that did nothing (`none`); a run's end, and a resume's, as its outcome, or a resume's as null when the
|
|
@@ -25,6 +26,7 @@ import { pluginServices } from './plugin-stream-services.mjs';
|
|
|
25
26
|
import { pathToFileURL } from 'node:url';
|
|
26
27
|
import { callingAPI, canceled, codaError, failed, failureOf, givenUp, providerAPI, queryingAPI } from './provider-api.mjs';
|
|
27
28
|
import { queryId } from './plugin-command.mjs';
|
|
29
|
+
import { pluginEvents } from './plugin-events.mjs';
|
|
28
30
|
|
|
29
31
|
export function pluginModules({ send }) {
|
|
30
32
|
// This machine's Coda, as `start` gives it: its address only. Each module reaches it with its own plugin's token, given
|
|
@@ -40,10 +42,11 @@ export function pluginModules({ send }) {
|
|
|
40
42
|
// What a handler of a call is given beside its input (coda#2749 3.1): the call's ID, its record, its `signal`, which goes
|
|
41
43
|
// off as the backend calls it off, its `deadline` (milliseconds on the backend's clock, or none), `query`, queries made
|
|
42
44
|
// under it, and `spawn`, processes started for it, the backend's request `under` which the call came; a doing call's
|
|
43
|
-
// handler (`run`, `resume`), `call` too, doing calls it makes (`doingOf`).
|
|
45
|
+
// handler (`run`, `resume`), `call` too, doing calls it makes, and, made from a page, `caller`, who is before it (`doingOf`).
|
|
44
46
|
const contextOf = ({ id, record, deadline }, signal, { querying, spawnFor }, under) =>
|
|
45
47
|
({ id, record, signal, deadline, query: querying.within(signal, deadline), spawn: spawnFor(under, signal) });
|
|
46
|
-
const doingOf = (call, signal, made, under) => ({ ...contextOf(call, signal, made, under), call: made.calling.within(signal, call.deadline, under)
|
|
48
|
+
const doingOf = (call, signal, made, under) => ({ ...contextOf(call, signal, made, under), call: made.calling.within(signal, call.deadline, under),
|
|
49
|
+
...(call.caller ? { caller: call.caller } : {}) });
|
|
47
50
|
// The processes the modules started through the backend (`spawn`), by the key this host gave each, until they have
|
|
48
51
|
// exited or the host stops.
|
|
49
52
|
const processes = new Map();
|
|
@@ -205,6 +208,8 @@ export function pluginModules({ send }) {
|
|
|
205
208
|
const environment = (project = null, options = {}) => asks('environment', { of: options?.plugin ?? null, project });
|
|
206
209
|
// The listeners of `settings.onChange`: this plugin's own settings only, told as they are written.
|
|
207
210
|
const settingsChanges = new Set();
|
|
211
|
+
// The events it publishes and those it subscribes to (adapters/plugin-events.mjs).
|
|
212
|
+
const events = pluginEvents(plugin, asks, fire);
|
|
208
213
|
// A query through the backend's unified call, the caller this plugin by its token.
|
|
209
214
|
const querying = queryingAPI({ send: (request, signal) => asks('query', request, signal), plugin, operations });
|
|
210
215
|
// A doing call through the call kernel, from this plugin's address (docs/plugins.md「做事的调用」).
|
|
@@ -285,8 +290,10 @@ export function pluginModules({ send }) {
|
|
|
285
290
|
// Coda's own collections, as a page watches the module's (`threads`: the sessions this machine lists), or a kind's
|
|
286
291
|
// records by its protocol's name.
|
|
287
292
|
watch: watching,
|
|
293
|
+
// Events (docs/plugins.md「事件」): `emit` one of its plugin's protocols, `on` one it subscribes to.
|
|
294
|
+
...events.api,
|
|
288
295
|
});
|
|
289
|
-
return { coda, views, protocols, operations, services, querying, calling, spawnFor, settingsChanges };
|
|
296
|
+
return { coda, views, protocols, operations, services, querying, calling, spawnFor, settingsChanges, events };
|
|
290
297
|
}
|
|
291
298
|
|
|
292
299
|
// Loaded once, as the backend activates it (`activate`, the first time anything of it is needed); what else comes for it
|
|
@@ -392,7 +399,7 @@ export function pluginModules({ send }) {
|
|
|
392
399
|
} finally { cancels.delete(id); }
|
|
393
400
|
},
|
|
394
401
|
// A doing call of a protocol the plugin implements (docs/plugins.md「做事的操作」), as the backend hosts it
|
|
395
|
-
// (components/plugins/hosted-calls.mjs): `call` is `{ id, ref, record, operation, input, deadline }`, `ref` the call's on the call
|
|
402
|
+
// (components/plugins/hosted-calls.mjs): `call` is `{ id, ref, record, operation, input, deadline, caller? }`, `ref` the call's on the call
|
|
396
403
|
// kernel (`{ from, id }`), which the doing calls its handler makes are made by. Its handler is given
|
|
397
404
|
// besides `progress`, said to the backend as it comes, and `ask`, answered as the backend passes the answer on (one at
|
|
398
405
|
// a time, as the backend has it: components/plugins/hosted-calls.mjs `question`). It ends with the call's outcome (`ending`). Not handled, nothing was done.
|
|
@@ -415,7 +422,7 @@ export function pluginModules({ send }) {
|
|
|
415
422
|
});
|
|
416
423
|
},
|
|
417
424
|
// A doing call left by a host process that ended before its handler did (coda#2749 3.6), handed to its operation's
|
|
418
|
-
// `resume` in this one: `call` is `{ id, ref, record, operation, input, deadline, progress, canceled, halted }`, `halted`
|
|
425
|
+
// `resume` in this one: `call` is `{ id, ref, record, operation, input, deadline, caller?, progress, canceled, halted }`, `halted`
|
|
419
426
|
// why its `ctx.signal` has gone off already (asked to be cancelled, or past its deadline, as `cancel`'s reason
|
|
420
427
|
// crosses), or none. `resume` is given the call as `Interrupted` and a `ctx` as a query's handler is with `call`, and ends it as
|
|
421
428
|
// `run` does; with none, null, for the backend to end it as it does then. Its `ctx.call` makes calls as the call's, as `run`'s
|
|
@@ -449,6 +456,11 @@ export function pluginModules({ send }) {
|
|
|
449
456
|
const made = await loading.get(plugin)?.catch(() => null);
|
|
450
457
|
if (made) fire(made.settingsChanges, settings);
|
|
451
458
|
},
|
|
459
|
+
// An event the plugin subscribes to (`coda.on`), as the backend delivers it to a module activated already.
|
|
460
|
+
async event({ plugin, event }) {
|
|
461
|
+
const made = await loading.get(plugin)?.catch(() => null);
|
|
462
|
+
made?.events.deliver(event);
|
|
463
|
+
},
|
|
452
464
|
close({ instance }) {
|
|
453
465
|
const shown = instances.get(instance);
|
|
454
466
|
if (shown) { instances.delete(instance); fire(shown.listeners.close); }
|
|
@@ -491,8 +503,8 @@ export function pluginModules({ send }) {
|
|
|
491
503
|
let stopping = null;
|
|
492
504
|
const stop = () => stopping ??= Promise.allSettled([...processes.values()].map(entry => entry.interrupt())
|
|
493
505
|
.concat([...loading.values()].map(async loaded => {
|
|
494
|
-
const { module, services, settingsChanges } = await loaded;
|
|
495
|
-
settingsChanges.clear();
|
|
506
|
+
const { module, services, settingsChanges, events } = await loaded;
|
|
507
|
+
settingsChanges.clear(); events.clear();
|
|
496
508
|
await services.close(false);
|
|
497
509
|
if (typeof module?.deactivate === 'function') await module.deactivate();
|
|
498
510
|
})));
|
|
@@ -45,6 +45,9 @@ export interface CallOptions {
|
|
|
45
45
|
onProgress?(value: Json): void;
|
|
46
46
|
}
|
|
47
47
|
|
|
48
|
+
/** Who is before the page that made a doing call: Coda's own client on this machine, or a device, with its name if known. */
|
|
49
|
+
export type Caller = { local: true } | { device: string; name?: string };
|
|
50
|
+
|
|
48
51
|
/** What a handler of a call is given beside its input. A handler of a query, and `resume`, have no `progress` nor `ask`. */
|
|
49
52
|
export interface Context {
|
|
50
53
|
/** This call's ID, the host's, unique: the same for the same caller's same request. */
|
|
@@ -75,6 +78,11 @@ export interface Context {
|
|
|
75
78
|
* made before the process ended, its outcome waited on again.
|
|
76
79
|
*/
|
|
77
80
|
call?: Coda['call'];
|
|
81
|
+
/**
|
|
82
|
+
* A doing call's, made from a plugin's page: who is before that page, as Coda knows it, never as the page says. None
|
|
83
|
+
* for a call a module (`coda.call`), a command (`coda call`) or a flow makes.
|
|
84
|
+
*/
|
|
85
|
+
caller?: Caller;
|
|
78
86
|
}
|
|
79
87
|
|
|
80
88
|
/** Its return value is the result; what it throws, the failure (`coda.error`, or anything else as `handler_error`). */
|
|
@@ -179,6 +187,22 @@ export interface RecordFilter { scope?: 'local' | 'available'; id?: string }
|
|
|
179
187
|
/** A record read anew, made or gone: by its ID, as it is now, or as it was last. */
|
|
180
188
|
export interface RecordChange { type: 'ADDED' | 'MODIFIED' | 'DELETED'; id: string; entry: Entry }
|
|
181
189
|
|
|
190
|
+
/** An event, as a module's handler of it is given it (`coda.on`). */
|
|
191
|
+
export interface Event {
|
|
192
|
+
/** Its name, the full dotted one (`pull_request.closed`), one on this machine. */
|
|
193
|
+
name: string;
|
|
194
|
+
/** The protocol it is of, with its major version (`github/pull-request@1`): the event's version. */
|
|
195
|
+
kind: string;
|
|
196
|
+
/** What it is about, `<kind>:<id>`. */
|
|
197
|
+
subject: string;
|
|
198
|
+
/** The ID of the project of this machine it was published in. */
|
|
199
|
+
project: string;
|
|
200
|
+
/** What it says, as its protocol's payload schema has it. */
|
|
201
|
+
data: { [key: string]: Json };
|
|
202
|
+
/** The ID of the plugin that published it; `coda` for Coda's own. */
|
|
203
|
+
publisher: string;
|
|
204
|
+
}
|
|
205
|
+
|
|
182
206
|
export interface Coda {
|
|
183
207
|
/** Handles an operation of a protocol the plugin implements: a query (`safe`) or a doing call (any other, `idempotent` among them). */
|
|
184
208
|
handle(kind: string, operation: string, handler: Handler | { run: Handler; resume?: Resume }): Disposable;
|
|
@@ -235,6 +259,18 @@ export interface Coda {
|
|
|
235
259
|
* the entries given, in their order.
|
|
236
260
|
*/
|
|
237
261
|
replace(kind: string, entries: (RecordValue & { key: string })[]): Promise<Entry[]>;
|
|
262
|
+
/**
|
|
263
|
+
* Publishes an event of a protocol the plugin defines or implements, not one of Coda's own (those only Coda publishes),
|
|
264
|
+
* about `subject` in `project` (a project of this machine, by ID, the plugin applying there): done once Coda has checked
|
|
265
|
+
* it, its delivery not waited for; refused (`invalid_input`), nothing was published.
|
|
266
|
+
*/
|
|
267
|
+
emit(name: string, data: { [key: string]: Json }, options: { subject: string; project: string }): Promise<void>;
|
|
268
|
+
/**
|
|
269
|
+
* Handles an event the plugin subscribes to: one of an event group in its `uses`, any other throwing at once (`forbidden`).
|
|
270
|
+
* Given each one published in a project the plugin applies in, at most once, while the module is activated; not sorted by
|
|
271
|
+
* subject. What it throws is logged; the event is not given again.
|
|
272
|
+
*/
|
|
273
|
+
on(name: string, fn: (event: Event) => void): Disposable;
|
|
238
274
|
}
|
|
239
275
|
|
|
240
276
|
/** A protocol a plugin implements, some of its operations by commands: operation name to the file that implements it. */
|
|
@@ -255,12 +291,14 @@ export interface TestPlugin {
|
|
|
255
291
|
* or `{ kind, commands }`, the operations in `commands` each implemented by a file of the plugin's (its path from `path`),
|
|
256
292
|
* the rest its module's. Such a command is run as Coda runs it, its call in its environment as its `ctx` has it
|
|
257
293
|
* (`CODA_RECORD_KIND`, `CODA_RECORD_ID`, `CODA_RECORD_KEY` of a record the plugin holds, `CODA_CALL_ID`, `CODA_DEADLINE`
|
|
258
|
-
* when it has one), but with no token: `coda progress`, `coda ask`, `coda query` and `coda self` in it are not answered
|
|
294
|
+
* when it has one, `CODA_CALLER`, the `caller` as JSON, when it has one), but with no token: `coda progress`, `coda ask`, `coda query` and `coda self` in it are not answered
|
|
259
295
|
* by the test host.
|
|
260
296
|
*/
|
|
261
297
|
protocolImplementations?: (string | ProtocolImplementation)[];
|
|
262
298
|
/** The names of the processes it declares (`contributes.processes`): a named `spawn` of any other fails (`not_found`). */
|
|
263
299
|
processes?: string[];
|
|
300
|
+
/** The permission groups it uses (`uses`), by protocol: its event groups are the events its `coda.on` may name. */
|
|
301
|
+
uses?: Record<string, string[]>;
|
|
264
302
|
}
|
|
265
303
|
|
|
266
304
|
export interface TestCallOptions extends QueryOptions {
|
|
@@ -268,6 +306,8 @@ export interface TestCallOptions extends QueryOptions {
|
|
|
268
306
|
onProgress?(value: Json): void;
|
|
269
307
|
/** Answers a doing call's question (`ctx.ask`); without it, the question fails. */
|
|
270
308
|
answer?(question: Json): Json | Promise<Json>;
|
|
309
|
+
/** A doing call's: made from a page this caller is before (`ctx.caller`, `CODA_CALLER`); without it, as a module's call. */
|
|
310
|
+
caller?: Caller;
|
|
271
311
|
}
|
|
272
312
|
|
|
273
313
|
export interface TestHost {
|
|
@@ -290,9 +330,16 @@ export interface TestHost {
|
|
|
290
330
|
* `ctx.deadline`) or none: `canceled`, or the deadline past by the host's clock, its `ctx.signal` has gone off already
|
|
291
331
|
* (`AbortError`, `TimeoutError`); its result, or its failure; with no `resume`, an `interrupted` failure of unknown effect.
|
|
292
332
|
*/
|
|
293
|
-
resume(record: Ref, operation: string, call?: { id?: string; input?: Json; progress?: Json | null; canceled?: boolean; deadline?: number | null }): Promise<Json>;
|
|
333
|
+
resume(record: Ref, operation: string, call?: { id?: string; input?: Json; progress?: Json | null; canceled?: boolean; deadline?: number | null; caller?: Caller }): Promise<Json>;
|
|
294
334
|
/** Writes the plugin's settings again, as the backend does: `coda.settings.get` gives them, and `onChange` is told. */
|
|
295
335
|
setSettings(settings: Json): Promise<void>;
|
|
336
|
+
/** Delivers an event to the module as Coda does: to its handlers of the name (`coda.on`) now. */
|
|
337
|
+
emit(event: Event): Promise<void>;
|
|
338
|
+
/**
|
|
339
|
+
* The events the module published (`coda.emit`), in order, each checked as Coda checks it but for its project: of a
|
|
340
|
+
* protocol the plugin defines or implements, not one of Coda's own, as its payload schema has it.
|
|
341
|
+
*/
|
|
342
|
+
emitted: Omit<Event, 'publisher'>[];
|
|
296
343
|
close(): Promise<unknown>;
|
|
297
344
|
}
|
|
298
345
|
|
|
@@ -311,6 +358,8 @@ export function createTestHost(options?: {
|
|
|
311
358
|
* this machine (`TEST_OWNER`). The space's 64 KiB a record is not held to here.
|
|
312
359
|
*/
|
|
313
360
|
records?: (Ref & RecordValue & { plugin?: string; owner?: string; location?: string })[];
|
|
361
|
+
/** Others' protocol definitions the plugin uses event groups of. */
|
|
362
|
+
protocols?: object[];
|
|
314
363
|
}): TestHost;
|
|
315
364
|
/** This machine's backend in the test host: the `owner` and `location` of the records the module writes. */
|
|
316
365
|
export const TEST_OWNER: string;
|
|
@@ -14,7 +14,9 @@
|
|
|
14
14
|
//
|
|
15
15
|
// What the module queries (`coda.query`, `ctx.query`) of a record of a protocol it implements its own handlers answer; of
|
|
16
16
|
// another's, `call` given. A doing call it makes (`coda.call`, `ctx.call`) its own handlers answer, of a protocol it implements. Its settings (`coda.settings`) are those the test gives, or sets again with `setSettings`, which
|
|
17
|
-
// tells the module's `onChange` as the backend does.
|
|
17
|
+
// tells the module's `onChange` as the backend does. The events it publishes (`coda.emit`) are kept for the test to read
|
|
18
|
+
// (`emitted`); those the test delivers (`emit`) go to its handlers (`coda.on`), which may name only what it subscribes to by
|
|
19
|
+
// its `uses`, as the backend has it. What it starts (`coda.spawn`, `ctx.spawn`) is a real child process of
|
|
18
20
|
// the test's, its streams and its end relayed as the backend relays them (adapters/process-relay.mjs), with no token and
|
|
19
21
|
// no entry in a registry: ended with the call or the module only as the test ends it, or as the host closes. The records
|
|
20
22
|
// (`coda.get`, `list`, `watch`, `put`, `delete`, `replace`, coda#2749 3.7) are those it writes, on this one machine, by its
|
|
@@ -22,12 +24,15 @@
|
|
|
22
24
|
// to what the backend holds them to (components/protocols/record-rules.mjs, the kinds' schemas) but the record directory's
|
|
23
25
|
// size. Anything else of the backend's it asks is refused. A command implementing an operation is started as the module's
|
|
24
26
|
// processes are, with no token: what it asks with `coda` (`progress`, `ask`, `query`, `self`) is not answered here, but by the backend's.
|
|
25
|
-
import { CORE_PROTOCOLS } from '@coda-console/protocol/protocol';
|
|
27
|
+
import { CORE_PROTOCOLS, protocolHasRecords } from '@coda-console/protocol/protocol';
|
|
26
28
|
import { spawn } from 'node:child_process';
|
|
27
29
|
import { randomUUID } from 'node:crypto';
|
|
28
30
|
import { ContractError } from '../domain/errors.mjs';
|
|
29
31
|
import { ProtocolTypes } from '../components/protocols/types.mjs';
|
|
30
32
|
import { commandOf, implementations } from '../components/plugins/plugin-rules.mjs';
|
|
33
|
+
import { publishedProblem, subscribed } from '../components/plugins/plugin-extensions.mjs';
|
|
34
|
+
import { protocolEvents } from '../components/protocols/protocol-events.mjs';
|
|
35
|
+
import { HOST_PROTOCOLS } from '../application/host-protocols.mjs';
|
|
31
36
|
import { checkGiven, checkHeld, checkKept, groupType, keptStatus } from '../components/concurrency-groups/schemas.mjs';
|
|
32
37
|
import { validate } from '../components/protocols/types.mjs';
|
|
33
38
|
import { LOCAL_KINDS, checkLabels, checkReplace, checkWrite, labelled, picked, readFilter, readRef, recordId, writeRef } from '../components/protocols/record-rules.mjs';
|
|
@@ -53,18 +58,27 @@ const open = { type: 'object' };
|
|
|
53
58
|
// the calls' deadlines go by (adapters/clock.mjs), for a test to move. `settings`: the plugin's settings to begin with.
|
|
54
59
|
// `records`: others' records the module reads, each `{ kind, id, spec, status?, labels?, plugin?, owner?, location? }`,
|
|
55
60
|
// another machine's (`owner`, by default `other`; `plugin`, by default the plugin under test) or, `owner` this one's
|
|
56
|
-
// (`TEST_OWNER`), another plugin's here (`plugin`, by default `other`).
|
|
57
|
-
|
|
61
|
+
// (`TEST_OWNER`), another plugin's here (`plugin`, by default `other`). `protocols`: others' protocol definitions, of the
|
|
62
|
+
// event groups the plugin uses (its `uses`), as the backend reckons what its `coda.on` may name
|
|
63
|
+
// (components/plugins/plugin-events.mjs `subscribed`).
|
|
64
|
+
export function createTestHost({ plugin = {}, call = null, clock = new Clock(), settings = {}, records = [], protocols = [] } = {}) {
|
|
58
65
|
// The protocols as the backend compiles them: Coda's own, those of its concurrency groups (RunGroups.attach), those it
|
|
59
66
|
// keeps out of the record directory, and the plugin's.
|
|
60
67
|
const types = new ProtocolTypes();
|
|
61
68
|
for (const { name, spec, status, operations = {} } of [...Object.values(CORE_PROTOCOLS), { ...groupType, name: groupType.kind },
|
|
62
|
-
...(plugin.protocols ?? [])]) types.register({ kind: name, spec, status, operations });
|
|
69
|
+
...(plugin.protocols ?? []).filter(protocolHasRecords)]) types.register({ kind: name, spec, status, operations });
|
|
63
70
|
for (const kind of LOCAL_KINDS) if (!types.types.has(kind)) types.register({ kind, spec: open, status: open, operations: {} });
|
|
64
71
|
const manifest = { protocolImplementations: implementations(plugin.protocolImplementations ?? []) };
|
|
65
72
|
const implemented = manifest.protocolImplementations.map(entry => entry.kind);
|
|
66
73
|
const operationOf = (kind, operation) => types.types.get(kind)?.operations.get(operation);
|
|
67
|
-
|
|
74
|
+
// The plugin, and what the backend would have of it and of the other plugins as its catalog: its protocols, what it
|
|
75
|
+
// implements and uses, and the others' protocols.
|
|
76
|
+
const id = plugin.id ?? 'test', entry = { id, protocols: plugin.protocols ?? [], protocolImplementations: manifest.protocolImplementations, uses: plugin.uses ?? {} };
|
|
77
|
+
const catalog = new Map([[id, entry], [' ', { protocols }]]);
|
|
78
|
+
const described = { id, path: plugin.path ?? process.cwd(), state: plugin.state ?? null, protocolImplementations: implemented,
|
|
79
|
+
events: subscribed(entry, catalog, () => null) };
|
|
80
|
+
// The events the module published (`coda.emit`), in order.
|
|
81
|
+
const emitted = [];
|
|
68
82
|
// Requests to the module waiting for its answer, the module's queries under way, and the doing calls handed to it, with what
|
|
69
83
|
// their caller is told of them, by the request's ID each.
|
|
70
84
|
const waiting = new Map(), querying = new Map(), runs = new Map();
|
|
@@ -185,6 +199,18 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
|
|
|
185
199
|
});
|
|
186
200
|
}
|
|
187
201
|
if (message.method === 'settings') return reply({ result: JSON.parse(JSON.stringify(current)) });
|
|
202
|
+
// An event the module publishes, checked as the backend checks it (components/plugins/plugin-extensions.mjs
|
|
203
|
+
// `publishedProblem`) but for its project, which is none here: among the events of Coda's own protocols too, which
|
|
204
|
+
// only Coda publishes.
|
|
205
|
+
if (message.method === 'emit') {
|
|
206
|
+
return answered(() => {
|
|
207
|
+
const { token, name, data, ...about } = message.params, event = protocolEvents(catalog, HOST_PROTOCOLS).get(name);
|
|
208
|
+
const problem = publishedProblem('coda.emit', entry, event, { name, subject: about.subject, payload: data });
|
|
209
|
+
if (problem) throw refused('invalid_input', problem);
|
|
210
|
+
emitted.push(structuredClone({ name, kind: event.kind, ...about, data }));
|
|
211
|
+
return null;
|
|
212
|
+
});
|
|
213
|
+
}
|
|
188
214
|
// A doing call's question, answered as its caller's `answer` says; one at a time, as the backend has it
|
|
189
215
|
// (components/plugins/hosted-calls.mjs `question`).
|
|
190
216
|
if (message.method === 'question') {
|
|
@@ -290,8 +316,8 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
|
|
|
290
316
|
}
|
|
291
317
|
|
|
292
318
|
// A run of the plugin's command `file` implementing an operation, as the backend runs one (components/plugins/plugin-host.mjs
|
|
293
|
-
// `startCommand`): `sh -c` from the plugin's directory, the call's input as JSON on its standard input, its record, ID
|
|
294
|
-
// deadline in its environment (`callEnv`); cancelled (`cancel`), its group asked to end, and made to once the grace has
|
|
319
|
+
// `startCommand`): `sh -c` from the plugin's directory, the call's input as JSON on its standard input, its record, ID,
|
|
320
|
+
// deadline and caller in its environment (`callEnv`); cancelled (`cancel`), its group asked to end, and made to once the grace has
|
|
295
321
|
// passed on the host's clock; the host closing kills it at once.
|
|
296
322
|
const commanded = (file, call, cancel) => startPluginCommand(fileCommand(file), { cwd: described.path, env: { ...process.env, ...callEnv(call) },
|
|
297
323
|
clock, timeoutMs: Infinity, signal: ending.signal, cancel, input: JSON.stringify(call.input), start: unregistered, label: `${described.id} · ${file}` });
|
|
@@ -316,10 +342,11 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
|
|
|
316
342
|
// input checked as the operation has it, its deadline its `timeout` from now or the operation's own, or none; called
|
|
317
343
|
// off with `signal`, or past its deadline, its handler's `ctx.signal` goes off (`AbortError`, `TimeoutError`) and its
|
|
318
344
|
// handler ends it still. Its result as the module's outcome says (`outcomeOf`); failed, thrown with its code; cancelled,
|
|
319
|
-
// thrown as `canceled`. Each progress is given to `onProgress`, each question to `answer`, which answers it.
|
|
320
|
-
|
|
345
|
+
// thrown as `canceled`. Each progress is given to `onProgress`, each question to `answer`, which answers it. `caller`, who
|
|
346
|
+
// is before the page that made it (`ctx.caller`, `CODA_CALLER`), or none, as for a call not made from a page.
|
|
347
|
+
async function run(record, operation, input, found, { signal, timeout, onProgress, answer, caller }) {
|
|
321
348
|
const name = `${record.kind}/${operation}`, at = timeout ?? found.timeout;
|
|
322
|
-
const call = { id: randomUUID(), record: recordFor(record), operation, input, deadline: at ? clock.now() + at : null };
|
|
349
|
+
const call = { id: randomUUID(), record: recordFor(record), operation, input, deadline: at ? clock.now() + at : null, ...(caller ? { caller } : {}) };
|
|
323
350
|
try { checkInput(found, name, input); checkRequest(call); } catch (error) { throw Object.assign(error, { effects: 'none' }); }
|
|
324
351
|
const command = commandOf(manifest, record.kind, operation);
|
|
325
352
|
if (command) return ended(found, name, await commandRun(command, call, signal));
|
|
@@ -348,10 +375,11 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
|
|
|
348
375
|
coda,
|
|
349
376
|
// Calls the plugin's module (or, for another's record, `call`) as a caller would: its result, or a failure with its
|
|
350
377
|
// `code`, `effects` and `retryAfterMs`. A query given up on with `signal` fails as an `AbortError`, past `timeout` as a
|
|
351
|
-
// `timeout`; a doing call of a protocol the plugin implements ends as its handler ends it (`run`)
|
|
352
|
-
|
|
378
|
+
// `timeout`; a doing call of a protocol the plugin implements ends as its handler ends it (`run`), made from a page
|
|
379
|
+
// when it has a `caller`.
|
|
380
|
+
call(record, operation, input = {}, { signal = null, timeout = null, onProgress = null, answer = null, caller = null } = {}) {
|
|
353
381
|
const found = operationOf(record?.kind, operation);
|
|
354
|
-
if (found && !found.safe && implemented.includes(record.kind)) return run(record, operation, input, found, { signal, timeout, onProgress, answer });
|
|
382
|
+
if (found && !found.safe && implemented.includes(record.kind)) return run(record, operation, input, found, { signal, timeout, onProgress, answer, caller });
|
|
355
383
|
return query(record, operation, input, { signal, deadline: timeout ? clock.now() + timeout : null });
|
|
356
384
|
},
|
|
357
385
|
// A query of the module's own (`coda self <名字>`, docs/plugins.md「只给自己用的查询」), handed to what it registered with
|
|
@@ -371,15 +399,15 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
|
|
|
371
399
|
},
|
|
372
400
|
// A doing call of a protocol the plugin implements, left by a process of the plugin's that ended before its handler did,
|
|
373
401
|
// handed to its operation's `resume` as the backend hands it (coda#2749 3.6), with the call's `deadline` (`ctx.deadline`),
|
|
374
|
-
// or none: asked to be cancelled (`canceled`), or past its deadline, its `ctx.signal` gone off already as an
|
|
402
|
+
// or none, and its `caller` (`ctx.caller`), or none: asked to be cancelled (`canceled`), or past its deadline, its `ctx.signal` gone off already as an
|
|
375
403
|
// `AbortError` or a `TimeoutError`; its result, or its failure, as `call`'s; with no `resume`, interrupted, of unknown
|
|
376
404
|
// effect, as the backend ends it then.
|
|
377
|
-
async resume(record, operation, { id = randomUUID(), input = {}, progress = null, canceled = false, deadline = null } = {}) {
|
|
405
|
+
async resume(record, operation, { id = randomUUID(), input = {}, progress = null, canceled = false, deadline = null, caller = null } = {}) {
|
|
378
406
|
const found = operationOf(record?.kind, operation), name = `${record?.kind}/${operation}`;
|
|
379
407
|
if (!found || found.safe || !implemented.includes(record.kind)) throw refused('not_found', `插件没有实现做事的操作 ${name}`);
|
|
380
408
|
const halted = canceled ? { name: 'AbortError' } : deadline !== null && deadline <= clock.now() ? { name: 'TimeoutError' } : null;
|
|
381
409
|
const call = { id, record: recordFor(record), operation, input, deadline, progress, canceled,
|
|
382
|
-
...(halted ? { halted } : {}) }, at = ++next;
|
|
410
|
+
...(caller ? { caller } : {}), ...(halted ? { halted } : {}) }, at = ++next;
|
|
383
411
|
const said = await new Promise((resolve, reject) => {
|
|
384
412
|
waiting.set(at, { resolve, reject });
|
|
385
413
|
modules.receive({ id: at, method: 'resume', params: { plugin: described, call } });
|
|
@@ -387,6 +415,11 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
|
|
|
387
415
|
if (said === null) throw new ContractError('interrupted', `插件没有给 ${name} 写 resume`, { effects: 'unknown' });
|
|
388
416
|
return ended(found, name, said);
|
|
389
417
|
},
|
|
418
|
+
// An event delivered to the module as the backend delivers one (components/plugins/plugin-events.mjs), a copy of it: to
|
|
419
|
+
// the handlers of its name (`coda.on`) now, none of it kept. `{ name, kind, subject, project, data, publisher }`.
|
|
420
|
+
emit: event => modules.receive({ method: 'event', params: { plugin: described.id, event: structuredClone(event) } }),
|
|
421
|
+
// The events the module published (`coda.emit`), in order: `{ name, kind, subject, project, data }` each.
|
|
422
|
+
emitted,
|
|
390
423
|
// The plugin's settings written again, as `Plugins.setSettings` leaves them: what the module's `settings.get` gives from now
|
|
391
424
|
// on, and what its `settings.onChange` listeners are told, which have been by the time this is done.
|
|
392
425
|
setSettings: async next => {
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// Coda's own protocols (docs/plugins.md「用到的权限」), each as its component defines it: data that nothing running changes,
|
|
2
|
+
// listed once. The service registers them from here, each bound by its kind to what serves it (components/protocols/protocols.mjs
|
|
3
|
+
// `bind`: application/assembly.mjs; a composer's and a group's own component binds that one), none left unbound once it is
|
|
4
|
+
// put together (server.mjs `checkBound`); and the plugins are judged against them from the first reading of the catalog on, before any is
|
|
5
|
+
// registered (components/plugins/plugins.mjs `protocols`). The plugin host for a plugin's tests takes Coda's events from here
|
|
6
|
+
// too (adapters/plugin-test-host.mjs), so nothing this imports runs. The protocol package's core protocols are not among them
|
|
7
|
+
// (CORE_PROTOCOLS).
|
|
8
|
+
import { PLUGIN_PROTOCOL } from '../kernel/plugin-protocol.mjs';
|
|
9
|
+
import { PROJECT_PROTOCOL } from '../kernel/project-protocol.mjs';
|
|
10
|
+
import { THREAD_PROTOCOL } from '../kernel/thread-protocol.mjs';
|
|
11
|
+
import { composerType, submissionType } from '../components/composers/schemas.mjs';
|
|
12
|
+
import { groupType } from '../components/concurrency-groups/schemas.mjs';
|
|
13
|
+
import { WORKFLOW_PROTOCOL, WORKFLOW_RUN_PROTOCOL, withWorkflows } from '../components/workflows/workflow-protocol-definitions.mjs';
|
|
14
|
+
|
|
15
|
+
// A session's, with the workflows' query and the group that has it (workflow-protocol-definitions.mjs `withWorkflows`).
|
|
16
|
+
export const THREAD_DEFINITION = withWorkflows(THREAD_PROTOCOL);
|
|
17
|
+
export const HOST_PROTOCOLS = [THREAD_DEFINITION, PROJECT_PROTOCOL, PLUGIN_PROTOCOL, WORKFLOW_PROTOCOL, WORKFLOW_RUN_PROTOCOL, composerType, submissionType, groupType];
|