effect-cf 0.20.1 → 0.23.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, {