sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare-runtime/ src/ vite/ module-runner/ wrapper.worker.ts

import { DurableObject, WorkerEntrypoint, WorkflowEntrypoint } from "cloudflare:workers";
import { HEADER_ERROR_STACK, INIT_PATH } from "./constants.shared.ts";
import type { Env as WrapperEnv } from "./env.worker.ts";
import { getEntryEnvironment, stripInternalEnv } from "./env.worker.ts";
import {
  DURABLE_OBJECT_KEYS,
  IGNORED_KEYS,
  WORKER_ENTRYPOINT_KEYS,
  WORKFLOW_ENTRYPOINT_KEYS,
} from "./keys.shared.ts";
import { getWorkerEntryExport } from "./module-runner.worker.ts";

/**
 * Constructor interface for `WorkerEntrypoint` class.
 * @template T - The `env` type
 */
interface WorkerEntrypointConstructor<T = Cloudflare.Env> {
  new (...args: ConstructorParameters<typeof WorkerEntrypoint<T>>): WorkerEntrypoint<T>;
}

/**
 * Constructor interface for `DurableObject` class.
 * @template T - The `env` type
 */
interface DurableObjectConstructor<T = Cloudflare.Env> {
  new (...args: ConstructorParameters<typeof DurableObject<T>>): DurableObject<T>;
}

/**
 * Constructor interface for `WorkflowEntrypoint` class.
 * @template T - The `env` type
 */
interface WorkflowEntrypointConstructor<T = Cloudflare.Env> {
  new (...args: ConstructorParameters<typeof WorkflowEntrypoint<T>>): WorkflowEntrypoint<T>;
}

export {
  DURABLE_OBJECT_KEYS,
  IGNORED_KEYS,
  WORKER_ENTRYPOINT_KEYS,
  WORKFLOW_ENTRYPOINT_KEYS,
} from "./keys.shared.ts";

/**
 * Creates a proxy wrapper for `WorkerEntrypoint` classes that enables RPC functionality.
 * The wrapper intercepts property access and delegates to the user code, handling both direct method calls and RPC property access.
 * @param exportName - The name of the `WorkerEntrypoint` export to wrap
 * @returns A `WorkerEntrypoint` constructor that acts as a proxy to the user code
 */
export function createWorkerEntrypointWrapper(
  exportName: string,
): WorkerEntrypointConstructor<WrapperEnv> {
  class Wrapper extends WorkerEntrypoint<WrapperEnv> {
    constructor(ctx: ExecutionContext, env: WrapperEnv) {
      super(ctx, env);

      return new Proxy(this, {
        get(target, key, receiver) {
          const value = Reflect.get(target, key, receiver);

          if (value !== undefined) {
            return value;
          }

          if (
            typeof key === "symbol" ||
            (IGNORED_KEYS as ReadonlyArray<string>).includes(key) ||
            // The class methods are accessed to determine the type of the export.
            // We should therefore avoid proxying `DurableObject` methods on the `WorkerEntrypoint` class.
            (DURABLE_OBJECT_KEYS as ReadonlyArray<string>).includes(key)
          ) {
            return;
          }

          const property = getWorkerEntrypointRpcProperty.call(receiver, exportName, key);

          return getRpcPropertyCallableThenable(key, property);
        },
      });
    }
  }

  for (const key of WORKER_ENTRYPOINT_KEYS) {
    Wrapper.prototype[key] = async function (arg) {
      const proxy = async () => {
        const exportValue = await getWorkerEntryExport(this.env, exportName);
        const userEnv = stripInternalEnv(this.env);

        if (typeof exportValue === "object" && exportValue !== null) {
          // The export is an `ExportedHandler`
          const maybeFn = (exportValue as Record<string, unknown>)[key];

          if (typeof maybeFn !== "function") {
            throw new TypeError(
              `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to define a \`${key}()\` function.`,
            );
          }

          return maybeFn.call(exportValue, arg, userEnv, this.ctx);
        } else if (typeof exportValue === "function") {
          // The export is a `WorkerEntrypoint`
          const ctor = exportValue as WorkerEntrypointConstructor;
          const instance = new ctor(this.ctx, userEnv);

          if (!(instance instanceof WorkerEntrypoint)) {
            throw new TypeError(
              `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to be a subclass of \`WorkerEntrypoint\`.`,
            );
          }

          const maybeFn = instance[key];

          if (typeof maybeFn !== "function") {
            throw new TypeError(
              `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to define a \`${key}()\` method.`,
            );
          }

          return (maybeFn as (arg: unknown) => unknown).call(instance, arg);
        } else {
          throw new TypeError(
            `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to be an object or a class.`,
          );
        }
      };

      if (key === "fetch") {
        const request = arg as Request;
        const url = new URL(request.url);
        // Initialize the module runner
        if (url.pathname === INIT_PATH) {
          const stub = this.env.__DISTILLED_MODULE_RUNNER__.get("singleton");
          return stub.fetch(request);
        }
        try {
          return await proxy();
        } catch (error) {
          // The default export's errors go to Vite's error page, as under
          // `@cloudflare/vite-plugin`: the dev server revives this response.
          if (exportName === "default") {
            return Response.json(reduceError(error), {
              status: 500,
              headers: { [HEADER_ERROR_STACK]: "true" },
            });
          }
          console.error("Error calling fetch", error);
          throw error;
        }
      }
      return await proxy();
    };
  }

  return Wrapper;
}

