lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

README.md (3035B)


      1 # radroots_transport_nostr_browser
      2 
      3 Origin-thread WebSocket I/O for the existing shared Radroots Nostr session.
      4 `BrowserConnector` is inert; `create_transport` selects this concrete provider.
      5 DOM objects and callbacks remain in one local owner. Cross-boundary futures
      6 contain only owned Rust data and safe channels. There is no second relay pool.
      7 
      8 Received messages are limited to 512 KiB, 256 queued messages and 4 MiB of
      9 queued payload. The original connection admission charges each delivered
     10 message before exposing it to the shared decoder. Refusal closes this socket
     11 and reports an error. Outgoing messages are serialized, bounded, and refused
     12 when the browser's reported buffered amount would exceed 4 MiB. A successful
     13 send means local browser enqueue only; protocol acceptance remains owned by
     14 the shared session. Binary and text remain distinct and unchanged.
     15 
     16 The browser owns DNS, TLS, WebSocket framing, control frames and allocations
     17 before callbacks. This provider cannot pin DNS results, meter plaintext before
     18 decode, observe wire fragmentation or bound the user agent's internal buffers.
     19 It checks literal IP destinations against admission and relies on the shared
     20 explicit URL policy for configured DNS names. Its byte/work charges describe
     21 delivered payload and message starts, not native wire framing. Ping/pong are
     22 unsupported. User-agent error objects and close reasons are not diagnostics.
     23 Use `Socket::close` for local close; sending a control-frame variant is refused.
     24 
     25 The pinned upstream session requires one compile-time time-provider selection
     26 in a final WASM artifact. That artifact root must bind the provider to real
     27 browser monotonic and wall clocks. This library exports no global provider
     28 symbol. The source-owned browser I/O fixture makes this artifact-root choice
     29 explicitly; it does not use a simulated clock.
     30 
     31 Explicit close waits for local callback detachment and socket close initiation;
     32 it does not prove a remote close handshake. Cancelling a connect or dropping the
     33 last socket handle requests that same local cleanup. A page or worker being
     34 terminated has no asynchronous completion guarantee. Import and construction
     35 perform no I/O. Non-browser targets refuse connections.
     36 The user agent may retain an underlying pending network task after DOM close;
     37 repeated interrupted handshakes can consume its per-origin connection capacity.
     38 Subsequent calls still consume their original deadlines and cannot infer remote
     39 cleanup from local disposal.
     40 
     41 Cloned `BrowserConnector` handles own one disposal scope, with at most 64 retained
     42 original socket owners. Keep the connector when composing a client. After
     43 stopping the shared protocol session, await its `close` method before closing
     44 storage: it permanently refuses new owners and waits for every original local
     45 socket owner to detach callbacks and initiate close. A cancelled close resumes
     46 the same disposal. Separate connector scopes remain independent. This scope
     47 does not manage protocol membership, grant retries or join upstream SDK tasks.