trystero: serverless WebRTC rooms for C++

<webcpp/trystero.hpp> is the rooms themselves, which build on both of trystero’s targets, native and emscripten, and include neither backend. Each backend is a header of its own:

Both run the same room, and both meet Trystero JS peers. Every name is in the namespace webcpp::trystero.

trystero raises no exception of its own: an operation that can fail completes with an error code. The rooms, the protocol and the browser backend compile without exceptions; so do the native timer, sealer and WebSockets.

A browser program keeps five things alive for as long as its page: an io_context, the browser::event_loop that drives it from the page’s JavaScript events, the browser::backend that implements the platform over the browser’s APIs, the app that owns its identity and shared connections, and the room joined through that app. Actions are made from the room by name and payload type:

<webcpp/trystero/browser/src.hpp> is included in exactly one source file of the program: it defines the functions the page calls into the library with.

Handlers are set once the application exists. This program greets every peer that completes the handshake, prints every chat message, and starts a coroutine that answers the echo action:

The coroutine awaits messages with async_receive and answers with async_send. boost::asio::as_tuple turns the error into a value, so leaving the room ends the loop instead of throwing:

main returns at once. Nothing blocks in a browser: every JavaScript event that reaches the library runs its handlers and then whatever became ready on the io_context (The browser backend).

The same app and its joined room, natively, whole: a program that greets every peer that joins and prints what it receives on chat. A native program runs its io_context itself, since there is no event loop of a page to drive it, and the native backend posts what libdatachannel’s threads report to it:

io.run() returns only when the program is stopped: the room keeps its relays and its peers for as long as it lives.

A b2 project uses the rooms and the browser backend through /webcpp/trystero//trystero, which adds trystero’s headers, Boost’s, libsecp256k1 and Boost.JSON’s definitions, compiled once per variant, and, on emscripten, embind and BOOST_ASIO_DISABLE_THREADS, since the page has no threads:

embind is linked as a flag, -lembind, rather than with b2’s own <embind>on: that feature is not free, and b2 ignores a feature that is not free among usage requirements, so a program that used it would not link.

A native program uses /webcpp/trystero//native, which adds libdatachannel and the same source-built OpenSSL used by Asio and Beast:

The native backend uses worker threads, so each consumer declares <threading>multi. Its OpenSSL dependency is the matching threaded variant; a single-threaded native backend is rejected before compilation.

The native backend’s WebRTC also needs exceptions (Exceptions), and b2 lets no usage requirement override a build’s exception-handling=off, so each program and test that uses it declares <exception-handling>on itself, as the examples do:

and as trystero’s own tests of the native backend’s connections do:

A browser program is linked for the web, with a memory that grows:

The emscripten target is b2’s emscripten toolset, registered against Emscripten 6.0.11 from emsdk, as a user-config.jam declares it, where $(emsdk) is the emsdk’s directory and $(node) the node that runs a program:

With it, libsecp256k1 installed and the pinned source submodules initialized, from the root of a webcpp checkout, these build the tests and the examples, natively and on emscripten:

libsecp256k1 is built twice: natively, and with Emscripten for the browser. Its small tables keep the browser’s download small:

where webcpp is the checkout of the superproject: each is installed in the directory of .local/ where the build looks for it.

Initialize the native dependencies from the superproject root:

Install CMake 3.21 or newer, Perl and Make (native Windows Perl and nmake with MSVC). B2 builds OpenSSL, libdatachannel and its pinned nested libjuice, usrsctp and libsrtp sources for the configured compiler, standard library, runtime and build variant. Upstream sources are verified and copied to a disposable build directory; the checkout is never patched. The resulting headers and separate static archives stay in B2’s variant directory, and the final link contains exactly one OpenSSL archive pair.

libdatachannel’s own WebSocket, examples and tests are disabled; media transport remains enabled. System OpenSSL and installed libdatachannel binaries are never fallback providers. A combined Asio/Beast/Trystero application uses the same native <threading>multi configuration for all three libraries.

The three examples need the public relays or a browser, so the build links them and never runs them: native_quick_start.cpp, natively; quick_start.cpp, a .js and a .wasm to embed in a page; and the chat, a page whose room is C++ (A page and its program). The quick starts meet in the room lobby of the app webcpp-trystero-quick-start, over the public relays; the chat joins the app and the room its user types, the room lobby of the app webcpp-trystero-chat unless the user changes them, and meets the quick starts when the user types theirs.

The native quick start is built as a program of its own, and runs until it is stopped:

The chat is a page and its program, which the target site copies into a directory of its own under the build directory, out of the tree, and prints. The page is served from localhost, where crypto.subtle exists:

At http://localhost:8000, joining the app webcpp-trystero-quick-start, in place of the page’s webcpp-trystero-chat, and the room lobby brings the native quick start in as a peer within seconds: its greeting appears in the chat, and what the page sends is printed in its terminal. On another toolset, site stops the build, saying that the page is built on emscripten alone.

An app is this program in one application and password domain: one peer id, one immutable password, and one connection to each remote peer, which every room of the app it shares with that peer uses, as a Trystero JS page shares them. Constructing it takes the executor every handler and completion runs on, the backend, which must outlive it, and its configuration, app_config, moved. A room is joined with join, which returns a boost::system::result<room> to test, or an error: error::already_joined while a room of that id is joined in the app, and error::too_many_rooms when 64 rooms count, since a peer drops a connection that advertises more. Joining an id in its 99 ms farewell finishes that farewell first and joins afresh.

