quietquic 0.1.0.alpha.3

data/ext/quietquic/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "quietquic"
+version = "0.0.1"
+edition = "2021"
+license = "0BSD"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+quietquic-core = { package = "quietquic", version = "=0.1.0-alpha.3" }
+tokio = { version = "1", features = ["rt-multi-thread", "time"] }
+# `FutureExt::catch_unwind` is used to catch a panic inside a spawned op so it
+# surfaces as a `QuietQUIC::Error` rather than hanging the awaiting fiber (the
+# result slot would otherwise never be populated and the wake byte never sent).
+futures-util = "0.3"
+libc = "0.2"
+hex = "0.4"
+toml = "0.8"
+serde = { version = "1", features = ["derive"] }
+
+# Own workspace so this crate does not join any containing workspace.
+[workspace]

data/ext/quietquic/extconf.rb

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: 0BSD
+require "mkmf"
+require "rb_sys/mkmf"
+
+# Cargo resolves the published quietquic crate from crates.io; this gem does
+# not vendor or path-depend on a local QuietQUIC checkout.
+create_rust_makefile("quietquic/quietquic")

data/ext/quietquic/src/client.rs

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: 0BSD
+//! `QuietQUIC::Native::Client` — the FFI wrapper over the crate's cloaked QUIC
+//! [`quietquic_core::client::Client`].
+//!
+//! This follows the exact native-handle-through-the-bridge pattern set up by
+//! Task 5's `Server::bind` (see `server.rs`'s module doc for the full
+//! rationale): `connect` spawns the crate's async `Client::connect` on the
+//! shared tokio runtime via [`PendingOp::spawn_op`], and the op yields
+//! **plain Rust data** (the crate's `Connection`) — the `to_ruby` converter
+//! builds the Ruby [`crate::server::NativeConnection`] object ON THE RUBY
+//! THREAD, never on a tokio worker thread.
+//!
+//! Unlike `Server`, `Client::connect` needs no long-lived shared handle: the
+//! crate function is a one-shot `async fn` that either resolves to a
+//! `Connection` or fails, so there is no `Arc<Mutex<..>>`, no shutdown
+//! `Notify`, and no `close` method here — the connect future either completes
+//! or the `PendingOp` is disposed (which aborts the tokio task).
+//!
+//! ## NativeConnection is reused, not redefined
+//!
+//! Task 7 extends one `Connection` type with streams for *both* accepted
+//! (server-side) and dialed (client-side) connections. Task 5's `server.rs`
+//! already defines `pub(crate) struct NativeConnection` (and its
+//! `from_core` constructor) for exactly that purpose; this module imports and
+//! reuses it rather than defining a second, parallel `NativeConnection` type.
+//!
+//! ## Error mapping
+//!
+//! The crate's `Client::connect` reports failure as a
+//! [`quietquic_core::client::ClientError`]. Per the task interface, EVERY
+//! variant — including the crate's own internal-timeout variant
+//! `ClientError::TimedOut` — maps to `QuietQUIC::ConnectError`: from the
+//! caller's point of view a timed-out dial and any other connect failure
+//! (bad transport params, socket I/O, handshake lost before completion) are
+//! all "the connect did not succeed," and `ConnectError` is the exception
+//! class the brief and Task 5's `Server::bind` already use for that shape of
+//! failure. Note the crate's `Client::connect` already has an internal
+//! connect timeout (`~10s`, see `crate::client::DEFAULT_CONNECT_TIMEOUT` in
+//! the core crate) — this bridge adds no timeout of its own.
+
+use magnus::{function, prelude::*, Error, IntoValue, RModule, Ruby};
+
+use quietquic_core::client::{Client as CoreClient, ClientError as CoreClientError};
+
+use crate::config::ClientConfigHandle;
+use crate::errors::{ErrorKind, MappedError};
+use crate::pending::PendingOp;
+use crate::conn::NativeConnection;
+
+/// Map a crate `ClientError` to a `QuietQUIC::ConnectError`-classified
+/// [`MappedError`]. Every variant (including `TimedOut`) maps to
+/// `ErrorKind::Connect` — see the module doc for why a timeout and any other
+/// connect failure are both surfaced identically to Ruby callers.
+fn map_client_error(err: CoreClientError) -> MappedError {
+    match err {
+        CoreClientError::TimedOut => {
+            MappedError::new(ErrorKind::Connect, "connect timed out".to_string())
+        }
+        other => MappedError::new(ErrorKind::Connect, format!("connect failed: {other}")),
+    }
+}
+
+/// `QuietQUIC::Native::Client.connect(config) -> PendingOp`.
+///
+/// Spawns the crate's `Client::connect(cfg)` on the shared runtime. The op
+/// yields a `NativeConnection` handle — wrapped into the Ruby object by
+/// `to_ruby` ON THE RUBY THREAD, exactly like `Server::bind`/`accept_op`. A
+/// connect failure (including the crate's internal handshake timeout) maps to
+/// `QuietQUIC::ConnectError`.
+fn connect(config: &ClientConfigHandle) -> Result<PendingOp, Error> {
+    // Clone the parsed config out of the shared Ruby handle: `Client::connect`
+    // consumes it by value, and we only hold `&ClientConfigHandle`.
+    let cfg = config.0.clone();
+    PendingOp::spawn_op(
+        async move { CoreClient::connect(cfg).await.map_err(map_client_error) },
+        |conn| {
+            // Build the Ruby object on the Ruby thread (never off-thread).
+            let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+            NativeConnection::from_core(conn).into_value_with(&ruby)
+        },
+    )
+}
+
+/// Register `Client` and its methods on `QuietQUIC::Native`.
+pub(crate) fn init(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let client = native.define_class("Client", ruby.class_object())?;
+    client.define_singleton_method("connect", function!(connect, 1))?;
+    Ok(())
+}

