Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 249 additions & 34 deletions Cargo.lock

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[workspace]
members = ["noq", "noq-proto", "noq-udp", "bench", "perf", "fuzz"]
default-members = ["noq", "noq-proto", "noq-udp", "bench", "perf"]
members = ["noq", "noq-proto", "noq-udp", "web-transport-moq", "bench", "perf", "fuzz"]
default-members = ["noq", "noq-proto", "noq-udp", "web-transport-moq", "bench", "perf"]
resolver = "2"

[workspace.package]
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@

This is [moq-dev](https://github.com/moq-dev)'s fork of
[n0-computer/noq](https://github.com/n0-computer/noq), published on crates.io as
`moq-noq`, `moq-noq-proto`, and `moq-noq-udp`. It carries the QUIC features
[Media over QUIC](https://github.com/moq-dev/moq) needs before they land
upstream, and it never publishes under the parent's names. `PARENT` names the
`moq-noq`, `moq-noq-proto`, `moq-noq-udp`, and `web-transport-moq`, the
WebTransport adapter over the fork. All four share one version and one release.
It carries the QUIC features [Media over QUIC](https://github.com/moq-dev/moq)
needs before they land upstream, and it never publishes under the parent's
names. `PARENT` names the
upstream commit each release includes, and `moq-sync` merges upstream weekly.
General changes are offered upstream once their shape settles; the carried set
is `git log --no-merges upstream/main..main`.
Expand Down
60 changes: 60 additions & 0 deletions web-transport-moq/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
[package]
name = "web-transport-moq"
description = "WebTransport library for moq-noq, the MoQ fork of Noq"
authors = ["Luke Curley"]
version.workspace = true
repository.workspace = true
license.workspace = true
rust-version.workspace = true
edition = "2021"
workspace = ".."

keywords = ["quic", "http3", "webtransport"]
categories = ["network-programming", "web-programming"]

[package.metadata.docs.rs]
all-features = true

[features]
default = ["aws-lc-rs"]
aws-lc-rs = ["noq/aws-lc-rs", "rustls/aws-lc-rs"]
ring = ["noq/ring", "rustls/ring"]
# Unlocks `noq::TransportConfig::qlog_*`, which this crate re-exports but cannot
# enable on a caller's behalf.
qlog = ["noq/qlog"]

[dependencies]
bytes = "1"
futures = "0.3"
http = "1"
kio = "0.5.4"
noq = { package = "moq-noq", path = "../noq", version = "1.3.0", default-features = false, features = [
"tracing-log",
"platform-verifier",
"runtime-tokio",
"rustls",
"bloom",
] }
rustls = { version = "0.23", default-features = false, features = [
"logging",
"std",
] }
rustls-native-certs = "0.8"
thiserror = "2"
tokio = { version = "1", default-features = false, features = [
"io-util",
"macros",
"time",
] }
tracing = "0.1"
url = "2"
web-transport-proto = "0.6"
web-transport-trait = "0.4"

[dev-dependencies]
anyhow = "1"
clap = { version = "4", features = ["derive"] }
rcgen = "0.14"
rustls-pemfile = "2"
tokio = { version = "1", features = ["full"] }
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
56 changes: 56 additions & 0 deletions web-transport-moq/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
[![crates.io](https://img.shields.io/crates/v/web-transport-moq)](https://crates.io/crates/web-transport-moq)
[![docs.rs](https://img.shields.io/docsrs/web-transport-moq)](https://docs.rs/web-transport-moq)
[![discord](https://img.shields.io/discord/1124083992740761730)](https://discord.gg/FCYF3p99mr)

# web-transport-moq
A wrapper around the [moq-noq](../README.md) API (the MoQ fork of Noq, a Quinn fork), abstracting away the annoying HTTP/3 internals. The same adapter for upstream noq is [web-transport-noq](https://github.com/moq-dev/web-transport).
Provides a QUIC-like API but with web support!

## WebTransport
[WebTransport](https://developer.mozilla.org/en-US/docs/Web/API/WebTransport_API) is a new web API that allows for low-level, bidirectional communication between a client and a server.
It's [available in the browser](https://caniuse.com/webtransport) as an alternative to HTTP and WebSockets.

WebTransport is layered on top of HTTP/3 which itself is layered on top of QUIC.
This library hides that detail and exposes only the QUIC API, delegating as much as possible to the underlying QUIC implementation (Noq, a Quinn fork).

QUIC provides two primary APIs:

## Streams

QUIC streams are ordered, reliable, flow-controlled, and optionally bidirectional.
Both endpoints can create and close streams (including an error code) with no overhead.
You can think of them as TCP connections, but shared over a single QUIC connection.

## Datagrams

QUIC datagrams are unordered, unreliable, and not flow-controlled.
Both endpoints can send datagrams below the MTU size (~1.2kb minimum) and they might arrive out of order or not at all.
They are basically UDP packets, except they are encrypted and congestion controlled.

# Usage
Build a [Client](https://docs.rs/web-transport-moq/latest/web_transport_moq/struct.Client.html) or [Server](https://docs.rs/web-transport-moq/latest/web_transport_moq/struct.Server.html) with its builder, or wrap your own [noq::Endpoint](https://docs.rs/moq-noq/latest/moq_noq/struct.Endpoint.html) with `Client::new` / `Server::new`; the only requirement is that the ALPN is set to `web_transport_moq::ALPN` (aka `h3`).
Connecting or accepting takes over the QUIC connection and performs the boring HTTP/3 handshake for you.

See the [examples](examples) or [moq-tokio](https://github.com/moq-dev/moq/blob/main/rs/moq-tokio/src/noq.rs) for a full setup.

```rust
// Create a QUIC client that trusts the system roots.
let client = web_transport_moq::ClientBuilder::new().with_system_roots()?;

// Connect to the given URL.
let session = client.connect(Url::parse("https://localhost")?).await?;

// Create a bidirectional stream.
let (mut send, mut recv) = session.open_bi().await?;

// Send a message.
send.write(b"hello").await?;
```

## API
The `web-transport-moq` API is almost identical to the Noq API, except that [Connection](https://docs.rs/moq-noq/latest/moq_noq/struct.Connection.html) is called [Session](https://docs.rs/web-transport-moq/latest/web_transport_moq/struct.Session.html).

When possible, `Deref` is used to expose the underlying Noq API.
However some of the API is wrapped or unavailable due to WebTransport limitations.
- Stream IDs are not available.
- Error codes are not full VarInts (62-bits) and significantly smaller.
12 changes: 12 additions & 0 deletions web-transport-moq/examples/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Example

## Simple Echo
A simple [server](echo-server.rs) and [client](echo-client.rs).

There's also advanced examples [server](echo-server-advanced.rs) and [client](echo-client-advanced.rs) that construct the QUIC connection manually.

QUIC requires TLS, which makes the initial setup a bit more involved.

- Generate a certificate, for example `rcgen` or `mkcert localhost`
- Run the Rust server: `cargo run --example echo-server -- --tls-cert localhost.crt --tls-key localhost.key`
- Run the Rust client: `cargo run --example echo-client -- --tls-cert localhost.crt`
83 changes: 83 additions & 0 deletions web-transport-moq/examples/echo-client-advanced.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
use std::{fs, io, path, sync::Arc};

use anyhow::Context;
use clap::Parser;
use rustls::pki_types::CertificateDer;
use url::Url;

#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
struct Args {
#[arg(short, long, default_value = "https://localhost:4443")]
url: Url,

/// Accept the certificates at this path, encoded as PEM.
#[arg(long)]
tls_cert: path::PathBuf,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Enable info logging.
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
)
.init();

let args = Args::parse();

// Read the PEM certificate chain
let chain = fs::File::open(args.tls_cert).context("failed to open cert file")?;
let mut chain = io::BufReader::new(chain);

let chain: Vec<CertificateDer> = rustls_pemfile::certs(&mut chain)
.collect::<Result<_, _>>()
.context("failed to load certs")?;

anyhow::ensure!(!chain.is_empty(), "could not find certificate");

let mut roots = rustls::RootCertStore::empty();
roots.add_parsable_certificates(chain);

// Standard noq setup, accepting only the given certificate.
// You should use system roots in production.
let mut config =
rustls::ClientConfig::builder_with_provider(web_transport_moq::crypto::default_provider())
.with_protocol_versions(&[&rustls::version::TLS13])?
.with_root_certificates(roots)
.with_no_client_auth();
config.alpn_protocols = vec![web_transport_moq::ALPN.as_bytes().to_vec()]; // this one is important

let config: noq::crypto::rustls::QuicClientConfig = config.try_into()?;
let config = noq::ClientConfig::new(Arc::new(config));

let client = noq::Endpoint::client("[::]:0".parse()?)?;
let client = web_transport_moq::Client::new(client, config);

// Connect to the given URL.
tracing::info!(url = %args.url, "connecting");
let session = client.connect(args.url).await?;

tracing::info!("connected");

// Create a bidirectional stream.
let (mut send, mut recv) = session.open_bi().await?;

tracing::info!("created stream");

// Send a message.
let msg = "hello world".to_string();
send.write_all(msg.as_bytes()).await?;
tracing::info!(%msg, "sent");

// Shut down the send stream.
send.finish()?;

// Read back the message.
let msg = recv.read_to_end(1024).await?;
tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv");

Ok(())
}
108 changes: 108 additions & 0 deletions web-transport-moq/examples/echo-client.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
use std::{fs, io, path};

use anyhow::Context;
use clap::Parser;
use rustls::pki_types::CertificateDer;
use url::Url;
use web_transport_moq::proto::ConnectRequest;

#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
struct Args {
#[arg(short, long, default_value = "https://localhost:4443")]
url: Url,

/// Accept the certificates at this path, encoded as PEM.
#[arg(long)]
tls_cert: Option<path::PathBuf>,

/// Dangerous: Disable TLS certificate verification.
#[arg(long, default_value = "false")]
tls_disable_verify: bool,

/// Optional WebTransport subprotocol to negotiate.
#[arg(long)]
protocol: Option<String>,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Enable info logging.
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
)
.init();

let args = Args::parse();

let client = web_transport_moq::ClientBuilder::new();

let client = if args.tls_disable_verify {
tracing::warn!("disabling TLS certificate verification; a MITM attack is possible");

// Accept any certificate.
client.dangerous().with_no_certificate_verification()?
} else if let Some(path) = &args.tls_cert {
// Read the PEM certificate chain
let chain = fs::File::open(path).context("failed to open cert file")?;
let mut chain = io::BufReader::new(chain);

let chain: Vec<CertificateDer> = rustls_pemfile::certs(&mut chain)
.collect::<Result<_, _>>()
.context("failed to load certs")?;

anyhow::ensure!(!chain.is_empty(), "could not find certificate");

// Only accept these certificates.
// Also available: with_server_certificate_hashes
client.with_server_certificates(chain)?
} else {
// Accept any certificate that matches a system root.
client.with_system_roots()?
};

tracing::info!(url = %args.url, "connecting");

// Connect to the given URL.
let mut request = ConnectRequest::new(args.url);
if let Some(protocol) = &args.protocol {
request = request.with_protocol(protocol);
}
let session = client.connect(request).await?;

tracing::info!("connected");

match (&args.protocol, session.protocol()) {
(Some(_), Some(protocol)) => {
tracing::info!(%protocol, "negotiated protocol");
}
(Some(requested), None) => {
tracing::warn!(%requested, "server did not negotiate protocol");
}
_ => {}
}

// Create a bidirectional stream.
let (mut send, mut recv) = session.open_bi().await?;

tracing::info!("created stream");

// Send a message.
let msg = "hello world".to_string();
send.write_all(msg.as_bytes()).await?;
tracing::info!(%msg, "sent");

// Shut down the send stream.
send.finish()?;

// Read back the message.
let msg = recv.read_to_end(1024).await?;
tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv");

session.close(42069, b"bye");
session.closed().await;

Ok(())
}
Loading
Loading