effect-cf 0.20.1 → 0.22.0

package/src/BrowserRendering.ts

@@ -2,6 +2,7 @@ import { Context, Data, Effect, type Layer } from "effect";
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedBrowserRenderingBinding = "Browser Rendering binding resource";
 
@@ -12,7 +13,11 @@ export class BrowserRenderingOperationError extends Data.TaggedError(
   readonly binding: string;
   readonly operation: string;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Browser Rendering ${this.operation} failed for binding "${this.binding}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** Typed Browser Rendering binding definition. */
 export interface BrowserRenderingDefinition {
@@ -106,7 +111,7 @@ export interface BrowserRenderingClient<
     connect: BrowserRenderingConnect<RawBinding, Browser, ConnectOptions>,
     options?: ConnectOptions,
   ) => Effect.Effect<BrowserRenderingBrowserClient<Browser, Page>, BrowserRenderingOperationError>;
-  readonly unsafeRaw: Effect.Effect<RawBinding>;
+  readonly rawUnsafe: Effect.Effect<RawBinding>;
   readonly definition: BrowserRenderingDefinition;
 }
 
@@ -251,15 +256,33 @@ export const makeClient =
   ) =>
   (binding: RawBinding): BrowserRenderingClient<RawBinding> => ({
     definition,
-    launchWith: (launch, options) =>
+    launchWith: <
+      Browser extends BrowserRenderingBrowserLike<Page>,
+      Page extends BrowserRenderingPageLike = BrowserRenderingPageLike,
+      LaunchOptions = unknown,
+    >(
+      launch: BrowserRenderingLaunch<RawBinding, Browser, LaunchOptions>,
+      options?: LaunchOptions,
+    ) =>
       tryBrowserRenderingPromise(definition.binding, "launch", () => launch(binding, options)).pipe(
-        Effect.map((browser) => wrapBrowser(definition.binding, browser)),
+        Effect.map((browser) => wrapBrowser<Browser, Page>(definition.binding, browser)),
+        Effect.withSpan("BrowserRendering.launchWith"),
       ),
-    connectWith: (connect, options) =>
+    connectWith: <
+      Browser extends BrowserRenderingBrowserLike<Page>,
+      Page extends BrowserRenderingPageLike = BrowserRenderingPageLike,
+      ConnectOptions = unknown,
+    >(
+      connect: BrowserRenderingConnect<RawBinding, Browser, ConnectOptions>,
+      options?: ConnectOptions,
+    ) =>
       tryBrowserRenderingPromise(definition.binding, "connect", () =>
         connect(binding, options),
-      ).pipe(Effect.map((browser) => wrapBrowser(definition.binding, browser))),
-    unsafeRaw: Effect.succeed(binding),
+      ).pipe(
+        Effect.map((browser) => wrapBrowser<Browser, Page>(definition.binding, browser)),
+        Effect.withSpan("BrowserRendering.connectWith"),
+      ),
+    rawUnsafe: Effect.succeed(binding),
   });
 
 export const layer = <Self>(

package/src/Cache.ts

@@ -6,6 +6,8 @@ import type {
 } from "@cloudflare/workers-types";
 import { Context, Data, Effect, Layer, Option } from "effect";
 
+import * as ErrorMessage from "./internal/ErrorMessage";
+
 /** Request key accepted by Cloudflare's Cache API. */
 export type CacheRequest = CloudflareRequestInfo | URL;
 
@@ -20,7 +22,11 @@ export class CacheOperationError extends Data.TaggedError("CacheOperationError")
   readonly cache: string;
   readonly operation: CacheOperation;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Cache ${this.operation} failed for cache "${this.cache}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** Effect wrapper around one Cloudflare `Cache` instance. */
 export interface CacheClient {
@@ -42,7 +48,7 @@ export interface CacheClient {
     options?: CacheQueryOptions,
   ) => Effect.Effect<boolean, CacheOperationError>;
   /** Access to the native Cloudflare `Cache` instance. */
-  readonly unsafeRaw: Effect.Effect<CloudflareCache>;
+  readonly rawUnsafe: Effect.Effect<CloudflareCache>;
 }
 
 /** Effect wrapper around Cloudflare's global `caches` object. */
@@ -52,7 +58,7 @@ export interface CacheStorageClient {
   /** Opens a named cache. */
   readonly open: (name: string) => Effect.Effect<CacheClient, CacheOperationError>;
   /** Access to the native Cloudflare `CacheStorage` instance. */
-  readonly unsafeRaw: Effect.Effect<CloudflareCacheStorage>;
+  readonly rawUnsafe: Effect.Effect<CloudflareCacheStorage>;
 }
 
 /** Service for Cloudflare's global Cache API. */
@@ -73,17 +79,34 @@ const tryCachePromise = <A>(
     catch: (cause) => cacheError(cache, operation, cause),
   });
 