/**
 * Retrieves an RPC property from a `WorkerEntrypoint` export, creating an instance and returning the bound method or property value.
 * @param exportName - The name of the `WorkerEntrypoint` export
 * @param key - The property key to access on the `WorkerEntrypoint` instance
 * @returns The property value, with methods bound to the instance
 * @throws TypeError if the export is not a `WorkerEntrypoint` subclass
 */
async function getWorkerEntrypointRpcProperty(
  this: WorkerEntrypoint<WrapperEnv>,
  exportName: string,
  key: string,
): Promise<unknown> {
  const ctor = (await getWorkerEntryExport(this.env, exportName)) as WorkerEntrypointConstructor;
  const userEnv = stripInternalEnv(this.env);
  const expectedWorkerEntrypointMessage = `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to be a subclass of \`WorkerEntrypoint\` for RPC.`;

  if (typeof ctor !== "function") {
    throw new TypeError(expectedWorkerEntrypointMessage);
  }

  const instance = new ctor(this.ctx, userEnv);

  if (!(instance instanceof WorkerEntrypoint)) {
    throw new TypeError(expectedWorkerEntrypointMessage);
  }

  const value = getRpcProperty(ctor, instance, key);

  if (typeof value === "function") {
    return value.bind(instance);
  }

  return value;
}

/** Symbol key for storing the `DurableObject` instance */
const kInstance = Symbol("kInstance");
/** Symbol key for the instance initialization method */
const kEnsureInstance = Symbol("kEnsureInstance");

/**
 * Container for a `DurableObject` constructor and its instance.
 */
interface DurableObjectInstance {
  ctor: DurableObjectConstructor;
  instance: DurableObject;
}

/**
 * Extended `DurableObject` interface that includes instance management methods.
 */
interface DurableObjectWrapper extends DurableObject<WrapperEnv> {
  [kInstance]?: DurableObjectInstance;
  [kEnsureInstance](): Promise<DurableObjectInstance>;
}

/**
 * Retrieves an RPC property from a `DurableObject` export, ensuring an instance is properly initialized and returning the bound method or property value.
 * @param exportName - The name of the `DurableObject` export
 * @param key - The property key to access on the `DurableObject` instance
 * @returns The property value, with methods bound to the instance
 * @throws TypeError if the export is not a `DurableObject` subclass
 */
async function getDurableObjectRpcProperty(
  this: DurableObjectWrapper,
  exportName: string,
  key: string,
): Promise<unknown> {
  const { ctor, instance } = await this[kEnsureInstance]();

  if (!(instance instanceof DurableObject)) {
    throw new TypeError(
      `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to be a subclass of \`DurableObject\` for RPC.`,
    );
  }

  const value = getRpcProperty(ctor, instance, key);

  if (typeof value === "function") {
    return value.bind(instance);
  }

  return value;
}

/**
 * Creates a proxy wrapper for `DurableObject` classes that enables RPC functionality.
 * The wrapper manages instance lifecycle and delegates method calls to the user code, handling both direct method calls and RPC property access.
 * @param exportName - The name of the `DurableObject` export to wrap
 * @returns A `DurableObject` constructor that acts as a proxy to the user code
 */
export function createDurableObjectWrapper(
  exportName: string,
): DurableObjectConstructor<WrapperEnv> {
  class Wrapper extends DurableObject<WrapperEnv> implements DurableObjectWrapper {
    [kInstance]?: DurableObjectInstance;

    constructor(ctx: DurableObjectState, env: WrapperEnv) {
      super(ctx, env);

      return new Proxy(this, {
        get(target, key, receiver) {
          const value = Reflect.get(target, key, receiver);

          if (value !== undefined) {
            return value;
          }

          if (
            typeof key === "symbol" ||
            (IGNORED_KEYS as ReadonlyArray<string>).includes(key) ||
            // The class methods are accessed to determine the type of the export.
            // We should therefore avoid proxying `WorkerEntrypoint` methods on the `DurableObject` class.
            (WORKER_ENTRYPOINT_KEYS as ReadonlyArray<string>).includes(key)
          ) {
            return;
          }

          const property = getDurableObjectRpcProperty.call(receiver, exportName, key);

          return getRpcPropertyCallableThenable(key, property);
        },
      });
    }

    async [kEnsureInstance]() {
      const ctor = (await getWorkerEntryExport(this.env, exportName)) as DurableObjectConstructor;

      if (typeof ctor !== "function") {
        throw new TypeError(
          `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to be a subclass of \`DurableObject\`.`,
        );
      }

      // We reuse the same instance unless the constructor changes
      if (!this[kInstance] || this[kInstance].ctor !== ctor) {
        const userEnv = stripInternalEnv(this.env);
        const instance = new ctor(this.ctx, userEnv);

        this[kInstance] = { ctor, instance };

        // Wait for `blockConcurrencyWhile()`s in the constructor to complete
        await this.ctx.blockConcurrencyWhile(async () => {});
      }

      return this[kInstance];
    }
  }

  for (const key of DURABLE_OBJECT_KEYS) {
    Wrapper.prototype[key] = async function (...args: Array<unknown>) {
      const { instance } = await this[kEnsureInstance]();
      const maybeFn = instance[key];

      if (typeof maybeFn !== "function") {
        throw new TypeError(
          `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to define a \`${key}()\` function.`,
        );
      }

      return (maybeFn as (...args: Array<unknown>) => any).apply(instance, args);
    };
  }

  return Wrapper;
}

