@niwa-labs/workflow 0.0.0-stage → 0.0.0
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/LICENSE +21 -0
- package/README.md +13 -2
- package/package.json +55 -4
- package/src/actions.ts +408 -0
- package/src/agent.ts +211 -0
- package/src/ask.ts +84 -0
- package/src/bridge.ts +710 -0
- package/src/catalogue.ts +74 -0
- package/src/check.ts +880 -0
- package/src/child.ts +1378 -0
- package/src/cockpit/actions.ts +128 -0
- package/src/cockpit/catalogue-actions.ts +97 -0
- package/src/cockpit/dashboard.tsx +134 -0
- package/src/cockpit/groups.ts +45 -0
- package/src/cockpit/index.tsx +50 -0
- package/src/cockpit/launch.tsx +136 -0
- package/src/cockpit/plan.ts +101 -0
- package/src/cockpit/run-commands.tsx +102 -0
- package/src/cockpit/run-page.tsx +140 -0
- package/src/cockpit/run-summary.ts +16 -0
- package/src/cockpit/runs.tsx +73 -0
- package/src/cockpit/statistics.tsx +176 -0
- package/src/cockpit/track.tsx +159 -0
- package/src/cockpit/workflows.tsx +383 -0
- package/src/describe-cache.ts +122 -0
- package/src/describe.ts +174 -0
- package/src/guide.ts +213 -0
- package/src/index.ts +2813 -0
- package/src/inspect.ts +235 -0
- package/src/installation.ts +90 -0
- package/src/language.ts +217 -0
- package/src/records-entry.ts +63 -0
- package/src/records.ts +574 -0
- package/src/registry.ts +250 -0
- package/src/revise.ts +89 -0
- package/src/runner.ts +339 -0
- package/src/script-types.ts +549 -0
- package/src/stats.ts +460 -0
- package/src/status.ts +512 -0
- package/src/store.ts +259 -0
- package/src/subscriptions.ts +102 -0
- package/src/waiting.ts +61 -0
- package/test/cockpit-actions.test.ts +20 -0
- package/test/cockpit-groups.test.ts +42 -0
- package/test/cockpit-plan.test.ts +118 -0
- package/test/fixtures/branches-host.ts +58 -0
- package/test/fixtures/branches-script.js +23 -0
- package/test/fixtures/bridge-host.ts +23 -0
- package/test/fixtures/bridge-keys-script.js +15 -0
- package/test/fixtures/bridge-wait-script.js +8 -0
- package/test/fixtures/cancel-host.ts +58 -0
- package/test/fixtures/cancel-script.js +12 -0
- package/test/fixtures/crash-host.ts +61 -0
- package/test/fixtures/crash-script.js +14 -0
- package/test/fixtures/ping-records.ts +20 -0
- package/test/fixtures/revision-host.ts +57 -0
- package/test/fixtures/revision-script.js +11 -0
- package/test/fixtures/running-host.ts +61 -0
- package/test/fixtures/running-script.js +12 -0
- package/test/fixtures/with-data/flow.ts +2 -0
- package/test/fixtures/with-data/table.json +1 -0
- package/test/git-repo.ts +45 -0
- package/test/git-worktree.test.ts +413 -0
- package/test/question-format.test.ts +279 -0
- package/test/workflow-agent-caps.test.ts +91 -0
- package/test/workflow-agent-lifetime.test.ts +93 -0
- package/test/workflow-agent-options.test.ts +216 -0
- package/test/workflow-agent-schema.test.ts +386 -0
- package/test/workflow-agent-typings.test.ts +241 -0
- package/test/workflow-ask-resume.test.ts +145 -0
- package/test/workflow-branch-keys.test.ts +133 -0
- package/test/workflow-bridge-inproc.test.ts +230 -0
- package/test/workflow-bridge.test.ts +141 -0
- package/test/workflow-builtin-candidate.test.ts +230 -0
- package/test/workflow-builtin.test.ts +197 -0
- package/test/workflow-cancel-agent.test.ts +144 -0
- package/test/workflow-cancel.test.ts +166 -0
- package/test/workflow-chain.test.ts +84 -0
- package/test/workflow-check-options.test.ts +144 -0
- package/test/workflow-check-uses.test.ts +148 -0
- package/test/workflow-check.test.ts +282 -0
- package/test/workflow-contract.test.ts +295 -0
- package/test/workflow-crash-resume.test.ts +141 -0
- package/test/workflow-deadline.test.ts +102 -0
- package/test/workflow-describe-cache.test.ts +240 -0
- package/test/workflow-directory.test.ts +73 -0
- package/test/workflow-emits.test.ts +261 -0
- package/test/workflow-group-keys.test.ts +72 -0
- package/test/workflow-harnesses.test.ts +262 -0
- package/test/workflow-inspect.test.ts +152 -0
- package/test/workflow-language-types.test.ts +148 -0
- package/test/workflow-manifest.test.ts +93 -0
- package/test/workflow-manual-pause.test.ts +116 -0
- package/test/workflow-owners.test.ts +154 -0
- package/test/workflow-pause.test.ts +200 -0
- package/test/workflow-phases.test.ts +445 -0
- package/test/workflow-plugin-entries.test.ts +59 -0
- package/test/workflow-record-refs.test.ts +310 -0
- package/test/workflow-replay.test.ts +206 -0
- package/test/workflow-resume-once.test.ts +188 -0
- package/test/workflow-revision.test.ts +216 -0
- package/test/workflow-scope.test.ts +505 -0
- package/test/workflow-script-defaults.test.ts +119 -0
- package/test/workflow-script-error.test.ts +228 -0
- package/test/workflow-script-libraries.test.ts +88 -0
- package/test/workflow-script-packages.test.ts +119 -0
- package/test/workflow-stdout.test.ts +89 -0
- package/test/workflow-stop.test.ts +299 -0
- package/test/workflow-store.test.ts +220 -0
- package/test/workflow-visible.test.ts +136 -0
- package/test/workflow-wait-version.test.ts +54 -0
- package/test/workflow-wait.test.ts +224 -0
- package/test/workflow-waiting-agent.test.ts +64 -0
- package/tsconfig.json +15 -0
package/src/records.ts
ADDED
|
@@ -0,0 +1,574 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The records of a workflow run.
|
|
3
|
+
*
|
|
4
|
+
* A run is a few facts and nothing else:
|
|
5
|
+
*
|
|
6
|
+
* - **requested**: a run was asked for, which wakes the handler of the plugin;
|
|
7
|
+
* - **started**: the handler began a script, with the file it came from and the arguments it got;
|
|
8
|
+
* - **phase entered**, **phase left** and **step phase**: a branch of the script entered a declared phase, a branch
|
|
9
|
+
* that had one ended, and the phase a step was made in;
|
|
10
|
+
* - **log**: what the script wrote;
|
|
11
|
+
* - **paused**: something did not complete and a decision is needed. A paused run is a request
|
|
12
|
+
* with the choices of the core: retry, skip, cancel;
|
|
13
|
+
* - **finished**: the run ended, with its result;
|
|
14
|
+
* - **subscription installed** and **uninstalled**: a script niwa starts by itself on records.
|
|
15
|
+
*
|
|
16
|
+
* The calls the script made are not here: they are steps of the run's invocation, and the
|
|
17
|
+
* journal holds them like any other step.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import { EntityDescription, JsonSchemaValue, JsonValueSchema, idSchema, principalSchema, record, stableJson } from "@niwa-labs/core";
|
|
21
|
+
import { Subscription } from "@niwa-labs/script";
|
|
22
|
+
import { z } from "zod";
|
|
23
|
+
|
|
24
|
+
import { ScopeClosing, ScopeOutcome, WorkflowPhases } from "./language.ts";
|
|
25
|
+
|
|
26
|
+
/** The id of a run: `run-3fa9c2`, issued by niwa. */
|
|
27
|
+
export const RunId = idSchema("run");
|
|
28
|
+
export type RunId = z.infer<typeof RunId>;
|
|
29
|
+
|
|
30
|
+
/** The id of a registered workflow: `wf-a3f9c2`, issued at its first registration. */
|
|
31
|
+
export const WorkflowId = idSchema("workflow");
|
|
32
|
+
export type WorkflowId = z.infer<typeof WorkflowId>;
|
|
33
|
+
|
|
34
|
+
/** The id of an installation: `sub-3fa9c2`, issued when the script is installed. */
|
|
35
|
+
export const InstallationId = idSchema("subscription");
|
|
36
|
+
export type InstallationId = z.infer<typeof InstallationId>;
|
|
37
|
+
|
|
38
|
+
/** A version of a workflow: the sha256 of its source closure, the entry file and the local files it imports. */
|
|
39
|
+
export const WorkflowVersion = z.string().regex(/^[0-9a-f]{64}$/, "a version is a sha256 in hex").brand<"WorkflowVersion">();
|
|
40
|
+
export type WorkflowVersion = z.infer<typeof WorkflowVersion>;
|
|
41
|
+
|
|
42
|
+
/** Where a run came from, when it is more than a file: the workflow and the version it runs, the installation that started it, the directory it was started for. */
|
|
43
|
+
const RunOrigin = {
|
|
44
|
+
/** The registered workflow the run runs, when it was started by its id. */
|
|
45
|
+
workflow: WorkflowId.optional(),
|
|
46
|
+
/** The version of the workflow it runs. */
|
|
47
|
+
version: WorkflowVersion.optional(),
|
|
48
|
+
/** The installation whose record started the run. */
|
|
49
|
+
installation: InstallationId.optional(),
|
|
50
|
+
/** The directory the run was started for, an absolute path: the project it belongs to. Absent when the caller named none. */
|
|
51
|
+
directory: z.string().optional(),
|
|
52
|
+
/** The run and the step of it that started this run, when a run started it: the tree a cancel and a pause go down. */
|
|
53
|
+
parent: z.object({ run: z.string(), step: z.string() }).optional(),
|
|
54
|
+
/** The most branches each group of the run runs at once, set from outside; the script's own limit holds when it is lower. */
|
|
55
|
+
concurrency: z.number().int().positive().optional(),
|
|
56
|
+
/**
|
|
57
|
+
* The limits of the run: how many runs deep its tree may go, the run that started it being one, and how long the whole
|
|
58
|
+
* script may take, in milliseconds. A child run takes them.
|
|
59
|
+
*/
|
|
60
|
+
limits: z.object({ depth: z.number().int().positive().optional(), deadline: z.number().int().positive().optional() }).optional(),
|
|
61
|
+
/**
|
|
62
|
+
* The moment the run's deadline comes, in milliseconds since the epoch: its start and `limits.deadline`, never later than
|
|
63
|
+
* the deadline of the run that started it. Absent when nothing bounds it.
|
|
64
|
+
*/
|
|
65
|
+
deadline: z.number().int().optional(),
|
|
66
|
+
/** The rules `allow` narrowed the run to, and their version: the sha256 of the rules as given. */
|
|
67
|
+
allow: z.object({ rules: z.array(z.string()), version: z.string() }).optional(),
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
export { JsonSchemaValue };
|
|
71
|
+
|
|
72
|
+
/** The hash of the contract of a script: its input and output schemas, as the host reads them. */
|
|
73
|
+
export const ContractHash = z.string().regex(/^[0-9a-f]{64}$/, "a contract hash is a sha256 in hex").brand<"ContractHash">();
|
|
74
|
+
export type ContractHash = z.infer<typeof ContractHash>;
|
|
75
|
+
|
|
76
|
+
/** A field of a value that did not pass a schema. */
|
|
77
|
+
export const Issue = z.object({ path: z.string(), message: z.string() });
|
|
78
|
+
export type Issue = z.infer<typeof Issue>;
|
|
79
|
+
|
|
80
|
+
/** The run started: a script, and the arguments it was given. */
|
|
81
|
+
export const RunStarted = record(
|
|
82
|
+
"workflow.run.started",
|
|
83
|
+
z.object({
|
|
84
|
+
/** The id of the run: the identity of this attempt at the script. */
|
|
85
|
+
run: RunId,
|
|
86
|
+
/** The file the script came from. */
|
|
87
|
+
file: z.string(),
|
|
88
|
+
/** The arguments the script was given. */
|
|
89
|
+
args: z.unknown(),
|
|
90
|
+
/** The label of the run, when it has one. */
|
|
91
|
+
label: z.string().optional(),
|
|
92
|
+
/**
|
|
93
|
+
* The hash of the script file as it was when the run started.
|
|
94
|
+
*
|
|
95
|
+
* A hash that differs from the one of the file now means the script was edited, so the run
|
|
96
|
+
* that is resumed is a revision and not a replay. It is absent when the file could not be read.
|
|
97
|
+
*/
|
|
98
|
+
hash: z.string().optional(),
|
|
99
|
+
/** Whether the script process runs in a box (an empty one: no write, no network, a clean environment). Absent: it does not. */
|
|
100
|
+
box: z.boolean().optional(),
|
|
101
|
+
/** The hash of the contract (input and output schemas) the run started under. Absent when the script could not be read. */
|
|
102
|
+
contract: ContractHash.optional(),
|
|
103
|
+
/** The phases the script declares, in order: the plan the run's progress is shown against. Absent when it declares none. */
|
|
104
|
+
phases: WorkflowPhases.optional(),
|
|
105
|
+
...RunOrigin,
|
|
106
|
+
}),
|
|
107
|
+
);
|
|
108
|
+
|
|
109
|
+
/** The script wrote a line to the log of the run. */
|
|
110
|
+
export const RunLog = record(
|
|
111
|
+
"workflow.run.log",
|
|
112
|
+
z.object({ run: RunId, text: z.string() }),
|
|
113
|
+
);
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* A branch of the script entered a phase it declares: `phase(title)` was called in it, or the branch was made (by
|
|
117
|
+
* `parallel` or `pipeline`) in a branch that was in a phase, and starts in that one. The branch is its path in the
|
|
118
|
+
* script (`p1.0`, `p1.0.s2.1`), `""` for the script itself. Written under the branch and the number of the change
|
|
119
|
+
* within it, so a replay writes the same record and one branch does not take another's.
|
|
120
|
+
*/
|
|
121
|
+
export const PhaseEntered = record(
|
|
122
|
+
"workflow.phase.entered",
|
|
123
|
+
z.object({
|
|
124
|
+
run: RunId,
|
|
125
|
+
/** The path of the branch: `""` for the script itself. */
|
|
126
|
+
branch: z.string(),
|
|
127
|
+
/** The title of the declared phase. */
|
|
128
|
+
phase: z.string(),
|
|
129
|
+
}),
|
|
130
|
+
);
|
|
131
|
+
|
|
132
|
+
/** A branch that was in a phase ended: its phase is no longer one the run is in. Under the branch's own key. */
|
|
133
|
+
export const PhaseLeft = record(
|
|
134
|
+
"workflow.phase.left",
|
|
135
|
+
z.object({
|
|
136
|
+
run: RunId,
|
|
137
|
+
/** The path of the branch. */
|
|
138
|
+
branch: z.string(),
|
|
139
|
+
}),
|
|
140
|
+
);
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* A step of the run was made in a declared phase: the phase its branch was in when the step began. Written just
|
|
144
|
+
* before the step, under the step's key, so the steps of a run are grouped by phase from the journal alone.
|
|
145
|
+
*/
|
|
146
|
+
export const StepPhase = record(
|
|
147
|
+
"workflow.step.phase",
|
|
148
|
+
z.object({
|
|
149
|
+
run: RunId,
|
|
150
|
+
/** The key of the step: its label, or its place among the unlabeled calls. */
|
|
151
|
+
key: z.string(),
|
|
152
|
+
/** The title of the declared phase. */
|
|
153
|
+
phase: z.string(),
|
|
154
|
+
}),
|
|
155
|
+
);
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* The run paused: something did not complete, and a decision is needed.
|
|
160
|
+
*
|
|
161
|
+
* The choices are the ones of the core: retry, skip, cancel. The step it paused on is named, so
|
|
162
|
+
* the answer says which step it is about.
|
|
163
|
+
*/
|
|
164
|
+
export const RunPaused = record(
|
|
165
|
+
"workflow.run.paused",
|
|
166
|
+
z.object({
|
|
167
|
+
/** The run that paused. */
|
|
168
|
+
run: RunId,
|
|
169
|
+
/** Why it paused. */
|
|
170
|
+
reason: z.string(),
|
|
171
|
+
/** The step it paused on, when it paused on one. */
|
|
172
|
+
key: z.string().optional(),
|
|
173
|
+
/** The choices an owner may answer with. */
|
|
174
|
+
choices: z.array(z.enum(["retry", "skip", "cancel"])).optional(),
|
|
175
|
+
}),
|
|
176
|
+
);
|
|
177
|
+
|
|
178
|
+
/** A request to stop entering script operations at a workflow boundary. */
|
|
179
|
+
export const RunPauseRequested = record(
|
|
180
|
+
"workflow.run.pause-requested",
|
|
181
|
+
z.object({
|
|
182
|
+
run: RunId,
|
|
183
|
+
/** `deadline`: the run reached the deadline it names, and only `workflow.extend` or a cancel answers it. Absent for a pause someone asked for. */
|
|
184
|
+
kind: z.literal("deadline").optional(),
|
|
185
|
+
/** The deadline that was reached. */
|
|
186
|
+
deadline: z.number().int().optional(),
|
|
187
|
+
}),
|
|
188
|
+
);
|
|
189
|
+
|
|
190
|
+
/** The deadline of a run was moved later: the moment it comes now. */
|
|
191
|
+
export const RunDeadlineExtended = record("workflow.run.deadline-extended", z.object({ run: RunId, deadline: z.number().int() }));
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* A hold of a run: from now on a new call of an action that writes or cannot be undone is refused,
|
|
195
|
+
* in the run and, with `tree`, in the runs it started; reads and niwa's own records go on. The
|
|
196
|
+
* operations already going are left to end. Released by `workflow.run.continued` with its id.
|
|
197
|
+
*/
|
|
198
|
+
export const RunHoldRequested = record(
|
|
199
|
+
"workflow.run.hold-requested",
|
|
200
|
+
z.object({ run: RunId, tree: z.boolean(), effects: z.literal("deny") }),
|
|
201
|
+
);
|
|
202
|
+
|
|
203
|
+
/** Release only the specified request, so a duplicate cannot release a later pause. */
|
|
204
|
+
export const RunContinued = record("workflow.run.continued", z.object({ run: RunId, pause: z.string() }));
|
|
205
|
+
|
|
206
|
+
/** How a run ended: with the result the script returned, with an error, or by a cancel. */
|
|
207
|
+
export const RunOutcome = z.discriminatedUnion("status", [
|
|
208
|
+
/** The script returned, and what it returned passes its `output`. */
|
|
209
|
+
z.object({ status: z.literal("done"), result: z.json() }),
|
|
210
|
+
/** The run ended with no result of the script: what it returned does not pass its `output`. */
|
|
211
|
+
z.object({
|
|
212
|
+
status: z.literal("failed"),
|
|
213
|
+
error: z.object({ code: z.literal("output-invalid"), message: z.string(), issues: z.array(Issue) }),
|
|
214
|
+
}),
|
|
215
|
+
z.object({ status: z.literal("cancelled") }),
|
|
216
|
+
]);
|
|
217
|
+
export type RunOutcome = z.infer<typeof RunOutcome>;
|
|
218
|
+
|
|
219
|
+
/** The run finished: how it ended. */
|
|
220
|
+
export const RunFinished = record(
|
|
221
|
+
"workflow.run.finished",
|
|
222
|
+
z.object({
|
|
223
|
+
/** The run that finished. */
|
|
224
|
+
run: RunId,
|
|
225
|
+
execution: z.string().optional(),
|
|
226
|
+
/** How it ended. */
|
|
227
|
+
outcome: RunOutcome,
|
|
228
|
+
}),
|
|
229
|
+
{ providerOnly: "workflow" },
|
|
230
|
+
);
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* The run was asked for: a script, and the arguments it gets.
|
|
234
|
+
*
|
|
235
|
+
* The handler of the plugin is woken by this record, so the run is an invocation like any other.
|
|
236
|
+
*/
|
|
237
|
+
export const RunRequested = record("workflow.run.requested", z.object({
|
|
238
|
+
execution: z.string().optional(),
|
|
239
|
+
/** The id of the run: the identity of this attempt at the script. */
|
|
240
|
+
run: RunId,
|
|
241
|
+
/** The file the script came from. */
|
|
242
|
+
file: z.string(),
|
|
243
|
+
/** The arguments the script was given. */
|
|
244
|
+
args: z.unknown(),
|
|
245
|
+
/** The label of the run, when it has one. */
|
|
246
|
+
label: z.string().optional(),
|
|
247
|
+
/** The sha256 of the script as it was read when the run was asked for; the run records it as the script it started. */
|
|
248
|
+
hash: z.string().optional(),
|
|
249
|
+
/** Whether the script process runs in a box (an empty one: no write, no network, a clean environment). Absent: it does not. */
|
|
250
|
+
box: z.boolean().optional(),
|
|
251
|
+
/** The hash of the contract of the script as it was read when the run was asked for. */
|
|
252
|
+
contract: ContractHash.optional(),
|
|
253
|
+
/** The phases declared by the requested script, before any phase has been entered. */
|
|
254
|
+
phases: WorkflowPhases.optional(),
|
|
255
|
+
/** Run again the steps from this one on: a step key, a key prefix of a branch or scope, or the title of a phase. */
|
|
256
|
+
from: z.string().min(1).optional(),
|
|
257
|
+
...RunOrigin,
|
|
258
|
+
}), { providerOnly: "workflow" });
|
|
259
|
+
|
|
260
|
+
/** A call of the script was taken from an earlier start of the run instead of being made again. */
|
|
261
|
+
export const StepReused = record(
|
|
262
|
+
"workflow.step.reused",
|
|
263
|
+
z.object({
|
|
264
|
+
run: RunId,
|
|
265
|
+
/** The key of the call. */
|
|
266
|
+
key: z.string(),
|
|
267
|
+
/** The start of the run whose answer it took. */
|
|
268
|
+
from: z.string(),
|
|
269
|
+
}),
|
|
270
|
+
);
|
|
271
|
+
|
|
272
|
+
// The record a script starts on is read from its header, so the script package defines it.
|
|
273
|
+
export { Subscription };
|
|
274
|
+
|
|
275
|
+
/**
|
|
276
|
+
* A built-in workflow: one a plugin ships and offers (`BUILTIN_WORKFLOW`), named by the plugin and its name among
|
|
277
|
+
* the plugin's built-ins. The pair is what finds it again when the host starts: niwa issues the ids, the pair keeps them.
|
|
278
|
+
*/
|
|
279
|
+
export const Builtin = z.object({
|
|
280
|
+
/** The plugin that offers it, as the host says. */
|
|
281
|
+
plugin: z.string().min(1),
|
|
282
|
+
/** Its name among the built-ins of that plugin. */
|
|
283
|
+
name: z.string().min(1),
|
|
284
|
+
});
|
|
285
|
+
export type Builtin = z.infer<typeof Builtin>;
|
|
286
|
+
|
|
287
|
+
/**
|
|
288
|
+
* A script was installed: from now on niwa starts one run of it per record that matches.
|
|
289
|
+
*
|
|
290
|
+
* The record says what was pinned (the file and its hash), what starts the script, what it uses,
|
|
291
|
+
* and who installed it: the runs are born from the grant of the installer, for attribution and
|
|
292
|
+
* for the cascade.
|
|
293
|
+
*/
|
|
294
|
+
export const SubscriptionInstalled = record(
|
|
295
|
+
"workflow.subscription.installed",
|
|
296
|
+
z.object({
|
|
297
|
+
installation: InstallationId,
|
|
298
|
+
/** What the installation is for, in a few words of whoever made it. */
|
|
299
|
+
description: EntityDescription,
|
|
300
|
+
/** The registered workflow that was installed, when it was installed by its id. */
|
|
301
|
+
workflow: WorkflowId.optional(),
|
|
302
|
+
version: WorkflowVersion.optional(),
|
|
303
|
+
file: z.string(),
|
|
304
|
+
hash: z.string(),
|
|
305
|
+
on: z.array(Subscription),
|
|
306
|
+
uses: z.array(z.string()),
|
|
307
|
+
/** The JSON Schema of the trigger the script gets: absent for a script with `on`, which always gets the record. */
|
|
308
|
+
input: JsonSchemaValue.optional(),
|
|
309
|
+
/** The JSON Schema of what the script returns; absent when it returns nothing. */
|
|
310
|
+
output: JsonSchemaValue.optional(),
|
|
311
|
+
/** The hash of the contract, at the installation. */
|
|
312
|
+
contract: ContractHash,
|
|
313
|
+
/** The phases declared by the script at this installation. */
|
|
314
|
+
phases: WorkflowPhases.optional(),
|
|
315
|
+
/** Absent when nothing limits the installer (the host itself). */
|
|
316
|
+
installer: principalSchema.optional(),
|
|
317
|
+
/** Whether the runs of the script are boxed, as for `workflow.start`. Absent: they are not. */
|
|
318
|
+
box: z.boolean().optional(),
|
|
319
|
+
/** The built-in this installation is, made by the workflow module when the host started. Absent for one somebody made. */
|
|
320
|
+
builtin: Builtin.optional(),
|
|
321
|
+
}),
|
|
322
|
+
);
|
|
323
|
+
|
|
324
|
+
/** An installation ended: nothing starts from it any more. */
|
|
325
|
+
export const SubscriptionUninstalled = record(
|
|
326
|
+
"workflow.subscription.uninstalled",
|
|
327
|
+
z.object({ installation: InstallationId, reason: z.string() }),
|
|
328
|
+
);
|
|
329
|
+
|
|
330
|
+
/** A record type a script declares in `emits`: the name it gives it, its type `wf.<name>.<record>`, and the JSON Schema of its data. */
|
|
331
|
+
export const EmittedRecord = z.object({ record: z.string(), type: z.string(), schema: JsonSchemaValue });
|
|
332
|
+
export type EmittedRecord = z.infer<typeof EmittedRecord>;
|
|
333
|
+
|
|
334
|
+
/** A workflow that a registered one calls (`flow.<id>` in its `uses`), with the contract it was checked against. */
|
|
335
|
+
export const FlowCall = z.object({ workflow: WorkflowId, contract: ContractHash });
|
|
336
|
+
export type FlowCall = z.infer<typeof FlowCall>;
|
|
337
|
+
|
|
338
|
+
/** State shared by offer, registration and promotion guards at journal append. */
|
|
339
|
+
interface BuiltinAdmission {
|
|
340
|
+
offer?: string;
|
|
341
|
+
wanted: readonly { plugin: string; name: string; version: string; gated?: true }[];
|
|
342
|
+
registered: Map<string, { revision: string; version: string; candidate: boolean }>;
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
const builtinKey = (builtin: { plugin: string; name: string }): string => JSON.stringify([builtin.plugin, builtin.name]);
|
|
346
|
+
|
|
347
|
+
const builtinAdmission = {
|
|
348
|
+
group: "workflow.builtin.admission",
|
|
349
|
+
key: () => "builtin",
|
|
350
|
+
initial: (): BuiltinAdmission => ({ wanted: [], registered: new Map() }),
|
|
351
|
+
};
|
|
352
|
+
|
|
353
|
+
const staleTrial = { code: "stale-builtin-trial", reason: "The offered or accepted versions changed after the trial began" };
|
|
354
|
+
|
|
355
|
+
/**
|
|
356
|
+
* A version of a workflow was registered: from now on `flow.<id>` runs it.
|
|
357
|
+
*
|
|
358
|
+
* The first registration issues the id; a later one under the same id is a new version. What the
|
|
359
|
+
* script declared is kept, so the action the workflow is has its schemas without loading the script.
|
|
360
|
+
*/
|
|
361
|
+
export const WorkflowRegistered = record(
|
|
362
|
+
"workflow.registered",
|
|
363
|
+
z.object({
|
|
364
|
+
workflow: WorkflowId,
|
|
365
|
+
version: WorkflowVersion,
|
|
366
|
+
file: z.string(),
|
|
367
|
+
description: EntityDescription,
|
|
368
|
+
input: JsonSchemaValue.optional(),
|
|
369
|
+
output: JsonSchemaValue.optional(),
|
|
370
|
+
contract: ContractHash,
|
|
371
|
+
uses: z.array(z.string()),
|
|
372
|
+
/** The registered workflows it calls. */
|
|
373
|
+
calls: z.array(FlowCall),
|
|
374
|
+
/** The `name` the script gives itself, the prefix of its records: no other registered workflow has it. Absent when it has none. */
|
|
375
|
+
name: z.string().optional(),
|
|
376
|
+
/** The records of other scripts (`wf.<name>.<record>`) it waits for or reads by name: a change in what their writer declares checks it again. */
|
|
377
|
+
reads: z.array(z.string()).optional(),
|
|
378
|
+
/** The record types it declares in `emits`: they join the record catalogue the typing of other scripts is made from. Absent when it declares none. */
|
|
379
|
+
emits: z.array(EmittedRecord).optional(),
|
|
380
|
+
/** The records that start it once it is installed (its `on`). Absent when it declares none: it is only started by hand. */
|
|
381
|
+
on: z.array(Subscription).optional(),
|
|
382
|
+
/** The phases it declares, in order. Absent when it declares none. */
|
|
383
|
+
phases: WorkflowPhases.optional(),
|
|
384
|
+
/** The built-in it is: registered by the workflow module from the file the plugin ships, never by hand. */
|
|
385
|
+
builtin: Builtin.optional(),
|
|
386
|
+
/** A candidate version of a gated built-in: it moves neither the latest version nor the installation. */
|
|
387
|
+
candidate: z.literal(true).optional(),
|
|
388
|
+
}),
|
|
389
|
+
{
|
|
390
|
+
guard: {
|
|
391
|
+
...builtinAdmission,
|
|
392
|
+
admit(state, data) {
|
|
393
|
+
if (data.candidate !== true) return;
|
|
394
|
+
if (!state.wanted.some((one) => one.gated && one.plugin === data.builtin?.plugin && one.name === data.builtin?.name && one.version === data.version)) {
|
|
395
|
+
return { code: "superseded-builtin", reason: "The plugin no longer offers this candidate" };
|
|
396
|
+
}
|
|
397
|
+
},
|
|
398
|
+
fold(state, data, row) {
|
|
399
|
+
if (data.builtin !== undefined) {
|
|
400
|
+
state.registered.set(builtinKey(data.builtin), { revision: row.id, version: data.version, candidate: data.candidate === true });
|
|
401
|
+
}
|
|
402
|
+
return state;
|
|
403
|
+
},
|
|
404
|
+
},
|
|
405
|
+
},
|
|
406
|
+
);
|
|
407
|
+
|
|
408
|
+
/** One built-in as the host wants it now: the plugin's declaration, and the version its file is. */
|
|
409
|
+
export const WantedBuiltin = Builtin.extend({
|
|
410
|
+
file: z.string().min(1),
|
|
411
|
+
description: EntityDescription,
|
|
412
|
+
version: WorkflowVersion,
|
|
413
|
+
/** Its new versions come in as candidates. */
|
|
414
|
+
gated: z.literal(true).optional(),
|
|
415
|
+
suite: z.literal(true).optional(),
|
|
416
|
+
});
|
|
417
|
+
export type WantedBuiltin = z.infer<typeof WantedBuiltin>;
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* The built-ins that stand are not the ones the plugins offer: written when the host starts and finds a built-in
|
|
421
|
+
* missing, of another version, or one no plugin offers any more. Its handler registers and installs what is wanted
|
|
422
|
+
* and uninstalls the rest.
|
|
423
|
+
*/
|
|
424
|
+
export const BuiltinsWanted = record("workflow.builtins.wanted", z.object({ items: z.array(WantedBuiltin) }), {
|
|
425
|
+
guard: {
|
|
426
|
+
...builtinAdmission,
|
|
427
|
+
admit: () => undefined,
|
|
428
|
+
fold(state, { items }, row) {
|
|
429
|
+
return stableJson(state.wanted) === stableJson(items) ? state : { ...state, wanted: items, offer: row.id };
|
|
430
|
+
},
|
|
431
|
+
},
|
|
432
|
+
});
|
|
433
|
+
|
|
434
|
+
/** One version of a workflow, by its id and its version. */
|
|
435
|
+
export const VersionOf = z.object({ workflow: WorkflowId, version: WorkflowVersion });
|
|
436
|
+
|
|
437
|
+
/** An offered version and the registration that was current when it was selected. */
|
|
438
|
+
export const TrialVersion = VersionOf.extend({
|
|
439
|
+
name: z.string(),
|
|
440
|
+
revision: z.string(),
|
|
441
|
+
candidate: z.literal(true).optional(),
|
|
442
|
+
});
|
|
443
|
+
|
|
444
|
+
/** The exact set a trusted suite run and its children try. */
|
|
445
|
+
export const BuiltinTrial = record("workflow.builtin.trial", z.object({
|
|
446
|
+
run: RunId,
|
|
447
|
+
plugin: z.string(),
|
|
448
|
+
offer: z.string(),
|
|
449
|
+
entries: z.array(TrialVersion),
|
|
450
|
+
}), {
|
|
451
|
+
guard: {
|
|
452
|
+
group: "workflow.builtin.trial",
|
|
453
|
+
key: (data) => data.run,
|
|
454
|
+
initial: () => false,
|
|
455
|
+
admit: (exists) => exists ? { code: "builtin-trial-exists", reason: "This suite run already pinned a trial" } : undefined,
|
|
456
|
+
fold: () => true,
|
|
457
|
+
},
|
|
458
|
+
});
|
|
459
|
+
|
|
460
|
+
/** Update the accepted version of every trial candidate in one journal transition. */
|
|
461
|
+
export const BuiltinPromoted = record("workflow.builtin.promoted", BuiltinTrial.schema.and(z.object({
|
|
462
|
+
versions: z.array(VersionOf).min(1),
|
|
463
|
+
})), {
|
|
464
|
+
guard: {
|
|
465
|
+
...builtinAdmission,
|
|
466
|
+
admit(state, data) {
|
|
467
|
+
if (state.offer !== data.offer) return staleTrial;
|
|
468
|
+
for (const entry of data.entries) {
|
|
469
|
+
const current = state.registered.get(builtinKey({ plugin: data.plugin, name: entry.name }));
|
|
470
|
+
if (current?.revision !== entry.revision || current.version !== entry.version || current.candidate !== (entry.candidate === true)) return staleTrial;
|
|
471
|
+
}
|
|
472
|
+
},
|
|
473
|
+
fold(state, data) {
|
|
474
|
+
for (const entry of data.entries) {
|
|
475
|
+
if (entry.candidate !== true) continue;
|
|
476
|
+
state.registered.set(builtinKey({ plugin: data.plugin, name: entry.name }), { revision: entry.revision, version: entry.version, candidate: false });
|
|
477
|
+
}
|
|
478
|
+
return state;
|
|
479
|
+
},
|
|
480
|
+
},
|
|
481
|
+
});
|
|
482
|
+
|
|
483
|
+
/** One error of a check, with its place in the file. */
|
|
484
|
+
export const CheckProblem = z.object({ file: z.string(), line: z.number().int(), column: z.number().int(), code: z.string(), message: z.string() });
|
|
485
|
+
|
|
486
|
+
/**
|
|
487
|
+
* A workflow was checked again because one it calls changed its contract.
|
|
488
|
+
*
|
|
489
|
+
* A version whose latest check failed is broken: it does not start until a check passes again.
|
|
490
|
+
*/
|
|
491
|
+
export const WorkflowRechecked = record(
|
|
492
|
+
"workflow.rechecked",
|
|
493
|
+
z.object({
|
|
494
|
+
workflow: WorkflowId,
|
|
495
|
+
version: WorkflowVersion,
|
|
496
|
+
/** The workflow whose new contract asked for the check. */
|
|
497
|
+
because: WorkflowId,
|
|
498
|
+
ok: z.boolean(),
|
|
499
|
+
errors: z.array(CheckProblem),
|
|
500
|
+
/** The contracts of the workflows it calls, as the check met them. */
|
|
501
|
+
calls: z.array(FlowCall),
|
|
502
|
+
}),
|
|
503
|
+
);
|
|
504
|
+
|
|
505
|
+
/**
|
|
506
|
+
* The records a script writes with `emit`: every type under `wf.`, with data of any shape.
|
|
507
|
+
*
|
|
508
|
+
* A composition may declare a type of its own under `wf.` (`emits`) to give its data a schema; the
|
|
509
|
+
* others are this one.
|
|
510
|
+
*/
|
|
511
|
+
export const ScriptRecord = record("wf.*", z.unknown());
|
|
512
|
+
|
|
513
|
+
/** The types of the workflow module. */
|
|
514
|
+
/** A group of branches of a run opened: its key prefix, what leaving it does, its deadline, and whether an outer cancel waits for it. */
|
|
515
|
+
export const ScopeOpened = record(
|
|
516
|
+
"workflow.scope.opened",
|
|
517
|
+
z.object({
|
|
518
|
+
run: RunId,
|
|
519
|
+
scope: z.string(),
|
|
520
|
+
onExit: z.enum(["wait", "cancel"]),
|
|
521
|
+
/** The moment the group runs out of time, in milliseconds since the epoch. */
|
|
522
|
+
deadline: z.number().optional(),
|
|
523
|
+
onDeadline: z.enum(["skip", "fail"]).optional(),
|
|
524
|
+
shield: z.boolean().optional(),
|
|
525
|
+
concurrency: z.number().int().positive().optional(),
|
|
526
|
+
}),
|
|
527
|
+
);
|
|
528
|
+
|
|
529
|
+
/** A branch joined a group: written before the branch makes its first step. */
|
|
530
|
+
export const ScopeBranched = record("workflow.scope.branched", z.object({ run: RunId, scope: z.string(), key: z.string() }));
|
|
531
|
+
|
|
532
|
+
/** A branch of a group ended. `order` is its place among the outcomes of the group: the order `next()` gives them in. */
|
|
533
|
+
export const ScopeSettled = record(
|
|
534
|
+
"workflow.scope.settled",
|
|
535
|
+
z.object({
|
|
536
|
+
run: RunId,
|
|
537
|
+
scope: z.string(),
|
|
538
|
+
key: z.string(),
|
|
539
|
+
order: z.number().int().nonnegative(),
|
|
540
|
+
outcome: ScopeOutcome,
|
|
541
|
+
error: z.object({ name: z.string(), message: z.string() }).optional(),
|
|
542
|
+
}),
|
|
543
|
+
);
|
|
544
|
+
|
|
545
|
+
/** A group closed: its block returned, threw, or ran out of time, and every branch of it ended. */
|
|
546
|
+
export const ScopeClosed = record("workflow.scope.closed", z.object({ run: RunId, scope: z.string(), outcome: ScopeClosing }));
|
|
547
|
+
|
|
548
|
+
export const WORKFLOW_TYPES = [
|
|
549
|
+
ScriptRecord,
|
|
550
|
+
RunRequested,
|
|
551
|
+
RunStarted,
|
|
552
|
+
PhaseEntered,
|
|
553
|
+
PhaseLeft,
|
|
554
|
+
StepPhase,
|
|
555
|
+
RunLog,
|
|
556
|
+
RunPaused,
|
|
557
|
+
RunPauseRequested,
|
|
558
|
+
RunDeadlineExtended,
|
|
559
|
+
RunHoldRequested,
|
|
560
|
+
RunContinued,
|
|
561
|
+
RunFinished,
|
|
562
|
+
StepReused,
|
|
563
|
+
ScopeOpened,
|
|
564
|
+
ScopeBranched,
|
|
565
|
+
ScopeSettled,
|
|
566
|
+
ScopeClosed,
|
|
567
|
+
SubscriptionInstalled,
|
|
568
|
+
SubscriptionUninstalled,
|
|
569
|
+
WorkflowRegistered,
|
|
570
|
+
WorkflowRechecked,
|
|
571
|
+
BuiltinsWanted,
|
|
572
|
+
BuiltinTrial,
|
|
573
|
+
BuiltinPromoted,
|
|
574
|
+
];
|