+const spanOptions = (cache: string, operation: CacheOperation) => ({
+  attributes: { cache, operation },
+});
+
 /** Wraps a native Cloudflare `Cache` instance. */
 export const makeCacheClient = (cache: CloudflareCache, name = "default"): CacheClient => ({
   name,
-  match: (request, options) =>
+  match: Effect.fn(
+    "Cache.match",
+    spanOptions(name, "match"),
+  )((request: CacheRequest, options?: CacheQueryOptions) =>
     tryCachePromise(name, "match", () => cache.match(request, options)).pipe(
       Effect.map(Option.fromUndefinedOr),
     ),
-  put: (request, response) => tryCachePromise(name, "put", () => cache.put(request, response)),
-  delete: (request, options) =>
+  ),
+  put: Effect.fn(
+    "Cache.put",
+    spanOptions(name, "put"),
+  )((request: CacheRequest, response: Response) =>
+    tryCachePromise(name, "put", () => cache.put(request, response)),
+  ),
+  delete: Effect.fn(
+    "Cache.delete",
+    spanOptions(name, "delete"),
+  )((request: CacheRequest, options?: CacheQueryOptions) =>
     tryCachePromise(name, "delete", () => cache.delete(request, options)),
-  unsafeRaw: Effect.succeed(cache),
+  ),
+  rawUnsafe: Effect.succeed(cache),
 });
 
 /** Wraps a native Cloudflare `CacheStorage` instance. */
@@ -92,8 +115,9 @@ export const makeClient = (storage: CloudflareCacheStorage): CacheStorageClient
   open: (name) =>
     tryCachePromise(name, "open", () => storage.open(name)).pipe(
       Effect.map((cache) => makeCacheClient(cache, name)),
+      Effect.withSpan("Cache.open", spanOptions(name, "open")),
     ),
-  unsafeRaw: Effect.succeed(storage),
+  rawUnsafe: Effect.succeed(storage),
 });
 
 /** Provides Cache API services from an explicit native `CacheStorage` instance. */

package/src/CloudflareOtlp.ts

