quietquic 0.1.0.alpha.3

data/ext/quietquic/src/server.rs

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: 0BSD
+//! `QuietQUIC::Native::Server` — the FFI wrapper over the crate's cloaked QUIC
+//! [`quietquic_core::server::Server`], plus a minimal [`NativeConnection`] that
+//! Task 7 extends into the friendly stream-carrying `Connection`.
+//!
+//! ## Native-handle-through-the-bridge pattern (the template for Tasks 6/7)
+//!
+//! The crate's `Server` is a Rust value whose UDP/endpoint driver runs on the
+//! shared tokio runtime (see [`crate::runtime`]). We must (a) hand a handle onto
+//! it back to Ruby, (b) let an async `accept` drive it, and (c) let a sync
+//! `close` stop it — all while the Ruby object is freely shared/`dup`ed.
+//!
+//! Sharing model:
+//! - `NativeServer` wraps `Arc<tokio::sync::Mutex<Option<Server>>>`. The `Arc`
+//!   lets the same underlying server be driven by an `accept` future while the
+//!   Ruby object is shared; the `Option` lets `close` (and GC `free`) *take* and
+//!   drop the crate `Server`, which drops its `JoinHandle` and stops the driver.
+//! - `accept` takes `&mut Server`, and the future must hold the server locked
+//!   across the `.await`. We therefore use a **`tokio::sync::Mutex`**, never a
+//!   `std::sync::Mutex` — holding a std mutex across `.await` is forbidden (it
+//!   would block a runtime worker and can deadlock). Only one `accept` can be
+//!   in flight at a time, which matches the crate's single-consumer `accept`.
+//! - `local_addr` is cached as a plain `SocketAddr` at wrap time, so
+//!   `local_address` is lock-free and still answers after `close`.
+//! - A parked `accept` holds the async mutex across `server.accept().await`,
+//!   which never resolves while no client connects — the normal idle state of an
+//!   accept loop. `close` must take that same mutex to drop the server, so it
+//!   would block forever (and, under a single-threaded `Async` reactor,
+//!   `blocking_lock` freezes the whole Ruby VM). To break this, `NativeServer`
+//!   carries a shared `shutdown: Arc<Notify>`: the accept future `select!`s on
+//!   it, so `close` can fire `notify_waiters()` FIRST to unpark a parked accept.
+//!   The woken accept drops its guard on the tokio worker thread, so `close`'s
+//!   subsequent `blocking_lock` acquires promptly instead of deadlocking.
+//! - BUT `notify_waiters()` is EDGE-triggered: it wakes only accepts already
+//!   registered on the `Notify` at that instant. With CONCURRENT accepts, one
+//!   accept can still be queued on the FIFO async mutex (not yet in `select!`,
+//!   not yet registered) when `close` fires; it acquires the guard AFTER the
+//!   woken accept releases it, reaches `select!`, registers on the `Notify` too
+//!   late (the edge already passed), and parks forever — re-deadlocking `close`.
+//!   To close this window, `NativeServer` also carries a LATCHING
+//!   `closed: Arc<AtomicBool>`: `close` sets it `true` (Release) BEFORE firing
+//!   the notify, and every accept, right after acquiring the async-mutex guard
+//!   and BEFORE entering `select!`, checks it (Acquire) and returns
+//!   `ConnectionLost` immediately if set — never parking, releasing the guard at
+//!   once. The `Notify` still promptly unparks the already-parked accept; the
+//!   latch covers any accept that reaches the guard after the edge passed. This
+//!   is deadlock-free for 0, 1, or N concurrent parked accepts plus a `close`.
+//!
+//! FFI thread-safety: `spawn_op` runs the future on a tokio worker and yields
+//! **plain Rust data** (`Server` / `Connection`); the Ruby `NativeServer` /
+//! `NativeConnection` object is built by the `to_ruby` converter on the Ruby
+//! thread. No magnus `Value` is ever constructed on a tokio worker thread.
+
+use std::net::SocketAddr;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use magnus::{function, method, prelude::*, Error, IntoValue, RModule, Ruby};
+use tokio::sync::Mutex as AsyncMutex;
+use tokio::sync::Notify;
+
+use quietquic_core::conn::Connection as CoreConnection;
+use quietquic_core::server::Server as CoreServer;
+
+use crate::config::ServerConfigHandle;
+use crate::conn::NativeConnection;
+use crate::errors::{ErrorKind, MappedError};
+use crate::pending::PendingOp;
+
+/// Shared, drop-on-close handle onto the crate's running `Server`. `None` once
+/// closed (or never bound). Cloned into the `accept` future so it can drive the
+/// server; taken by `close`/`free` to stop the driver.
+type SharedServer = Arc<AsyncMutex<Option<CoreServer>>>;
+
+/// `QuietQUIC::Native::Server` — TypedData wrapper over the crate's `Server`.
+///
+/// `Send` (required for the GC free path and for moving the shared handle into
+/// `accept` futures) because `Arc<tokio::sync::Mutex<Option<Server>>>` is `Send`
+/// (the crate `Server` is `Send`) and `SocketAddr` is `Copy + Send`.
+#[magnus::wrap(class = "QuietQUIC::Native::Server", free_immediately, size)]
+pub(crate) struct NativeServer {
+    server: SharedServer,
+    /// Cached at bind time so `local_address` needs no lock and survives `close`.
+    local_addr: SocketAddr,
+    /// Fired by `close` to unpark a parked `accept`. The accept future `select!`s
+    /// on `notified()`, so a `close` racing an idle-waiting `accept` wakes it; the
+    /// woken accept then releases the async mutex on the tokio worker thread,
+    /// letting `close`'s `blocking_lock` proceed instead of deadlocking. Cloned
+    /// (as an `Arc`) into the accept future so both sides share one `Notify`.
+    shutdown: Arc<Notify>,
+    /// Latching shutdown flag. Set `true` by `close` (Release) BEFORE firing
+    /// `shutdown.notify_waiters()`; read by every accept (Acquire) after it
+    /// acquires the async-mutex guard and BEFORE it enters `select!`. Because
+    /// `notify_waiters()` is edge-triggered, an accept that only reaches the
+    /// guard AFTER `close`'s notify fired would otherwise register on the
+    /// `Notify` too late and park forever; this latch lets such a late accept
+    /// see closure and return `ConnectionLost` at once, releasing the guard so
+    /// `close`'s `blocking_lock` proceeds. Lock-free, so it is read before (not
+    /// across) the `.await` — no `std` lock is ever held across an await.
+    closed: Arc<AtomicBool>,
+}
+
+impl NativeServer {
+    /// `QuietQUIC::Native::Server.bind(config) -> PendingOp`.
+    ///
+    /// Spawns the crate's `Server::bind(secrets)` on the shared runtime. The op
+    /// yields a `NativeServer` handle — wrapped into the Ruby object by `to_ruby`
+    /// ON THE RUBY THREAD. A bind failure (socket bind / TLS setup, an
+    /// `io::Error`) maps to `QuietQUIC::ConnectError`.
+    fn bind(config: &ServerConfigHandle) -> Result<PendingOp, Error> {
+        // Clone the parsed secrets out of the shared Ruby handle: `Server::bind`
+        // consumes them by value, and we only hold `&ServerConfigHandle`.
+        let secrets = config.0.clone();
+        PendingOp::spawn_op(
+            async move {
+                CoreServer::bind(secrets)
+                    .await
+                    .map_err(|e| MappedError::new(ErrorKind::Connect, format!("bind failed: {e}")))
+            },
+            |server: CoreServer| {
+                // Build the Ruby object on the Ruby thread (never off-thread).
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                let local_addr = server.local_addr();
+                let native = NativeServer {
+                    server: Arc::new(AsyncMutex::new(Some(server))),
+                    local_addr,
+                    shutdown: Arc::new(Notify::new()),
+                    closed: Arc::new(AtomicBool::new(false)),
+                };
+                native.into_value_with(&ruby)
+            },
+        )
+    }
+
+    /// `NativeServer#accept_op -> PendingOp`.
+    ///
+    /// Spawns `server.accept()`; yields a `NativeConnection`. Holds the server's
+    /// `tokio::sync::Mutex` across the `.await` (safe — async mutex), so exactly
+    /// one accept drives the server at a time. Maps a closed/lost server (accept
+    /// yielding `None`, or the server already closed) to `QuietQUIC::ConnectionLost`.
+    ///
+    /// The accept `.await` parks indefinitely while no client connects — the
+    /// normal idle state of an accept loop — and holds the async mutex the whole
+    /// time. To let a concurrent `close` shut down an idle server, the future
+    /// `select!`s the accept against `shutdown.notified()`: when `close` fires
+    /// `notify_waiters()`, the shutdown arm wins, the future returns a mapped
+    /// `ConnectionLost`, and the guard is dropped HERE on the tokio worker
+    /// thread — unblocking `close`'s lock acquisition.
+    fn accept_op(&self) -> Result<PendingOp, Error> {
+        let shared = Arc::clone(&self.server);
+        let shutdown = Arc::clone(&self.shutdown);
+        let closed = Arc::clone(&self.closed);
+        PendingOp::spawn_op(
+            async move {
+                // Lock across the await: this is a tokio async mutex, so parking
+                // here yields the worker rather than blocking it.
+                let mut guard = shared.lock().await;
+                // Latching closed-check, BEFORE the select!. `close` sets `closed`
+                // Release-ordered before firing the edge-triggered notify, so any
+                // accept that reaches this guard after that edge sees `true` here
+                // and returns WITHOUT parking — releasing the guard at once so
+                // `close`'s `blocking_lock` proceeds. This is the window that a
+                // bare `notify_waiters()` leaves open for a concurrent accept.
+                // The AtomicBool is lock-free, so this read is not a lock held
+                // across an await.
+                if closed.load(Ordering::Acquire) {
+                    return Err(MappedError::new(ErrorKind::ConnectionLost, "server is closed"));
+                }
+                let server = guard.as_mut().ok_or_else(|| {
+                    MappedError::new(ErrorKind::ConnectionLost, "server is closed")
+                })?;
+                tokio::select! {
+                    // Bias the accept arm so a connection that is already ready is
+                    // preferred over a simultaneous shutdown signal; a purely idle
+                    // accept still parks and yields to the shutdown arm.
+                    biased;
+                    res = server.accept() => match res {
+                        Some(conn) => Ok(conn),
+                        None => Err(MappedError::new(
+                            ErrorKind::ConnectionLost,
+                            "server stopped accepting (driver shut down)",
+                        )),
+                    },
+                    () = shutdown.notified() => Err(MappedError::new(
+                        ErrorKind::ConnectionLost,
+                        "server closed while accepting",
+                    )),
+                }
+                // `guard` is dropped here, on the tokio worker thread, releasing
+                // the async mutex so a waiting `close` can `take()` the server.
+            },
+            |conn: CoreConnection| {
+                let ruby = Ruby::get().expect("to_ruby runs on the Ruby thread");
+                NativeConnection::from_core(conn).into_value_with(&ruby)
+            },
+        )
+    }
+
+    /// `NativeServer#local_address -> String`. Synchronous, lock-free.
+    fn local_address(&self) -> String {
+        self.local_addr.to_string()
+    }
+
+    /// `NativeServer#close`. Synchronous; drops the crate `Server`, stopping its
+    /// driver (which prunes CIDs and releases the socket). Idempotent: a second
+    /// close finds `None` and is a no-op.
+    ///
+    /// Order matters, and there are THREE steps.
+    ///
+    /// 1. Set the latching `closed` flag (Release). This must happen BEFORE the
+    ///    notify so any accept that later acquires the async-mutex guard — even
+    ///    one still queued FIFO on that mutex when `close` runs — observes
+    ///    closure (Acquire) and returns immediately instead of parking. This is
+    ///    the fix for the CONCURRENT-accept deadlock: `notify_waiters()` is
+    ///    edge-triggered and cannot wake an accept that has not yet registered.
+    /// 2. Fire `shutdown.notify_waiters()`. This promptly unparks any accept
+    ///    ALREADY parked in `select!` (registered on the `Notify`), so it does
+    ///    not have to wait for step 1's guarantee — it returns and drops its
+    ///    guard on the tokio worker thread right away.
+    /// 3. `blocking_lock` to `take()` + drop the server. If an `accept` is parked
+    ///    on `server.accept().await` (idle-waiting for a client), it holds the
+    ///    async mutex, and a bare `blocking_lock` here would block forever — and
+    ///    under a single-threaded `Async` reactor `blocking_lock` does not
+    ///    release the GVL, freezing the whole VM. Steps 1+2 guarantee every
+    ///    parked or about-to-park accept releases the guard promptly (via the
+    ///    notify if already parked, via the latch if it reaches the guard later),
+    ///    so this lock acquisition always completes. `blocking_lock` is otherwise
+    ///    safe: `close` runs on the Ruby thread, never on a runtime worker.
+    ///
+    /// Idempotent + drop-safe: a second `close` re-stores `true` (harmless),
+    /// finds `None` (harmless `notify_waiters` on a `Notify` with no waiters is a
+    /// no-op, and `take()` yields `None`). Racing a still-in-flight accept cannot
+    /// double-drop: whoever holds the guard owns the `Some`, and `take()`
+    /// replaces it with `None`, so exactly one path drops the crate `Server`.
+    fn close(&self) {
+        // 1. Latch closure FIRST so a late/queued accept sees it and never parks.
+        self.closed.store(true, Ordering::Release);
+        // 2. Unpark any already-parked accept so it releases the async mutex.
+        self.shutdown.notify_waiters();
+        // 3. Take + drop the server. The lock now resolves promptly.
+        let taken = {
+            let mut guard = self.server.blocking_lock();
+            guard.take()
+        };
+        drop(taken);
+    }
+}
+
+/// Register `Server` and its methods on `QuietQUIC::Native`. The
+/// `Connection`/`Stream` classes are registered by [`crate::conn`].
+pub(crate) fn init(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let server = native.define_class("Server", ruby.class_object())?;
+    server.define_singleton_method("bind", function!(NativeServer::bind, 1))?;
+    server.define_method("accept_op", method!(NativeServer::accept_op, 0))?;
+    server.define_method("local_address", method!(NativeServer::local_address, 0))?;
+    server.define_method("close", method!(NativeServer::close, 0))?;
+
+    Ok(())
+}

