@xeonr/pipelines-sdk 0.0.0-stage → 0.1.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/README.md +267 -2
- package/dist/auth.d.ts +72 -0
- package/dist/auth.d.ts.map +1 -0
- package/dist/auth.js +139 -0
- package/dist/auth.js.map +1 -0
- package/dist/client.d.ts +118 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +101 -0
- package/dist/client.js.map +1 -0
- package/dist/errors.d.ts +77 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +72 -0
- package/dist/errors.js.map +1 -0
- package/dist/gen/buf/validate/validate_pb.d.ts +4828 -0
- package/dist/gen/buf/validate/validate_pb.d.ts.map +1 -0
- package/dist/gen/buf/validate/validate_pb.js +357 -0
- package/dist/gen/buf/validate/validate_pb.js.map +1 -0
- package/dist/gen/gnostic/openapi/v3/annotations_pb.d.ts +24 -0
- package/dist/gen/gnostic/openapi/v3/annotations_pb.d.ts.map +1 -0
- package/dist/gen/gnostic/openapi/v3/annotations_pb.js +37 -0
- package/dist/gen/gnostic/openapi/v3/annotations_pb.js.map +1 -0
- package/dist/gen/gnostic/openapi/v3/openapiv3_pb.d.ts +2245 -0
- package/dist/gen/gnostic/openapi/v3/openapiv3_pb.d.ts.map +1 -0
- package/dist/gen/gnostic/openapi/v3/openapiv3_pb.js +410 -0
- package/dist/gen/gnostic/openapi/v3/openapiv3_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.d.ts +1031 -0
- package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.js +219 -0
- package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/runners_pb.d.ts +190 -0
- package/dist/gen/xeonr/pipelines/private/v1/runners_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/runners_pb.js +53 -0
- package/dist/gen/xeonr/pipelines/private/v1/runners_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.d.ts +1161 -0
- package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.js +269 -0
- package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/worker_pb.d.ts +915 -0
- package/dist/gen/xeonr/pipelines/private/v1/worker_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/private/v1/worker_pb.js +159 -0
- package/dist/gen/xeonr/pipelines/private/v1/worker_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/common_pb.d.ts +550 -0
- package/dist/gen/xeonr/pipelines/v1/common_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/common_pb.js +453 -0
- package/dist/gen/xeonr/pipelines/v1/common_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/definition_pb.d.ts +760 -0
- package/dist/gen/xeonr/pipelines/v1/definition_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/definition_pb.js +190 -0
- package/dist/gen/xeonr/pipelines/v1/definition_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/pools_pb.d.ts +800 -0
- package/dist/gen/xeonr/pipelines/v1/pools_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/pools_pb.js +247 -0
- package/dist/gen/xeonr/pipelines/v1/pools_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/registry_pb.d.ts +895 -0
- package/dist/gen/xeonr/pipelines/v1/registry_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/registry_pb.js +277 -0
- package/dist/gen/xeonr/pipelines/v1/registry_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/runs_pb.d.ts +1217 -0
- package/dist/gen/xeonr/pipelines/v1/runs_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/runs_pb.js +204 -0
- package/dist/gen/xeonr/pipelines/v1/runs_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/secrets_pb.d.ts +642 -0
- package/dist/gen/xeonr/pipelines/v1/secrets_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/secrets_pb.js +181 -0
- package/dist/gen/xeonr/pipelines/v1/secrets_pb.js.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/sinks_pb.d.ts +381 -0
- package/dist/gen/xeonr/pipelines/v1/sinks_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/pipelines/v1/sinks_pb.js +145 -0
- package/dist/gen/xeonr/pipelines/v1/sinks_pb.js.map +1 -0
- package/dist/gen/xeonr/platform/v1/options_pb.d.ts +313 -0
- package/dist/gen/xeonr/platform/v1/options_pb.d.ts.map +1 -0
- package/dist/gen/xeonr/platform/v1/options_pb.js +235 -0
- package/dist/gen/xeonr/platform/v1/options_pb.js.map +1 -0
- package/dist/handler.d.ts +94 -0
- package/dist/handler.d.ts.map +1 -0
- package/dist/handler.js +18 -0
- package/dist/handler.js.map +1 -0
- package/dist/index.d.ts +29 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +23 -0
- package/dist/index.js.map +1 -0
- package/dist/internal/time.d.ts +8 -0
- package/dist/internal/time.d.ts.map +1 -0
- package/dist/internal/time.js +25 -0
- package/dist/internal/time.js.map +1 -0
- package/dist/logship.d.ts +67 -0
- package/dist/logship.d.ts.map +1 -0
- package/dist/logship.js +176 -0
- package/dist/logship.js.map +1 -0
- package/dist/testing/index.d.ts +202 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +909 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/transport.d.ts +43 -0
- package/dist/transport.d.ts.map +1 -0
- package/dist/transport.js +44 -0
- package/dist/transport.js.map +1 -0
- package/dist/worker.d.ts +213 -0
- package/dist/worker.d.ts.map +1 -0
- package/dist/worker.js +664 -0
- package/dist/worker.js.map +1 -0
- package/package.json +70 -3
package/README.md
CHANGED
|
@@ -1,3 +1,268 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @xeonr/pipelines-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The TypeScript SDK for xeonr pipelines (Trellis PIPE-5). It does two things:
|
|
4
|
+
|
|
5
|
+
- **Client**: start runs and enqueue jobs on the public API (`CreateRun`,
|
|
6
|
+
`CreateJob`), read them and cancel them.
|
|
7
|
+
- **Worker**: run your product's handlers inside your own Node.js process.
|
|
8
|
+
The worker claims your handlers' attempts from pipelines-api, and the
|
|
9
|
+
platform handles retries, delays, timeouts, leases, cancel, logs and the
|
|
10
|
+
console. You run no runner, no image and no container-platform.
|
|
11
|
+
|
|
12
|
+
This is not the step SDK (`@xeonr/runner-sdk`, `defineStep` inside an image).
|
|
13
|
+
|
|
14
|
+
**Runtime:** Node.js 20, 22 and 24, ESM only. CI runs on 24. The smoke test of
|
|
15
|
+
the built package also passes on 20 and 22.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
pnpm add @xeonr/pipelines-sdk @bufbuild/protobuf @connectrpc/connect
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Auth
|
|
24
|
+
|
|
25
|
+
Calls carry an Auth access token for your product's service account. The
|
|
26
|
+
token comes from the `jwt-bearer` grant (`auth.service-to-service`), the same
|
|
27
|
+
exchange as go-platform's `authn.NewTokenSource`. `jwtBearer` caches the token
|
|
28
|
+
and refreshes it single-flight, 30 s before it expires. If a refresh fails
|
|
29
|
+
while the old token is still valid, the old token is used.
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
import { jwtBearer } from "@xeonr/pipelines-sdk";
|
|
33
|
+
|
|
34
|
+
const token = jwtBearer({
|
|
35
|
+
tokenUrl: "https://auth.xeonr.io/api/v1/oauth/token",
|
|
36
|
+
assertion: () => process.env.PIPELINES_SA_ASSERTION!, // re-read on each refresh
|
|
37
|
+
scopes: ["pipelines:run:edit", "pipelines:run:read", "pipelines:worker:edit", "pipelines:package:edit", "pipelines:pool:edit"],
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
You can also pass any `() => string | Promise<string>` as `token`. On
|
|
42
|
+
`unauthenticated`, the SDK drops the cached token and retries the call once
|
|
43
|
+
with a fresh one.
|
|
44
|
+
|
|
45
|
+
| Scope | Needed for |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `pipelines:run:edit` | `createRun`, `createJob`, `cancelRun` |
|
|
48
|
+
| `pipelines:run:read` | `getRun`, `getRunGraph`, `listRuns` |
|
|
49
|
+
| `pipelines:worker:edit` | the worker's claim loop (`WorkerService`) |
|
|
50
|
+
| `pipelines:package:edit`, `pipelines:pool:edit` | a worker that registers itself at boot (the default) |
|
|
51
|
+
|
|
52
|
+
A worker may claim only its owner's handlers. The API checks this at claim.
|
|
53
|
+
|
|
54
|
+
## Run a worker
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { defineHandler, Worker, jwtBearer } from "@xeonr/pipelines-sdk";
|
|
58
|
+
|
|
59
|
+
const TEAM = "urn:xeonr:auth:team:0f3c9a2e-8f1b-4c2d-9e6a-1b2c3d4e5f60";
|
|
60
|
+
|
|
61
|
+
export const sendEmail = defineHandler<{ to: string; template: string }, { messageId: string }>({
|
|
62
|
+
name: "acme/send-email", // <namespace>/<name>; the namespace is your team's
|
|
63
|
+
version: "1.2.0", // published at boot; bump it when the manifest changes
|
|
64
|
+
inputs: [{ name: "to", type: 1, required: true }, { name: "template", type: 1, required: true }],
|
|
65
|
+
outputs: [{ name: "messageId", type: 1 }],
|
|
66
|
+
concurrency: 4, // at most 4 of these at once in this process
|
|
67
|
+
async run({ input, signal, log, attempt }) {
|
|
68
|
+
log.info("sending", { to: input.to, attempt: attempt.number });
|
|
69
|
+
const res = await fetch("https://mail.internal/send", { method: "POST", body: JSON.stringify(input), signal });
|
|
70
|
+
if (!res.ok) throw new Error(`mail service answered ${res.status}`); // fails this attempt only
|
|
71
|
+
return { messageId: (await res.json()).id }; // kv outputs
|
|
72
|
+
},
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
const worker = new Worker({
|
|
76
|
+
baseUrl: "https://pipelines.xeonr.io",
|
|
77
|
+
token,
|
|
78
|
+
tenant: TEAM,
|
|
79
|
+
pool: { name: "acme-app" }, // every replica of the app uses the same pool
|
|
80
|
+
concurrency: 16, // across all handlers; also the pool's capacity per instance
|
|
81
|
+
});
|
|
82
|
+
worker.handle(sendEmail);
|
|
83
|
+
await worker.start(); // publishes handler versions, declares the sdk pool, starts claiming
|
|
84
|
+
|
|
85
|
+
process.on("SIGTERM", () => void worker.stop({ timeoutMs: 30_000 }));
|
|
86
|
+
await worker.wait(); // rejects if the worker stopped on an auth error
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
At boot, `start()` publishes each handler as a `kind: worker` package
|
|
90
|
+
(`RegistryService.PublishVersion`) and declares the `sdk` pool (`SetPool`).
|
|
91
|
+
Pass `register: false` and `pool.id` if something else does that.
|
|
92
|
+
|
|
93
|
+
### What the worker does for each attempt
|
|
94
|
+
|
|
95
|
+
1. **Claim.** It long-polls `ClaimAttempts` for its handlers. No claim is
|
|
96
|
+
allowed to push the worker past its overall `concurrency` or a handler's
|
|
97
|
+
`concurrency`: each poll reserves its slots up front.
|
|
98
|
+
2. **Start.** It calls `StartAttempt`. Your code runs only after that succeeds.
|
|
99
|
+
3. **Heartbeat.** It renews the lease at the interval the claim gives, from
|
|
100
|
+
the claim until completion.
|
|
101
|
+
4. **Run.** It calls your handler with an `AbortSignal`. The signal fires
|
|
102
|
+
with an `AttemptAbortedError` whose `cause` says why:
|
|
103
|
+
- `cancelled`: a heartbeat answered cancel;
|
|
104
|
+
- `deadline`: the node's timeout passed;
|
|
105
|
+
- `lost`: the lease was lost;
|
|
106
|
+
- `shutdown`: `stop()` ran past its timeout.
|
|
107
|
+
5. **Log.** `ctx.log` ships the attempt's log in order with `AppendLogs`,
|
|
108
|
+
idempotent on seq, and honours the attempt's log cap.
|
|
109
|
+
6. **Complete.** It calls `CompleteAttempt` with the kv outputs inline, or
|
|
110
|
+
with a termination:
|
|
111
|
+
|
|
112
|
+
| How the handler ended | Termination | Failure class (set by the platform) |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| Returned outputs | `EXITED` (0) | none |
|
|
115
|
+
| Threw or rejected; outputs not valid kv; `parseInput` threw | `HANDLER_ERROR` | `HANDLER_ERROR` |
|
|
116
|
+
| Still running at its deadline | `TIMED_OUT` | `TIMEOUT` |
|
|
117
|
+
| Stopped after a cancel | `CANCELLED` | `CANCELLED` |
|
|
118
|
+
| Aborted by `stop()` past its timeout | `RUNNER_ERROR` | `RUNNER_CRASHED` |
|
|
119
|
+
| Lease lost | nothing reported | `ABANDONED`, decided by the platform |
|
|
120
|
+
|
|
121
|
+
The platform picks the failure class and decides whether to retry, using the
|
|
122
|
+
node's `retry.when`. By default it retries only transient classes:
|
|
123
|
+
`ABANDONED`, `RUNNER_CRASHED`, `IMAGE_PULL`, `STAGING_FAILED` and `INTERNAL`.
|
|
124
|
+
So a handler error is retried only when the node lists `HANDLER_ERROR`. A
|
|
125
|
+
handler cannot mark one particular error as permanent or transient: the
|
|
126
|
+
contract has no field for it (see "Contract gaps" in the MR).
|
|
127
|
+
|
|
128
|
+
A thrown error or rejected promise fails that attempt, never the process.
|
|
129
|
+
JavaScript cannot kill a handler that ignores its signal. Such a handler gets
|
|
130
|
+
the cancel grace (or `stop`'s `graceMs`). After that its slot is freed and
|
|
131
|
+
anything it does later is ignored.
|
|
132
|
+
|
|
133
|
+
### Errors from pipelines-api
|
|
134
|
+
|
|
135
|
+
The worker reads each error by its Connect code (`errorKind`):
|
|
136
|
+
|
|
137
|
+
- `failed_precondition`: the attempt is no longer this worker's. The handler
|
|
138
|
+
is aborted (`lost`) and nothing more is reported.
|
|
139
|
+
- `invalid_argument` on `StartAttempt` or `CompleteAttempt`: final, not
|
|
140
|
+
retried.
|
|
141
|
+
- `unauthenticated` or `permission_denied`: not transient. The worker stops
|
|
142
|
+
claiming, calls `onError`, and `wait()` rejects once in-flight attempts end.
|
|
143
|
+
- `out_of_range` on `AppendLogs`: not fatal. The rest of that attempt's log is
|
|
144
|
+
dropped and the attempt carries on.
|
|
145
|
+
- Anything else (`unavailable`, `deadline_exceeded`, `internal`, network
|
|
146
|
+
errors): retried with backoff. A heartbeat that cannot get through before
|
|
147
|
+
the lease runs out loses the attempt.
|
|
148
|
+
|
|
149
|
+
### Graceful shutdown
|
|
150
|
+
|
|
151
|
+
`stop({ timeoutMs, graceMs })` works in four steps:
|
|
152
|
+
|
|
153
|
+
1. It stops claiming and aborts any held long-polls.
|
|
154
|
+
2. In-flight handlers get `timeoutMs` to finish (default 30 s). Their real
|
|
155
|
+
outcome is reported.
|
|
156
|
+
3. Handlers still running after that are aborted with `shutdown`. They get
|
|
157
|
+
`graceMs` more (default 5 s), then their attempts are completed as
|
|
158
|
+
`RUNNER_ERROR`, which the platform retries by default.
|
|
159
|
+
4. Attempts that were claimed but never started are left alone. Their leases
|
|
160
|
+
lapse and they are offered again with no retry spent.
|
|
161
|
+
|
|
162
|
+
## Enqueue jobs and start runs
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
import { FailureClass, PipelinesClient } from "@xeonr/pipelines-sdk";
|
|
166
|
+
|
|
167
|
+
const pipelines = new PipelinesClient({ baseUrl: "https://pipelines.xeonr.io", token });
|
|
168
|
+
|
|
169
|
+
// One handler, run once: CreateJob (the plan's EnqueueJob). Idempotent per product.
|
|
170
|
+
const { run } = await pipelines.createJob({
|
|
171
|
+
tenant: TEAM,
|
|
172
|
+
handler: "acme/send-email",
|
|
173
|
+
payload: { to: "ada@example.com", template: "welcome" },
|
|
174
|
+
idempotencyKey: "welcome-email:user-4821",
|
|
175
|
+
delayMs: 10 * 60_000, // not offered to a worker before ten minutes have passed
|
|
176
|
+
});
|
|
177
|
+
|
|
178
|
+
// A full run that mixes an image node and a worker node, passing an output between them.
|
|
179
|
+
await pipelines.createRun({
|
|
180
|
+
idempotencyKey: "thumbs:upload-91",
|
|
181
|
+
tenant: TEAM,
|
|
182
|
+
resource: { kind: "acme.upload", id: "upload-91" },
|
|
183
|
+
definition: {
|
|
184
|
+
nodes: [
|
|
185
|
+
{ id: "extract", action: { case: "uses", value: { name: "acme/extract", version: "1.0.0" } } },
|
|
186
|
+
{
|
|
187
|
+
id: "notify",
|
|
188
|
+
action: { case: "handler", value: "acme/send-email" },
|
|
189
|
+
with: { to: { kind: { case: "stringValue", value: "${{ steps.extract.outputs.kv.owner }}" } } },
|
|
190
|
+
retry: { max: 3, when: [FailureClass.HANDLER_ERROR] },
|
|
191
|
+
},
|
|
192
|
+
],
|
|
193
|
+
},
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
await pipelines.getRun(run.id);
|
|
197
|
+
await pipelines.cancelRun(run.id, "superseded");
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
`pipelines.runs` is the generated `RunsService` client, for anything not
|
|
201
|
+
wrapped. The generated messages are importable from
|
|
202
|
+
`@xeonr/pipelines-sdk/gen/xeonr/pipelines/v1/*_pb`.
|
|
203
|
+
|
|
204
|
+
## Test your handlers: `@xeonr/pipelines-sdk/testing`
|
|
205
|
+
|
|
206
|
+
`FakePipelines` is an in-memory pipelines-api: a real Connect router behind an
|
|
207
|
+
in-memory transport. The real `Worker` and `PipelinesClient` run against it
|
|
208
|
+
unchanged.
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
import { FakePipelines, FAKE_TENANT } from "@xeonr/pipelines-sdk/testing";
|
|
212
|
+
|
|
213
|
+
const fake = new FakePipelines({ leaseMs: 600, heartbeatIntervalMs: 50 });
|
|
214
|
+
const worker = new Worker({ transport: fake.transport(), tenant: FAKE_TENANT, pool: { name: "test" } });
|
|
215
|
+
worker.handle(sendEmail);
|
|
216
|
+
await worker.start();
|
|
217
|
+
|
|
218
|
+
const client = new PipelinesClient({ transport: fake.transport() });
|
|
219
|
+
const { run } = await client.createJob({ tenant: FAKE_TENANT, handler: "acme/send-email", idempotencyKey: "t1", payload: { to: "a@b", template: "x" } });
|
|
220
|
+
const done = await fake.waitForRun(run.id);
|
|
221
|
+
expect(done.nodes.get("job")!.kv).toEqual({ messageId: "…" });
|
|
222
|
+
|
|
223
|
+
await worker.stop();
|
|
224
|
+
fake.close();
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
The fake models:
|
|
228
|
+
|
|
229
|
+
- accounts (a token with a tenant and scopes), and namespace and pool
|
|
230
|
+
ownership;
|
|
231
|
+
- publish, pools, jobs with delay and idempotency, and runs;
|
|
232
|
+
- the claim long-poll, leases and their lapse (`expireLease`), heartbeats and
|
|
233
|
+
cancel;
|
|
234
|
+
- logs, with `out_of_range` for a gap;
|
|
235
|
+
- the server's mapping from termination to failure class, and retries by
|
|
236
|
+
class;
|
|
237
|
+
- external (image) nodes you settle with `completeNode`;
|
|
238
|
+
- error injection (`inject("Heartbeat", Code.Unavailable, 2)`).
|
|
239
|
+
|
|
240
|
+
It does not model secrets, blobs, tiers or routing between pools.
|
|
241
|
+
|
|
242
|
+
## Dependencies
|
|
243
|
+
|
|
244
|
+
| Package | Why |
|
|
245
|
+
|---|---|
|
|
246
|
+
| `@connectrpc/connect-node` (dependency) | the Connect transport over Node's HTTP |
|
|
247
|
+
| `@connectrpc/connect`, `@bufbuild/protobuf` (peers) | the generated clients and messages; peers, so your app has one copy |
|
|
248
|
+
|
|
249
|
+
Nothing else at runtime. The token exchange uses the global `fetch`.
|
|
250
|
+
|
|
251
|
+
## Development
|
|
252
|
+
|
|
253
|
+
```sh
|
|
254
|
+
pnpm install
|
|
255
|
+
pnpm typecheck && pnpm lint && pnpm test && pnpm build
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
The Connect code is generated from the BSR before every typecheck, lint, test
|
|
259
|
+
and build. The modules are `proto.prod.wtf/xeonr/pipelines` and
|
|
260
|
+
`xeonr/pipelines-private`, pinned in `buf.gen.yaml`. Nothing generated is
|
|
261
|
+
committed (`ui.no-generated-code`). Log in once with
|
|
262
|
+
`buf registry login proto.prod.wtf`. To pick up a contract change, bump the
|
|
263
|
+
pins in `buf.gen.yaml`.
|
|
264
|
+
|
|
265
|
+
Releasing means bumping `version` in `package.json` on `main`. CI publishes
|
|
266
|
+
any version the registry does not have yet.
|
|
267
|
+
|
|
268
|
+
See `CLAUDE.md` for the plan, the tickets and Plumb.
|
package/dist/auth.d.ts
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Supplies the bearer token every pipelines-api call carries: an Auth access
|
|
3
|
+
* token for the product's service account, holding the scopes the calls need
|
|
4
|
+
* (`pipelines:run:edit` to start runs and jobs, `pipelines:worker:edit` for a
|
|
5
|
+
* worker, `pipelines:package:edit` and `pipelines:pool:edit` for a worker
|
|
6
|
+
* that registers itself at boot).
|
|
7
|
+
*
|
|
8
|
+
* Either a function returning the token, or an object that can also drop a
|
|
9
|
+
* cached token when the API answers `unauthenticated`, so the next call
|
|
10
|
+
* fetches a fresh one.
|
|
11
|
+
*/
|
|
12
|
+
export type TokenProvider = ((signal?: AbortSignal) => string | Promise<string>) | {
|
|
13
|
+
token(signal?: AbortSignal): Promise<string>;
|
|
14
|
+
invalidate?(): void;
|
|
15
|
+
};
|
|
16
|
+
/** A normalised TokenProvider. */
|
|
17
|
+
export interface TokenSource {
|
|
18
|
+
token(signal?: AbortSignal): Promise<string>;
|
|
19
|
+
invalidate(): void;
|
|
20
|
+
}
|
|
21
|
+
/** Normalises a TokenProvider. */
|
|
22
|
+
export declare function tokenSource(p: TokenProvider): TokenSource;
|
|
23
|
+
/** Options for {@link jwtBearer}. */
|
|
24
|
+
export interface JwtBearerOptions {
|
|
25
|
+
/**
|
|
26
|
+
* Auth's token endpoint, e.g. `https://auth.xeonr.io/api/v1/oauth/token`.
|
|
27
|
+
* Use the edge path the platform names for your environment.
|
|
28
|
+
*/
|
|
29
|
+
tokenUrl: string;
|
|
30
|
+
/**
|
|
31
|
+
* The service account's pre-issued assertion (an Auth service-account
|
|
32
|
+
* token), or a function that reads it, so a rotated secret is picked up on
|
|
33
|
+
* the next refresh.
|
|
34
|
+
*/
|
|
35
|
+
assertion: string | (() => string | Promise<string>);
|
|
36
|
+
/** Scopes requested on every token. */
|
|
37
|
+
scopes?: readonly string[];
|
|
38
|
+
/**
|
|
39
|
+
* RFC 8707 `resource`: the audience of the bound application the token is
|
|
40
|
+
* narrowed to (pipelines-api's), when Auth is configured for it.
|
|
41
|
+
*/
|
|
42
|
+
resource?: string;
|
|
43
|
+
/** Reuse a token only until this long before it expires. Default 30 s. */
|
|
44
|
+
expirySkewMs?: number;
|
|
45
|
+
/** Assumed lifetime when the endpoint omits `expires_in`. Default 5 min. */
|
|
46
|
+
fallbackLifetimeMs?: number;
|
|
47
|
+
/** Bound on one token request. Default 30 s. */
|
|
48
|
+
timeoutMs?: number;
|
|
49
|
+
/** The fetch implementation. Default `globalThis.fetch`. */
|
|
50
|
+
fetch?: typeof globalThis.fetch;
|
|
51
|
+
/** The clock, for tests. Default `Date.now`. */
|
|
52
|
+
now?: () => number;
|
|
53
|
+
}
|
|
54
|
+
/** A token provider that also reports what it holds, for diagnostics and tests. */
|
|
55
|
+
export interface JwtBearerTokenProvider extends TokenSource {
|
|
56
|
+
/** When the cached token expires (epoch ms), or undefined when none is cached. */
|
|
57
|
+
readonly expiresAt: number | undefined;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Exchanges a service-account assertion for access tokens with the RFC 7523
|
|
61
|
+
* `jwt-bearer` grant at Auth's token endpoint (`auth.service-to-service`),
|
|
62
|
+
* the same exchange as go-platform's `authn.NewTokenSource` with
|
|
63
|
+
* `GrantJWTBearer`.
|
|
64
|
+
*
|
|
65
|
+
* Tokens are cached and reused until `expirySkewMs` before they expire.
|
|
66
|
+
* Refreshes are single-flight: concurrent callers wait for one request. When
|
|
67
|
+
* a refresh fails while the cached token has not actually expired yet, the
|
|
68
|
+
* cached token is returned, so a brief Auth outage near the end of a
|
|
69
|
+
* token's life does not fail calls; once it has expired, the error is thrown.
|
|
70
|
+
*/
|
|
71
|
+
export declare function jwtBearer(opts: JwtBearerOptions): JwtBearerTokenProvider;
|
|
72
|
+
//# sourceMappingURL=auth.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GACpD;IACE,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB,CAAC;AAEN,kCAAkC;AAClC,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,kCAAkC;AAClC,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,WAAW,CAQzD;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACrD,uCAAuC;IACvC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,sBAAsB,CAsFxE"}
|
package/dist/auth.js
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { PipelinesAuthError } from "./errors.js";
|
|
2
|
+
/** Normalises a TokenProvider. */
|
|
3
|
+
export function tokenSource(p) {
|
|
4
|
+
if (typeof p === "function") {
|
|
5
|
+
return { token: async (signal) => p(signal), invalidate: () => undefined };
|
|
6
|
+
}
|
|
7
|
+
return {
|
|
8
|
+
token: (signal) => p.token(signal),
|
|
9
|
+
invalidate: () => p.invalidate?.(),
|
|
10
|
+
};
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Exchanges a service-account assertion for access tokens with the RFC 7523
|
|
14
|
+
* `jwt-bearer` grant at Auth's token endpoint (`auth.service-to-service`),
|
|
15
|
+
* the same exchange as go-platform's `authn.NewTokenSource` with
|
|
16
|
+
* `GrantJWTBearer`.
|
|
17
|
+
*
|
|
18
|
+
* Tokens are cached and reused until `expirySkewMs` before they expire.
|
|
19
|
+
* Refreshes are single-flight: concurrent callers wait for one request. When
|
|
20
|
+
* a refresh fails while the cached token has not actually expired yet, the
|
|
21
|
+
* cached token is returned, so a brief Auth outage near the end of a
|
|
22
|
+
* token's life does not fail calls; once it has expired, the error is thrown.
|
|
23
|
+
*/
|
|
24
|
+
export function jwtBearer(opts) {
|
|
25
|
+
const tokenUrl = opts.tokenUrl.trim();
|
|
26
|
+
if (!tokenUrl)
|
|
27
|
+
throw new TypeError("jwtBearer: tokenUrl is required");
|
|
28
|
+
if (typeof opts.assertion === "string" && !opts.assertion.trim()) {
|
|
29
|
+
throw new TypeError("jwtBearer: assertion is required");
|
|
30
|
+
}
|
|
31
|
+
const skew = opts.expirySkewMs ?? 30_000;
|
|
32
|
+
const fallback = opts.fallbackLifetimeMs ?? 5 * 60_000;
|
|
33
|
+
const timeoutMs = opts.timeoutMs ?? 30_000;
|
|
34
|
+
const doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
|
|
35
|
+
const now = opts.now ?? Date.now;
|
|
36
|
+
let cached;
|
|
37
|
+
let inflight;
|
|
38
|
+
async function fetchToken() {
|
|
39
|
+
const assertion = typeof opts.assertion === "string" ? opts.assertion : await opts.assertion();
|
|
40
|
+
if (!assertion.trim())
|
|
41
|
+
throw new PipelinesAuthError("jwtBearer: the assertion is empty");
|
|
42
|
+
const form = new URLSearchParams();
|
|
43
|
+
form.set("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer");
|
|
44
|
+
form.set("assertion", assertion);
|
|
45
|
+
if (opts.scopes && opts.scopes.length > 0)
|
|
46
|
+
form.set("scope", opts.scopes.join(" "));
|
|
47
|
+
if (opts.resource?.trim())
|
|
48
|
+
form.set("resource", opts.resource.trim());
|
|
49
|
+
const startedAt = now();
|
|
50
|
+
let res;
|
|
51
|
+
try {
|
|
52
|
+
res = await doFetch(tokenUrl, {
|
|
53
|
+
method: "POST",
|
|
54
|
+
headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
|
|
55
|
+
body: form.toString(),
|
|
56
|
+
signal: AbortSignal.timeout(timeoutMs),
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
catch (err) {
|
|
60
|
+
throw new PipelinesAuthError("jwtBearer: calling the token endpoint failed", undefined, undefined, { cause: err });
|
|
61
|
+
}
|
|
62
|
+
const text = await res.text().catch(() => "");
|
|
63
|
+
if (!res.ok) {
|
|
64
|
+
// Status and OAuth error code only: the body may echo the request.
|
|
65
|
+
const code = oauthErrorCode(text);
|
|
66
|
+
throw new PipelinesAuthError(`jwtBearer: the token endpoint returned ${res.status}${code ? ` (${code})` : ""}`, res.status, code);
|
|
67
|
+
}
|
|
68
|
+
let body;
|
|
69
|
+
try {
|
|
70
|
+
body = JSON.parse(text);
|
|
71
|
+
}
|
|
72
|
+
catch {
|
|
73
|
+
throw new PipelinesAuthError("jwtBearer: the token response is not JSON", res.status);
|
|
74
|
+
}
|
|
75
|
+
if (typeof body.access_token !== "string" || !body.access_token) {
|
|
76
|
+
throw new PipelinesAuthError("jwtBearer: the token response has no access_token", res.status);
|
|
77
|
+
}
|
|
78
|
+
const lifetime = typeof body.expires_in === "number" && body.expires_in > 0 ? body.expires_in * 1000 : fallback;
|
|
79
|
+
return { accessToken: body.access_token, expiresAt: startedAt + lifetime };
|
|
80
|
+
}
|
|
81
|
+
function refresh() {
|
|
82
|
+
inflight ??= fetchToken().finally(() => {
|
|
83
|
+
inflight = undefined;
|
|
84
|
+
});
|
|
85
|
+
return inflight;
|
|
86
|
+
}
|
|
87
|
+
return {
|
|
88
|
+
get expiresAt() {
|
|
89
|
+
return cached?.expiresAt;
|
|
90
|
+
},
|
|
91
|
+
async token(signal) {
|
|
92
|
+
signal?.throwIfAborted();
|
|
93
|
+
if (cached && now() + skew < cached.expiresAt)
|
|
94
|
+
return cached.accessToken;
|
|
95
|
+
try {
|
|
96
|
+
const fresh = await abortable(refresh(), signal);
|
|
97
|
+
cached = fresh;
|
|
98
|
+
return fresh.accessToken;
|
|
99
|
+
}
|
|
100
|
+
catch (err) {
|
|
101
|
+
if (cached && now() < cached.expiresAt && !signal?.aborted)
|
|
102
|
+
return cached.accessToken;
|
|
103
|
+
throw err;
|
|
104
|
+
}
|
|
105
|
+
},
|
|
106
|
+
invalidate() {
|
|
107
|
+
cached = undefined;
|
|
108
|
+
},
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
/** The OAuth `error` member when it is a plain code, else undefined. */
|
|
112
|
+
function oauthErrorCode(body) {
|
|
113
|
+
try {
|
|
114
|
+
const doc = JSON.parse(body);
|
|
115
|
+
if (typeof doc.error === "string" && /^[a-z_]{1,64}$/.test(doc.error))
|
|
116
|
+
return doc.error;
|
|
117
|
+
}
|
|
118
|
+
catch {
|
|
119
|
+
// not JSON
|
|
120
|
+
}
|
|
121
|
+
return undefined;
|
|
122
|
+
}
|
|
123
|
+
/** Races a promise against a signal without cancelling the shared work. */
|
|
124
|
+
function abortable(p, signal) {
|
|
125
|
+
if (!signal)
|
|
126
|
+
return p;
|
|
127
|
+
return new Promise((resolve, reject) => {
|
|
128
|
+
const onAbort = () => reject(signal.reason);
|
|
129
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
130
|
+
p.then((v) => {
|
|
131
|
+
signal.removeEventListener("abort", onAbort);
|
|
132
|
+
resolve(v);
|
|
133
|
+
}, (e) => {
|
|
134
|
+
signal.removeEventListener("abort", onAbort);
|
|
135
|
+
reject(e instanceof Error ? e : new Error(String(e)));
|
|
136
|
+
});
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
//# sourceMappingURL=auth.js.map
|
package/dist/auth.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import type { JsonObject, MessageInitShape } from "@bufbuild/protobuf";
|
|
2
|
+
import type { Client, Transport } from "@connectrpc/connect";
|
|
3
|
+
import type { RunState } from "./gen/xeonr/pipelines/v1/common_pb.js";
|
|
4
|
+
import type { Definition } from "./gen/xeonr/pipelines/v1/definition_pb.js";
|
|
5
|
+
import { DefinitionSchema } from "./gen/xeonr/pipelines/v1/definition_pb.js";
|
|
6
|
+
import { RunsService } from "./gen/xeonr/pipelines/v1/runs_pb.js";
|
|
7
|
+
import type { Exclusion, ExclusionSchema, GetRunGraphResponse, Run } from "./gen/xeonr/pipelines/v1/runs_pb.js";
|
|
8
|
+
import type { Connection } from "./transport.js";
|
|
9
|
+
/** Options for {@link PipelinesClient}: how to reach pipelines-api. */
|
|
10
|
+
export type PipelinesClientOptions = Connection & {
|
|
11
|
+
/** Bound on each call. Default 30 s. */
|
|
12
|
+
timeoutMs?: number;
|
|
13
|
+
};
|
|
14
|
+
/** What {@link PipelinesClient.createRun} takes. */
|
|
15
|
+
export interface CreateRunInput {
|
|
16
|
+
/**
|
|
17
|
+
* Makes the create safe to repeat, per calling product: a repeat returns
|
|
18
|
+
* the first run with `deduplicated` set.
|
|
19
|
+
*/
|
|
20
|
+
idempotencyKey: string;
|
|
21
|
+
/** The team the run belongs to: `urn:xeonr:auth:team:<uuid>`. */
|
|
22
|
+
tenant: string;
|
|
23
|
+
/** What the run is about. */
|
|
24
|
+
resource: {
|
|
25
|
+
kind: string;
|
|
26
|
+
id: string;
|
|
27
|
+
json?: JsonObject;
|
|
28
|
+
};
|
|
29
|
+
/** The definition to run, as a message or its init shape. */
|
|
30
|
+
definition: Definition | MessageInitShape<typeof DefinitionSchema>;
|
|
31
|
+
/** Facts about the run the product vouches for (tiers and secret policies read them). */
|
|
32
|
+
attestedFacts?: JsonObject;
|
|
33
|
+
/** Per-run values, read as `${{ variables.<name> }}`. Never secrets. */
|
|
34
|
+
variables?: JsonObject;
|
|
35
|
+
/** Makes runs sharing a key mutually exclusive (milestone 2). */
|
|
36
|
+
exclusion?: Exclusion | MessageInitShape<typeof ExclusionSchema>;
|
|
37
|
+
}
|
|
38
|
+
/** What {@link PipelinesClient.createJob} takes. */
|
|
39
|
+
export interface CreateJobInput {
|
|
40
|
+
/** The team the job belongs to: `urn:xeonr:auth:team:<uuid>`. */
|
|
41
|
+
tenant: string;
|
|
42
|
+
/** The worker handler to run, `<namespace>/<name>`. */
|
|
43
|
+
handler: string;
|
|
44
|
+
/** The handler's inputs, by input name. At most 256 KiB encoded. */
|
|
45
|
+
payload?: JsonObject;
|
|
46
|
+
/** Holds the job back: it is not offered to a worker earlier. At most a year. */
|
|
47
|
+
delayMs?: number;
|
|
48
|
+
/** Makes the create safe to repeat, per calling product. */
|
|
49
|
+
idempotencyKey: string;
|
|
50
|
+
/** What the job is about, if anything. */
|
|
51
|
+
resource?: {
|
|
52
|
+
kind: string;
|
|
53
|
+
id: string;
|
|
54
|
+
json?: JsonObject;
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
/** A created run, and whether the idempotency key had been seen. */
|
|
58
|
+
export interface CreatedRun {
|
|
59
|
+
run: Run;
|
|
60
|
+
/** The key was seen before and `run` is the one the first call made. */
|
|
61
|
+
deduplicated: boolean;
|
|
62
|
+
}
|
|
63
|
+
/** What {@link PipelinesClient.listRuns} takes. */
|
|
64
|
+
export interface ListRunsInput {
|
|
65
|
+
tenant: string;
|
|
66
|
+
resource?: {
|
|
67
|
+
kind: string;
|
|
68
|
+
id: string;
|
|
69
|
+
};
|
|
70
|
+
states?: RunState[];
|
|
71
|
+
cursor?: string;
|
|
72
|
+
limit?: number;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* The public-API client a product uses to start runs and jobs and to read
|
|
76
|
+
* what became of them (`RunsService`). It calls with the product's Auth
|
|
77
|
+
* service-account token (scopes `pipelines:run:edit` and
|
|
78
|
+
* `pipelines:run:read`).
|
|
79
|
+
*
|
|
80
|
+
* Every method is a single RPC; errors are the API's `ConnectError`s,
|
|
81
|
+
* classified by {@link errorKind}.
|
|
82
|
+
*/
|
|
83
|
+
export declare class PipelinesClient {
|
|
84
|
+
/** The generated RunsService client, for anything not wrapped here. */
|
|
85
|
+
readonly runs: Client<typeof RunsService>;
|
|
86
|
+
/** The transport, to build other generated clients on. */
|
|
87
|
+
readonly transport: Transport;
|
|
88
|
+
private readonly timeoutMs;
|
|
89
|
+
constructor(opts: PipelinesClientOptions);
|
|
90
|
+
/**
|
|
91
|
+
* Creates a run of a definition (`CreateRun`). Worker nodes name a handler
|
|
92
|
+
* (`{ id, action: { case: "handler", value: "acme/resize" } }`); they mix
|
|
93
|
+
* freely with image nodes in one run.
|
|
94
|
+
*/
|
|
95
|
+
createRun(input: CreateRunInput, signal?: AbortSignal): Promise<CreatedRun>;
|
|
96
|
+
/**
|
|
97
|
+
* Enqueues a job: one run of one worker handler (`CreateJob`, the plan's
|
|
98
|
+
* `EnqueueJob`). With `delayMs` it stays `QUEUED` and is not offered to a
|
|
99
|
+
* worker before the delay has passed.
|
|
100
|
+
*/
|
|
101
|
+
createJob(input: CreateJobInput, signal?: AbortSignal): Promise<CreatedRun>;
|
|
102
|
+
/** Reads one run (`GetRun`). */
|
|
103
|
+
getRun(runId: string, signal?: AbortSignal): Promise<Run>;
|
|
104
|
+
/** Reads a run with its frozen definition and every node's attempts and outputs (`GetRunGraph`). */
|
|
105
|
+
getRunGraph(runId: string, signal?: AbortSignal): Promise<GetRunGraphResponse>;
|
|
106
|
+
/** Lists a tenant's runs, newest first (`ListRuns`). */
|
|
107
|
+
listRuns(input: ListRunsInput, signal?: AbortSignal): Promise<{
|
|
108
|
+
runs: Run[];
|
|
109
|
+
nextCursor: string;
|
|
110
|
+
}>;
|
|
111
|
+
/**
|
|
112
|
+
* Asks a run to stop (`CancelRun`). Running attempts are told on their next
|
|
113
|
+
* heartbeat; an SDK worker aborts the handler's signal. Idempotent.
|
|
114
|
+
*/
|
|
115
|
+
cancelRun(runId: string, reason?: string, signal?: AbortSignal): Promise<Run>;
|
|
116
|
+
private opts;
|
|
117
|
+
}
|
|
118
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|