sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ RuntimeBindings.ts

import type { BindingHook, BindingServices } from "@alchemy.run/cloudflare-runtime/core";
import {
  Ai,
  AiSearch,
  AnalyticsEngine,
  Artifacts,
  Assets,
  Browser,
  D1,
  Data,
  DispatchNamespace,
  DurableObjectNamespace,
  Flagship,
  Hyperdrive,
  Images,
  Json,
  KvNamespace,
  MtlsCertificate,
  Pipelines,
  Queue,
  R2Bucket,
  RateLimit,
  SecretKey,
  SecretsStore,
  SendEmail,
  Service,
  Stream as StreamSim,
  Text,
  Vectorize,
  VersionMetadata,
  VpcService,
  WasmModule,
  WorkerLoader,
  Workflows,
} from "@alchemy.run/cloudflare-runtime/core/bindings";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schema from "effect/Schema";
import { isInstantNamespaceLocalId } from "../KV/InstantNamespaceLocal.ts";
import { isLocalId } from "../LocalRuntime.ts";
import { LOCAL_R2_S3_CREDENTIALS, LOCAL_R2_S3_PATH } from "../R2/LocalS3.ts";
import type { WorkerBinding } from "./WorkerBinding.ts";

export class WorkerValidationError extends Schema.TaggedError<WorkerValidationError>()(
  "WorkerValidationError",
  {
    message: Schema.String,
    hint: Schema.optional(Schema.String),
    value: Schema.Unknown,
  },
) {}

