sonic-ws

sonic-ws

The socket library that handle correctness, security, and performance for you

SonicWS is a schema-driven WebSocket library for multiple languages. It uses a shared Rust packet codec, to provide compact binary packets, validation before listener execution, batching, compression, built-in rate limiting, and more.

It is designed for real-time applications such as games, dashboards, collaborative tools, and distributed systems where packet correctness, bandwidth efficiency, and predictable socket lifecycle behavior matter.

Why SonicWS?

• Define exactly which packets each side may send.
• Reject invalid packets before user callbacks run.
• Use compact numeric packet IDs instead of repeated string keys.
• Share the same packet codec across Node and browser clients.
• Batch, validate, compress, and rate-limit packets with minimal boilerplate.
• Code is much more readable than every other socket library*

HOW IT WORKS

You define the packets each side is allowed to send. SonicWS exchanges that schema during the connection handshake, assigns compact numeric packet IDs, and validates incoming data before calling your listeners.

The TypeScript/python layer handles connections, packet definitions, middleware, and the public API. The Rust core handles the wire format:

• Primitive and object packet encoding/decoding
• Packet validation and range checks
• Enum, string, boolean, varint, delta, float, and hex codecs
• Object framing, batching, and raw DEFLATE compression
• TypeScript/Python-side JSON conversion transported through reserved wire type 16 as raw bytes

The same Rust implementation is exposed through N-API for native Node use and through WASM for browsers, Python, and the portable Node fallback. Python loads its packaged WASM core through wasmtime, so the Python package does not need separate SonicWS DLL, dylib, or shared-object releases. Protocol behavior therefore does not depend on which runtime is connected.

Automatic browser-file serving at /SonicWS/bundle.js and /SonicWS/bundle.wasm is supported only by the Node.js server, where it can be installed directly on the native HTTP server. If the SonicWS server is written in Python or another language, serve the browser files yourself or use the CDN bundle:

<script src="https://cdn.jsdelivr.net/gh/liwybloc/sonic-ws/release/SonicWS_bundle"></script>

The browser loader prefers the server's local bundle.wasm. If it isn't available, it verifies that jsDelivr's release protocol matches the client and then loads the CDN WASM module. Initialization fails on a version mismatch or invalid download.

INSTALLATION

NodeJS/Typescript:

npm install sonic-ws

Python* (*unpublished currently):

pip install sonic-ws

BUILDING AND TESTING

Building requires Node.js, Rust with the wasm32-unknown-unknown target, and wasm-pack.

From the repository root, use the build dispatcher:

./build.sh all       # Build every project
./build.sh rust      # Rust core only
./build.sh ts        # Complete Node/browser package
./build.sh py        # Python wheel and sdist
./build.sh test      # Run all test suites
./build.sh help      # List every target

The underlying TypeScript commands can also be run directly:

cd projects/ts
npm install
npm run build       # TypeScript, Node WASM, browser WASM, and browser bundle
npm run build_node  # Node distribution and WASM fallback
npm run build_web   # Browser bundle and WASM
npm run test_node   # Node end-to-end packet tests
npm run test_web    # Headless browser/WASM end-to-end tests

The workspace is split into projects/core, projects/ts, and projects/py. Each project owns its source, tests, and packaging configuration. Shared browser artifacts remain at bundled/bundle.js and bundled/bundle.wasm.

Build or install the Python project separately:

python -m pip install ./projects/py

Full API documentation:

• TypeScript / Node / browser
• Python

Packet schemas can now map the existing single-type wire format directly to application objects:

const entitySnapshot = CreatePacket({
  tag: "entitySnapshot",
  type: PacketType.VARINT,
  schema: ["id", "type", "x", "y", "z", "pitch", "yaw"],
  autoFlatten: true,
});

await ws.send("entitySnapshot", [...entities.values()]);

This remains a homogeneous VARINT packet. Schema mapping, row-major autoFlatten, object-packet autoTranspose, quantization, bounds, and packet groups are application-layer conveniences and do not turn the codec into a mixed-type serializer. See the packet documentation above for TypeScript and Python examples.

KNOWN ISSUES

• KEY_EFFECTIVE is reserved but still a work in progress.
• Native .node addons are platform-specific. WASM is used as the portable fallback, while prebuilt native binaries will need separate builds for each supported operating system and architecture.

PLANNED FEATURES

• Better encoding for the first packet that sends packet information
• Publish the Rust core as a standalone, documented crate
• Add first-class Go bindings
• Provide prebuilt N-API binaries for the main Node platforms to avoid using WASM for the server

LICENSE

This project is source-available.

You are free to use, modify, and contribute for personal, non-commercial purposes.

Commercial use requires a separate license. Please contact me regarding information on this.