@xeonr/pipelines-sdk 0.0.0-stage → 0.2.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 +334 -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 +129 -0
  7. package/dist/client.d.ts.map +1 -0
  8. package/dist/client.js +106 -0
  9. package/dist/client.js.map +1 -0
  10. package/dist/errors.d.ts +113 -0
  11. package/dist/errors.d.ts.map +1 -0
  12. package/dist/errors.js +115 -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 +1061 -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 +221 -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 +580 -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 +483 -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 +762 -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 +919 -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 +272 -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 +1237 -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 +647 -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 +30 -0
  79. package/dist/index.d.ts.map +1 -0
  80. package/dist/index.js +24 -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 +117 -0
  87. package/dist/logship.d.ts.map +1 -0
  88. package/dist/logship.js +319 -0
  89. package/dist/logship.js.map +1 -0
  90. package/dist/testing/index.d.ts +215 -0
  91. package/dist/testing/index.d.ts.map +1 -0
  92. package/dist/testing/index.js +1015 -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 +236 -0
  99. package/dist/worker.d.ts.map +1 -0
  100. package/dist/worker.js +733 -0
  101. package/dist/worker.js.map +1 -0
  102. package/package.json +70 -3
package/README.md CHANGED
@@ -1,3 +1,335 @@
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. Each `Worker` has
98
+ its own instance id (`worker.workerId`, a UUID), which it claims with
99
+ and echoes in `AttemptRef.worker_id` on every later call, so one
100
+ replica cannot write to another's attempt.
101
+ 2. **Start.** It calls `StartAttempt`. Your code runs only after that succeeds.
102
+ 3. **Heartbeat.** It renews the lease at the interval the claim gives, from
103
+ the claim until completion.
104
+ 4. **Run.** It calls your handler with an `AbortSignal`. The signal fires
105
+ with an `AttemptAbortedError` whose `cause` says why:
106
+ - `cancelled`: a heartbeat answered cancel;
107
+ - `deadline`: the node's timeout passed;
108
+ - `lost`: the lease was lost;
109
+ - `shutdown`: `stop()` ran past its timeout.
110
+ 5. **Log.** `ctx.log` ships the attempt's log in order with `AppendLogs`,
111
+ idempotent on seq, and honours the attempt's log cap. If the server lost
112
+ chunks it had acknowledged, it says so with `out_of_range` naming the seq
113
+ it expects: the worker resends from there if it still holds them, and
114
+ otherwise carries on from that seq after one line saying how many bytes
115
+ of output were lost.
116
+ 6. **Complete.** It calls `CompleteAttempt` with the kv outputs inline, or
117
+ with a termination:
118
+
119
+ | How the handler ended | Termination | Failure class (set by the platform) |
120
+ |---|---|---|
121
+ | Returned outputs | `EXITED` (0) | none |
122
+ | Threw or rejected; `parseInput` threw | `HANDLER_ERROR`, kind from the error (below) | `HANDLER_ERROR` |
123
+ | Returned outputs that are not valid kv | `HANDLER_ERROR`, kind `PERMANENT` | `HANDLER_ERROR` |
124
+ | Still running at its deadline | `TIMED_OUT` | `TIMEOUT` |
125
+ | Stopped after a cancel | `CANCELLED` | `CANCELLED` |
126
+ | Aborted by `stop()` past its timeout | `INTERRUPTED` | `INTERRUPTED` |
127
+ | Lease lost | nothing reported | `ABANDONED`, decided by the platform |
128
+
129
+ The platform picks the failure class and decides whether to retry, using the
130
+ node's `retry.when`. By default it retries only transient classes:
131
+ `ABANDONED`, `RUNNER_CRASHED`, `IMAGE_PULL`, `STAGING_FAILED`, `INTERRUPTED`
132
+ and `INTERNAL`.
133
+
134
+ A handler says whether its failure can pass by what it throws. The class
135
+ stays `HANDLER_ERROR` either way; this sets
136
+ `CompleteAttemptRequest.handler_failure_kind`:
137
+
138
+ ```ts
139
+ import { PermanentError, TransientError } from "@xeonr/pipelines-sdk";
140
+
141
+ if (res.status === 503) throw new TransientError("mail service unavailable"); // retried under the default policy
142
+ if (res.status === 422) throw new PermanentError("template not found"); // never retried, whatever retry.when says
143
+ throw new Error("anything else"); // unspecified: retry.when alone decides
144
+ ```
145
+
146
+ The marker is found on the thrown error or anywhere in its `cause` chain, so
147
+ wrapping one (`new Error("send failed", { cause: new PermanentError(...) })`)
148
+ keeps it. A worker can narrow a node's policy this way, never widen it: an
149
+ explicit `retry.when` still applies to a `TransientError`, and `retry.max`
150
+ and backoff bound every retry.
151
+
152
+ A thrown error or rejected promise fails that attempt, never the process.
153
+ JavaScript cannot kill a handler that ignores its signal. Such a handler gets
154
+ the cancel grace (or `stop`'s `graceMs`). After that its slot is freed and
155
+ anything it does later is ignored.
156
+
157
+ ### Errors from pipelines-api
158
+
159
+ The worker reads each error by its Connect code (`errorKind`):
160
+
161
+ - `failed_precondition`: the attempt is no longer this worker's. The handler
162
+ is aborted (`lost`) and nothing more is reported.
163
+ - `invalid_argument` on `StartAttempt` or `CompleteAttempt`: final, not
164
+ retried.
165
+ - `unauthenticated` or `permission_denied`: not transient. The worker stops
166
+ claiming, calls `onError`, and `wait()` rejects once in-flight attempts end.
167
+ - `out_of_range` on `AppendLogs`: not fatal. It names the seq the server
168
+ expects, and the log resends or renumbers from there (see step 5). An
169
+ `out_of_range` that names no seq drops the rest of that attempt's log; the
170
+ attempt carries on.
171
+ - Anything else (`unavailable`, `deadline_exceeded`, `internal`, network
172
+ errors): retried with backoff. A heartbeat that cannot get through before
173
+ the lease runs out loses the attempt.
174
+
175
+ ### Graceful shutdown
176
+
177
+ `stop({ timeoutMs, graceMs })` works in four steps:
178
+
179
+ 1. It stops claiming and aborts any held long-polls.
180
+ 2. Attempts that were claimed but never started are handed back with
181
+ `ReleaseAttempt`. They are offered again at once, to any worker, as the
182
+ same attempt, with nothing spent. A release answered `failed_precondition`
183
+ was no longer this worker's, which counts as done.
184
+ 3. Running handlers get `timeoutMs` to finish (default 30 s). Their real
185
+ outcome is reported.
186
+ 4. Handlers still running after that are aborted with `shutdown`. They get
187
+ `graceMs` more (default 5 s), then their attempts are completed with
188
+ `TERMINATION_INTERRUPTED`. That is transient, so the platform retries it by
189
+ default. On a node marked `interruptible`, the retry does not count
190
+ against `retry.max`.
191
+
192
+ ## Enqueue jobs and start runs
193
+
194
+ ```ts
195
+ import { FailureClass, PipelinesClient } from "@xeonr/pipelines-sdk";
196
+
197
+ const pipelines = new PipelinesClient({ baseUrl: "https://pipelines.xeonr.io", token });
198
+
199
+ // One handler, run once: CreateJob (the plan's EnqueueJob). Idempotent per product.
200
+ const { run } = await pipelines.createJob({
201
+ tenant: TEAM,
202
+ handler: "acme/send-email",
203
+ payload: { to: "ada@example.com", template: "welcome" },
204
+ idempotencyKey: "welcome-email:user-4821",
205
+ delayMs: 10 * 60_000, // not offered to a worker before ten minutes have passed
206
+ retry: { max: 3, when: [FailureClass.HANDLER_ERROR] }, // the job's node policy; unset is the platform default
207
+ timeoutMs: 5 * 60_000, // bounds one attempt
208
+ });
209
+
210
+ // A full run that mixes an image node and a worker node, passing an output between them.
211
+ await pipelines.createRun({
212
+ idempotencyKey: "thumbs:upload-91",
213
+ tenant: TEAM,
214
+ resource: { kind: "acme.upload", id: "upload-91" },
215
+ definition: {
216
+ nodes: [
217
+ { id: "extract", action: { case: "uses", value: { name: "acme/extract", version: "1.0.0" } } },
218
+ {
219
+ id: "notify",
220
+ action: { case: "handler", value: "acme/send-email" },
221
+ needs: [{ node: "extract" }], // a reference adds no edge: name the node in needs
222
+ with: { to: { kind: { case: "stringValue", value: "${{ steps.extract.outputs.kv.owner }}" } } },
223
+ retry: { max: 3, when: [FailureClass.HANDLER_ERROR] },
224
+ },
225
+ ],
226
+ },
227
+ });
228
+
229
+ await pipelines.getRun(run.id);
230
+ await pipelines.cancelRun(run.id, "superseded");
231
+ ```
232
+
233
+ `pipelines.runs` is the generated `RunsService` client, for anything not
234
+ wrapped. The generated messages are importable from
235
+ `@xeonr/pipelines-sdk/gen/xeonr/pipelines/v1/*_pb`.
236
+
237
+ ## Test your handlers: `@xeonr/pipelines-sdk/testing`
238
+
239
+ `FakePipelines` is an in-memory pipelines-api: a real Connect router behind an
240
+ in-memory transport. The real `Worker` and `PipelinesClient` run against it
241
+ unchanged.
242
+
243
+ ```ts
244
+ import { FakePipelines, FAKE_TENANT } from "@xeonr/pipelines-sdk/testing";
245
+
246
+ const fake = new FakePipelines({ leaseMs: 600, heartbeatIntervalMs: 50 });
247
+ const worker = new Worker({ transport: fake.transport(), tenant: FAKE_TENANT, pool: { name: "test" } });
248
+ worker.handle(sendEmail);
249
+ await worker.start();
250
+
251
+ const client = new PipelinesClient({ transport: fake.transport() });
252
+ const { run } = await client.createJob({ tenant: FAKE_TENANT, handler: "acme/send-email", idempotencyKey: "t1", payload: { to: "a@b", template: "x" } });
253
+ const done = await fake.waitForRun(run.id);
254
+ expect(done.nodes.get("job")!.kv).toEqual({ messageId: "…" });
255
+
256
+ await worker.stop();
257
+ fake.close();
258
+ ```
259
+
260
+ The fake models:
261
+
262
+ - accounts (a token with a tenant and scopes), and namespace and pool
263
+ ownership;
264
+ - publish, pools, jobs with delay, idempotency, retry and timeout, and runs
265
+ (references only into a node's needs closure);
266
+ - the claim long-poll, the worker id on every ref, leases and their lapse
267
+ (`expireLease`), `ReleaseAttempt`, heartbeats and cancel;
268
+ - logs, with `out_of_range` naming the expected seq for a gap, and
269
+ `loseLogChunks` to play a server that lost acknowledged chunks;
270
+ - the server's mapping from termination to failure class,
271
+ `handler_failure_kind`, retries by class, and free interruptions on an
272
+ `interruptible` node;
273
+ - external (image) nodes you settle with `completeNode`;
274
+ - error injection (`inject("Heartbeat", Code.Unavailable, 2)`).
275
+
276
+ It does not model secrets, blobs, tiers or routing between pools.
277
+
278
+ ## Conformance suite
279
+
280
+ `src/conformance/suite.ts` holds the cases both SDKs must pass against
281
+ pipelines-api. The Go SDK runs the same list (`xeonr/pipelines/sdk-go`,
282
+ `CONFORMANCE.md`):
283
+
284
+ 1. enqueue
285
+ 2. delayed job
286
+ 3. retry by class
287
+ 4. permanent failure
288
+ 5. cancel
289
+ 6. lease loss
290
+ 7. release on shutdown
291
+ 8. another owner's handler unclaimable
292
+
293
+ The cases run against the fake in every `pnpm test`. To run them against a
294
+ real pipelines-api, set these variables (otherwise the suite is skipped):
295
+
296
+ | Variable | Value |
297
+ |---|---|
298
+ | `PIPELINES_API_URL` | the api's base URL |
299
+ | `PIPELINES_TOKEN` | an access token; or `PIPELINES_SA_ASSERTION` with `PIPELINES_TOKEN_URL` |
300
+ | `PIPELINES_TENANT` | the owner's team URN |
301
+ | `PIPELINES_NAMESPACE` | a registry namespace that team owns |
302
+ | `PIPELINES_OTHER_TOKEN`, `PIPELINES_OTHER_TENANT` | optional: a second product, for the ownership case |
303
+ | `PIPELINES_LEASE_MS` | optional: the server's lease, default 60000 |
304
+
305
+ ```sh
306
+ PIPELINES_API_URL=... PIPELINES_TOKEN=... PIPELINES_TENANT=... PIPELINES_NAMESPACE=... pnpm vitest run src/conformance/api.test.ts
307
+ ```
308
+
309
+ ## Dependencies
310
+
311
+ | Package | Why |
312
+ |---|---|
313
+ | `@connectrpc/connect-node` (dependency) | the Connect transport over Node's HTTP |
314
+ | `@connectrpc/connect`, `@bufbuild/protobuf` (peers) | the generated clients and messages; peers, so your app has one copy |
315
+
316
+ Nothing else at runtime. The token exchange uses the global `fetch`.
317
+
318
+ ## Development
319
+
320
+ ```sh
321
+ pnpm install
322
+ pnpm typecheck && pnpm lint && pnpm test && pnpm build
323
+ ```
324
+
325
+ The Connect code is generated from the BSR before every typecheck, lint, test
326
+ and build. The modules are `proto.prod.wtf/xeonr/pipelines` and
327
+ `xeonr/pipelines-private`, pinned in `buf.gen.yaml`. Nothing generated is
328
+ committed (`ui.no-generated-code`). Log in once with
329
+ `buf registry login proto.prod.wtf`. To pick up a contract change, bump the
330
+ pins in `buf.gen.yaml`.
331
+
332
+ Releasing means bumping `version` in `package.json` on `main`. CI publishes
333
+ any version the registry does not have yet.
334
+
335
+ 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":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA0BjD,kCAAkC;AAClC,MAAM,UAAU,WAAW,CAAC,CAAgB;IAC1C,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE,CAAC;QAC5B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO;QACL,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;QAClC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,EAAE;KACnC,CAAC;AACJ,CAAC;AA6CD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,IAAsB;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IACtC,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;IACtE,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QACjE,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,MAAM,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,IAAI,CAAC,GAAG,MAAM,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAEjC,IAAI,MAA0B,CAAC;IAC/B,IAAI,QAAqC,CAAC;IAE1C,KAAK,UAAU,UAAU;QACvB,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/F,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,kBAAkB,CAAC,mCAAmC,CAAC,CAAC;QACzF,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;QACnC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,6CAA6C,CAAC,CAAC;QACtE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACpF,IAAI,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAEtE,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;QACxB,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE;gBAC5B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,EAAE,kBAAkB,EAAE;gBAC5F,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE;gBACrB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,kBAAkB,CAAC,8CAA8C,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACrH,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,mEAAmE;YACnE,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,IAAI,kBAAkB,CAC1B,0CAA0C,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EACjF,GAAG,CAAC,MAAM,EACV,IAAI,CACL,CAAC;QACJ,CAAC;QACD,IAAI,IAAsD,CAAC;QAC3D,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAgB,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,kBAAkB,CAAC,2CAA2C,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YAChE,MAAM,IAAI,kBAAkB,CAAC,mDAAmD,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAChG,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;QAChH,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,EAAE,SAAS,GAAG,QAAQ,EAAE,CAAC;IAC7E,CAAC;IAED,SAAS,OAAO;QACd,QAAQ,KAAK,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACrC,QAAQ,GAAG,SAAS,CAAC;QACvB,CAAC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO;QACL,IAAI,SAAS;YACX,OAAO,MAAM,EAAE,SAAS,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,MAAoB;YAC9B,MAAM,EAAE,cAAc,EAAE,CAAC;YACzB,IAAI,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,GAAG,MAAM,CAAC,SAAS;gBAAE,OAAO,MAAM,CAAC,WAAW,CAAC;YACzE,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;gBACjD,MAAM,GAAG,KAAK,CAAC;gBACf,OAAO,KAAK,CAAC,WAAW,CAAC;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,OAAO;oBAAE,OAAO,MAAM,CAAC,WAAW,CAAC;gBACtF,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,UAAU;YACR,MAAM,GAAG,SAAS,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAwB,CAAC;QACpD,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC,KAAK,CAAC;IAC1F,CAAC;IAAC,MAAM,CAAC;QACP,WAAW;IACb,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,2EAA2E;AAC3E,SAAS,SAAS,CAAI,CAAa,EAAE,MAAoB;IACvD,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IACtB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAe,CAAC,CAAC;QACrD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC,CAAC,IAAI,CACJ,CAAC,CAAC,EAAE,EAAE;YACJ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,CAAC,CAAC,CAAC,CAAC;QACb,CAAC,EACD,CAAC,CAAU,EAAE,EAAE;YACb,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,MAAM,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}