effect-cf 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {
@@ -9,6 +9,7 @@
     "directory": "packages/effect-cf"
   },
   "files": [
+    "CHANGELOG.md",
     "dist",
     "src"
   ],
@@ -38,7 +39,7 @@
     "@effect/vitest": "catalog:",
     "effect": "catalog:",
     "typescript": "^6.0.2",
-    "vite-plus": "0.1.19",
+    "vite-plus": "0.1.20",
     "vitest": "catalog:"
   },
   "peerDependencies": {

package/src/DurableObjectRpcWebSocket.ts

@@ -4,6 +4,7 @@ import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
 import * as RpcServer from "effect/unstable/rpc/RpcServer";
 
 import { DurableObjectState } from "./DurableObjectState";
+import type { DurableWebSocket } from "./DurableObjectWebSocket";
 
 const defaultAttachmentKey = "effectCloudflareRpcClientId";
 const defaultTag = "effect-cf-rpc";
@@ -25,15 +26,18 @@ export type NativeWebSocketMessage = string | ArrayBuffer;
  * Service API used to wire websocket lifecycle events to Effect RPC server protocol.
  */
 export interface DurableObjectRpcWebSocketService {
-  readonly accept: (socket: WebSocket) => Effect.Effect<void>;
-  readonly message: (socket: WebSocket, message: NativeWebSocketMessage) => Effect.Effect<void>;
-  readonly close: (socket: WebSocket) => Effect.Effect<void>;
-  readonly error: (socket: WebSocket, error: unknown) => Effect.Effect<void>;
+  readonly accept: (socket: DurableWebSocket) => Effect.Effect<void>;
+  readonly message: (
+    socket: DurableWebSocket,
+    message: NativeWebSocketMessage,
+  ) => Effect.Effect<void>;
+  readonly close: (socket: DurableWebSocket) => Effect.Effect<void>;
+  readonly error: (socket: DurableWebSocket, error: unknown) => Effect.Effect<void>;
 }
 
 interface RpcConnection {
   readonly id: number;
-  readonly socket: WebSocket;
+  readonly socket: DurableWebSocket;
   readonly parser: RpcSerialization.Parser;
 }
 
@@ -64,20 +68,20 @@ export const layer = (options: LayerOptions = {}) =>
         | ((clientId: number, data: RpcMessage.FromClientEncoded) => Effect.Effect<void>)
         | undefined;
 
-      const reserveClientId = (socket: WebSocket) => {
-        const attachment = readAttachment(socket, attachmentKey);
+      const reserveClientId = (socket: DurableWebSocket) => {
+        const attachment = readAttachment(socket.raw, attachmentKey);
         if (attachment !== undefined) {
           nextClientId = Math.max(nextClientId, attachment + 1);
           return attachment;
         }
 
         const id = nextClientId++;
-        writeAttachment(socket, attachmentKey, id);
+        writeAttachment(socket.raw, attachmentKey, id);
         return id;
       };
 
-      const register = (socket: WebSocket) => {
-        const existing = connectionsBySocket.get(socket);
+      const register = (socket: DurableWebSocket) => {
+        const existing = connectionsBySocket.get(socket.raw);
         if (existing !== undefined) {
           return existing;
         }
@@ -88,20 +92,20 @@ export const layer = (options: LayerOptions = {}) =>
           parser: serialization.makeUnsafe(),
         } satisfies RpcConnection;
 
-        connectionsBySocket.set(socket, connection);
+        connectionsBySocket.set(socket.raw, connection);
         connectionsById.set(connection.id, connection);
         clientIds.add(connection.id);
         return connection;
       };
 
-      const unregister = (socket: WebSocket) =>
+      const unregister = (socket: DurableWebSocket) =>
         Effect.sync(() => {
-          const connection = connectionsBySocket.get(socket);
+          const connection = connectionsBySocket.get(socket.raw);
           if (connection === undefined) {
             return;
           }
 
-          connectionsBySocket.delete(socket);
+          connectionsBySocket.delete(socket.raw);
           connectionsById.delete(connection.id);
           clientIds.delete(connection.id);
           Queue.offerUnsafe(disconnects, connection.id);
@@ -116,12 +120,12 @@ export const layer = (options: LayerOptions = {}) =>
           try {
             const encoded = connection.parser.encode(response);
             if (encoded !== undefined) {
-              connection.socket.send(encoded);
+              connection.socket.raw.send(encoded);
             }
           } catch (cause) {
             const encoded = connection.parser.encode(RpcMessage.ResponseDefectEncoded(cause));
             if (encoded !== undefined) {
-              connection.socket.send(encoded);
+              connection.socket.raw.send(encoded);
             }
           }
         });
@@ -138,7 +142,7 @@ export const layer = (options: LayerOptions = {}) =>
           end: (clientId) =>
             Effect.sync(() => {
               const connection = connectionsById.get(clientId);
-              connection?.socket.close();
+              connection?.socket.raw.close();
             }),
           clientIds: Effect.sync(() => clientIds),
           initialMessage: Effect.succeed(Option.none()),

package/src/DurableObjectState.ts

@@ -1,6 +1,7 @@
 import { Cause, Context, Effect, Exit } from "effect";
 
 import { fromDurableObjectStorage, type DurableObjectStorage } from "./DurableObjectStorage";
+import { fromWebSocket, type DurableWebSocket } from "./DurableObjectWebSocket";
 
 /**
  * Effect-friendly wrapper around Cloudflare `DurableObjectState`.
@@ -35,21 +36,21 @@ export interface DurableObjectStateService {
    */
   blockConcurrencyWhileOrReset<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
   /** Accepts a websocket connection for hibernation-capable Durable Objects. */
-  acceptWebSocket(ws: WebSocket, tags?: Array<string>): Effect.Effect<void>;
+  acceptWebSocket(ws: DurableWebSocket, tags?: Array<string>): Effect.Effect<void>;
   /** Lists active sockets, optionally filtered by tag. */
-  getWebSockets(tag?: string): Effect.Effect<Array<WebSocket>>;
+  getWebSockets(tag?: string): Effect.Effect<Array<DurableWebSocket>>;
   /** Configures automatic request/response handling for sockets. */
   setWebSocketAutoResponse(pair?: WebSocketRequestResponsePair): Effect.Effect<void>;
   /** Gets the configured websocket auto-response pair. */
   getWebSocketAutoResponse: Effect.Effect<WebSocketRequestResponsePair | null>;
   /** Timestamp of the last automatic websocket response for a socket. */
-  getWebSocketAutoResponseTimestamp(ws: WebSocket): Effect.Effect<Date | null>;
+  getWebSocketAutoResponseTimestamp(ws: DurableWebSocket): Effect.Effect<Date | null>;
   /** Sets the timeout for hibernatable websocket events. */
   setHibernatableWebSocketEventTimeout(timeoutMs?: number): Effect.Effect<void>;
   /** Gets the timeout for hibernatable websocket events. */
   getHibernatableWebSocketEventTimeout: Effect.Effect<number | null>;
   /** Reads tags attached to a websocket. */
-  getTags(ws: WebSocket): Effect.Effect<Array<string>>;
+  getTags(ws: DurableWebSocket): Effect.Effect<Array<string>>;
   /**
    * Forcibly resets the Durable Object. Cloudflare logs an uncaught Error using
    * the optional reason, and the method is not available in `wrangler dev` local
@@ -97,20 +98,21 @@ export const fromDurableObjectState = (
         ),
       ),
     ),
-  acceptWebSocket: (ws: WebSocket, tags?: Array<string>) =>
-    Effect.sync(() => state.acceptWebSocket(ws, tags)),
-  getWebSockets: (tag?: string) => Effect.sync(() => state.getWebSockets(tag)),
+  acceptWebSocket: (ws: DurableWebSocket, tags?: Array<string>) =>
+    Effect.sync(() => state.acceptWebSocket(ws.raw, tags)),
+  getWebSockets: (tag?: string) =>
+    Effect.sync(() => state.getWebSockets(tag).map((socket) => fromWebSocket(socket))),
   setWebSocketAutoResponse: (pair?: WebSocketRequestResponsePair) =>
     Effect.sync(() => state.setWebSocketAutoResponse(pair)),
   getWebSocketAutoResponse: Effect.sync(() => state.getWebSocketAutoResponse()),
-  getWebSocketAutoResponseTimestamp: (ws: WebSocket) =>
-    Effect.sync(() => state.getWebSocketAutoResponseTimestamp(ws)),
+  getWebSocketAutoResponseTimestamp: (ws: DurableWebSocket) =>
+    Effect.sync(() => state.getWebSocketAutoResponseTimestamp(ws.raw)),
   setHibernatableWebSocketEventTimeout: (timeoutMs?: number) =>
     Effect.sync(() => state.setHibernatableWebSocketEventTimeout(timeoutMs)),
   getHibernatableWebSocketEventTimeout: Effect.sync(() =>
     state.getHibernatableWebSocketEventTimeout(),
   ),
-  getTags: (ws: WebSocket) => Effect.sync(() => state.getTags(ws)),
+  getTags: (ws: DurableWebSocket) => Effect.sync(() => state.getTags(ws.raw)),
   abort: (reason?: string) => Effect.sync(() => state.abort(reason)),
 });
 

package/src/DurableObjectWebSocket.ts

@@ -1,7 +1,82 @@
-import { Effect } from "effect";
+import { Data, Effect, Option, Schema as S } from "effect";
 
 import { DurableObjectState } from "./DurableObjectState";
 
+/** Data supported by Cloudflare websocket `send`. */
+export type DurableWebSocketSendData = string | ArrayBuffer | ArrayBufferView;
+
+/** Error raised when sending on a Durable Object websocket fails. */
+export class DurableWebSocketSendError extends Data.TaggedError("DurableWebSocketSendError")<{
+  readonly cause: unknown;
+}> {}
+
+/** Error raised when closing a Durable Object websocket fails. */
+export class DurableWebSocketCloseError extends Data.TaggedError("DurableWebSocketCloseError")<{
+  readonly cause: unknown;
+}> {}
+
+/** Error raised when serializing or deserializing a websocket attachment fails. */
+export class DurableWebSocketAttachmentError extends Data.TaggedError(
+  "DurableWebSocketAttachmentError",
+)<{
+  readonly operation: "serialize" | "deserialize";
+  readonly cause: unknown;
+}> {}
+
+/** Effect-native wrapper around a hibernatable Durable Object websocket. */
+export interface DurableWebSocket<Attachment = unknown> {
+  /** Underlying Cloudflare websocket. */
+  readonly raw: WebSocket;
+  /** Sends a message through the socket. */
+  send(data: DurableWebSocketSendData): Effect.Effect<void, DurableWebSocketSendError>;
+  /** Closes the socket. */
+  close(code?: number, reason?: string): Effect.Effect<void, DurableWebSocketCloseError>;
+  /** Serializes hibernation attachment metadata onto the socket. */
+  serializeAttachment<A = Attachment>(
+    value: A,
+  ): Effect.Effect<void, DurableWebSocketAttachmentError>;
+  /** Deserializes hibernation attachment metadata from the socket. */
+  readonly deserializeAttachment: Effect.Effect<unknown, DurableWebSocketAttachmentError>;
+}
+
+const wrappers = new WeakMap<WebSocket, DurableWebSocket<unknown>>();
+
+/** Wraps a native Cloudflare websocket in the Effect-native Durable Object API. */
+export const fromWebSocket = <Attachment = unknown>(
+  raw: WebSocket,
+): DurableWebSocket<Attachment> => {
+  const existing = wrappers.get(raw);
+  if (existing !== undefined) {
+    return existing as DurableWebSocket<Attachment>;
+  }
+
+  const socket: DurableWebSocket<unknown> = {
+    raw,
+    send: (data) =>
+      Effect.try({
+        try: () => raw.send(data),
+        catch: (cause) => new DurableWebSocketSendError({ cause }),
+      }),
+    close: (code, reason) =>
+      Effect.try({
+        try: () => raw.close(code, reason),
+        catch: (cause) => new DurableWebSocketCloseError({ cause }),
+      }),
+    serializeAttachment: (value) =>
+      Effect.try({
+        try: () => raw.serializeAttachment(value),
+        catch: (cause) => new DurableWebSocketAttachmentError({ operation: "serialize", cause }),
+      }),
+    deserializeAttachment: Effect.try({
+      try: () => raw.deserializeAttachment(),
+      catch: (cause) => new DurableWebSocketAttachmentError({ operation: "deserialize", cause }),
+    }),
+  };
+
+  wrappers.set(raw, socket);
+  return socket as DurableWebSocket<Attachment>;
+};
+
 /**
  * Options for accepting an incoming websocket request in a Durable Object.
  */
@@ -15,9 +90,9 @@ export interface AcceptUpgradeOptions<Attachment = unknown> {
 /**
  * Result of a websocket upgrade accepted by {@link acceptUpgrade}.
  */
-export interface AcceptedUpgrade {
+export interface AcceptedUpgrade<Attachment = unknown> {
   readonly client: WebSocket;
-  readonly server: WebSocket;
+  readonly server: DurableWebSocket<Attachment>;
   readonly response: Response;
 }
 
@@ -35,15 +110,15 @@ export interface AcceptedUpgrade {
  */
 export const acceptUpgrade = <Attachment = unknown>(
   options: AcceptUpgradeOptions<Attachment> = {},
-): Effect.Effect<AcceptedUpgrade, never, DurableObjectState> =>
+): Effect.Effect<AcceptedUpgrade<Attachment>, never, DurableObjectState> =>
   Effect.gen(function* () {
     const state = yield* DurableObjectState;
     const pair = new WebSocketPair();
     const client = pair[0];
-    const server = pair[1];
+    const server = fromWebSocket<Attachment>(pair[1]);
 
     if (options.attachment !== undefined) {
-      server.serializeAttachment(options.attachment);
+      server.raw.serializeAttachment(options.attachment);
     }
 
     yield* state.acceptWebSocket(
@@ -60,3 +135,137 @@ export const acceptUpgrade = <Attachment = unknown>(
       }),
     };
   });
+
+export type AttachmentInvalidPolicy = "ignore" | "ignore-and-close" | "fail";
+
+export interface AttachmentRehydrateOptions {
+  /** Optional Durable Object websocket tag filter. */
+  readonly tag?: string | undefined;
+  /** Invalid attachment behavior. Defaults to skipping invalid sockets. */
+  readonly onInvalid?: AttachmentInvalidPolicy | undefined;
+}
+
+export interface RehydratedDurableWebSocket<Attachment> {
+  readonly socket: DurableWebSocket<Attachment>;
+  readonly attachment: Attachment;
+}
+
+export interface DurableWebSocketAttachment<Attachment, Encoded> {
+  serialize(
+    socket: DurableWebSocket<unknown>,
+    value: Attachment,
+  ): Effect.Effect<void, DurableWebSocketAttachmentError>;
+  deserialize(
+    socket: DurableWebSocket<unknown>,
+  ): Effect.Effect<Option.Option<Attachment>, DurableWebSocketAttachmentError>;
+  rehydrate(
+    options?: AttachmentRehydrateOptions,
+  ): Effect.Effect<
+    Array<RehydratedDurableWebSocket<Attachment>>,
+    DurableWebSocketAttachmentError,
+    DurableObjectState
+  >;
+  readonly schema: S.Codec<Attachment, Encoded, never, never>;
+}
+
+/** Creates typed attachment helpers for accepted and rehydrated sockets. */
+export const attachment = <const AttachmentSchema extends S.Codec<any, any, never, never>>(
+  schema: AttachmentSchema,
+): DurableWebSocketAttachment<
+  S.Schema.Type<AttachmentSchema>,
+  S.Codec.Encoded<AttachmentSchema>
+> => {
+  type Attachment = S.Schema.Type<AttachmentSchema>;
+  type Encoded = S.Codec.Encoded<AttachmentSchema>;
+
+  const serialize = (socket: DurableWebSocket<unknown>, value: Attachment) =>
+    S.encodeEffect(schema)(value).pipe(
+      Effect.mapError(
+        (cause) => new DurableWebSocketAttachmentError({ operation: "serialize", cause }),
+      ),
+      Effect.flatMap((encoded) => socket.serializeAttachment(encoded as Encoded)),
+    );
+
+  const deserialize = (socket: DurableWebSocket<unknown>) =>
+    Effect.gen(function* () {
+      const value = yield* socket.deserializeAttachment;
+      if (value == null) {
+        return Option.none<Attachment>();
+      }
+
+      return Option.some(
+        yield* S.decodeUnknownEffect(schema)(value).pipe(
+          Effect.mapError(
+            (cause) => new DurableWebSocketAttachmentError({ operation: "deserialize", cause }),
+          ),
+        ),
+      );
+    });
+
+  const rehydrate = (options: AttachmentRehydrateOptions = {}) =>
+    Effect.gen(function* () {
+      const state = yield* DurableObjectState;
+      const sockets = yield* state.getWebSockets(options.tag);
+      const restored: Array<RehydratedDurableWebSocket<Attachment>> = [];
+      const onInvalid = options.onInvalid ?? "ignore";
+
+      for (const socket of sockets) {
+        const decoded = yield* deserialize(socket).pipe(
+          Effect.match({
+            onFailure: (error) => ({ _tag: "Failure" as const, error }),
+            onSuccess: (value) => ({ _tag: "Success" as const, value }),
+          }),
+        );
+
+        if (decoded._tag === "Success" && Option.isSome(decoded.value)) {
+          restored.push({ socket, attachment: decoded.value.value });
+          continue;
+        }
+
+        if (decoded._tag === "Failure" && onInvalid === "fail") {
+          return yield* Effect.fail(decoded.error);
+        }
+
+        if (decoded._tag === "Failure" && onInvalid === "ignore-and-close") {
+          yield* socket.close(1008, "invalid websocket attachment").pipe(Effect.ignore);
+        }
+      }
+
+      return restored;
+    });
+
+  return { serialize, deserialize, rehydrate, schema };
+};
+
+export interface DurableWebSocketHandlers<R = never, E = unknown> {
+  readonly message?: (
+    socket: DurableWebSocket,
+    message: string | ArrayBuffer,
+  ) => Effect.Effect<void, E, R>;
+  readonly close?: (
+    socket: DurableWebSocket,
+    code: number,
+    reason: string,
+    wasClean: boolean,
+  ) => Effect.Effect<void, E, R>;
+  readonly error?: (socket: DurableWebSocket, error: unknown) => Effect.Effect<void, E, R>;
+}
+
+/** Adapts wrapped websocket lifecycle handlers to `DurableObject.make` raw callbacks. */
+export const handlers = <R = never, E = unknown>(options: DurableWebSocketHandlers<R, E>) => ({
+  webSocketMessage:
+    options.message === undefined
+      ? undefined
+      : (socket: WebSocket, message: string | ArrayBuffer) =>
+          options.message?.(fromWebSocket(socket), message) ?? Effect.void,
+  webSocketClose:
+    options.close === undefined
+      ? undefined
+      : (socket: WebSocket, code: number, reason: string, wasClean: boolean) =>
+          options.close?.(fromWebSocket(socket), code, reason, wasClean) ?? Effect.void,
+  webSocketError:
+    options.error === undefined
+      ? undefined
+      : (socket: WebSocket, error: unknown) =>
+          options.error?.(fromWebSocket(socket), error) ?? Effect.void,
+});

package/src/Queue.ts

@@ -0,0 +1,116 @@
+import { Data, Effect, type Scope } from "effect";
+
+import type { ExecutionContext, WorkerContext } from "./Worker";
+import type { WorkerEnvironment } from "./Environment";
+import * as QueueDefinition from "./QueueDefinition";
+
+export interface QueueMessage<Body> {
+  readonly raw: globalThis.Message<unknown>;
+  readonly id: string;
+  readonly timestamp: Date;
+  readonly body: Body;
+  readonly attempts: number;
+  readonly ack: Effect.Effect<void>;
+  readonly retry: (options?: globalThis.QueueRetryOptions) => Effect.Effect<void>;
+}
+
+export interface QueueBatch<Body> {
+  readonly raw: globalThis.MessageBatch<unknown>;
+  readonly messages: ReadonlyArray<QueueMessage<Body>>;
+  readonly queue: string;
+  readonly metadata: globalThis.MessageBatchMetadata;
+  readonly ackAll: Effect.Effect<void>;
+  readonly retryAll: (options?: globalThis.QueueRetryOptions) => Effect.Effect<void>;
+}
+
+export class QueueMessageDecodeError extends Data.TaggedError("QueueMessageDecodeError")<{
+  readonly queue: string;
+  readonly messageId: string;
+  readonly index: number;
+  readonly cause: unknown;
+}> {}
+
+type RuntimeContext<ROut> = ExecutionContext | WorkerContext | WorkerEnvironment | ROut;
+
+type QueueHandlerContext<ROut> = RuntimeContext<ROut> | Scope.Scope;
+
+export type QueueHandler<ROut, Body = unknown> = (
+  batch: QueueBatch<Body>,
+) => Effect.Effect<void, unknown, QueueHandlerContext<ROut>>;
+
+export interface QueueOptions<ROut, Body = unknown> {
+  readonly queue: QueueHandler<ROut, Body>;
+}
+
+export const fromMessage = <Body>(message: globalThis.Message<unknown>, body: Body) => ({
+  raw: message,
+  id: message.id,
+  timestamp: message.timestamp,
+  body,
+  attempts: message.attempts,
+  ack: Effect.sync(() => message.ack()),
+  retry: (options?: globalThis.QueueRetryOptions) => Effect.sync(() => message.retry(options)),
+});
+
+export const fromMessageBatch = <Body>(
+  batch: globalThis.MessageBatch<unknown>,
+  messages: ReadonlyArray<QueueMessage<Body>>,
+): QueueBatch<Body> => ({
+  raw: batch,
+  messages,
+  queue: batch.queue,
+  metadata: batch.metadata,
+  ackAll: Effect.sync(() => batch.ackAll()),
+  retryAll: (options?: globalThis.QueueRetryOptions) => Effect.sync(() => batch.retryAll(options)),
+});
+
+export const decodeBatch = <Body>(
+  batch: globalThis.MessageBatch<unknown>,
+  decodeBody: (body: unknown) => Effect.Effect<Body, unknown>,
+): Effect.Effect<QueueBatch<Body>, QueueMessageDecodeError> =>
+  Effect.gen(function* () {
+    const messages: Array<QueueMessage<Body>> = [];
+
+    for (let index = 0; index < batch.messages.length; index++) {
+      const message = batch.messages[index];
+      const body = yield* decodeBody(message.body).pipe(
+        Effect.mapError(
+          (cause) =>
+            new QueueMessageDecodeError({
+              queue: batch.queue,
+              messageId: message.id,
+              index,
+              cause,
+            }),
+        ),
+      );
+
+      messages.push(fromMessage(message, body));
+    }
+
+    return fromMessageBatch(batch, messages);
+  });
+
+export const Tag = QueueDefinition.Tag;
+
+export const implement = QueueDefinition.implement;
+
+export type Definition<
+  Id extends string = string,
+  Message extends QueueDefinition.Definition.Any["message"] =
+    QueueDefinition.Definition.Any["message"],
+> = QueueDefinition.Definition<Id, Message>;
+
+export namespace Definition {
+  export type Any = QueueDefinition.Definition.Any;
+}
+
+export type Handler<ROut, Self extends QueueDefinition.Definition.Any> = QueueDefinition.Handler<
+  ROut,
+  Self
+>;
+
+export type Options<ROut, Self extends QueueDefinition.Definition.Any> = QueueDefinition.Options<
+  ROut,
+  Self
+>;

package/src/QueueBinding.ts

@@ -0,0 +1,131 @@
+import { Data, Effect, Schema as S } from "effect";
+
+import * as Binding from "./Binding";
+import type * as RpcDefinition from "./RpcDefinition";
+
+const TypeId = "effect-cf/QueueBinding" as const;
+
+export type QueueSendOptions = globalThis.QueueSendOptions;
+export type QueueSendResponse = globalThis.QueueSendResponse;
+export type QueueSendBatchOptions = globalThis.QueueSendBatchOptions;
+export type QueueSendBatchResponse = globalThis.QueueSendBatchResponse;
+export type QueueMetrics = globalThis.QueueMetrics;
+export type MessageSendRequest<Body> = globalThis.MessageSendRequest<Body>;
+
+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;
+}
+
+declare const QueueServiceTypeId: unique symbol;
+
+/** Nominal service marker for Queue services created with {@link make}. */
+export interface QueueService<Id extends string, Message extends RpcDefinition.ServiceFreeSchema> {
+  readonly [QueueServiceTypeId]: {
+    readonly id: Id;
+    readonly message: S.Schema.Type<Message>;
+    readonly encodedMessage: S.Codec.Encoded<Message>;
+  };
+}
+
+export class QueueOperationError extends Data.TaggedError("QueueOperationError")<{
+  readonly binding: string;
+  readonly operation: string;
+  readonly cause: unknown;
+}> {}
+
+const queueError = (binding: string, operation: string, cause: unknown) =>
+  new QueueOperationError({ binding, operation, cause });
+
+const tryQueuePromise = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => Promise<A>,
+): Effect.Effect<A, QueueOperationError> =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => queueError(binding, operation, cause),
+  });
+
+const isQueue = <Body>(value: unknown): value is globalThis.Queue<Body> => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const resource = value as Record<string, unknown>;
+
+  return (
+    typeof resource.send === "function" &&
+    typeof resource.sendBatch === "function" &&
+    typeof resource.metrics === "function"
+  );
+};
+
+/** Creates a typed Queue binding service tag plus Effect helpers. */
+export const make = <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
+  id: Id,
+  definition: QueueBindingDefinition<Message>,
+) => Service<QueueService<Id, Message>>()<Id, Message>(id, definition);
+
+/**
+ * Builds an Effect service around a Cloudflare Queue producer binding.
+ */
+export const Service =
+  <Self>() =>
+  <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
+    id: Id,
+    definition: QueueBindingDefinition<Message>,
+  ) => {
+    type Body = S.Schema.Type<Message>;
+    type EncodedBody = S.Codec.Encoded<Message>;
+
+    const tag = Binding.Service<Self>()(
+      id,
+      definition.binding,
+      (value): value is globalThis.Queue<EncodedBody> => isQueue<EncodedBody>(value),
+    );
+
+    const encodeMessage = S.encodeEffect(definition.message);
+
+    const send = Effect.fnUntraced(function* (message: Body, options?: QueueSendOptions) {
+      const queue = yield* tag;
+      const encoded = yield* encodeMessage(message);
+
+      return yield* tryQueuePromise(definition.binding, "send", () => queue.send(encoded, options));
+    });
+
+    const sendBatch = Effect.fnUntraced(function* (
+      messages: Iterable<MessageSendRequest<Body>>,
+      options?: QueueSendBatchOptions,
+    ) {
+      const queue = yield* tag;
+      const encodedMessages: Array<MessageSendRequest<EncodedBody>> = [];
+
+      for (const message of messages) {
+        encodedMessages.push({
+          ...message,
+          body: yield* encodeMessage(message.body),
+        });
+      }
+
+      return yield* tryQueuePromise(definition.binding, "sendBatch", () =>
+        queue.sendBatch(encodedMessages, options),
+      );
+    });
+
+    const metrics = Effect.fnUntraced(function* () {
+      const queue = yield* tag;
+
+      return yield* tryQueuePromise(definition.binding, "metrics", () => queue.metrics());
+    });
+
+    return Object.assign(tag, {
+      [TypeId]: TypeId,
+      binding: definition.binding,
+      send,
+      sendBatch,
+      metrics,
+    });
+  };