Fire close event for server WebSocket close, with allowHalfOpen opt-out.

Author: anonrig

src/workerd/api/tests/BUILD.bazel

@@ -514,6 +514,12 @@ wd_test(
     data = ["url-test.js"],
 )
 
+wd_test(
+    src = "websocket-allow-half-open-test.wd-test",
+    args = ["--experimental"],
+    data = ["websocket-allow-half-open-test.js"],
+)
+
 wd_test(
     src = "websocket-constructor-test.wd-test",
     args = ["--experimental"],

src/workerd/api/tests/http-test.wd-test

@@ -11,7 +11,7 @@ const unitTests :Workerd.Config = (
           ( name = "SERVICE", service = "http-test" ),
           ( name = "CACHE_ENABLED", json = "false" ),
         ],
-        compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_option_disabled", "url_standard", "workers_api_getters_setters_on_prototype", "fetch_legacy_url"],
+        compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_option_disabled", "url_standard", "workers_api_getters_setters_on_prototype", "fetch_legacy_url", "no_web_socket_half_open_by_default"],
       )
     ),
     ( name = "http-test-cache-option-enabled",
@@ -23,7 +23,7 @@ const unitTests :Workerd.Config = (
           ( name = "SERVICE", service = "http-test-cache-option-enabled" ),
           ( name = "CACHE_ENABLED", json = "true" ),
         ],
-        compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_option_enabled", "url_standard", "workers_api_getters_setters_on_prototype", "fetch_legacy_url"],
+        compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_option_enabled", "url_standard", "workers_api_getters_setters_on_prototype", "fetch_legacy_url", "no_web_socket_half_open_by_default"],
     ))
   ],
 );

src/workerd/api/tests/tail-worker-test.js

@@ -12,7 +12,7 @@ const unitTests :Workerd.Config = (
           ( name = "SERVICE", service = "http-test" ),
           ( name = "CACHE_ENABLED", json = "false" ),
         ],
-        compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_option_disabled", "queues_json_messages", "url_standard", "workers_api_getters_setters_on_prototype", "fetch_legacy_url"],
+        compatibilityFlags = ["nodejs_compat", "service_binding_extra_handlers", "cache_option_disabled", "queues_json_messages", "url_standard", "workers_api_getters_setters_on_prototype", "fetch_legacy_url", "no_web_socket_half_open_by_default"],
         streamingTails = ["log", "log-invalid"],
       ),
     ),

src/workerd/api/tests/tail-worker-test.wd-test

@@ -0,0 +1,74 @@
+// Copyright (c) 2017-2022 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+import { strictEqual } from 'node:assert';
+
+// Test that when allowHalfOpen is false (default with compat flag), a server-initiated
+// close sets readyState to CLOSED.
+export const autoCloseReplyWhenNotHalfOpen = {
+  async test() {
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair);
+
+    // accept() without options — allowHalfOpen defaults to false with the compat flag.
+    client.accept();
+    server.accept();
+
+    const closePromise = new Promise((resolve) => {
+      client.addEventListener('close', (event) => {
+        // When allowHalfOpen is false, the runtime auto-sends a close reply,
+        // so both closedIncoming and closedOutgoing are true — readyState should be CLOSED.
+        resolve({
+          readyState: client.readyState,
+          code: event.code,
+          wasClean: event.wasClean,
+        });
+      });
+    });
+
+    // Server initiates close.
+    server.close(1000, 'server closing');
+
+    const result = await closePromise;
+    strictEqual(result.readyState, WebSocket.CLOSED);
+    strictEqual(result.code, 1000);
+    strictEqual(result.wasClean, true);
+  },
+};
+
+// Test that when allowHalfOpen is true via accept(), a server-initiated close sets
+// readyState to CLOSING.
+export const halfOpenCloseKeepsClosingState = {
+  async test() {
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair);
+
+    // Opt into half-open mode via accept() options.
+    client.accept({ allowHalfOpen: true });
+    server.accept();
+
+    const closePromise = new Promise((resolve) => {
+      client.addEventListener('close', (event) => {
+        // When allowHalfOpen is true, no auto-reply is sent, so only closedIncoming
+        // is true — readyState should be CLOSING.
+        resolve({
+          readyState: client.readyState,
+          code: event.code,
+          wasClean: event.wasClean,
+        });
+      });
+    });
+
+    // Server initiates close.
+    server.close(1000, 'server closing');
+
+    const result = await closePromise;
+    strictEqual(result.readyState, WebSocket.CLOSING);
+    strictEqual(result.code, 1000);
+    strictEqual(result.wasClean, true);
+
+    // The client must manually close to complete the handshake.
+    client.close(1000, 'client reply');
+  },
+};

src/workerd/api/tests/websocket-allow-half-open-test.js

