sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare-runtime/ src/ internal/ workflows-shared/ introspection.ts

// Alchemy modifications are licensed under Apache-2.0.
// This file includes third-party code; see /THIRD_PARTY_LICENSES.md.
import type {
  ModifierCallback,
  WorkflowBinding,
  WorkflowInstanceIntrospector,
  WorkflowInstanceModifier,
  WorkflowIntrospectionOperation,
  WorkflowIntrospectionStreamResult,
  WorkflowIntrospector,
  WorkflowStepSelector,
} from "./types.ts";

function normalizeStreamMockChunk(value: unknown): Uint8Array {
  if (value instanceof Uint8Array) {
    return value;
  }

  if (value instanceof ArrayBuffer) {
    return new Uint8Array(value);
  }

  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
  }

  throw new TypeError(
    "Workflow mockStepResult() ReadableStream chunks must be ArrayBuffer or TypedArray values.",
  );
}

async function readStreamMockChunks(stream: ReadableStream<unknown>): Promise<Array<Uint8Array>> {
  if (stream.locked) {
    throw new TypeError(
      "Workflow mockStepResult() received a locked or unreadable ReadableStream.",
    );
  }

  const chunks: Array<Uint8Array> = [];
  const reader = stream.getReader();
  let fullyRead = false;
  try {
    while (true) {
      const result = await reader.read();
      if (result.done) {
        fullyRead = true;
        return chunks;
      }

      const chunk = normalizeStreamMockChunk(result.value);
      if (chunk.byteLength === 0) {
        continue;
      }

      chunks.push(chunk.slice());
    }
  } finally {
    if (!fullyRead) {
      await reader.cancel("stream mock consumption stopped before completion").catch(() => {});
    }
    try {
      reader.releaseLock();
    } catch {
      /** Reader may still be processing cancel(). */
    }
  }
}

export class WorkflowInstanceModificationRecorder implements WorkflowInstanceModifier {
  constructor(private readonly operations: Array<WorkflowIntrospectionOperation>) {}

  async disableSleeps(steps?: Array<WorkflowStepSelector>): Promise<void> {
    this.operations.push({ type: "disableSleeps", steps });
  }

  async disableRetryDelays(steps?: Array<WorkflowStepSelector>): Promise<void> {
    this.operations.push({ type: "disableRetryDelays", steps });
  }

  async mockStepResult(step: WorkflowStepSelector, stepResult: unknown): Promise<void> {
    if (stepResult instanceof ReadableStream) {
      const streamResult: WorkflowIntrospectionStreamResult = {
        __workflowIntrospectionStreamResult: true,
        chunks: await readStreamMockChunks(stepResult),
      };
      this.operations.push({
        type: "mockStepResult",
        step,
        stepResult: streamResult,
      });
      return;
    }

    this.operations.push({ type: "mockStepResult", step, stepResult });
  }

  async mockStepError(step: WorkflowStepSelector, error: Error, times?: number): Promise<void> {
    this.operations.push({
      type: "mockStepError",
      step,
      error: { name: error.name, message: error.message },
      times,
    });
  }

  async forceStepTimeout(step: WorkflowStepSelector, times?: number): Promise<void> {
    this.operations.push({ type: "forceStepTimeout", step, times });
  }

  async mockEvent(event: { type: string; payload: unknown }): Promise<void> {
    this.operations.push({ type: "mockEvent", event });
  }

  async forceEventTimeout(step: WorkflowStepSelector): Promise<void> {
    this.operations.push({ type: "forceEventTimeout", step });
  }
}

export class WorkflowIntrospectorHandle implements WorkflowIntrospector {
  #disposed = false;
  #sessionId: string | undefined;
  #instanceIntrospectors = new Map<string, WorkflowInstanceIntrospector>();
  #operations: Array<WorkflowIntrospectionOperation> = [];

  constructor(private readonly workflow: WorkflowBinding) {}

  async start(): Promise<void> {
    this.#sessionId = await this.workflow.unsafeStartIntrospection();
  }

  private getSessionId(): string {
    if (this.#sessionId === undefined) {
      throw new Error("Workflow introspection has not started.");
    }
    return this.#sessionId;
  }

