quietquic 0.1.0.alpha.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2279831479628d7d0abcc6c8781589309dfb594ed6ea8181b6ec7456b31136e
+  data.tar.gz: 2e1c4b1100fb01b72378d4f9515e0983c0a1e365470e27504ac8a7d0fa75cf8c
+SHA512:
+  metadata.gz: 5d448e3a389baca997afaeb13eec314889c47b3b7b9ba170af269d61789817ce2ef5d6c85b7627ebc41d7758d75fc3deba4a9dd5a7fccfe6feafad5338c4e09d
+  data.tar.gz: 5c110b414b7a24cbe5a4c96b188dcfae6a212be88a308088b60d1f2e87553cdbfc1ccc7cb1cc3fc8293fc38d4d155c26535ad38db391e6f853cdf0d988e017e7

data/HISTORY.md

@@ -0,0 +1,79 @@
+# History and durable decisions
+
+This repository begins with a clean snapshot split from the original
+QuietQUIC monorepo in July 2026. The mother repository preserves detailed Git
+history; this document records the decisions that should guide maintenance.
+The design and plan under `docs/` are historical records and retain some
+original monorepo path references.
+
+## 0.1.0.alpha.3 — unreleased
+
+First public experimental alpha of the Ruby binding, aligned with
+`quietquic` and `quietquic-proto` 0.1.0-alpha.3. This release is not production
+quality. It provides the plain blocking/GVL-releasing Ruby interface and
+cooperates with a Ruby `Fiber.scheduler` such as the `async` gem while native
+network work runs on the binding's Tokio runtime.
+
+The native extension uses the published crates.io packages
+`quietquic` `0.1.0-alpha.3` and `quietquic-proto` `0.1.0-alpha.3`, built from
+upstream QuietQUIC commit
+[`d9580ba`](https://github.com/astounding/quietquic/commit/d9580bae624ca4edd536144956aaceae8699b9f6).
+
+Stream reads are bounded: `Stream#read_to_end(limit:)` defaults to 1 MiB and
+raises `QuietQUIC::StreamError` if an authenticated peer exceeds the limit.
+`Stream#finish_and_wait(timeout:)` sends FIN and waits for the peer's QUIC
+transport to acknowledge it; this proves transport receipt, not application
+processing.
+
+## Native bridge
+
+The gem uses Magnus/rb-sys and a Rust native extension around the Tokio
+QuietQUIC crate. A process-global Tokio runtime performs asynchronous work.
+Each operation stores a Rust result and signals a pipe file descriptor; Ruby
+waits with `IO#wait_readable`, which cooperates with a Fiber scheduler and
+releases the GVL in blocking use.
+
+Ruby `Value` objects must only be created on the Ruby VM thread. Producers
+spawned on Tokio return Rust-owned, `Send` data, and conversion happens after
+the waiting Ruby thread resumes.
+
+The result slot and wake pipe form a happens-before boundary. Wake and dispose
+must remain mutually exclusive to prevent writes to a recycled file descriptor.
+A panic in a spawned operation is caught and converted to
+`QuietQUIC::Error`; otherwise the waiting fiber could hang forever.
+
+## Lifecycle corrections
+
+`Server#close` must wake every accept operation already parked. The shutdown
+state is latched before notification and checked while installing a waiter so
+zero, one, or many concurrent accepts terminate without a missed-wakeup race.
+
+The runtime is process-owned and unsafe to reuse after `fork(2)`. The gem
+detects PID changes and raises a clear error; applications such as Puma or
+Unicorn must initialize the runtime in the worker process.
+
+Connection cleanup also depends on the Rust transport reaping locally drained
+connections, not solely `ConnectionLost`. That core correction prevented
+handle reuse from wedging repeated server lifecycles.
+
+## Stream model
+
+The Rust alpha.3 API split bidirectional streams into send and receive halves.
+Ruby keeps one `Stream` facade around those halves: send operations serialize
+with send operations, receive operations serialize with receive operations, and
+`read_to_end(limit:)` remains bounded to prevent an authenticated peer from
+growing receiver memory without limit.
+
+## Packaging decision
+
+The source gem does not vendor the Rust QuietQUIC implementation. The native
+extension depends on an exact published `quietquic` crate version from
+crates.io, and that crate selects the matching published `quietquic-proto`
+version. This keeps the Ruby gem small and makes release provenance explicit,
+at the cost of requiring Cargo registry access during native-extension builds.
+
+## Platform record
+
+The original combined tree was exercised on macOS, Linux/musl, and FreeBSD.
+FreeBSD native builds require GNU make and LLVM/libclang in addition to Ruby,
+Rust, and CMake. CI retains those prerequisites.

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (C) 2026 by the quietquic contributors
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
+OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,318 @@
+<!-- SPDX-License-Identifier: 0BSD -->
+# quietquic (Ruby bindings)
+
+**DISCLAIMER:** This was 100% AI coded, prompted by the human "creator" but
+planned and designed by multiple AI models including those from Anthropic,
+Google, and OpenAI. Trust at your own peril.
+
+Ruby bindings for the independent `quietquic` Rust project, a cloaked QUIC transport:
+scanner-invisible (silent to any peer that doesn't prove PSK possession) and
+camouflaged as ordinary QUIC v1/HTTP3 traffic on the wire. This gem is a
+**thin native-extension wrapper** (Magnus + rb-sys) around the Rust
+`quietquic` crate's public API — it adds no transport or cryptographic logic
+of its own, only a Ruby-friendly client/server surface with first-class
+`async`-gem cooperation.
+
+> **Release status:** `0.1.0.alpha.3` is an experimental preview matching the
+> `quietquic` and `quietquic-proto` 0.1.0-alpha.3 Rust components. It is **not
+> production quality** and has not received an independent security audit.
+
+See the [Rust crate's README](https://github.com/astounding/quietquic) for the full **threat model**
+(what quietquic defeats and does not defeat) — read it before deploying;
+nothing here repeats it. The design rationale for this gem specifically is in
+[`docs/specs/2026-07-04-quietquic-ruby-design.md`](docs/specs/2026-07-04-quietquic-ruby-design.md).
+
+---
+
+## Install
+
+The gem builds a native Rust extension at install time, so an installing
+machine needs a **Rust toolchain** (stable, via `rustup` or a system package)
+in addition to Ruby.
+
+### From a checkout
+
+Add this gem to a `Gemfile` pointing at this checkout (path source) or at the
+repository directly (git source):
+
+```ruby
+# Path source (e.g. this repo checked out alongside your app):
+gem "quietquic", path: "../quietquicrb"
+
+# ...or, after the repository is hosted, its git URL:
+gem "quietquic", git: "https://github.com/astounding/quietquicrb.git"
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+Bundler resolves `rb_sys`/`rake-compiler` (declared in the gemspec) and drives
+`extconf.rb`, which compiles the bundled Rust extension crate via `cargo`.
+The extension depends on the exact published `quietquic` `0.1.0-alpha.3`
+crate from crates.io; it does not use a local QuietQUIC checkout or vendored
+Rust source. This is the supported, tested install path — it's exactly what
+this repo's own test suite and CI
+(`.github/workflows/ci.yml`, covering Linux, macOS, and
+FreeBSD) exercise.
+
+### Standalone `gem install` — status
+
+A built `.gem` (`rake build` / `gem build quietquic.gemspec`) packages only
+the Ruby binding and its native extension sources. During installation, Cargo
+downloads the published Rust crates from crates.io. `rb_sys` is declared as a
+runtime dependency precisely so a plain `gem install quietquic` can resolve
+everything it needs to compile the extension. What we have **not** set up yet
+is publishing this gem to a public gem source (e.g. rubygems.org) — until
+then, `gem install quietquic` "from the internet" has nothing to fetch. If
+you have a built `.gem` file in hand (or a private gem server hosting it),
+installing it directly works today; the Bundler path/git source above remains
+the recommended flow for working from this repository.
+
+### Platforms & prerequisites
+
+- **Ruby 3.1+** (MRI). `Fiber.scheduler` / the `async` gem need a reasonably
+  modern Ruby; older Rubies are not supported.
+- **macOS, Linux, FreeBSD.**
+- **Rust 1.88+** reachable as `cargo`/`rustc` (matching the Rust crates'
+  minimum supported toolchain).
+- **FreeBSD** needs a few extra system packages beyond the default toolchain,
+  because `rb_sys` generates a GNU Makefile (the base BSD `make` can't run it)
+  and its `bindgen` build script needs `libclang`:
+
+  ```sh
+  pkg install -y ruby devel/ruby-gems rust cmake gmake llvm
+  ```
+
+  and these environment variables set for the build:
+
+  ```sh
+  export MAKE=gmake
+  export LIBCLANG_PATH="$(ls -d /usr/local/llvm*/lib | tail -1)"
+  ```
+
+  (`gmake` because `rb_sys`/rake-compiler emit a GNU-style Makefile; `llvm`
+  supplies `libclang.so` for rb-sys's `bindgen` step.) This is exactly what
+  `.github/workflows/ci.yml`'s `freebsd` job does.
+
+---
+
+## Quickstart
+
+```ruby
+require "quietquic"
+```
+
+### Server
+
+```ruby
+srv = QuietQUIC::Server.bind(
+  listen:  "0.0.0.0:4433",
+  clients: { "laptop" => "aabb…(64 hex chars)" } # client_id => psk_hex
+)
+puts srv.local_address # => "0.0.0.0:4433" (the kernel-chosen port if you bound :0)
+
+loop do
+  conn = srv.accept # parks the fiber under Async; blocks (GVL-released) otherwise
+  Thread.new do
+    stream = conn.accept_stream
+    data = stream.read_to_end
+    puts "got #{data.bytesize} bytes from #{conn.remote_address}"
+
+    # Reply on a second stream.
+    reply = conn.open_stream
+    reply.write_all("thanks: #{data}")
+    reply.finish_and_wait
+  end
+end
+```
+
+Or from a TOML secrets file (reuses the crate's own loader, including its
+`chmod 600` group/world-readable warning):
+
+```ruby
+srv = QuietQUIC::Server.bind_toml("server.toml")
+```
+
+### Client
+
+```ruby
+conn = QuietQUIC::Client.connect(
+  client_id: "laptop",
+  psk:       "aabb…(64 hex chars)",
+  server:    "example.com:4433"
+)
+
+out = conn.open_stream
+out.write_all("hello over a cloaked pipe")
+out.finish
+
+reply_stream = conn.accept_stream
+puts reply_stream.read_to_end
+
+conn.close
+```
+
+Or: `conn = QuietQUIC::Client.connect_toml("client.toml")`.
+
+That's the whole alpha surface: `Server.bind`/`.bind_toml`/`#accept`/`#local_address`/`#close`,
+`Client.connect`/`.connect_toml`, and `Connection#open_stream`/`#accept_stream`/`#remote_address`/`#close`,
+`Stream#write_all`/`#finish`/`#finish_and_wait`/`#read_to_end`. Bytes in and out are binary
+`String`s (`Encoding::BINARY`); PSKs are 64-hex-character `String`s.
+
+---
+
+## Async cooperation
+
+Every method that can wait (`Server#accept`, `Client.connect`/`.connect_toml`,
+`Connection#open_stream`/`#accept_stream`, `Stream#write_all`/`#finish`/
+`#finish_and_wait`/`#read_to_end`) goes through the same bridge:
+
+- **Inside `Async do … end`** (the [`async`](https://github.com/socketry/async)
+  gem), the waiting call parks the current fiber via `Fiber.scheduler`'s
+  `io_wait` hook, so the reactor runs other tasks on the same thread while it
+  waits. Two concurrent connections/streams inside one `Async` block genuinely
+  interleave rather than serialize.
+- **With no scheduler installed**, the same call blocks the calling thread
+  while releasing the GVL, so plain scripts work unmodified and other Ruby
+  `Thread`s keep making progress.
+
+`async` is an optional peer dependency — this gem works with or without it
+installed; it only changes behavior if a `Fiber.scheduler` is actually active
+when you call in. Applications that want this mode must add `gem "async"` to
+their Gemfile (or install it separately); it is not a runtime dependency of
+`quietquic`.
+
+### Two execution models
+
+The ordinary two-terminal examples require no Ruby event-loop library:
+
+```sh
+ruby examples/echo_server.rb
+ruby examples/echo_client.rb
+```
+
+QuietQUIC performs their network operations on its native process-global Tokio
+runtime. Ruby waits through the native self-pipe bridge; without a fiber
+scheduler the calling Ruby thread blocks with the GVL released.
+
+The cooperative example keeps the Ruby application on one event-loop thread:
+
+```sh
+gem install async
+ruby examples/cooperative_async.rb
+```
+
+It deliberately parks a server fiber in `accept`, runs a visible ticker on the
+same Ruby thread, and then completes an echo round trip. “Single-threaded”
+describes the Ruby application side: native Tokio worker threads still perform
+the transport I/O. The example does not use `Thread.new`.
+
+---
+
+## Fork safety
+
+This gem runs async operations on a process-global multi-thread tokio runtime.
+That runtime's worker threads **do not survive `fork(2)`** — only the forking
+thread is duplicated into the child. So a pre-forking Ruby server
+(Puma/Unicorn, or Spring) that touches the runtime in the **parent** and then
+forks leaves each worker child with a runtime whose worker threads are gone;
+the child's first await would otherwise hang forever.
+
+To make that a loud, actionable failure instead of a silent hang, the gem
+records the PID at runtime initialization and checks it before every async op.
+A call from a process that inherited an already-initialized runtime raises:
+
+```
+QuietQUIC::Error: quietquic's async runtime does not survive fork();
+initialize it after forking (e.g. in a Puma on_worker_boot / after_fork hook)
+rather than before
+```
+
+**Workaround: initialize (and use) quietquic only *after* forking.** Don't
+open connections/servers in the parent; do it in the worker-boot hook so each
+child builds its own runtime:
+
+```ruby
+# config/puma.rb
+on_worker_boot do
+  # First quietquic use in THIS child initializes its own runtime.
+  $qq_conn = QuietQUIC::Client.connect(client_id: "...", psk: "...", server: "...")
+end
+```
+
+(Unicorn: `after_fork`. Spring: re-establish inside the forked worker.) A
+parent that never touches quietquic before forking is fine — the child
+initializes the runtime in its own process on first use.
+
+---
+
+## Streams
+
+The Rust `quietquic` 0.1.0-alpha.3 API splits bidirectional streams into send
+and receive halves. The Ruby API keeps a small `Stream` facade around those
+halves: `write_all`, `finish`, and `finish_and_wait` operate on the send half;
+`read_to_end(limit:)` operates on the receive half.
+
+`finish` queues FIN locally. `finish_and_wait(timeout: 10)` queues FIN and waits
+for the peer's QUIC transport to acknowledge the send half; that proves
+transport receipt, not that the peer application processed the bytes. Use it
+before immediately closing a connection whose final stream must reach the peer.
+The timeout is an upper bound, not an unconditional delay.
+
+`read_to_end(limit:)` parks until the peer sends FIN and defaults to a 1 MiB
+limit so an authenticated peer cannot grow receiver memory without bound.
+
+Send-half calls on the same `Stream` are serialized with each other, and
+receive-half calls are serialized with each other. A read and a write on the
+same `Stream` use separate native halves, but both sides of a protocol still
+need sane ordering: if both peers wait to read before either peer finishes
+writing, the application protocol has deadlocked.
+
+The echo examples use two streams for a simple request/reply shape:
+
+```ruby
+out = conn.open_stream
+out.write_all(payload)
+out.finish
+
+in_stream = conn.accept_stream
+reply = in_stream.read_to_end
+```
+
+---
+
+## Exceptions
+
+All native-boundary errors raise under one hierarchy so a bare
+`rescue QuietQUIC::Error` catches everything the gem can raise:
+
+- `QuietQUIC::Error` — base class (`< StandardError`).
+  - `QuietQUIC::ConfigError` — bad config: malformed PSK hex, a bad listen/
+    server address, a missing/invalid TOML file.
+  - `QuietQUIC::ConnectError` — the client's handshake failed or timed out
+    (the crate's own internal connect timeout, ~10s, covers "nothing answered").
+  - `QuietQUIC::ConnectionLost` — a previously-established connection was
+    closed or dropped (locally or by the peer) while a call was waiting on it.
+  - `QuietQUIC::StreamError` — a stream-level failure: reset, stopped, or
+    refused.
+
+A Rust panic in the extension is turned into a Ruby exception rather than
+aborting the process — a bug in the extension should not crash your Ruby
+process outright:
+
+- A panic at a **synchronous** native boundary is converted to an exception by
+  Magnus's panic hook.
+- A panic inside an **async** operation (a future spawned on the runtime) is
+  caught and surfaced as `QuietQUIC::Error` (base class) with the message
+  `"quietquic internal error: the async operation panicked"`, so the awaiting
+  call raises instead of crashing *or* hanging. (Without this, the result slot
+  would never be populated and the awaiting fiber/thread would park forever.)
+
+---
+
+## License
+
+0BSD (BSD Zero Clause), same as the Rust crate. See [`LICENSE`](LICENSE).

data/examples/cooperative_async.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# SPDX-License-Identifier: 0BSD
+#
+# A complete echo round trip driven by one cooperative Ruby event-loop thread.
+# QuietQUIC performs network I/O on its native Tokio runtime; while a Ruby
+# fiber is awaiting that work, Async can run other Ruby fibers on this thread.
+#
+# Prerequisite:
+#   gem install async
+#
+# Run:
+#   ruby examples/cooperative_async.rb
+
+require "async"
+require "timeout"
+require "quietquic"
+
+PSK = "00" * 31 + "07"
+CLIENT_ID = "demo-client"
+MESSAGE = "hello from cooperative Ruby"
+
+ruby_thread = Thread.current
+ticks = 0
+echo_verified = false
+server = nil
+
+Timeout.timeout(10) do
+  Async do |task|
+    server = QuietQUIC::Server.bind(
+      listen: "127.0.0.1:0",
+      clients: { CLIENT_ID => PSK },
+    )
+
+    server_task = task.async do
+      connection = server.accept
+      begin
+        incoming = connection.accept_stream
+        payload = incoming.read_to_end
+
+        reply = connection.open_stream
+        reply.write_all(payload)
+        reply.finish
+      ensure
+        connection&.close
+      end
+    end
+
+    # server.accept above is now pending. These ticks prove that waiting for
+    # native I/O parks that fiber instead of blocking this Ruby event loop.
+    ticker_task = task.async do
+      3.times do
+        task.sleep(0.05)
+        raise "ticker moved to another Ruby thread" unless Thread.current.equal?(ruby_thread)
+
+        ticks += 1
+        puts "Ruby event loop did other work (tick #{ticks})"
+      end
+    end
+
+    ticker_task.wait
+
+    client_task = task.async do
+      connection = QuietQUIC::Client.connect(
+        client_id: CLIENT_ID,
+        psk: PSK,
+        server: server.local_address,
+      )
+      begin
+        outgoing = connection.open_stream
+        outgoing.write_all(MESSAGE)
+        outgoing.finish
+
+        response = connection.accept_stream.read_to_end
+        raise "echo mismatch" unless response == MESSAGE.b
+
+        echo_verified = true
+        puts "echo verified: #{response.inspect}"
+      ensure
+        connection&.close
+      end
+    end
+
+    client_task.wait
+    server_task.wait
+  ensure
+    server&.close
+  end
+end
+
+raise "cooperative task did not progress" unless ticks == 3
+raise "echo task did not complete" unless echo_verified

data/examples/echo_client.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# SPDX-License-Identifier: 0BSD
+#
+# A minimal QuietQUIC echo client: connects to a running echo server (see
+# echo_server.rb), opens a stream, sends a message, finishes the stream, then
+# accepts the server's echoed reply on a second stream and prints it.
+#
+# Usage:
+#   ruby examples/echo_client.rb [server_addr] [psk_hex] [message]
+#
+#   server_addr defaults to "127.0.0.1:4433" (must match echo_server.rb)
+#   psk_hex     defaults to the same demo PSK echo_server.rb uses
+#   message     defaults to "hello, quietquic"
+
+require "quietquic"
+
+SERVER = ARGV[0] || "127.0.0.1:4433"
+PSK = ARGV[1] || "00" * 31 + "07"
+MESSAGE = ARGV[2] || "hello, quietquic"
+CLIENT_ID = "demo-client"
+
+conn = QuietQUIC::Client.connect(client_id: CLIENT_ID, psk: PSK, server: SERVER)
+puts "connected to #{conn.remote_address}"
+
+begin
+  out = conn.open_stream
+  out.write_all(MESSAGE)
+  out.finish
+  puts "sent #{MESSAGE.bytesize} byte(s): #{MESSAGE.inspect}"
+
+  reply_stream = conn.accept_stream
+  reply = reply_stream.read_to_end
+  puts "received echo: #{reply.inspect}"
+
+  raise "echo mismatch!" unless reply == MESSAGE.b
+
+  puts "echo verified OK"
+ensure
+  conn.close
+end

data/examples/echo_server.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# SPDX-License-Identifier: 0BSD
+#
+# A minimal QuietQUIC echo server: binds to a listen address, accepts one
+# connection, accepts one stream on it, reads the stream to end, and echoes
+# the exact bytes back to the peer on a second stream.
+#
+# Usage:
+#   ruby examples/echo_server.rb [listen_addr] [psk_hex]
+#
+#   listen_addr defaults to "127.0.0.1:4433"
+#   psk_hex     defaults to a demo PSK (64 hex chars) -- DO NOT use this
+#               demo PSK for anything real; generate your own with e.g.
+#               `SecureRandom.hex(32)`.
+#
+# Run this first, then run echo_client.rb (same psk_hex if you override it)
+# in another terminal.
+
+require "quietquic"
+
+$stdout.sync = true
+
+LISTEN = ARGV[0] || "127.0.0.1:4433"
+PSK = ARGV[1] || "00" * 31 + "07"
+CLIENT_ID = "demo-client"
+
+srv = QuietQUIC::Server.bind(listen: LISTEN, clients: { CLIENT_ID => PSK })
+puts "listening on #{srv.local_address}"
+
+begin
+  conn = srv.accept
+  puts "accepted connection from #{conn.remote_address}"
+
+  stream = conn.accept_stream
+  data = stream.read_to_end
+  puts "received #{data.bytesize} byte(s): #{data.inspect}"
+
+  echo = conn.open_stream
+  echo.write_all(data)
+  # `finish` only queues FIN locally. Wait for the peer to acknowledge it so
+  # closing below cannot discard the final echo on a slower or NATted path.
+  echo.finish_and_wait
+  puts "echoed #{data.bytesize} byte(s) back"
+
+  conn.close
+ensure
+  srv.close
+end