/**
 * Creates a proxy wrapper for `WorkflowEntrypoint` classes.
 * The wrapper delegates method calls to the user code.
 * @param exportName - The name of the `WorkflowEntrypoint` export to wrap
 * @returns A `WorkflowEntrypoint` constructor that acts as a proxy to the user code
 */
export function createWorkflowEntrypointWrapper(
  exportName: string,
): WorkflowEntrypointConstructor<WrapperEnv> {
  class Wrapper extends WorkflowEntrypoint<WrapperEnv> {}

  for (const key of WORKFLOW_ENTRYPOINT_KEYS) {
    Wrapper.prototype[key] = async function (...args: Array<unknown>) {
      const ctor = (await getWorkerEntryExport(
        this.env,
        exportName,
      )) as WorkflowEntrypointConstructor;
      const userEnv = stripInternalEnv(this.env);
      const instance = new ctor(this.ctx, userEnv);

      if (!(instance instanceof WorkflowEntrypoint)) {
        throw new TypeError(
          `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to be a subclass of \`WorkflowEntrypoint\`.`,
        );
      }

      const maybeFn = instance[key];

      if (typeof maybeFn !== "function") {
        throw new TypeError(
          `Expected "${exportName}" export of "${getEntryEnvironment().entryName}" to define a \`${key}()\` function.`,
        );
      }

      return (maybeFn as (...args: Array<unknown>) => any).apply(instance, args);
    };
  }

  return Wrapper;
}

/**
 * Creates a callable thenable that is used to access the properties of an RPC target.
 * It can be both awaited and invoked as a function.
 * This enables RPC properties to be used both as promises and callable functions.
 * @param key - The property key name used for error messages
 * @param property - The promise that resolves to the property value
 * @returns A callable thenable that implements both Promise and function interfaces
 */
function getRpcPropertyCallableThenable(
  key: string,
  property: Promise<unknown>,
): Promise<unknown> & ((...args: Array<unknown>) => Promise<unknown>) {
  const fn = async function (...args: Array<unknown>) {
    const maybeFn = await property;

    if (typeof maybeFn !== "function") {
      throw new TypeError(`"${key}" is not a function.`);
    }

    return maybeFn(...args);
  } as Promise<unknown> & ((...args: Array<unknown>) => Promise<unknown>);

  // oxlint-disable-next-line unicorn/no-thenable
  fn.then = (onFulfilled, onRejected) => property.then(onFulfilled, onRejected);
  fn.catch = (onRejected) => property.catch(onRejected);
  fn.finally = (onFinally) => property.finally(onFinally);

  return fn;
}

/**
 * Retrieves an RPC property from a constructor prototype, ensuring it exists on the prototype rather than the instance to maintain RPC compatibility.
 * @param ctor - The constructor function (`WorkerEntrypoint` or `DurableObject`)
 * @param instance - The instance to bind methods to
 * @param key - The property key to retrieve
 * @returns The property value from the prototype
 * @throws TypeError if the property doesn't exist on the prototype
 */
function getRpcProperty(
  ctor: WorkerEntrypointConstructor | DurableObjectConstructor,
  instance: WorkerEntrypoint | DurableObject,
  key: string,
): unknown {
  const prototypeHasKey = Reflect.has(ctor.prototype, key);

  if (!prototypeHasKey) {
    const instanceHasKey = Reflect.has(instance, key);

    if (instanceHasKey) {
      throw new TypeError(
        [
          `The RPC receiver's prototype does not implement "${key}", but the receiver instance does.`,
          "Only properties and methods defined on the prototype can be accessed over RPC.",
          `Ensure properties are declared as \`get ${key}() { ... }\` instead of \`${key} = ...\`,`,
          `and methods are declared as \`${key}() { ... }\` instead of \`${key} = () => { ... }\`.`,
        ].join("\n"),
      );
    }

    throw new TypeError(`The RPC receiver does not implement "${key}".`);
  }

  return Reflect.get(ctor.prototype, key, instance);
}

/**
 * Serializes an error for the dev server to revive (Wrangler's
 * `middleware-miniflare3-json-error.ts`).
 */
function reduceError(e: unknown): unknown {
  const errorObj = (e ?? {}) as Record<string, unknown>;
  return {
    name: errorObj.name,
    message: errorObj.message ?? String(e),
    stack: errorObj.stack,
    cause: errorObj.cause === undefined ? undefined : reduceError(errorObj.cause),
  };
}