data/lib/quietquic/await.rb

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: 0BSD
+module QuietQUIC
+  # Wait for an in-flight native operation (a +PendingOp+) to complete and
+  # return its result, raising the mapped +QuietQUIC::*+ exception on failure.
+  #
+  # Waiting goes through +IO#wait_readable+ on the op's self-pipe fd, which is
+  # fiber-scheduler aware (Ruby >= 3.0): under +Async+ it parks the fiber and
+  # lets the reactor run other tasks; with no scheduler it blocks while
+  # releasing the GVL.
+  #
+  # +autoclose: false+ is a hard invariant: Rust owns the fd and closes it on
+  # disposal, so the Ruby +IO+ must never autoclose it (that would double-close).
+  #
+  # The op is explicitly disposed in an +ensure+ so its pipe fds are freed at
+  # await-completion rather than whenever the GC eventually runs the finalizer.
+  def self.await(op)
+    IO.for_fd(op.fd, autoclose: false).wait_readable
+    op.take_result
+  ensure
+    op.close
+  end
+end

data/lib/quietquic/client.rb

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: 0BSD
+module QuietQUIC
+  # Dial a cloaked QUIC server.
+  #
+  # Build a connection with {.connect} (from a client id + PSK + server
+  # address) or {.connect_toml} (from a client config file). Both parse and
+  # validate the config synchronously (raising {QuietQUIC::ConfigError} on a
+  # bad address or PSK), then +await+ the native connect on the shared
+  # runtime.
+  #
+  # The underlying crate connect has its own internal handshake timeout
+  # (about 10 seconds); a server that never responds surfaces as
+  # {QuietQUIC::ConnectError}, same as any other failed dial.
+  class Client
+    # Dial a server from this client's identity, PSK, and the server address.
+    #
+    # @param client_id [String] this client's id (must be authorized by the
+    #   server).
+    # @param psk [String] the shared PSK, 64 hex chars (32 bytes).
+    # @param server [String] the server's +"ip:port"+ to dial.
+    # @return [Connection]
+    # @raise [QuietQUIC::ConfigError] on a bad address or PSK.
+    # @raise [QuietQUIC::ConnectError] if the connect fails or times out.
+    def self.connect(client_id:, psk:, server:)
+      handle = Native.client_config_from_parts(client_id, psk, server)
+      Connection.new(QuietQUIC.await(Native::Client.connect(handle)))
+    end
+
+    # Dial a server using a client config TOML file.
+    #
+    # @param path [String] path to the client config TOML.
+    # @return [Connection]
+    # @raise [QuietQUIC::ConfigError] if the file is missing or invalid.
+    # @raise [QuietQUIC::ConnectError] if the connect fails or times out.
+    def self.connect_toml(path)
+      handle = Native.client_config_from_toml(path)
+      Connection.new(QuietQUIC.await(Native::Client.connect(handle)))
+    end
+  end
+end

