effect-cf 0.32.1 → 0.34.0

package/src/Worker.ts

@@ -1,26 +1,29 @@
 import { WorkerEntrypoint as CloudflareWorkerEntrypoint } from "cloudflare:workers";
-import { type Cause, Context, Effect, Layer, type ManagedRuntime, type Scope } from "effect";
+import {
+  type Cause,
+  Context,
+  Effect,
+  Layer,
+  type ManagedRuntime,
+  type Scope,
+  Tracer,
+} from "effect";
 import { HttpEffect, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
 import { WorkerEnvironment, type WorkerEnv } from "./Environment";
 import { fromMessage, fromMessageBatch, type QueueHandler } from "./Queue";
 import type * as RpcDefinition from "./RpcDefinition";
+import type { ReceiverOptions, RpcInvocationInfo } from "./RpcTracing";
 import * as Entrypoint from "./internal/Entrypoint";
 import * as Runtime from "./internal/Runtime";
 import * as Telemetry from "./internal/Telemetry";
 import { fromExecutionContext } from "./internal/WorkerContext";
 
-/**
- * Access to Cloudflare's native `ExecutionContext`.
- */
 export class ExecutionContext extends Context.Service<
   ExecutionContext,
   globalThis.ExecutionContext
 >()("effect-cf/ExecutionContext") {}
 
-/**
- * Options for {@link WorkerContextService.waitUntil}.
- */
 export interface WorkerContextWaitUntilOptions<E, R> {
   /**
    * Failure mode for the background effect: `"observe"` (default) logs or
@@ -28,13 +31,9 @@ export interface WorkerContextWaitUntilOptions<E, R> {
    * native `waitUntil` promise.
    */
   readonly mode?: "observe" | "propagate";
-  /** Custom failure handler for the background effect. */
   readonly onFailure?: (cause: Cause.Cause<E>) => Effect.Effect<void, never, R>;
 }
 
-/**
- * Effect wrapper around `ExecutionContext` background APIs.
- */
 export interface WorkerContextService {
   readonly raw: globalThis.ExecutionContext;
   waitUntil<A, E, R, R2 = never>(
@@ -46,36 +45,17 @@ export interface WorkerContextService {
     options?: Omit<WorkerContextWaitUntilOptions<E, R2>, "mode">,
   ): Effect.Effect<void, never, R | R2>;
   readonly passThroughOnException: Effect.Effect<void>;
-  /** Abort the current stateless Worker invocation (`ExecutionContext.abort`). */
   abort(reason?: string): Effect.Effect<void>;
 }
 
-/**
- * Service used inside handlers to schedule background work via `waitUntil`.
- *
- * @example
- * ```ts
- * const handler = Effect.gen(function* () {
- *   const ctx = yield* Worker.WorkerContext;
- *   yield* ctx.waitUntil(Effect.log("flush analytics"));
- *   return new Response("ok");
- * });
- * ```
- */
 export class WorkerContext extends Context.Service<WorkerContext, WorkerContextService>()(
   "effect-cf/WorkerContext",
 ) {}
 
-/**
- * Access to the incoming `Request` currently handled by a worker or Durable Object fetch.
- */
 export class NativeRequest extends Context.Service<NativeRequest, Request>()(
   "effect-cf/NativeRequest",
 ) {}
 
-/**
- * Returns `true` when the request is a websocket upgrade request.
- */
 export const isWebSocketUpgrade = (request: Request): boolean =>
   request.headers.get("Upgrade")?.toLowerCase() === "websocket";
 
@@ -120,14 +100,16 @@ type WorkerFetchContext<ROut> =
 type WorkerRpcContext<ROut> = WorkerBaseContext<ROut> | Scope.Scope;
 
 type RuntimeContext<ROut> = WorkerBaseContext<ROut>;
-const RunSymbol = Symbol.for("effect-cf/Worker/run");
+/** Override to instrument the whole event, then call super[RunSymbol]. */
+export const RunSymbol = Symbol.for("effect-cf/Worker/run");
 const FetchSymbol = Symbol.for("effect-cf/Worker/fetch");
 
-/**
- * Successful result of a worker fetch handler: either a native `Response`
- * (returned to Cloudflare untouched) or an Effect `HttpServerResponse`
- * (rendered through the Effect HTTP pipeline).
- */
+/** Metadata available before an event effect or its event layer starts. */
+export interface RunOptions {
+  readonly event?: "fetch" | "rpc" | "queue";
+  readonly rpc?: RpcInvocationInfo;
+}
+
 export type WorkerFetchSuccess = Response | HttpServerResponse.HttpServerResponse;
 
 /**
@@ -173,9 +155,6 @@ export type RpcHandlers<ROut, Api> = {
     : never;
 };
 
-/**
- * Options for creating a worker class with Effect handlers.
- */
 export interface WorkerOptions<
   RRuntime,
   REvent = never,
@@ -191,13 +170,11 @@ export interface WorkerOptions<
    * flush capped at two seconds; queue handlers do not flush automatically.
    */
   readonly eventLayer?: Layer.Layer<REvent, EventLayerError, WorkerBaseContext<RRuntime>>;
-  /** Main request handler. */
   readonly fetch?: Effect.Effect<
     WorkerFetchSuccess,
     unknown,
     WorkerFetchContext<RRuntime | REvent>
   >;
-  /** Queue consumer handler invoked per message batch. */
   readonly queue?: QueueHandler<RRuntime | REvent>;
   /**
    * Optional RPC methods exposed as class instance methods.
@@ -207,6 +184,8 @@ export interface WorkerOptions<
    * flush silently settles within two seconds even if the exporter does not.
    */
   readonly rpc?: Rpc;
+  /** Accept live native trace metadata. The client must also enable rpcTracing. */
+  readonly rpcTracing?: ReceiverOptions;
 }
 
 type WorkerOptionsWithEventLayer<
@@ -241,6 +220,10 @@ export type WorkerClass<Rpc extends WorkerRpc<ROut>, ROut> = new (
 ) => CloudflareWorkerEntrypoint<WorkerEnv> & {
   fetch(request: Request): Promise<Response>;
   queue(batch: globalThis.MessageBatch): Promise<void>;
+  [RunSymbol]<A, E>(
+    effect: Effect.Effect<A, E, WorkerRpcContext<ROut>>,
+    options?: RunOptions,
+  ): Promise<A>;
   [FetchSymbol](request: Request, requestContext: globalThis.ExecutionContext): Promise<Response>;
 } & WorkerRpcContract<Rpc, ROut>;
 
@@ -313,19 +296,8 @@ const scheduleTelemetryFlush: Effect.Effect<void, never, WorkerContext> =
   );
 
 /**
- * Creates a Cloudflare worker class backed by a single managed Effect runtime.
- *
- * The runtime layer is built when Cloudflare constructs the class and reused
- * for every event the instance handles. Layer finalizers do not run when the
- * isolate is evicted; Cloudflare provides no shutdown hook. Use `eventLayer`
- * for resources that must be finalized per event.
- *
- * @example
- * ```ts
- * export default Worker.make(Layer.empty, {
- *   fetch: Effect.succeed(new Response("ok")),
- * });
- * ```
+ * The layer is built once per Worker instance and reused for its events.
+ * Eviction skips finalizers, so use `eventLayer` for per-event resources.
  */
 export function make<ROut, LayerError>(
   layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
@@ -387,8 +359,11 @@ export function make<
 
     [RunSymbol]<A, E>(
       effect: Effect.Effect<A, E, RuntimeContext<ROut> | REvent | Scope.Scope>,
+      runOptions: RunOptions = {},
     ): Promise<A> {
       const eventLayer = options.eventLayer;
+      const parent = runOptions.rpc?.parent;
+      const parentSpan = parent === undefined ? undefined : Tracer.externalSpan(parent);
 
       if (eventLayer === undefined) {
         // SAFETY: the public make overloads permit an absent event layer only when REvent is never.
@@ -396,6 +371,8 @@ export function make<
           this.runtime,
           // @effect-diagnostics-next-line unsafeEffectTypeAssertion:off
           effect as Effect.Effect<A, E, RuntimeContext<ROut> | Scope.Scope>,
+          undefined,
+          parentSpan,
         );
       }
 
@@ -406,7 +383,7 @@ export function make<
         REvent,
         EventLayerError,
         LayerError
-      >(this.runtime, effect, eventLayer);
+      >(this.runtime, effect, eventLayer, parentSpan);
     }
 
     fetch(request: Request): Promise<Response> {
@@ -437,6 +414,7 @@ export function make<
           Effect.tap(() => scheduleTelemetryFlush),
           Effect.provide(requestServices),
         ) as Effect.Effect<Response, unknown, RuntimeContext<ROut> | REvent | Scope.Scope>,