export const toRuntimeBinding = Effect.fn(function* (
  b: WorkerBinding,
  /**
   * Dev-only channel from the Worker's binding data (see the `devRemote`
   * member of the Worker binding contract): binding name → opt-out of local
   * emulation for the capabilities that support it (browser / images /
   * stream / send_email).
   */
  devRemote?: Record<string, boolean>,
) {
  const unsupported = () =>
    WorkerValidationError.make({
      message: `${b.type} bindings are not supported in local mode`,
      value: b,
    });
  switch (b.type) {
    case "ai":
      return Ai.remote(b.name);
    case "ai_search":
      return AiSearch.remote(b.name, b.instanceName);
    case "ai_search_namespace":
      return AiSearch.remoteNamespace(b.name, b.namespace);
    case "analytics_engine":
      return AnalyticsEngine.local(b.name, b.dataset);
    case "artifacts":
      return Artifacts.remote(b.name, b.namespace);
    case "assets":
      return Assets.local(b.name);
    case "browser":
      // Local emulation launches a real headless Chrome on this machine and
      // proxies the Browser Rendering session protocol to its CDP endpoint;
      // `Alchemy.remote()` opts into the real service instead.
      return devRemote?.[b.name] ? Browser.remote(b.name) : Browser.local({ binding: b.name });
    case "d1":
      // A `dev:` id belongs to a locally-emulated database (local D1
      // provider); a real id is a live database the dev worker proxies to
      // (e.g. the resource opted out of emulation via `Alchemy.remote()`).
      return isLocalId(b.databaseId)
        ? D1.local({ binding: b.name, id: b.databaseId })
        : D1.remote(b.name, b.databaseId);
    case "data_blob":
      return Data.local(b.name, Buffer.from(b.part));
    case "dispatch_namespace":
      return DispatchNamespace.remote({
        binding: b.name,
        namespace: b.namespace,
      });
    case "durable_object_namespace":
      return DurableObjectNamespace.local({
        binding: b.name,
        className: b.className,
        scriptName: b.scriptName,
        uniqueKey: b.namespaceId ?? encodeURIComponent(`${b.scriptName!}-${b.className}`),
      });
    case "flagship":
      // A `dev:` id belongs to a locally-emulated app (the local Flag
      // provider seeds its definitions into the simulator); a real id is a
      // live app the dev worker proxies to (`Alchemy.remote()`).
      return isLocalId(b.appId)
        ? Flagship.local({ binding: b.name, appId: b.appId })
        : Flagship.remote(b.name, b.appId);
    case "hyperdrive":
      return Hyperdrive.local(b.name, b.id);
    case "images":
      // Local emulation runs transforms via Sharp on this machine and stores
      // hosted images in a local KV-backed store; `Alchemy.remote()`
      // opts into the real Images service instead.
      return devRemote?.[b.name] ? Images.remote(b.name) : Images.local({ binding: b.name });
    case "inherit":
      return yield* unsupported();
    case "json":
      return Json.local(b.name, b.json);
    case "k2":
      // Miniflare has no K2 simulation and no remote proxy for it yet.
      return yield* WorkerValidationError.make({
        message: `K2 binding "${b.name}" is not supported in local mode: K2 has no local simulation.`,
        hint: "Run K2 producers against a deployed Worker (alchemy deploy).",
        value: b,
      });
    case "kv_namespace":
      // A `dev:` id belongs to a locally-emulated namespace; a real id is
      // a live namespace the dev worker proxies to.
      return isLocalId(b.namespaceId)
        ? KvNamespace.local({
            binding: b.name,
            id: b.namespaceId,
            mode: isInstantNamespaceLocalId(b.namespaceId) ? "instant" : undefined,
          })
        : KvNamespace.remote(b.name, b.namespaceId);
    case "mtls_certificate":
      return MtlsCertificate.remote(b.name, b.certificateId);
    case "pipelines":
      return Pipelines.remote(b.name, b.pipeline);
    case "plain_text":
      return Text.local(b.name, b.text);
    case "queue": {
      // A real queueId belongs to an `Alchemy.remote()` queue. Queue bindings
      // are NOT supported in Cloudflare's remote/preview sessions — a
      // platform limitation (cloudflare/workers-sdk#9929) — so live
      // production goes through the deployed shim worker registered at
      // eval time (see `Queues/QueueShim.ts`): the local binding targets a
      // forwarder service that relays the queue wire protocol to the shim
      // over HTTPS with a bearer token.
      if (b.queueId !== undefined && !isLocalId(b.queueId)) {
        const url = b.shim?.url;
        const token = b.shim?.token;
        if (url === undefined || token === undefined) {
          // Defensive: binding data produced by current eval always carries
          // the shim for this mode combination.
          return yield* WorkerValidationError.make({
            message:
              `Queue binding "${b.name}" targets a live queue ` +
              "(Alchemy.remote()) but no producer shim was registered for it — " +
              "re-deploy, or remove remote() from the queue (local emulation).",
            value: b,
          });
        }
        return Queue.remote({
          binding: b.name,
          queueName: b.queueName,
          url,
          token: typeof token === "string" ? token : Redacted.value(token),
        });
      }
      return Queue.local({
        binding: b.name,
        queueName: b.queueName,
      });
    }
    case "r2_bucket":
      // A `dev:`-prefixed bucket name belongs to a locally-emulated bucket
      // (R2 has no opaque id — the name is the identity); a real name is a
      // live bucket the dev worker proxies to. Local buckets are also served
      // on the Worker's local S3 endpoint, so presigned URLs and S3 clients
      // work in dev without extra configuration.
      return isLocalId(b.bucketName)
        ? R2Bucket.local({
            binding: b.name,
            id: b.bucketName,
            s3Credentials: LOCAL_R2_S3_CREDENTIALS,
          })
        : R2Bucket.remote(b.name, b.bucketName, b.jurisdiction);
    case "ratelimit":
      return RateLimit.local({
        binding: b.name,
        simple: b.simple,
        namespaceId: b.namespaceId,
      });
    case "secret_key":
      // workerd imports the key natively: raw material passes through as
      // base64, pkcs8/spki base64 DER is PEM-wrapped, and JWK objects are
      // serialized — all handled by the hook.
      return SecretKey.local({
        binding: b.name,
        format: b.format,
        algorithm: b.algorithm,
        usages: b.usages,
        keyBase64: b.keyBase64,
        keyJwk: b.keyJwk,
      });
    case "secret_text":
      return Text.local(b.name, b.text);
    case "secrets_store_secret":
      // A `dev:` store id belongs to a locally-emulated Secrets Store
      // (local Store/Secret providers seed the simulator); a real id is a
      // live secret the dev worker proxies to (`Alchemy.remote()`).
      return isLocalId(b.storeId)
        ? SecretsStore.local({
            binding: b.name,
            storeId: b.storeId,
            secretName: b.secretName,
          })
        : SecretsStore.remote(b.name, b.storeId, b.secretName);
    case "send_email":
      // Local emulation validates and persists sent mail as `.eml` files
      // under the local storage's `email/` dir; `Alchemy.remote()` on the
      // descriptor opts into the real Email service instead.
      return SendEmail[devRemote?.[b.name] ? "remote" : "local"]({
        binding: b.name,
        destinationAddress: b.destinationAddress,
        allowedDestinationAddresses: b.allowedDestinationAddresses,
        allowedSenderAddresses: b.allowedSenderAddresses,
      });
    case "self_service":
      // A service binding to the worker itself: served in-process by the
      // runtime's self service (bypasses the assets middleware), matching
      // the production `service: <own name>` lowering.
      return Service.self(b.name, { entrypoint: b.entrypoint, props: b.props });
    case "service":
      return Service.local({
        binding: b.name,
        scriptName: b.service,
        entrypoint: b.entrypoint,
        props: b.props,
      });
    case "stream":
      // Local emulation stores videos in a local simulator (no transcoding,
      // no signed URLs) and serves each video's `preview` URL at
      // /cdn-cgi/mf/stream/<id>/watch on the dev URL; `Alchemy.remote()`
      // opts into the real Stream service instead.
      return devRemote?.[b.name] ? StreamSim.remote(b.name) : StreamSim.local({ binding: b.name });
    case "text_blob":
      return Data.local(b.name, Buffer.from(b.part));
    case "vectorize":
      return Vectorize.remote(b.name, b.indexName);
    case "version_metadata":
      return VersionMetadata.local(b.name);
    case "vpc_service":
      // A VPC service tunnels into a private network — nothing to emulate
      // locally, so the dev worker always proxies to the real service
      // through the remote-binding bridge.
      return VpcService.remote(b.name, b.serviceId);
    case "wasm_module":
      return WasmModule.local(b.name, Buffer.from(b.part));
    case "worker_loader":
      return WorkerLoader.local(b.name);
    case "workflow":
      return Workflows.local({
        binding: b.name,
        workflowName: b.workflowName,
        className: b.className,
        scriptName: b.scriptName,
      });
    default:
      return yield* unsupported();
  }
});