data/lib/quietquic/connection.rb

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: 0BSD
+module QuietQUIC
+  # A single post-handshake, PSK-authenticated QUIC connection.
+  #
+  # Produced identically by {Server#accept} and {Client.connect} (both sides
+  # surface the same type). Carries bidirectional {Stream}s: {#open_stream}
+  # dials a new stream, {#accept_stream} awaits the next peer-opened one. Both
+  # park the fiber (under an +Async+ reactor) until they resolve.
+  #
+  # Dropping a +Connection+ does not tear the connection down; call {#close} to
+  # send a CONNECTION_CLOSE so the peer tears down promptly rather than idling
+  # out.
+  class Connection
+    # @param native [Native::Connection] the wrapped crate connection.
+    def initialize(native)
+      @native = native
+    end
+
+    # Open a new bidirectional {Stream}.
+    #
+    # @return [Stream]
+    # @raise [QuietQUIC::ConnectionLost] if the connection is closed or lost.
+    # @raise [QuietQUIC::StreamError] if the transport refuses the stream.
+    def open_stream
+      Stream.new(QuietQUIC.await(@native.open_stream_op))
+    end
+
+    # Await and return the next bidirectional {Stream} the peer opens.
+    #
+    # Blocks until the peer initiates a stream. Under an +Async+ reactor it
+    # parks the fiber; otherwise it blocks with the GVL released.
+    #
+    # @return [Stream]
+    # @raise [QuietQUIC::ConnectionLost] if the connection is closed or lost
+    #   while awaiting.
+    def accept_stream
+      Stream.new(QuietQUIC.await(@native.accept_stream_op))
+    end
+
+    # The remote peer's address (e.g. +"127.0.0.1:54321"+).
+    #
+    # @return [String]
+    def remote_address
+      @native.remote_address
+    end
+
+    # Close the connection, sending a CONNECTION_CLOSE frame so the peer tears
+    # down promptly. Best-effort and idempotent.
+    #
+    # @return [void]
+    def close
+      @native.close
+    end
+  end
+end

