Skip to content

Add WebSocket.bufferedAmount - #8479

Merged
danlapid merged 2 commits into
mainfrom
dlapid/websocket-buffered-amount
Nov 16, 2026
Merged

danlapid merged 2 commits into
mainfrom
dlapid/websocket-buffered-amount

Conversation

@danlapid

@danlapid danlapid commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Since #8306, messages a WebSocket has queued but not yet written count toward the isolate's memory limit. But a Worker has no way to tell how much it has queued, so one that streams faster than its peer reads can only guess a send rate. If it guesses wrong, the isolate exceeds its limit and every connection on it drops. #8477 is a speed test that hit this.

This adds the standard WebSocket.bufferedAmount: the number of payload bytes passed to send() that haven't been written to the connection yet. As in browsers, there's no drain event; applications poll it.

  • Text counts as its UTF-8 length and binary data as its byte length. Close frames and framing overhead don't count.
  • The count goes down once each write completes, so it includes the message the pump is writing now.
  • As the standard requires, data that send() silently discards because the connection has failed is added and never subtracted, so the value keeps climbing if an application keeps sending to a dead connection.

The count lives in the IoContext-owned Native state next to the outgoing queue, which the pump already updates without the isolate lock.

No compatibility flag. The property was undefined before, so code that checks ws.bufferedAmount > limit was never applying backpressure and now will. The one thing that could break is a strict-mode assignment to ws.bufferedAmount, which now throws because the property is read-only. That seems unlikely enough not to need a flag, but say so if you disagree.

Types. bufferedAmount is added to types/generated-snapshot by hand, with the MDN comment from TypeScript's lib.dom.d.ts that the generator uses. I couldn't run just generate-types in this setup, so the snapshot check job will confirm whether it matches the generated output.

Testing

websocket-buffered-amount-test covers: the starting value of 0, UTF-8 and binary counting, the count holding while the peer isn't reading and draining once it reads, and close() not being counted. Every variant passed with --runs_per_test=5. The existing WebSocket wd-tests still pass, and clang-tidy is clean on //src/workerd/io.

WPT

The second commit re-enables the WPT Send-* tests that were disabled for lack of bufferedAmount. 17 of the 20 now pass, as do idlharness's two bufferedAmount checks. The config now records why the other three are still off:

  • Send-binary-blob.any.js stays disabled, because send() doesn't accept a Blob.
  • Send-unpaired-surrogates.any.js is an expected failure, because send() doesn't replace an unpaired surrogate with U+FFFD.
  • Send-data.worker.js is omitted, because it relies on importScripts().

The suite passed with --runs_per_test=5.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

The generated output of @cloudflare/workers-types matches the snapshot in types/generated-snapshot 🎉

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 7a2accb1.

This review, of be9f0fb7

🛑 Significant concerns — 1 BLOCKING: the new pure virtual getBufferedAmount() is not overridden in the final class HibernatableWebSocketAdapter. That triggers Clang's default-on -Wabstract-final-class, which the -Werror CI configuration turns into a build failure. Otherwise the change is sound.

Findings: 1 blocking · 1 info (2 are inline comments on the diff)

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8479.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## BLOCKING (1)

### [Code Quality] `HibernatableWebSocketAdapter` (declared `final`) does not override the new pure virtual `getBufferedAmount()`. The resulting abstract final class triggers Clang's default-on `-Wabstract-final-class`, which the `-Werror` config (`.bazelrc:607`, enabled by `.bazelrc:644`) makes a build error.
- **File:** src/workerd/api/web-socket.h:432

## INFO (1)

### [Code Quality] `types/generated-snapshot/*` was edited by hand, which the repository rules forbid. If the snapshot check fails, regenerate the files with `just generate-types`.
- **File:** types/generated-snapshot/index.d.ts:3417

📋 Code Quality: 🛑 1 blocking · 1 info

The new pure virtual is not implemented in HibernatableWebSocketAdapter, which breaks the build under -Werror. The type snapshots were edited by hand.