join and the app’s other methods run where its executor runs. An app and all its rooms use that executor; a multithreaded io_context needs a strand. Destroying or moving over the app handle releases it; its rooms keep the app’s state alive and continue. Two app objects, even with the same app id, are two peers. Rooms with different passwords use separate apps with distinct self ids. A room has no password override; changing the domain password requires a new app. No registry or identity is kept in static storage.

app_config is move-only because its log sink is a handler: pass it moved, or build it in place. Each room adds room_options:

on_peer_join and on_peer_leave set what is called with each peer whose handshake completed, and with each joined peer that leaves; peers() lists the joined peers. on_error sets what is called with each problem with one peer that the room handled itself, as Trystero’s onPeerError: a peer with signals under another password, a malformed room proof, a handshake that timed out, a connection the backend refused. It is called with an empty peer id for a count of signals that did not open with the room key (Bounded signaling). Each handler replaces the one set before, and every view it receives is valid for the call.

async_ping measures the round trip to a joined peer, from sending @_ping to receiving its @_pong.

async_leave says goodbye to every peer, Trystero’s @_leave, gives the farewell 99 ms, as Trystero waits, then detaches its bindings and closes its relay sockets, and every pending operation completes with error::room_left. Destroying a room leaves at once, without the 99 ms, and so does assigning another room over a joined one: every peer is told, and every pending operation completes with error::room_left, even while an action of it lives.

A kick or a peer’s @_leave ends only that room’s binding: the app’s other rooms keep using the connection. When it stays live, rebinding waits one step after the end, initially the larger of handshake_timeout and 10 s, plus 1 s, doubling after each further end to at most 5 minutes. A completed handshake or the connection’s end resets the count. After its own kick the lower id refuses bindings until that time and keeps frames; the higher id drops frames until it sends presence, but accepts the lower id’s presence. A binding also requires the peer to have advertised the token itself. A peer on a protected app’s shared connection already authenticated with that app’s password through the initial sealed negotiation. A peer that knows it can still send a wrong room proof: only the lower id reports that proof as wrong_password; the higher id answers and sees a departure. Malformed challenge data is rejected by its receiver too. This room handshake retains Trystero JS 0.26.0’s one-way wire behavior.

An action is a named channel of messages, wire compatible with Trystero’s makeAction. Its name has 1 to 32 UTF-8 bytes and no NUL; with another, every send fails with error::invalid_action_name. Its type says how messages travel and how they are received:

A message of another format than the action’s type is not delivered to it. Several actions of different types may share a name: one receives as views, another sends by moving strings, as the chat does (A page and its program).

Messages arrive at the handler on_message sets, with a message_info: the sender’s id and the metadata it passed. Without a handler they queue, up to 1024 per action, the oldest dropped first, for async_receive, which needs an owning type: a view would outlive the message. Frames of an action that arrived before it was made are kept, 64 per peer for 120 s, and delivered to it once it is.

async_send sends to send_options::targets, or to every joined peer, with optional JSON metadata. A payload that fits one 16 KiB frame with its header and metadata travels inline; a larger one is offered, accepted by the receiver within 120 s, and sent in chunks of at most 16,370 bytes. A frame or a chunk is handed to the data channel only while the channel buffers at most 64 KiB, waiting at most 10 s for it to drain. async_send completes once each target’s local data channel has taken the inline frame, or the last chunk of the transfer the receiver accepted, with the first failure if any, as Trystero’s send resolves: nothing confirms that the receiver has the message. A receiver takes one transfer per peer at a time, accepts it only for an action with a receiver, and reserves at most max_receive_bytes across peers.

Every asynchronous operation is an Asio initiating function. With a callback it calls it on the room’s executor; with boost::asio::use_awaitable it resumes a coroutine; with boost::asio::deferred it returns an operation started later.

Because a deferred operation starts after the call, the arguments of an asynchronous operation are owned: async_send takes its value by value, moved when the type owns its storage, copied once at the call into the room’s resource when it is a view, and serialized at once when it is a boost::json::value; send_options owns its strings; and async_ping copies the peer id at the call. Everything else that only reads text takes a std::string_view.

Operations complete with a boost::system::error_code in the category webcpp.trystero, of the enumeration error:

All resource access runs on the app’s executor. A resource need not be thread-safe when that executor runs on one thread; several io_context threads require a strand.

The allocation test builds every part of app_config in its counted resource before the counting window, including strings, relay URLs, ICE servers and log sink; app_config_in and options_in name both resources:

The app’s resource must outlive its state: the app handle, every room of it, retained values allocated there and every pending operation. A room’s own resource must outlive that room, its retained std::pmr::string, pmr_bytes and boost::json::value values, and its pending operations. Destroying a handle closes its work but queued completions can still free memory. Declare both app_config::memory and room_options::memory resources before the io_context, then construct the backend, app and rooms. Drain or destroy the io_context before destroying either resource. In the browser, keep them until all pending promises settle: the page’s event_loop registrations retain their handlers, so in practice resources live for the page’s life.

No check in debug builds catches the misuse: trystero holds a raw pointer and cannot see the resource end, and the use comes after the room is gone, from an operation of Asio’s or of the browser’s. A resource that asserts nothing is out when it is destroyed, as the test’s counting resources do, is the check, and it is the user’s.

