perf(server): negotiate permessage-deflate on the websocket

[t3dotgg]

Summary

Enables WebSocket compression by patching @effect/platform-node and @effect/platform-bun to accept permessage-deflate from clients that offer it. This is the first item from the WS data-reduction audit (follow-up to #4622).

• Backwards compatible per-connection: the negotiation is the standard Sec-WebSocket-Extensions handshake. Browsers offer the extension automatically, so web/desktop get compressed frames with no client changes; any client that doesn't offer it (old versions, exotic stacks) silently keeps uncompressed frames on its connection.
• Context takeover stays enabled (ws default on Node; dedicated compressors on Bun), so the per-connection compression window is shared across frames — that's where the win comes from on streaming traffic of small JSON frames full of repeated keys and UUIDs. Node also sets a 512-byte threshold so tiny frames skip compression.
• Shipped as pnpm patch entries consistent with the existing patches/ setup (we already patch effect@4.0.0-beta.102). Worth an upstream PR to expose this as a layer option so the patches can eventually be dropped.

Measurements

Replayed 500 real thread.activity-appended frames from a production database over the wire, counting raw TCP bytes:

Traffic	Plain	Deflate	Ratio
Pruned (post-#4622) live frames	344,330 B	85,855 B	4.0×
Unpruned frames	903,884 B	243,625 B	3.7×

Large cold-open snapshot frames compress closer to the ~10× measured for gzip on the same content.

Testing

• New test in apps/server/src/server.test.ts boots the real server stack and asserts: (1) a socket offering permessage-deflate gets it accepted in the 101 response, (2) a socket not offering it still connects and works uncompressed.
• Full apps/server/src/server.test.ts suite passes (115/115); t3 typecheck clean.

Follow-ups (not in this PR)

• CPU load-check under a real streaming turn with multiple connected clients.
• Confirm whether React Native's socket offers the extension on iOS/Android; if not, mobile stays uncompressed (the planned profile: "lite" work is the mobile lever anyway).

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes the WebSocket transport for every connection (compression CPU and interoperability), though negotiation is standard and opt-in per client; dependency patches add upgrade/maintenance risk until upstream lands.

Overview
Enables permessage-deflate on server WebSockets by patching @effect/platform-node and @effect/platform-bun (registered in pnpm-workspace.yaml / lockfile) until Effect 4.0.0-beta.103 exposes the same as layer options. There are no changes in apps/server runtime code beyond tests.

On Node, the patch turns on perMessageDeflate: true on the ws WebSocketServer. On Bun, it sets perMessageDeflate: { compress: "dedicated", decompress: "shared" } to negotiate compression while avoiding uWebSockets’ dedicated decompressor disconnect issue.

Clients that offer the extension get compressed frames; clients that do not stay on plain frames. A new server.test.ts case boots the real stack and asserts permessage-deflate appears in negotiated extensions only when the client requests it.

^{Reviewed by Cursor Bugbot for commit df9816c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Negotiate permessage-deflate compression on WebSocket connections

• Patches @effect/platform-bun to enable permessage-deflate with a dedicated compressor and shared decompressor in BunHttpServer.make.
• Patches @effect/platform-node to pass perMessageDeflate: true to the WebSocketServer constructor in NodeHttpServer.make.
• Both patches are registered in pnpm-workspace.yaml and applied during installation.
• A new test in server.test.ts verifies the extension is negotiated when offered by the client and absent when not.
• Behavioral Change: WebSocket connections that advertise permessage-deflate support will now use per-message compression, increasing CPU usage in exchange for reduced bandwidth.

^{Macroscope summarized df9816c.}

Summary by CodeRabbit

• New Features

  • Enabled WebSocket per-message compression when supported by the client.
  • Clients without compression support continue to connect normally without compressed frames.

• Tests

  • Added coverage verifying compression negotiation during WebSocket handshakes.

[coderabbitai]

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: negotiating permessage-deflate for WebSocket connections.
Description check	✅ Passed	The description covers what changed, why, testing, and follow-ups, though it does not follow the template headings exactly.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/audit-client-payloads

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e70433c. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR enables WebSocket compression (permessage-deflate) by patching @effect/platform dependencies. While well-documented, this is a significant runtime behavior change affecting all WebSocket connections that warrants human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

apps/server/src/server.test.ts (1)

3109-3109: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Add Bun-backed negotiation coverage.

This test provisions NodeHttpServer.layerTest, so it validates only the Node patch. Add an equivalent Bun integration/package-level check, or document a focused Bun verification path for the new compressor/decompressor modes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/server.test.ts` at line 3109, Extend the coverage around the
test using NodeHttpServer.layerTest to also exercise the equivalent Bun-backed
server path, verifying negotiation for the new compressor/decompressor modes. If
an equivalent integration test cannot be added here, document a focused Bun
verification path that explicitly covers those modes.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/server/src/server.test.ts`:
- Around line 3089-3100: Update the finalizer of openSocket to await the
WebSocket close event after calling socket.close(), rather than completing
immediately via Effect.sync. Add a bounded fallback so teardown still completes
if the close event never arrives, while preserving the existing socket
acquisition and error handling.

---

Nitpick comments:
In `@apps/server/src/server.test.ts`:
- Line 3109: Extend the coverage around the test using NodeHttpServer.layerTest
to also exercise the equivalent Bun-backed server path, verifying negotiation
for the new compressor/decompressor modes. If an equivalent integration test
cannot be added here, document a focused Bun verification path that explicitly
covers those modes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 56189bc4-a153-4c80-939f-41a4e366ea59

📥 Commits

Reviewing files that changed from the base of the PR and between dd5ea32 and 6b327f0.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (4)

• apps/server/src/server.test.ts
• patches/@effect__platform-bun@4.0.0-beta.102.patch
• patches/@effect__platform-node@4.0.0-beta.102.patch
• pnpm-workspace.yaml

[coderabbitai]

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Changed files/stat:"
git diff --stat || true

echo
echo "Locate test file and relevant lines:"
wc -l apps/server/src/server.test.ts
sed -n '3060,3130p' apps/server/src/server.test.ts

echo
echo "Search for openSocket usages and related tests:"
rg -n "openSocket|perMessageDeflate|NodeWs|NodeWS|layerTest|NodeServer|close event|Effect\.acquireRelease" apps/server/src/server.test.ts

echo
echo "Package WebSocket dependencies:"
if [ -f package.json ]; then jq '.dependencies, .devDependencies' package.json | rg -i 'ws|`@ff-labs/fff-node`|bun|node' || true; fi
fd -a 'package.json' . | while read -r f; do
  echo "--- ${f#"$PWD/"}"
  jq -r 'select(.dependencies or .devDependencies) as $d
    | {"path": env.SUBJECT_FILE, "deps": ($d.dependencies // {}), "dev": ($d.devDependencies // {})}
    | with_entries(select(.value|keys[]?|test("^(ws|`@ff-labs/fff-node`)$";"i")?))' "$f" || true
done

Repository: pingdotgg/t3code

Length of output: 12844

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Behavioral probe: if test workspace has ws installed, demonstrate close() starts handshake and close event arrives after it.
# Otherwise print availability context without executing repository test code.
echo "Node version:"
node --version || true
echo "Probe: ws availability"
node - <<'JS'
try {
  const wsPkg = require('ws');
  const server = require('ws');
  console.log("ws version:", wsPkg.version);
  const WebSocket = server.WebSocket;
  const wss = new server.WebSocketServer({ port: 0 }, () => {
    const url = `ws://localhost:${wss.address().port}`;
    console.log("server url:", url);
    const client = new WebSocket(url, { perMessageDeflate: false });
    let events;
    client.on("open", () => {
      events.push(["open"]);
      client.close();
    });
    client.on("close", (code, reason) => {
      events.push(["close", code, reason && reason.toString()]);
      console.log(JSON.stringify(events));
    });
    client.on("error", (err) => {
      console.log("error", err.message);
    });
    console.log("events immediate after close init:", events);
  });
} catch (err) {
  console.log("ws not available in node_modules:", err && err.message);
}
JS

Repository: pingdotgg/t3code

Length of output: 302

---

🌐 Web query:

ws WebSocket close event close method asynchronous close handshake documentation

💡 Result:

The WebSocket closing handshake is a standardized mechanism defined in RFC 6455 to ensure that both peers are aware that the connection is being terminated, allowing for the graceful handling of pending data [1]. In the context of the popular Node.js ws library, the websocket.close([code[, reason]]) method initiates this closing handshake [2][3]. It is important to note that while the closing handshake is an asynchronous process in the WebSocket protocol, the ws library's close method itself is synchronous in terms of function execution—it immediately triggers the protocol's closing sequence [2][3]. It does not return a Promise or take a completion callback to signal when the handshake has finished [2][3]. Instead, the completion of the handshake is signaled by the 'close' event, which is emitted once the connection has been fully closed [2][3][4]. Key distinctions regarding closing methods: 1. websocket.close: This initiates the graceful closing handshake [4]. It allows for pending messages to be sent before the handshake begins and waits for the corresponding close frame from the other peer [5][6]. 2. websocket.terminate: This is an alternative method that immediately destroys the underlying socket connection without performing the closing handshake [4]. It is typically used for error handling or when an immediate shutdown is required regardless of the state of pending data [7][4]. While libraries in other environments (such as.NET with CloseAsync or Boost.Beast with async_close) explicitly expose the asynchronous nature of the handshake via Promises or completion handlers [8][9], the standard Web API close and the Node.js ws library's close method are designed to be invoked as fire-and-forget actions that lead to a later 'close' event [5][3][6].

Citations:

• 1: https://datatracker.ietf.org/doc/html/rfc6455
• 2: https://github.com/websockets/ws/blob/HEAD/doc/ws.md
• 3: https://github.com/websockets/ws/blob/8.8.1/doc/ws.md
• 4: doc clarification between ws.close() and ws.terminate() websockets/ws#1142
• 5: https://websockets.spec.whatwg.org/
• 6: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close
• 7: https://github.com/websockets/ws?tab=readme-ov-file
• 8: https://learn.microsoft.com/en-us/dotnet/api/system.net.websockets.websocket.closeasync?view=net-9.0
• 9: https://www.boost.org/doc/libs/latest/libs/beast/doc/html/beast/ref/boost__beast__websocket__stream/async_close.html

---

Await the sockets’ close events in the finalizer.

WebSocket.close() initiates an asynchronous closing handshake; wrapping it in Effect.sync lets the scope finish immediately after calling close(), before the close event signals the socket is actually terminated. Await the close event in the finalizer with a bounded termination fallback to avoid leaving unclosed WebSocket handles during teardown. (github.com)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/server.test.ts` around lines 3089 - 3100, Update the
finalizer of openSocket to await the WebSocket close event after calling
socket.close(), rather than completing immediately via Effect.sync. Add a
bounded fallback so teardown still completes if the close event never arrives,
while preserving the existing socket acquisition and error handling.

[t3dotgg]

Update: the options passthrough was upstreamed and merged as Effect-TS/effect#6691; it ships in @effect/platform-node / @effect/platform-bun >= 4.0.0-beta.103 (queued in their open Version Packages PR). Both patch files now carry a comment pointing at the upstream PR and the removal path: on the next effect bump, delete the two patches and pass websocket: { perMessageDeflate: ... } through the layer options in apps/server/src/server.ts instead.