effect-cf 0.25.3 → 0.27.0

package/src/ComputerWorkspaceHost.ts

@@ -0,0 +1,216 @@
+import { createGitClient, type GitClientFactory } from "@cloudflare/computer/git";
+import {
+  type DurableObjectStorageLike,
+  type WithWorkspaceCtor,
+  type WorkspaceHandle,
+  type WorkspaceObserver,
+  type WorkspaceOptions,
+  type WorkspaceRegisteredBackend,
+  type WorkspaceRetryPendingSyncResult,
+  type WorkspaceSpan,
+  type WorkspaceAttributes,
+  type WorkspaceAttributeValue,
+  type SyncRetryIntent,
+  type SyncRetryOptions,
+  type SyncRetryScheduler,
+  withWorkspace,
+} from "@cloudflare/computer";
+import {
+  WorkerShellBackend,
+  type ShellModuleGroup,
+  type WorkerShellBackendOptions,
+  type WorkerShellLoader,
+  type WorkspaceEgressPolicy,
+} from "@cloudflare/computer/backends/worker-shell";
+
+import type * as Artifacts from "./Artifacts";
+import * as HostRegistry from "./internal/ComputerWorkspaceHostRegistry";
+
+/**
+ * The worker-shell backend resolves this exact export through
+ * `ctx.exports.WorkspaceServiceProxy`. Every Worker that configures
+ * {@link withComputerWorkspace} with `shell` must re-export it from its main
+ * module.
+ */
+export { WorkspaceServiceProxy } from "@cloudflare/computer";
+
+export type {
+  ShellModuleGroup,
+  SyncRetryIntent,
+  SyncRetryOptions,
+  SyncRetryScheduler,
+  WorkspaceAttributeValue,
+  WorkspaceAttributes,
+  WorkspaceEgressPolicy,
+  WorkspaceObserver,
+  WorkspaceRetryPendingSyncResult,
+  WorkspaceSpan,
+};
+
+/** The value of a `worker_loaders` binding. */
+export type DynamicWorkerLoader = WorkerShellLoader;
+
+/** Default author and committer identity for workspace Git operations. */
+export interface ComputerWorkspaceGitIdentity {
+  readonly name: string;
+  readonly email: string;
+}
+
+/** Session-scoped Artifacts configuration passed through to `Workspace`. */
+export interface ComputerWorkspaceArtifactsOptions {
+  readonly binding: Artifacts.ArtifactsBinding;
+  /**
+   * Session prefix for repository names. When omitted, `sessionId` from the
+   * enclosing host configuration is used.
+   */
+  readonly sessionId?: string;
+}
+
+/**
+ * Worker-shell backend options with the loopback workspace wiring named in
+ * Durable Object terms.
+ */
+export interface ComputerWorkspaceShellOptions extends Omit<
+  WorkerShellBackendOptions,
+  "source" | "loader" | "workspace" | "ctx" | "egress"
+> {
+  readonly loader: DynamicWorkerLoader;
+  /** Durable Object namespace binding that points back to the wrapped class. */
+  readonly hostBinding: string;
+  /** Current Durable Object id, normally `ctx.id.toString()`. */
+  readonly hostId: string;
+  /** Current Durable Object execution context, normally `ctx`. */
+  readonly executionContext: unknown;
+  /** Dynamic Worker egress policy. Defaults to `{ mode: "none" }`. */
+  readonly egress?: WorkspaceEgressPolicy;
+}
+
+/** Configuration accepted by {@link withComputerWorkspace}. */
+export interface ComputerWorkspaceHostConfig {
+  /** Native SQLite-backed Durable Object storage (`ctx.storage`). */
+  readonly storage: globalThis.DurableObjectStorage | DurableObjectStorageLike;
+  /** Stable workspace id used by mounts and as the default Artifacts session. */
+  readonly sessionId?: string;
+  readonly gitIdentity?: ComputerWorkspaceGitIdentity;
+  /** Override the default `createGitClient()` factory. */
+  readonly git?: GitClientFactory;
+  /** Additional container, Worker JavaScript, shell, or custom backends. */
+  readonly backends?: ReadonlyArray<WorkspaceRegisteredBackend>;
+  /** Convenience wiring for one Worker Shell backend. */
+  readonly shell?: ComputerWorkspaceShellOptions;
+  readonly mounts?: WorkspaceOptions["mounts"];
+  readonly observer?: WorkspaceOptions["observer"];
+  readonly retryScheduler?: WorkspaceOptions["retryScheduler"];
+  readonly retry?: WorkspaceOptions["retry"];
+  readonly assets?: WorkspaceOptions["assets"];
+  readonly artifacts?: ComputerWorkspaceArtifactsOptions;
+  readonly now?: WorkspaceOptions["now"];
+  readonly useThink?: WorkspaceOptions["useThink"];
+}
+
+const toWorkspaceOptions = (config: ComputerWorkspaceHostConfig): WorkspaceOptions => {
+  const backends = [...(config.backends ?? [])];
+
+  if (config.shell !== undefined) {
+    const { egress, executionContext, hostBinding, hostId, loader, ...shellOptions } = config.shell;
+
+    backends.push(
+      new WorkerShellBackend({
+        ...shellOptions,
+        loader,
+        workspace: { binding: hostBinding, id: hostId },
+        ctx: executionContext,
+        egress: egress ?? { mode: "none" },
+      }),
+    );
+  }
+
+  return {
+    storage: config.storage as DurableObjectStorageLike,
+    git: config.git ?? createGitClient(),
+    ...(config.gitIdentity === undefined ? {} : { defaultGitIdentity: config.gitIdentity }),
+    ...(backends.length === 0 ? {} : { backends }),
+    ...(config.sessionId === undefined ? {} : { sessionId: config.sessionId }),
+    ...(config.mounts === undefined ? {} : { mounts: config.mounts }),
+    ...(config.observer === undefined ? {} : { observer: config.observer }),
+    ...(config.retryScheduler === undefined ? {} : { retryScheduler: config.retryScheduler }),
+    ...(config.retry === undefined ? {} : { retry: config.retry }),
+    ...(config.assets === undefined ? {} : { assets: config.assets }),
+    ...(config.artifacts === undefined
+      ? {}
+      : {
+          artifacts: {
+            binding: config.artifacts.binding as unknown as NonNullable<
+              WorkspaceOptions["artifacts"]
+            >["binding"],
+            ...(config.artifacts.sessionId === undefined
+              ? {}
+              : { sessionId: config.artifacts.sessionId }),
+          },
+        }),
+    ...(config.now === undefined ? {} : { now: config.now }),
+    ...(config.useThink === undefined ? {} : { useThink: config.useThink }),
+  };
+};
+
+// Cloudflare constructs Durable Objects with `(state, env)`. Keeping the
+// remaining tuple open preserves arbitrary Effect-backed base constructors.
+type DurableObjectConstructor = new (...args: Array<any>) => object;
+
+const HostArguments = Symbol("effect-cf/ComputerWorkspaceHost/arguments");
+
+interface CapturedHostArguments {
+  readonly state: globalThis.DurableObjectState;
+  readonly env: unknown;
+}
+
+interface HostArgumentsInstance {
+  readonly [HostArguments]: CapturedHostArguments;
+}
+
+/**
+ * Wraps a Durable Object class with one SQLite-backed Cloudflare Computer
+ * workspace and registers that local workspace for {@link ComputerWorkspace}
+ * to acquire through its Effect layer.
+ *
+ * The class must use a `new_sqlite_classes` migration. If `shell` is present,
+ * its Worker must also configure a `worker_loaders` binding, enable the
+ * `experimental` compatibility flag, and export `WorkspaceServiceProxy`.
+ */
+export const withComputerWorkspace = <TBase extends DurableObjectConstructor>(
+  Base: TBase,
+  config: (
+    self: InstanceType<TBase>,
+    state: globalThis.DurableObjectState,
+    env: ConstructorParameters<TBase>[1],
+  ) => ComputerWorkspaceHostConfig,
+): WithWorkspaceCtor<TBase> => {
+  const CapturedBase = class extends (Base as DurableObjectConstructor) {
+    readonly [HostArguments]: CapturedHostArguments;
+
+    constructor(...args: Array<any>) {
+      super(...args);
+      this[HostArguments] = {
+        state: args[0] as globalThis.DurableObjectState,
+        env: args[1],
+      };
+    }
+  };
+
+  const WithWorkspace = withWorkspace(CapturedBase, (self) => {
+    const { env, state } = (self as HostArgumentsInstance)[HostArguments];
+
+    return toWorkspaceOptions(
+      config(self as InstanceType<TBase>, state, env as ConstructorParameters<TBase>[1]),
+    );
+  }) as unknown as DurableObjectConstructor;
+
+  class WithComputerWorkspace extends WithWorkspace {
+    constructor(...args: Array<any>) {
+      super(...args);
+      HostRegistry.register(args[0] as globalThis.DurableObjectState, this as WorkspaceHandle);
+    }
+  }
+
+  return WithComputerWorkspace as unknown as WithWorkspaceCtor<TBase>;
+};

