@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 1,008 lines 31.8 KB
Raw
1 // Alchemy modifications are licensed under Apache-2.0.
2 // This file includes third-party code; see /THIRD_PARTY_LICENSES.md.
3 // Alchemy modifications: uses Effect Schema instead of Zod and Array<T> syntax for non-tuple arrays,
4 // and resolves Workflow storage paths from the Engine namespace uniqueKey used by cloudflare-runtime.
5 import { RpcTarget, WorkerEntrypoint } from "cloudflare:workers";
6 import * as Result from "effect/Result";
7 import * as Schema from "effect/Schema";
8 import { ms } from "itty-time";
9 import type {
10 DatabaseInstance,
11 DatabaseVersion,
12 DatabaseWorkflow,
13 Engine,
14 EngineLogs,
15 } from "./engine.ts";
16 import { InstanceEvent, instanceStatusName } from "./instance.ts";
17 import type { InstanceStatus as EngineInstanceStatus } from "./instance.ts";
18 import {
19 duplicateInstanceError,
20 isUserTriggeredDelete,
21 isUserTriggeredPause,
22 isUserTriggeredRestart,
23 createWorkflowError,
24 isUserTriggeredTerminate,
25 WorkflowError,
26 } from "./lib/errors.ts";
27 import {
28 isValidAddressableWorkflowInstanceId,
29 isValidWorkflowInstanceId,
30 } from "./lib/validators.ts";
31 import { parseWorkflowSubscriptionOptions } from "./subscription.ts";
32 import type { WorkflowSubscription, WorkflowSubscriptionOptions } from "./subscription.ts";
33 import type {
34 WorkflowInstanceModifier,
35 WorkflowIntrospectionOperation,
36 WorkflowIntrospectionStreamResult,
37 } from "./types.ts";
38
39 type Env = {
40 ENGINE: DurableObjectNamespace<Engine>;
41 BINDING_NAME: string;
42 WORKFLOW_NAME: string;
43 WORKFLOW_STORAGE?: Fetcher;
44 };
45
46 const STORAGE_DELETE_RETRY_INTERVAL_MS = 50;
47 const STORAGE_DELETE_RETRY_BUDGET_MS = 2_000;
48 const STORAGE_DELETE_MAX_RETRIES =
49 STORAGE_DELETE_RETRY_BUDGET_MS / STORAGE_DELETE_RETRY_INTERVAL_MS;
50
51 const pendingDeletes = new Map<string, Promise<boolean>>();
52
53 function getStorageUrl(workflowName: string, hexId: string): string {
54 if (/[\\/]/.test(workflowName) || workflowName.includes("\0") || !/^[a-f0-9]{64}$/i.test(hexId)) {
55 throw new Error("Invalid Workflow storage path");
56 }
57 // Alchemy modification: the Engine namespace's uniqueKey (and so its
58 // directory on disk) is `encodeURIComponent(workflowName)`, not Miniflare's
59 // `miniflare-workflows-${workflowName}`.
60 return `http://disk/${encodeURIComponent(encodeURIComponent(workflowName))}/${hexId}`;
61 }
62
63 async function removeFile(disk: Fetcher, url: string): Promise<boolean> {
64 for (let attempt = 0; ; attempt++) {
65 let isDirectory = false;
66 try {
67 const file = await disk.fetch(url, { method: "HEAD" });
68 if (file.status === 404) {
69 return false;
70 }
71 if (file.ok && file.headers.get("Content-Type") !== "application/octet-stream") {
72 isDirectory = true;
73 } else if (file.ok) {
74 const response = await disk.fetch(url, { method: "DELETE" });
75 if (response.ok || response.status === 404) {
76 return response.ok;
77 }
78 }
79 } catch (error) {
80 if (attempt === STORAGE_DELETE_MAX_RETRIES) {
81 throw error;
82 }
83 }
84 if (isDirectory) {
85 throw new Error("Refusing to delete a Workflow storage directory");
86 }
87 if (attempt === STORAGE_DELETE_MAX_RETRIES) {
88 throw new Error("Failed to delete Workflow storage file");
89 }
90 await scheduler.wait(STORAGE_DELETE_RETRY_INTERVAL_MS);
91 }
92 }
93
94 async function deleteWorkflowStorageFiles(
95 disk: Fetcher,
96 url: string,
97 deleted = false,
98 ): Promise<boolean> {
99 let failure: unknown;
100 for (const extension of [".sqlite", ".sqlite-shm", ".sqlite-wal"]) {
101 try {
102 const removed = await removeFile(disk, url + extension);
103 deleted ||= extension === ".sqlite" && removed;
104 } catch (error) {
105 failure ??= error;
106 }
107 }
108 if (failure !== undefined) {
109 throw failure;
110 }
111 return deleted;
112 }
113
114 /** Aborts local execution and serializes file cleanup with reuse of the same ID. */
115 export function deleteWorkflowStorage({
116 disk,
117 workflowName,
118 ctx,
119 hexId,
120 abort,
121 abortOnlyIfPersisted = false,
122 }: {
123 disk?: Fetcher;
124 workflowName: string;
125 ctx: ExecutionContext;
126 hexId: string;
127 abort: () => Promise<void>;
128 abortOnlyIfPersisted?: boolean;
129 }): Promise<boolean> {
130 if (disk === undefined) {
131 return abort().then(() => false);
132 }
133 const url = getStorageUrl(workflowName, hexId);
134 const previous = pendingDeletes.get(url);
135 const readyToDelete = (previous ?? Promise.resolve(false))
136 .catch(() => false)
137 .then(async (deleted) => {
138 if (
139 !abortOnlyIfPersisted ||
140 (await disk.fetch(url + ".sqlite", { method: "HEAD" })).status !== 404
141 ) {
142 await abort();
143 await scheduler.wait(100);
144 }
145 return deleted;
146 });
147 const cleanup = readyToDelete.then((deleted) => deleteWorkflowStorageFiles(disk, url, deleted));
148 const pendingDelete = readyToDelete.then(
149 () => cleanup,
150 () => previous ?? false,
151 );
152 pendingDeletes.set(url, pendingDelete);
153 ctx.waitUntil(
154 pendingDelete.then(
155 () => {
156 if (pendingDeletes.get(url) === pendingDelete) {
157 pendingDeletes.delete(url);
158 }
159 },
160 () => {},
161 ),
162 );
163 return cleanup;
164 }
165
166 /** Waits for queued file cleanup, retrying a failed cleanup once before reuse. */
167 async function waitForPersistedInstanceDelete(env: Env, id: string | undefined): Promise<void> {
168 if (id === undefined || env.WORKFLOW_STORAGE === undefined) {
169 return;
170 }
171
172 const hexId = env.ENGINE.idFromName(id).toString();
173 const url = getStorageUrl(env.WORKFLOW_NAME, hexId);
174 let retried = false;
175 let pending = pendingDeletes.get(url);
176 while (pending !== undefined) {
177 try {
178 await pending;
179 } catch (error) {
180 if (pendingDeletes.get(url) === pending) {
181 if (retried) {
182 throw error;
183 }
184 retried = true;
185 pendingDeletes.set(url, deleteWorkflowStorageFiles(env.WORKFLOW_STORAGE, url));
186 }
187 }
188 const latest = pendingDeletes.get(url);
189 if (latest === pending) {
190 pendingDeletes.delete(url);
191 return;
192 }
193 pending = latest;
194 }
195 }
196
197 /** Aborts an Engine object before removing its persistence files. */
198 async function deletePersistedInstance(env: Env, ctx: ExecutionContext, id: string): Promise<void> {
199 if (env.WORKFLOW_STORAGE === undefined) {
200 return;
201 }
202
203 const stub = env.ENGINE.get(env.ENGINE.idFromName(id));
204 await deleteWorkflowStorage({
205 disk: env.WORKFLOW_STORAGE,
206 workflowName: env.WORKFLOW_NAME,
207 ctx,
208 hexId: stub.id.toString(),
209 abort: async () => {
210 try {
211 await stub.unsafeAbort();
212 } catch {
213 // Aborting the Durable Object rejects its RPC.
214 }
215 },
216 });
217 }
218
219 type WorkflowIntrospectionSession = {
220 id: string;
221 operations: Array<WorkflowIntrospectionOperation>;
222 instanceIds: Array<string>;
223 };
224
225 // workerd may construct a fresh WorkflowBinding object for each RPC call. Store
226 // sessions at module scope so start/modify/get/dispose calls, and later
227 // WorkflowBinding.create() calls, all see the same active Workflow session.
228 const workflowIntrospectionSessions = new Map<string, WorkflowIntrospectionSession>();
229
230 function getWorkflowIntrospectionSession(
231 workflowName: string,
232 sessionId: string,
233 ): WorkflowIntrospectionSession {
234 const session = workflowIntrospectionSessions.get(workflowName);
235 if (session?.id !== sessionId) {
236 throw new Error(
237 `Workflow ${JSON.stringify(workflowName)} does not have an active introspection session for this introspector.`,
238 );
239 }
240 return session;
241 }
242
243 function isWorkflowIntrospectionStreamResult(
244 value: unknown,
245 ): value is WorkflowIntrospectionStreamResult {
246 return (
247 value !== null &&
248 typeof value === "object" &&
249 "__workflowIntrospectionStreamResult" in value &&
250 "chunks" in value &&
251 value.__workflowIntrospectionStreamResult === true &&
252 Array.isArray(value.chunks)
253 );
254 }
255
256 function createWorkflowIntrospectionReadableStream(
257 result: WorkflowIntrospectionStreamResult,
258 ): ReadableStream<Uint8Array> {
259 return new ReadableStream<Uint8Array>({
260 start(controller) {
261 for (const chunk of result.chunks) {
262 controller.enqueue(chunk.slice());
263 }
264 controller.close();
265 },
266 });
267 }
268
269 async function applyWorkflowIntrospectionOperation(
270 modifier: WorkflowInstanceModifier,
271 operation: WorkflowIntrospectionOperation,
272 ) {
273 switch (operation.type) {
274 case "disableSleeps":
275 await modifier.disableSleeps(operation.steps);
276 break;
277 case "disableRetryDelays":
278 await modifier.disableRetryDelays(operation.steps);
279 break;
280 case "mockStepResult":
281 await modifier.mockStepResult(
282 operation.step,
283 isWorkflowIntrospectionStreamResult(operation.stepResult)
284 ? createWorkflowIntrospectionReadableStream(operation.stepResult)
285 : operation.stepResult,
286 );
287 break;
288 case "mockStepError": {
289 const error = new Error(operation.error.message);
290 error.name = operation.error.name;
291 await modifier.mockStepError(operation.step, error, operation.times);
292 break;
293 }
294 case "forceStepTimeout":
295 await modifier.forceStepTimeout(operation.step, operation.times);
296 break;
297 case "mockEvent":
298 await modifier.mockEvent(operation.event);
299 break;
300 case "forceEventTimeout":
301 await modifier.forceEventTimeout(operation.step);
302 break;
303 }
304 }
305
306 // TODO(vaish): import from @cloudflare/workers-types once restart options are published
307 export interface RestartFromStep {
308 name: string;
309 count?: number;
310 type?: "do" | "sleep" | "waitForEvent";
311 }
312
313 export interface WorkflowInstanceTerminateOptions {
314 /**
315 * If true, run registered rollback handlers before terminating the instance.
316 */
317 rollback?: boolean;
318 }
319
320 export interface WorkflowInstanceRestartOptions {
321 from?: RestartFromStep;
322 }
323
324 export type WorkflowBatchCreateOptions =
325 | {
326 count: number;
327 params?: unknown;
328 retention?: WorkflowInstanceCreateOptions<unknown>["retention"];
329 locationHint?: WorkflowInstanceCreateOptions<unknown>["locationHint"];
330 instances?: never;
331 }
332 | {
333 instances: WorkflowInstanceCreateOptions<unknown>[];
334 count?: never;
335 params?: never;
336 retention?: never;
337 locationHint?: never;
338 };
339
340 export type WorkflowBatchCreateResult = {
341 created: { id: string }[];
342 errors: {
343 index: number;
344 id?: string;
345 code: number;
346 message: string;
347 }[];
348 };
349
350 // Numeric durations are whole milliseconds; both forms must be positive. A
351 // single refinement keeps one error message for every invalid duration.
352 const retentionDurationSchema = Schema.Union([Schema.Number, Schema.String]).check(
353 Schema.makeFilter(
354 (value) => {
355 if (typeof value === "number") return Number.isInteger(value) && value > 0;
356 try {
357 const duration = ms(value);
358 return Number.isFinite(duration) && duration > 0;
359 } catch {
360 return false;
361 }
362 },
363 {
364 message:
365 "Duration must be a number or a string in format '{{number}} {{unit}}' where unit is second(s), minute(s), etc.",
366 },
367 ),
368 );
369 const workflowInstanceCreateOptionsSchema = Schema.Struct({
370 id: Schema.optional(Schema.String),
371 params: Schema.optional(Schema.Unknown),
372 retention: Schema.optional(
373 Schema.Struct({
374 successRetention: Schema.optional(retentionDurationSchema),
375 errorRetention: Schema.optional(retentionDurationSchema),
376 }),
377 ),
378 locationHint: Schema.optional(
379 Schema.Literals([
380 "wnam",
381 "weur",
382 "enam",
383 "eeur",
384 "apac",
385 "apac-ne",
386 "apac-se",
387 "oc",
388 "sam",
389 "afr",
390 "me",
391 ]),
392 ),
393 });
394
395 // this.env.WORKFLOW is WorkflowBinding
396 export class WorkflowBinding extends WorkerEntrypoint<Env> {
397 constructor(ctx: ExecutionContext, env: Env) {
398 super(ctx, env);
399 }
400
401 async #instanceExists(id: string): Promise<boolean> {
402 // Avoid recreating the engine while its previous persistence is being deleted.
403 await waitForPersistedInstanceDelete(this.env, id);
404 const stub = this.env.ENGINE.get(this.env.ENGINE.idFromName(id));
405 return await stub.hasInstance();
406 }
407
408 public async create(options: WorkflowInstanceCreateOptions = {}): Promise<{
409 id: string;
410 }> {
411 // Destructuring defaults apply only to absent fields: an explicit null
412 // id must reach the validation below rather than becoming a generated
413 // id.
414 const { id = crypto.randomUUID() } = options;
415 if (!isValidWorkflowInstanceId(id)) {
416 throw new WorkflowError("Workflow instance has invalid id");
417 }
418
419 // Deterministic (caller-provided) ids carry a documented uniqueness
420 // contract: creating an instance with an id that already exists throws
421 // and the existing instance is retained. The existence marker is
422 // committed by the engine's init(), dispatched fire-and-forget below,
423 // so duplicate creates racing ahead of that commit can all resolve
424 // successfully; the engine's init() guards make the extra dispatch a
425 // no-op, so the race cannot double-execute the workflow body.
426 if (options.id !== undefined && (await this.#instanceExists(id))) {
427 throw duplicateInstanceError(id);
428 }
429
430 return this.#createUnchecked(id, options);
431 }
432
433 // Creation body shared by create() and createBatch(), which perform their
434 // own validation and existence checks before calling this.
435 async #createUnchecked(
436 id: string,
437 options: WorkflowInstanceCreateOptions,
438 ): Promise<{ id: string }> {
439 const { params = {} } = options;
440 if (options.id === undefined) {
441 await waitForPersistedInstanceDelete(this.env, id);
442 }
443 const stubId = this.env.ENGINE.idFromName(id);
444 const stub = this.env.ENGINE.get(stubId);
445 const introspectionSession = workflowIntrospectionSessions.get(this.env.WORKFLOW_NAME);
446
447 if (introspectionSession !== undefined) {
448 using modifier = await stub.getInstanceModifier();
449 introspectionSession.instanceIds.push(id);
450 for (const operation of introspectionSession.operations) {
451 await applyWorkflowIntrospectionOperation(modifier, operation);
452 }
453 }
454
455 const now = new Date().toISOString();
456 const initPromise = stub
457 .init(
458 0, // accountId: number,
459 {} as DatabaseWorkflow, // workflow: DatabaseWorkflow,
460 {} as DatabaseVersion, // version: DatabaseVersion,
461 {
462 id,
463 created_on: now,
464 modified_on: now,
465 workflow_id: "",
466 version_id: "",
467 status: 0, // InstanceStatus.Queued
468 started_on: now,
469 ended_on: null,
470 } satisfies DatabaseInstance,
471 {
472 timestamp: new Date(),
473 payload: params as Readonly<typeof params>,
474 instanceId: id,
475 workflowName: this.env.WORKFLOW_NAME,
476 },
477 )
478 .then((val) => {
479 if (val !== undefined) {
480 val[Symbol.dispose]();
481 }
482 })
483 .catch(() => {
484 // Suppress all rejections: create() should queue and
485 // return immediately
486 });
487
488 this.ctx.waitUntil(initPromise);
489
490 return {
491 id,
492 };
493 }
494
495 public async get(id: string): Promise<WorkflowInstance> {
496 const stubId = this.env.ENGINE.idFromName(id);
497 const stub = this.env.ENGINE.get(stubId);
498
499 // Pass a getter function so WorkflowHandle can get a fresh stub after abort
500 const getStub = () => this.env.ENGINE.get(this.env.ENGINE.idFromName(id));
501
502 const handle = new WorkflowHandle(id, stub, getStub, this);
503
504 try {
505 await handle.status();
506 } catch {
507 throw new Error("instance.not_found");
508 }
509
510 return handle;
511 }
512
513 // A Workflow on `ctx.exports` is built by workerd's
514 // `cloudflare-internal:workflows-api`, which addresses each instance by id
515 // on the binding rather than calling the instance returned by `get()`. Each
516 // method goes through `get()` so a missing instance still fails with
517 // `instance.not_found`.
518
519 public async getInstance(id: string): Promise<{ id: string }> {
520 await this.get(id);
521 return { id };
522 }
523
524 public async pause(id: string): Promise<void> {
525 await (await this.get(id)).pause();
526 }
527
528 public async resume(id: string): Promise<void> {
529 await (await this.get(id)).resume();
530 }
531
532 public async terminate(id: string, options?: WorkflowInstanceTerminateOptions): Promise<void> {
533 await (await this.get(id)).terminate(options);
534 }
535
536 public async restart(id: string, options?: WorkflowInstanceRestartOptions): Promise<void> {
537 await (await this.get(id)).restart(options);
538 }
539
540 public async status(id: string): Promise<InstanceStatus> {
541 return await (await this.get(id)).status();
542 }
543
544 public async sendEvent(id: string, event: { type: string; payload: unknown }): Promise<void> {
545 await (await this.get(id)).sendEvent(event);
546 }
547
548 public async subscribe(
549 id: string,
550 options?: WorkflowInstanceSubscribeOptions,
551 ): Promise<WorkflowInstanceSubscription> {
552 return await (await this.get(id)).subscribe(options);
553 }
554
555 public async createBatch(
556 batch: WorkflowInstanceCreateOptions<unknown>[],
557 ): Promise<{ id: string }[]>;
558 public async createBatch(options: WorkflowBatchCreateOptions): Promise<WorkflowBatchCreateResult>;
559 public async createBatch(
560 options: WorkflowInstanceCreateOptions<unknown>[] | WorkflowBatchCreateOptions,
561 ): Promise<{ id: string }[] | WorkflowBatchCreateResult> {
562 const isLegacyBatch = Array.isArray(options);
563 let batch: WorkflowInstanceCreateOptions<unknown>[];
564 if (isLegacyBatch) {
565 batch = options;
566 } else if (options !== null && typeof options === "object") {
567 if ("count" in options && options.count !== undefined) {
568 if (!Number.isInteger(options.count) || options.count <= 0) {
569 throw createWorkflowError("count must be a positive integer", "body");
570 }
571 if (options.count > 100) {
572 throw createWorkflowError("batchCreate only supports 100 instances at a time", "body");
573 }
574 batch = Array.from({ length: options.count }, () => ({
575 params: options.params,
576 retention: options.retention,
577 locationHint: options.locationHint,
578 }));
579 } else if ("instances" in options && Array.isArray(options.instances)) {
580 batch = options.instances;
581 } else {
582 throw createWorkflowError("Provided argument is invalid", "body");
583 }
584 } else {
585 throw createWorkflowError("Provided argument is invalid", "body");
586 }
587
588 if (batch.length === 0) {
589 if (!isLegacyBatch) {
590 throw createWorkflowError("Batch size exceeds maximum allowed", "body");
591 }
592 throw new Error("WorkflowError: batchCreate should have at least 1 instance");
593 }
594 if (batch.length > 100) {
595 if (!isLegacyBatch) {
596 throw createWorkflowError("Batch size exceeds maximum allowed", "body");
597 }
598 throw new Error("WorkflowError: batchCreate only supports 100 instances at a time");
599 }
600
601 // Validate only object-form entries before probing ids, which persists storage;
602 // the deprecated array form retains create()'s option validation behavior.
603 for (const instanceOptions of batch) {
604 if (!isLegacyBatch) {
605 const validation = Schema.decodeResult(workflowInstanceCreateOptionsSchema)(
606 instanceOptions,
607 );
608 if (Result.isFailure(validation)) {
609 throw createWorkflowError(validation.failure.message, "body");
610 }
611 }
612 // Reserved ids are only rejected by the object form; the deprecated
613 // array form keeps accepting every id that create() accepts.
614 if (
615 instanceOptions.id !== undefined &&
616 (!isValidWorkflowInstanceId(instanceOptions.id) ||
617 (!isLegacyBatch &&
618 (["batch", "terminate", "terminateAll"].includes(instanceOptions.id) ||
619 /^cf_[0-9a-f]{64}$/.test(instanceOptions.id))))
620 ) {
621 if (isLegacyBatch) {
622 throw new WorkflowError("Workflow instance has invalid id");
623 }
624 throw createWorkflowError("Instance ID is invalid", "instance.invalid_id");
625 }
626 }
627
628 // Probe each distinct caller-provided id once, concurrently, instead of
629 // sequentially per entry (and a second time inside create()).
630 const providedIds = [
631 ...new Set(
632 batch
633 .map((instanceOptions) => instanceOptions.id)
634 .filter((id): id is string => id !== undefined),
635 ),
636 ];
637 const existing = new Set<string>();
638 await Promise.all(
639 providedIds.map(async (id) => {
640 if (await this.#instanceExists(id)) {
641 existing.add(id);
642 }
643 }),
644 );
645
646 // Existing and repeated ids are excluded from the created instances. The
647 // legacy form omits them, while the object form reports their input indexes.
648 const result: WorkflowBatchCreateResult = { created: [], errors: [] };
649 const seenIds = new Set<string>();
650 for (const [index, instanceOptions] of batch.entries()) {
651 if (instanceOptions.id !== undefined) {
652 if (seenIds.has(instanceOptions.id)) {
653 if (!isLegacyBatch) {
654 result.errors.push({
655 index,
656 id: instanceOptions.id,
657 code: 10415,
658 message: "workflows.api.error.instance.duplicate_in_batch",
659 });
660 }
661 continue;
662 }
663 seenIds.add(instanceOptions.id);
664 if (existing.has(instanceOptions.id)) {
665 if (!isLegacyBatch) {
666 result.errors.push({
667 index,
668 id: instanceOptions.id,
669 code: 10405,
670 message: "workflows.api.error.instance.already_exists",
671 });
672 }
673 continue;
674 }
675 }
676 const { id = crypto.randomUUID() } = instanceOptions;
677 result.created.push(await this.#createUnchecked(id, instanceOptions));
678 }
679 return isLegacyBatch ? result.created : result;
680 }
681
682 /**
683 * Deletes an instance. Named `deleteInstance` because `Fetcher.delete()` shadows
684 * a same-named JSRPC method.
685 */
686 public async deleteInstance(id: string): Promise<void> {
687 if (!isValidAddressableWorkflowInstanceId(id)) {
688 throw createWorkflowError("Instance ID is invalid", "instance.invalid_id");
689 }
690
691 const stub = this.env.ENGINE.get(this.env.ENGINE.idFromName(id));
692 await deleteWorkflowStorage({
693 disk: this.env.WORKFLOW_STORAGE,
694 workflowName: this.env.WORKFLOW_NAME,
695 ctx: this.ctx,
696 hexId: stub.id.toString(),
697 abort: async () => {
698 try {
699 await stub.deleteInstance();
700 } catch (error) {
701 // delete aborts the instance
702 if (!isUserTriggeredDelete(error)) {
703 throw error;
704 }
705 }
706 },
707 });
708 }
709
710 /** Removes local persistence by hex ID, including orphaned instances in Explorer. */
711 public async unsafeDeletePersistedInstance(hexId: string): Promise<boolean> {
712 if (this.env.WORKFLOW_STORAGE === undefined) {
713 throw new Error("Workflow storage service not available");
714 }
715 return deleteWorkflowStorage({
716 disk: this.env.WORKFLOW_STORAGE,
717 workflowName: this.env.WORKFLOW_NAME,
718 ctx: this.ctx,
719 hexId,
720 abort: async () => {
721 try {
722 const stub = this.env.ENGINE.get(this.env.ENGINE.idFromString(hexId));
723 await stub.unsafeAbort();
724 } catch {}
725 },
726 abortOnlyIfPersisted: true,
727 });
728 }
729
730 /** Deletes each unique instance once while preserving duplicate results. */
731 public async deleteBatch(options: {
732 instances: Array<string>;
733 }): Promise<WorkflowBatchDeleteResult> {
734 const instanceIds = options?.instances;
735 if (!Array.isArray(instanceIds)) {
736 throw createWorkflowError("Provided argument is invalid", "body");
737 }
738 if (instanceIds.length > 100) {
739 throw createWorkflowError(
740 "batchDeleteInstances only supports 100 instances at a time",
741 "body",
742 );
743 }
744 if (instanceIds.length === 0) {
745 throw createWorkflowError("batchDeleteInstances should have at least 1 instance", "body");
746 }
747 if (!instanceIds.every(isValidAddressableWorkflowInstanceId)) {
748 throw createWorkflowError("Instance ID is invalid", "instance.invalid_id");
749 }
750
751 const uniqueIds = [...new Set(instanceIds)];
752 const settled = await Promise.allSettled(uniqueIds.map((id) => this.deleteInstance(id)));
753 const resultsById = new Map(uniqueIds.map((id, index) => [id, settled[index]]));
754 const result: WorkflowBatchDeleteResult = { deleted: [], errors: [] };
755 for (const id of instanceIds) {
756 const deletion = resultsById.get(id);
757 if (deletion === undefined) {
758 throw new Error("Missing batch deletion result");
759 }
760 if (deletion.status === "fulfilled" || isUserTriggeredDelete(deletion.reason)) {
761 result.deleted.push({ id });
762 continue;
763 }
764
765 const isNotFound =
766 deletion.reason instanceof Error &&
767 deletion.reason.message.includes("(instance.not_found)");
768 result.errors.push({
769 id,
770 code: isNotFound ? 10400 : 10001,
771 message: isNotFound
772 ? "workflows.api.error.instance.not_found"
773 : "workflows.api.error.internal_server",
774 });
775 }
776
777 const missingIds = new Set(
778 result.errors.filter(({ code }) => code === 10400).map(({ id }) => id),
779 );
780 const cleanupIds = [...missingIds];
781 const cleanups = await Promise.allSettled(
782 cleanupIds.map((id) => deletePersistedInstance(this.env, this.ctx, id)),
783 );
784 const failedCleanupIds = new Set(
785 cleanupIds.filter((_, index) => cleanups[index]?.status === "rejected"),
786 );
787 if (failedCleanupIds.size === 0) {
788 return result;
789 }
790
791 const errorsById = new Map(result.errors.map((error) => [error.id, error]));
792 return {
793 deleted: result.deleted.filter(({ id }) => !failedCleanupIds.has(id)),
794 errors: instanceIds.flatMap((id) => {
795 if (failedCleanupIds.has(id)) {
796 return [{ id, code: 10001, message: "workflows.api.error.internal_server" }];
797 }
798 const error = errorsById.get(id);
799 return error === undefined ? [] : [error];
800 }),
801 };
802 }
803
804 public async unsafeGetBindingName(): Promise<string> {
805 // async because of rpc
806 return this.env.BINDING_NAME;
807 }
808
809 public async unsafeStartIntrospection(): Promise<string> {
810 if (workflowIntrospectionSessions.has(this.env.WORKFLOW_NAME)) {
811 throw new Error(
812 `Workflow ${JSON.stringify(this.env.WORKFLOW_NAME)} already has an active introspection session for binding ${JSON.stringify(this.env.BINDING_NAME)}.`,
813 );
814 }
815
816 const sessionId = crypto.randomUUID();
817 workflowIntrospectionSessions.set(this.env.WORKFLOW_NAME, {
818 id: sessionId,
819 operations: [],
820 instanceIds: [],
821 });
822 return sessionId;
823 }
824
825 public async unsafeStopIntrospection(sessionId: string): Promise<void> {
826 const session = workflowIntrospectionSessions.get(this.env.WORKFLOW_NAME);
827 if (session?.id === sessionId) {
828 workflowIntrospectionSessions.delete(this.env.WORKFLOW_NAME);
829 }
830 }
831
832 public async unsafeSetIntrospectionOperations(
833 sessionId: string,
834 operations: Array<WorkflowIntrospectionOperation>,
835 ): Promise<void> {
836 const session = getWorkflowIntrospectionSession(this.env.WORKFLOW_NAME, sessionId);
837 session.operations = operations;
838 }
839
840 public async unsafeGetIntrospectionInstances(sessionId: string): Promise<Array<string>> {
841 return getWorkflowIntrospectionSession(this.env.WORKFLOW_NAME, sessionId).instanceIds;
842 }
843
844 public async unsafeGetInstanceModifier(instanceId: string): Promise<unknown> {
845 // async because of rpc
846 const stubId = this.env.ENGINE.idFromName(instanceId);
847 const stub = this.env.ENGINE.get(stubId);
848
849 const instanceModifier = stub.getInstanceModifier();
850
851 return instanceModifier;
852 }
853
854 public async unsafeWaitForStepResult(
855 instanceId: string,
856 name: string,
857 index?: number,
858 ): Promise<unknown> {
859 const stubId = this.env.ENGINE.idFromName(instanceId);
860 const stub = this.env.ENGINE.get(stubId);
861
862 return stub.waitForStepResult(name, index);
863 }
864
865 public async unsafeAbort(instanceId: string, reason?: string): Promise<void> {
866 const stubId = this.env.ENGINE.idFromName(instanceId);
867 const stub = this.env.ENGINE.get(stubId);
868
869 try {
870 await stub.unsafeAbort(reason);
871 } catch {
872 // do nothing because we want to dispose this instance
873 }
874 }
875
876 public async unsafeWaitForStatus(instanceId: string, status: string): Promise<void> {
877 const stubId = this.env.ENGINE.idFromName(instanceId);
878 const stub = this.env.ENGINE.get(stubId);
879 return await stub.waitForStatus(status);
880 }
881
882 public async unsafeGetOutputOrError(instanceId: string, isOutput: boolean): Promise<unknown> {
883 const stubId = this.env.ENGINE.idFromName(instanceId);
884 const stub = this.env.ENGINE.get(stubId);
885 return stub.getOutputOrError(isOutput);
886 }
887 }
888
889 export class WorkflowHandle extends RpcTarget implements WorkflowInstance {
890 private stub: DurableObjectStub<Engine>;
891
892 constructor(
893 public id: string,
894 stub: DurableObjectStub<Engine>,
895 private getStub: () => DurableObjectStub<Engine>,
896 private binding: WorkflowBinding,
897 ) {
898 super();
899 this.stub = stub;
900 }
901
902 public async pause(): Promise<void> {
903 try {
904 await this.stub.changeInstanceStatus("pause");
905 } catch (e) {
906 // pause causes instance abortion
907 if (!isUserTriggeredPause(e)) {
908 throw e;
909 }
910 }
911 }
912
913 public async resume(): Promise<void> {
914 await this.stub.changeInstanceStatus("resume");
915 }
916
917 public async terminate(options?: WorkflowInstanceTerminateOptions): Promise<void> {
918 try {
919 await this.stub.changeInstanceStatus("terminate", undefined, options);
920 } catch (e) {
921 // terminate causes instance abortion
922 if (!isUserTriggeredTerminate(e)) {
923 throw e;
924 }
925 }
926 }
927
928 public async delete(): Promise<void> {
929 await this.binding.deleteInstance(this.id);
930 }
931
932 public async restart(options?: WorkflowInstanceRestartOptions): Promise<void> {
933 try {
934 await this.stub.changeInstanceStatus("restart", options?.from);
935 } catch (e) {
936 // restart causes instance abortion
937 if (!isUserTriggeredRestart(e)) {
938 throw e;
939 }
940 }
941
942 // trigger restart flow after abortion
943 this.stub = this.getStub();
944 await this.stub.attemptRestart();
945 }
946
947 public async status(): Promise<InstanceStatus & { __LOCAL_DEV_STEP_OUTPUTS: Array<unknown> }> {
948 // Both getStatus() and readLogs() must use the same fresh stub.
949 // After pause/restart/terminate aborts the DO, the stub goes stale
950 const fetchStatusAndLogs = async () => {
951 const status = await this.stub.getStatus();
952
953 // NOTE(lduarte): for some reason, sync functions over RPC are typed as never instead of Promise<EngineLogs>
954 const logs = await (this.stub.readLogs() as unknown as Promise<EngineLogs & Disposable>);
955
956 return { status, logs };
957 };
958
959 let result: {
960 status: EngineInstanceStatus;
961 logs: EngineLogs & Disposable;
962 };
963 try {
964 result = await fetchStatusAndLogs();
965 } catch {
966 this.stub = this.getStub();
967 result = await fetchStatusAndLogs();
968 }
969 // Dispose the RPC handle when the method scope exits
970 using logs = result.logs;
971
972 const filteredLogs = logs.logs.filter(
973 (log) =>
974 log.event === InstanceEvent.STEP_SUCCESS || log.event === InstanceEvent.WAIT_COMPLETE,
975 );
976
977 const stepOutputs = filteredLogs.map((log) =>
978 log.event === InstanceEvent.STEP_SUCCESS ? log.metadata.result : log.metadata.payload,
979 );
980
981 const workflowOutput =
982 logs.logs.find((log) => log.event === InstanceEvent.WORKFLOW_SUCCESS)?.metadata.result ??
983 null;
984
985 const workflowError = logs.logs.find((log) => log.event === InstanceEvent.WORKFLOW_FAILURE)
986 ?.metadata.error;
987
988 return {
989 status: instanceStatusName(result.status),
990 __LOCAL_DEV_STEP_OUTPUTS: stepOutputs,
991 output: workflowOutput,
992 error: workflowError,
993 };
994 }
995
996 public async subscribe(options?: WorkflowSubscriptionOptions): Promise<WorkflowSubscription> {
997 const parsedOptions = parseWorkflowSubscriptionOptions(options);
998 return this.stub.subscribe(parsedOptions);
999 }
1000
1001 public async sendEvent(args: { payload: unknown; type: string }): Promise<void> {
1002 await this.stub.receiveEvent({
1003 payload: args.payload,
1004 type: args.type,
1005 timestamp: new Date(),
1006 });
1007 }
1008 }