effect-cf 0.33.0 → 0.35.0

package/src/ComputerWorkspace.ts

@@ -100,6 +100,17 @@ export class WorkspaceAssetsError extends Schema.TaggedError<WorkspaceAssetsErro
   },
 ) {}
 
+/** Schema-serializable error while acquiring the Computer workspace client. */
+export class WorkspaceAcquireError extends Schema.TaggedError<WorkspaceAcquireError>()(
+  "WorkspaceAcquireError",
+  {
+    operation: Schema.String,
+    message: Schema.String,
+    code: Schema.optionalKey(Schema.String),
+    cause: Schema.optionalKey(Schema.Defect({ includeStack: true })),
+  },
+) {}
+
 export type WorkspaceReadFileOptions = Omit<CloudflareReadFileOptions, "encoding">;
 export type ReadTextFileOptions = WorkspaceReadFileOptions;
 export type ListDirectoryOptions = CloudflareReaddirOptions;
@@ -128,7 +139,6 @@ export interface WorkspaceReadFile {
   ): Effect.Effect<ReadableStream<Uint8Array>, WorkspaceFsError>;
 }
 
-/** Complete Effect wrapper of `WorkspaceClient.fs`. */
 export interface ComputerWorkspaceFilesystem {
   readonly readFile: WorkspaceReadFile;
   readonly stat: (path: string) => Effect.Effect<WorkspaceEntryStat, WorkspaceFsError>;
@@ -173,7 +183,6 @@ export type WorkspaceGitDiffOptions = CloudflareGitDiffOptions;
 export type WorkspaceGitCommitOptions = CloudflareGitCommitOptions;
 
 export interface WorkspaceGitLogOptions extends Omit<CloudflareGitLogOptions, "depth"> {
-  /** Preferred upstream name for the history bound. */
   readonly depth?: number;
   /** Consumer-port compatibility alias for `depth`. */
   readonly maxCount?: number;
@@ -235,7 +244,6 @@ export type WorkspaceExecOptions<Encoding extends WorkspaceExecEncoding = "utf8"
   "encoding" | "timeoutMs"
 > & {
   readonly encoding?: Encoding;
-  /** Upstream runtime option name. */
   readonly timeoutMs?: number;
   /** Consumer-port compatibility alias for `timeoutMs`. */
   readonly timeoutMillis?: number;
@@ -334,7 +342,6 @@ export interface WorkspaceExecCollect {
   ): Effect.Effect<WorkspaceExecResult<"binary">, WorkspaceExecError>;
 }
 
-/** Complete Effect wrapper of `WorkspaceClient.runtime`. */
 export interface ComputerWorkspaceRuntime {
   readonly exec: WorkspaceExec;
   readonly execCollect: WorkspaceExecCollect;
@@ -349,7 +356,6 @@ export interface ComputerWorkspaceRuntime {
   ) => Effect.Effect<void, WorkspaceExecError>;
 }
 
-/** Effect wrapper over a configured local `Workspace.assets` client. */
 export interface ComputerWorkspaceAssets {
   readonly share: (
     path: string,
@@ -368,7 +374,6 @@ export type ComputerWorkspaceThink = {
   >;
 };
 
-/** Effect service over every client surface exposed by Cloudflare Computer. */
 export interface ComputerWorkspaceService {
   readonly fs: ComputerWorkspaceFilesystem;
   readonly git: ComputerWorkspaceGit;
@@ -377,7 +382,6 @@ export interface ComputerWorkspaceService {
   readonly assets: ComputerWorkspaceAssets | undefined;
   readonly think: ComputerWorkspaceThink | undefined;
 
-  /** Flat filesystem aliases retained for mechanical consumer migration. */
   readonly readFile: WorkspaceReadFile;
   readonly stat: ComputerWorkspaceFilesystem["stat"];
   readonly lstat: ComputerWorkspaceFilesystem["lstat"];
@@ -395,7 +399,6 @@ export interface ComputerWorkspaceService {
   readonly chmod: ComputerWorkspaceFilesystem["chmod"];
   readonly symlink: ComputerWorkspaceFilesystem["symlink"];
 
-  /** Flat runtime aliases retained for mechanical consumer migration. */
   readonly exec: WorkspaceExec;
   readonly execCollect: WorkspaceExecCollect;
   readonly getExec: WorkspaceGetExec;
@@ -477,6 +480,21 @@ const execError = (operation: string, cause: unknown) => {
   return WorkspaceExecError.make(properties);
 };
 
+const acquireError = (operation: string, cause: unknown) => {
+  const properties: WorkspaceOperationErrorProperties = {
+    operation,
+    message: errorMessage(cause),
+    cause,
+  };
+  const code = errorCode(cause);
+
+  if (code !== undefined) {
+    properties.code = code;
+  }
+
+  return WorkspaceAcquireError.make(properties);
+};
+
 const assetsError = (operation: string, path: string, cause: unknown) => {
   const properties: WorkspaceFsErrorProperties = {
     operation,
@@ -895,9 +913,6 @@ const wrapRun = <Encoding extends WorkspaceExecEncoding>(
   return { id: handle.id, backend: handle.backend, events, result, kill };
 };
 
-const releaseRun = (handle: CloudflareWorkspaceRuntimeExecHandle<"utf8" | undefined>) =>
-  Effect.sync(() => handle[Symbol.dispose]());
-
 const makeRuntime = (client: CloudflareWorkspaceClient): ComputerWorkspaceRuntime => {
   const execImplementation = Effect.fn("ComputerWorkspace.runtime.exec", {
     attributes: { family: "runtime", operation: "exec" },
@@ -913,7 +928,7 @@ const makeRuntime = (client: CloudflareWorkspaceClient): ComputerWorkspaceRuntim
       : undefined;
 
     yield* Effect.annotateCurrentSpan({ backend: options?.backend, runId: options?.id });
-    const handle = yield* Effect.acquireRelease(
+    const handle = yield* Effect.acquireDisposable(
       Effect.tryPromise({
         try: () => {
           if (Predicate.isString(source)) {
@@ -934,7 +949,6 @@ const makeRuntime = (client: CloudflareWorkspaceClient): ComputerWorkspaceRuntim
         },
         catch: (cause) => execError("exec", cause),
       }),
-      releaseRun,
     );
 
     // SAFETY: runtimeExecOptions carries Encoding to Cloudflare's corresponding handle overload.
@@ -953,12 +967,11 @@ const makeRuntime = (client: CloudflareWorkspaceClient): ComputerWorkspaceRuntim
     options?: WorkspaceGetExecOptions<Encoding>,
   ) {
     yield* Effect.annotateCurrentSpan({ backend: options?.backend, runId: id });
-    const handle = yield* Effect.acquireRelease(
+    const handle = yield* Effect.acquireDisposable(
       Effect.tryPromise({
         try: () => client.runtime.getExec(id, runtimeGetOptions(options)),
         catch: (cause) => execError("getExec", cause),
       }),
-      releaseRun,
     );
 
     // SAFETY: runtimeGetOptions carries Encoding to Cloudflare's corresponding handle overload.
@@ -1169,7 +1182,6 @@ export const fromWorkspaceClient = (
   };
 };
 
-/** Effect service for the workspace owned by the enclosing Durable Object. */
 export class ComputerWorkspace extends Context.Service<
   ComputerWorkspace,
   ComputerWorkspaceService
@@ -1178,25 +1190,31 @@ export class ComputerWorkspace extends Context.Service<
    * Acquires the single workspace registered by `withComputerWorkspace` and
    * releases its RPC client when the layer scope closes.
    */
-  static readonly layer: Layer.Layer<ComputerWorkspace, never, DurableObjectState> = Layer.effect(
-    ComputerWorkspace,
-    Effect.gen(function* () {
-      const state = yield* DurableObjectState;
-      const host = HostRegistry.lookup(state.raw);
-
-      if (host === undefined) {
-        return yield* Effect.die(
-          "ComputerWorkspace.layer requires a Durable Object class built with withComputerWorkspace",
+  static readonly layer: Layer.Layer<ComputerWorkspace, WorkspaceAcquireError, DurableObjectState> =
+    Layer.effect(
+      ComputerWorkspace,
+      Effect.gen(function* () {
+        const state = yield* DurableObjectState;
+        const host = HostRegistry.lookup(state.raw);
+
+        if (host === undefined) {
+          return yield* Effect.die(
+            "ComputerWorkspace.layer requires a Durable Object class built with withComputerWorkspace",
+          );
+        }
+
+        const computer = yield* Effect.tryPromise({
+          try: () => import("@cloudflare/computer"),
+          catch: (cause) => acquireError("import", cause),
+        });
+        const client = yield* Effect.acquireDisposable(
+          Effect.tryPromise({
+            try: () => computer.getWorkspace(host),
+            catch: (cause) => acquireError("getWorkspace", cause),
+          }),
         );
-      }
-
-      const computer = yield* Effect.promise(() => import("@cloudflare/computer"));
-      const client = yield* Effect.acquireRelease(
-        Effect.promise(() => computer.getWorkspace(host)),
-        (workspace) => Effect.sync(() => workspace[Symbol.dispose]()),
-      );
 
-      return ComputerWorkspace.of(fromWorkspaceClient(client));
-    }),
-  );
+        return ComputerWorkspace.of(fromWorkspaceClient(client));
+      }),
+    );
 }

package/src/ComputerWorkspaceHost.ts

@@ -47,7 +47,6 @@ export type {
   WorkspaceSpan,
 };
 
-/** The value of a `worker_loaders` binding. */
 export type DynamicWorkerLoader = WorkerShellLoader;
 
 /** Default author and committer identity for workspace Git operations. */
@@ -75,21 +74,14 @@ export interface ComputerWorkspaceShellOptions extends Omit<
   "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. */

package/src/ContainerNamespace.ts

@@ -6,13 +6,10 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedContainerNamespace = "Container namespace binding with getByName()";
 
-/** Named signal accepted by Cloudflare Container instances. */
 export type ContainerSignal = "SIGKILL" | "SIGINT" | "SIGTERM";
 
-/** Named or numeric signal accepted by Container `stop()`. */
 export type ContainerStopSignal = ContainerSignal | number;
 
-/** Per-instance Container startup configuration. */
 export interface ContainerStartOptions {
   readonly envVars?: Record<string, string>;
   readonly entrypoint?: Array<string>;
@@ -34,7 +31,6 @@ export interface ContainerReadinessOptions {
   readonly waitInterval?: number;
 }
 
-/** Options for starting a Container and waiting for its ports. */
 export interface ContainerStartAndWaitForPortsOptions {
   readonly startOptions?: ContainerStartOptions;
   readonly ports?: number | Array<number>;
@@ -77,7 +73,6 @@ export interface ContainerStub {
   removeDeniedHost(hostname: string): Promise<void>;
 }
 
-/** Native Container namespace binding shape. */
 export interface ContainerNamespaceResource {
   getByName(
     name: string,
@@ -85,18 +80,14 @@ export interface ContainerNamespaceResource {
   ): ContainerStub;
 }
 
-/** Exact native stub type produced by a Container namespace binding. */
 export type ContainerStubOf<Namespace extends ContainerNamespaceResource> = ReturnType<
   Namespace["getByName"]
 >;
 
-/** Container namespace binding metadata. */
 export interface ContainerNamespaceDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
-/** Failure raised when invoking a named Container operation. */
 export class ContainerOperationError extends Data.TaggedError("ContainerOperationError")<{
   readonly binding: string;
   readonly instance: string;
@@ -108,7 +99,6 @@ export class ContainerOperationError extends Data.TaggedError("ContainerOperatio
   }
 }
 
-/** Effect-wrapped client for one named Container instance. */
 export interface ContainerInstanceClient<Stub extends ContainerStub = ContainerStub> {
   readonly rawUnsafe: Effect.Effect<Stub, ContainerOperationError>;
   readonly state: Effect.Effect<ContainerState, ContainerOperationError>;
@@ -140,7 +130,6 @@ export interface ContainerInstanceClient<Stub extends ContainerStub = ContainerS
   readonly removeDeniedHost: (hostname: string) => Effect.Effect<void, ContainerOperationError>;
 }
 
-/** Effect client for a Container namespace binding. */
 export interface ContainerNamespaceClient<
   Namespace extends ContainerNamespaceResource = ContainerNamespaceResource,
 > {
@@ -433,14 +422,12 @@ export const make = <Id extends string>(id: Id) => Tag<ContainerNamespaceService
 
 declare const ContainerNamespaceServiceTypeId: unique symbol;
 
-/** Nominal service marker for Container namespaces created with {@link make}. */
 export interface ContainerNamespaceService<Id extends string> {
   readonly [ContainerNamespaceServiceTypeId]: {
     readonly id: Id;
   };
 }
 
-/** Creates a typed Effect service for a Cloudflare Container namespace. */
 export const Tag =
   <Self, Namespace extends ContainerNamespaceResource = ContainerNamespaceResource>() =>
   <Id extends string>(id: Id) => {

package/src/D1.ts

@@ -10,18 +10,14 @@ const TypeId = "~effect-cf/D1" as const;
 export type TypeId = typeof TypeId;
 const expectedD1Database = "D1 database binding with prepare(), batch(), and exec()";
 
-/** Typed D1 binding definition. */
 export interface D1Definition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
-/** Options forwarded to `@effect/sql-d1` when building a SQL client layer. */
 export type D1SqlLayerOptions = Omit<D1Client.D1ClientConfig, "db">;
 
 declare const D1ServiceTypeId: unique symbol;
 
-/** Nominal service marker for D1 services created with {@link make}. */
 export interface D1Service<Id extends string> {
   readonly [D1ServiceTypeId]: {
     readonly id: Id;
@@ -36,27 +32,9 @@ const isD1Database = <Candidate>(value: Candidate): value is Candidate & D1Datab
   Predicate.hasProperty(value, "exec") &&
   Predicate.isFunction(value.exec);
 
-/**
- * Creates a typed D1 service tag plus Effect helpers.
- */
 export const make = <Id extends string>(id: Id, definition: D1Definition) =>
   Service<D1Service<Id>>()(id, definition);
 
-/**
- * Builds a D1 service around a Cloudflare D1 database binding.
- *
- * The returned service exposes the raw `D1Database` binding and `sqlLayer(...)`
- * for providing `effect/unstable/sql` via `@effect/sql-d1`.
- *
- * @example
- * ```ts
- * class TodoDatabase extends D1.Service<TodoDatabase>()("TodoDatabase", {
- *   binding: "TODO_DB",
- * }) {}
- *
- * const SqlLive = TodoDatabase.sqlLayer();
- * ```
- */
 export const Service =
   <Self>() =>
   <Id extends string>(id: Id, definition: D1Definition) => {

package/src/DurableObject.ts

@@ -1,34 +1,38 @@
 import { DurableObject as CloudflareDurableObject } from "cloudflare:workers";
-import { Effect, Layer, type ManagedRuntime, type Scope } from "effect";
+import { Effect, Layer, type ManagedRuntime, type Scope, Tracer } from "effect";
 
 import { NativeRequest } from "./Worker";
 import { WorkerEnvironment, type WorkerEnv } from "./Environment";
 import { DurableObjectState, fromDurableObjectState } from "./DurableObjectState";
 import { fromWebSocket, type DurableWebSocket } from "./DurableObjectWebSocket";
+import * as RpcDefinition from "./RpcDefinition";
 import * as Entrypoint from "./internal/Entrypoint";
 import * as Runtime from "./internal/Runtime";
 import * as Telemetry from "./internal/Telemetry";
+import type { ReceiverOptions, RpcInvocationInfo } from "./RpcTracing";
 
-const reservedMethodNames = new Set<string>([
-  "constructor",
-  "dup",
-  "fetch",
-  "alarm",
-  "webSocketMessage",
-  "webSocketClose",
-  "webSocketError",
-]);
+const reservedMethodNames: ReadonlySet<string> = RpcDefinition.reservedMethodNames;
 
 type RuntimeContext<ROut> = DurableObjectState | WorkerEnvironment | ROut;
 
 type HandlerContext<ROut> = RuntimeContext<ROut> | Scope.Scope;
 
 type FetchContext<ROut> = HandlerContext<ROut> | NativeRequest;
-type RunOptions = {
+/** Metadata available before an event effect or its event layer starts. */
+export interface RunOptions {
   readonly eventLayer?: boolean;
-};
+  readonly event?:
+    | "fetch"
+    | "rpc"
+    | "alarm"
+    | "webSocketMessage"
+    | "webSocketClose"
+    | "webSocketError";
+  readonly rpc?: RpcInvocationInfo;
+}
 
-const RunSymbol = Symbol.for("effect-cf/DurableObject/run");
+/** Override to instrument the whole event, then call super[RunSymbol]. */
+export const RunSymbol = Symbol.for("effect-cf/DurableObject/run");
 
 const scheduleTelemetryFlush: Effect.Effect<void, never, DurableObjectState> =
   Telemetry.scheduleTelemetryFlush((flush) =>
@@ -74,9 +78,6 @@ export type RpcHandlers<ROut, Api> = {
     : never;
 };
 
-/**
- * Options for creating a Durable Object class backed by Effect handlers.
- */
 export interface DurableObjectOptions<
   RRuntime,
   REvent = never,
@@ -113,15 +114,10 @@ export interface DurableObjectOptions<
    * does not.
    */
   readonly rpc?: Rpc;
-  /** Optional fetch handler for HTTP/WebSocket requests. */
+  /** Accept live native trace metadata. The client must also enable rpcTracing. */
+  readonly rpcTracing?: ReceiverOptions;
   readonly fetch?: Effect.Effect<Response, unknown, FetchContext<RRuntime | REvent>>;
-  /**
-   * Optional logical alarm processing effect.
-   *
-   * This runs before `alarm` and should be built with helpers such as
-   * `DurableObjectAlarm.processDue(...)` so the reusable scheduler stays inside
-   * the Durable Object's single managed runtime boundary.
-   */
+
   readonly alarms?: Effect.Effect<unknown, unknown, HandlerContext<RRuntime | REvent>>;
   /**
    * Optional raw alarm handler.
@@ -156,10 +152,19 @@ export interface DurableObjectOptions<
 export type DurableObjectClass<Rpc extends DurableObjectRpc<ROut>, ROut> = new (
   state: globalThis.DurableObjectState,
   env: WorkerEnv,
-) => CloudflareDurableObject<WorkerEnv> & DurableObjectRpcApi<Rpc, ROut>;
+) => CloudflareDurableObject<WorkerEnv> &
+  DurableObjectRpcApi<Rpc, ROut> & {
+    [RunSymbol]<A, E>(
+      effect: Effect.Effect<A, E, HandlerContext<ROut>>,
+      options?: RunOptions,
+    ): Promise<A>;
+  };
 
 /**
- * Creates a Durable Object class backed by a single managed Effect runtime.
+ * Builds a Durable Object whose base `layer` lives for the in-memory instance.
+ * Cloudflare does not expose an eviction or shutdown hook, so finalizers in
+ * that layer are not guaranteed to run. Put resources that require timely
+ * release in `eventLayer`, whose scope closes after each handled event.
  */
 export const make = <
   ROut,
@@ -195,6 +200,8 @@ export const make = <
       runOptions: RunOptions = {},
     ): Promise<A> {
       const eventLayer = runOptions.eventLayer === false ? undefined : options.eventLayer;
+      const parent = runOptions.rpc?.parent;
+      const parentSpan = parent === undefined ? undefined : Tracer.externalSpan(parent);
 
       if (eventLayer === undefined) {
         // SAFETY: event-layer bypass is used only for initialize; otherwise an absent layer means REvent is never.
@@ -202,6 +209,8 @@ export const make = <
           this.runtime,
           // @effect-diagnostics-next-line unsafeEffectTypeAssertion:off
           effect as Effect.Effect<A, E, HandlerContext<ROut>>,
+          undefined,
+          parentSpan,
         );
       }
 
@@ -212,7 +221,7 @@ export const make = <
         REvent,
         EventLayerError,
         LayerError
-      >(this.runtime, effect, eventLayer);
+      >(this.runtime, effect, eventLayer, parentSpan);
     }
 
     fetch(request: Request): Promise<Response> {
@@ -222,7 +231,9 @@ export const make = <
         return Promise.resolve(new Response("Not Found", { status: 404 }));
       }
 
-      return this[RunSymbol](Effect.provideService(fetchHandler, NativeRequest, request));
+      return this[RunSymbol](Effect.provideService(fetchHandler, NativeRequest, request), {
+        event: "fetch",
+      });
     }
 
     alarm(alarmInfo?: globalThis.AlarmInvocationInfo): Promise<void> | void {
@@ -237,13 +248,17 @@ export const make = <
           : (logicalAlarms ?? rawAlarm);
 
       if (alarmEffect !== undefined) {
-        return this[RunSymbol](alarmEffect.pipe(Effect.onExit(() => scheduleTelemetryFlush)));
+        return this[RunSymbol](alarmEffect.pipe(Effect.onExit(() => scheduleTelemetryFlush)), {
+          event: "alarm",
+        });
       }
     }
 
     webSocketMessage(socket: WebSocket, message: string | ArrayBuffer): Promise<void> | void {
       if (options.webSocketMessage !== undefined) {
-        return this[RunSymbol](options.webSocketMessage(fromWebSocket(socket), message));
+        return this[RunSymbol](options.webSocketMessage(fromWebSocket(socket), message), {
+          event: "webSocketMessage",
+        });
       }
     }
 
@@ -256,13 +271,16 @@ export const make = <
       if (options.webSocketClose !== undefined) {
         return this[RunSymbol](
           options.webSocketClose(fromWebSocket(socket), code, reason, wasClean),
+          { event: "webSocketClose" },
         );
       }
     }
 
     webSocketError(socket: WebSocket, cause: unknown): Promise<void> | void {
       if (options.webSocketError !== undefined) {
-        return this[RunSymbol](options.webSocketError(fromWebSocket(socket), cause));
+        return this[RunSymbol](options.webSocketError(fromWebSocket(socket), cause), {
+          event: "webSocketError",
+        });
       }
     }
   }
@@ -272,8 +290,9 @@ export const make = <
     EffectDurableObject.prototype,
     options.rpc,
     reservedMethodNames,
-    (self, effect) => self[RunSymbol](effect),
+    (self, effect, rpc) => self[RunSymbol](effect, { event: "rpc", rpc }),
     () => scheduleTelemetryFlush,
+    options.rpcTracing,
   );
 
   return Entrypoint.assumeEntrypointClass<DurableObjectClass<Rpc, ROut | REvent>>(