The best way to control Claude Code, Codex and more from any computer or phone
| 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 | } |