data/lib/quietquic/server.rb

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: 0BSD
+module QuietQUIC
+  # A running cloaked QUIC server.
+  #
+  # Build one with {.bind} (from a listen address + a +{client_id => psk}+ map)
+  # or {.bind_toml} (from a secrets file). Both parse and validate the config
+  # synchronously (raising {QuietQUIC::ConfigError} on a bad address or PSK),
+  # then +await+ the native bind on the shared runtime.
+  #
+  # {#accept} yields the next authenticated {Connection}; it blocks (parking the
+  # fiber under an +Async+ reactor) until a peer completes the cloaked handshake.
+  class Server
+    # Bind a server from a listen address and an authorized-clients map.
+    #
+    # @param listen [String] the +"ip:port"+ to bind (use port +0+ for an
+    #   ephemeral port, then read {#local_address}).
+    # @param clients [Hash{String=>String}] +client_id => psk_hex+ (64 hex chars).
+    # @return [Server]
+    # @raise [QuietQUIC::ConfigError] on a bad address or PSK.
+    # @raise [QuietQUIC::ConnectError] if the socket cannot be bound.
+    def self.bind(listen:, clients:)
+      handle = Native.server_config_from_hash(listen, clients)
+      new(QuietQUIC.await(Native::Server.bind(handle)))
+    end
+
+    # Bind a server from a TOML secrets file.
+    #
+    # @param path [String] path to the server secrets TOML.
+    # @return [Server]
+    # @raise [QuietQUIC::ConfigError] if the file is missing or invalid.
+    # @raise [QuietQUIC::ConnectError] if the socket cannot be bound.
+    def self.bind_toml(path)
+      handle = Native.server_config_from_toml(path)
+      new(QuietQUIC.await(Native::Server.bind(handle)))
+    end
+
+    # @param native [Native::Server] the wrapped crate server.
+    def initialize(native)
+      @native = native
+    end
+
+    # Await and return the next authenticated {Connection}.
+    #
+    # Blocks until a peer completes the cloaked handshake. Under an +Async+
+    # reactor it parks the fiber; otherwise it blocks with the GVL released.
+    #
+    # @return [Connection]
+    # @raise [QuietQUIC::ConnectionLost] if the server has been closed or its
+    #   driver has shut down.
+    def accept
+      Connection.new(QuietQUIC.await(@native.accept_op))
+    end
+
+    # The address the server is actually listening on (e.g. +"127.0.0.1:54321"+).
+    # After binding to port +0+ this reports the kernel-chosen port.
+    #
+    # @return [String]
+    def local_address
+      @native.local_address
+    end
+
+    # Stop the server: drop the crate server, halting its driver and releasing
+    # the socket. Idempotent.
+    #
+    # @return [void]
+    def close
+      @native.close
+    end
+  end
+end

