effect-cf 0.33.0 → 0.35.0

package/src/Kv.ts

@@ -11,10 +11,8 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 const expectedKvNamespace =
   "KV namespace binding with get(), put(), delete(), getWithMetadata(), and list()";
 
-/** KV operation represented by {@link KvOperationError}. */
 export type KvOperation = "put" | "get" | "getWithMetadata" | "list" | "delete";
 
-/** Error raised when a KV operation fails. */
 export class KvOperationError extends Data.TaggedError("KvOperationError")<{
   readonly binding: string;
   readonly operation: KvOperation;
@@ -25,28 +23,23 @@ export class KvOperationError extends Data.TaggedError("KvOperationError")<{
   }
 }
 
-/** `KVNamespace.put` options. */
 export type KvPutOptions = CloudflareKVNamespacePutOptions;
-/** `KVNamespace.list` options with optional metadata decoding schema. */
 export type KvListOptions<Metadata = unknown> = CloudflareKVNamespaceListOptions & {
   readonly metadataSchema?: S.Codec<Metadata, unknown>;
 };
 
-/** Successful value returned by `getWithMetadata`. */
 export interface KvWithMetadata<Value, Metadata> {
   readonly value: Value;
   readonly metadata: Option.Option<Metadata>;
   readonly cacheStatus: Option.Option<string>;
 }
 
-/** Decoded key entry returned by `list`. */
 export interface KvListKey<Key, Metadata = unknown> {
   readonly name: Key;
   readonly expiration: Option.Option<number>;
   readonly metadata: Option.Option<Metadata>;
 }
 