@@ -0,0 +1,14 @@
+using Workerd = import "/workerd/workerd.capnp";
+
+const unitTests :Workerd.Config = (
+  services = [
+    ( name = "websocket-allow-half-open-test",
+      worker = (
+        modules = [
+          (name = "worker", esModule = embed "websocket-allow-half-open-test.js")
+        ],
+        compatibilityFlags = ["nodejs_compat", "no_web_socket_half_open_by_default"]
+      )
+    ),
+  ],
+);

src/workerd/api/tests/websocket-allow-half-open-test.wd-test

@@ -57,6 +57,7 @@ WebSocket::WebSocket(
       binaryType_(FeatureFlags::get(js).getWebsocketBinaryTypeDefault() ? BinaryType::BLOB
                                                                         : BinaryType::ARRAYBUFFER),
       serializedAttachment(kj::mv(package.serializedAttachment)),
+      allowHalfOpen(package.allowHalfOpen),
       farNative(initNative(ioContext,
           ws,
           kj::mv(KJ_REQUIRE_NONNULL(package.maybeTags)),
@@ -76,6 +77,7 @@ WebSocket::WebSocket(jsg::Lock& js, kj::Own<kj::WebSocket> native)
       url(kj::none),
       binaryType_(FeatureFlags::get(js).getWebsocketBinaryTypeDefault() ? BinaryType::BLOB
                                                                         : BinaryType::ARRAYBUFFER),
+      allowHalfOpen(!FeatureFlags::get(js).getWebSocketCloseReadyStateClosed()),
       farNative(nullptr),
       outgoingMessages(IoContext::current().addObject(kj::heap<OutgoingMessagesMap>())) {
   auto nativeObj = kj::heap<Native>();
@@ -88,6 +90,7 @@ WebSocket::WebSocket(jsg::Lock& js, kj::String url)
       url(kj::mv(url)),
       binaryType_(FeatureFlags::get(js).getWebsocketBinaryTypeDefault() ? BinaryType::BLOB
                                                                         : BinaryType::ARRAYBUFFER),
+      allowHalfOpen(!FeatureFlags::get(js).getWebSocketCloseReadyStateClosed()),
       farNative(nullptr),
       outgoingMessages(IoContext::current().addObject(kj::heap<OutgoingMessagesMap>())) {
   auto nativeObj = kj::heap<Native>();
@@ -398,7 +401,7 @@ kj::Promise<DeferredProxy<void>> WebSocket::couple(
   co_return co_await promise;
 }
 
-void WebSocket::accept(jsg::Lock& js) {
+void WebSocket::accept(jsg::Lock& js, jsg::Optional<AcceptOptions> options) {
   auto& native = *farNative;
   JSG_REQUIRE(!native.state.is<AwaitingConnection>(), TypeError,
       "Websockets obtained from the 'new WebSocket()' constructor cannot call accept");
@@ -414,6 +417,12 @@ void WebSocket::accept(jsg::Lock& js) {
     return;
   }
 
+  KJ_IF_SOME(opts, options) {
+    KJ_IF_SOME(value, opts.allowHalfOpen) {
+      allowHalfOpen = AllowHalfOpen(value);
+    }
+  }
+
   internalAccept(js, IoContext::current().getCriticalSection());
 }
 
@@ -605,11 +614,8 @@ void WebSocket::send(jsg::Lock& js, kj::OneOf<kj::Array<byte>, kj::String> messa
     KJ_UNREACHABLE;
   }();
 
-  auto pendingAutoResponses =
-      autoResponseStatus.pendingAutoResponseDeque.size() - autoResponseStatus.queuedAutoResponses;
-  autoResponseStatus.queuedAutoResponses = autoResponseStatus.pendingAutoResponseDeque.size();
   outgoingMessages->insert(
-      GatedMessage{kj::mv(maybeOutputLock), kj::mv(msg), pendingAutoResponses});
+      GatedMessage{kj::mv(maybeOutputLock), kj::mv(msg), getPendingAutoResponseCount()});
 
   ensurePumping(js);
 }
@@ -680,22 +686,13 @@ void WebSocket::close(
 
   assertNoError(js);
 
-  // pendingAutoResponses stores the number of queuedAutoResponses that will be pumped before sending
-  // the current GatedMessage, guaranteeing order.
-  // queuedAutoResponses stores the total number of auto-response messages that are already in accounted
-  // for in previous GatedMessages. This is useful to easily calculate the number of pendingAutoResponses
-  // for each new GateMessage.
-  auto pendingAutoResponses =
-      autoResponseStatus.pendingAutoResponseDeque.size() - autoResponseStatus.queuedAutoResponses;
-  autoResponseStatus.queuedAutoResponses = autoResponseStatus.pendingAutoResponseDeque.size();
-
   outgoingMessages->insert(GatedMessage{IoContext::current().waitForOutputLocksIfNecessary(),
     kj::WebSocket::Close{
       // Code 1005 actually translates to sending a close message with no body on the wire.
       static_cast<uint16_t>(code.orDefault(1005)),
       kj::mv(reason).orDefault(jsg::USVString(kj::str())),
     },
-    pendingAutoResponses});
+    getPendingAutoResponseCount()});
 
   native.closedOutgoing = true;
   closedOutgoingForHib = true;
@@ -990,6 +987,13 @@ kj::Promise<void> WebSocket::pump(IoContext& context,
   completed = true;
 }
 
+size_t WebSocket::getPendingAutoResponseCount() {
+  auto count =
+      autoResponseStatus.pendingAutoResponseDeque.size() - autoResponseStatus.queuedAutoResponses;
+  autoResponseStatus.queuedAutoResponses = autoResponseStatus.pendingAutoResponseDeque.size();
+  return count;
+}
+
 void WebSocket::tryReleaseNative(jsg::Lock& js) {
   // If the native WebSocket is no longer needed (the connection closed) and there are no more
   // messages to send, we can discard the underlying connection.
@@ -1057,6 +1061,23 @@ kj::Promise<kj::Maybe<kj::Exception>> WebSocket::readLoop(
           }
           KJ_CASE_ONEOF(close, kj::WebSocket::Close) {
             native.closedIncoming = true;
+            if (!allowHalfOpen.toBool() && !native.closedOutgoing && !native.outgoingAborted &&
+                !native.state.is<Released>()) {
+              // When allowHalfOpen is false (the spec-compliant default with the
+              // no_web_socket_half_open_by_default compat flag), automatically send a reciprocal
+              // Close frame through the outgoing message pump so that readyState is CLOSED (3)
+              // when the close event fires. Skip if a close frame was already sent (e.g. the
+              // application called close() before the server sent its Close), or if the outgoing
+              // side is otherwise unusable.
+              outgoingMessages->insert(
+                  GatedMessage{IoContext::current().waitForOutputLocksIfNecessary(),
+                    kj::WebSocket::Close{close.code, kj::str(close.reason)},
+                    getPendingAutoResponseCount()});
+
+              native.closedOutgoing = true;
+              closedOutgoingForHib = true;
+              ensurePumping(js);
+            }
             dispatchEventImpl(js, js.alloc<CloseEvent>(close.code, kj::mv(close.reason), true));
             // Native WebSocket no longer needed; release.
             tryReleaseNative(js);
@@ -1202,6 +1223,7 @@ WebSocket::HibernationPackage WebSocket::buildPackageForHibernation() {
     .serializedAttachment = kj::mv(serializedAttachment),
     .maybeTags = kj::none,
     .closedOutgoingConnection = closedOutgoingForHib,
+    .allowHalfOpen = allowHalfOpen,
   };
 }
 

src/workerd/api/web-socket.c++

@@ -11,6 +11,7 @@
 #include <workerd/io/observer.h>
 #include <workerd/jsg/jsg.h>
 #include <workerd/util/checked-queue.h>
+#include <workerd/util/strong-bool.h>
 #include <workerd/util/weak-refs.h>
 
 #include <kj/compat/http.h>
@@ -88,6 +89,8 @@ class CloseEvent: public Event {
   bool clean;
 };
 
+WD_STRONG_BOOL(AllowHalfOpen);
+
 // The forward declaration is necessary so we can make some
 // WebSocket methods accessible to WebSocketPair via friend declaration.
 class WebSocket;
@@ -207,6 +210,9 @@ class WebSocket: public EventTarget {
 
     // True forever once the JS WebSocket calls `close()`.
     bool closedOutgoingConnection = false;
+
+    // Whether the WebSocket allows half-open close state.
+    AllowHalfOpen allowHalfOpen = AllowHalfOpen::YES;
   };
 
   ~WebSocket() noexcept(false) {
@@ -287,13 +293,19 @@ class WebSocket: public EventTarget {
   // ---------------------------------------------------------------------------
   // JS API.
 
+  struct AcceptOptions {
+    jsg::Optional<bool> allowHalfOpen;
+
+    JSG_STRUCT(allowHalfOpen);
+  };
+
   // Creates a new outbound WebSocket.
   static jsg::Ref<WebSocket> constructor(jsg::Lock& js,
       kj::String url,
       jsg::Optional<kj::OneOf<kj::Array<kj::String>, kj::String>> protocols);
 
   // Begin delivering events locally.
-  void accept(jsg::Lock& js);
+  void accept(jsg::Lock& js, jsg::Optional<AcceptOptions> options);
 
   // Same as accept(), but websockets that are created with `new WebSocket()` in JS cannot call
   // accept(). Instead, we only permit the C++ constructor to call this "internal" version of accept()
@@ -387,9 +399,20 @@ class WebSocket: public EventTarget {
       open: Event;
       error: ErrorEvent;
     });
+    JSG_TS_DEFINE(interface WebSocketAcceptOptions {
+      /**
+       * When set to `true`, receiving a server-initiated WebSocket Close frame will not
+       * automatically send a reciprocal Close frame, leaving the connection in a half-open
+       * state. Defaults to `false` when the `no_web_socket_half_open_by_default`
+       * compatibility flag is enabled.
+       */
+      allowHalfOpen?: boolean;
+    });
     JSG_TS_OVERRIDE(extends EventTarget<WebSocketEventMap> {
       get binaryType(): "blob" | "arraybuffer";
       set binaryType(value: "blob" | "arraybuffer");
+      accept(options?: WebSocketAcceptOptions): void;
+      constructor(url: string, protocols?: string[] | string);
     });
   }
 
@@ -421,6 +444,14 @@ class WebSocket: public EventTarget {
   // `close()`, thereby preventing calls to `send()` even after we wake from hibernation.
   bool closedOutgoingForHib = false;
 
+  // When YES, a server-initiated close does NOT automatically send a reciprocal close frame,
+  // leaving readyState as CLOSING (2) when the close event fires. The application is then
+  // responsible for calling close() explicitly. When NO (spec-compliant default with the
+  // no_web_socket_half_open_by_default compat flag), a close reply is sent automatically and
+  // readyState is CLOSED (3) when the close event fires.
+  // Default is YES (legacy behavior); overridden from the compat flag at construction time.
+  AllowHalfOpen allowHalfOpen = AllowHalfOpen::YES;
+
   // Maximum allowed size for WebSocket messages
   inline static const size_t SUGGESTED_MAX_MESSAGE_SIZE = 1u << 20;
 
@@ -615,6 +646,11 @@ class WebSocket: public EventTarget {
 
   void ensurePumping(jsg::Lock& js);
 
+  // Returns the number of pending auto-responses that should be sent before the next outgoing
+  // message, and advances the queuedAutoResponses counter. Called each time a GatedMessage is
+  // inserted into outgoingMessages to guarantee auto-response ordering.
+  size_t getPendingAutoResponseCount();
+
   // Write messages from `outgoingMessages` into `ws`.
   //
   // These are not necessarily called under isolate lock, but they are called on the given
@@ -639,8 +675,8 @@ class WebSocket: public EventTarget {
 };
 
 #define EW_WEBSOCKET_ISOLATE_TYPES                                                                 \
-  api::CloseEvent, api::CloseEvent::Initializer, api::WebSocket, api::WebSocketPair,               \
-      api::WebSocketPair::PairIterator,                                                            \
+  api::CloseEvent, api::CloseEvent::Initializer, api::WebSocket, api::WebSocket::AcceptOptions,    \
+      api::WebSocketPair, api::WebSocketPair::PairIterator,                                        \
       api::WebSocketPair::PairIterator::                                                           \
           Next  // The list of websocket.h types that are added to worker.c++'s JSG_DECLARE_ISOLATE_TYPE
 

src/workerd/api/web-socket.h

@@ -1429,7 +1429,7 @@ struct CompatibilityFlags @0x8f8c1b68151b6cef {
   websocketBinaryTypeDefault @166 :Bool
       $compatEnableFlag("websocket_standard_binary_type")
       $compatDisableFlag("no_websocket_standard_binary_type")
-      $compatEnableDate("2026-03-17");
+    $compatEnableDate("2026-03-31");
   # Per the WHATWG WebSocket spec, the binaryType attribute defaults to "blob"
   # and binary messages are delivered as Blob objects. Previously, workerd did
   # not expose the binaryType property at all and always delivered binary
@@ -1472,4 +1472,14 @@ struct CompatibilityFlags @0x8f8c1b68151b6cef {
   #  - Getter .length is explicitly 0 and setter .length is 1.
   #  - Getter .name is "get <name>" and setter .name is "set <name>" per the
   #    Web IDL spec, instead of empty strings.
+
+  webSocketCloseReadyStateClosed @170 :Bool
+    $compatEnableFlag("no_web_socket_half_open_by_default")
+    $compatDisableFlag("web_socket_half_open_by_default")
+    $compatEnableDate("2026-03-17");
+  # When enabled, a reciprocal Close frame is automatically sent through the
+  # outgoing message pump when a server-initiated close is received, and the
+  # WebSocket readyState is CLOSED (3) when the close event fires. Previously,
+  # no close reply was sent and readyState was CLOSING (2). The WebSocket spec
+  # requires readyState to be CLOSED when the close event is dispatched.
 }