Recommendation: 🔴 Serious Concerns

  • [BLOCKING] HibernatableWebSocketAdapter (declared final) does not override the new pure virtual getBufferedAmount(). The resulting abstract final class triggers Clang's default-on -Wabstract-final-class, which the -Werror config (.bazelrc:607, enabled by .bazelrc:644) makes a build error. (src/workerd/api/web-socket.h:432)
  • [INFO] types/generated-snapshot/* was edited by hand, which the repository rules forbid. If the snapshot check fails, regenerate the files with just generate-types. (types/generated-snapshot/index.d.ts:3417)
View full review

1. HibernatableWebSocketAdapter does not override getBufferedAmount() (BLOCKING)

web-socket.h:432 adds virtual double getBufferedAmount() = 0; to WebSocketAdapter, but only LegacyWebSocketAdapter overrides it.

  • HibernatableWebSocketAdapter (src/workerd/api/hibernatable-adapter.h:18) is declared final and lists an override for every other adapter method, but not this one.
  • hibernatable-adapter.c++ is part of the api library (src/workerd/api/BUILD.bazel:30).
  • An abstract class marked final triggers Clang's -Wabstract-final-class warning, which is on by default.
  • The werror config adds -Werror (.bazelrc:607). The bazelflare config enables it (.bazelrc:644) and notes "Warnings are errors, as in CI" (.bazelrc:629). So the header fails to compile in CI and on any -Werror build.
  • Even without -Werror, the class cannot be instantiated once the hibernatable-adapter path is enabled.

Fix: add double getBufferedAmount() override; to the class, and define it in hibernatable-adapter.c++ with unimplemented();, as getReadyState() is.

2. Hand-edited type snapshots (INFO)

The repository rules say not to edit types/generated-snapshot/ directly. The description discloses this and relies on the snapshot check to confirm it. The added declaration matches how readyState is declared. If that check fails, regenerate the files with just generate-types.


✅ All other checks passed

🔒 Security: ✅ LGTM

bufferedAmount is a read-only counter of the caller's own payload bytes. It adds no new trust boundary, injection surface or data exposure.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md changes are needed.


⚡ Performance: ✅ LGTM

Keeping the count costs one integer add per send() and one subtract per completed write.


📝 Documentation: ✅ LGTM

The header comment and the type declaration describe the behaviour accurately.


Reviewed commit: be9f0fb7

Comment thread src/workerd/api/web-socket.h Resolved
Comment thread types/generated-snapshot/index.d.ts Resolved
@danlapid
danlapid force-pushed the dlapid/websocket-buffered-amount branch from be9f0fb to 7a2accb Compare November 15, 2026 20:21

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 8bcc25df.

This review, of 7a2accb1

💬 Approved with comments — The earlier BLOCKING item (missing override in the final HibernatableWebSocketAdapter) is fixed. The only remaining note is an INFO about the hand-edited type snapshots.

Findings: 1 info

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📋 Code Quality: 💬 1 info

The earlier missing-override build break is fixed. One INFO remains about hand-edited type snapshots.

Recommendation: 💬 Optional Nits

  • [INFO] The types/generated-snapshot/ files were edited by hand, which the repository rules forbid. Regenerate them with just generate-types if the snapshot check fails. (types/generated-snapshot/index.d.ts:3417)
View full review
  • Override added. HibernatableWebSocketAdapter now declares double getBufferedAmount() override; and defines it with unimplemented(), so it is no longer an abstract final class.
  • Counting. send() adds the payload size on every path, including the ones that discard the message on a dead connection. The pump subtracts the size only after each ws->send() completes. The value is kept as a uint64_t and returned as a double.
  • Types (INFO). types/generated-snapshot/* was edited by hand, which the repository rules forbid. If the snapshot check fails, regenerate the files with just generate-types.

✅ All other checks passed

🔒 Security: ✅ LGTM

bufferedAmount is a read-only count of the caller's own payload bytes. It adds no new trust boundary or data exposure.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md changes are needed.


⚡ Performance: ✅ LGTM

Each message costs one integer add in send() and one subtract after its write completes, so the overhead is negligible.


📝 Documentation: ✅ LGTM

The header comment and the type declaration describe the behaviour accurately.


Reviewed commit: 7a2accb1

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 11a4b7d5.

This review, of 8bcc25df

✅ Approved — No new issues: the WPT config change is correct and the bufferedAmount counting is still sound. One earlier note about the hand-edited type snapshots remains open.

Not opened by the correctness review: 2 changed files it was meant to read
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

bufferedAmount is a read-only count of the caller's own payload bytes. It adds no new trust boundary and exposes no new data.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates are needed.


📋 Code Quality: ✅ LGTM

  • WPT config: removeUseCapture is defined in src/wpt/websockets-test.ts, so every re-enabled Send-* entry resolves. The three tests still off (Send-binary-blob, Send-unpaired-surrogates, Send-data.worker.js) each record a reason.
  • Counting: send() adds the payload size on both discard paths and after queuing. The pump subtracts it only after each write completes.

⚡ Performance: ✅ LGTM

Each message costs one integer add in send() and one subtract after its write completes. That overhead is negligible.


📝 Documentation: ✅ LGTM

The header comment and the type declaration describe the behaviour accurately.


Reviewed commit: 8bcc25df

Since #8306, messages a WebSocket has queued but not yet written
count toward the isolate's memory limit, but an application has no
way to tell how much it has queued. A Worker that streams faster than
its peer reads can only guess a send rate, and if it guesses wrong,
the isolate exceeds its limit and every connection on it drops
(#8477).

bufferedAmount is the WHATWG WebSockets standard's answer: the number
of payload bytes passed to send() that haven't been written to the
connection yet. Text counts as its UTF-8 length; Close frames and
framing overhead don't count. As the standard requires, data that
send() discards because the connection has failed is counted and
never subtracted, so the value keeps climbing if an application
keeps sending to a dead connection.

The count lives with the outgoing queue in the IoContext-owned
native state, which the pump already updates without the isolate
lock. It is lowered after each write completes, so it also covers the
message the pump is currently writing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@danlapid
danlapid force-pushed the dlapid/websocket-buffered-amount branch from 8bcc25d to 11a4b7d Compare November 15, 2026 20:56

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 8afc5934.

This review, of 11a4b7d5

✅ Approved — No new issues: the updated http-test expectation matches the property's registration order, and the bufferedAmount counting is still sound. One earlier note about the hand-edited type snapshots is still open.

Not opened by the correctness review: 2 changed files it was meant to read
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

bufferedAmount is a read-only count of the caller's own payload bytes. It adds no new trust boundary and exposes no new data. The only change since the last review is a test expectation.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates are needed.


📋 Code Quality: ✅ LGTM

  • http-test.js: The new bufferedAmount: 0 sits right after readyState, which matches the registration order in web-socket.h in both property branches.
  • Counting: send() adds the payload size on both discard paths and after queuing. The pump subtracts it only after each write completes, and it reads the size from the queued message, which stays alive until the write finishes.
  • Hibernatable adapter: getBufferedAmount() is unimplemented() there, like getReadyState() next to it.
  • WPT config: Each re-enabled entry resolves, and each of the three tests still off records why.

⚡ Performance: ✅ LGTM

Each message costs one integer add in send() and one subtract after its write completes. That overhead is negligible.


📝 Documentation: ✅ LGTM

The header comment and the type declaration describe the behaviour accurately. One earlier note is still open: the files under types/generated-snapshot/ were edited by hand rather than regenerated. Those files have not changed since then.


Reviewed commit: 11a4b7d5

These tests were disabled because they check bufferedAmount, which
workerd didn't have until the previous commit. 17 of the 20 now pass
and are enabled. The idlharness checks for bufferedAmount pass too,
so they come off its expected failures.

The other three fail for reasons unrelated to bufferedAmount, and the
config now says why:

* Send-binary-blob.any.js stays disabled: send() doesn't accept a
  Blob, so no message comes back and the test hangs.
* Send-unpaired-surrogates.any.js is an expected failure: send()
  doesn't replace an unpaired surrogate with U+FFFD, so the echo
  server never returns the message.
* Send-data.worker.js is omitted: it loads its helpers with
  importScripts(), and Send-data.any.js covers the same case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@danlapid
danlapid force-pushed the dlapid/websocket-buffered-amount branch from 11a4b7d to 8afc593 Compare November 16, 2026 01:27

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved — No findings. The only change since the last review is the WPT test config, which is correct, and the bufferedAmount counting is still sound.

Not opened by the correctness review: 2 changed files it was meant to read
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

bufferedAmount is a read-only count of the caller's own payload bytes. It adds no new trust boundary.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates are needed.


📋 Code Quality: ✅ LGTM

send() adds the payload size on both discard paths and after queuing. The pump subtracts it only after each write completes. The hibernatable adapter override is present. The WPT config entries resolve, and each disabled test records why.


⚡ Performance: ✅ LGTM

Each message costs one integer add and one subtract, which is negligible.


📝 Documentation: ✅ LGTM

The header comment and the type declarations accurately describe the behaviour. The .ts and .d.ts snapshot files match each other.


Reviewed commit: 8afc5934

@danlapid
danlapid enabled auto-merge November 16, 2026 02:38
@danlapid
danlapid disabled auto-merge November 16, 2026 02:38
@danlapid
danlapid merged commit 33612ed into main Nov 16, 2026
23 checks passed
@danlapid
danlapid deleted the dlapid/websocket-buffered-amount branch November 16, 2026 02:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants