@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.
Files changed (102) hide show
  1. package/README.md +267 -2
  2. package/dist/auth.d.ts +72 -0
  3. package/dist/auth.d.ts.map +1 -0
  4. package/dist/auth.js +139 -0
  5. package/dist/auth.js.map +1 -0
  6. package/dist/client.d.ts +118 -0
  7. package/dist/client.d.ts.map +1 -0
  8. package/dist/client.js +101 -0
  9. package/dist/client.js.map +1 -0
  10. package/dist/errors.d.ts +77 -0
  11. package/dist/errors.d.ts.map +1 -0
  12. package/dist/errors.js +72 -0
  13. package/dist/errors.js.map +1 -0
  14. package/dist/gen/buf/validate/validate_pb.d.ts +4828 -0
  15. package/dist/gen/buf/validate/validate_pb.d.ts.map +1 -0
  16. package/dist/gen/buf/validate/validate_pb.js +357 -0
  17. package/dist/gen/buf/validate/validate_pb.js.map +1 -0
  18. package/dist/gen/gnostic/openapi/v3/annotations_pb.d.ts +24 -0
  19. package/dist/gen/gnostic/openapi/v3/annotations_pb.d.ts.map +1 -0
  20. package/dist/gen/gnostic/openapi/v3/annotations_pb.js +37 -0
  21. package/dist/gen/gnostic/openapi/v3/annotations_pb.js.map +1 -0
  22. package/dist/gen/gnostic/openapi/v3/openapiv3_pb.d.ts +2245 -0
  23. package/dist/gen/gnostic/openapi/v3/openapiv3_pb.d.ts.map +1 -0
  24. package/dist/gen/gnostic/openapi/v3/openapiv3_pb.js +410 -0
  25. package/dist/gen/gnostic/openapi/v3/openapiv3_pb.js.map +1 -0
  26. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.d.ts +1031 -0
  27. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.d.ts.map +1 -0
  28. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.js +219 -0
  29. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.js.map +1 -0
  30. package/dist/gen/xeonr/pipelines/private/v1/runners_pb.d.ts +190 -0
  31. package/dist/gen/xeonr/pipelines/private/v1/runners_pb.d.ts.map +1 -0
  32. package/dist/gen/xeonr/pipelines/private/v1/runners_pb.js +53 -0
  33. package/dist/gen/xeonr/pipelines/private/v1/runners_pb.js.map +1 -0
  34. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.d.ts +1161 -0
  35. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.d.ts.map +1 -0
  36. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.js +269 -0
  37. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.js.map +1 -0
  38. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.d.ts +915 -0
  39. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.d.ts.map +1 -0
  40. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.js +159 -0
  41. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.js.map +1 -0
  42. package/dist/gen/xeonr/pipelines/v1/common_pb.d.ts +550 -0
  43. package/dist/gen/xeonr/pipelines/v1/common_pb.d.ts.map +1 -0
  44. package/dist/gen/xeonr/pipelines/v1/common_pb.js +453 -0
  45. package/dist/gen/xeonr/pipelines/v1/common_pb.js.map +1 -0
  46. package/dist/gen/xeonr/pipelines/v1/definition_pb.d.ts +760 -0
  47. package/dist/gen/xeonr/pipelines/v1/definition_pb.d.ts.map +1 -0
  48. package/dist/gen/xeonr/pipelines/v1/definition_pb.js +190 -0
  49. package/dist/gen/xeonr/pipelines/v1/definition_pb.js.map +1 -0
  50. package/dist/gen/xeonr/pipelines/v1/pools_pb.d.ts +800 -0
  51. package/dist/gen/xeonr/pipelines/v1/pools_pb.d.ts.map +1 -0
  52. package/dist/gen/xeonr/pipelines/v1/pools_pb.js +247 -0
  53. package/dist/gen/xeonr/pipelines/v1/pools_pb.js.map +1 -0
  54. package/dist/gen/xeonr/pipelines/v1/registry_pb.d.ts +895 -0
  55. package/dist/gen/xeonr/pipelines/v1/registry_pb.d.ts.map +1 -0
  56. package/dist/gen/xeonr/pipelines/v1/registry_pb.js +277 -0
  57. package/dist/gen/xeonr/pipelines/v1/registry_pb.js.map +1 -0
  58. package/dist/gen/xeonr/pipelines/v1/runs_pb.d.ts +1217 -0
  59. package/dist/gen/xeonr/pipelines/v1/runs_pb.d.ts.map +1 -0
  60. package/dist/gen/xeonr/pipelines/v1/runs_pb.js +204 -0
  61. package/dist/gen/xeonr/pipelines/v1/runs_pb.js.map +1 -0
  62. package/dist/gen/xeonr/pipelines/v1/secrets_pb.d.ts +642 -0
  63. package/dist/gen/xeonr/pipelines/v1/secrets_pb.d.ts.map +1 -0
  64. package/dist/gen/xeonr/pipelines/v1/secrets_pb.js +181 -0
  65. package/dist/gen/xeonr/pipelines/v1/secrets_pb.js.map +1 -0
  66. package/dist/gen/xeonr/pipelines/v1/sinks_pb.d.ts +381 -0
  67. package/dist/gen/xeonr/pipelines/v1/sinks_pb.d.ts.map +1 -0
  68. package/dist/gen/xeonr/pipelines/v1/sinks_pb.js +145 -0
  69. package/dist/gen/xeonr/pipelines/v1/sinks_pb.js.map +1 -0
  70. package/dist/gen/xeonr/platform/v1/options_pb.d.ts +313 -0
  71. package/dist/gen/xeonr/platform/v1/options_pb.d.ts.map +1 -0
  72. package/dist/gen/xeonr/platform/v1/options_pb.js +235 -0
  73. package/dist/gen/xeonr/platform/v1/options_pb.js.map +1 -0
  74. package/dist/handler.d.ts +94 -0
  75. package/dist/handler.d.ts.map +1 -0
  76. package/dist/handler.js +18 -0
  77. package/dist/handler.js.map +1 -0
  78. package/dist/index.d.ts +29 -0
  79. package/dist/index.d.ts.map +1 -0
  80. package/dist/index.js +23 -0
  81. package/dist/index.js.map +1 -0
  82. package/dist/internal/time.d.ts +8 -0
  83. package/dist/internal/time.d.ts.map +1 -0
  84. package/dist/internal/time.js +25 -0
  85. package/dist/internal/time.js.map +1 -0
  86. package/dist/logship.d.ts +67 -0
  87. package/dist/logship.d.ts.map +1 -0
  88. package/dist/logship.js +176 -0
  89. package/dist/logship.js.map +1 -0
  90. package/dist/testing/index.d.ts +202 -0
  91. package/dist/testing/index.d.ts.map +1 -0
  92. package/dist/testing/index.js +909 -0
  93. package/dist/testing/index.js.map +1 -0
  94. package/dist/transport.d.ts +43 -0
  95. package/dist/transport.d.ts.map +1 -0
  96. package/dist/transport.js +44 -0
  97. package/dist/transport.js.map +1 -0
  98. package/dist/worker.d.ts +213 -0
  99. package/dist/worker.d.ts.map +1 -0
  100. package/dist/worker.js +664 -0
  101. package/dist/worker.js.map +1 -0
  102. package/package.json +70 -3
package/README.md CHANGED
@@ -1,3 +1,268 @@
1
- # Temporary Holding Version
1
+ # @xeonr/pipelines-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}
@@ -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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"}