effect-cf 0.46.1 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # effect-cf
 
+## 0.48.0
+
+### Minor Changes
+
+- [#192](https://github.com/danieljvdm/effect-cf/pull/192) [`761c4f4`](https://github.com/danieljvdm/effect-cf/commit/761c4f411e11ae0491f61c6fe7c7697faf68e7f0) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Report absent Artifacts commits as `ArtifactsOperationError` with `NOT_FOUND` instead of succeeding with `null`. Correct the raw `ArtifactsRepoBinding.readCommit` return type to include `null`; the Effect client continues to return a commit or a typed failure.
+
+## 0.47.0
+
+### Minor Changes
+
+- [#190](https://github.com/danieljvdm/effect-cf/pull/190) [`a3ae008`](https://github.com/danieljvdm/effect-cf/commit/a3ae008af959d08eec649042edc9309982354a0d) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add `RpcWebSocketClient.layer` and the browser-safe `effect-cf/rpc-websocket-client` entrypoint. Provide a typed client service and its WebSocket connection for an application or session without requiring callers to wrap client construction in `Effect.scoped`. The layer closes the connection when its lifetime ends.
+
+  Persist the RPC serializer's content type in Durable Object WebSocket attachments and reset restored connections whose saved content type differs from the server's, preventing incompatible frames from reaching RPC handlers after a deployment. Existing attachments without serializer metadata remain supported.
+
+  Acknowledge WebSocket close events and ignore late messages on closed connections so client scope cleanup completes the close handshake.
+
 ## 0.46.1
 
 ### Patch Changes

package/README.md

@@ -10,6 +10,8 @@ The repository tests against workerd `1.20260825.1` and `@cloudflare/workers-typ
 
 See the [runtime performance guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/runtime-performance.md) for measured alarm batching and telemetry configuration guidance.
 
+For typed WebSocket RPC clients whose connection lifetime is owned by an Effect layer, see the [WebSocket RPC guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/websocket-rpc.md).
+
 ## Worker
 
 ```ts

package/dist/Artifacts.d.mts

@@ -145,7 +145,7 @@ interface ArtifactsRepoBinding extends Partial<ArtifactsRepoInfo> {
   readonly revokeToken: (tokenOrId: string) => Promise<boolean>;
   readonly fork: (name: RepoName, options?: ArtifactsForkOptions) => Promise<ArtifactsCreateRepoResult>;
   readonly log: (options?: ArtifactsLogOptions) => Promise<ArtifactsLogResult>;
-  readonly readCommit: (hash: string) => Promise<ArtifactsCommit>;
+  readonly readCommit: (hash: string) => Promise<ArtifactsCommit | null>;
   readonly readTree: (hash: string) => Promise<ArtifactsTree>;
 }
 interface ArtifactsBinding {

package/dist/Artifacts.mjs

@@ -105,7 +105,17 @@ const wrapRepo = (binding, repo, info) => ({
 	revokeToken: Effect.fn("Artifacts.revokeToken", spanOptions(binding, "revokeToken"))((tokenOrId) => tryArtifactsPromise(binding, "revokeToken", () => repo.revokeToken(tokenOrId))),
 	fork: Effect.fn("Artifacts.fork", spanOptions(binding, "fork"))((name, options) => tryArtifactsPromise(binding, "fork", () => repo.fork(name, options))),
 	log: Effect.fn("Artifacts.log", spanOptions(binding, "log"))((options) => tryArtifactsPromise(binding, "log", () => repo.log(options))),
-	readCommit: Effect.fn("Artifacts.readCommit", spanOptions(binding, "readCommit"))((hash) => tryArtifactsPromise(binding, "readCommit", () => repo.readCommit(hash))),
+	readCommit: Effect.fn("Artifacts.readCommit", spanOptions(binding, "readCommit"))(function* (hash) {
+		const commit = yield* tryArtifactsPromise(binding, "readCommit", () => repo.readCommit(hash));
+		if (commit === null) return yield* new ArtifactsOperationError({
+			binding,
+			operation: "readCommit",
+			code: "NOT_FOUND",
+			numericCode: artifactsErrorNumericCodes.NOT_FOUND,
+			cause: /* @__PURE__ */ new Error("Commit not found")
+		});
+		return commit;
+	}),
 	readTree: Effect.fn("Artifacts.readTree", spanOptions(binding, "readTree"))((hash) => tryArtifactsPromise(binding, "readTree", () => repo.readTree(hash))),
 	raw: repo
 });

package/dist/DurableObjectRpcWebSocket.mjs

@@ -40,7 +40,8 @@ const ResumableAttachmentMetadataSchema = Schema.Struct({
 	clientId: Schema.Finite,
 	hasPendingRequests: Schema.Boolean,
 	hasNonResumableRequests: Schema.Boolean,
-	subscriptions: Schema.Array(PersistedSubscriptionSchema)
+	subscriptions: Schema.Array(PersistedSubscriptionSchema),
+	serialization: Schema.optionalKey(Schema.String)
 });
 const decodeResumableAttachment = Schema.decodeUnknownOption(ResumableAttachmentMetadataSchema);
 var DurableObjectRpcWebSocket = class extends Context.Service()("effect-cf/DurableObjectRpcWebSocket") {};
@@ -83,7 +84,8 @@ const layer = (options = {}) => Layer.effectContext(Effect.gen(function* () {
 		const created = {
 			version: legacyAttachmentVersion,
 			clientId: id,
-			hasPendingRequests: false
+			hasPendingRequests: false,
+			serialization: serialization.contentType
 		};
 		writeAttachment(socket.raw, attachmentKey, created);
 		return created;
@@ -143,7 +145,8 @@ const layer = (options = {}) => Layer.effectContext(Effect.gen(function* () {
 					writeAttachment(connection.socket.raw, attachmentKey, {
 						version: legacyAttachmentVersion,
 						clientId: connection.id,
-						hasPendingRequests: connection.requestIds.size > 0
+						hasPendingRequests: connection.requestIds.size > 0,
+						serialization: serialization.contentType
 					});
 					return;
 				}
@@ -153,7 +156,8 @@ const layer = (options = {}) => Layer.effectContext(Effect.gen(function* () {
 					clientId: connection.id,
 					hasPendingRequests: connection.requestIds.size > 0,
 					hasNonResumableRequests: connection.nonResumableRequestIds.size > 0,
-					subscriptions
+					subscriptions,
+					serialization: serialization.contentType
 				});
 			},
 			catch: (cause) => new DurableWebSocketAttachmentError({
@@ -249,6 +253,10 @@ const layer = (options = {}) => Layer.effectContext(Effect.gen(function* () {
 			continue;
 		}
 		const metadata = attachment.metadata;
+		if (metadata.serialization !== void 0 && metadata.serialization !== serialization.contentType) {
+			yield* resetSocket(socket);
+			continue;
+		}
 		if (metadata.version === legacyAttachmentVersion) {
 			if (metadata.hasPendingRequests) yield* resetSocket(socket);
 			else if (connectionsById.has(metadata.clientId)) yield* resetSocket(socket);
@@ -476,7 +484,10 @@ const layer = (options = {}) => Layer.effectContext(Effect.gen(function* () {
 			const connection = register(socket);
 			return Predicate.isTagged(cause, "MaxBufferSizeExceeded") ? Effect.ignore(connection.socket.close(1009, String(cause))) : send(connection, RpcMessage.ResponseDefectEncoded(encodeDefect(cause)));
 		})),
-		close: unregister,
+		close: (socket) => Effect.gen(function* () {
+			resetSockets.add(socket.raw);
+			yield* socket.close(1e3).pipe(Effect.ignore);
+		}).pipe(Effect.ensuring(unregister(socket)), Effect.uninterruptible),
 		error: resetSocket,
 		checkpoint
 	});
@@ -506,12 +517,14 @@ const readAttachment = (socket, key) => {
 		} : { _tag: "Invalid" };
 	}
 	const hasPendingRequests = Predicate.hasProperty(metadata, "hasPendingRequests") ? metadata.hasPendingRequests : false;
-	if ((!Predicate.hasProperty(metadata, "version") || metadata.version === legacyAttachmentVersion) && Predicate.hasProperty(metadata, "clientId") && Predicate.isNumber(metadata.clientId) && isClientId(metadata.clientId) && Predicate.isBoolean(hasPendingRequests)) return {
+	const serialization = Predicate.hasProperty(metadata, "serialization") ? metadata.serialization : void 0;
+	if ((!Predicate.hasProperty(metadata, "version") || metadata.version === legacyAttachmentVersion) && Predicate.hasProperty(metadata, "clientId") && Predicate.isNumber(metadata.clientId) && isClientId(metadata.clientId) && Predicate.isBoolean(hasPendingRequests) && (serialization === void 0 || Predicate.isString(serialization))) return {
 		_tag: "Valid",
 		metadata: {
 			version: legacyAttachmentVersion,
 			clientId: metadata.clientId,
-			hasPendingRequests
+			hasPendingRequests,
+			serialization
 		}
 	};
 	return { _tag: "Invalid" };

package/dist/RpcWebSocketClient.d.mts

@@ -0,0 +1,30 @@
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as Socket from "effect/unstable/socket/Socket";
+import * as Rpc from "effect/unstable/rpc/Rpc";
+import { RpcClientError } from "effect/unstable/rpc/RpcClientError";
+import * as RpcGroup from "effect/unstable/rpc/RpcGroup";
+declare namespace RpcWebSocketClient_d_exports {
+  export { LayerOptions, layer };
+}
+interface LayerOptions {
+  readonly socket?: Parameters<typeof Socket.layerWebSocket>[1];
+  readonly protocol?: Parameters<typeof RpcClient.layerProtocolSocket>[0];
+  readonly client?: Omit<NonNullable<Parameters<typeof RpcClient.make>[1]>, "flatten">;
+  /** Must match the server's serialization. Defaults to Effect RPC JSON. */
+  readonly serialization?: RpcSerialization.RpcSerialization["Service"] | undefined;
+}
+/**
+ * Provides a typed RPC client and its WebSocket transport for the layer's lifetime.
+ * Callers yield the service without supplying a Scope. Provide this layer once
+ * around the application or session to share the connection across calls.
+ *
+ * Provide Socket.layerWebSocketConstructorGlobal in browsers, or a platform's
+ * WebSocketConstructor layer elsewhere. Streaming RPCs returned as queues still
+ * require a consumer scope; ordinary Stream operations manage their own scopes.
+ */
+declare const layer: <I, Rpcs extends Rpc.Any>(service: Context.Key<I, RpcClient.RpcClient<Rpcs, RpcClientError>>, group: RpcGroup.RpcGroup<Rpcs>, url: Parameters<typeof Socket.layerWebSocket>[0], options?: LayerOptions) => Layer.Layer<I, never, Socket.WebSocketConstructor | Rpc.MiddlewareClient<Rpcs>>;
+//#endregion
+export { LayerOptions, RpcWebSocketClient_d_exports, layer };

package/dist/RpcWebSocketClient.mjs

@@ -0,0 +1,19 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import * as Layer from "effect/Layer";
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as Socket from "effect/unstable/socket/Socket";
+//#region src/RpcWebSocketClient.ts
+var RpcWebSocketClient_exports = /* @__PURE__ */ __exportAll({ layer: () => layer });
+/**
+* Provides a typed RPC client and its WebSocket transport for the layer's lifetime.
+* Callers yield the service without supplying a Scope. Provide this layer once
+* around the application or session to share the connection across calls.
+*
+* Provide Socket.layerWebSocketConstructorGlobal in browsers, or a platform's
+* WebSocketConstructor layer elsewhere. Streaming RPCs returned as queues still
+* require a consumer scope; ordinary Stream operations manage their own scopes.
+*/
+const layer = (service, group, url, options = {}) => Layer.effect(service, RpcClient.make(group, options.client)).pipe(Layer.provide(RpcClient.layerProtocolSocket(options.protocol).pipe(Layer.provide(Socket.layerWebSocket(url, options.socket)), Layer.provide(Layer.succeed(RpcSerialization.RpcSerialization, options.serialization ?? RpcSerialization.json)))));
+//#endregion
+export { RpcWebSocketClient_exports, layer };

package/dist/index.d.mts

@@ -14,6 +14,7 @@ import { ServiceBinding_d_exports } from "./ServiceBinding.mjs";
 import { Worker_d_exports } from "./Worker.mjs";
 import { DurableObjectState_d_exports } from "./DurableObjectState.mjs";
 import { Hyperdrive_d_exports } from "./Hyperdrive.mjs";
+import { RpcWebSocketClient_d_exports } from "./RpcWebSocketClient.mjs";
 import { ContainerNamespace_d_exports } from "./ContainerNamespace.mjs";
 import { WorkflowBinding_d_exports } from "./WorkflowBinding.mjs";
 import { WorkersAi_d_exports } from "./WorkersAi.mjs";
@@ -39,4 +40,4 @@ import { Vectorize_d_exports } from "./Vectorize.mjs";
 import { WebTransport_d_exports } from "./WebTransport.mjs";
 import { WorkflowDefinition_d_exports } from "./WorkflowDefinition.mjs";
 import { Workflow_d_exports } from "./Workflow.mjs";
-export { AiGateway_d_exports as AiGateway, AnalyticsEngine_d_exports as AnalyticsEngine, Artifacts_d_exports as Artifacts, Binding_d_exports as Binding, BrowserRendering_d_exports as BrowserRendering, Cache_d_exports as Cache, CloudflareOtlp_d_exports as CloudflareOtlp, CloudflareTracer_d_exports as CloudflareTracer, ContainerNamespace_d_exports as ContainerNamespace, D1_d_exports as D1, DurableObject_d_exports as DurableObject, DurableObjectAlarm_d_exports as DurableObjectAlarm, DurableObjectDefinition_d_exports as DurableObjectDefinition, DurableObjectNamespace_d_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_d_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_d_exports as DurableObjectSqlite, DurableObjectState_d_exports as DurableObjectState, DurableObjectStorage_d_exports as DurableObjectStorage, DurableObjectWebSocket_d_exports as DurableObjectWebSocket, Email_d_exports as Email, Environment_d_exports as Environment, Hyperdrive_d_exports as Hyperdrive, Images_d_exports as Images, Kv_d_exports as Kv, Queue_d_exports as Queue, QueueBinding_d_exports as QueueBinding, QueueDefinition_d_exports as QueueDefinition, R2_d_exports as R2, Rpc_d_exports as Rpc, RpcDefinition_d_exports as RpcDefinition, RpcTargets_d_exports as RpcTargets, RpcTracing_d_exports as RpcTracing, ServiceBinding_d_exports as ServiceBinding, Vectorize_d_exports as Vectorize, WebTransport_d_exports as WebTransport, Worker_d_exports as Worker, WorkerConfig, WorkerDefinition_d_exports as WorkerDefinition, type WorkerEnv, WorkerEnvironment, WorkersAi_d_exports as WorkersAi, Workflow_d_exports as Workflow, WorkflowBinding_d_exports as WorkflowBinding, WorkflowDefinition_d_exports as WorkflowDefinition };
+export { AiGateway_d_exports as AiGateway, AnalyticsEngine_d_exports as AnalyticsEngine, Artifacts_d_exports as Artifacts, Binding_d_exports as Binding, BrowserRendering_d_exports as BrowserRendering, Cache_d_exports as Cache, CloudflareOtlp_d_exports as CloudflareOtlp, CloudflareTracer_d_exports as CloudflareTracer, ContainerNamespace_d_exports as ContainerNamespace, D1_d_exports as D1, DurableObject_d_exports as DurableObject, DurableObjectAlarm_d_exports as DurableObjectAlarm, DurableObjectDefinition_d_exports as DurableObjectDefinition, DurableObjectNamespace_d_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_d_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_d_exports as DurableObjectSqlite, DurableObjectState_d_exports as DurableObjectState, DurableObjectStorage_d_exports as DurableObjectStorage, DurableObjectWebSocket_d_exports as DurableObjectWebSocket, Email_d_exports as Email, Environment_d_exports as Environment, Hyperdrive_d_exports as Hyperdrive, Images_d_exports as Images, Kv_d_exports as Kv, Queue_d_exports as Queue, QueueBinding_d_exports as QueueBinding, QueueDefinition_d_exports as QueueDefinition, R2_d_exports as R2, Rpc_d_exports as Rpc, RpcDefinition_d_exports as RpcDefinition, RpcTargets_d_exports as RpcTargets, RpcTracing_d_exports as RpcTracing, RpcWebSocketClient_d_exports as RpcWebSocketClient, ServiceBinding_d_exports as ServiceBinding, Vectorize_d_exports as Vectorize, WebTransport_d_exports as WebTransport, Worker_d_exports as Worker, WorkerConfig, WorkerDefinition_d_exports as WorkerDefinition, type WorkerEnv, WorkerEnvironment, WorkersAi_d_exports as WorkersAi, Workflow_d_exports as Workflow, WorkflowBinding_d_exports as WorkflowBinding, WorkflowDefinition_d_exports as WorkflowDefinition };

package/dist/index.mjs

@@ -34,9 +34,10 @@ import { Hyperdrive_exports } from "./Hyperdrive.mjs";
 import { Images_exports } from "./Images.mjs";
 import { Kv_exports } from "./Kv.mjs";
 import { R2_exports } from "./R2.mjs";
+import { RpcWebSocketClient_exports } from "./RpcWebSocketClient.mjs";
 import { Vectorize_exports } from "./Vectorize.mjs";
 import { WebTransport_exports } from "./WebTransport.mjs";
 import { WorkflowBinding_exports } from "./WorkflowBinding.mjs";
 import { WorkflowDefinition_exports } from "./WorkflowDefinition.mjs";
 import { Workflow_exports } from "./Workflow.mjs";
-export { AiGateway_exports as AiGateway, AnalyticsEngine_exports as AnalyticsEngine, Artifacts_exports as Artifacts, Binding_exports as Binding, BrowserRendering_exports as BrowserRendering, Cache_exports as Cache, CloudflareOtlp_exports as CloudflareOtlp, CloudflareTracer_exports as CloudflareTracer, ContainerNamespace_exports as ContainerNamespace, D1_exports as D1, DurableObject_exports as DurableObject, DurableObjectAlarm_exports as DurableObjectAlarm, DurableObjectDefinition_exports as DurableObjectDefinition, DurableObjectNamespace_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_exports as DurableObjectSqlite, DurableObjectState_exports as DurableObjectState, DurableObjectStorage_exports as DurableObjectStorage, DurableObjectWebSocket_exports as DurableObjectWebSocket, Email_exports as Email, Environment_exports as Environment, Hyperdrive_exports as Hyperdrive, Images_exports as Images, Kv_exports as Kv, Queue_exports as Queue, QueueBinding_exports as QueueBinding, QueueDefinition_exports as QueueDefinition, R2_exports as R2, Rpc_exports as Rpc, RpcDefinition_exports as RpcDefinition, RpcTargets_exports as RpcTargets, RpcTracing_exports as RpcTracing, ServiceBinding_exports as ServiceBinding, Vectorize_exports as Vectorize, WebTransport_exports as WebTransport, Worker_exports as Worker, WorkerConfig, WorkerDefinition_exports as WorkerDefinition, WorkerEnvironment, WorkersAi_exports as WorkersAi, Workflow_exports as Workflow, WorkflowBinding_exports as WorkflowBinding, WorkflowDefinition_exports as WorkflowDefinition };
+export { AiGateway_exports as AiGateway, AnalyticsEngine_exports as AnalyticsEngine, Artifacts_exports as Artifacts, Binding_exports as Binding, BrowserRendering_exports as BrowserRendering, Cache_exports as Cache, CloudflareOtlp_exports as CloudflareOtlp, CloudflareTracer_exports as CloudflareTracer, ContainerNamespace_exports as ContainerNamespace, D1_exports as D1, DurableObject_exports as DurableObject, DurableObjectAlarm_exports as DurableObjectAlarm, DurableObjectDefinition_exports as DurableObjectDefinition, DurableObjectNamespace_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_exports as DurableObjectSqlite, DurableObjectState_exports as DurableObjectState, DurableObjectStorage_exports as DurableObjectStorage, DurableObjectWebSocket_exports as DurableObjectWebSocket, Email_exports as Email, Environment_exports as Environment, Hyperdrive_exports as Hyperdrive, Images_exports as Images, Kv_exports as Kv, Queue_exports as Queue, QueueBinding_exports as QueueBinding, QueueDefinition_exports as QueueDefinition, R2_exports as R2, Rpc_exports as Rpc, RpcDefinition_exports as RpcDefinition, RpcTargets_exports as RpcTargets, RpcTracing_exports as RpcTracing, RpcWebSocketClient_exports as RpcWebSocketClient, ServiceBinding_exports as ServiceBinding, Vectorize_exports as Vectorize, WebTransport_exports as WebTransport, Worker_exports as Worker, WorkerConfig, WorkerDefinition_exports as WorkerDefinition, WorkerEnvironment, WorkersAi_exports as WorkersAi, Workflow_exports as Workflow, WorkflowBinding_exports as WorkflowBinding, WorkflowDefinition_exports as WorkflowDefinition };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.46.1",
+  "version": "0.48.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {
@@ -57,6 +57,11 @@
       "import": "./dist/Vitest.mjs",
       "default": "./dist/Vitest.mjs"
     },
+    "./rpc-websocket-client": {
+      "types": "./dist/RpcWebSocketClient.d.mts",
+      "import": "./dist/RpcWebSocketClient.mjs",
+      "default": "./dist/RpcWebSocketClient.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/Artifacts.ts

@@ -222,7 +222,7 @@ export interface ArtifactsRepoBinding extends Partial<ArtifactsRepoInfo> {
     options?: ArtifactsForkOptions,
   ) => Promise<ArtifactsCreateRepoResult>;
   readonly log: (options?: ArtifactsLogOptions) => Promise<ArtifactsLogResult>;
-  readonly readCommit: (hash: string) => Promise<ArtifactsCommit>;
+  readonly readCommit: (hash: string) => Promise<ArtifactsCommit | null>;
   readonly readTree: (hash: string) => Promise<ArtifactsTree>;
 }
 
@@ -451,7 +451,20 @@ const wrapRepo = (
   readCommit: Effect.fn(
     "Artifacts.readCommit",
     spanOptions(binding, "readCommit"),
-  )((hash: string) => tryArtifactsPromise(binding, "readCommit", () => repo.readCommit(hash))),
+  )(function* (hash: string) {
+    const commit = yield* tryArtifactsPromise(binding, "readCommit", () => repo.readCommit(hash));
+
+    if (commit === null)
+      return yield* new ArtifactsOperationError({
+        binding,
+        operation: "readCommit",
+        code: "NOT_FOUND",
+        numericCode: artifactsErrorNumericCodes.NOT_FOUND,
+        cause: new Error("Commit not found"),
+      });
+
+    return commit;
+  }),
   readTree: Effect.fn(
     "Artifacts.readTree",
     spanOptions(binding, "readTree"),

package/src/DurableObjectRpcWebSocket.ts

@@ -148,6 +148,7 @@ interface LegacyAttachmentMetadata {
   readonly version: 1;
   readonly clientId: number;
   readonly hasPendingRequests: boolean;
+  readonly serialization?: string | undefined;
 }
 
 interface PersistedPendingBatch {
@@ -170,6 +171,7 @@ interface ResumableAttachmentMetadata {
   readonly hasPendingRequests: boolean;
   readonly hasNonResumableRequests: boolean;
   readonly subscriptions: ReadonlyArray<PersistedSubscription>;
+  readonly serialization?: string | undefined;
 }
 
 type AttachmentMetadata = LegacyAttachmentMetadata | ResumableAttachmentMetadata;
@@ -200,6 +202,7 @@ const ResumableAttachmentMetadataSchema = Schema.Struct({
   hasPendingRequests: Schema.Boolean,
   hasNonResumableRequests: Schema.Boolean,
   subscriptions: Schema.Array(PersistedSubscriptionSchema),
+  serialization: Schema.optionalKey(Schema.String),
 });
 
 const decodeResumableAttachment = Schema.decodeUnknownOption(ResumableAttachmentMetadataSchema);
@@ -279,6 +282,7 @@ export const layer = (
           version: legacyAttachmentVersion,
           clientId: id,
           hasPendingRequests: false,
+          serialization: serialization.contentType,
         };
 
         writeAttachment(socket.raw, attachmentKey, created);
@@ -392,6 +396,7 @@ export const layer = (
                 version: legacyAttachmentVersion,
                 clientId: connection.id,
                 hasPendingRequests: connection.requestIds.size > 0,
+                serialization: serialization.contentType,
               });
 
               return;
@@ -407,6 +412,7 @@ export const layer = (
               hasPendingRequests: connection.requestIds.size > 0,
               hasNonResumableRequests: connection.nonResumableRequestIds.size > 0,
               subscriptions,
+              serialization: serialization.contentType,
             });
           },
           catch: (cause) => new DurableWebSocketAttachmentError({ operation: "serialize", cause }),
@@ -589,6 +595,14 @@ export const layer = (
 
         const metadata = attachment.metadata;
 
+        if (
+          metadata.serialization !== undefined &&
+          metadata.serialization !== serialization.contentType
+        ) {
+          yield* resetSocket(socket);
+          continue;
+        }
+
         if (metadata.version === legacyAttachmentVersion) {
           if (metadata.hasPendingRequests) {
             yield* resetSocket(socket);
@@ -1036,7 +1050,11 @@ export const layer = (
                 : send(connection, RpcMessage.ResponseDefectEncoded(encodeDefect(cause)));
             }),
           ),
-        close: unregister,
+        close: (socket) =>
+          Effect.gen(function* () {
+            resetSockets.add(socket.raw);
+            yield* socket.close(1000).pipe(Effect.ignore);
+          }).pipe(Effect.ensuring(unregister(socket)), Effect.uninterruptible),
         error: resetSocket,
         checkpoint,
       });
@@ -1102,13 +1120,17 @@ const readAttachment = (socket: WebSocket, key: string): AttachmentRead => {
   const hasPendingRequests = Predicate.hasProperty(metadata, "hasPendingRequests")
     ? metadata.hasPendingRequests
     : false;
+  const serialization = Predicate.hasProperty(metadata, "serialization")
+    ? metadata.serialization
+    : undefined;
 
   if (
     (!Predicate.hasProperty(metadata, "version") || metadata.version === legacyAttachmentVersion) &&
     Predicate.hasProperty(metadata, "clientId") &&
     Predicate.isNumber(metadata.clientId) &&
     isClientId(metadata.clientId) &&
-    Predicate.isBoolean(hasPendingRequests)
+    Predicate.isBoolean(hasPendingRequests) &&
+    (serialization === undefined || Predicate.isString(serialization))
   ) {
     return {
       _tag: "Valid",
@@ -1116,6 +1138,7 @@ const readAttachment = (socket: WebSocket, key: string): AttachmentRead => {
         version: legacyAttachmentVersion,
         clientId: metadata.clientId,
         hasPendingRequests,
+        serialization,
       },
     };
   }

package/src/RpcWebSocketClient.ts

@@ -0,0 +1,45 @@
+import type * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import type * as Rpc from "effect/unstable/rpc/Rpc";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import type { RpcClientError } from "effect/unstable/rpc/RpcClientError";
+import type * as RpcGroup from "effect/unstable/rpc/RpcGroup";
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
+import * as Socket from "effect/unstable/socket/Socket";
+
+export interface LayerOptions {
+  readonly socket?: Parameters<typeof Socket.layerWebSocket>[1];
+  readonly protocol?: Parameters<typeof RpcClient.layerProtocolSocket>[0];
+  readonly client?: Omit<NonNullable<Parameters<typeof RpcClient.make>[1]>, "flatten">;
+  /** Must match the server's serialization. Defaults to Effect RPC JSON. */
+  readonly serialization?: RpcSerialization.RpcSerialization["Service"] | undefined;
+}
+
+/**
+ * Provides a typed RPC client and its WebSocket transport for the layer's lifetime.
+ * Callers yield the service without supplying a Scope. Provide this layer once
+ * around the application or session to share the connection across calls.
+ *
+ * Provide Socket.layerWebSocketConstructorGlobal in browsers, or a platform's
+ * WebSocketConstructor layer elsewhere. Streaming RPCs returned as queues still
+ * require a consumer scope; ordinary Stream operations manage their own scopes.
+ */
+export const layer = <I, Rpcs extends Rpc.Any>(
+  service: Context.Key<I, RpcClient.RpcClient<Rpcs, RpcClientError>>,
+  group: RpcGroup.RpcGroup<Rpcs>,
+  url: Parameters<typeof Socket.layerWebSocket>[0],
+  options: LayerOptions = {},
+): Layer.Layer<I, never, Socket.WebSocketConstructor | Rpc.MiddlewareClient<Rpcs>> =>
+  Layer.effect(service, RpcClient.make(group, options.client)).pipe(
+    Layer.provide(
+      RpcClient.layerProtocolSocket(options.protocol).pipe(
+        Layer.provide(Socket.layerWebSocket(url, options.socket)),
+        Layer.provide(
+          Layer.succeed(
+            RpcSerialization.RpcSerialization,
+            options.serialization ?? RpcSerialization.json,
+          ),
+        ),
+      ),
+    ),
+  );

package/src/index.ts

@@ -30,6 +30,7 @@ export * as Rpc from "./Rpc";
 export * as RpcDefinition from "./RpcDefinition";
 export * as RpcTracing from "./RpcTracing";
 export * as RpcTargets from "./RpcTargets";
+export * as RpcWebSocketClient from "./RpcWebSocketClient";
 export * as ServiceBinding from "./ServiceBinding";
 export * as Vectorize from "./Vectorize";
 export * as WebTransport from "./WebTransport";