@@ -1,7 +1,22 @@
+/**
+ * OTLP telemetry layers for Cloudflare Workers and Durable Objects.
+ *
+ * Every layer exposes {@link OtlpExporter.Flusher}, which drains buffered
+ * telemetry on demand. Cloudflare isolates can freeze before the periodic
+ * export interval fires, so flush explicitly before returning a response, or
+ * hand the flush to `ctx.waitUntil`:
+ *
+ * ```ts
+ * const flusher = yield* OtlpExporter.Flusher;
+ *
+ * yield* flusher.flush;
+ * ```
+ */
 import { ConfigProvider, Effect, Layer, Option } from "effect";
 import type * as Tracer from "effect/Tracer";
 import { FetchHttpClient, type Headers } from "effect/unstable/http";
 import {
+  OtlpExporter,
   OtlpLogger,
   OtlpMetrics,
   OtlpSerialization,
@@ -138,7 +153,7 @@ const mergeSignalLayers = (layers: ReadonlyArray<SignalLayer>): SignalLayer => {
 const makeLayer = (
   options: LayerOptions = {},
   runtimeAttributes: Record<string, unknown> = {},
-): Layer.Layer<never, never, never> => {
+): Layer.Layer<OtlpExporter.Flusher> => {
   const signals = selectedSignals(options.signals);
   const resource = makeResource(options, runtimeAttributes);
   const layers: Array<SignalLayer> = [];
@@ -174,7 +189,7 @@ const makeLayer = (
   }
 
   if (layers.length === 0) {
-    return Layer.empty;
+    return OtlpExporter.layerFlusher;
   }
 
   return mergeSignalLayers(layers).pipe(
@@ -191,16 +206,22 @@ const makeLayer = (
  * layers. In Cloudflare Workers and Durable Objects, the current `env` object is
  * installed as the primary `ConfigProvider`; outside Cloudflare, the ambient
  * Effect `ConfigProvider` remains the fallback.
+ *
+ * The layer provides {@link OtlpExporter.Flusher} for draining buffered
+ * telemetry before the isolate freezes.
  */
-export const layer = (options: LayerOptions = {}) => makeLayer(options);
+export const layer = (options: LayerOptions = {}): Layer.Layer<OtlpExporter.Flusher> =>
+  makeLayer(options);
 
 /** Base OTLP telemetry layer forced to JSON serialization. */
-export const layerJson = (options: Omit<LayerOptions, "serialization"> = {}) =>
-  layer({ ...options, serialization: "json" });
+export const layerJson = (
+  options: Omit<LayerOptions, "serialization"> = {},
+): Layer.Layer<OtlpExporter.Flusher> => layer({ ...options, serialization: "json" });
 
 /** Base OTLP telemetry layer forced to protobuf serialization. */
-export const layerProtobuf = (options: Omit<LayerOptions, "serialization"> = {}) =>
-  layer({ ...options, serialization: "protobuf" });
+export const layerProtobuf = (
+  options: Omit<LayerOptions, "serialization"> = {},
+): Layer.Layer<OtlpExporter.Flusher> => layer({ ...options, serialization: "protobuf" });
 
 /**
  * OTLP layer with Cloudflare Worker resource attributes.
@@ -208,7 +229,7 @@ export const layerProtobuf = (options: Omit<LayerOptions, "serialization"> = {})
  * Provide this layer at runtime scope for long-lived metrics aggregation, or at
  * handler scope when traces/logs should flush as the Cloudflare event finishes.
  */
-export const workerLayer = (options: WorkerLayerOptions = {}) =>
+export const layerWorker = (options: WorkerLayerOptions = {}): Layer.Layer<OtlpExporter.Flusher> =>
   makeLayer(options, {
     "cloudflare.resource_type": "worker",
     "cloudflare.worker.name": options.workerName,
@@ -221,7 +242,9 @@ export const workerLayer = (options: WorkerLayerOptions = {}) =>
  * Durable Object id. Prefer leaving `includeObjectId` disabled unless the
  * backend can tolerate high-cardinality resource attributes.
  */
-export const durableObjectLayer = (options: DurableObjectLayerOptions = {}) =>
+export const layerDurableObject = (
+  options: DurableObjectLayerOptions = {},
+): Layer.Layer<OtlpExporter.Flusher, never, DurableObjectState> =>
   Layer.unwrap(
     Effect.map(DurableObjectState, (state) =>
       makeLayer(options, {

package/src/ContainerNamespace.ts

@@ -1,7 +1,8 @@
-import { Context, Data, Effect, Schema, type Layer } from "effect";
+import { Context, Data, Effect, Schema as S, type Layer } from "effect";
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedContainerNamespace = "Container namespace binding with getByName()";
 
@@ -38,15 +39,15 @@ export interface ContainerStartAndWaitForPortsOptions {
 }
 
 /** Serializable state reported by a Cloudflare Container instance. */
-export const ContainerState = Schema.Union([
-  Schema.Struct({
-    lastChange: Schema.Finite,
-    status: Schema.Literals(["running", "stopping", "stopped", "healthy"]),
+export const ContainerState = S.Union([
+  S.Struct({
+    lastChange: S.Finite,
+    status: S.Literals(["running", "stopping", "stopped", "healthy"]),
   }),
-  Schema.Struct({
-    lastChange: Schema.Finite,
-    status: Schema.Literal("stopped_with_code"),
-    exitCode: Schema.optionalKey(Schema.Int),
+  S.Struct({
+    lastChange: S.Finite,
+    status: S.Literal("stopped_with_code"),
+    exitCode: S.optionalKey(S.Int),
   }),
 ]);
 export type ContainerState = typeof ContainerState.Type;
@@ -86,11 +87,15 @@ export class ContainerOperationError extends Data.TaggedError("ContainerOperatio
   readonly instance: string;
   readonly operation: string;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Container ${this.operation} failed for binding "${this.binding}" instance "${this.instance}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** Effect-wrapped client for one named Container instance. */
 export interface ContainerInstanceClient {
-  readonly unsafeRaw: Effect.Effect<ContainerStub, ContainerOperationError>;
+  readonly rawUnsafe: Effect.Effect<ContainerStub, ContainerOperationError>;
   readonly state: Effect.Effect<ContainerState, ContainerOperationError>;
   readonly fetch: (
     input: RequestInfo | URL,
@@ -118,7 +123,7 @@ export interface ContainerNamespaceClient {
     name: string,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
   ) => ContainerInstanceClient;
-  readonly unsafeRaw: Effect.Effect<ContainerNamespaceResource>;
+  readonly rawUnsafe: Effect.Effect<ContainerNamespaceResource>;
 }
 
 export type ContainerNamespaceStaticClient<R> = {
@@ -144,9 +149,9 @@ export type ContainerNamespaceStaticClient<R> = {
     ) => Effect.Effect<void, ContainerOperationError, R>;
     readonly stop: (signal?: ContainerSignal) => Effect.Effect<void, ContainerOperationError, R>;
     readonly destroy: Effect.Effect<void, ContainerOperationError, R>;
-    readonly unsafeRaw: Effect.Effect<ContainerStub, ContainerOperationError, R>;
+    readonly rawUnsafe: Effect.Effect<ContainerStub, ContainerOperationError, R>;
   };
-  readonly unsafeRaw: () => Effect.Effect<ContainerNamespaceResource, never, R>;
+  readonly rawUnsafe: Effect.Effect<ContainerNamespaceResource, never, R>;
 };
 
 export type LayerOptions = {
@@ -155,7 +160,7 @@ export type LayerOptions = {
 
 export interface TagClass<Self, Id extends string>
   extends
-    Context.ServiceClass<Self, Id, ContainerNamespaceClient>,
+    Context.ServiceClass<Self, `effect-cf/Container/${Id}`, ContainerNamespaceClient>,
     ContainerNamespaceStaticClient<Self> {
   readonly id: Id;
   readonly layer: (
@@ -188,32 +193,62 @@ const makeInstanceClient = (
   definition: ContainerNamespaceDefinition,
   instance: string,
   stub: ContainerStub,
-): ContainerInstanceClient => ({
-  unsafeRaw: Effect.succeed(stub),
-  state: tryContainerPromise(definition, instance, "state", () => stub.getState()).pipe(
-    Effect.flatMap(Schema.decodeUnknownEffect(ContainerState)),
-    Effect.mapError((cause) =>
-      cause instanceof ContainerOperationError
-        ? cause
-        : new ContainerOperationError({
-            binding: definition.binding,
-            instance,
-            operation: "state",
-            cause,
-          }),
+): ContainerInstanceClient => {
+  const spanOptions = (operation: string) => ({
+    attributes: { binding: definition.binding, instance, operation },
+  });
+
+  return {
+    rawUnsafe: Effect.succeed(stub),
+    state: tryContainerPromise(definition, instance, "state", () => stub.getState()).pipe(
+      Effect.flatMap(S.decodeUnknownEffect(ContainerState)),
+      Effect.mapError((cause) =>
+        cause instanceof ContainerOperationError
+          ? cause
+          : new ContainerOperationError({
+              binding: definition.binding,
+              instance,
+              operation: "state",
+              cause,
+            }),
+      ),
+      Effect.withSpan("ContainerNamespace.state", spanOptions("state")),
     ),
-  ),
-  fetch: (input, init) =>
-    tryContainerPromise(definition, instance, "fetch", () => stub.fetch(input, init)),
-  start: (options, waitOptions) =>
-    tryContainerPromise(definition, instance, "start", () => stub.start(options, waitOptions)),
-  startAndWaitForPorts: (options) =>
-    tryContainerPromise(definition, instance, "startAndWaitForPorts", () =>
-      stub.startAndWaitForPorts(options),
+    fetch: Effect.fn(
+      "ContainerNamespace.fetch",
+      spanOptions("fetch"),
+    )(function* (input: RequestInfo | URL, init?: RequestInit) {
+      return yield* tryContainerPromise(definition, instance, "fetch", () =>
+        stub.fetch(input, init),
+      );
+    }),
+    start: Effect.fn(
+      "ContainerNamespace.start",
+      spanOptions("start"),
+    )(function* (options?: ContainerStartOptions, waitOptions?: ContainerWaitOptions) {
+      return yield* tryContainerPromise(definition, instance, "start", () =>
+        stub.start(options, waitOptions),
+      );
+    }),
+    startAndWaitForPorts: Effect.fn(
+      "ContainerNamespace.startAndWaitForPorts",
+      spanOptions("startAndWaitForPorts"),
+    )(function* (options?: ContainerStartAndWaitForPortsOptions) {
+      return yield* tryContainerPromise(definition, instance, "startAndWaitForPorts", () =>
+        stub.startAndWaitForPorts(options),
+      );
+    }),
+    stop: Effect.fn(
+      "ContainerNamespace.stop",
+      spanOptions("stop"),
+    )(function* (signal?: ContainerSignal) {
+      return yield* tryContainerPromise(definition, instance, "stop", () => stub.stop(signal));
+    }),
+    destroy: tryContainerPromise(definition, instance, "destroy", () => stub.destroy()).pipe(
+      Effect.withSpan("ContainerNamespace.destroy", spanOptions("destroy")),
     ),
-  stop: (signal) => tryContainerPromise(definition, instance, "stop", () => stub.stop(signal)),
-  destroy: tryContainerPromise(definition, instance, "destroy", () => stub.destroy()),
-});
+  };
+};
 
 export const isContainerNamespaceResource = (value: unknown): value is ContainerNamespaceResource =>
   typeof value === "object" &&
@@ -245,7 +280,7 @@ export const makeClient =
       const instance = getByName(name, options);
 
       return {
-        unsafeRaw: Effect.flatMap(instance, (client) => client.unsafeRaw),
+        rawUnsafe: Effect.flatMap(instance, (client) => client.rawUnsafe),
         state: Effect.flatMap(instance, (client) => client.state),
         fetch: (input, init) => Effect.flatMap(instance, (client) => client.fetch(input, init)),
         start: (startOptions, waitOptions) =>
@@ -261,7 +296,7 @@ export const makeClient =
       definition,
       getByName,
       byName,
-      unsafeRaw: Effect.succeed(namespace),
+      rawUnsafe: Effect.succeed(namespace),
     };
   };
 
@@ -288,18 +323,19 @@ export interface ContainerNamespaceService<Id extends string> {
 export const Tag =
   <Self>() =>
   <Id extends string>(id: Id) => {
-    const tag = Context.Service<Self, ContainerNamespaceClient>()(id);
+    const tag = Context.Service<Self, ContainerNamespaceClient>()(
+      `effect-cf/Container/${id}` as const,
+    );
     const makeLayer = (definition: LayerOptions) => layer(tag, definition);
 
-    const getByName = (
+    const getByName = Effect.fnUntraced(function* (
       name: string,
       options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
-    ) =>
-      Effect.gen(function* () {
-        const namespace = yield* tag;
+    ) {
+      const namespace = yield* tag;
 
-        return yield* namespace.getByName(name, options);
-      });
+      return yield* namespace.getByName(name, options);
+    });
 
     const byName = (
       name: string,
@@ -319,21 +355,17 @@ export const Tag =
       stop: (signal?: ContainerSignal) =>
         Effect.flatMap(getByName(name, options), (instance) => instance.stop(signal)),
       destroy: Effect.flatMap(getByName(name, options), (instance) => instance.destroy),
-      unsafeRaw: Effect.flatMap(getByName(name, options), (instance) => instance.unsafeRaw),
+      rawUnsafe: Effect.flatMap(getByName(name, options), (instance) => instance.rawUnsafe),
     });
 
-    const unsafeRaw = Effect.fn(function* () {
-      const namespace = yield* tag;
-
-      return yield* namespace.unsafeRaw;
-    });
+    const rawUnsafe = Effect.flatMap(tag, (namespace) => namespace.rawUnsafe);
 
     return Object.assign(tag, {
       id,
       layer: makeLayer,
       getByName,
       byName,
-      unsafeRaw,
+      rawUnsafe,
     }) as TagClass<Self, Id>;
   };
 

package/src/D1.ts

@@ -1,9 +1,13 @@
 import { D1Client } from "@effect/sql-d1";
-import { Effect, Layer } from "effect";
+import { Effect, Layer, type Config } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
 
 import * as Binding from "./Binding";
+import type { WorkerEnvironment } from "./Environment";
 
-const TypeId = "effect-cf/D1" as const;
+const TypeId = "~effect-cf/D1" as const;
+
+export type TypeId = typeof TypeId;
 const expectedD1Database = "D1 database binding with prepare(), batch(), and exec()";
 
 /** Typed D1 binding definition. */
@@ -66,7 +70,13 @@ export const Service =
       expected: expectedD1Database,
     });
 
-    const sqlLayer = (options?: D1SqlLayerOptions) =>
+    const sqlLayer = (
+      options?: D1SqlLayerOptions,
+    ): Layer.Layer<
+      D1Client.D1Client | SqlClient.SqlClient,
+      Config.ConfigError | Binding.BindingNotFoundError | Binding.BindingValidationError,
+      WorkerEnvironment
+    > =>
       Layer.unwrap(
         Effect.gen(function* () {
           const db = yield* tag;