A room allocates and frees on every event, a frame, a parsed text, a post or a log line, so a resource that reuses what is freed, a pool such as std::pmr::unsynchronized_pool_resource, suits a long-lived room; a std::pmr::monotonic_buffer_resource grows with every event and suits a short-lived one, or a test.

A completion handler is the user’s, and is allocated as its own associated allocator says: the room never binds its allocator over it. boost::asio::bind_allocator gives one the room’s resource. The allocation test makes the allocator of a resource:

and binds it over the completions of a transfer and of a ping, so that they too are allocated in the sender’s resource:

When the room erases a completion handler’s type (an any_completion_handler), it records whether the handler’s associated executor is the room’s, which only the concrete type tells without allocating; such a completion runs from an operation the room posts to its executor, allocated with the handler’s allocator. One bound to another executor is handed to that executor by Asio, whose type-erased executor wraps it with std::allocator.

Every container trystero declares is a std::pmr one: std::pmr::string (and peer_id), std::pmr::vector (and backend::bytes, protocol::bytes and pmr_bytes), std::pmr::deque, std::pmr::map, std::pmr::set, std::pmr::unordered_map and std::pmr::unordered_set, built over their owner’s resource; app_config, room_options, send_options, message_info and backend::ice_server hold them too. Two types stay the user’s choice of std::allocator: trystero::bytes, a std::vector<std::uint8_t>, and trystero::payload, a variant of std::string, boost::json::value and bytes. A received bytes, or the binary of a payload, is a copy of the frame, which starts in the app’s resource.

A struct that holds std::pmr containers takes the room’s std::pmr::polymorphic_allocator<> in its constructor, and a container of such structs is given it when it makes one, with try_emplace(key, allocator). A std::pmr container is never copied without an allocator: its copy constructor takes the default resource, so a copy names the resource, std::pmr::string(text, allocator). Moving keeps the resource.

Shared objects are made with std::allocate_shared over std::pmr::polymorphic_allocator<>, never with std::make_shared, std::make_unique or new; a timer is a std::shared_ptr for that reason.

std::function takes no allocator since C++17, so trystero holds every handler it keeps in handler<R(Args...)>, a move-only callable that allocates through a std::pmr::polymorphic_allocator<>. Constructed with handler(std::allocator_arg, allocator, f), it holds f inline when f fits in three pointers and is nothrow-movable, and in storage of the allocator otherwise. It replaces every std::function of the backend interface (the handlers of its timer, WebSocket, data channel, peer connection and sealer), of the room and of the log’s sink. Constructed from f alone it uses the default resource; the app moves app_config::log into its resource with the allocator-extended move. A move assignment carries the source’s allocator with its target.

Asio. Every post, dispatch, timer wait and any_completion_handler the room makes carries boost::asio::bind_allocator over its resource. A post through boost::asio::any_io_executor is wrapped by Asio in a function object allocated with std::allocator, from Asio’s per-thread recycling cache, which calls std::aligned_alloc on a miss (measured: two per post, in every round of five posts, natively and on emscripten). So the room posts through the executor of an io_context when its executor is one, where Asio allocates the operation as the handler’s allocator says; on another executor, as the browser’s event_loop executor, the wrapper stays Asio’s.

The backends. Each method of backend::factory that makes an object takes a std::pmr::memory_resource* as its last parameter. Peer connections, data channels and received frames use the app’s resource; relay sockets, sealers and room timers use the room’s. Objects and their handlers allocate through that supplied resource.

Boost.JSON allocates through json_resource, a boost::container::pmr::memory_resource that forwards to a std::pmr::memory_resource, header-only: the global resources of boost::container::pmr are compiled, and webcpp’s CI installs Boost’s headers alone. The room’s JSON storage is made once, when the room is constructed, since a value a handler keeps may outlive the room. Text is parsed by a boost::json::parser over that storage, never by boost::json::parse, whose temporaries beyond a stack buffer come from the default resource, and JSON is written by a boost::json::serializer whose stack is the resource.

The protocol (protocol/) takes a std::pmr::memory_resource* as the last parameter of every function that returns what it allocates, with the default resource as its default, and returns std::pmr types. protocol::nostr::verify uses secp256k1_context_static and allocates nothing.

The browser’s event_loop and the test’s memory relays are shared by every room of a page or of a test: they allocate the entries of their registrations and their relays through the resource they are constructed with, and a registered callback stays in its own resource, a room’s for a room’s object.

test/allocation_test.cpp, on both targets, counts the global operator new, which it replaces, and the C library’s allocation functions, where the platform lets a program see them: glibc’s are replaced and forward to __libc_*, Emscripten’s dlmalloc has weak definitions the test replaces, and macOS reports each to malloc_logger; MSVC’s are not counted, nor any under AddressSanitizer, whose own allocator reports to none of these. Only the thread main runs on is counted.

The counting resources also count a return of memory they never gave, a std::pmr object freed through the wrong resource, which must be none. Asio’s once-per-context allocations are made before anything is counted; without them the count is 8, not 2. On Emscripten the test also replaces select() with one that keeps its array on the stack, so that the count sees the rooms’ allocations rather than the C library’s wait. The test is declared in test/Jamfile:

In a browser nothing may block, and the page’s JavaScript event loop is the only source of events. An io_context never runs on its own there: browser::event_loop drives it without ever calling run().

So nothing runs while nothing happens, and a handler runs as soon as its event does. Two alternatives were rejected: poll() from emscripten_set_main_loop costs 60 wake-ups a second and stops in hidden tabs, where requestAnimationFrame does; poll() on a fixed interval costs wake-ups and up to an interval of latency. The backend’s timers are setTimeout, so their expiry is a JavaScript event like any other.

