sailfork / t3code-github / apps/ web/ src/ components/ files/ office/ worker-rpc.ts

// Adapted from opencode (MIT). Copyright (c) 2025 opencode. See LICENSE.opencode.
// The engines run in a worker per open file, so no layout, recalculation or painting holds the window. These are the
// two ends of that worker's protocol: typed calls by method name, a key that lets a newer call replace a queued one
// (as the markdown worker's queue does), transferable payloads, and a worker that fails every pending call when it dies.

import * as Schema from "effect/Schema";

/** What one method takes and returns. */
export type Method<Input, Output> = { readonly input: Input; readonly output: Output };

/** A worker's methods by name. */
export type Methods = { readonly [name: string]: Method<unknown, unknown> };

type Request = {
  readonly id: number;
  readonly method: string;
  readonly key?: string | undefined;
  readonly input: unknown;
};

/** Withdraws a call whose caller aborted it. */
type Cancel = { readonly cancel: number };

type Response =
  /** `transferred` lists the objects the reply moved, so a reply nobody waits for can close its bitmaps. */
  | {
      readonly id: number;
      readonly ok: true;
      readonly value: unknown;
      readonly transferred: readonly Transferable[];
    }
  | {
      readonly id: number;
      readonly ok: false;
      readonly superseded: boolean;
      readonly message: string;
    };

/** A value a method returns with the buffers to move to the caller rather than copy. */
export class Transfer<T> {
  constructor(
    readonly value: T,
    readonly transfer: readonly Transferable[],
  ) {}
}

/** A call that a newer call with the same key replaced before it ran. */
export class SupersededError extends Schema.TaggedError<SupersededError>()("SupersededError", {
  message: Schema.String,
}) {}

/** A call made after the worker failed or was closed, or pending when that happened. */
class WorkerClosedError extends Schema.TaggedError<WorkerClosedError>()("WorkerClosedError", {
  message: Schema.String,
}) {}

type CallOptions = {
  /** A newer call with the same key replaces this one while it waits to run. */
  readonly key?: string;
  /** Buffers to move to the worker rather than copy, such as the file's bytes or a transferred canvas. */
  readonly transfer?: readonly Transferable[];
  /** Drops the reply and a call still queued; a call that has started sees its handler's signal abort. */
  readonly signal?: AbortSignal;
};

/** A call waiting for its reply. */
type Pending = {
  readonly settle: (response: Response) => void;
  readonly reject: (error: Error) => void;
};

/** The next call id, and why the worker stopped answering once it has. */
type ClientState = { next: number; failure: Error | undefined };

/** The window's end: starts the worker and calls its methods. */
export function createWorkerClient<M extends Methods>(worker: Worker) {
  const pending = new Map<number, Pending>();
  const state: ClientState = { next: 0, failure: undefined };

  const fail = (error: Error) => {
    state.failure ??= error;
    pending.forEach((call) => call.reject(error));
    pending.clear();
    worker.terminate();
  };

  worker.addEventListener("message", (event: MessageEvent<Response>) => {
    const call = pending.get(event.data.id);

    // A reply that crossed its call's cancel on the way: its bitmaps would hold their memory until collected.
    if (!call) {
      if (event.data.ok) closeBitmaps(event.data.transferred);

      return;
    }

    pending.delete(event.data.id);
    call.settle(event.data);
  });

  worker.addEventListener("error", (event) =>
    fail(new WorkerClosedError({ message: event.message || "The Office engine stopped" })),
  );
  worker.addEventListener("messageerror", () =>
    fail(new WorkerClosedError({ message: "The Office engine sent an unreadable reply" })),
  );

  return {
    call<K extends keyof M & string>(
      method: K,
      input: M[K]["input"],
      options: CallOptions = {},
    ): Promise<M[K]["output"]> {
      if (state.failure) return Promise.reject(state.failure);

      if (options.signal?.aborted)
        return Promise.reject(new WorkerClosedError({ message: "The call was aborted" }));

      const id = ++state.next;

      return new Promise<M[K]["output"]>((resolve, reject) => {
        const timeout = setTimeout(
          () =>
            fail(
              new WorkerClosedError({
                message: "This document took too long to preview. Open it in another app.",
              }),
            ),
          30_000,
        );
        const abort = () => {
          clearTimeout(timeout);
          pending.delete(id);
          reject(new WorkerClosedError({ message: "The call was aborted" }));
          worker.postMessage({ cancel: id } satisfies Cancel, []);
        };

        options.signal?.addEventListener("abort", abort, { once: true });
        pending.set(id, {
          settle: (response) => {
            clearTimeout(timeout);
            options.signal?.removeEventListener("abort", abort);

            if (!response.ok)
              return reject(
                response.superseded
                  ? new SupersededError({ message: response.message })
                  : new Error(response.message),
              );

            // SAFETY: the worker answers each id with the output of the method that id called (see `serveWorker`).
            resolve(response.value as M[K]["output"]);
          },
          reject: (error) => {
            clearTimeout(timeout);
            options.signal?.removeEventListener("abort", abort);
            reject(error);
          },
        });
        worker.postMessage({ id, method, key: options.key, input } satisfies Request, [
          ...(options.transfer ?? []),
        ]);
      });
    },
    /** Stops the worker, which frees its engine's memory, and fails every pending call. */
    close() {
      fail(new WorkerClosedError({ message: "The Office engine was closed" }));
    },
  };
}