data/lib/quietquic/stream.rb

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: 0BSD
+module QuietQUIC
+  # A bidirectional QUIC stream on a {Connection}.
+  #
+  # Obtained from {Connection#open_stream} or {Connection#accept_stream}. Write
+  # bytes with {#write_all}, signal end-of-data with {#finish}, and read the
+  # peer's whole reply with {#read_to_end}. Each operation parks the fiber
+  # (under an +Async+ reactor) until it resolves.
+  #
+  # @note The native alpha.3 API has split send/receive halves. This Ruby class
+  #   keeps one facade around those halves: send operations serialize with send
+  #   operations, receive operations serialize with receive operations, and both
+  #   still park through the same scheduler-aware bridge.
+  class Stream
+    # Default upper bound for {#read_to_end}, chosen to keep the convenience
+    # method safe against an authenticated peer sending an unbounded response.
+    DEFAULT_READ_LIMIT = 1024 * 1024
+    DEFAULT_FINISH_TIMEOUT = 10
+
+    # @param native [Native::Stream] the wrapped crate stream.
+    def initialize(native)
+      @native = native
+    end
+
+    # Write all of +bytes+ to the stream, waiting out flow-control
+    # back-pressure. The bytes are sent verbatim: +bytes+ is read as a raw byte
+    # sequence regardless of its String encoding.
+    #
+    # @param bytes [String] the bytes to send.
+    # @return [void]
+    # @raise [QuietQUIC::ConnectionLost] if the connection is closed or lost.
+    # @raise [QuietQUIC::StreamError] if the stream is reset or stopped.
+    def write_all(bytes)
+      QuietQUIC.await(@native.write_all_op(bytes))
+    end
+
+    # Finish (send FIN on) the stream, signalling end-of-data to the peer.
+    #
+    # @return [void]
+    # @raise [QuietQUIC::ConnectionLost] if the connection is closed or lost.
+    # @raise [QuietQUIC::StreamError] if the stream is reset or stopped.
+    def finish
+      QuietQUIC.await(@native.finish_op)
+    end
+
+    # Finish the stream and wait for the peer to acknowledge its FIN.
+    #
+    # Use this before immediately closing the connection when delivery of the
+    # final stream matters. A plain {#finish} only queues FIN locally.
+    #
+    # @param timeout [Numeric] maximum seconds to wait.
+    # @return [void]
+    def finish_and_wait(timeout: DEFAULT_FINISH_TIMEOUT)
+      unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+        raise ArgumentError, "timeout must be a positive finite number"
+      end
+
+      QuietQUIC.await(@native.finish_and_wait_op(timeout.to_f))
+    end
+
+    # Read the stream to end-of-stream, returning up to +limit+ bytes.
+    #
+    # Parks until the peer sends FIN. The result is a +String+ with
+    # +Encoding::BINARY+ (ASCII-8BIT): exact bytes, never UTF-8-validated.
+    #
+    # @note This parks until the peer sends FIN. Avoid issuing multiple
+    #   concurrent reads on the same Stream; they share one receive half.
+    # @param limit [Integer] maximum response size in bytes.
+    # @return [String] the received bytes, BINARY-encoded.
+    # @raise [QuietQUIC::ConnectionLost] if the connection is closed or lost.
+    # @raise [QuietQUIC::StreamError] if the stream is reset before FIN or
+    #   exceeds +limit+.
+    def read_to_end(limit: DEFAULT_READ_LIMIT)
+      raise ArgumentError, "limit must be a non-negative Integer" unless limit.is_a?(Integer) && limit >= 0
+
+      QuietQUIC.await(@native.read_to_end_op(limit))
+    end
+  end
+end