The page calls one function, trystero_dispatch, which <webcpp/trystero/browser/src.hpp> exports. A JavaScript handler is that function bound to the event loop, a registration and a slot. An object registers a callback with the loop and removes it when it is destroyed, so a late event for a destroyed object finds nothing; a destroyed loop marks every handler it made as dead.

Text that crosses into JavaScript is decoded straight from the WebAssembly memory a view points into, by a TextDecoder the loop keeps, and text that comes back is encoded by a TextEncoder straight into a string of the object’s resource: no std::string is made to carry either.

The browser backend makes every call into JavaScript that can throw, a constructor, JSON.parse, a send, a WebRTC or Web Crypto method, through one function defined once in browser/src.hpp with EM_JS, which runs it inside try and returns a value or the exception as a value; the C++ turns that into the error its interface has. Every event of the page enters C++ through a function of the same file that catches what still escapes, puts WebAssembly’s stack pointer and the loop’s depth back as they were before the call, reports it and lets the loop poll again. With exceptions, browser::dispatch catches a C++ exception first, which frees it: one that reached JavaScript would keep its object for good. So a program that uses the browser backend may be built with exceptions or without them, and a peer’s malformed message never stops the page’s loop.

Peer connections, data channels and received frames use the app’s resource; relay sockets and sealed signaling texts use the room’s. Presence or reuse binds another room without making another peer connection.

The chat example is a page whose room is C++: the program joins and sends, and the page only draws. It keeps the loop, the backend and the room for the page’s life, and makes the action chat twice: once as std::string_view, to receive a message as a view of its frame, and once as std::string, to send by moving the text:

The page calls join with the app and the room its user typed, and the program joins and sets its handlers; a received message goes from its frame straight into a JavaScript string:

send shows the message at once, and reports a failure in the page’s log:

The two functions are what the program exports to the page, through embind:

Any Trystero JS page, or any other page of the chat, that joins the same app and room is in the same chat (Running the examples).

trystero raises no exception of its own, but libdatachannel reports errors by throwing, and the native backend’s data channel and peer connection catch what it throws on refused input and complete with error::backend_failure. So they need exceptions: without them, or with WEBCPP_NO_EXCEPTIONS or WEBCPP_TRYSTERO_NO_EXCEPTIONS defined, native::data_channel, native::peer_connection and native::backend, which makes their objects, do not exist, and code that uses them does not compile. The native timer, sealer and WebSockets, and the rest of trystero, are unchanged.

<webcpp/trystero/config.hpp>, which every header includes first, defines WEBCPP_TRYSTERO_NO_EXCEPTIONS when webcpp has no exceptions (WEBCPP_HAS_EXCEPTIONS is not defined: the compiler has none, or the program defined WEBCPP_NO_EXCEPTIONS); a developer may define it for trystero alone in a build that has them. Each program and test that uses the native backend’s WebRTC declares <exception-handling>on itself, whatever the build asks (In a b2 project). One function of the backend throws: its constructor, a boost::system::system_error when OpenSSL cannot make the TLS context or load the system’s certificate authorities.

libdatachannel delivers its events on threads of its own. The backend never runs a handler there: each event copies what it carries and is posted to the room’s executor, through a weak reference, so an event that arrives after its object is gone does nothing. Every handler of the room and every completion runs on the executor, as in the browser. An application that runs the io_context on several threads gives the app a strand, shared by all its rooms.

A received data channel message is copied once, out of libdatachannel’s std::vector<std::byte> into the app’s resource, on the executor. A view handler reads it there. A binary payload moves when its message buffer and the room use the same resource, and is copied once otherwise; chunked transfers assemble their buffer in the room’s resource. A text message, as a peer can send, or a binary one larger than any room frame, is dropped on libdatachannel’s thread: neither can be a frame.

Valid binary frames that arrive before the message handler is installed wait in a FIFO in the app’s resource. The queue holds at most 64 frames for at most 10 seconds from its first frame. Overflow or expiry closes the channel; closing or destroying it discards the pending frames. The existing native timer invalidates an expiry already queued when the queue drains or closes. Installing a receiver posts delivery on the executor with the app’s allocator. It never calls the receiver inline, and delivery checks the current handler and channel before each frame, so a handler may replace itself or close the channel. A message already queued ahead of that delivery drains older frames first when a receiver is available.

If a transport closes during adoption, before the room obtains a binding, the room forgets that negotiation and restarts announcements. Its later close event cannot leave signaling marked connected with no binding.

native::backend_config is what the backend makes its peer connections with, beside the app’s ice_servers:

The relays are reached over Boost.Beast: ws:// in the clear, wss:// over TLS with SNI and host name verification. The backend verifies relays against the system’s certificate authorities; tls_context() gives the boost::asio::ssl::context to an application with authorities of its own. A relay whose certificate does not verify is unreachable, and the room retries it later as it would any other. The WebSockets are Beast’s rather than libdatachannel’s own, so the relays run on the room’s executor like everything else.

A relay is a third party, and the backend bounds what one can make the room hold:

Each drop reports one close, and the room reconnects with its backoff (Discovery over Nostr). A page has no idle timeout: its WebSocket cannot ping (What a page bounds).