/**
 * Turns the serializable half of a local Worker configuration into the
 * cloudflare-runtime binding hooks consumed by `Runtime.start`.
 *
 * Kept in a leaf module, independent of the provider, so a Vite child
 * process can reconstruct the hooks after receiving plain binding
 * descriptors from its parent without evaluating the provider's module
 * graph. Binding hooks themselves are Effects and cannot cross a process
 * boundary.
 *
 * `config.env` must already be resolved to plain values — `Worker.URL`
 * sentinels substituted with the actual dev-proxy URL by the caller.
 */
export const materializeRuntimeBindings = Effect.fn(function* (
  config: {
    name: string;
    env?: Record<string, unknown>;
    hasAssets: boolean;
    bindingDescriptors: WorkerBinding[];
    /** Binding name → opt-out of local emulation (`Alchemy.remote()`). */
    devRemote?: Record<string, boolean>;
    /**
     * Simulated Cloudflare Access config (`dev: { access: ... }`), lowered
     * into the `ALCHEMY_DEV_ACCESS` env binding the worker bridge reads to
     * serve `ctx.access` locally.
     */
    devAccess?: { aud?: string; identity?: Record<string, unknown> };
  },
  options: {
    accountId: string;
    selfUrl: string | undefined;
    stack: { name: string; stage: string };
  },
) {
  // Resource-backed env entries (e.g. `env: { KV: namespace }`) are
  // represented by their binding descriptor (same name) — don't ALSO
  // serialize the resolved attributes as a duplicate json binding.
  const descriptorNames = new Set(config.bindingDescriptors.map((descriptor) => descriptor.name));
  const workerBindings: BindingHook<BindingServices>[] = [
    Text.local("ALCHEMY_PHASE", "runtime"),
    Text.local("ALCHEMY_WORKER_NAME", config.name),
    Text.local("ALCHEMY_STACK_NAME", options.stack.name),
    Text.local("ALCHEMY_STAGE", options.stack.stage),
    Text.local("ALCHEMY_CLOUDFLARE_ACCOUNT_ID", options.accountId),
    ...Object.entries(config.env ?? {})
      .filter(([key]) => !descriptorNames.has(key))
      .map(([key, value]) => {
        const unredacted = Redacted.isRedacted(value) ? Redacted.value(value) : value;
        return typeof unredacted === "string"
          ? Text.local(key, unredacted)
          : Json.local(key, unredacted);
      }),
    ...(config.hasAssets ? [Assets.local("ASSETS")] : []),
    ...(config.devAccess !== undefined ? [Json.local("ALCHEMY_DEV_ACCESS", config.devAccess)] : []),
  ];
  for (const descriptor of config.bindingDescriptors) {
    if (descriptor.type === "self_url") {
      // Lowered here rather than in `toRuntimeBinding` — only the caller
      // knows the worker's own dev-proxy URL.
      workerBindings.push(Text.local(descriptor.name, options.selfUrl!));
      continue;
    }
    if (descriptor.type === "r2_s3_credentials") {
      // `Cloudflare.R2.S3Credentials` over a `dev:` bucket: credentials for
      // this Worker's local S3 endpoint (the dev-proxy URL, known only
      // here), plus a bucket binding so the runtime serves the bucket on
      // that endpoint.
      workerBindings.push(
        Text.local(
          descriptor.name,
          JSON.stringify({
            endpoint: `${options.selfUrl!}${LOCAL_R2_S3_PATH}`,
            bucketName: descriptor.bucketName,
            region: "auto",
            ...LOCAL_R2_S3_CREDENTIALS,
          }),
        ),
        R2Bucket.local({
          binding: `${descriptor.name}__BUCKET`,
          id: descriptor.bucketName,
          s3Credentials: LOCAL_R2_S3_CREDENTIALS,
        }),
      );
      continue;
    }
    workerBindings.push(yield* toRuntimeBinding(descriptor, config.devRemote));
  }
  return workerBindings;
});