feat: allow configuring handleProtocols or change default behavior

[productdevbook]

Problem

The node adapter hardcodes handleProtocols: () => false:

// src/adapters/node.ts
const wss = options.wss || new _WebSocketServer({
  noServer: true,
  handleProtocols: () => false,
  ...options.serverOptions
});

This breaks WebSocket subprotocol negotiation for browsers. When using protocols like graphql-transport-ws (for GraphQL subscriptions), browsers reject the connection:

WebSocket connection failed: Error during WebSocket handshake: 
Sent non-empty 'Sec-WebSocket-Protocol' header but no response was received

Why This Happens

1. Browser sends Sec-WebSocket-Protocol: graphql-transport-ws
2. ws library calls handleProtocols() → returns false
3. ws internally marks "no protocol selected"
4. Even if we add Sec-WebSocket-Protocol header in the headers event, browsers still reject
5. Node.js ws client is lenient and accepts, but browsers are strict

Current Workaround Doesn't Work for Browsers

defineWebSocketHandler({
  upgrade(request) {
    const protocol = request.headers.get('sec-websocket-protocol')
    if (protocol?.includes('graphql-transport-ws')) {
      return {
        headers: { 'Sec-WebSocket-Protocol': 'graphql-transport-ws' }
      }
    }
  }
})

This works for Node.js clients but not for browsers.

Proposed Solutions

Option 1: Smart default based on upgrade hook response

If the upgrade hook returns a Sec-WebSocket-Protocol header, use that as the selected protocol:

handleProtocols: (protocols, request) => {
  // Check if upgrade hook set a protocol header
  const upgradeProtocol = request._upgradeHeaders?.get?.('sec-websocket-protocol')
  if (upgradeProtocol && protocols.has(upgradeProtocol)) {
    return upgradeProtocol
  }
  return false
}

Option 2: Allow configuration via options

wsAdapter({
  serverOptions: {
    handleProtocols: (protocols) => {
      if (protocols.has('graphql-transport-ws')) return 'graphql-transport-ws'
      return false
    }
  }
})

This already works via ...options.serverOptions spread, but requires upstream (Nitro) to expose it.

Option 3: Echo back first requested protocol by default

Instead of () => false, default to echoing the first protocol:

handleProtocols: (protocols) => protocols.values().next().value || false

Use Case

GraphQL subscriptions using the graphql-ws protocol, which is standard for:

• GraphQL Yoga
• Apollo Server
• Any server implementing graphql-ws spec

Environment

• crossws: 0.4.1
• ws: 8.x
• Tested with Chrome, Firefox, Safari - all fail
• Node.js ws client works (more lenient)

Related

• Nitro issue: feat: expose WebSocket serverOptions for crossws adapter nitrojs/nitro#3925

[productdevbook]

Root Cause Found

After deeper investigation, I found the exact issue in the ws library's behavior:

// ws library - completeUpgrade function
if (protocols.size) {
  const protocol = this.options.handleProtocols
    ? this.options.handleProtocols(protocols, req)
    : protocols.values().next().value;  // ← DEFAULT: echo first protocol!

  if (protocol) {
    headers.push(`Sec-WebSocket-Protocol: ${protocol}`);
  }
}

Key insight:

• If handleProtocols is null/undefined → ws library automatically echoes back the first protocol ✅
• If handleProtocols: () => false → no protocol is selected, header not added ❌

Simplest Fix

Just remove the handleProtocols: () => false line from the node adapter:

// src/adapters/node.ts
const wss = options.wss || new _WebSocketServer({
  noServer: true,
- handleProtocols: () => false,
  ...options.serverOptions
});

This would let the ws library use its default behavior, which is to echo back the first protocol from the client's list - exactly what's needed for graphql-transport-ws and other subprotocol negotiations.

Why The Current Workaround Fails

Even though crossws adds the Sec-WebSocket-Protocol header in the headers event:

1. The ws library's internal state thinks "no protocol was selected" (because handleProtocols returned false)
2. Node.js ws client is lenient and accepts the connection anyway
3. Browsers are stricter and validate that the protocol was properly negotiated internally

Testing

With handleProtocols: null (or removed), browsers should accept the connection because:

1. ws library sees client wants graphql-transport-ws
2. handleProtocols is null, so ws uses default: protocols.values().next().value
3. Returns "graphql-transport-ws"
4. Header is added properly by ws itself
5. Internal state is consistent
6. Browsers accept ✅