A relay that answers rate-limited: is skipped for 60 s, doubling to 15 minutes while the replies persist; one that answers blocked:, restricted:, auth-required: or pow: is retired. A lost relay is reconnected after a random share of 3.3 s, doubling to 60 s, and the delay comes back to 3.3 s only once a connection stayed open for 60 s, so that a relay that closes the room at once after each open is tried less and less often.

Of two peers, the one with the lower id offers, on the relay that carried the other’s announcement. The higher one answers an announcement by announcing itself on the other’s peer topic, so the lower one offers: at most once a second per peer, and once in 5.3 s per relay for the whole room, Trystero’s announce interval, so that a flood of low ids does not have the relays rate-limit the room. Offers, answers and candidates are sealed with AES-GCM under the SHA-256 of <password>:<app>:<room>, using the immutable app_config::password, empty for a passwordless app, with a 16-byte IV, as the text <iv>$<ciphertext>: the IV’s bytes in decimal joined by commas, and the ciphertext with its tag in base64. Candidates follow their offer or answer, trickled. A negotiation ends when the data channel opens: the app adopts the connection, and signals from a bound peer are ignored. A live connection is reused for another room only after the peer advertised that room’s token itself on the connection.

Every message is a room frame: 1, the length of the room token (16 bits, big-endian), the token, the hexadecimal SHA-256 of Trystero:<app>:<room>, then an action frame. A presence frame, 2, present or not, the token’s length and the token, announces or withdraws the room.

Presence advertises every room of the app on each connection. It records which rooms the remote peer joined and binds matching local rooms; a withdrawal detaches only that room. The connection routes by token:

On binding, kept frames arrive before later frames; a kept @_leave discards itself and everything kept before it for that token. There is no buffer for a bound room awaiting its handler: delivery is installed in the same call that makes its binding.

Waiting sends take turns by binding on each channel drain, preserving each binding’s waiter order and the 10 s stall bound. Chunked transfers send one chunk per drain, giving waiting sends from other rooms a turn. Inline sends at a buffered amount of at most 64 KiB go straight to the channel: they have no trystero rate bound, so a flood of pings can delay every room’s traffic to that peer, and that peer only.

Action frames are Trystero’s action wire, version 2: an inline frame carries the payload whole; a larger payload is an offer, accepted or refused by the receiver, then chunks of at most 16,370 bytes, in order. Integers and float64 values are big-endian, as JavaScript’s DataView writes them.

The payload’s format is text (0), JSON (1) or binary (2). Internal actions run the room:

The media actions, @_stream, @_track and @_signal, are not ported (Differences from Trystero): a frame of one is ignored.

Announcements are not sealed, so anyone who knows the app and room ids can announce any number of peer ids, and anyone who reads the relays can send any signal in any peer’s name. Trystero JS bounds none of this; trystero bounds what each costs a room.

After a kick or the peer’s @_leave, a live connection is rebound one step after that binding ended. The initial step is the larger of handshake_timeout and 10 s, plus 1 s (11 s by default), doubling at each further end to 5 minutes. Only a completed handshake or the connection’s end resets it. After its own kicks the lower id refuses bindings until its backoff ends, ignores signals and keeps frames; the higher id drops frames until it next sends presence and accepts the lower id’s presence at once. The room sends presence again on reuse or scheduled rebinding, making the other side bind without a relay response. Announcements restart only when no live connection remains. A forged announcement never binds a peer that has not advertised that token itself.

A connection counts against its negotiating room’s 64-per-57-s window even after the app adopts it; presence and reuse make no connections. Fresh ids that connect and depart keep at most 64 x ceil(idle_timeout / 57 s) idle connections per room, 192 by default, within the backend’s own bound. Leaving a room with many peers retains no more connections than the app already held. Kept frames and tokens cost at most about 1 MiB and 8 KiB per connection; each of at most 64 bound rooms retains its own peer bounds. A flood spends its room’s queues, transfers and reservations; routing never holds one room’s frame for another room.

With the lower id an invalid room response proof causes at most six kicks and reports in the first ten minutes, then one per 5 minutes. The higher id can be rebound by a lower-id peer at that peer’s pace, but reports at most one handshake timeout per handshake_timeout, and does not verify a response proof. Malformed challenges are rejected by their receiver and can also report wrong_password; their report rate follows the malicious peer’s repeated bindings, rather than the timeout bound.

A sealed offer or answer holds neither its offer id nor a peer id (Trystero’s wire), so one recorded from the relays still opens when anyone resends it in its sender’s name, and so does the room’s own, sent back to it. A room remembers, by the SHA-256 of their opened text, the last 1024 offers and answers it made or acted on (detail::signaling::remembered_descriptions), and refuses one that comes to it as a peer’s: it changes nothing and is logged. It makes or acts on at most two per connection it makes, so each is remembered for at least an offer’s lifetime (57 s), and in a quiet room for its whole life. So a room refuses a sealed offer or answer it acted on, resent, and one it made itself, sent back as a peer’s offer or answer.

Sharing preserves Trystero JS 0.26.0’s wire. Each C++ app is one password domain: it copies one password at construction, and all its rooms use it. The initial sealed signaling authenticates that password before the data channel is adopted. Later room binding reuses this authenticated connection. There are no per-room overrides, and different passwords require separate apps with distinct self ids. This protects admission to the C++ app’s rooms without changing the room handshake on the wire.

