add changelog for web_socket_auto_reply_to_close (#28887)

* add changelog for web_socket_auto_reply_to_close

* Apply suggestions from code review

Co-authored-by: Kenton Varda <kenton@cloudflare.com>

* replace changelog with compat-flag entry

* update websocket/do documentation

---------

Co-authored-by: Kenton Varda <kenton@cloudflare.com>

Author: anonrig

src/content/compatibility-flags/web-socket-auto-reply-to-close.md

@@ -0,0 +1,67 @@
+---
+_build:
+  publishResources: false
+  render: never
+  list: never
+
+name: "WebSocket auto-reply to close"
+sort_date: "2026-03-10"
+enable_date: "2026-04-07"
+enable_flag: "web_socket_auto_reply_to_close"
+disable_flag: "web_socket_manual_reply_to_close"
+---
+
+When a server sends a WebSocket Close frame, the Workers runtime now automatically sends a reciprocal Close frame and transitions `readyState` to `CLOSED` before firing the `close` event. This matches the [WebSocket spec](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close_event) and browser behavior.
+
+Previously, receiving a server-initiated Close frame left the WebSocket in `CLOSING` and required the application to call `close()` itself. With this flag active, you no longer need to call `close()` in your `close` event handler. The runtime handles the close handshake automatically.
+
+```js
+const [client, server] = Object.values(new WebSocketPair());
+server.accept();
+
+server.addEventListener("close", (event) => {
+  // readyState is already CLOSED — no need to call server.close().
+  console.log(server.readyState); // WebSocket.CLOSED
+  console.log(event.code); // 1000
+  console.log(event.wasClean); // true
+}, { once: true });
+```
+
+If you do still call `close()` inside the handler, the call is silently ignored. This means existing code that manually replies to Close frames will not break when you update your compatibility date.
+
+The automatic close behavior can interfere with WebSocket proxying. When a Worker proxies between a client and a backend, the old behavior allowed the Worker to observe a backend Close frame without the runtime tearing down the connection, giving the Worker time to coordinate a clean close on the client side. To support this pattern, the `accept()` method now accepts an option `allowHalfOpen`. Call `ws.accept({ allowHalfOpen: true })` to restore the old half-open behavior regardless of the compatibility flag.
+
+```js
+const [client, server] = Object.values(new WebSocketPair());
+
+// Opt into half-open mode for proxying
+server.accept({ allowHalfOpen: true });
+
+server.addEventListener("close", (event) => {
+  // With allowHalfOpen true, readyState is still CLOSING here,
+  // giving you time to coordinate the close on the other side.
+  console.log(server.readyState); // WebSocket.CLOSING
+
+  // Manually close when ready.
+  server.close(1000, "done");
+}, { once: true });
+```
+
+Note that there is no corresponding option to the `WebSocket` constructor. WebSockets constructed with `new WebSocket` will always auto-reply to closes after this flag takes effect. WebSockets constructed this way are automatically "accepted", so there is no opportunity to pass the option to `accept()`. If you are creating a WebSocket with `new WebSocket`, but you need half-open behavior, you will need to switch to using `fetch()` instead.
+
+```js
+// This does not allow half-open:
+let ws = new WebSocket("wss://example.com");
+
+// But you can do this instead:
+let resp = await fetch("https://example.com", {
+  headers: { "Upgrade": "websocket" }
+});
+if (!resp.webSocket) {
+  throw new Error("WebSocket handshake not accepted");
+}
+let ws = resp.webSocket;
+ws.accept({ allowHalfOpen: true });
+```
+
+For more information, refer to the [WebSocket API documentation](/workers/runtime-apis/websockets/).

src/content/docs/durable-objects/api/base.mdx

@@ -175,10 +175,9 @@ export class MyDurableObject extends DurableObject<Env> {
   	reason <Type text="string" />, wasClean <Type text="boolean" />)
   </code>
   : <Type text="void" /> | <Type text="Promise<void>" />- Called by the system
-  when a WebSocket connection is closed. - You **must** call `ws.close(code,
-  reason)` inside this handler to complete the WebSocket close handshake.
-  Failing to reciprocate the close will result in `1006` errors on the client,
-  representing an abnormal closure per the WebSocket specification.
+  when a WebSocket connection is closed.
+  - With the [`web_socket_auto_reply_to_close`](/workers/configuration/compatibility-flags/#websocket-auto-reply-to-close) compatibility flag (enabled by default on compatibility dates on or after `2026-04-07`), the runtime automatically sends a reciprocal Close frame and transitions `readyState` to `CLOSED` before this handler is called. You do not need to call `ws.close()` — but doing so is safe (the call is silently ignored).
+  - On older compatibility dates (before `2026-04-07`), you **must** call `ws.close(code, reason)` inside this handler to complete the WebSocket close handshake. Failing to reciprocate the close will result in `1006` errors on the client, representing an abnormal closure per the WebSocket specification.
   - This method can be `async`.
 
 #### Parameters
@@ -198,7 +197,9 @@ export class MyDurableObject extends DurableObject<Env> {
 ```ts
 export class MyDurableObject extends DurableObject<Env> {
 	async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
-		// Complete the WebSocket close handshake
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07),
+		// the runtime has already completed the close handshake.
+		// On older compat dates, call ws.close(code, reason) here.
 		ws.close(code, reason);
 		console.log(`WebSocket closed: code=${code}, reason=${reason}`);
 	}

src/content/docs/durable-objects/api/state.mdx

@@ -190,7 +190,9 @@ The WebSocket Hibernation API permits a maximum of 32,768 WebSocket connections
 
 :::note[`waitUntil` is not necessary]
 
-Disconnected WebSockets are not returned by this method, but `getWebSockets` may still return WebSockets even after `ws.close` has been called. For example, if the server-side WebSocket sends a close, but does not receive one back (and has not detected a disconnect from the client), then the connection is in the CLOSING 'readyState'. The client might send more messages, so the WebSocket is technically not disconnected.
+Disconnected WebSockets are not returned by this method, but `getWebSockets` may still return WebSockets even after `ws.close` has been called. For example, if the server-side WebSocket sends a close, but does not receive one back (and has not detected a disconnect from the client), then the connection is in the `CLOSING` readyState. The client might send more messages, so the WebSocket is technically not disconnected.
+
+With the [`web_socket_auto_reply_to_close`](/workers/configuration/compatibility-flags/#websocket-auto-reply-to-close) compatibility flag (enabled by default on compatibility dates on or after `2026-04-07`), the runtime automatically completes the close handshake, so WebSockets transition from `CLOSING` to `CLOSED` much faster and are less likely to be observed in the `CLOSING` state.
 
 :::
 

src/content/docs/durable-objects/best-practices/rules-of-durable-objects.mdx

@@ -1185,7 +1185,8 @@ export class ChatRoom extends DurableObject<Env> {
     	reason: string,
     	wasClean: boolean
     ) {
-    	// Calling close() completes the WebSocket handshake
+    	// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+    	// auto-replies to Close frames. Calling close() is safe but no longer required.
     	ws.close(code, reason);
     	console.log(`WebSocket closed: ${code} ${reason}`);
     }
@@ -1204,7 +1205,7 @@ With the Hibernation API, your Durable Object can go to sleep when there is no a
 Best practices:
 
 - The [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api) exposes `webSocketError`, `webSocketMessage`, and `webSocketClose` handlers for their respective WebSocket events.
-- When implementing `webSocketClose`, you **must** reciprocate the close by calling `ws.close()` to avoid swallowing the WebSocket close frame. Failing to do so results in `1006` errors, representing an abnormal close per the WebSocket specification.
+- With the [`web_socket_auto_reply_to_close`](/workers/configuration/compatibility-flags/#websocket-auto-reply-to-close) compatibility flag (enabled by default on compatibility dates on or after `2026-04-07`), the runtime automatically completes the close handshake. Calling `ws.close()` in `webSocketClose` is still safe but no longer required. On older compatibility dates, you **must** call `ws.close()` to avoid `1006` abnormal closure errors.
 
 Refer to [WebSockets](/durable-objects/best-practices/websockets/) for more details.
 
@@ -1275,7 +1276,8 @@ export class ChatRoom extends DurableObject<Env> {
 	}
 
 	async webSocketClose(ws: WebSocket, code: number, reason: string) {
-		// Calling close() completes the WebSocket handshake
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		// auto-replies to Close frames. Calling close() is safe but no longer required.
 		ws.close(code, reason);
 		const state = ws.deserializeAttachment() as ConnectionState;
 		this.broadcast(`${state.username} left the chat`);

src/content/docs/durable-objects/best-practices/websockets.mdx

@@ -100,7 +100,8 @@ export class WebSocketHibernationServer extends DurableObject {
 	}
 
 	async webSocketClose(ws, code, reason, wasClean) {
-		// Calling close() on the server completes the WebSocket close handshake
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		// auto-replies to Close frames. Calling close() is safe but no longer required.
 		ws.close(code, reason);
 	}
 }
@@ -148,7 +149,8 @@ export class WebSocketHibernationServer extends DurableObject {
 		reason: string,
 		wasClean: boolean,
 	) {
-		// Calling close() on the server completes the WebSocket close handshake
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		// auto-replies to Close frames. Calling close() is safe but no longer required.
 		ws.close(code, reason);
 	}
 }
@@ -190,7 +192,8 @@ self.ctx = state
         )
 
     async def webSocketClose(self, ws, code, reason, was_clean):
-        # Calling close() on the server completes the WebSocket close handshake
+        # With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+        # auto-replies to Close frames. Calling close() is safe but no longer required.
         ws.close(code, reason)
 
 ````
@@ -359,33 +362,34 @@ export class WebSocketServer extends DurableObject<Env> {
 		const url = new URL(request.url);
 		const orderId = url.searchParams.get("orderId") ?? "anonymous";
 
-    	const webSocketPair = new WebSocketPair();
-    	const [client, server] = Object.values(webSocketPair);
-
-    	this.ctx.acceptWebSocket(server);
+		const webSocketPair = new WebSocketPair();
+		const [client, server] = Object.values(webSocketPair);
 
-    	// Persist per-connection state that survives hibernation
-    	const state: ConnectionState = {
-    		orderId,
-    		joinedAt: Date.now(),
-    	};
-    	server.serializeAttachment(state);
+		this.ctx.acceptWebSocket(server);
 
-    	return new Response(null, { status: 101, webSocket: client });
-    }
+		// Persist per-connection state that survives hibernation
+		const state: ConnectionState = {
+			orderId,
+			joinedAt: Date.now(),
+		};
+		server.serializeAttachment(state);
 
-    async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
-    	// Restore state after potential hibernation
-    	const state = ws.deserializeAttachment() as ConnectionState;
-    	ws.send(`Hello ${state.orderId}, you joined at ${state.joinedAt}`);
-    }
+		return new Response(null, { status: 101, webSocket: client });
+	}
 
-    async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
-    	const state = ws.deserializeAttachment() as ConnectionState;
-    	console.log(`${state.orderId} disconnected`);
-    	ws.close(code, reason);
-    }
+	async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
+		// Restore state after potential hibernation
+		const state = ws.deserializeAttachment() as ConnectionState;
+		ws.send(`Hello ${state.orderId}, you joined at ${state.joinedAt}`);
+	}
 
+	async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
+		const state = ws.deserializeAttachment() as ConnectionState;
+		console.log(`${state.orderId} disconnected`);
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		// auto-replies to Close frames. Calling close() is safe but no longer required.
+		ws.close(code, reason);
+	}
 }
 
 ````
@@ -568,7 +572,9 @@ export class WebSocketServer extends DurableObject {
 			);
 		});
 
-		// If the client closes the connection, the runtime will close the connection too.
+		// When the client closes the connection, clean up the server side.
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		// auto-replies to Close frames. Calling close() is safe but no longer required.
 		server.addEventListener("close", (cls) => {
 			this.currentlyConnectedWebSockets -= 1;
 			server.close(cls.code, "Durable Object is closing WebSocket");
@@ -612,7 +618,9 @@ export class WebSocketServer extends DurableObject {
 			);
 		});
 
-		// If the client closes the connection, the runtime will close the connection too.
+		// When the client closes the connection, clean up the server side.
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		// auto-replies to Close frames. Calling close() is safe but no longer required.
 		server.addEventListener("close", (cls: CloseEvent) => {
 			this.currentlyConnectedWebSockets -= 1;
 			server.close(cls.code, "Durable Object is closing WebSocket");
@@ -657,7 +665,9 @@ self.currently_connected_websockets = 0
 
         server.addEventListener("message", create_proxy(on_message))
 
-        # If the client closes the connection, the runtime will close the connection too.
+        # When the client closes the connection, clean up the server side.
+        # With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+        # auto-replies to Close frames. Calling close() is safe but no longer required.
         def on_close(event):
             self.currently_connected_websockets -= 1
             server.close(event.code, "Durable Object is closing WebSocket")

src/content/docs/durable-objects/examples/websocket-hibernation-server.mdx

@@ -151,7 +151,8 @@ export class WebSocketHibernationServer extends DurableObject {
   }
 
   async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
-    // Calling close() on the server completes the WebSocket close handshake
+    // With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+    // auto-replies to Close frames. Calling close() is safe but no longer required.
     ws.close(code, reason);
     this.sessions.delete(ws);
   }
@@ -266,7 +267,8 @@ class WebSocketHibernationServer(DurableObject):
 				session.ws.send(f"[Durable Object] message: {message}, from: {session_id}, to: all clients except the initiating client. Total connections: {len(self.sessions)}")
 
 	async def webSocketClose(self, ws, code, reason, wasClean):
-		# Calling close() on the server completes the WebSocket close handshake
+		# With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		# auto-replies to Close frames. Calling close() is safe but no longer required.
 		ws.close(code, reason)
 		# Get the session ID from the WebSocket attachment to remove it from sessions
 		session_id = ws.deserializeAttachment()

src/content/docs/durable-objects/examples/websocket-server.mdx

@@ -96,7 +96,7 @@ export class WebSocketServer extends DurableObject {
             this.handleWebSocketMessage(server, event.data);
         });
 
-        // If the client closes the connection, the runtime will close the connection too.
+        // When the client closes the connection, clean up the server side.
         server.addEventListener('close', () => {
             this.handleConnectionClose(server);
         });
@@ -130,6 +130,8 @@ export class WebSocketServer extends DurableObject {
 
     async handleConnectionClose(ws: WebSocket) {
         this.sessions.delete(ws);
+        // With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+        // auto-replies to Close frames. Calling close() is safe but no longer required.
         ws.close(1000, 'Durable Object is closing WebSocket');
     }
 }
@@ -201,7 +203,7 @@ class WebSocketServer(DurableObject):
 		message_proxy = create_proxy(on_message)
 		server.addEventListener('message', message_proxy)
 
-		# If the client closes the connection, the runtime will close the connection too.
+		# When the client closes the connection, clean up the server side.
 		async def on_close(event):
 			await self.handleConnectionClose(id)
 			# Clean up proxies
@@ -236,6 +238,8 @@ class WebSocketServer(DurableObject):
 	async def handleConnectionClose(self, session_id):
 		session = self.sessions.pop(session_id, None)
 		if session:
+			# With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+			# auto-replies to Close frames. Calling close() is safe but no longer required.
 			session.ws.close(1000, 'Durable Object is closing WebSocket')
 ```
 

src/content/docs/workers/best-practices/workers-best-practices.mdx

@@ -569,6 +569,8 @@ export class ChatRoom extends DurableObject {
 		reason: string,
 		wasClean: boolean,
 	) {
+		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07), the runtime
+		// auto-replies to Close frames. Calling close() is safe but no longer required.
 		ws.close(code, reason);
 	}
 }

src/content/docs/workers/examples/websockets.mdx

@@ -329,6 +329,8 @@ async function websocket(url) {
 
 	// Call accept() to indicate that you'll be handling the socket here
 	// in JavaScript, as opposed to returning it on to a client.
+	// You can pass { allowHalfOpen: true } if you need to coordinate
+	// the close handshake manually (for example, when proxying).
 	ws.accept();
 
 	// Now you can send and receive messages like before.
@@ -339,6 +341,14 @@ async function websocket(url) {
 }
 ```
 
+## WebSocket close behavior
+
+With the [`web_socket_auto_reply_to_close`](/workers/configuration/compatibility-flags/#websocket-auto-reply-to-close) compatibility flag (enabled by default on compatibility dates on or after `2026-04-07`), the Workers runtime automatically replies to incoming Close frames and transitions `readyState` to `CLOSED` before firing the `close` event. You do not need to call `close()` in your `close` event handler, but doing so is safe (the call is silently ignored).
+
+If you need half-open behavior (for example, for WebSocket proxying), pass `{ allowHalfOpen: true }` to `accept()`. Note that `new WebSocket(url)` always auto-replies after this flag takes effect. To get half-open behavior for a client WebSocket, use the `fetch()`-based pattern shown above and call `ws.accept({ allowHalfOpen: true })`.
+
+For more details, refer to [WebSocket close behavior](/workers/runtime-apis/websockets/#close-behavior).
+
 ## WebSocket compression
 
 Cloudflare Workers supports WebSocket compression. Refer to [WebSocket Compression](/workers/configuration/compatibility-flags/#websocket-compression) for more information.

src/content/docs/workers/observability/errors.mdx

@@ -69,6 +69,12 @@ You can prevent this by enforcing the [`no-floating-promises` eslint rule](https
 
 If a WebSocket is missing the proper code to close its server-side connection, the Workers runtime will throw a `script will never generate a response` error. In the example below, the `'close'` event from the client is not properly handled by calling `server.close()`, and the error is thrown. In order to avoid this, ensure that the WebSocket's server-side connection is properly closed via an event listener or other server-side logic.
 
+:::note
+
+With the [`web_socket_auto_reply_to_close`](/workers/configuration/compatibility-flags/#websocket-auto-reply-to-close) compatibility flag (enabled by default on compatibility dates on or after `2026-04-07`), the runtime automatically completes the WebSocket close handshake. This specific error scenario is less likely to occur because the runtime handles the close for you. The example below applies to Workers on older compatibility dates.
+
+:::
+
 ```js null {10}
 async function handleRequest(request) {
 	let webSocketPair = new WebSocketPair();