  async modifyAll(fn: ModifierCallback): Promise<void> {
    const sessionId = this.getSessionId();
    await fn(new WorkflowInstanceModificationRecorder(this.#operations));
    await this.workflow.unsafeSetIntrospectionOperations(sessionId, this.#operations);
  }

  async get(): Promise<Array<WorkflowInstanceIntrospector>> {
    const sessionId = this.getSessionId();
    await this.syncInstanceIntrospectors(sessionId);

    return Array.from(this.#instanceIntrospectors.values());
  }

  private async syncInstanceIntrospectors(sessionId: string): Promise<void> {
    const instanceIds = await this.workflow.unsafeGetIntrospectionInstances(sessionId);

    for (const instanceId of instanceIds) {
      if (!this.#instanceIntrospectors.has(instanceId)) {
        this.#instanceIntrospectors.set(
          instanceId,
          new WorkflowInstanceIntrospectorHandle(this.workflow, instanceId),
        );
      }
    }
  }

  private async stopIntrospectionSession(sessionId: string): Promise<void> {
    try {
      await this.syncInstanceIntrospectors(sessionId);
    } finally {
      await this.workflow.unsafeStopIntrospection(sessionId);
    }
  }

  private async disposeInstanceIntrospectors(): Promise<void> {
    try {
      await Promise.all(
        Array.from(this.#instanceIntrospectors.values(), (introspector) => introspector.dispose()),
      );
    } finally {
      this.#instanceIntrospectors.clear();
    }
  }

  /** Keep this bound; explicit resource management may call the disposer unbound. */
  dispose = async (): Promise<void> => {
    if (this.#disposed) {
      return;
    }
    this.#disposed = true;
    const sessionId = this.#sessionId;

    try {
      if (sessionId !== undefined) {
        await this.stopIntrospectionSession(sessionId);
      }
    } finally {
      await this.disposeInstanceIntrospectors();
    }
  };

  async [Symbol.asyncDispose](): Promise<void> {
    await this.dispose();
  }
}

export class WorkflowInstanceIntrospectorHandle implements WorkflowInstanceIntrospector {
  #disposed = false;
  #instanceModifier: WorkflowInstanceModifier | undefined;
  #instanceModifierPromise: Promise<WorkflowInstanceModifier> | undefined;

  constructor(
    private readonly workflow: WorkflowBinding,
    private readonly instanceId: string,
  ) {
    this.#instanceModifierPromise = workflow
      .unsafeGetInstanceModifier(instanceId)
      .then((modifier) => {
        this.#instanceModifier = modifier as WorkflowInstanceModifier;
        this.#instanceModifierPromise = undefined;
        return this.#instanceModifier;
      });

    // To avoid an unhandled rejection when the handle is used without modify()
    void this.#instanceModifierPromise.catch(() => {});
  }

  async modify(fn: ModifierCallback): Promise<WorkflowInstanceIntrospector> {
    if (this.#instanceModifierPromise !== undefined) {
      this.#instanceModifier = await this.#instanceModifierPromise;
    }
    if (this.#instanceModifier === undefined) {
      throw new Error(
        "could not apply modifications due to internal error. Retrying the test may resolve the issue.",
      );
    }

    await fn(this.#instanceModifier);

    return this;
  }

  async waitForStepResult(step: WorkflowStepSelector): Promise<unknown> {
    return await this.workflow.unsafeWaitForStepResult(this.instanceId, step.name, step.index);
  }

  async waitForStatus(status: string): Promise<void> {
    if (status === "queued") {
      return;
    }

    await this.workflow.unsafeWaitForStatus(this.instanceId, status);
  }

  async getOutput(): Promise<unknown> {
    return await this.workflow.unsafeGetOutputOrError(this.instanceId, true);
  }

  async getError(): Promise<{ name: string; message: string }> {
    return (await this.workflow.unsafeGetOutputOrError(this.instanceId, false)) as {
      name: string;
      message: string;
    };
  }

  /** Keep this bound; explicit resource management may call the disposer unbound. */
  dispose = async (): Promise<void> => {
    if (this.#disposed) {
      return;
    }
    this.#disposed = true;
    try {
      // Acquisition starts in the constructor, even if modify() is never called.
      // If it failed, there is no modifier to dispose; modify() still reports it.
      const modifier =
        this.#instanceModifier ?? (await this.#instanceModifierPromise?.catch(() => undefined));
      (modifier as Partial<Disposable> | undefined)?.[Symbol.dispose]?.();
    } finally {
      await this.workflow.unsafeAbort(this.instanceId, "Instance dispose");
    }
  };

  async [Symbol.asyncDispose](): Promise<void> {
    await this.dispose();
  }
}