A watcher not connected to the app, without the key, can keep two peers apart. A sealed offer or answer the room neither made nor acted on still opens and is acted on. Such texts are not scarce: every peer seals a fresh offer for any id announced above its own, and announcements need no key. So anyone who reads and publishes on the relays, without the key, can keep any two peers of a room apart from their first meeting for as long as it keeps at it, each attempt costing the other peer a connection of its window. A watcher not connected to the app cannot read or alter anything the peers exchange, join the room, or touch peers already joined; a joined peer that drops is a new peer again. The room refuses only what it made or already acted on. Only a wire that seals the offer id and both peer ids closes this, which Trystero would have to share (reported upstream).

A flooder can delay new peers. Joined peers, memory and connections stay safe under a flood, but a flooder who keeps sending new ids takes each place, or each connection of the window, as it frees, so new peers can be kept out for as long as the flood lasts, each place up to one offer’s lifetime (57 s) at a time. A joined peer whose connection drops comes back as a new peer, with the same id, and is kept out the same way: the room has no renegotiation that would keep its place. Closing it needs announcements that prove the room key, a wire change Trystero would have to share.

A passwordless app’s rooms are open to its connected peers. Presence gives a peer connected through any room the token of every room of that app. Relay events reveal their topics in the clear, and announcements reveal the app’s peer id. The token alone binds the existing connection, and the empty app password goes straight to @_hsready, so that peer can join another room without knowing its id. A watcher not connected to the app still needs the room id to derive its topics and signaling key. Protected rooms belong to another app with a password and a distinct self id. Its presence, tokens and connections never reach the passwordless app.

The upstream one-way handshake remains. The responder to a room challenge answers and passes its side; only the lower id verifies the password proof. A Trystero JS page that itself mixes different passwords on one app’s shared connection can therefore admit a peer to its own higher-id room without that room’s password, and can expose a challenge response for offline guessing. The C++ app-domain boundary does not repair such a JS page. Configure all rooms of one JS app with one password, and use separate page contexts for different password domains. The wire has not gained bilateral room proofs.

A domain member can send an invalid room proof. A peer already connected to a protected C++ app knows its domain password from the initial sealed negotiation. It can nevertheless answer a later room’s challenge incorrectly or send malformed handshake data. The room kicks that binding and applies the documented backoff; only the lower id checks and reports a wrong response. These checks isolate faulty peers within an authenticated domain, rather than admitting another password domain.

One identity links the app’s rooms. Each room announces the same peerId in clear, and connected peers see it across shared rooms. Relay observers and peers can link those rooms to one program. Separate apps provide separate identities and connections for rooms that must remain unlinked. A forged announcement in a connected peer’s name binds nothing: only the peer itself, on its encrypted connection, can advertise the token. It causes no report or rebinding count against that innocent peer.

Two transient cases remain with a Trystero JS lower id. If it binds by reuse during the higher C++ id’s dropping window, its challenge is dropped and its handshake can time out once. With the default 10 s timeout the next rebinding joins by at most 43 s after the first kick plus one-way delay, with no false password error on either side. If a JS page’s timer that expires a stale answer runs later than the 1 s margin before presence arrives, JS can flush the old answer into a new handshake and report a false password error. One-minute timer lag can repeat this at the 11, 22 and 44 s steps, at most three times, before the 88 s step exceeds that lag. The C++ side reports nothing false in either case.

Everything above the backend interface is the core, which builds on both targets: the same room runs over the browser’s APIs, over libdatachannel, and over the memory relays of the tests (Testing). The core never includes a backend, libdatachannel, OpenSSL or Emscripten: a boundary of the library’s own, which webcpp’s lint checks, keeps it so.

The backend is a handful of abstract classes rather than template parameters. Each of its operations is a call into JavaScript or into a network stack, so a virtual call costs nothing measurable, while the room’s code stays free of templates over the platform and of #ifdef, and the test backend and the browser backend are interchangeable at run time. Every handler a backend invokes runs on the room’s executor, after the call that caused it has returned, never inside it: the room calls these operations from inside handlers whose state a completion run there would change under them.

libdatachannel’s WebAssembly port, datachannel-wasm, has no media and hides the RTCPeerConnection it wraps. Binding the browser’s objects directly through emscripten::val is smaller than that wrapper, reports every error, and leaves the browser’s whole WebRTC stack (capture, codecs, playout) within reach for media.

A parameter that only reads text is a std::string_view, bytes are a std::span, and a string is used where something must own the text: a map key, a member, a capture of a handler that runs later.

The asynchronous operations are the exception, for the reason Completion tokens and ownership gives.

libdatachannel is under the MPL 2.0 and OpenSSL under the Apache License 2.0. Both are needed only by the native backend, which a browser program never includes: /webcpp/trystero//trystero depends on neither, and /webcpp/trystero//native adds them, as OpenSSL is optional for Asio.

The library is distributed under the Boost Software License. It ports Trystero’s protocol and was written with Trystero’s source open, so Trystero’s MIT notice comes with it (Acknowledgements).

A room needs relays and peers, and a test needs neither the network nor another machine. The backend interface is the seam: a program’s tests run its rooms over a backend of their own, in memory, as trystero’s own tests run whole rooms over test/support/memory_backend.hpp, a backend whose Nostr relays forward ephemeral events to matching subscriptions, whose peer connections pair through their descriptions, whose data channels deliver in order, and whose sealer opens only what was sealed under the same key, each event posted to the io_context. It is in the namespace webcpp::trystero::test, outside the library’s public headers, and a program may copy it.

