effect-cf 0.32.1 → 0.34.0

package/src/ServiceBinding.ts

@@ -6,13 +6,11 @@ import * as RpcDefinition from "./RpcDefinition";
 import type * as WorkerDefinition from "./WorkerDefinition";
 import * as ErrorMessage from "./internal/ErrorMessage";
 import * as RpcInvocation from "./internal/RpcInvocation";
+import * as RpcTracing from "./RpcTracing";
 
 const TypeId = "effect-cf/ServiceBinding" as const;
 const expectedServiceBinding = "Worker service binding with fetch()";
 
-/**
- * Minimum shape for a Cloudflare service binding.
- */
 export interface ServiceFetcher {
   fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 }
@@ -27,9 +25,6 @@ type RpcClient<Api> = {
 
 type ReservedMethodName = WorkerDefinition.ReservedMethodName | "fetch";
 
-/**
- * Native Cloudflare service object including optional RPC methods.
- */
 export type ServiceBindingClient<Api extends object> = ServiceFetcher &
   RpcClient<CloudflareRpc.Provider<Api, ReservedMethodName>>;
 
@@ -47,10 +42,10 @@ type ApiOrDefinition<Api extends object, Definition> = [Api] extends [never]
 export interface ServiceBindingDefinition<
   Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
 > {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
-  /** Optional RPC schema used for argument/result encoding. */
   readonly definition?: Definition;
+  /** Append live trace context only when the receiver also enables rpcTracing. */
+  readonly rpcTracing?: boolean;
 }
 
 /**
@@ -112,22 +107,6 @@ export type ServiceBindingEffectClient<
   Api extends object,
   Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
 > = DirectMethods<never, Definition> & {
-  /**
-   * Forwards an HTTP request to the bound Worker service.
-   *
-   * Use this when the service binding is acting as an HTTP origin rather than a
-   * Cloudflare RPC target.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.gen(function* () {
-   *   const api = yield* ApiWorker;
-   *   return yield* api.fetch(new Request("https://internal.example/users"));
-   * });
-   * ```
-   */
   readonly fetch: (
     input: RequestInfo | URL,
     init?: RequestInit,
@@ -140,20 +119,6 @@ export type ServiceBindingEffectClient<
    * promise-like value and it does not decode definition-backed success schemas.
    *
    * Most application code should use {@link call} instead.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.gen(function* () {
-   *   const counter = yield* CounterService;
-   *
-   *   const result = yield* counter.rpc("increment", 41);
-   *   const value = yield* Effect.promise(() => result);
-   *
-   *   return value;
-   * });
-   * ```
    */
   readonly rpc: <Method extends ServiceMethodKey<Api>>(
     method: Method,
@@ -164,18 +129,6 @@ export type ServiceBindingEffectClient<
    * the success value when the binding was created from a definition.
    *
    * This is the normal choice when application code wants the final typed value.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.gen(function* () {
-   *   const counter = yield* CounterService;
-   *   const value = yield* counter.call("increment", 41);
-   *
-   *   return value;
-   * });
-   * ```
    */
   readonly call: <Method extends ServiceMethodKey<Api>>(
     method: Method,
@@ -188,20 +141,6 @@ export type ServiceBindingEffectClient<
    *
    * Use this for RPC methods that return Cloudflare RPC resources or other
    * disposable objects whose lifetime should be tied to an Effect scope.
-   *
-   * @example
-   * ```ts
-   * import { Effect } from "effect";
-   *
-   * const program = Effect.scoped(
-   *   Effect.gen(function* () {
-   *     const files = yield* FileService;
-   *     const handle = yield* files.scopedCall("open", "report.csv");
-   *
-   *     return yield* handle.read();
-   *   }),
-   * );
-   * ```
    */
   readonly scopedCall: <Method extends ServiceMethodKey<Api>>(
     method: Method,
@@ -261,10 +200,10 @@ export const makeClient = <
       });
     });
 