-/** Decoded result returned by `list`. */
 export interface KvListResult<Key, Metadata = unknown> {
   readonly keys: ReadonlyArray<KvListKey<Key, Metadata>>;
   readonly listComplete: boolean;
@@ -54,15 +47,9 @@ export interface KvListResult<Key, Metadata = unknown> {
   readonly cacheStatus: Option.Option<string>;
 }
 
-/**
- * Typed KV binding definition.
- */
 export interface KvDefinition<Key, Value, EncodedValue> {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
-  /** Codec used to encode/decode keys. */
   readonly key: S.Codec<Key, string>;
-  /** Codec used to encode/decode values. */
   readonly value: S.Codec<Value, EncodedValue>;
 }
 
@@ -76,9 +63,7 @@ export interface Definition<
   EncodedValue = unknown,
 > {
   readonly id: Id;
-  /** Codec used to encode/decode keys. */
   readonly key: S.Codec<Key, string>;
-  /** Codec used to encode/decode values. */
   readonly value: S.Codec<Value, EncodedValue>;
 }
 

package/src/QueueBinding.ts

@@ -27,9 +27,7 @@ const expectedQueueProducer = "Queue producer binding with send(); optional send
 type QueueCandidate = Parameters<typeof Predicate.isUnknown>[0];
 
 export interface QueueBindingDefinition<Message extends RpcDefinition.ServiceFreeSchema> {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
-  /** Codec used to encode messages before sending them to Cloudflare Queues. */
   readonly message: Message;
 }
 

package/src/R2.ts

@@ -21,7 +21,6 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 const expectedR2Bucket =
   "R2 bucket binding with head(), get(), put(), createMultipartUpload(), resumeMultipartUpload(), delete(), and list()";
 
-/** R2 operation represented by {@link R2OperationError}. */
 export type R2Operation =
   | "head"
   | "get"
@@ -39,7 +38,6 @@ export type R2Operation =
   | "json"
   | "blob";
 
-/** Error raised when an R2 operation fails. */
 export class R2OperationError extends Data.TaggedError("R2OperationError")<{
   readonly binding: string;
   readonly operation: R2Operation;
@@ -50,9 +48,7 @@ export class R2OperationError extends Data.TaggedError("R2OperationError")<{
   }
 }
 
-/** Typed R2 bucket binding definition. */
 export interface R2Definition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
@@ -133,7 +129,6 @@ export interface R2Client {
 
 declare const R2ServiceTypeId: unique symbol;
 
-/** Nominal service marker for R2 services created with {@link make}. */
 export interface R2Service<Id extends string> {
   readonly [R2ServiceTypeId]: {
     readonly id: Id;

package/src/RpcDefinition.ts

@@ -106,7 +106,6 @@ export const encodeWireError = (error: WireValue): WireValue => {
   }
 };
 
-/** Restores package RPC errors from the {@link encodeWireError} envelope. */
 export const decodeWireError = (cause: WireValue): WireValue => {
   if (!(cause instanceof Error)) {
     return cause;
@@ -125,7 +124,7 @@ export const decodeWireError = (cause: WireValue): WireValue => {
   }
 };
 
-export const reservedMethodNames = new Set([
+const reservedMethodNameValues = [
   "constructor",
   "fetch",
   "connect",
@@ -138,21 +137,11 @@ export const reservedMethodNames = new Set([
   "dispose",
   "serialize",
   "deserialize",
-]);
+] as const;
+
+export const reservedMethodNames = new Set<string>(reservedMethodNameValues);
 
-export type ReservedMethodName =
-  | "constructor"
-  | "fetch"
-  | "connect"
-  | "alarm"
-  | "webSocketMessage"
-  | "webSocketClose"
-  | "webSocketError"
-  | "then"
-  | "dup"
-  | "dispose"
-  | "serialize"
-  | "deserialize";
+export type ReservedMethodName = (typeof reservedMethodNameValues)[number];
 
 export type ServiceFreeSchema = S.Codec<any, any, never, never>;
 
@@ -184,7 +173,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;
   };

package/src/RpcTracing.ts

@@ -0,0 +1,133 @@
+import { Cause, Clock, Context, Effect, Exit, Option, References, Schema, Tracer } from "effect";
+
+/**
+ * Live native RPC metadata. Opted-in receivers reserve a valid trailing value
+ * with this tag for transport context; do not use it as a final domain argument.
+ * Never store this in durable messages or envelopes.
+ */
+export const RpcTraceContext = Schema.Struct({
+  _tag: Schema.Literal("effect-cf/RpcTraceContext/v1"),
+  traceId: Schema.String.check(Schema.isPattern(/^(?!0{32}$)[0-9a-f]{32}$/)),
+  spanId: Schema.String.check(Schema.isPattern(/^(?!0{16}$)[0-9a-f]{16}$/)),
+  sampled: Schema.Boolean,
+});
+
+export type RpcTraceContext = typeof RpcTraceContext.Type;
+
+export interface ReceiverOptions {
+  /** Stable service name, never an instance id or capability URL. */
+  readonly service: string;
+}
+
+/** Per-invocation metadata passed to Worker and DurableObject RunSymbol overrides. */
+export interface RpcInvocationInfo {
+  readonly service: string;
+  readonly method: string;
+  /** Native arguments with valid, opted-in trace metadata removed. Do not log them. */
+  readonly args: ReadonlyArray<unknown>;
+  /**
+   * Set after a definition-backed receiver decodes its arguments, before its
+   * handler runs. Absent before decoding and when decoding fails. Do not log it.
+   */
+  readonly decodedArgs?: ReadonlyArray<unknown>;
+  readonly parent?: RpcTraceContext;
+}
+
+const isRpcTraceContext = Schema.is(RpcTraceContext);
+
+/**
+ * Appends the current live parent only for a receiver that has opted in.
+ * Call this inside the CLIENT span, immediately before the native invocation.
+ * With no valid propagating parent, the original argument array is returned.
+ */
+export const withRpcTraceContext = Effect.fnUntraced(function* (
+  args: ReadonlyArray<unknown>,
+): Effect.fn.Return<ReadonlyArray<unknown>> {
+  if (yield* Tracer.DisablePropagation) {
+    return args;
+  }
+
+  const parent = yield* Effect.serviceOption(Tracer.ParentSpan);
+
+  if (Option.isNone(parent) || Context.get(parent.value.annotations, Tracer.DisablePropagation)) {
+    return args;
+  }
+
+  const context = {
+    _tag: "effect-cf/RpcTraceContext/v1",
+    traceId: parent.value.traceId,
+    spanId: parent.value.spanId,
+    sampled: parent.value.sampled,
+  };
+
+  return isRpcTraceContext(context) ? [...args, context] : args;
+});
+
+const attributes = (service: string, method: string) => ({
+  "sentry.op": "rpc",
+  "rpc.system.name": "cloudflare",
+  "rpc.method": `${service}/${method}`,
+  "server.address": service,
+});
+
+const withRpcSpan = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  service: string,
+  method: string,
+  options: Tracer.SpanOptionsNoTrace,
+): Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>> =>
+  Effect.useSpan(
+    `${service}/${method}`,
+    {
+      ...options,
+      attributes: attributes(service, method),
+    },
+    (span) =>
+      effect.pipe(
+        Effect.withParentSpan(span),
+        Effect.onExit((exit) => {
+          if (
+            Exit.isSuccess(exit) ||
+            Cause.hasInterruptsOnly(exit.cause) ||
+            span.status._tag === "Ended"
+          ) {
+            return Effect.void;
+          }
+
+          // OTLP's default cause formatter includes schema inputs and native error
+          // messages. End with a safe failure, while returning the original exit.
+          return Effect.gen(function* () {
+            const timing = yield* References.TracerTimingEnabled;
+            const endTime = timing ? yield* Clock.currentTimeNanos : 0n;
+
+            span.attribute("error.type", "_OTHER");
+            span.end(endTime, Exit.fail("RPC failed"));
+          });
+        }),
+      ),
+  );
+
+/** Wrap the whole call, including native result resolution and success decoding. */
+export const withRpcClientSpan = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  binding: string,
+  method: string,
+): Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>> =>
+  withRpcSpan(effect, binding, method, {
+    kind: "client",
+  });
+
+/**
+ * Optional application instrumentation for the entire receiver effect.
+ * Use in a RunSymbol override to include argument decode, handler and encode.
+ * Records stable service/method attributes and failure status, not argument or
+ * error payloads. The original typed failure still propagates to the caller.
+ */
+export const withRpcServerSpan = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  invocation: RpcInvocationInfo,
+): Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>> =>
+  withRpcSpan(effect, invocation.service, invocation.method, {
+    kind: "server",
+    parent: invocation.parent === undefined ? undefined : Tracer.externalSpan(invocation.parent),
+  });

package/src/Sandbox.ts

@@ -77,13 +77,10 @@ export type {
 const expectedSandboxNamespace =
   "Sandbox Durable Object namespace binding with idFromName() and get()";
 
-/** Sandbox namespace binding metadata. */
 export interface SandboxDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
-/** Failure raised when invoking a sandbox operation. */
 export class SandboxOperationError extends Data.TaggedError("SandboxOperationError")<{
   readonly binding: string;
   readonly instance: string;
@@ -110,55 +107,42 @@ export interface SandboxNamespaceResource {
   ): globalThis.DurableObjectStub;
 }
 
-/** Result of `writeFile` as reported by the sandbox client. */
 export type WriteFileResult = Awaited<ReturnType<ISandbox["writeFile"]>>;
 
-/** Result of `readFile` as reported by the sandbox client. */
 export type ReadFileResult = Awaited<ReturnType<ISandbox["readFile"]>>;
 
-/** Result of `mkdir` as reported by the sandbox client. */
 export type MkdirResult = Awaited<ReturnType<ISandbox["mkdir"]>>;
 
-/** Result of `deleteFile` as reported by the sandbox client. */
 export type DeleteFileResult = Awaited<ReturnType<ISandbox["deleteFile"]>>;
 
-/** Result of `renameFile` as reported by the sandbox client. */
 export type RenameFileResult = Awaited<ReturnType<ISandbox["renameFile"]>>;
 
-/** Result of `moveFile` as reported by the sandbox client. */
 export type MoveFileResult = Awaited<ReturnType<ISandbox["moveFile"]>>;
 
-/** Result of `listFiles` as reported by the sandbox client. */
 export type ListFilesResult = Awaited<ReturnType<ISandbox["listFiles"]>>;
 
-/** Result of `exists` as reported by the sandbox client. */
 export type FileExistsResult = Awaited<ReturnType<ISandbox["exists"]>>;
 
-/** Text encodings accepted by `readFile`. */
 export type ReadFileEncoding = "utf-8" | "utf8" | "base64";
 
-/** Options accepted by `exposePort`. */
 export interface ExposePortOptions {
   readonly name?: string;
   readonly hostname: string;
   readonly token?: string;
 }
 
-/** Preview URL information returned by `exposePort`. */
 export interface ExposedPort {
   readonly url: string;
   readonly port: number;
   readonly name?: string;
 }
 
-/** Currently forwardable preview URL returned by `getExposedPorts`. */
 export interface ExposedPortStatus {
   readonly url: string;
   readonly port: number;
   readonly status: "active";
 }
 
-/** Structural tunnel API surface exposed by a sandbox client. */
 export interface SandboxTunnelsResource {
   get(port: number, options?: TunnelOptions): Promise<TunnelInfo>;
   list(): Promise<Array<TunnelInfo>>;
@@ -183,7 +167,6 @@ export interface SandboxClientResource extends ISandbox {
   readonly tunnels: SandboxTunnelsResource;
 }
 
-/** Effect-wrapped handle for one process started inside a sandbox. */
 export interface SandboxProcessHandle {
   readonly id: string;
   readonly pid: number;
@@ -213,7 +196,6 @@ export interface SandboxProcessHandle {
   readonly kill: (signal?: number) => Effect.Effect<void, SandboxOperationError>;
 }
 
-/** Effect-wrapped handle for one interactive terminal inside a sandbox. */
 export interface SandboxTerminalHandle {
   readonly id: string;
   readonly rawUnsafe: Effect.Effect<Terminal>;
@@ -238,7 +220,6 @@ export interface SandboxTerminalHandle {
   ) => Effect.Effect<Response, SandboxOperationError>;
 }
 
-/** Effect-wrapped tunnel operations for one sandbox instance. */
 export interface SandboxTunnelsClient {
   readonly get: (
     port: number,
@@ -248,7 +229,6 @@ export interface SandboxTunnelsClient {
   readonly destroy: (portOrInfo: number | TunnelInfo) => Effect.Effect<void, SandboxOperationError>;
 }
 
-/** Effect-wrapped client for one named sandbox instance. */
 export interface SandboxInstanceClient {
   readonly rawUnsafe: Effect.Effect<SandboxClientResource>;
   readonly exec: (
@@ -344,7 +324,6 @@ export interface SandboxInstanceClient {
   readonly destroy: Effect.Effect<void, SandboxOperationError>;
 }
 
-/** Effect client for a Sandbox Durable Object namespace binding. */
 export interface SandboxNamespaceClient<
   Namespace extends SandboxNamespaceResource = SandboxNamespaceResource,
 > {
@@ -616,13 +595,6 @@ const makeTerminalHandle = (
   };
 };
 
-/**
- * Wraps an already-created sandbox client (the value returned by
- * `getSandbox()` from `@cloudflare/sandbox`) into an Effect client.
- *
- * Prefer {@link Tag}/{@link make} with a layer for application code; this
- * entry point exists for advanced composition and testing.
- */
 export const fromSandboxClient = (
   client: SandboxClientResource,
   definition: SandboxDefinition,
@@ -1029,14 +1001,12 @@ export const make = <Id extends string>(id: Id) => Tag<SandboxNamespaceService<I
 
 declare const SandboxNamespaceServiceTypeId: unique symbol;
 
-/** Nominal service marker for Sandbox namespaces created with {@link make}. */
 export interface SandboxNamespaceService<Id extends string> {
   readonly [SandboxNamespaceServiceTypeId]: {
     readonly id: Id;
   };
 }
 
-/** Creates a typed Effect service for a Cloudflare Sandbox namespace. */
 export const Tag =
   <Self, Namespace extends SandboxNamespaceResource = SandboxNamespaceResource>() =>
   <Id extends string>(id: Id) => {