/** Whether a call runs, and which call it is, so its caller can abort it. */
type ServerState = {
  running: boolean;
  current: { readonly id: number; readonly controller: AbortController } | undefined;
};

/**
 * The worker's end: runs calls one at a time, in order, letting messages through between them. A handler's signal
 * aborts when its caller aborts the call.
 */
export function serveWorker<M extends Methods>(handlers: {
  readonly [K in keyof M]: (
    input: M[K]["input"],
    signal: AbortSignal,
  ) =>
    | M[K]["output"]
    | Transfer<M[K]["output"]>
    | Promise<M[K]["output"] | Transfer<M[K]["output"]>>;
}) {
  const queue: Request[] = [];

  const state: ServerState = { running: false, current: undefined };

  const reply = (response: Response, transfer: readonly Transferable[] = []) =>
    self.postMessage(response, { transfer: [...transfer] });

  const run = async () => {
    if (state.running) return;

    state.running = true;

    // Each call returns to the event loop before it leaves the queue, so calls that arrived meanwhile can replace it.
    while (queue.length > 0) {
      await new Promise((resolve) => setTimeout(resolve));

      const request = queue.shift();

      if (!request) break;

      const handler = handlers[request.method];
      const controller = new AbortController();

      state.current = { id: request.id, controller };

      if (!handler) {
        reply({
          id: request.id,
          ok: false,
          superseded: false,
          message: `Unknown method ${request.method}`,
        });
        continue;
      }

      // SAFETY: the client sends each method the input its `Methods` entry declares (see `createWorkerClient`).
      const input = request.input as never;

      await Promise.resolve()
        .then(() => handler(input, controller.signal))
        .then(
          (result) => {
            const transfer = result instanceof Transfer ? result.transfer : [];

            // The caller already settled a call it aborted, so nothing would take the reply or its bitmaps.
            if (controller.signal.aborted) return closeBitmaps(transfer);

            reply(
              {
                id: request.id,
                ok: true,
                value: result instanceof Transfer ? result.value : result,
                transferred: transfer,
              },
              transfer,
            );
          },
          (cause: unknown) => {
            if (controller.signal.aborted) return;

            reply({
              id: request.id,
              ok: false,
              superseded: false,
              message: cause instanceof Error ? cause.message : String(cause),
            });
          },
        );
    }

    state.running = false;
    state.current = undefined;
  };

  self.addEventListener("message", (event: MessageEvent<Request | Cancel>) => {
    // The caller already settled a cancelled call, so it gets no reply.
    if ("cancel" in event.data) {
      const id = event.data.cancel;
      const queued = queue.findIndex((request) => request.id === id);

      if (queued !== -1) queue.splice(queued, 1);

      if (state.current?.id === id) state.current.controller.abort();

      return;
    }

    const key = event.data.key;
    const replaced = key === undefined ? -1 : queue.findIndex((request) => request.key === key);

    if (replaced !== -1) {
      const [old] = queue.splice(replaced, 1);

      if (old)
        reply({ id: old.id, ok: false, superseded: true, message: "Replaced by a newer call" });
    }

    queue.push(event.data);
    void run();
  });
}

/** Frees the bitmaps among objects that were moved for a reply nobody takes. */
function closeBitmaps(transfer: readonly Transferable[]) {
  transfer.forEach((item) => {
    if (item instanceof ImageBitmap) item.close();
  });
}