The memory network identifies connection ends with std::size_t ids. on_made records construction and ICE servers, and peer_of identifies the paired end. A filter delivers, drops or holds frames; a held frame holds all later frames from its sending end behind it, preserving channel order until release. Deferred open calls open each end separately; inject and fail supply malformed frames and transport failure.

With channel_capacity enabled, the channel queues bytes and drains up to drain_per_post per post. It delivers a frame only after its last byte drains, and buffered reports the exact unsent amount. Set virtual_clock before making timers: advance fires due timers in order and runs ready work between them; step and poll_ready give tests finer control. Timeouts, backoffs and late frames are tested without wall-clock sleeps. Optional fault hooks allocate outside the measured resources only when enabled; the allocation test leaves them disabled.

A test of the native backend’s own WebRTC binds its connections to the loopback, native::backend_config::bind_address set to "127.0.0.1", and names a STUN server where nothing answers, stun:127.0.0.1:9, in place of Trystero’s public ones: the loopback’s host candidate is then the only one, and it is enough.

trystero’s tests are under test/, each declared in test/Jamfile, and each guarantee of Guarantees names the tests that hold it. They run on two targets: 75 tests in all, 54 natively and 60 on emscripten, under node. The protocol, the rooms and the allocation test run on both:

The native backend’s connections need exceptions whatever the build asks (Exceptions), and each browser test is also built without exceptions, as a program that uses the browser backend may be:

From the root of a webcpp checkout, with the three libraries of Building found, each of these builds and runs the tests, natively, under AddressSanitizer and UndefinedBehaviorSanitizer, and on emscripten:

The 3 examples are linked and never run, since each needs the public relays or a browser. b2 compares timestamps, so a result that counts is built from scratch, with b2 -a.

Two lanes of trystero’s own, declared in test/oracle/Jamfile, check it against Trystero itself, pinned at 0.26.0 by test/oracle/package.json and package-lock.json, with Node:

oracle, which names no target, runs Trystero’s own functions over the inputs of test/fixtures/cases/protocol.json and checks that they still write test/fixtures/expected/expected.json byte for byte, the values the protocol and native_sealer tests reproduce; update-expected is its only writer.

interop, natively and on emscripten, meets each C++ peer, the native one as a process and the browser’s in headless Chrome, with Trystero JS peers in Chrome, over an in-memory Nostr relay on 127.0.0.1 that verifies every event’s id and signature as a public relay does. Its scenarios: the C++ peer offering; Trystero JS offering, with a password; a Trystero JS peer that also sends malformed candidates, or text messages on its data channel; a first relay to which no WebSocket can be made; a C++ peer given a TURN server without credentials; a watcher without the key that answers every offer with garbage in the other peer’s name, that resends a sealed answer and offer it recorded, and that sends the C++ peer its own sealed offer back, which the C++ peer must refuse; a flood of announcements and of unsealed offers from fresh peer ids; a relay text longer than 1 MiB; a C++ peer and a Trystero JS page each in two rooms of one app, sharing one connection and one peer id per app; a wrong password; and a mesh of three. The native peer meets three more: a room moved over the joined one, which must leave it as destroying it does; a relay that ends the connection just as the peer writes, which twelve peers in turn must survive; and the driver’s own check that a peer killed by a signal is named at once.

The shared-connection scenarios run in both lanes:

The C++ peers accept room2Delay and room3Delay in milliseconds; the JS page also accepts room2Delay. These delayed joins establish the first room before a shared-binding scenario begins; the proof-pacing scenario first authenticates the shared password domain, then corrupts room proofs after the initial announcement burst.

The adoption scenarios allow crossed duplicates to retry, but fail with connection counts if either side constructs more than four. Transient recovery accounts for JS reuse during the higher id’s dropping window (What remains).

Every peer gathers its ICE candidates on the machine alone: the C++ peers get stun:127.0.0.1:9 in place of Trystero’s public STUN servers, the native peer binds its connections to 127.0.0.1, and the Trystero JS peers have no ICE server. Chrome is the one CHROME names, else on macOS Playwright’s chrome-headless-shell; the continuous integration names Chrome for Testing’s chrome-headless-shell, at the version webcpp pins. Each driver is bounded by 2,400 s, beyond its scenarios’ own limits, so that a scenario that does not complete fails by name with what each peer saw.

Two lanes of the continuous integration, gcc-14 and clang-linux-18, build and run the unit tests with GCC 14 and with clang 18 against libstdc++ in a Linux container, Ubuntu 24.04, with docker run and the network none, which leaves the loopback alone: every test passes, which shows that none reaches beyond the machine (guarantee 6). libsecp256k1 is installed before running the container. B2 builds the pinned OpenSSL, libdatachannel and nested source dependencies inside the container with the lane’s compiler, runtime and static link configuration. These builds need no network access.

The native provider-integration lane builds and runs one application that uses Asio TLS, Beast and Trystero’s native backend together. It compares the compiled OpenSSL version with the loaded implementation and constructs TLS and WebRTC state. The run is bounded to 45 seconds and uses the threaded release profile. The superproject’s source dependency tests also check that the final Unix executable has no dynamic OpenSSL or libdatachannel provider, that each static archive occurs once and that dependent archives precede OpenSSL in the link order.

The continuous integration runs trystero’s tests in lanes, one toolset each, and its own lanes, the oracle once and the interop natively and on emscripten, as native.trystero.interop and emscripten.trystero.interop, plus the native provider-integration lane for the common TLS provider. Each lane builds from scratch and records what b2 built and ran; webcpp’s tools/report/report.py merges the files of every lane into a matrix, where each cell says whether that program passed in that lane, or how it failed. The matrix is published with the documentation, at https://webcpporg.github.io/report/.

