feat(rpc): add webzockets dependency for json rpc websockets by jbuckmccready · Pull Request #1222 · Syndica/sig

jbuckmccready · 2026-02-09T18:36:41Z

Summary

Adds webzockets package to path src/rpc/webzockets. webzockets implements websockets in zig, built on top of libxev for network IO. See src/rpc/webzockets/README.md for details on the package itself.

This is only adds a websocket implementation needed to implement the json RPC websocket API. The json RPC API will be in a different PR.

Changes

Updated the libxev version used by sig in build.zig.zon to new commit (current HEAD of zig-0.14 branch): Syndica/libxev@11a00ee
This commit is on top of a slightly later version of libxev than we were previously using that is still compatible with zig 0.14.1, and the commit fixes error returns for the kqueue backend (associated pull request upstream: mitchellh/libxev#207).

Updated build.zig and build.zig.zon with webzockets dependency, and added import to src/rpc/lib.zig so webzockets is part of the build.

Ran docs/generate.py so webzockets README.md is included in the published docs.

Updated scripts/style.py to skip cache dirs.

Update 2026-02-13:

Fixed another bug in libxev where io_uring gave unexpected error on shutdown when socket already closed.
Upstream PR: mitchellh/libxev#211
Syndica fork commit: Syndica/libxev@c16162f
NOTE: for kqueue/epoll backends it could just issue std.posix.shutdown directly to avoid the event loop processing entirely, but io_uring backend actually queues the shutdown command to avoid a syscall.

Update 2026-02-14:

Added read pause/resume (0028053)

Added heuristic for compaction to avoid small TCP reads (e.g., want to avoid a full TCP read cycle through IO loop if there is only 46 bytes remaining in the read buffer but compaction would free 8KB).
Added ability for connections to pause reads to exert back pressure on the TCP connection. This is helpful for future jrpc layer to allow server handlers to not have any queue of received messages by having the control flow: receive sub/unsub request from client -> pause reads -> send sub/unsub response -> write complete -> resume reads.

Removed BufferPool (51641cc), it will not be used by the jrpc server (embedded read buffer will cover sub/unsub requests) and adds complexity.

- Add webzockets as a local path dependency in build.zig.zon - Wire up webzockets module in build.zig - Re-export webzockets module from src/rpc/lib.zig to include in build - Update libxev dependency with fix for error returns (compatible with zig 0.14): Syndica/libxev@11a00ee

codecov · 2026-02-09T19:32:47Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 2 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Not particularly useful and takes up a lot of space in the README.md.

- Define test_webzockets job for Linux environment - Define test_webzockets_macos job for macOS environment - Update workflows to run webzockets tests on both platforms

- add RawClient wait helpers for message type, close frames, and disconnects - make read timeout configurable and default to 2s to reduce jitter flakes - update close, fragmentation, handshake, and timeout tests to use bounded waits

Sobeston · 2026-02-10T21:08:47Z

src/rpc/webzockets/src/buffer.zig

+/// Growable buffer pool with runtime-configurable buffer size.
+/// Uses an intrusive free list (like std.heap.MemoryPool) for efficient reuse.
+/// Thread-safe for shared use across connections.
+///
+/// Pool grows beyond preheat size as needed. Use preheat to pre-allocate
+/// buffers for expected concurrent usage, avoiding allocations in the
+/// common case.
+pub const BufferPool = struct {


Not convinced we need something like this, we already have e.g. arena allocators

I don't quite follow, how would I use arena allocator effectively for server side read buffer per client?

This pooling is maybe an over optimization, this approach is biased to the patterns I saw from networking around edge-gateway.

The idea is if you know the use case for the server/API then you can tune the buffer pool size according to message sizes you expect from clients, then clients connecting, sending message, and disconnecting turns into single pop and push rather than going to a more generic/global allocator and relying on it to pool efficiently.

For our very specific use case of broadcasting jrpc subscriptions I I don't think this buffer pool will be used at all since client messages will always fit within the embedded read buffer each client struct has - but this should be effective for a more general web server use case and doesn't add much complexity.

Removed BufferPool, commit: 51641cc

Sobeston · 2026-02-10T21:09:49Z

src/rpc/webzockets/src/buffer.zig

+    /// Mutex for thread-safe access.
+    mutex: std.Thread.Mutex,


We can do without multi-threading here - if we do have a pool (or arena), per-thread is probably better.

Yeah I'll change it.

My original thinking was the uncontested path is extremely fast anyways and this would allow more IO loops to share something that even under high volume will be largely uncontested, and it would avoid dead/unbalanced distributions across threads, but that's something easy to refine later.

Current code does bad things with the lock too (holds while allocating new buffer...). EDIT: oh right it would have to if it's backed by the arena.

Sobeston · 2026-02-10T21:13:50Z

src/rpc/webzockets/autobahn/client/client.zig

+// ============================================================================
+// AutobahnRunner — orchestrates sequential test-case execution
+// ============================================================================


Bad doc string

Sobeston · 2026-02-10T21:13:59Z

src/rpc/webzockets/autobahn/client/client.zig

+// ============================================================================
+// AutobahnClientHandler — echo handler for the Autobahn testsuite
+// ============================================================================


Bad doc string

Sobeston · 2026-02-10T21:14:41Z

src/rpc/webzockets/autobahn/client/client.zig

+pub fn main() !void {
+    const allocator = std.heap.c_allocator;


Let's avoid the c_allocator and prefer the gpa

I can update autobahn server as well. I can change to GPA but still no graceful exit (no leak check), or change to GPA and add sigint handler and graceful shutdown and check for leak (this adds some lines). LMK

Sobeston · 2026-02-10T21:22:50Z

src/rpc/webzockets/src/reader.zig

+/// Manages read buffer state with automatic tier escalation:
+/// - Starts with an embedded buffer for small messages
+/// - Upgrades to pooled or dynamic buffer when needed
+/// - Retains larger buffer for subsequent messages (performance optimization)
+/// - Restores to embedded only on explicit reset()


Not convinced that we need any of this

Ties in with #1222 (comment)

Removed buffer pool, commit: 51641cc

Sobeston · 2026-02-10T21:28:03Z

src/rpc/webzockets/src/server/server.zig

+        /// Type-erased context pointer for the shutdown completion callback.
+        shutdown_userdata: ?*anyopaque,


redundant comments

Sobeston · 2026-02-10T21:37:11Z

src/rpc/webzockets/src/mask.zig

+    .stage2_llvm, .stage2_c => true,
+    else => false,
+};
+


Is this correct? If so can you link something on the issue tracker. Worth noting we only use the llvm backend

I copied from: https://github.com/karlseguin/websocket.zig/blob/97fefafa59cc78ce177cff540b8685cd7f699276/src/proto.zig#L7-L10

I didn't drill into the compiler to see details. I put it in mostly just to note a place where disabling may be needed - for our use case it's not needed.

Sobeston · 2026-02-10T21:37:43Z

src/rpc/webzockets/src/mask.zig

+pub fn mask(m: []const u8, payload: []u8) void {
+    std.debug.assert(m.len == 4);


if m must be len 4, then why not e.g. *const [4]u8

Yeah, and style wise should I pass by value or *const here? Likely compiles to same thing but style wise is there preference for small values/arrays like this?

96a343e

Removed conditional stuff with backend, changed to pass by value.

Sobeston · 2026-02-10T21:39:17Z

src/rpc/webzockets/src/root.zig

+test {
+    // Uncomment to see logs during tests
+    // std.testing.log_level = .debug;
+    std.testing.refAllDecls(@This());
+    std.testing.refAllDecls(@import("control_queue.zig"));
+}


We should be moving away from refAllDecls

Should there be explicit import for each file inside test block? I'm not familiar with Zig on this.

Also removes need for pool_buffer_size field in Reader.

- remove pending_data from client and server write state - add outstandingUserWrite helper for busy, defer, and cleanup checks - clear header_len in finishWrite before invoking onWriteComplete

Update libxev dependency hash in both root and webzockets build.zig.zon

…erver - Add pauseReads/resumeReads/peekBufferedBytes API to both connections - Add onBytesRead handler callback for observing raw TCP data arrival - Add re-entrancy guard to processMessages to prevent recursive dispatch - Improve reader with availableSpace, compactIfFull, early compaction heuristic - Add comprehensive e2e tests for burst processing, mid-stream pause, close-while-paused, re-entrancy detection, and small-buffer scenarios

- Document onBytesRead handler callback - Add pauseReads, resumeReads, peekBufferedBytes connection methods

- Delete buffer.zig and update all code and docs - Reader now escalates directly from embedded buffer to dynamic allocation

jbuckmccready requested review from dnut, ultd and yewman as code owners February 9, 2026 18:36

github-project-automation bot added this to Sig Feb 9, 2026

github-project-automation bot moved this to 🏗 In progress in Sig Feb 9, 2026

jbuckmccready self-assigned this Feb 9, 2026

jbuckmccready requested a review from kprotty February 9, 2026 18:36

jbuckmccready force-pushed the jbuckmccready/webzockets branch from 87e052b to 35e2914 Compare February 9, 2026 18:40

jbuckmccready force-pushed the jbuckmccready/webzockets branch from 35e2914 to 8e6b2f6 Compare February 9, 2026 19:09

jbuckmccready requested review from InKryption and Rexicon226 February 9, 2026 19:10

jbuckmccready added 7 commits February 9, 2026 11:44

docs(webzockets): remove module dependencies from README.md

79fb4b2

Not particularly useful and takes up a lot of space in the README.md.

fix: run docs/generate.py

10c03c2

ci(webzockets): add Linux and macOS test jobs

9c3e188

- Define test_webzockets job for Linux environment - Define test_webzockets_macos job for macOS environment - Update workflows to run webzockets tests on both platforms

test(webzockets): improve null value diagnostics and fix flakey tests

94d60ef

fix(style): skip cache directories in style script

9d058e6

test(webzockets): stabilize e2e frame and close waits

12ea7ce

- add RawClient wait helpers for message type, close frames, and disconnects - make read timeout configurable and default to 2s to reduce jitter flakes - update close, fragmentation, handshake, and timeout tests to use bounded waits

test(webzockets): handle NoResponse on close frame wait

8bb390a

Sobeston reviewed Feb 10, 2026

View reviewed changes

jbuckmccready added 4 commits February 10, 2026 16:03

docs(webzockets): cleanup doc comments for autobahn client

9402c82

docs(webzockets): simplify server struct field comments

aa9cb5c

test(webzockets): use gpa allocator for autobahn client

744fc9a

refactor(webzockets): pass mask keys by value in mask api

96a343e

jbuckmccready force-pushed the jbuckmccready/webzockets branch from 83cd274 to 96a343e Compare February 11, 2026 01:18

jbuckmccready added 4 commits February 10, 2026 17:32

refactor(webzockets): remove BufferPool mutex

6a75ec7

Also removes need for pool_buffer_size field in Reader.

docs(webzockets): simplify reader struct field comments

189852a

refactor(webzockets): use header_len for outstanding writes

fa599f3

- remove pending_data from client and server write state - add outstandingUserWrite helper for busy, defer, and cleanup checks - clear header_len in finishWrite before invoking onWriteComplete

chore(deps): bump libxev to fix io_uring shutdown unexpected error

279a715

Update libxev dependency hash in both root and webzockets build.zig.zon

jbuckmccready force-pushed the jbuckmccready/webzockets branch from 46fbfc7 to 0639fd4 Compare February 14, 2026 21:17

jbuckmccready force-pushed the jbuckmccready/webzockets branch from 0639fd4 to 0028053 Compare February 14, 2026 21:30

jbuckmccready added 3 commits February 14, 2026 14:30

docs(webzockets): add onBytesRead callback and read flow control APIs

c5b8056

- Document onBytesRead handler callback - Add pauseReads, resumeReads, peekBufferedBytes connection methods

refactor(webzockets): remove BufferPool

51641cc

- Delete buffer.zig and update all code and docs - Reader now escalates directly from embedded buffer to dynamic allocation

chore: run docs/generate.py

82de667

		pub fn main() !void {
		const allocator = std.heap.c_allocator;

		/// Type-erased context pointer for the shutdown completion callback.
		shutdown_userdata: ?*anyopaque,

		pub fn mask(m: []const u8, payload: []u8) void {
		std.debug.assert(m.len == 4);

Conversation

jbuckmccready commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Update 2026-02-13:

Update 2026-02-14:

Uh oh!

codecov bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbuckmccready Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbuckmccready Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbuckmccready Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbuckmccready Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jbuckmccready commented Feb 9, 2026 •

edited

Loading

codecov bot commented Feb 9, 2026 •

edited

Loading

jbuckmccready Feb 14, 2026 •

edited

Loading

jbuckmccready Feb 11, 2026 •

edited

Loading

jbuckmccready Feb 11, 2026 •

edited

Loading

jbuckmccready Feb 11, 2026 •

edited

Loading