+        { event: "fetch" },
       );
     }
 
@@ -449,7 +427,7 @@ export function make<
 
       const messages = batch.messages.map((message) => fromMessage(message, message.body));
 
-      return this[RunSymbol](queueHandler(fromMessageBatch(batch, messages)));
+      return this[RunSymbol](queueHandler(fromMessageBatch(batch, messages)), { event: "queue" });
     }
   }
 
@@ -458,8 +436,9 @@ export function make<
     EffectWorker.prototype,
     options.rpc,
     reservedMethodNames,
-    (self, effect) => self[RunSymbol](effect),
+    (self, effect, rpc) => self[RunSymbol](effect, { event: "rpc", rpc }),
     () => scheduleTelemetryFlush,
+    options.rpcTracing,
   );
 
   return Entrypoint.assumeEntrypointClass<WorkerClass<Rpc, ROut | REvent>>(EffectWorker);

package/src/WorkerDefinition.ts

@@ -6,6 +6,7 @@ import * as WorkerEntrypoint from "./Worker";
 import type { WorkerRpcHandler } from "./Worker";
 import type * as Rpc from "./Rpc";
 import * as RpcDefinition from "./RpcDefinition";
+import { recordDecodedArgs } from "./internal/RpcInvocation";
 import * as ServiceBinding from "./ServiceBinding";
 
 /**
@@ -37,7 +38,6 @@ export namespace Method {
       ? [S.Schema.Type<Head>, ...ArgsFromSchemas<Tail>]
       : Array<S.Schema.Type<Args[number]>>;
 
-  /** Method schemas cross the wire through their canonical JSON codec. */
   type EncodedArgsFromSchemas<Args extends ReadonlyArray<ServiceFreeSchema>> = {
     [Index in keyof Args]: S.Json;
   };
@@ -153,6 +153,7 @@ export type Options<
 
 export type LayerOptions = {
   readonly binding: string;
+  readonly rpcTracing?: boolean;
 };
 
 export type TagClass<
@@ -236,19 +237,6 @@ export const method: {
   }): Method<Args, Success>;
 } = RpcDefinition.method;
 
-/**
- * Creates a typed worker RPC definition plus helpers for implementation and bindings.
- *
- * @example
- * ```ts
- * const CounterWorker = WorkerDefinition.make("CounterWorker", {
- *   increment: WorkerDefinition.method({
- *     args: [Schema.Number],
- *     success: Schema.Number,
- *   }),
- * });
- * ```
- */
 const makeDefinition = <Id extends string, const MethodDefinitions extends Methods>(
   id: Id,
   methods: MethodDefinitions & NoReservedMethods<MethodDefinitions>,
@@ -414,6 +402,9 @@ const wrapHandlers = <ROut, const Self extends Definition.Any>(
     wrapped[key] = (...args: Array<unknown>) =>
       Effect.gen(function* () {
         const decodedArgs = yield* RpcDefinition.decodeArgs(definition, key, args);
+
+        yield* recordDecodedArgs(decodedArgs);
+
         const value = yield* handler(...decodedArgs);
 
         return yield* RpcDefinition.encodeSuccess(definition, key, value);

package/src/WorkersAi.ts

@@ -18,7 +18,6 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedWorkersAiBinding = "Workers AI binding with run(), gateway(), and models()";
 
-/** Error raised when a Workers AI operation fails. */
 export class WorkersAiOperationError extends Data.TaggedError("WorkersAiOperationError")<{
   readonly binding: string;
   readonly operation: string;
@@ -29,9 +28,7 @@ export class WorkersAiOperationError extends Data.TaggedError("WorkersAiOperatio
   }
 }
 
-/** Typed Workers AI binding definition. */
 export interface WorkersAiDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
@@ -117,7 +114,6 @@ export interface WorkersAiClient<ModelList extends AiModelListType = AiModels> {
 
 declare const WorkersAiServiceTypeId: unique symbol;
 
-/** Nominal service marker for Workers AI services created with {@link make}. */
 export interface WorkersAiService<Id extends string> {
   readonly [WorkersAiServiceTypeId]: {
     readonly id: Id;

package/src/Workflow.ts

@@ -1,7 +1,3 @@
-/**
- * Effect wrapper for Cloudflare Workflows entrypoints and bindings; distinct
- * from Effect's runtime-agnostic `effect/unstable/workflow` cluster module.
- */
 import {
   WorkflowEntrypoint as CloudflareWorkflowEntrypoint,
   type WorkflowEvent as CloudflareWorkflowEvent,
@@ -46,7 +42,6 @@ export class WorkflowEvent extends Context.Service<WorkflowEvent, WorkflowEventS
 
 type RunWorkflowStepEffect = <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>;
 
-/** Failure raised when a Cloudflare Workflow step operation rejects. */
 export class WorkflowStepError extends Data.TaggedError("WorkflowStepError")<{
   readonly step?: string;
   readonly operation: string;

package/src/WorkflowBinding.ts

@@ -67,11 +67,8 @@ export interface WorkflowBindingDefinition<
   Payload extends RpcDefinition.ServiceFreeSchema,
   Result extends RpcDefinition.ServiceFreeSchema,
 > {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
-  /** Codec used to encode payloads passed to `Workflow.create`. */
   readonly payload: Payload;
-  /** Codec used to decode completed workflow status output. */
   readonly result: Result;
 }
 

package/src/index.ts

@@ -27,6 +27,7 @@ export * as QueueDefinition from "./QueueDefinition";
 export * as R2 from "./R2";
 export * as Rpc from "./Rpc";
 export * as RpcDefinition from "./RpcDefinition";
+export * as RpcTracing from "./RpcTracing";
 export * as ServiceBinding from "./ServiceBinding";
 export * as Vectorize from "./Vectorize";
 export * as WebTransport from "./WebTransport";

package/src/internal/Entrypoint.ts

@@ -1,26 +1,44 @@
 import { Effect, Layer, Schema } from "effect";
 
 import * as RpcDefinition from "../RpcDefinition";
+import { RpcTraceContext, type ReceiverOptions, type RpcInvocationInfo } from "../RpcTracing";
+import { CurrentInvocation } from "./RpcInvocation";
 
 type AnyArgs = Array<any>;
 type EntrypointRpcMethod = (...args: AnyArgs) => Effect.Effect<any, any, any>;
 
 export type EntrypointRpc = Record<string, EntrypointRpcMethod>;
 
+const isRpcTraceContext = Schema.is(RpcTraceContext);
+
 const invokeEntrypointRpcMethod = <Self>(
   self: Self,
   method: EntrypointRpcMethod,
   args: AnyArgs,
-  run: (self: Self, effect: Effect.Effect<any, any, any>) => Promise<any>,
+  run: (self: Self, effect: Effect.Effect<any, any, any>, rpc: RpcInvocationInfo) => Promise<any>,
   onExit: ((self: Self) => Effect.Effect<void, never, any>) | undefined,
+  service: string,
+  key: string,
+  rpcTracing: ReceiverOptions | undefined,
 ): Promise<any> => {
-  const handler = Effect.suspend(() => method(...args)).pipe(
+  const last = args.at(-1);
+  const parent = rpcTracing !== undefined && isRpcTraceContext(last) ? last : undefined;
+  const handlerArgs = parent === undefined ? args : args.slice(0, -1);
+  const invocation: CurrentInvocation["Service"] = {
+    service: rpcTracing?.service ?? service,
+    method: key,
+    args: handlerArgs,
+    parent,
+  };
+  const handler = Effect.suspend(() => method(...handlerArgs)).pipe(
+    Effect.provideService(CurrentInvocation, invocation),
     Effect.mapError(RpcDefinition.encodeWireError),
   );
 
   return run(
     self,
     onExit === undefined ? handler : handler.pipe(Effect.onExit(() => onExit(self))),
+    invocation,
   );
 };
 
@@ -36,8 +54,9 @@ export const defineEntrypointRpcMethods = <Self, Prototype extends object = obje
   prototype: Prototype,
   rpc: EntrypointRpc | undefined,
   reservedMethodNames: ReadonlySet<string>,
-  run: (self: Self, effect: Effect.Effect<any, any, any>) => Promise<any>,
+  run: (self: Self, effect: Effect.Effect<any, any, any>, rpc: RpcInvocationInfo) => Promise<any>,
   onExit?: (self: Self) => Effect.Effect<void, never, any>,
+  rpcTracing?: ReceiverOptions,
 ): void => {
   const methods = rpc ?? {};
 
@@ -47,7 +66,7 @@ export const defineEntrypointRpcMethods = <Self, Prototype extends object = obje
     Object.defineProperty(prototype, key, {
       enumerable: true,
       value(this: Self, ...args: AnyArgs) {
-        return invokeEntrypointRpcMethod(this, method, args, run, onExit);
+        return invokeEntrypointRpcMethod(this, method, args, run, onExit, target, key, rpcTracing);
       },
     });
   }

package/src/internal/ErrorMessage.ts

@@ -18,7 +18,6 @@ export const causeMessage = (cause: unknown): string => {
   }
 };
 
-/** Renders a violation list as a single `path: message; ...` line. */
 export const violationsMessage = (
   violations: ReadonlyArray<{ readonly path: string; readonly message: string }>,
 ): string => violations.map((violation) => `${violation.path}: ${violation.message}`).join("; ");

package/src/internal/RpcInvocation.ts

@@ -1,9 +1,26 @@
-import { Effect, Predicate, Schema } from "effect";
+import { Context, Effect, Option, Predicate, Schema } from "effect";
 
 import type * as CloudflareRpc from "../Rpc";
+import type { RpcInvocationInfo } from "../RpcTracing";
 
 type AnyArgs = Array<any>;
 
+interface Invocation extends RpcInvocationInfo {
+  decodedArgs?: ReadonlyArray<unknown>;
+}
+
+/** Scoped to the incoming event effect, never the instance runtime or storage. */
+export class CurrentInvocation extends Context.Service<CurrentInvocation, Invocation>()(
+  "effect-cf/internal/RpcInvocation",
+) {}
+
+export const recordDecodedArgs = (args: ReadonlyArray<unknown>): Effect.Effect<void> =>
+  Effect.map(Effect.serviceOption(CurrentInvocation), (invocation) => {
+    if (Option.isSome(invocation)) {
+      invocation.value.decodedArgs = args;
+    }
+  });
+
 export type AsyncMethodKey<Api> = {
   [Key in keyof Api]-?: Key extends string
     ? Api[Key] extends (...args: AnyArgs) => Promise<any>

package/src/internal/Runtime.ts

@@ -1,4 +1,4 @@
-import { ConfigProvider, Effect, Layer, ManagedRuntime, type Scope } from "effect";
+import { ConfigProvider, Effect, Layer, ManagedRuntime, type Scope, type Tracer } from "effect";
 
 import { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "../Environment";
 import { provideEntrypointServices } from "./Entrypoint";
@@ -26,17 +26,18 @@ export const makeEntrypointRuntime = <ROut, LayerError, Services>(
   return ManagedRuntime.make(provideEntrypointServices(layer, entrypointServices));
 };
 
-/** Runs an event effect whose requirements are already available in the runtime. */
 export function runEventPromise<A, E, R, LayerError>(
   runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
   effect: Effect.Effect<A, E, NoInfer<R> | Scope.Scope>,
   eventLayer?: undefined,
+  parent?: Tracer.AnySpan,
 ): Promise<A>;
 /** Builds and provides an event layer inside the event effect's scope. */
 export function runEventPromise<A, E, R, REvent, EventLayerError, LayerError>(
   runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
   effect: Effect.Effect<A, E, NoInfer<R> | REvent | Scope.Scope>,
   eventLayer: Layer.Layer<REvent, EventLayerError, NoInfer<R>>,
+  parent?: Tracer.AnySpan,
 ): Promise<A>;
 export function runEventPromise<A, E, R, REvent, EventLayerError, LayerError>(
   ...args:
@@ -44,20 +45,24 @@ export function runEventPromise<A, E, R, REvent, EventLayerError, LayerError>(
         runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
         effect: Effect.Effect<A, E, R | Scope.Scope>,
         eventLayer?: undefined,
+        parent?: Tracer.AnySpan,
       ]
     | readonly [
         runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
         effect: Effect.Effect<A, E, R | REvent | Scope.Scope>,
         eventLayer: Layer.Layer<REvent, EventLayerError, R>,
+        parent?: Tracer.AnySpan,
       ]
 ): Promise<A> {
-  const [runtime, effect, eventLayer] = args;
+  const [runtime, effect, eventLayer, parent] = args;
 
   if (eventLayer === undefined) {
-    return runtime.runPromise(Effect.scoped(effect));
+    const event = Effect.scoped(effect);
+
+    return runtime.runPromise(parent === undefined ? event : Effect.withParentSpan(event, parent));
   }
 
-  return runtime.runPromise(
-    Effect.scoped(effect.pipe(Effect.provide(eventLayer, { local: true }))),
-  );
+  const event = Effect.scoped(effect.pipe(Effect.provide(eventLayer, { local: true })));
+
+  return runtime.runPromise(parent === undefined ? event : Effect.withParentSpan(event, parent));
 }

package/src/internal/WorkerContext.ts

@@ -27,14 +27,6 @@ const failureHandler = <E, R>(
     ),
   );
 
-/**
- * Builds a `waitUntil` scheduler for any Cloudflare lifecycle that accepts
- * background promises (`ExecutionContext`, `DurableObjectState`).
- *
- * Background effects capture the calling fiber's context via `Effect.context`
- * before being registered, so the default module-level `Effect.runPromiseExit`
- * runner is sufficient; entrypoints may still pass a runtime-bound runner.
- */
 export const makeWaitUntilScheduler = (
   label: string,
   register: (promise: Promise<unknown>) => void,
@@ -77,9 +69,6 @@ export const makeWaitUntilScheduler = (
     );
 };
 
-/**
- * Builds the `WorkerContext` service from a native `ExecutionContext`.
- */
 export const fromExecutionContext = (
   ctx: globalThis.ExecutionContext,
   runPromiseExit: RunWaitUntilEffect = (effect) => Effect.runPromiseExit(effect),