Skip to content

ws: mask outgoing payload in chunks - #23567

Closed
mvanslobbe wants to merge 5 commits into
curl:masterfrom
mvanslobbe:perf/ws-mask-chunks
Closed

mvanslobbe wants to merge 5 commits into
curl:masterfrom
mvanslobbe:perf/ws-mask-chunks

Conversation

@mvanslobbe

@mvanslobbe mvanslobbe commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

ws_enc_write_payload() masks one byte at a time and calls
Curl_bufq_write() once per byte. That limits WebSocket sends
(curl_ws_send() and uploads through the ws encode reader) to about
100-250 MB/s on one core, whatever the frame size.

This change masks into a 1 KiB stack buffer, eight bytes at a time, with
the mask rotated to the current offset. Each chunk then goes to the bufq
in a single call. Partial writes and CURLE_AGAIN behave as before: the
xor index and payload_remain advance only by the bytes the bufq
accepted.

The masking now lives in ws_enc_mask_write(), marked UNITTEST, and the
new unit test 2607 drives it with random piece sizes, mask offsets and
drains through a hard-limited bufq, so partial writes and CURLE_AGAIN
are covered. It checks the output against a byte-by-byte reference.

Benchmarked on GitHub Actions with the real ws_enc_write_payload() from
master and from this branch, both built at -O2 and linked against the
same libcurl, output checked identical, median of 7 rounds:
https://github.com/mvanslobbe/curl-fork/actions/runs/39835136699
(source: https://github.com/mvanslobbe/curl-fork/tree/e0412bb)

Master → this PR, MB/s:

runner compiler 16 B 125 B 1000 B 16 KiB 1 MiB
x86-64 gcc 13 133 → 785 (6x) 165 → 4369 (26x) 168 → 11355 (68x) 166 → 12129 (73x) 169 → 11324 (67x)
x86-64 clang 18 131 → 694 (5x) 149 → 4545 (31x) 151 → 20137 (133x) 156 → 21405 (137x) 162 → 14878 (92x)
arm64 gcc 13 149 → 798 (5x) 159 → 4047 (25x) 160 → 11421 (71x) 160 → 12936 (81x) 160 → 10863 (68x)
arm64 clang 18 134 → 951 (7x) 148 → 5097 (34x) 150 → 20135 (134x) 150 → 22441 (150x) 150 → 14979 (100x)
macOS arm64 Apple clang 21 95 → 928 (10x) 141 → 3243 (23x) 158 → 6860 (43x) 173 → 9954 (58x) 148 → 6956 (47x)

clang vectorises the 8-byte loop at -O2 and gcc does not, which
accounts for most of the difference between the two.

Tests 2300-2304, 2601, 2607 and 2700-2723 pass in a debug build with
ASan and UBSan.

AI disclosure

This change was found while reviewing curl's WebSocket send path and written with the help of Claude Code. I reviewed and tested the change myself.

ws_enc_write_payload() masks one byte at a time and calls
Curl_bufq_write() once per byte. That limits WebSocket sends
(curl_ws_send() and uploads through the ws encode reader) to about
250 MB/s on one core, whatever the frame size.

This change masks into a 1 KiB stack buffer, eight bytes at a time, with
the mask rotated to the current offset. Each chunk then goes to the bufq
in a single call. Partial writes and CURLE_AGAIN behave as before: the
xor index and payload_remain advance only by the bytes the bufq
accepted.

The masking now lives in ws_enc_mask_write(), marked UNITTEST, and the
new unit test 2607 drives it with random piece sizes, mask offsets and
drains through a hard-limited bufq, so partial writes and CURLE_AGAIN
are covered. It checks the output against a byte-by-byte reference.

A microbenchmark of the function body (clang 22 -O2, one P-core of an
i7-12700H, 64 MiB sent per frame size, median of 7 runs, output compared
byte for byte against the old loop):

| frame size | before    | after       |
|------------|-----------|-------------|
| 16 B       | 200 MB/s  | 1222 MB/s   |
| 125 B      | 239 MB/s  | 7527 MB/s   |
| 1000 B     | 244 MB/s  | 31319 MB/s  |
| 16 KiB     | 245 MB/s  | 36416 MB/s  |
| 1 MiB      | 245 MB/s  | 20796 MB/s  |

Tests 2300-2304, 2601, 2607 and 2700-2723 pass in a debug build with
ASan and UBSan.
@github-actions github-actions Bot added the tests label Oct 22, 2026
Comment thread tests/data/test2607 Resolved
@vszakats

Copy link
Copy Markdown
Member

frame size before after
16 B 200 MB/s 1222 MB/s
125 B 239 MB/s 7527 MB/s
1000 B 244 MB/s 31319 MB/s
16 KiB 245 MB/s 36416 MB/s
1 MiB 245 MB/s 20796 MB/s
Tests 2300-2304, 2601, 2607 and 2700-2723 pass in a debug build with ASan and UBSan.

I'd personally like these results replicated and confirmed in curl's test server,
or elsewhere via a public CI log.

Comment thread lib/ws.c Resolved
Comment thread tests/unit/unit2607.c Resolved
mvanslobbe added a commit to mvanslobbe/curl-fork that referenced this pull request Oct 22, 2026
@mvanslobbe

mvanslobbe commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor Author

I'd personally like these results replicated and confirmed in curl's test server,
or elsewhere via a public CI log.

Fair enough. Public run and source:

I looked at tests/perf and scorecard.py first. The perf programs avoid servers and only use the public API and curlx, but sending WebSocket data needs a connection, so ws_enc_write_payload() can't be reached that way. scorecard.py has no WebSocket mode, and over a real socket the cost of the transfer would hide most of the masking anyway. So I went with a small standalone benchmark instead.

run.sh includes lib/ws.c from master and from this PR into the same bench.c, links both against the same libcurl built at -O2, checks the masked output is identical and reports the median of 7 rounds.

Master → this PR, MB/s:

runner compiler 16 B 125 B 1000 B 16 KiB 1 MiB
x86-64 gcc 13 133 → 785 (6x) 165 → 4369 (26x) 168 → 11355 (68x) 166 → 12129 (73x) 169 → 11324 (67x)
x86-64 clang 18 131 → 694 (5x) 149 → 4545 (31x) 151 → 20137 (133x) 156 → 21405 (137x) 162 → 14878 (92x)
arm64 gcc 13 149 → 798 (5x) 159 → 4047 (25x) 160 → 11421 (71x) 160 → 12936 (81x) 160 → 10863 (68x)
arm64 clang 18 134 → 951 (7x) 148 → 5097 (34x) 150 → 20135 (134x) 150 → 22441 (150x) 150 → 14979 (100x)
macOS arm64 Apple clang 21 95 → 928 (10x) 141 → 3243 (23x) 158 → 6860 (43x) 173 → 9954 (58x) 148 → 6956 (47x)

clang vectorises the 8-byte loop at -O2 and gcc does not, hence the 2x gap. Reshaping the loop helps gcc but slows clang, and getting both to their best would need compiler-specific code, so I've kept it simple here. It's worth exploring separately.

I have updated the PR description with these numbers.

Copilot AI 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.

🟢 Approval recommended

No blocking issues were identified in the bounded masking change, partial-write handling, or test integration.

No open issues 🎉

What changed in this PR

This PR optimizes outgoing WebSocket payload masking by replacing per-byte queue writes with chunked writes, benefiting both curl_ws_send() and WebSocket uploads.

Changes:

  • Masks payloads in 1 KiB chunks using eight-byte operations.
  • Preserves mask-offset and payload accounting across partial writes and queue backpressure.
  • Adds a randomized unit test comparing masked output against a byte-by-byte reference.
File Description
tests/​unit/​unit2607.c Tests masking, partial writes, and full-queue handling.
tests/​unit/​Makefile.inc Registers the new unit test source.
tests/​data/​test2607 Defines the WebSocket masking test case and required features.
tests/​data/​Makefile.am Registers the new test case.
lib/​ws.c Extracts a testable helper and implements chunked payload masking.

Review effort: Balanced

@bagder

bagder commented Oct 22, 2026

Copy link
Copy Markdown
Member

Would be cool to get websocket transfers into the scorecard tests so that we can get them into the perf test site. WDYT @icing ?

@bagder bagder left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Faster transfers is good!

@bagder
bagder requested a review from vszakats October 22, 2026 20:56
@icing

icing commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Would be cool to get websocket transfers into the scorecard tests so that we can get them into the perf test site. WDYT @icing ?

You want the impossible

I'll see what I can do.

@bagder bagder closed this in e234f37 Oct 23, 2026
@bagder

bagder commented Oct 23, 2026

Copy link
Copy Markdown
Member

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Development

Successfully merging this pull request may close these issues.

5 participants