@xeonr/pipelines-sdk 0.1.0 → 0.3.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 (106) hide show
  1. package/README.md +247 -24
  2. package/dist/client.d.ts +73 -3
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +48 -1
  5. package/dist/client.js.map +1 -1
  6. package/dist/errors.d.ts +42 -6
  7. package/dist/errors.d.ts.map +1 -1
  8. package/dist/errors.js +45 -2
  9. package/dist/errors.js.map +1 -1
  10. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.d.ts +173 -12
  11. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.d.ts.map +1 -1
  12. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.js +45 -28
  13. package/dist/gen/xeonr/pipelines/private/v1/attempt_pb.js.map +1 -1
  14. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.d.ts +136 -17
  15. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.d.ts.map +1 -1
  16. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.js +42 -35
  17. package/dist/gen/xeonr/pipelines/private/v1/step_local_pb.js.map +1 -1
  18. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.d.ts +346 -15
  19. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.d.ts.map +1 -1
  20. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.js +105 -10
  21. package/dist/gen/xeonr/pipelines/private/v1/worker_pb.js.map +1 -1
  22. package/dist/gen/xeonr/pipelines/v1/common_pb.d.ts +38 -6
  23. package/dist/gen/xeonr/pipelines/v1/common_pb.d.ts.map +1 -1
  24. package/dist/gen/xeonr/pipelines/v1/common_pb.js +37 -5
  25. package/dist/gen/xeonr/pipelines/v1/common_pb.js.map +1 -1
  26. package/dist/gen/xeonr/pipelines/v1/definition_pb.d.ts +280 -5
  27. package/dist/gen/xeonr/pipelines/v1/definition_pb.d.ts.map +1 -1
  28. package/dist/gen/xeonr/pipelines/v1/definition_pb.js +100 -7
  29. package/dist/gen/xeonr/pipelines/v1/definition_pb.js.map +1 -1
  30. package/dist/gen/xeonr/pipelines/v1/pipelines_pb.d.ts +1100 -0
  31. package/dist/gen/xeonr/pipelines/v1/pipelines_pb.d.ts.map +1 -0
  32. package/dist/gen/xeonr/pipelines/v1/pipelines_pb.js +298 -0
  33. package/dist/gen/xeonr/pipelines/v1/pipelines_pb.js.map +1 -0
  34. package/dist/gen/xeonr/pipelines/v1/pools_pb.d.ts +120 -1
  35. package/dist/gen/xeonr/pipelines/v1/pools_pb.d.ts.map +1 -1
  36. package/dist/gen/xeonr/pipelines/v1/pools_pb.js +36 -11
  37. package/dist/gen/xeonr/pipelines/v1/pools_pb.js.map +1 -1
  38. package/dist/gen/xeonr/pipelines/v1/queues_pb.d.ts +769 -0
  39. package/dist/gen/xeonr/pipelines/v1/queues_pb.d.ts.map +1 -0
  40. package/dist/gen/xeonr/pipelines/v1/queues_pb.js +190 -0
  41. package/dist/gen/xeonr/pipelines/v1/queues_pb.js.map +1 -0
  42. package/dist/gen/xeonr/pipelines/v1/registry_pb.d.ts +60 -0
  43. package/dist/gen/xeonr/pipelines/v1/registry_pb.d.ts.map +1 -1
  44. package/dist/gen/xeonr/pipelines/v1/registry_pb.js +21 -16
  45. package/dist/gen/xeonr/pipelines/v1/registry_pb.js.map +1 -1
  46. package/dist/gen/xeonr/pipelines/v1/runs_pb.d.ts +867 -4
  47. package/dist/gen/xeonr/pipelines/v1/runs_pb.d.ts.map +1 -1
  48. package/dist/gen/xeonr/pipelines/v1/runs_pb.js +243 -27
  49. package/dist/gen/xeonr/pipelines/v1/runs_pb.js.map +1 -1
  50. package/dist/gen/xeonr/pipelines/v1/schedules_pb.d.ts +1110 -0
  51. package/dist/gen/xeonr/pipelines/v1/schedules_pb.d.ts.map +1 -0
  52. package/dist/gen/xeonr/pipelines/v1/schedules_pb.js +295 -0
  53. package/dist/gen/xeonr/pipelines/v1/schedules_pb.js.map +1 -0
  54. package/dist/gen/xeonr/pipelines/v1/secrets_pb.d.ts +8 -3
  55. package/dist/gen/xeonr/pipelines/v1/secrets_pb.d.ts.map +1 -1
  56. package/dist/gen/xeonr/pipelines/v1/secrets_pb.js +1 -1
  57. package/dist/gen/xeonr/pipelines/v1/secrets_pb.js.map +1 -1
  58. package/dist/gen/xeonr/platform/v1/options_pb.d.ts +123 -1
  59. package/dist/gen/xeonr/platform/v1/options_pb.d.ts.map +1 -1
  60. package/dist/gen/xeonr/platform/v1/options_pb.js +90 -1
  61. package/dist/gen/xeonr/platform/v1/options_pb.js.map +1 -1
  62. package/dist/handler.d.ts +50 -0
  63. package/dist/handler.d.ts.map +1 -1
  64. package/dist/handler.js +27 -0
  65. package/dist/handler.js.map +1 -1
  66. package/dist/index.d.ts +13 -1
  67. package/dist/index.d.ts.map +1 -1
  68. package/dist/index.js +7 -1
  69. package/dist/index.js.map +1 -1
  70. package/dist/logship.d.ts +60 -10
  71. package/dist/logship.d.ts.map +1 -1
  72. package/dist/logship.js +171 -28
  73. package/dist/logship.js.map +1 -1
  74. package/dist/queues.d.ts +171 -0
  75. package/dist/queues.d.ts.map +1 -0
  76. package/dist/queues.js +135 -0
  77. package/dist/queues.js.map +1 -0
  78. package/dist/reporter.d.ts +120 -0
  79. package/dist/reporter.d.ts.map +1 -0
  80. package/dist/reporter.js +323 -0
  81. package/dist/reporter.js.map +1 -0
  82. package/dist/schedules.d.ts +201 -0
  83. package/dist/schedules.d.ts.map +1 -0
  84. package/dist/schedules.js +127 -0
  85. package/dist/schedules.js.map +1 -0
  86. package/dist/testing/cron.d.ts +33 -0
  87. package/dist/testing/cron.d.ts.map +1 -0
  88. package/dist/testing/cron.js +177 -0
  89. package/dist/testing/cron.js.map +1 -0
  90. package/dist/testing/index.d.ts +142 -4
  91. package/dist/testing/index.d.ts.map +1 -1
  92. package/dist/testing/index.js +843 -44
  93. package/dist/testing/index.js.map +1 -1
  94. package/dist/testing/queues.d.ts +46 -0
  95. package/dist/testing/queues.d.ts.map +1 -0
  96. package/dist/testing/queues.js +70 -0
  97. package/dist/testing/queues.js.map +1 -0
  98. package/dist/testing/schedules.d.ts +113 -0
  99. package/dist/testing/schedules.d.ts.map +1 -0
  100. package/dist/testing/schedules.js +419 -0
  101. package/dist/testing/schedules.js.map +1 -0
  102. package/dist/worker.d.ts +78 -8
  103. package/dist/worker.d.ts.map +1 -1
  104. package/dist/worker.js +163 -33
  105. package/dist/worker.js.map +1 -1
  106. package/package.json +1 -1
package/README.md CHANGED
@@ -94,7 +94,10 @@ Pass `register: false` and `pool.id` if something else does that.
94
94
 
95
95
  1. **Claim.** It long-polls `ClaimAttempts` for its handlers. No claim is
96
96
  allowed to push the worker past its overall `concurrency` or a handler's
97
- `concurrency`: each poll reserves its slots up front.
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.
98
101
  2. **Start.** It calls `StartAttempt`. Your code runs only after that succeeds.
99
102
  3. **Heartbeat.** It renews the lease at the interval the claim gives, from
100
103
  the claim until completion.
@@ -105,25 +108,46 @@ Pass `register: false` and `pool.id` if something else does that.
105
108
  - `lost`: the lease was lost;
106
109
  - `shutdown`: `stop()` ran past its timeout.
107
110
  5. **Log.** `ctx.log` ships the attempt's log in order with `AppendLogs`,
108
- idempotent on seq, and honours the attempt's log cap.
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.
109
116
  6. **Complete.** It calls `CompleteAttempt` with the kv outputs inline, or
110
117
  with a termination:
111
118
 
112
119
  | How the handler ended | Termination | Failure class (set by the platform) |
113
120
  |---|---|---|
114
121
  | Returned outputs | `EXITED` (0) | none |
115
- | Threw or rejected; outputs not valid kv; `parseInput` threw | `HANDLER_ERROR` | `HANDLER_ERROR` |
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` |
116
124
  | Still running at its deadline | `TIMED_OUT` | `TIMEOUT` |
117
125
  | 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 |
126
+ | Aborted by `stop()` past its timeout | `INTERRUPTED` | `INTERRUPTED` |
127
+ | Lease lost | nothing reported | `ABANDONED`, decided by the platform; run again automatically only on an `interruptible` node or job |
120
128
 
121
129
  The platform picks the failure class and decides whether to retry, using the
122
130
  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).
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.
127
151
 
128
152
  A thrown error or rejected promise fails that attempt, never the process.
129
153
  JavaScript cannot kill a handler that ignores its signal. Such a handler gets
@@ -140,8 +164,10 @@ The worker reads each error by its Connect code (`errorKind`):
140
164
  retried.
141
165
  - `unauthenticated` or `permission_denied`: not transient. The worker stops
142
166
  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.
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.
145
171
  - Anything else (`unavailable`, `deadline_exceeded`, `internal`, network
146
172
  errors): retried with backoff. A heartbeat that cannot get through before
147
173
  the lease runs out loses the attempt.
@@ -151,13 +177,139 @@ The worker reads each error by its Connect code (`errorKind`):
151
177
  `stop({ timeoutMs, graceMs })` works in four steps:
152
178
 
153
179
  1. It stops claiming and aborts any held long-polls.
154
- 2. In-flight handlers get `timeoutMs` to finish (default 30 s). Their real
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
155
185
  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.
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
+ ### Stages, progress, issues and spans
193
+
194
+ A handler can tell the console how far it has got, and what went wrong with
195
+ individual items, without failing:
196
+
197
+ ```ts
198
+ export const scanLibrary = defineHandler<{ libraryId: string }>({
199
+ name: "acme/scan-library",
200
+ version: "2.0.0",
201
+ title: "Scan library",
202
+ // Published in the manifest, so a console draws every stage before the attempt starts.
203
+ stages: [
204
+ { key: "read", name: "Reading folders" },
205
+ { key: "probe", name: "Probing files", weight: 4 }, // dominates the overall bar
206
+ ],
207
+ async run(ctx) {
208
+ ctx.stage("read");
209
+ const files = await listFiles(ctx.input.libraryId);
210
+ ctx.stage("probe"); // finishes "read"
211
+ for (const [i, f] of files.entries()) {
212
+ await ctx.span("probe", async (span) => {
213
+ span.setAttribute("file", f.path);
214
+ try {
215
+ await probe(f);
216
+ } catch (err) {
217
+ ctx.issue({ severity: "warning", subject: f.path, subjectKind: "media.file", subjectId: f.id, message: `${f.path} could not be probed` });
218
+ }
219
+ });
220
+ ctx.progress({ processed: i + 1, total: files.length });
221
+ }
222
+ },
223
+ });
224
+ ```
225
+
226
+ - **`ctx.stage(key)`** enters a stage and finishes the one before it. The
227
+ last stage is finished as `SUCCEEDED` when the handler returns, or
228
+ `FAILED` when it fails. A key the handler does not declare is added at run
229
+ time with weight 0. The calls are `WorkerService.SetProgress` with `stage`.
230
+ - **`ctx.progress({ processed, total, failed, fraction, message })`** is
231
+ coalesced: the latest value about once a second (`reportIntervalMs`), and
232
+ a forced final report before the attempt completes.
233
+ - **`ctx.issue({ severity, subject, subjectKind, subjectId, message, detail })`**
234
+ is batched, up to 100 per `AppendIssues`. The run carries the counts by
235
+ severity, and `client.listIssues(runId)` reads them.
236
+ - **`ctx.span(name, fn, attributes?)`** records an OpenTelemetry-shaped span
237
+ of the attempt's trace (`ReportSpans`). Spans nest with `span.span(...)`,
238
+ and a throw marks a span `error`. `client.getRunTrace(runId)` reads the
239
+ whole trace.
240
+
241
+ None of this can fail a handler. Every error sending progress, issues or
242
+ spans is logged at debug and dropped.
243
+
244
+ ## Queues
245
+
246
+ Jobs are admitted through queues: lanes with limits and fairness between
247
+ tenants. A queue is not where work runs; pools and workers are. A job with no
248
+ `queue` goes to the product's `default` queue, which has no limits until the
249
+ product sets one.
250
+
251
+ ```ts
252
+ const worker = new Worker({
253
+ baseUrl, token, tenant: TEAM, pool: { name: "acme-app" },
254
+ // Declared at start with SetQueue, every writable field replaced; a pause survives.
255
+ queues: [
256
+ { name: "emails", maxConcurrency: 20, maxConcurrencyPerTenant: 5, rateLimit: { limit: 100, windowMs: 60_000 } },
257
+ { name: "imports", maxConcurrency: 2, defaultRetry: { max: 3, when: [FailureClass.HANDLER_ERROR] }, defaultTimeoutMs: 30 * 60_000 },
258
+ ],
259
+ });
260
+
261
+ await pipelines.createJob({ tenant: TEAM, handler: "acme/send-email", idempotencyKey: "welcome:4821", queue: "emails" });
262
+ ```
263
+
264
+ - An unknown queue name is `not_found`. A `retry` or `timeoutMs` over the
265
+ queue's `defaultRetry` / `defaultTimeoutMs` is `invalid_argument`. When
266
+ unset, the queue's defaults apply.
267
+ - **`QueuesClient`** has `setQueue`, `getQueue`, `listQueues`, `pauseQueue`,
268
+ `resumeQueue`, `getQueueStats`, `listQueueJobs`, `deleteQueue` and
269
+ `requeueJob`. `declareQueues(client, decls)` is the helper the worker uses.
270
+ Queues belong to the product (the Auth application id): the worker reads it
271
+ from its token's `urn:xeonr:auth:application_id`, or takes `product`.
272
+ - **Dead letters.** `listQueueJobs(id, { states: [RunState.FAILED] })` lists
273
+ them, and `requeueJob(runId)` (`RetryNode` on node `job`) offers one again on
274
+ its queue.
275
+ - **Fairness.** The next claim goes to the eligible tenant with the fewest
276
+ running attempts in the queue; ties go to the longest-waiting job.
277
+
278
+ `createJob` also takes `interruptible: true` for a handler that is safe to
279
+ run again from the start. A worker shutting down then spends no retry on it,
280
+ and a worker that vanished (`ABANDONED`) gets it run again. The platform
281
+ re-runs an abandoned attempt only for an interruptible node.
282
+
283
+ ## Schedules
284
+
285
+ ```ts
286
+ const worker = new Worker({
287
+ baseUrl, token, tenant: TEAM, pool: { name: "acme-app" },
288
+ schedules: [
289
+ // Each occurrence of the cron, in its time zone, starts a job to one of this worker's handlers.
290
+ { name: "reports.daily", cron: "0 4 * * *", cronLabel: "Every day at 4am", timeZone: "Europe/London", tenant: TEAM, job: { handler: "acme/report" } },
291
+ // Fan out: the enumeration handler returns the targets at each occurrence.
292
+ { name: "servers.backup", cron: "*/30 * * * *", tenant: TEAM, job: { handler: "acme/backup" }, enumerate: { handler: "acme/list-servers" } },
293
+ ],
294
+ });
295
+ worker.handle(report).handle(backup).handle(
296
+ defineEnumerator({ name: "acme/list-servers", version: "1.0.0", run: async () => (await servers()).map((s) => ({ key: `server:${s.id}`, args: { id: s.id } })) }),
297
+ );
298
+ ```
299
+
300
+ - A schedule whose job or enumeration handler the worker does not register
301
+ is refused at `start()`, before anything is published.
302
+ - The platform's rules: one run per occurrence and target, however many
303
+ replicas evaluate it. After an outage, only the latest missed occurrence
304
+ within `catchupWindowMs` fires (`misfire`). A target with a run still
305
+ pending is skipped unless `queueWhilePending`. An owner's override of the
306
+ cron or enabled flag survives redeclaration.
307
+ - **`SchedulesClient`** has `setSchedule`, `getSchedule`, `listSchedules`,
308
+ `setScheduleOverride`, `pauseSchedule`, `resumeSchedule`, `deleteSchedule`,
309
+ `runScheduleNow` and `listScheduleOccurrences`. `declareSchedules` is the
310
+ helper.
311
+ - `SchedulesService` is not served by pipelines-api's `main` yet. The client
312
+ is built to the contract, and the fake implements it.
161
313
 
162
314
  ## Enqueue jobs and start runs
163
315
 
@@ -173,6 +325,9 @@ const { run } = await pipelines.createJob({
173
325
  payload: { to: "ada@example.com", template: "welcome" },
174
326
  idempotencyKey: "welcome-email:user-4821",
175
327
  delayMs: 10 * 60_000, // not offered to a worker before ten minutes have passed
328
+ queue: "emails", // admitted through this product queue (see Queues)
329
+ retry: { max: 3, when: [FailureClass.HANDLER_ERROR] }, // the job's node policy; unset is the platform default
330
+ timeoutMs: 5 * 60_000, // bounds one attempt
176
331
  });
177
332
 
178
333
  // A full run that mixes an image node and a worker node, passing an output between them.
@@ -186,6 +341,7 @@ await pipelines.createRun({
186
341
  {
187
342
  id: "notify",
188
343
  action: { case: "handler", value: "acme/send-email" },
344
+ needs: [{ node: "extract" }], // a reference adds no edge: name the node in needs
189
345
  with: { to: { kind: { case: "stringValue", value: "${{ steps.extract.outputs.kv.owner }}" } } },
190
346
  retry: { max: 3, when: [FailureClass.HANDLER_ERROR] },
191
347
  },
@@ -193,6 +349,15 @@ await pipelines.createRun({
193
349
  },
194
350
  });
195
351
 
352
+ // A published version of a stored pipeline instead of an inline definition.
353
+ await pipelines.createRun({
354
+ idempotencyKey: "nightly:2026-11-12",
355
+ tenant: TEAM,
356
+ resource: { kind: "acme.library", id: "lib-7" },
357
+ pipeline: { name: "nightly-scan", scope: { kind: "acme.library", id: "lib-7" } }, // version 0: the latest
358
+ variables: { depth: 2 },
359
+ });
360
+
196
361
  await pipelines.getRun(run.id);
197
362
  await pipelines.cancelRun(run.id, "superseded");
198
363
  ```
