effect-cf 0.33.0 → 0.35.0

package/src/Worker.ts

@@ -1,26 +1,35 @@
 import { WorkerEntrypoint as CloudflareWorkerEntrypoint } from "cloudflare:workers";
-import { type Cause, Context, Effect, Layer, type ManagedRuntime, type Scope } from "effect";
-import { HttpEffect, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import {
+  type Cause,
+  Context,
+  Effect,
+  Layer,
+  type ManagedRuntime,
+  References,
+  type Scope,
+  Tracer,
+} from "effect";
+import {
+  HttpEffect,
+  HttpMiddleware,
+  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 * 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 +37,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 +51,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";
 
@@ -95,20 +81,13 @@ export type ReservedMethodName =
   | "webSocketError";
 
 const reservedMethodNames = new Set<string>([
-  "constructor",
-  "dup",
-  "fetch",
-  "connect",
+  ...RpcDefinition.reservedMethodNames,
   "queue",
   "scheduled",
   "tail",
   "tailStream",
   "test",
   "trace",
-  "alarm",
-  "webSocketMessage",
-  "webSocketClose",
-  "webSocketError",
 ]);
 
 type WorkerBaseContext<ROut> = ExecutionContext | WorkerContext | WorkerEnvironment | ROut;
@@ -120,14 +99,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 +154,6 @@ export type RpcHandlers<ROut, Api> = {
     : never;
 };
 
-/**
- * Options for creating a worker class with Effect handlers.
- */
 export interface WorkerOptions<
   RRuntime,
   REvent = never,
@@ -185,19 +163,19 @@ export interface WorkerOptions<
   /**
    * Layer provided around each Cloudflare event handled by this Worker.
    *
-   * The layer is built inside the event's Effect scope and finalized when the
-   * event effect completes. Use this for event-scoped resources such as OTLP
-   * trace/log exporters. Worker fetch and RPC handlers schedule a best-effort
-   * flush capped at two seconds; queue handlers do not flush automatically.
+   * The layer is built inside the event's Effect scope. For fetch handlers that
+   * return an Effect `HttpServerResponse` stream, its scope remains open until
+   * the response body finishes or is canceled. Native `Response` values pass
+   * through unchanged, so their body streams do not carry this scoped-lifetime
+   * guarantee. Fetch, queue, and RPC handlers schedule a best-effort telemetry
+   * flush capped at two seconds.
    */
   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 +185,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 +221,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>;
 
@@ -255,9 +239,14 @@ export interface FetchHandler<Env extends WorkerEnv = WorkerEnv> {
   ) => Promise<Response>;
 }
 
-const renderFetchSuccess = <E, R>(
+const renderFetchSuccess = <E, R, REvent, EventLayerError, EventLayerRequirements>(
   effect: Effect.Effect<WorkerFetchSuccess, E, R>,
-): Effect.Effect<Response, E, Exclude<R, Scope.Scope> | HttpServerRequest.HttpServerRequest> =>
+  eventLayer: Layer.Layer<REvent, EventLayerError, EventLayerRequirements> | undefined,
+): Effect.Effect<
+  Response,
+  E | EventLayerError,
+  Exclude<R | EventLayerRequirements, Scope.Scope> | HttpServerRequest.HttpServerRequest
+> =>
   Effect.suspend(() => {
     // Native `Response` values bypass all HTTP response processing: WebSocket
     // upgrade responses and app-level `HttpEffect.toHandled` results pass
@@ -266,26 +255,64 @@ const renderFetchSuccess = <E, R>(
     let nativeResponse: Response | undefined;
     let webResponse: Response | undefined;
 
-    const handled = HttpEffect.toHandled(
-      Effect.flatMap(effect, (response) => {
-        if (response instanceof Response) {
-          nativeResponse = response;
+    const httpApp = Effect.flatMap(effect, (response) => {
+      if (response instanceof Response) {
+        nativeResponse = response;
 
-          return Effect.succeed(HttpServerResponse.empty());
-        }
+        return Effect.succeed(HttpServerResponse.empty());
+      }
 
-        return Effect.succeed(response);
+      return Effect.succeed(response);
+    });
+    const handleResponse = (
+      request: HttpServerRequest.HttpServerRequest,
+      response: HttpServerResponse.HttpServerResponse,
+    ) =>
+      nativeResponse !== undefined
+        ? Effect.void
+        : Effect.map(Effect.context<never>(), (context) => {
+            webResponse = HttpServerResponse.toWeb(HttpEffect.scopeTransferToStream(response), {
+              withoutBody: request.method === "HEAD",
+              context,
+            });
+          });
+    const telemetryMiddleware = HttpMiddleware.make((self) =>
+      Effect.gen(function* () {
+        yield* Effect.addFinalizer(() => scheduleTelemetryFlush);
+
+        return yield* self;
       }),
-      (request, response) =>
-        nativeResponse !== undefined
-          ? Effect.void
-          : Effect.map(Effect.context<never>(), (context) => {
-              webResponse = HttpServerResponse.toWeb(HttpEffect.scopeTransferToStream(response), {
-                withoutBody: request.method === "HEAD",
-                context,
-              });
-            }),
     );
+    const handled =
+      eventLayer === undefined
+        ? HttpEffect.toHandled(httpApp, handleResponse, telemetryMiddleware)
+        : Effect.flatMap(References.TracerEnabled, (tracerEnabled) =>
+            HttpEffect.toHandled(
+              httpApp,
+              handleResponse,
+              HttpMiddleware.make((self) =>
+                Effect.provideService(
+                  Effect.gen(function* () {
+                    const context = yield* Layer.build(Layer.fresh(eventLayer));
+
+                    yield* Effect.addFinalizer(() =>
+                      Effect.provideContext(scheduleTelemetryFlush, context),
+                    );
+
+                    return yield* HttpMiddleware.tracer(self).pipe(
+                      // The tracer schedules span completion. Let it publish on
+                      // every exit with event references still installed, before
+                      // the exporter scope finalizes.
+                      Effect.onExit(() => Effect.yieldNow),
+                      Effect.provideContext(context),
+                    );
+                  }),
+                  References.TracerEnabled,
+                  tracerEnabled,
+                ),
+              ),
+            ).pipe(Effect.withTracerEnabled(false)),
+          );
 
     // `toHandled` re-fails with the original cause after rendering the error
     // response, so both branches return the response captured above.
@@ -299,13 +326,13 @@ const isWorkerOptions = <ROut, REvent, EventLayerError, Rpc extends WorkerRpc<RO
 ): options is WorkerOptions<ROut, REvent, EventLayerError, Rpc> => !Effect.isEffect(options);
 
 /**
- * Drains buffered OTLP telemetry once the fetch handler has produced its
- * response.
+ * Drains buffered OTLP telemetry when the fetch Effect scope closes. Effect
+ * response streams transfer that scope to the body and schedule the flush when
+ * the body finishes or is canceled.
  *
- * The flush is handed to `ctx.waitUntil` so it never delays the response
- * (including streaming bodies still being consumed). It is a no-op when the
- * context does not contain an `OtlpExporter.Flusher`. The handed-off effect is
- * best-effort and silently settles within two seconds.
+ * The flush is handed to `ctx.waitUntil` instead of being awaited by the
+ * handler. It is a no-op when the context does not contain an
+ * `OtlpExporter.Flusher`, and silently settles within two seconds.
  */
 const scheduleTelemetryFlush: Effect.Effect<void, never, WorkerContext> =
   Telemetry.scheduleTelemetryFlush((flush) =>
@@ -313,19 +340,10 @@ 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")),
- * });
- * ```
+ * Cloudflare creates a new `WorkerEntrypoint` instance for each native
+ * invocation, so this base layer is not shared across invocations. Its managed
+ * runtime has no deterministic disposal point in this adapter; use
+ * `eventLayer` for resources whose finalizers must run with an event.
  */
 export function make<ROut, LayerError>(
   layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
@@ -387,15 +405,22 @@ export function make<
 
     [RunSymbol]<A, E>(
       effect: Effect.Effect<A, E, RuntimeContext<ROut> | REvent | Scope.Scope>,
+      runOptions: RunOptions = {},
     ): Promise<A> {
-      const eventLayer = options.eventLayer;
+      // Fetch builds its event layer in the HTTP scope transferred to the body.
+      const eventLayer = runOptions.event === "fetch" ? undefined : 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.
+        // SAFETY: fetch provides REvent inside its HTTP middleware; otherwise the
+        // public make overloads permit an absent event layer only when REvent is never.
         return Runtime.runEventPromise(
           this.runtime,
           // @effect-diagnostics-next-line unsafeEffectTypeAssertion:off
           effect as Effect.Effect<A, E, RuntimeContext<ROut> | Scope.Scope>,
+          undefined,
+          parentSpan,
         );
       }
 
@@ -406,7 +431,7 @@ export function make<
         REvent,
         EventLayerError,
         LayerError
-      >(this.runtime, effect, eventLayer);
+      >(this.runtime, effect, eventLayer, parentSpan);
     }
 
     fetch(request: Request): Promise<Response> {
@@ -431,12 +456,12 @@ export function make<
         Layer.succeed(WorkerContext, fromExecutionContext(ctx)),
       );
 
-      // SAFETY: requestServices provides the HTTP/request contexts introduced by renderFetchSuccess.
+      // The request services wrap eventLayer construction so cached object handlers
+      // never build an event layer against a previous request's ExecutionContext.
+      // HttpEffect owns the inner scope and transfers it to streaming response bodies.
       return this[RunSymbol](
-        renderFetchSuccess(fetchHandler).pipe(
-          Effect.tap(() => scheduleTelemetryFlush),
-          Effect.provide(requestServices),
-        ) as Effect.Effect<Response, unknown, RuntimeContext<ROut> | REvent | Scope.Scope>,
+        renderFetchSuccess(fetchHandler, options.eventLayer).pipe(Effect.provide(requestServices)),
+        { event: "fetch" },
       );
     }
 
@@ -449,7 +474,12 @@ 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)).pipe(
+          Effect.onExit(() => scheduleTelemetryFlush),
+        ),
+        { event: "queue" },
+      );
     }
   }
 
@@ -458,8 +488,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);
@@ -473,12 +504,13 @@ interface FetchCapableInstance {
  * Creates an `ExportedHandler`-compatible `{ fetch }` object backed by
  * {@link make}.
  *
- * The Effect runtime is cached per `env` identity, so the user layer builds
- * once per isolate instead of once per request. `ExecutionContext`-backed
- * services (`Worker.ExecutionContext`, `Worker.WorkerContext`) are still
- * provided fresh for every request. 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.
+ * The Effect runtime is cached per `env` identity, so the base layer builds
+ * once for that cached handler. Request handlers and `eventLayer` receive fresh
+ * `ExecutionContext` and `WorkerContext` services. A service constructed by the
+ * cached base layer from either context instead captures the first request's
+ * value, so construct invocation-bound services in `eventLayer`. Cloudflare
+ * provides no isolate shutdown hook, so cached base-layer finalizers are not
+ * guaranteed to run.
  */
 export function makeFetchHandler<
   ROut,

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;
@@ -190,7 +186,7 @@ export const embeddingResponse = (value: {
   [embeddingDimensionsKey]: value[embeddingDimensionsKey] ?? [],
 });
 
-const decodeEmbeddingResponse = S.decodeUnknownOption(
+const decodeEmbeddingResponse = S.decodeUnknownEffect(
   S.Struct({
     data: S.optional(S.Array(S.Array(S.Number))),
     [embeddingDimensionsKey]: S.optional(S.Array(S.Number)),
@@ -216,21 +212,28 @@ export const makeClient =
         () => ai.aiGatewayLogId,
       ),
       run,
-      runEmbedding: Effect.fn("WorkersAi.runEmbedding")(
-        (model: string, input: WorkersAiEmbeddingInput, options?: WorkersAiOptions) => {
-          // SAFETY: every WorkersAiEmbeddingInput variant is a string-keyed Workers AI payload.
-          const modelInput = input as Parameters<WorkersAiBinding["run"]>[1];
+      runEmbedding: Effect.fn("WorkersAi.runEmbedding")(function* (
+        model: string,
+        input: WorkersAiEmbeddingInput,
+        options?: WorkersAiOptions,
+      ) {
+        // SAFETY: every WorkersAiEmbeddingInput variant is a string-keyed Workers AI payload.
+        const modelInput = input as Parameters<WorkersAiBinding["run"]>[1];
 
-          return run(model, modelInput, options).pipe(
-            Effect.map((response) =>
-              Option.match(decodeEmbeddingResponse(response), {
-                onNone: () => embeddingResponse({}),
-                onSome: embeddingResponse,
+        const response = yield* run(model, modelInput, options);
+        const decoded = yield* decodeEmbeddingResponse(response).pipe(
+          Effect.mapError(
+            (cause) =>
+              new WorkersAiOperationError({
+                binding: definition.binding,
+                operation: "runEmbedding",
+                cause,
               }),
-            ),
-          );
-        },
-      ),
+          ),
+        );
+
+        return embeddingResponse(decoded);
+      }),
       models: Effect.fn("WorkersAi.models")((params?: WorkersAiModelsSearchParams) =>
         tryWorkersAiPromise(definition.binding, "models", () => ai.models(params)),
       ),