package/src/WebTransport.ts

@@ -0,0 +1,123 @@
+/**
+ * Truthful WebTransport / HTTP/3 boundary for Cloudflare Workers.
+ *
+ * What Cloudflare supports today (verified against primary sources, August
+ * 2026):
+ *
+ * - Inbound HTTP/3 is a zone-level setting. Cloudflare's edge terminates the
+ *   QUIC connection and invokes the Worker with an ordinary `fetch` Request;
+ *   the inbound protocol is surfaced only as metadata on `request.cf`
+ *   ({@link inboundTransport}).
+ * - There is no runtime API for inbound WebTransport sessions — nothing
+ *   analogous to `WebSocketPair`. workerd contains no QUIC/HTTP-3 stack, and
+ *   the maintainers state WebTransport support "is not currently on our
+ *   priority list" (cloudflare/workerd#6451, discussion #6454).
+ * - There is no outbound WebTransport/QUIC/UDP client capability either;
+ *   `cloudflare:sockets` `connect()` is TCP-only, and
+ *   `@cloudflare/workers-types` contains no WebTransport types.
+ * - Workers and Durable Objects can accept inbound WebSocket connections;
+ *   Durable Objects additionally support hibernation (`acceptWebSocket`,
+ *   `webSocketMessage`, `webSocketClose`).
+ *
+ * Consequently a browser's WebTransport session can never reach Worker code:
+ * clients should attempt WebTransport only against origins that actually
+ * speak it, and fall back to WebSockets for Cloudflare-hosted endpoints (see
+ * the `effect-webtransport` package's `Fallback` module). This module gives
+ * that reality a typed shape: {@link capabilities} feature-detects what the
+ * current runtime provides, {@link inboundSessionsUnsupported} is the
+ * explicit typed boundary for the missing inbound API, and
+ * {@link inboundTransport} decodes the HTTP/3-relevant request metadata that
+ * the edge does provide.
+ */
+import type { Request as CloudflareRequest } from "@cloudflare/workers-types";
+import { Data, Effect, Option, Result, Schema as S } from "effect";
+
+/**
+ * Metadata Cloudflare's edge reports about the inbound client connection.
+ *
+ * `httpProtocol` and `clientTcpRtt` are declared in
+ * `@cloudflare/workers-types`; `clientQuicRtt` is documented by Cloudflare
+ * ("only present when the client connected over QUIC (HTTP/3)") but not yet
+ * present in the published types, so it is decoded from the open
+ * `Record<string, unknown>` side of `request.cf`.
+ */
+export class InboundTransport extends S.Class<InboundTransport>("InboundTransport")({
+  /** The HTTP protocol the client used, e.g. `"HTTP/2"` or `"HTTP/3"`. */
+  httpProtocol: S.String,
+  /** Client round-trip time; only present for QUIC (HTTP/3) connections. */
+  clientQuicRtt: S.optional(S.Number),
+  /** Client round-trip time; only present for TCP (HTTP/1.x, HTTP/2) connections. */
+  clientTcpRtt: S.optional(S.Number),
+}) {}
+
+const decodeInboundTransport = S.decodeUnknownResult(InboundTransport);
+
+/**
+ * Decodes the inbound transport metadata from `request.cf`.
+ *
+ * Returns `None` when the metadata is absent (for example in local `wrangler
+ * dev` or when a Worker invokes another Worker directly) or does not match
+ * the expected shape.
+ */
+export const inboundTransport = (
+  request: Pick<CloudflareRequest, "cf">,
+): Option.Option<InboundTransport> => Result.getSuccess(decodeInboundTransport(request.cf));
+
+/**
+ * Returns `true` when the client reached Cloudflare's edge over QUIC
+ * (HTTP/3). Prefers the documented QUIC signal (`clientQuicRtt` is only
+ * present for QUIC connections) and falls back to the `httpProtocol` string.
+ *
+ * Note this describes the browser→edge hop only: the edge always terminates
+ * QUIC, and the Worker still handles an ordinary `fetch` Request.
+ */
+export const isHttp3 = (transport: InboundTransport): boolean =>
+  transport.clientQuicRtt !== undefined || transport.httpProtocol === "HTTP/3";
+
+/** WebTransport-related capabilities of the current Workers runtime. */
+export interface Capabilities {
+  /**
+   * Whether Worker code can accept inbound WebTransport sessions. Typed as
+   * literally `false`: no such runtime API exists (cloudflare/workerd#6451),
+   * so this can only change through a breaking, deliberate update when
+   * Cloudflare ships one.
+   */
+  readonly inboundSessions: false;
+  /**
+   * Whether the runtime exposes a client `WebTransport` constructor global.
+   * Feature-detected at runtime; `false` in workerd today, which has no
+   * QUIC stack.
+   */
+  readonly outboundSessions: boolean;
+}
+
+/** Feature-detects the WebTransport capabilities of the current runtime. */
+export const capabilities: Effect.Effect<Capabilities> = Effect.sync(() => ({
+  inboundSessions: false,
+  outboundSessions: typeof (globalThis as Record<string, unknown>)["WebTransport"] === "function",
+}));
+
+/** WebTransport capability missing from the current Workers runtime. */
+export type WebTransportCapability = "inbound-sessions" | "outbound-sessions";
+
+/** Raised when a WebTransport capability is unavailable in this runtime. */
+export class WebTransportUnsupportedError extends Data.TaggedError("WebTransportUnsupportedError")<{
+  readonly capability: WebTransportCapability;
+}> {
+  override get message(): string {
+    return this.capability === "inbound-sessions"
+      ? "Cloudflare Workers cannot accept inbound WebTransport sessions: the edge terminates QUIC and no runtime session API exists (cloudflare/workerd#6451). Use Durable Object WebSockets for bidirectional push."
+      : "This Workers runtime provides no WebTransport client: workerd has no QUIC stack and cloudflare:sockets is TCP-only.";
+  }
+}
+
+/**
+ * The explicit typed boundary for inbound WebTransport sessions.
+ *
+ * Always fails with {@link WebTransportUnsupportedError} today. Route the
+ * code path that would accept a session through this effect so the
+ * limitation is visible in the type system and greppable when Cloudflare
+ * ships a real API.
+ */
+export const inboundSessionsUnsupported: Effect.Effect<never, WebTransportUnsupportedError> =
+  Effect.fail(new WebTransportUnsupportedError({ capability: "inbound-sessions" }));

package/src/index.ts

@@ -1,5 +1,6 @@
 export * as AiGateway from "./AiGateway";
 export * as AnalyticsEngine from "./AnalyticsEngine";
+export * as Artifacts from "./Artifacts";
 export * as Binding from "./Binding";
 export * as BrowserRendering from "./BrowserRendering";
 export * as Cache from "./Cache";
@@ -28,6 +29,7 @@ export * as Rpc from "./Rpc";
 export * as RpcDefinition from "./RpcDefinition";
 export * as ServiceBinding from "./ServiceBinding";
 export * as Vectorize from "./Vectorize";
+export * as WebTransport from "./WebTransport";
 export * as Worker from "./Worker";
 export * as WorkerDefinition from "./WorkerDefinition";
 export * as WorkersAi from "./WorkersAi";

package/src/internal/ComputerWorkspaceHostRegistry.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceHandle } from "@cloudflare/computer";
+
+const hosts = new WeakMap<globalThis.DurableObjectState, WorkspaceHandle>();
+
+export const register = (state: globalThis.DurableObjectState, host: WorkspaceHandle): void => {
+  hosts.set(state, host);
+};
+
+export const lookup = (state: globalThis.DurableObjectState): WorkspaceHandle | undefined =>
+  hosts.get(state);