Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (64 loc) · 4.65 KB

CLAUDE.md

File metadata and controls

87 lines (64 loc) · 4.65 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Commands

# Development environment (requires Nix)
nix develop          # Enter dev shell with all tools

# Rust
just check           # Full CI: clippy, fmt, feature powerset, cargo-shear, cargo-sort, biome
just test            # Run all tests including WASM targets
just fix             # Auto-fix: clippy, fmt, cargo-shear, cargo-sort, biome
cargo test -p <crate>                    # Test a single crate
cargo check -p <crate>                   # Check a single crate
cargo test -p <crate> -- <test_name>     # Run a single test

# JavaScript/TypeScript — use bun, never pnpm/npm/yarn
bun install          # Install JS dependencies
bun run check        # Biome lint
bun run fix          # Biome auto-fix

Architecture

Rust/TypeScript monorepo implementing WebTransport (bidirectional streams + datagrams over HTTP/3 + QUIC) with multiple backend adapters. Organized into rs/ (Rust crates) and js/ (TypeScript packages).

Rust Crates (rs/)

                        web-transport
                  (platform-agnostic router)
                    /                  \
          [native targets]        [wasm32 target]
                  |                     |
    ┌─────────────┼──────────────┐      |
    │             │              │      │
web-transport  web-transport  web-transport  web-transport
   -quinn        -noq         -quiche       -wasm
    │             │              │      (browser WebTransport API)
    └─────────────┼──────────────┘
                  │
          web-transport-proto     web-transport-trait
        (HTTP/3 frame parsing)    (async trait interface)
  • rs/web-transport — Platform router: compiles to quinn on native, wasm bindings in browser. Start here for consumers.
  • rs/web-transport-trait — Shared async trait that all backends implement.
  • rs/web-transport-proto — Low-level HTTP/3 protocol (frame encoding/decoding). Used by all native backends.
  • rs/web-transport-quinn / rs/web-transport-noq / rs/web-transport-quiche — Backend adapters for different QUIC libraries.
  • rs/web-transport-wasm — WASM bindings to the browser's native WebTransport API via wasm-bindgen.
  • rs/web-transport-node — NAPI-RS bridge: compiles Rust to .node binary for Node.js.
  • rs/web-transport-ffi — UniFFI crate exporting WebTransport client/server to Python, Kotlin, and Swift. Default TLS provider is aws-lc-rs; opt in to ring with --no-default-features --features ring.
  • rs/qmux — QMux protocol (draft-ietf-quic-qmux) over TCP/TLS/WebSocket (Rust implementation).

TypeScript Packages (js/)

  • js/qmux (@moq/qmux) — QMux protocol over WebSocket (TypeScript implementation).
  • js/web-transport (@moq/web-transport) — Node.js WebTransport via NAPI-RS (TS wrapper around rs/web-transport-node).
  • js/web-demo — Browser demo app.

Language Bindings (UniFFI)

All built from rs/web-transport-ffi. A single web-transport-ffi-v* tag (pushed by release-plz) drives all three downstream release workflows.

  • py/web-transport — Python wheel, published to PyPI as web-transport-rs. Import name remains web_transport. Pure-Python wrapper at python/web_transport/__init__.py re-creates the legacy exception hierarchy on top of the flat _uniffi.WebTransportError enum.
  • kt/ — Kotlin Multiplatform module (JVM + Android), published to Maven Central as dev.moq:web-transport. The :web-transport gradle module ships JNA-loaded desktop libs (src/jvmMain/resources/<os>-<arch>/) and Android jniLibs/<abi>/.
  • swift/ — Swift Package Manager package. WebTransportFFI.xcframework.zip is attached to the GitHub Release (no SPM mirror yet — re-enable later via vars.PUBLISH_SPM).

WASM Considerations

WASM targets require RUSTFLAGS=--cfg=web_sys_unstable_apis (set in .cargo/config.toml). The web-transport crate uses conditional compilation (target_arch = "wasm32") to route between native and WASM implementations.

Workflow

  • Always run just fix before committing to auto-fix formatting, linting, and sorting issues.

Formatting & Style

  • Rust: cargo fmt, standard rustfmt
  • TypeScript: Biome — tabs, 120 line width, double quotes, LF line endings
  • Both are enforced in just check

Release

Automated via release-plz on push to main. Publishes Rust crates to crates.io. NPM packages use bun run release scripts in each package directory.