A callable that allocates through a memory resource: what trystero holds every handler in, where std::function, which takes no allocator since C++17, would allocate with operator new.

The seam between the room and a platform: what a target must provide for a room to run on it. The browser provides it over emscripten::val (webcpp/trystero/browser), a native target over libdatachannel, Boost.Beast and OpenSSL (webcpp/trystero/native), and the tests over memory (test/support).

A data channel frame, in the memory resource of the room it is for.

A WebRTC data channel, as the RTCDataChannel a Trystero peer exchanges its frames over.

What a data channel reports, each on the room’s executor.

The buffered amount fell to low_threshold or below after being above it.

The channel closed; called once.

A binary message arrived, handed over in the room’s resource.

The channel opened.

Destroys the channel, which closes it without reporting the close.

The bytes queued to send, its bufferedAmount.

Closes the channel, which the handler close reports.

Whether the channel is open, its readyState "open".

Sends a binary message; one sent while the channel is not open is dropped.

Replaces the handlers; a handler may replace them during its own call.

Trystero’s backpressure threshold, its bufferedAmountLowThreshold: senders wait while more than 64 KiB is buffered.

Makes everything above, and gives a room its randomness and its clocks: one per page in the browser, one per application natively, one per test.

Destroys the factory, which must outlive every room that uses it.

Opens a WebSocket to a relay.

Makes a peer connection that gathers its candidates through servers.

Makes a sealer under a room’s key.

Makes a timer.

A monotonic clock in milliseconds, for rate limits and timeouts, as performance.now().

Fills out with bytes from a cryptographically secure source: they become secret keys and nonces.

Wall-clock seconds since the Unix epoch, for Nostr’s created_at and since.

A STUN or TURN server, an RTCIceServer of the iceServers Trystero gives RTCPeerConnection.

The TURN server’s credential; empty for a STUN server.

The server’s URLs, as "stun:stun.l.google.com:19302" or "turn:host:3478".

The TURN server’s user name; empty for a STUN server.

A WebRTC peer connection, as the RTCPeerConnection of a Trystero peer, whose negotiation the signaling drives: it makes an offer or an answer only when asked to.

What a peer connection reports, each on the room’s executor.

The remote peer opened a data channel.

A local ICE candidate, the JSON of an RTCIceCandidateInit, valid for the call.

The connection’s state changed.

Destroys the connection, which closes it without reporting the close.

Adds a remote ICE candidate, like addIceCandidate().

Closes the connection and its channels.

Opens a data channel, like createDataChannel().

Whether a remote description was applied, which a candidate needs before it is added.

Replaces the handlers; a handler may replace them during its own call.

Creates the offer or the answer the signaling state calls for and applies it, like setLocalDescription().

Applies the remote peer’s offer or answer, like setRemoteDescription().

AES-GCM under one room key, in Trystero’s sealed text form (protocol/signal.hpp), what Trystero’s encrypt and decrypt do with crypto.subtle.

Destroys the sealer.

Opens a sealed text.

Seals a text under a fresh random IV.

A one-shot timer, what the setTimeout calls of Trystero become.

Destroys the timer, which cancels a pending expiry.

Cancels the pending expiry, if any, whose handler is then never called.

Calls fire on the room’s executor once delay has passed, in place of a pending expiry.

A WebSocket to a Nostr relay, as the WebSocket Trystero’s relay manager opens.

What a WebSocket reports, each on the room’s executor.

The connection closed, or failed to open: called once, also when it never opened.

A text message arrived; the view is valid for the duration of the call.

The connection opened: messages can be sent.

Destroys the WebSocket, which closes it without reporting the close.

Closes the connection, which the handler close reports.

Sends a text message; one sent before the connection opens or after it closes is dropped.

The state of a peer connection, as RTCPeerConnection reports it.

Nothing has happened yet: "new".

The connection is being established: "connecting", or ICE’s "checking".

The connection works: "connected", or ICE’s "completed".

The connection was lost, perhaps for a moment: "disconnected".

The connection failed: "failed".

The connection was closed: "closed".

The error code every completion of a backend reports, empty on success.

The browser target: the backend interface over the page’s own WebSocket, RTCPeerConnection, RTCDataChannel, setTimeout and crypto.subtle, through emscripten::val. It needs a secure context (https, or http on localhost), where crypto.subtle exists.

The browser’s factory: one per page, beside the page’s event_loop.

Constructs the page’s backend.

Opens a WebSocket to a relay, with the page’s WebSocket.

Makes a peer connection, with the page’s RTCPeerConnection.

Makes a sealer, over crypto.subtle.

Makes a timer, over setTimeout.

Milliseconds from performance.now().

Fills out with the page’s entropy, which Emscripten draws from crypto.getRandomValues.

Seconds since the Unix epoch, from Date.now().

The most RTCPeerConnection objects the page’s rooms hold, every backend of the page together, counted from their construction until the garbage collector frees them: half of the 500 Chromium allows a page, which it counts the same way, so that a closed connection still counts until a collection the page cannot ask for.

A data channel over the page’s RTCDataChannel, its messages received as ArrayBuffer objects.

Wraps a channel of the page, and takes over its events.

Destroys the wrapper, which closes the channel without reporting the close.

The bytes queued to send.

Closes the channel, which the handler close reports.

Whether the channel is open.