-    const rpc = Effect.fn("ServiceBinding.rpc")(function* <Method extends ServiceMethodKey<Api>>(
+    const rpc = Effect.fnUntraced(function* <Method extends ServiceMethodKey<Api>>(
       method: Method,
       ...args: ServiceMethodArgs<Api, Method>
-    ) {
+    ): Effect.fn.Return<ServiceMethodCloudflareReturn<Api, Method>, ServiceBindingRpcError> {
       const methodName = String(method);
       // SAFETY: definition-backed clients derive Method and Args from this exact RPC definition.
       const encodedArgs =
@@ -285,11 +224,15 @@ export const makeClient = <
               ),
             );
 
-      // SAFETY: encoding preserves the selected API method's positional argument contract.
+      const nativeArgs = definition.rpcTracing
+        ? yield* RpcTracing.withRpcTraceContext(encodedArgs)
+        : encodedArgs;
+
+      // SAFETY: domain arguments retain their encoded order; an opted-in receiver strips only valid trace metadata.
       return yield* RpcInvocation.invokeRpcMethod(
         service,
         method,
-        encodedArgs as ServiceMethodArgs<Api, Method>,
+        nativeArgs as ServiceMethodArgs<Api, Method>,
         (cause) =>
           new ServiceBindingRpcError({
             binding: definition.binding,
@@ -302,7 +245,7 @@ export const makeClient = <
     const decodeSuccess = Effect.fnUntraced(function* <Method extends ServiceMethodKey<Api>>(
       methodName: string,
       value: Awaited<ServiceMethodCloudflareReturn<Api, Method>>,
-    ) {
+    ): Effect.fn.Return<ServiceMethodSuccess<Api, Method>, ServiceBindingRpcError> {
       if (definition.definition === undefined) {
         // SAFETY: without a definition the resolved native RPC value is the API method's declared success.
         return value as ServiceMethodSuccess<Api, Method>;
@@ -328,34 +271,43 @@ export const makeClient = <
       return decoded as ServiceMethodSuccess<Api, Method>;
     });
 
-    const call = Effect.fn("ServiceBinding.call")(function* <Method extends ServiceMethodKey<Api>>(
-      method: Method,
-      ...args: ServiceMethodArgs<Api, Method>
-    ) {
-      const methodName = String(method);
-      const value = yield* CloudflareRpc.resolve(yield* rpc(method, ...args)).pipe(
-        Effect.mapError(
-          (cause) =>
-            new ServiceBindingRpcError({
-              binding: definition.binding,
-              method: methodName,
-              cause,
-            }),
-        ),
-      );
-
-      return yield* decodeSuccess<Method>(methodName, value);
-    });
-
-    const scopedCall = Effect.fn("ServiceBinding.scopedCall")(function* <
-      Method extends ServiceMethodKey<Api>,
-    >(method: Method, ...args: ServiceMethodArgs<Api, Method>) {
-      const methodName = String(method);
-      const result = yield* rpc(method, ...args);
-      const value = yield* CloudflareRpc.scoped(result);
+    const call = Effect.fnUntraced(
+      function* <Method extends ServiceMethodKey<Api>>(
+        method: Method,
+        ...args: ServiceMethodArgs<Api, Method>
+      ): Effect.fn.Return<ServiceMethodSuccess<Api, Method>, ServiceBindingRpcError> {
+        const methodName = String(method);
+        const value = yield* CloudflareRpc.resolve(yield* rpc(method, ...args)).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ServiceBindingRpcError({
+                binding: definition.binding,
+                method: methodName,
+                cause,
+              }),
+          ),
+        );
+
+        return yield* decodeSuccess<Method>(methodName, value);
+      },
+      (effect, ...args) =>
+        RpcTracing.withRpcClientSpan(effect, definition.binding, String(args[0])),
+    );
 
-      return yield* decodeSuccess<Method>(methodName, value);
-    });
+    const scopedCall = Effect.fnUntraced(
+      function* <Method extends ServiceMethodKey<Api>>(
+        method: Method,
+        ...args: ServiceMethodArgs<Api, Method>
+      ): Effect.fn.Return<ServiceMethodSuccess<Api, Method>, unknown, Scope.Scope> {
+        const methodName = String(method);
+        const result = yield* rpc(method, ...args);
+        const value = yield* CloudflareRpc.scoped(result);
+
+        return yield* decodeSuccess<Method>(methodName, value);
+      },
+      (effect, ...args) =>
+        RpcTracing.withRpcClientSpan(effect, definition.binding, String(args[0])),
+    );
 
     const directMethods = makeDirectMethods<never, Api, Definition>(definition.definition, call);
 
@@ -385,35 +337,6 @@ export const layer = <
     { expected: expectedServiceBinding },
   );
 
-/**
- * Creates a typed Effect service for a Worker service binding.
- *
- * Returned value includes:
- * - a Context tag for dependency injection
- * - `fetch(...)` for raw HTTP forwarding
- * - `rpc(...)` for raw Cloudflare RPC results
- * - `call(...)` for resolved and decoded RPC results
- * - `scopedCall(...)` for scoped and decoded disposable RPC results
- * - direct RPC methods when `definition` is provided
- *
- * @example
- * ```ts
- * const Counter = WorkerDefinition.make("Counter", {
- *   increment: WorkerDefinition.method({
- *     args: [Schema.Number],
- *     success: Schema.Number,
- *   }),
- * });
- *
- * const CounterLive = Counter.layer({ binding: "COUNTER" });
- *
- * const program = Effect.gen(function* () {
- *   const counter = yield* Counter;
- *   const next = yield* counter.increment(1);
- *   return next;
- * });
- * ```
- */
 export const Service =
   <Self, Api extends object = never>() =>
   <

package/src/Vectorize.ts

@@ -22,7 +22,6 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 const expectedVectorizeBinding =
   "Vectorize index binding with describe(), query(), insert(), upsert(), deleteByIds(), and getByIds()";
 
-/** Vectorize operation represented by {@link VectorizeOperationError}. */
 export type VectorizeOperation =
   | "describe"
   | "query"
@@ -32,7 +31,6 @@ export type VectorizeOperation =
   | "deleteByIds"
   | "getByIds";
 
-/** Error raised when a Vectorize operation fails. */
 export class VectorizeOperationError extends Data.TaggedError("VectorizeOperationError")<{
   readonly binding: string;
   readonly operation: VectorizeOperation;
@@ -43,9 +41,7 @@ export class VectorizeOperationError extends Data.TaggedError("VectorizeOperatio
   }
 }
 
-/** Typed Vectorize binding definition. */
 export interface VectorizeDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
@@ -114,7 +110,6 @@ export interface VectorizeClient {
 
 declare const VectorizeServiceTypeId: unique symbol;
 
-/** Nominal service marker for Vectorize services created with {@link make}. */
 export interface VectorizeService<Id extends string> {
   readonly [VectorizeServiceTypeId]: {
     readonly id: Id;

package/src/Vitest.ts

@@ -36,24 +36,15 @@ import type { WorkflowInstanceStatusName } from "./WorkflowBinding";
 
 const currentEnv: WorkerEnv = env;
 
-/**
- * Provides the Workers test environment as both {@link WorkerEnvironment} and
- * the active Effect `ConfigProvider`.
- */
 export const layer: Layer.Layer<WorkerEnvironment> = Layer.mergeAll(
   Layer.succeed(WorkerEnvironment, currentEnv),
   ConfigProvider.layer(WorkerConfig.providerFromEnv(currentEnv)),
 );
 
-/** Constructor shape shared by Effect-backed Worker entrypoints. */
 export interface WorkerConstructor<Instance> {
   new (context: globalThis.ExecutionContext, env: WorkerEnv): Instance;
 }
 
-/**
- * Creates an `ExecutionContext` and drains all `waitUntil` work before the
- * returned effect completes, including when `use` fails or is interrupted.
- */
 export const withExecutionContext = Effect.fn("effect-cf/vitest/withExecutionContext")(function* <
   A,
   E,
@@ -86,10 +77,8 @@ export const fetch = Effect.fn("effect-cf/vitest/fetch")(function* <Instance ext
   );
 });
 
-/** Modules-format scheduled handler accepted by {@link scheduled}. */
 export type ScheduledHandler = NonNullable<globalThis.ExportedHandler<WorkerEnv>["scheduled"]>;
 
-/** Options used to construct a scheduled event controller. */
 export interface ScheduledOptions {
   readonly scheduledTime?: number | Date;
   readonly cron?: string;
@@ -134,7 +123,6 @@ type PagesEventContextInitData<Context> =
       : { readonly data: Data }
     : never;
 
-/** Initialization accepted by the Workers Vitest plugin for a Pages Function. */
 export type PagesEventContextInit<Function extends AnyPagesFunction> = PagesEventContextInitBase &
   PagesEventContextInitParams<Parameters<Function>[0]> &
   PagesEventContextInitData<Parameters<Function>[0]>;
@@ -162,7 +150,6 @@ interface QueueWorker {
   queue(batch: globalThis.MessageBatch): Promise<void>;
 }
 
-/** Input message accepted by the Workers Vitest plugin's `createMessageBatch` helper. */
 export type QueueMessage<Body> = {
   readonly id: string;
   readonly timestamp: Date;
@@ -172,7 +159,6 @@ export type QueueMessage<Body> = {
 /** Acknowledgement and retry result returned by the Workers Vitest plugin. */
 export type QueueResult = Awaited<ReturnType<typeof getQueueResult>>;
 
-/** Result of invoking a queue consumer through {@link queue}. */
 export interface QueueRunResult<Body> {
   readonly batch: globalThis.MessageBatch<Body>;
   readonly result: QueueResult;
@@ -234,19 +220,16 @@ export const runInDurableObject = Effect.fn("effect-cf/vitest/runInDurableObject
   return yield* exit;
 });
 
-/** Immediately runs and removes a scheduled Durable Object alarm. */
 export const runDurableObjectAlarm = Effect.fn("effect-cf/vitest/runDurableObjectAlarm")(function* (
   stub: globalThis.DurableObjectStub<RpcDurableObject>,
 ) {
   return yield* Effect.promise(() => runDurableObjectAlarmPromise(stub));
 });
 
-/** Options controlling how Durable Object eviction handles WebSockets. */
 export interface DurableObjectEvictionOptions {
   readonly webSockets?: "close" | "hibernate";
 }
 
-/** Gracefully evicts one running Durable Object while preserving durable storage. */
 export const evictDurableObject = Effect.fn("effect-cf/vitest/evictDurableObject")(function* (
   stub: globalThis.DurableObjectStub<RpcDurableObject>,
   options?: DurableObjectEvictionOptions,
@@ -254,39 +237,33 @@ export const evictDurableObject = Effect.fn("effect-cf/vitest/evictDurableObject
   yield* Effect.promise(() => evictDurableObjectPromise(stub, options));
 });
 
-/** Lists all IDs created in a Durable Object namespace. */
 export const listDurableObjectIds = Effect.fn("effect-cf/vitest/listDurableObjectIds")(function* <
   Object extends RpcDurableObject | undefined,
 >(namespace: globalThis.DurableObjectNamespace<Object>) {
   return yield* Effect.promise(() => listDurableObjectIdsPromise(namespace));
 });
 
-/** Deletes data from all bindings attached to the current test Worker. */
 export const reset = Effect.fn("effect-cf/vitest/reset")(function* () {
   yield* Effect.promise(resetPromise);
 });
 
-/** Aborts all Durable Object instances without deleting their persisted data. */
 export const abortAllDurableObjects = Effect.fn("effect-cf/vitest/abortAllDurableObjects")(
   function* () {
     yield* Effect.promise(abortAllDurableObjectsPromise);
   },
 );
 
-/** Gracefully evicts all running Durable Objects while preserving durable storage. */
 export const evictAllDurableObjects = Effect.fn("effect-cf/vitest/evictAllDurableObjects")(
   function* (options?: DurableObjectEvictionOptions) {
     yield* Effect.promise(() => evictAllDurableObjectsPromise(options));
   },
 );
 
-/** A D1 migration accepted by the Workers Vitest plugin. */
 export interface D1Migration {
   readonly name: string;
   readonly queries: ReadonlyArray<string>;
 }
 
-/** Applies all D1 migrations that have not already been recorded. */
 export const applyD1Migrations = Effect.fn("effect-cf/vitest/applyD1Migrations")(function* (
   database: globalThis.D1Database,
   migrations: ReadonlyArray<D1Migration>,
@@ -347,19 +324,16 @@ type NativeWorkflowInstanceModifier = Parameters<
   Parameters<NativeWorkflowInstanceIntrospector["modify"]>[0]
 >[0];
 
-/** Identifies one occurrence of a Workflow step or sleep. */
 export interface WorkflowStepTarget {
   readonly name: string;
   readonly index?: number;
 }
 
-/** Event delivered to a mocked Workflow `waitForEvent` operation. */
 export interface WorkflowMockEvent {
   readonly type: string;
   readonly payload: unknown;
 }
 
-/** Effect-native Workflow behavior modifier. */
 export interface WorkflowInstanceModifier {
   readonly disableSleeps: (steps?: ReadonlyArray<WorkflowStepTarget>) => Effect.Effect<void>;
   readonly disableRetryDelays: (steps?: ReadonlyArray<WorkflowStepTarget>) => Effect.Effect<void>;
@@ -379,7 +353,6 @@ export interface WorkflowInstanceModifier {
 
 type WorkflowMockResult = Schema.Schema.Type<typeof Schema.Unknown>;
 
-/** Effect-native introspector for one Workflow instance. */
 export interface WorkflowInstanceIntrospector {
   readonly raw: NativeWorkflowInstanceIntrospector;
   readonly modify: <A, E, R>(
@@ -391,7 +364,6 @@ export interface WorkflowInstanceIntrospector {
   readonly getError: Effect.Effect<{ readonly name: string; readonly message: string }>;
 }
 
-/** Effect-native introspector for subsequently created Workflow instances. */
 export interface WorkflowIntrospector {
   readonly raw: NativeWorkflowIntrospector;
   readonly modifyAll: <A, E, R>(

package/src/WebTransport.ts

@@ -42,11 +42,8 @@ import { Data, Effect, Option, Predicate, Result, Schema as S } from "effect";
  * `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),
 }) {}
 
@@ -63,18 +60,9 @@ 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
@@ -91,7 +79,6 @@ export interface Capabilities {
   readonly outboundSessions: boolean;
 }
 
-/** Feature-detects the WebTransport capabilities of the current runtime. */
 export const capabilities: Effect.Effect<Capabilities> = Effect.sync(() => {
   const runtime = globalThis;
 
@@ -103,10 +90,8 @@ export const capabilities: Effect.Effect<Capabilities> = Effect.sync(() => {
   };
 });
 
-/** 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;
 }> {