@@ -228,16 +393,74 @@ The fake models:
228
393
 
229
394
  - accounts (a token with a tenant and scopes), and namespace and pool
230
395
  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;
396
+ - publish, pools, jobs with delay, idempotency, retry and timeout, and runs
397
+ (references only into a node's needs closure);
398
+ - the claim long-poll, the worker id on every ref, leases and their lapse
399
+ (`expireLease`), `ReleaseAttempt`, heartbeats and cancel;
400
+ - logs, with `out_of_range` naming the expected seq for a gap, and
401
+ `loseLogChunks` to play a server that lost acknowledged chunks;
402
+ - the server's mapping from termination to failure class,
403
+ `handler_failure_kind`, retries by class, and free interruptions on an
404
+ `interruptible` node;
237
405
  - external (image) nodes you settle with `completeNode`;
238
406
  - error injection (`inject("Heartbeat", Code.Unavailable, 2)`).
239
407
 
240
- It does not model secrets, blobs, tiers or routing between pools.
408
+ It also models queues (limits, pause, rate limits, fairness, dead letters),
409
+ issues, staged progress, spans and the run trace, and schedules on a clock
410
+ you control:
411
+
412
+ ```ts
413
+ fake.clock.set(new Date("2026-11-12T03:59:30Z"));
414
+ fake.clock.advance(60_000); // fires the 04:00 occurrence
415
+ fake.schedules.occurrences(scheduleId); // what fired, skipped or was refused
416
+ ```
417
+
418
+ Like the api, the fake refuses payload keys the handler's manifest does not
419
+ declare as inputs. It retries an `ABANDONED` attempt only on an
420
+ interruptible node.
421
+
422
+ It does not model secrets, blobs, tiers, routing between pools or stored
423
+ pipelines.
424
+
425
+ ## Conformance suite
426
+
427
+ `src/conformance/suite.ts` holds the cases both SDKs must pass against
428
+ pipelines-api, with the ids of the Go SDK's `CONFORMANCE.md`
429
+ (`xeonr/pipelines/sdk-go`):
430
+
431
+ | Id | Case |
432
+ |---|---|
433
+ | C1 | Enqueue runs a job in-process (idempotent, kv output, log line) |
434
+ | C2 | A delayed job does not start early |
435
+ | C3 | Retry by class (transient-marked, unmarked, listed) |
436
+ | C4 | A permanent failure is not retried |
437
+ | C5 | A cancel stops the handler |
438
+ | C6 | A lost lease is retried on another replica (an interruptible job) |
439
+ | C7 | Shutdown releases unstarted attempts |
440
+ | C8 | Another owner's handlers are unclaimable |
441
+ | C9 | A job is admitted through the queue it names |
442
+ | C10 | An unknown queue name is `not_found` |
443
+ | C11 | A retry or timeout over the queue's ceiling is `invalid_argument` |
444
+ | C12 | `max_concurrency 1` holds across two workers |
445
+ | C13 | A paused queue starts nothing until resumed |
446
+ | C14 | A dead letter is listed and requeued |
447
+
448
+ The cases run against the fake in every `pnpm test`. To run them against a
449
+ real pipelines-api, set these variables (otherwise the suite is skipped):
450
+
451
+ | Variable | Value |
452
+ |---|---|
453
+ | `PIPELINES_API_URL` | the api's base URL |
454
+ | `PIPELINES_TOKEN` | an access token; or `PIPELINES_SA_ASSERTION` with `PIPELINES_TOKEN_URL` |
455
+ | `PIPELINES_TENANT` | the owner's team URN |
456
+ | `PIPELINES_NAMESPACE` | optional: a registry namespace the team owns or may claim, default `sdkconf` |
457
+ | `PIPELINES_PRODUCT` | optional: the owner's product, default read from the token |
458
+ | `PIPELINES_OTHER_TOKEN`, `PIPELINES_OTHER_TENANT` | optional: another team's service account, for C8 |
459
+ | `PIPELINES_LEASE_MS` | optional: the server's lease, default 60000 |
460
+
461
+ ```sh
462
+ PIPELINES_API_URL=... PIPELINES_TOKEN=... PIPELINES_TENANT=... pnpm vitest run src/conformance/api.test.ts
463
+ ```
241
464
 
242
465
  ## Dependencies
243
466
 
package/dist/client.d.ts CHANGED
@@ -1,10 +1,12 @@
1
1
  import type { JsonObject, MessageInitShape } from "@bufbuild/protobuf";
2
2
  import type { Client, Transport } from "@connectrpc/connect";
3
3
  import type { RunState } from "./gen/xeonr/pipelines/v1/common_pb.js";
4
+ import type { IssueSeverity } from "./gen/xeonr/pipelines/v1/runs_pb.js";
4
5
  import type { Definition } from "./gen/xeonr/pipelines/v1/definition_pb.js";
5
6
  import { DefinitionSchema } from "./gen/xeonr/pipelines/v1/definition_pb.js";
7
+ import type { RetrySchema } from "./gen/xeonr/pipelines/v1/definition_pb.js";
6
8
  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";
9
+ import type { Exclusion, ExclusionSchema, GetRunGraphResponse, GetRunTraceResponse, Run, RunIssue } from "./gen/xeonr/pipelines/v1/runs_pb.js";
8
10
  import type { Connection } from "./transport.js";
9
11
  /** Options for {@link PipelinesClient}: how to reach pipelines-api. */
10
12
  export type PipelinesClientOptions = Connection & {
@@ -26,8 +28,29 @@ export interface CreateRunInput {
26
28
  id: string;
27
29
  json?: JsonObject;
28
30
  };
29
- /** The definition to run, as a message or its init shape. */
30
- definition: Definition | MessageInitShape<typeof DefinitionSchema>;
31
+ /**
32
+ * The definition to run, as a message or its init shape. Give this or
33
+ * `pipeline`.
34
+ */
35
+ definition?: Definition | MessageInitShape<typeof DefinitionSchema>;
36
+ /**
37
+ * A published version of a stored pipeline (PipelinesService) to run
38
+ * instead of an inline definition: by id, or by its tenant, scope and
39
+ * name; `version` 0 (the default) runs the latest. Its declared variables
40
+ * are checked and defaulted by the platform.
41
+ */
42
+ pipeline?: {
43
+ id: string;
44
+ version?: number;
45
+ } | {
46
+ name: string;
47
+ scope: {
48
+ kind: string;
49
+ id: string;
50
+ };
51
+ product?: string;
52
+ version?: number;
53
+ };
31
54
  /** Facts about the run the product vouches for (tiers and secret policies read them). */
32
55
  attestedFacts?: JsonObject;
33
56
  /** Per-run values, read as `${{ variables.<name> }}`. Never secrets. */
@@ -53,6 +76,28 @@ export interface CreateJobInput {
53
76
  id: string;
54
77
  json?: JsonObject;
55
78
  };
79
+ /**
80
+ * The job's retry policy, as a node's `retry`. Unset is the platform's
81
+ * default: transient classes only, which retries a handler error only when
82
+ * the worker marked it transient (`TransientError`). List
83
+ * `FailureClass.HANDLER_ERROR` in `when` to retry every handler error; a
84
+ * `PermanentError` is still never retried. `max` is at most 10.
85
+ */
86
+ retry?: MessageInitShape<typeof RetrySchema>;
87
+ /** Bounds one attempt from its start. Unset is the queue's default, then the platform's. */
88
+ timeoutMs?: number;
89
+ /**
90
+ * The queue the job is admitted through, among this product's queues (the
91
+ * tenant's own of that name, else the product-wide one). Unset is the
92
+ * product's `default` queue. An unknown name is `not_found`; a `retry` or
93
+ * `timeoutMs` over the queue's ceiling is `invalid_argument`.
94
+ */
95
+ queue?: string;
96
+ /**
97
+ * The handler is safe to run again from the start: an attempt its worker
98
+ * stops by shutting down is offered again without spending a retry.
99
+ */
100
+ interruptible?: boolean;
56
101
  }
57
102
  /** A created run, and whether the idempotency key had been seen. */
58
103
  export interface CreatedRun {
@@ -112,6 +157,31 @@ export declare class PipelinesClient {
112
157
  * Asks a run to stop (`CancelRun`). Running attempts are told on their next
113
158
  * heartbeat; an SDK worker aborts the handler's signal. Idempotent.
114
159
  */
160
+ /**
161
+ * Lists a run's issues (`ListIssues`): the non-fatal problems its steps
162
+ * reported, oldest first, optionally narrowed to a node, an attempt or a
163
+ * least severity. `Run` carries their counts.
164
+ */
165
+ listIssues(runId: string, input?: {
166
+ nodeId?: string;
167
+ attemptId?: string;
168
+ minSeverity?: IssueSeverity;
169
+ cursor?: string;
170
+ limit?: number;
171
+ }, signal?: AbortSignal): Promise<{
172
+ issues: RunIssue[];
173
+ nextCursor: string;
174
+ }>;
175
+ /** Reads a run's trace (`GetRunTrace`): the platform's spans and those steps and handlers reported. */
176
+ getRunTrace(runId: string, input?: {
177
+ nodeId?: string;
178
+ attemptId?: string;
179
+ }, signal?: AbortSignal): Promise<GetRunTraceResponse>;
180
+ /**
181
+ * Runs one node of a finished run again (`RetryNode`). On a job (node
182
+ * `job`) this requeues a dead letter on its queue.
183
+ */
184
+ retryNode(runId: string, nodeId: string, signal?: AbortSignal): Promise<Run>;
115
185
  cancelRun(runId: string, reason?: string, signal?: AbortSignal): Promise<Run>;
116
186
  private opts;
117
187
  }
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGvE,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAkB,QAAQ,EAAE,MAAM,uCAAuC,CAAC;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAE/I,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,uEAAuE;AACvE,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG;IAChD,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC;IAC1D;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC,OAAO,gBAAgB,CAAC,CAAC;IACpE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxI,yFAAyF;IACzF,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,iEAAiE;IACjE,SAAS,CAAC,EAAE,SAAS,GAAG,gBAAgB,CAAC,OAAO,eAAe,CAAC,CAAC;CAClE;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC;IAC3D;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,WAAW,CAAC,CAAC;IAC7C,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,GAAG,CAAC;IACT,wEAAwE;IACxE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;IAC1C,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,EAAE,sBAAsB;IAMxC;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAgBjF;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAyBjF,gCAAgC;IAC1B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAI/D,oGAAoG;IAC9F,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIpF,wDAAwD;IAClD,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAcxG;;;OAGG;IACH;;;;OAIG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,KAAK,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,aAAa,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,EACjH,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAetD,uGAAuG;IACjG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIzI;;;OAGG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAI5E,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAInF,OAAO,CAAC,IAAI;CAGb"}
package/dist/client.js CHANGED
@@ -34,7 +34,7 @@ export class PipelinesClient {
34
34
  idempotencyKey: input.idempotencyKey,
35
35
  tenant: input.tenant,
36
36
  resource: resource(input.resource),
37
- source: { case: "inlineDefinition", value: create(DefinitionSchema, input.definition) },
37
+ source: runSource(input),
38
38
  ...(input.attestedFacts ? { attestedFacts: input.attestedFacts } : {}),
39
39
  ...(input.variables ? { variables: input.variables } : {}),
40
40
  ...(input.exclusion ? { exclusion: input.exclusion } : {}),
@@ -50,6 +50,9 @@ export class PipelinesClient {
50
50
  if (input.delayMs !== undefined && (input.delayMs < 0 || !Number.isFinite(input.delayMs))) {
51
51
  throw new RangeError("createJob: delayMs must be a finite, non-negative number");
52
52
  }
53
+ if (input.timeoutMs !== undefined && (input.timeoutMs <= 0 || !Number.isFinite(input.timeoutMs))) {
54
+ throw new RangeError("createJob: timeoutMs must be a finite, positive number");
55
+ }
53
56
  const res = await this.runs.createJob({
54
57
  tenant: input.tenant,
55
58
  handler: input.handler,
@@ -57,6 +60,10 @@ export class PipelinesClient {
57
60
  ...(input.payload ? { payload: input.payload } : {}),
58
61
  ...(input.delayMs ? { delay: durationFromMs(input.delayMs) } : {}),
59
62
  ...(input.resource ? { resource: resource(input.resource) } : {}),
63
+ ...(input.retry ? { retry: input.retry } : {}),
64
+ ...(input.queue ? { queue: input.queue } : {}),
65
+ ...(input.interruptible ? { interruptible: true } : {}),
66
+ ...(input.timeoutMs ? { timeout: durationFromMs(input.timeoutMs) } : {}),
60
67
  }, this.opts(signal));
61
68
  return { run: required(res.run), deduplicated: res.deduplicated };
62
69
  }
@@ -83,6 +90,33 @@ export class PipelinesClient {
83
90
  * Asks a run to stop (`CancelRun`). Running attempts are told on their next
84
91
  * heartbeat; an SDK worker aborts the handler's signal. Idempotent.
85
92
  */
93
+ /**
94
+ * Lists a run's issues (`ListIssues`): the non-fatal problems its steps
95
+ * reported, oldest first, optionally narrowed to a node, an attempt or a
96
+ * least severity. `Run` carries their counts.
97
+ */
98
+ async listIssues(runId, input = {}, signal) {
99
+ const res = await this.runs.listIssues({
100
+ runId,
101
+ nodeId: input.nodeId ?? "",
102
+ attemptId: input.attemptId ?? "",
103
+ minSeverity: input.minSeverity ?? 0,
104
+ cursor: input.cursor ?? "",
105
+ limit: input.limit ?? 0,
106
+ }, this.opts(signal));
107
+ return { issues: res.issues, nextCursor: res.nextCursor };
108
+ }
109
+ /** Reads a run's trace (`GetRunTrace`): the platform's spans and those steps and handlers reported. */
110
+ async getRunTrace(runId, input = {}, signal) {
111
+ return this.runs.getRunTrace({ runId, nodeId: input.nodeId ?? "", attemptId: input.attemptId ?? "" }, this.opts(signal));
112
+ }
113
+ /**
114
+ * Runs one node of a finished run again (`RetryNode`). On a job (node
115
+ * `job`) this requeues a dead letter on its queue.
116
+ */
117
+ async retryNode(runId, nodeId, signal) {
118
+ return required((await this.runs.retryNode({ runId, nodeId }, this.opts(signal))).run);
119
+ }
86
120
  async cancelRun(runId, reason, signal) {
87
121
  return required((await this.runs.cancelRun({ runId, ...(reason ? { reason } : {}) }, this.opts(signal))).run);
88
122
  }
@@ -98,4 +132,17 @@ function required(run) {
98
132
  throw new Error("pipelines-api answered without a run");
99
133
  return run;
100
134
  }
135
+ function runSource(input) {
136
+ if (input.definition && input.pipeline)
137
+ throw new TypeError("createRun: give definition or pipeline, not both");
138
+ if (input.definition)
139
+ return { case: "inlineDefinition", value: create(DefinitionSchema, input.definition) };
140
+ const p = input.pipeline;
141
+ if (!p)
142
+ throw new TypeError("createRun: definition or pipeline is required");
143
+ const pipeline = "id" in p
144
+ ? { case: "pipelineId", value: p.id }
145
+ : { case: "byName", value: { tenant: input.tenant, product: p.product ?? "", scope: p.scope, name: p.name } };
146
+ return { case: "pipeline", value: { pipeline, version: p.version ?? 0 } };
147
+ }
101
148
  //# sourceMappingURL=client.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAE7E,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAElE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AA8F7C;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAe;IAC1B,uEAAuE;IAC9D,IAAI,CAA6B;IAC1C,0DAA0D;IACjD,SAAS,CAAY;IACb,SAAS,CAAS;IAEnC,YAAY,IAA4B;QACtC,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACtD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,KAAqB,EAAE,MAAoB;QACzD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CACnC;YACE,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;YAClC,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC;YACxB,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,EACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAClB,CAAC;QACF,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,KAAqB,EAAE,MAAoB;QACzD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YAC1F,MAAM,IAAI,UAAU,CAAC,0DAA0D,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YACjG,MAAM,IAAI,UAAU,CAAC,wDAAwD,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CACnC;YACE,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzE,EACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAClB,CAAC;QACF,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC;IACpE,CAAC;IAED,gCAAgC;IAChC,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,MAAoB;QAC9C,OAAO,QAAQ,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,oGAAoG;IACpG,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,MAAoB;QACnD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,QAAQ,CAAC,KAAoB,EAAE,MAAoB;QACvD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAClC;YACE,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/C,EACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAClB,CAAC;QACF,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;IACxD,CAAC;IAED;;;OAGG;IACH;;;;OAIG;IACH,KAAK,CAAC,UAAU,CACd,KAAa,EACb,QAA+G,EAAE,EACjH,MAAoB;QAEpB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CACpC;YACE,KAAK;YACL,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;YAC1B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,EAAE;YAChC,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,CAAC;YACnC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;YAC1B,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;SACxB,EACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAClB,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;IAC5D,CAAC;IAED,uGAAuG;IACvG,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,QAAiD,EAAE,EAAE,MAAoB;QACxG,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3H,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,MAAc,EAAE,MAAoB;QACjE,OAAO,QAAQ,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACzF,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,MAAe,EAAE,MAAoB;QAClE,OAAO,QAAQ,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChH,CAAC;IAEO,IAAI,CAAC,MAAoB;QAC/B,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACtE,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,CAAkD;IAClE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,SAAS,QAAQ,CAAC,GAAoB;IACpC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAClE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,SAAS,CAAC,KAAqB;IACtC,IAAI,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAC;IAChH,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,kBAA2B,EAAE,KAAK,EAAE,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;IACtH,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;IACzB,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IAC7E,MAAM,QAAQ,GACZ,IAAI,IAAI,CAAC;QACP,CAAC,CAAC,EAAE,IAAI,EAAE,YAAqB,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE;QAC9C,CAAC,CAAC,EAAE,IAAI,EAAE,QAAiB,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3H,OAAO,EAAE,IAAI,EAAE,UAAmB,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,CAAC,EAAE,EAAE,CAAC;AACrF,CAAC"}
package/dist/errors.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { HandlerFailureKind } from "./gen/xeonr/pipelines/private/v1/worker_pb.js";
1
2
  /**
2
3
  * How the SDK treats an error from pipelines-api, decided by its Connect
3
4
  * code. The rules are the API's (WorkerService's comments, and what the api
@@ -8,8 +9,9 @@
8
9
  * work on it and report nothing more.
9
10
  * - `final`: `invalid_argument`, `not_found`, `already_exists`,
10
11
  * `unimplemented`, `out_of_range`. Repeating the same request cannot
11
- * succeed; the caller decides what that means for its operation (for
12
- * `out_of_range` on AppendLogs, it is not fatal to the attempt).
12
+ * succeed; the caller decides what that means for its operation. On
13
+ * AppendLogs, `out_of_range` names the seq the server expects and the log
14
+ * shipper resends or renumbers from it; it is never fatal to the attempt.
13
15
  * - `auth`: `unauthenticated`, `permission_denied`. Not transient: the
14
16
  * credential or its scopes are wrong. A worker stops claiming and surfaces
15
17
  * it.
@@ -51,8 +53,9 @@ export declare class AttemptAbortedError extends Error {
51
53
  * - `lost`: the attempt is no longer this worker's (lease lost). Nothing
52
54
  * the handler returns is reported.
53
55
  * - `shutdown`: the worker is stopping and its shutdown timeout passed.
54
- * The attempt is completed as a worker failure, which the platform
55
- * retries by default.
56
+ * The attempt is completed with `TERMINATION_INTERRUPTED`, which the
57
+ * platform retries by default (and, on an `interruptible` node,
58
+ * without spending the retry budget).
56
59
  */
57
60
  readonly cause: "cancelled" | "deadline" | "lost" | "shutdown";
58
61
  readonly name = "AttemptAbortedError";
@@ -65,8 +68,9 @@ export declare class AttemptAbortedError extends Error {
65
68
  * - `lost`: the attempt is no longer this worker's (lease lost). Nothing
66
69
  * the handler returns is reported.
67
70
  * - `shutdown`: the worker is stopping and its shutdown timeout passed.
68
- * The attempt is completed as a worker failure, which the platform
69
- * retries by default.
71
+ * The attempt is completed with `TERMINATION_INTERRUPTED`, which the
72
+ * platform retries by default (and, on an `interruptible` node,
73
+ * without spending the retry budget).
70
74
  */
71
75
  cause: "cancelled" | "deadline" | "lost" | "shutdown", message: string);
72
76
  }
@@ -74,4 +78,36 @@ export declare class AttemptAbortedError extends Error {
74
78
  export declare class WorkerStartError extends Error {
75
79
  readonly name = "WorkerStartError";
76
80
  }
81
+ /** Brands a thrown value with a failure kind, across duplicate copies of this package. */
82
+ declare const FAILURE_KIND: unique symbol;
83
+ /**
84
+ * Throw from a handler when the failure will not pass on a retry: a payload
85
+ * that fails validation, a 4xx from a downstream service. The attempt is
86
+ * completed with `handler_failure_kind = PERMANENT` and is not retried,
87
+ * whatever the node's `Retry.when` lists (a worker can narrow the policy,
88
+ * never widen it). The class stays `FAILURE_CLASS_HANDLER_ERROR`.
89
+ */
90
+ export declare class PermanentError extends Error {
91
+ readonly name: string;
92
+ readonly [FAILURE_KIND]: "permanent";
93
+ }
94
+ /**
95
+ * Throw from a handler when the failure may pass on its own: a downstream
96
+ * timeout, a 503. The attempt is completed with
97
+ * `handler_failure_kind = TRANSIENT`, so the platform's default policy
98
+ * retries it; an explicit `Retry.when` applies as written, and `Retry.max`
99
+ * and backoff bound it as always.
100
+ */
101
+ export declare class TransientError extends Error {
102
+ readonly name: string;
103
+ readonly [FAILURE_KIND]: "transient";
104
+ }
105
+ /**
106
+ * The handler failure kind a thrown value carries: PERMANENT for a
107
+ * {@link PermanentError}, TRANSIENT for a {@link TransientError} (or any
108
+ * error branded by another copy of this package), UNSPECIFIED otherwise. An
109
+ * error wrapped as the `cause` of another counts too.
110
+ */
111
+ export declare function handlerFailureKind(err: unknown): HandlerFailureKind;
112
+ export {};
77
113
  //# sourceMappingURL=errors.d.ts.map