effect-cf 0.33.0 → 0.35.0

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,
@@ -18,6 +14,7 @@ import {
   Context,
   Data,
   Effect,
+  FiberSet,
   Layer,
   type ManagedRuntime,
   Option,
@@ -44,9 +41,6 @@ export class WorkflowEvent extends Context.Service<WorkflowEvent, WorkflowEventS
   "effect-cf/WorkflowEvent",
 ) {}
 
-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;
@@ -140,52 +134,52 @@ const exposeCloudflareNonRetryableError = <A, E, R>(
       : Effect.failCause(cause);
   });
 
-const fromWorkflowStep = (
-  step: CloudflareWorkflowStep,
-  runPromise: RunWorkflowStepEffect,
-): WorkflowStepService => ({
+const fromWorkflowStep = (step: CloudflareWorkflowStep): WorkflowStepService => ({
   raw: step,
   do: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>, config?: WorkflowStepConfig) =>
-    Effect.context<Exclude<R, WorkflowStepContext>>().pipe(
-      Effect.flatMap((context) =>
-        Effect.tryPromise({
-          try: () => {
-            const run = (stepContext: CloudflareWorkflowStepContext) =>
-              runPromise(
-                exposeCloudflareNonRetryableError(
-                  Effect.scoped(
-                    Effect.provideService(
-                      Effect.provideContext(
-                        // SAFETY: WorkflowStepContext is provided immediately below; context supplies every other R service.
-                        // @effect-diagnostics-next-line unsafeEffectTypeAssertion:off
-                        effect as Effect.Effect<A, E, Exclude<R, WorkflowStepContext>>,
-                        context,
-                      ),
-                      WorkflowStepContext,
-                      stepContext,
-                    ),
-                  ),
-                ),
-              );
-            // SAFETY: these overloads reproduce the Cloudflare WorkflowStep.do runtime signatures used here.
-            const rawStep = step as {
-              do(
-                name: string,
-                callback: (context: CloudflareWorkflowStepContext) => Promise<A>,
-              ): Promise<A>;
-              do(
-                name: string,
-                config: WorkflowStepConfig,
-                callback: (context: CloudflareWorkflowStepContext) => Promise<A>,
-              ): Promise<A>;
-            };
-
-            return config === undefined ? rawStep.do(name, run) : rawStep.do(name, config, run);
-          },
-          catch: (cause) => new WorkflowStepError({ step: name, operation: "do", cause }),
+    Effect.gen(function* () {
+      const context = yield* Effect.context<Exclude<R, WorkflowStepContext>>();
+
+      return yield* Effect.scoped(
+        Effect.gen(function* () {
+          // Cloudflare owns retry timing and exposes no step cancellation API.
+          // Join the current callback on interruption and prevent later retry
+          // callbacks from starting, without waiting for native retry delays.
+          const runPromise = yield* FiberSet.makeRuntimePromise<never, A, E>();
+
+          return yield* Effect.tryPromise({
+            try: () => {
+              const run = (stepContext: CloudflareWorkflowStepContext) => {
+                const stepEffect: Effect.Effect<
+                  A,
+                  E,
+                  Exclude<R, WorkflowStepContext>
+                > = Effect.scoped(Effect.provideService(effect, WorkflowStepContext, stepContext));
+
+                return runPromise(
+                  exposeCloudflareNonRetryableError(Effect.provideContext(stepEffect, context)),
+                );
+              };
+              // SAFETY: these overloads reproduce the Cloudflare WorkflowStep.do runtime signatures used here.
+              const rawStep = step as {
+                do(
+                  name: string,
+                  callback: (context: CloudflareWorkflowStepContext) => Promise<A>,
+                ): Promise<A>;
+                do(
+                  name: string,
+                  config: WorkflowStepConfig,
+                  callback: (context: CloudflareWorkflowStepContext) => Promise<A>,
+                ): Promise<A>;
+              };
+
+              return config === undefined ? rawStep.do(name, run) : rawStep.do(name, config, run);
+            },
+            catch: (cause) => new WorkflowStepError({ step: name, operation: "do", cause }),
+          });
         }),
-      ),
-    ),
+      );
+    }),
   sleep: (name, duration) =>
     Effect.tryPromise({
       try: () => step.sleep(name, duration),
@@ -268,10 +262,7 @@ export const make = <ROut, LayerError, Payload = unknown, Result = unknown>(
     ): Promise<Result> {
       const workflowServices = Layer.mergeAll(
         Layer.succeed(WorkflowEvent, fromWorkflowEvent(event)),
-        Layer.succeed(
-          WorkflowStep,
-          fromWorkflowStep(step, (effect) => this.runtime.runPromise(effect)),
-        ),
+        Layer.succeed(WorkflowStep, fromWorkflowStep(step)),
       );
 
       return Runtime.runEventPromise(this.runtime, options.run(event.payload), workflowServices);

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/NativeCallback.ts

@@ -0,0 +1,55 @@
+import { Effect, Exit, FiberSet } from "effect";
+
+type RunCallback<A, E, R> = (effect: Effect.Effect<A, E, R>) => Promise<Exit.Exit<A, E>>;
+
+/**
+ * Runs an Effect callback owned by a native Promise operation.
+ *
+ * The callback keeps the caller's context, while a private scope owns its
+ * fiber. Closing that scope interrupts and joins the callback before awaiting
+ * the native operation's settlement.
+ */
+export const runNativeCallback = Effect.fnUntraced(function* <A, E, R, B>(
+  operation: (run: RunCallback<A, E, R>) => Promise<B>,
+): Effect.fn.Return<B, unknown, R> {
+  const callerContext = yield* Effect.context<R>();
+
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      let nativePromise: Promise<B> | undefined;
+
+      // Registered before the FiberSet so scope closure first interrupts and
+      // joins the callback, then waits for the native rollback/gate to settle.
+      yield* Effect.addFinalizer(() => {
+        const promise = nativePromise;
+
+        return promise === undefined
+          ? Effect.void
+          : Effect.promise(() =>
+              promise.then(
+                () => undefined,
+                () => undefined,
+              ),
+            );
+      });
+      const runPromise = yield* FiberSet.makeRuntimePromise<never, Exit.Exit<A, E>, never>();
+
+      return yield* Effect.callback<B, unknown>((resume) => {
+        try {
+          nativePromise = operation((effect) =>
+            runPromise(Effect.provideContext(Effect.exit(effect), callerContext)),
+          );
+        } catch (cause) {
+          resume(Effect.fail(cause));
+
+          return;
+        }
+
+        nativePromise.then(
+          (value) => resume(Effect.succeed(value)),
+          (cause) => resume(Effect.fail(cause)),
+        );
+      });
+    }),
+  );
+});

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

@@ -17,7 +17,9 @@ const failureHandler = <E, R>(
   cause: Cause.Cause<E>,
   options: WorkerContextWaitUntilOptions<E, R> | undefined,
 ) =>
-  (options?.onFailure?.(cause) ?? Effect.logError(`${label} failed`, Cause.pretty(cause))).pipe(
+  Effect.suspend(
+    () => options?.onFailure?.(cause) ?? Effect.logError(`${label} failed`, Cause.pretty(cause)),
+  ).pipe(
     Effect.catchCause((handlerCause) =>
       Effect.logError(
         `${label} failure handler failed`,
@@ -27,14 +29,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,
@@ -50,7 +44,7 @@ export const makeWaitUntilScheduler = (
         Effect.sync(() => {
           const runHandler = (cause: Cause.Cause<E>) =>
             runPromiseExit(
-              Effect.scoped(Effect.provideContext(failureHandler(label, cause, options), context)),
+              Effect.provideContext(Effect.scoped(failureHandler(label, cause, options)), context),
             ).then((exit) => {
               if (Exit.isFailure(exit)) {
                 console.error(`${label} failure handler failed`, Cause.pretty(exit.cause));
@@ -58,7 +52,7 @@ export const makeWaitUntilScheduler = (
             });
 
           register(
-            runPromiseExit(Effect.scoped(Effect.provideContext(effect, context))).then(
+            runPromiseExit(Effect.provideContext(Effect.scoped(effect), context)).then(
               async (exit) => {
                 if (Exit.isSuccess(exit)) {
                   return;
@@ -77,9 +71,6 @@ export const makeWaitUntilScheduler = (
     );
 };
 
-/**
- * Builds the `WorkerContext` service from a native `ExecutionContext`.
- */
 export const fromExecutionContext = (
   ctx: globalThis.ExecutionContext,
   runPromiseExit: RunWaitUntilEffect = (effect) => Effect.runPromiseExit(effect),