data/ext/quietquic/src/config.rs

@@ -0,0 +1,292 @@
+// SPDX-License-Identifier: 0BSD
+//! Config builders: `QuietQUIC::Native.server_config_from_hash`,
+//! `.server_config_from_toml`, `.client_config_from_parts`, and
+//! `.client_config_from_toml`.
+//!
+//! These are synchronous — config parsing is fast and purely local, so unlike
+//! the connect/stream operations added in later tasks, there is no
+//! `PendingOp`/async bridge involved. Each builder either returns an opaque
+//! handle (`ServerConfigHandle`/`ClientConfigHandle`) wrapping the crate's
+//! parsed config, or raises `QuietQUIC::ConfigError` synchronously via
+//! `MappedError::into_ruby_error`.
+//!
+//! The handles carry plain Rust data (no Ruby `Value`s), so they need no
+//! custom `mark`/`free` — `#[magnus::wrap]` derives a `DataType` for them.
+
+use std::net::SocketAddr;
+
+use magnus::{prelude::*, r_hash::ForEach, Error, RHash, RString, Ruby, Symbol, Value};
+use quietquic_core::config::{
+    ClientConfigFile, ConfigError as CoreConfigError, FileSource, SecretSource, ServerSecrets,
+};
+
+use crate::errors::{ErrorKind, MappedError};
+
+/// Opaque handle wrapping a parsed server secrets file (listen addr + all
+/// authorized clients). Produced by `server_config_from_hash`/`_toml`;
+/// consumed by `QuietQUIC::Server.bind` in a later task. The wrapped
+/// `ServerSecrets` is unread by this task on purpose — Task 4 only validates
+/// and carries it; Task 5/6 will read it to actually bind.
+#[magnus::wrap(class = "QuietQUIC::Native::ServerConfigHandle", free_immediately, size)]
+#[allow(dead_code)]
+pub(crate) struct ServerConfigHandle(pub(crate) ServerSecrets);
+
+/// Opaque handle wrapping a parsed client config (identity, PSK, server
+/// addr). Produced by `client_config_from_parts`/`_toml`; consumed by
+/// `QuietQUIC::Client.connect` in a later task. See
+/// [`ServerConfigHandle`] for why the wrapped value is unread here.
+#[magnus::wrap(class = "QuietQUIC::Native::ClientConfigHandle", free_immediately, size)]
+#[allow(dead_code)]
+pub(crate) struct ClientConfigHandle(pub(crate) ClientConfigFile);
+
+/// Build a `QuietQUIC::ConfigError` with `message`, ready to return from a
+/// `Result`-returning native method.
+fn config_error(ruby: &Ruby, message: impl Into<String>) -> Error {
+    MappedError::new(ErrorKind::Config, message).into_ruby_error(ruby)
+}
+
+/// Validate a PSK is 64 hex chars decoding to exactly 32 bytes. `Psk`'s inner
+/// byte array is private outside the crate (by design — see its `Debug`
+/// redaction), so there is no public constructor from raw bytes; the crate's
+/// `serde::Deserialize` impl is the only construction path. We validate here
+/// (for a precise, field-attributed error message) and let the TOML
+/// round-trip in the callers actually build the `Psk`, via that same
+/// `Deserialize` impl — so validation is never duplicated, only checked
+/// early.
+fn validate_psk(psk_hex: &str) -> Result<(), String> {
+    let bytes = hex::decode(psk_hex).map_err(|e| format!("invalid psk hex: {e}"))?;
+    if bytes.len() != 32 {
+        return Err("psk must be 32 bytes (64 hex chars)".to_string());
+    }
+    Ok(())
+}
+
+fn parse_addr(addr: &str, what: &str) -> Result<SocketAddr, String> {
+    addr.parse::<SocketAddr>()
+        .map_err(|e| format!("invalid {what} address {addr:?}: {e}"))
+}
+
+/// A minimal TOML-serializable mirror of a single client entry, used only to
+/// hand `client_id`/`psk_hex` to `toml`/`serde` so the crate's own
+/// `Psk: Deserialize` impl builds the real `Psk`. Never exposed to Ruby.
+#[derive(serde::Serialize)]
+struct ClientEntryToml<'a> {
+    client_id: &'a str,
+    psk: &'a str,
+}
+
+/// A minimal TOML-serializable mirror of `ServerSecrets`, for the same reason
+/// as [`ClientEntryToml`].
+#[derive(serde::Serialize)]
+struct ServerSecretsToml<'a> {
+    listen: &'a str,
+    clients: Vec<ClientEntryToml<'a>>,
+}
+
+/// A minimal TOML-serializable mirror of `ClientConfigFile`.
+#[derive(serde::Serialize)]
+struct ClientConfigFileToml<'a> {
+    client_id: &'a str,
+    psk: &'a str,
+    server: &'a str,
+}
+
+/// Map the crate's `ConfigError` (io/parse) to a message for `ConfigError`.
+fn core_config_error_message(err: CoreConfigError) -> String {
+    match err {
+        CoreConfigError::Io(e) => format!("io: {e}"),
+        CoreConfigError::Parse(e) => format!("parse: {e}"),
+        CoreConfigError::Invalid(e) => format!("invalid config: {e}"),
+    }
+}
+
+/// Convert a Ruby Hash key (a client id) to a `String`. Accepts a `String` or
+/// a `Symbol` (coerced to its name) — both are idiomatic ways to write a
+/// client-id key in Ruby (`{"alice" => psk}` / `{alice: psk}`). Anything else
+/// (Integer, nil, ...) is a plausible user mistake, so it is reported via
+/// `QuietQUIC::ConfigError` rather than letting magnus's own conversion
+/// raise a bare Ruby `TypeError`.
+fn client_id_from_key(ruby: &Ruby, key: Value) -> Result<String, Error> {
+    if let Some(s) = RString::from_value(key) {
+        return s
+            .to_string()
+            .map_err(|e| config_error(ruby, format!("invalid client id: {e}")));
+    }
+    if let Some(sym) = Symbol::from_value(key) {
+        return sym
+            .name()
+            .map(|n| n.into_owned())
+            .map_err(|e| config_error(ruby, format!("invalid client id symbol: {e}")));
+    }
+    Err(config_error(
+        ruby,
+        format!(
+            "client id must be a String or Symbol, got {}",
+            key.class().inspect()
+        ),
+    ))
+}
+
+/// Convert a Ruby Hash value (a PSK) to a `String`. Must be a Ruby `String`
+/// (a PSK is a 64-hex-char string) — anything else is reported via
+/// `QuietQUIC::ConfigError`, naming the offending client id.
+fn psk_from_value(ruby: &Ruby, client_id: &str, value: Value) -> Result<String, Error> {
+    match RString::from_value(value) {
+        Some(s) => s.to_string().map_err(|e| {
+            config_error(ruby, format!("invalid psk for client {client_id:?}: {e}"))
+        }),
+        None => Err(config_error(
+            ruby,
+            format!(
+                "psk for client {client_id:?} must be a String (64 hex chars), got {}",
+                value.class().inspect()
+            ),
+        )),
+    }
+}
+
+/// `QuietQUIC::Native.server_config_from_hash(listen, clients) -> ServerConfigHandle`.
+///
+/// `clients` is a `Hash` of `client_id => psk_hex` (64 hex chars each).
+/// Raises `QuietQUIC::ConfigError` if `listen` doesn't parse as a
+/// `SocketAddr`, or any PSK isn't valid 64-hex/32-bytes.
+///
+/// `clients` is taken as a `magnus::RHash` (not `HashMap<String, String>`)
+/// and iterated manually: magnus's blanket `TryConvert` for `HashMap<K, V>`
+/// runs its per-entry conversion *before* this function body ever executes,
+/// so a non-string key or value (e.g. Symbol keys, which are idiomatic Ruby)
+/// would raise a bare Ruby `TypeError` that never reaches the `ConfigError`
+/// mapping below. Iterating the `RHash` ourselves via `foreach::<Value,
+/// Value>` (identity conversion, infallible) lets us apply our own
+/// String/Symbol-friendly rules and always raise `QuietQUIC::ConfigError`
+/// on a bad entry.
+pub(crate) fn server_config_from_hash(
+    ruby: &Ruby,
+    listen: String,
+    clients: RHash,
+) -> Result<ServerConfigHandle, Error> {
+    // Validate the addr eagerly for a clean error, though it's re-parsed
+    // below by the crate's own `SocketAddr: Deserialize` via TOML.
+    parse_addr(&listen, "listen").map_err(|msg| config_error(ruby, msg))?;
+
+    let mut parsed: Vec<(String, String)> = Vec::with_capacity(clients.len());
+    let mut iter_err: Option<Error> = None;
+    clients.foreach(|key: Value, value: Value| {
+        let outcome = (|| -> Result<(String, String), Error> {
+            let client_id = client_id_from_key(ruby, key)?;
+            let psk_hex = psk_from_value(ruby, &client_id, value)?;
+            Ok((client_id, psk_hex))
+        })();
+        match outcome {
+            Ok(pair) => {
+                parsed.push(pair);
+                Ok(ForEach::Continue)
+            }
+            Err(e) => {
+                iter_err = Some(e);
+                Ok(ForEach::Stop)
+            }
+        }
+    })?;
+    if let Some(e) = iter_err {
+        return Err(e);
+    }
+
+    let mut entries = Vec::with_capacity(parsed.len());
+    for (client_id, psk_hex) in &parsed {
+        validate_psk(psk_hex)
+            .map_err(|msg| config_error(ruby, format!("client {client_id:?}: {msg}")))?;
+        entries.push(ClientEntryToml {
+            client_id,
+            psk: psk_hex,
+        });
+    }
+
+    let mirror = ServerSecretsToml {
+        listen: &listen,
+        clients: entries,
+    };
+    let toml_text = toml::to_string(&mirror)
+        .map_err(|e| config_error(ruby, format!("internal: failed to encode config: {e}")))?;
+    let secrets: ServerSecrets = toml::from_str(&toml_text)
+        .map_err(|e| config_error(ruby, format!("parse: {e}")))?;
+
+    Ok(ServerConfigHandle(secrets))
+}
+
+/// `QuietQUIC::Native.server_config_from_toml(path) -> ServerConfigHandle`.
+///
+/// Delegates to the crate's `FileSource::new(path).load()`, which preserves
+/// the crate's chmod-600 group/world-readable warning (logged via `tracing`,
+/// not raised) and its io/parse error handling. Any failure is mapped to
+/// `QuietQUIC::ConfigError`.
+pub(crate) fn server_config_from_toml(
+    ruby: &Ruby,
+    path: String,
+) -> Result<ServerConfigHandle, Error> {
+    let secrets = FileSource::new(path)
+        .load()
+        .map_err(|e| config_error(ruby, core_config_error_message(e)))?;
+    Ok(ServerConfigHandle(secrets))
+}
+
+/// `QuietQUIC::Native.client_config_from_parts(client_id, psk_hex, server) -> ClientConfigHandle`.
+pub(crate) fn client_config_from_parts(
+    ruby: &Ruby,
+    client_id: String,
+    psk_hex: String,
+    server: String,
+) -> Result<ClientConfigHandle, Error> {
+    validate_psk(&psk_hex).map_err(|msg| config_error(ruby, msg))?;
+    parse_addr(&server, "server").map_err(|msg| config_error(ruby, msg))?;
+
+    let mirror = ClientConfigFileToml {
+        client_id: &client_id,
+        psk: &psk_hex,
+        server: &server,
+    };
+    let toml_text = toml::to_string(&mirror)
+        .map_err(|e| config_error(ruby, format!("internal: failed to encode config: {e}")))?;
+    let parsed: ClientConfigFile = toml::from_str(&toml_text)
+        .map_err(|e| config_error(ruby, format!("parse: {e}")))?;
+
+    Ok(ClientConfigHandle(parsed))
+}
+
+/// `QuietQUIC::Native.client_config_from_toml(path) -> ClientConfigHandle`.
+pub(crate) fn client_config_from_toml(
+    ruby: &Ruby,
+    path: String,
+) -> Result<ClientConfigHandle, Error> {
+    let text = std::fs::read_to_string(&path)
+        .map_err(|e| config_error(ruby, format!("io: {e}")))?;
+    let parsed: ClientConfigFile =
+        toml::from_str(&text).map_err(|e| config_error(ruby, format!("parse: {e}")))?;
+    Ok(ClientConfigHandle(parsed))
+}
+
+/// Register the config builders and handle classes on `QuietQUIC::Native`.
+pub(crate) fn init(ruby: &Ruby, native: &magnus::RModule) -> Result<(), Error> {
+    use magnus::{function, prelude::*, Module};
+
+    native.define_class("ServerConfigHandle", ruby.class_object())?;
+    native.define_class("ClientConfigHandle", ruby.class_object())?;
+
+    native.define_singleton_method(
+        "server_config_from_hash",
+        function!(server_config_from_hash, 2),
+    )?;
+    native.define_singleton_method(
+        "server_config_from_toml",
+        function!(server_config_from_toml, 1),
+    )?;
+    native.define_singleton_method(
+        "client_config_from_parts",
+        function!(client_config_from_parts, 3),
+    )?;
+    native.define_singleton_method(
+        "client_config_from_toml",
+        function!(client_config_from_toml, 1),
+    )?;
+    Ok(())
+}