data/lib/quietquic/version.rb

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: 0BSD
+module QuietQUIC
+  VERSION = "0.1.0.alpha.3"
+end

data/lib/quietquic.rb

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: 0BSD
+require_relative "quietquic/version"
+require "quietquic/quietquic" # the compiled extension
+require_relative "quietquic/await"
+require_relative "quietquic/stream"
+require_relative "quietquic/connection"
+require_relative "quietquic/server"
+require_relative "quietquic/client"

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: quietquic
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha.3
+platform: ruby
+authors:
+- quietquic contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Experimental alpha Ruby bindings (native extension) for the quietquic
+  Rust crate.
+executables: []
+extensions:
+- ext/quietquic/extconf.rb
+extra_rdoc_files: []
+files:
+- HISTORY.md
+- LICENSE
+- README.md
+- examples/cooperative_async.rb
+- examples/echo_client.rb
+- examples/echo_server.rb
+- ext/quietquic/Cargo.lock
+- ext/quietquic/Cargo.toml
+- ext/quietquic/extconf.rb
+- ext/quietquic/src/client.rs
+- ext/quietquic/src/config.rs
+- ext/quietquic/src/conn.rs
+- ext/quietquic/src/errors.rs
+- ext/quietquic/src/lib.rs
+- ext/quietquic/src/pending.rs
+- ext/quietquic/src/runtime.rs
+- ext/quietquic/src/server.rs
+- lib/quietquic.rb
+- lib/quietquic/await.rb
+- lib/quietquic/client.rb
+- lib/quietquic/connection.rb
+- lib/quietquic/server.rb
+- lib/quietquic/stream.rb
+- lib/quietquic/version.rb
+homepage: https://github.com/astounding/quietquicrb
+licenses:
+- 0BSD
+metadata:
+  source_code_uri: https://github.com/astounding/quietquicrb
+  changelog_uri: https://github.com/astounding/quietquicrb/blob/main/HISTORY.md
+  documentation_uri: https://github.com/astounding/quietquicrb#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: 'Cloaked QUIC transport: scanner-invisible, PSK-authenticated, camouflaged
+  as vanilla QUIC.'
+test_files: []