quicsilver 0.4.0 → 0.5.0

data/benchmarks/latency.rb

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Quicsilver, Falcon and Puma over a link with a real round trip.
+#
+# This is the comparison loopback cannot give you. On localhost every protocol
+# looks the same because there is no round trip to spend, and the benchmark
+# measures Ruby rather than HTTP. Add a delay and the protocols start to differ
+# for the reasons they were designed to.
+#
+# Loss is in the same currency on both sides: one in N packets costs the
+# affected stream one round trip. On UDP that is a dropped datagram. On TCP the
+# bytes cannot be dropped, so the stream stalls for a round trip instead, which
+# is what the receiving kernel does while it waits for the retransmission. Same
+# probability, same cost, and what is left over is the protocol's own
+# behaviour. See Impair::Tcp for what that does and does not reproduce.
+#
+#   ruby benchmarks/latency.rb
+#   DELAY_MS=5,25,50 REQUESTS=200 CONCURRENCY=20 ruby benchmarks/latency.rb
+#
+# DELAY_MS is one-way, so the round trip is twice it. Every server runs through
+# a relay, including at 0ms, so the relay is in the baseline rather than a
+# handicap applied to one side.
+
+ENV["RUNS"] ||= "1"
+require_relative "compare"
+require "impair"
+
+DELAYS_MS = ENV.fetch("DELAY_MS", "0,25").split(",").map { |value| Float(value) }
+LOSS = Integer(ENV.fetch("LOSS", "0"))
+REPEATS = Integer(ENV.fetch("REPEATS", "3"))
+SEED = Integer(ENV.fetch("SEED", "1234"))
+
+def median_of(values)
+  sorted = values.sort
+  sorted[sorted.length / 2]
+end
+
+def with_udp_relay(target_port, delay_ms)
+  proxy = Impair::Udp.new(
+    host: "::1", target_host: "::1", target_port: target_port,
+    delay: delay_ms / 1000.0, loss: LOSS, seed: SEED
+  ).start
+  yield proxy.port
+ensure
+  proxy&.stop
+end
+
+# The TCP stall per lost segment is one round trip, and Impair derives that as
+# 2 * delay (Impair::Config#rtt) rather than taking it separately: two knobs
+# for one quantity is how the two arms drift apart. This passed rtt: as well,
+# which Config now rejects outright, so this benchmark raised ArgumentError on
+# every run. Dropping it preserves the behaviour, since the value passed was
+# exactly 2 * delay.
+def with_tcp_relay(target_port, delay_ms, host: "127.0.0.1")
+  proxy = Impair::Tcp.new(
+    host: host, target_host: host, target_port: target_port,
+    delay: delay_ms / 1000.0, loss: LOSS, seed: SEED
+  ).start
+  yield proxy.port
+ensure
+  proxy&.stop
+end
+
+def measure_with_delay(name, delay_ms)
+  port = free_port
+  case name
+  when "quicsilver"
+    with_quicsilver(port) do
+      with_udp_relay(port, delay_ms) { |front| measure_quicsilver(front) }
+    end
+  when "falcon"
+    with_falcon(port) do
+      with_tcp_relay(port, delay_ms) { |front| measure_async("falcon", "HTTP/2", front) }
+    end
+  when "puma"
+    with_puma(port) do
+      with_tcp_relay(port, delay_ms) { |front| measure_async("puma", "HTTP/1.1", front, host: "127.0.0.1") }
+    end
+  end
+end
+
+puts "Quicsilver, Falcon and Puma over a delayed link"
+puts "#{REQUESTS} requests, #{CONCURRENCY} in flight, #{REPEATS} repeats, all over TLS"
+puts "delay is one-way in milliseconds, so the round trip is twice it"
+puts "every server runs through an impairment relay, including at 0ms"
+puts "loss 1-in-#{LOSS} packets, costing the affected stream one round trip" if LOSS.positive?
+puts
+
+rows = []
+
+DELAYS_MS.each do |delay_ms|
+  %w[quicsilver falcon puma].each do |name|
+    attempts = REPEATS.times.filter_map do
+      result = measure_with_delay(name, delay_ms)
+      next unless result
+
+      stats = Benchmarks.stats(result.times)
+      {rps: result.rps, p50: stats[:p50], p95: stats[:p95], p99: stats[:p99], failed: result.failed}
+    rescue StandardError => error
+      warn "#{name} at #{delay_ms}ms failed: #{error.class}: #{error.message}"
+      warn error.backtrace.first(3).join("\n") if ENV["DEBUG"]
+      nil
+    end
+    next if attempts.empty?
+
+    rows << [delay_ms, name, attempts]
+  end
+end
+
+protocols = {"quicsilver" => "HTTP/3", "falcon" => "HTTP/2", "puma" => "HTTP/1.1"}
+
+puts format("%-8s %-12s %-9s %9s %9s %9s %9s %8s",
+  "delay", "server", "protocol", "Req/s", "p50", "p95", "p99", "Failed")
+puts "-" * 84
+rows.each do |(delay_ms, name, attempts)|
+  puts format("%6.0fms %-12s %-9s %9.0f %7.2fms %7.2fms %7.2fms %8d",
+    delay_ms, name, protocols.fetch(name),
+    median_of(attempts.map { |a| a[:rps] }),
+    median_of(attempts.map { |a| a[:p50] }),
+    median_of(attempts.map { |a| a[:p95] }),
+    median_of(attempts.map { |a| a[:p99] }),
+    attempts.sum { |a| a[:failed] })
+end
+
+puts
+puts "HTTP/1.1 opens a connection per concurrent request, so it pays the"
+puts "handshake more often as delay rises. HTTP/2 and HTTP/3 multiplex over one."

data/benchmarks/loss.rb

@@ -0,0 +1,193 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Head-of-line blocking, measured on a damaged link.
+#
+# HTTP/2 multiplexes streams over one TCP connection, and TCP owes the
+# application one ordered byte stream, so a lost packet stalls every stream
+# sharing that connection. HTTP/3 scopes ordering to the stream, so a lost
+# packet stalls only the streams whose data it carried. RFC 9114 1.1 puts it
+# as: "because the parallel nature of HTTP/2's multiplexing is not visible to
+# TCP's loss recovery mechanisms, a lost or reordered packet causes all active
+# transactions to experience a stall regardless of whether that transaction was
+# directly impacted by the lost packet."
+#
+# That is the central claim of HTTP/3, and loopback cannot show it, because
+# loopback never drops a packet. So the packets are dropped in userspace:
+#
+#   client ──▶ Impair::Udp (drops 1 in N)          ──▶ Quicsilver  HTTP/3
+#   client ──▶ Impair::Tcp (stalls + halves cwnd 1 in N) ──▶ Falcon  HTTP/2
+#   client ──▶ Impair::Tcp (stalls + halves cwnd 1 in N) ──▶ Puma    HTTP/1.1
+#
+# The three relays take the same link config. The TCP relay cannot drop bytes,
+# so it charges what a drop costs instead: a one-RTT stall of the connection
+# and a halved sender window for every segment the dice say was lost, an RTO
+# and window collapse for a burst. Same loss probability per packet, same
+# sender reaction; see Impair::Tcp for what that does and does not reproduce.
+#
+# Kernel shaping was tried first and abandoned. macOS dummynet does not shape
+# the loopback interface: pings through a 3% pipe reported 0.0% loss, so the
+# experiment was reporting "loss changes nothing" while dropping nothing. The
+# relay counts what it drops, and a row is only reported when the relay
+# confirms it saw every packet and the measured loss is close to the request.
+#
+#   ruby benchmarks/loss.rb
+#   LOSS=0,50,20 DELAY_MS=15 BURST=5 REQUESTS=1500 ruby benchmarks/loss.rb
+#   SERVERS=quicsilver,puma ruby benchmarks/loss.rb
+#
+# LOSS is 1-in-N, the way MsQuic's emulated-performance runs express it, with 0
+# meaning no loss. 10 is a brutal 10%; real networks are 1-in-100 or worse.
+#
+# With REPLAY=1 the HTTP/3 arm records its loss decisions and the TCP arms
+# replay them, so all three see the identical pattern rather than the same
+# seed. Whatever difference remains is the protocol.
+
+ENV["RUNS"] ||= "1"
+# Every arm binds and dials one literal so the resolver order of "localhost"
+# cannot pick a family the relay is not listening on. Puma only binds v4.
+ENV["QUIC_ADDRESS"] ||= "127.0.0.1"
+require_relative "compare"
+require "impair"
+
+HOST = "127.0.0.1"
+SERVERS = ENV.fetch("SERVERS", "quicsilver,falcon,puma").split(",")
+LOSS_RATES = ENV.fetch("LOSS", "0,100,50,20,10").split(",").map { |value| Integer(value) }
+REORDER = Integer(ENV.fetch("REORDER", "0"))
+# Mean length of a loss burst. Real links lose packets in runs, not
+# independently, and i.i.d. loss understates HTTP/3: a burst confined to one
+# stream's packets stalls that stream, where TCP would stall all of them. The
+# overall rate stays 1-in-LOSS; only the clustering changes. 0 is i.i.d.
+BURST = Integer(ENV.fetch("BURST", "0"))
+# One-way delay in milliseconds, so RTT is twice this. Loss without a round
+# trip understates itself: loopback retransmits in microseconds, and the cost
+# of a retransmission is one RTT. This is the axis that makes loss hurt.
+DELAY_MS = Float(ENV.fetch("DELAY_MS", "0"))
+SEED = Integer(ENV.fetch("SEED", "1234"))
+REPLAY = ENV["REPLAY"] == "1"
+# Repeats per row, because this server's own throughput varies enough between
+# runs to swallow the effect being measured. A single run once showed higher
+# throughput at 9% loss than at none, which is not a finding about loss.
+REPEATS = Integer(ENV.fetch("REPEATS", "3"))
+
+PROTOCOLS = {"quicsilver" => "HTTP/3", "falcon" => "HTTP/2", "puma" => "HTTP/1.1"}.freeze
+
+def link_for(loss)
+  {
+    loss: loss, reorder: REORDER, delay: DELAY_MS / 1000.0, seed: SEED,
+    # burst is a clustering of loss, so it is meaningless without any, and
+    # Impair rejects the pair rather than silently ignoring it.
+    **(BURST.positive? && loss.positive? ? {burst: BURST} : {}),
+  }
+end
+
+# Runs +name+ behind the matching relay and yields the relay's port. Returns
+# [result, relay] with the relay stopped.
+def with_impaired(name, loss, replay: nil)
+  relay_class = (name == "quicsilver") ? Impair::Udp : Impair::Tcp
+  port = free_port
+  server = case name
+  when "quicsilver" then method(:with_quicsilver)
+  when "falcon" then method(:with_falcon)
+  when "puma" then method(:with_puma)
+  end
+
+  server.call(port) do
+    relay = relay_class.start(
+      host: HOST, target_host: HOST, target_port: port,
+      trace: REPLAY && replay.nil?, replay: replay, **link_for(loss)
+    )
+    begin
+      result = case name
+      when "quicsilver" then measure_quicsilver(relay.port)
+      else measure_async(name, PROTOCOLS.fetch(name), relay.port, host: HOST)
+      end
+      [result, relay]
+    ensure
+      relay.stop
+    end
+  end
+end
+
+def median_of(values)
+  sorted = values.sort
+  sorted[sorted.length / 2]
+end
+
+puts "Head-of-line blocking under induced packet loss"
+puts "#{REQUESTS} requests, #{CONCURRENCY} in flight, #{REPEATS} repeats, through a userspace impairment relay"
+puts "connections: " + CONNECTIONS.map { |proto, n| "#{proto} on #{n}" }.join(", ")
+puts "loss is 1-in-N applied in both directions, seed #{SEED}"
+puts "bursts averaging #{BURST} packets, overall rate unchanged" if BURST.positive?
+puts "one-way delay #{DELAY_MS}ms, so about #{(DELAY_MS * 2).round}ms round trip" if DELAY_MS.positive?
+puts "TCP arms replay the HTTP/3 arm's loss decisions" if REPLAY
+puts
+
+rows = []
+
+LOSS_RATES.each do |loss|
+  SERVERS.each do |name|
+    attempts = REPEATS.times.filter_map do |repeat|
+      # With REPLAY, the HTTP/3 run of this row and repeat is the script.
+      replay = REPLAY && name != "quicsilver" ? rows.dig(-1, :traces, repeat) : nil
+      result, relay = with_impaired(name, loss, replay: replay)
+      counts = relay.counts
+
+      # Two things the relay must confirm before the row counts. That it saw
+      # every packet -- kernel drops before the relay are invisible to
+      # loss_rate -- and that the loss it applied is close to what was asked.
+      # The relay cannot know how many packets the client sent, so the first
+      # check is on its own queue only; the second catches the rest.
+      if counts.overrun.positive?
+        warn format("  %s 1-in-%d: relay overran its queue %d times, discarding", name, loss, counts.overrun)
+        next
+      end
+      expected = loss.zero? ? 0.0 : 1.0 / loss
+      if loss.positive? && counts.loss_rate < expected / 2
+        warn format("  %s 1-in-%d: relay dropped only %.2f%%, discarding", name, loss, counts.loss_rate * 100)
+        next
+      end
+
+      stats = Benchmarks.stats(result.times)
+      {rps: result.rps, p50: stats[:p50], p95: stats[:p95], p99: stats[:p99],
+       failed: result.failed, measured: counts.loss_rate,
+       longest_burst: counts.longest_burst, trace: relay.trace}
+    rescue StandardError => error
+      warn "#{name} 1-in-#{loss} failed: #{error.class}: #{error.message}"
+      warn error.backtrace.first(3).join("\n") if ENV["DEBUG"]
+      nil
+    end
+    next if attempts.empty?
+
+    rows << {loss: loss, name: name, attempts: attempts, traces: attempts.map { |a| a[:trace] }}
+  end
+end
+
+puts format("%-9s %-10s %-8s %8s %5s %7s %9s %9s %9s %6s %13s",
+  "loss", "server", "protocol", "measured", "burst", "Req/s", "p50", "p95", "p99", "Failed", "Req/s range")
+puts "-" * 104
+last_loss = nil
+rows.each do |row|
+  puts if last_loss && row[:loss] != last_loss
+  last_loss = row[:loss]
+  attempts = row[:attempts]
+  rates = attempts.map { |a| a[:rps] }
+  puts format("%-9s %-10s %-8s %7.2f%% %5d %7.0f %7.2fms %7.2fms %7.2fms %6d %13s",
+    row[:loss].zero? ? "none" : "1-in-#{row[:loss]}",
+    row[:name], PROTOCOLS.fetch(row[:name]),
+    median_of(attempts.map { |a| a[:measured] }) * 100,
+    attempts.map { |a| a[:longest_burst] }.max,
+    median_of(rates),
+    median_of(attempts.map { |a| a[:p50] }),
+    median_of(attempts.map { |a| a[:p95] }),
+    median_of(attempts.map { |a| a[:p99] }),
+    attempts.sum { |a| a[:failed] },
+    (rates.length > 1 ? format("%.0f-%.0f", rates.min, rates.max) : "single"))
+end
+
+puts
+puts "The relay is in the path for every row, including the first, so the"
+puts "no-loss row is the baseline rather than a direct connection."
+puts "Loss is applied to both directions, so a request and its response each"
+puts "face the dice. On TCP a lost segment stalls the whole connection one RTT"
+puts "and halves the sender's window (RFC 5681); a burst waits out the RTO and"
+puts "collapses it. No SACK, so the TCP rows are still conservative in TCP's favour."

data/benchmarks/mobile.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# A phone's network, for a few seconds at a time.
+#
+# The link's RTT swings, loss comes in bursts, and every couple of seconds
+# the NAT forgets the client's mapping. QUIC was built for the last one:
+# the client's source port changes, the server validates the new path, and
+# the connection carries on (RFC 9000 §9). A TCP connection is identified by
+# that port, so when it changes the connection is gone and every stream on
+# it dies with it; the client starts over with a new handshake.
+#
+#   client ──▶ Impair::Udp (rebind every 2s)  ──▶ Quicsilver  HTTP/3
+#   client ──▶ Impair::Tcp (reset every 2s)   ──▶ Falcon      HTTP/2
+#   client ──▶ Impair::Tcp (reset every 2s)   ──▶ Puma        HTTP/1.1
+#
+# rebind and reset are the same event seen by the two transports, which is
+# why the schedule is one Scenario driving all three arms. RTT and loss ride
+# along so the rebind lands on a busy link rather than a quiet one.
+#
+#   ruby benchmarks/mobile.rb
+#   REBIND_EVERY=1 REQUESTS=2000 ruby benchmarks/mobile.rb
+#
+# Failed counts requests that got no 200, which for TCP includes every
+# request in flight when the reset landed. That is the finding, not noise.
+
+ENV["RUNS"] ||= "1"
+ENV["QUIC_ADDRESS"] ||= "127.0.0.1"
+require_relative "compare"
+require "impair"
+
+HOST = "127.0.0.1"
+SERVERS = ENV.fetch("SERVERS", "quicsilver,falcon,puma").split(",")
+REBIND_EVERY = Float(ENV.fetch("REBIND_EVERY", "2"))
+DELAY_MS = Float(ENV.fetch("DELAY_MS", "20"))
+LOSS = Integer(ENV.fetch("LOSS", "50"))
+BURST = Integer(ENV.fetch("BURST", "5"))
+REPEATS = Integer(ENV.fetch("REPEATS", "3"))
+SEED = Integer(ENV.fetch("SEED", "1234"))
+PROTOCOLS = {"quicsilver" => "HTTP/3", "falcon" => "HTTP/2", "puma" => "HTTP/1.1"}.freeze
+
+# The one schedule. The RTT swings ±10ms around the base on a 6s period;
+# the NAT rebinds on the interval. A TCP relay has no rebind, so it resets:
+# that is what a rebind does to TCP.
+SCENARIO = Impair::Scenario.new do
+  every(0.1) { |relay, t| relay.update(delay: DELAY_MS / 1000.0 + wave(t, amplitude: 0.010, period: 6)) }
+  every(REBIND_EVERY) do |relay, t|
+    next if t.zero? # the first tick is t=0; nothing to rebind yet
+
+    relay.respond_to?(:rebind) ? relay.rebind : relay.reset
+  end
+end
+
+def link
+  {loss: LOSS, burst: BURST, delay: DELAY_MS / 1000.0, seed: SEED}
+end
+
+def with_impaired(name)
+  relay_class = (name == "quicsilver") ? Impair::Udp : Impair::Tcp
+  port = free_port
+  server = case name
+  when "quicsilver" then method(:with_quicsilver)
+  when "falcon" then method(:with_falcon)
+  when "puma" then method(:with_puma)
+  end
+  server.call(port) do
+    relay = relay_class.new(host: HOST, target_host: HOST, target_port: port, **link).start
+    relay.run(SCENARIO)
+    begin
+      result = yield relay.port
+      [result, relay.stop]
+    ensure
+      relay.stop
+    end
+  end
+end
+
+def median_of(values)
+  sorted = values.sort
+  sorted[sorted.length / 2]
+end
+
+puts "A mobile link: RTT swinging, bursty loss, NAT rebinding every #{REBIND_EVERY}s"
+puts "#{REQUESTS} requests, #{CONCURRENCY} in flight, #{REPEATS} repeats"
+puts "connections: " + CONNECTIONS.map { |proto, n| "#{proto} on #{n}" }.join(", ")
+puts format("base RTT %dms ±20ms, loss 1-in-%d in bursts of ~%d, seed %d", DELAY_MS * 2, LOSS, BURST, SEED)
+puts "QUIC rebinds; TCP has no such thing, so it is reset on the same schedule"
+puts "client retries: #{RETRIES}"
+puts
+
+rows = SERVERS.filter_map do |name|
+  attempts = REPEATS.times.filter_map do
+    result, counts = with_impaired(name) do |port|
+      (name == "quicsilver") ? measure_quicsilver(port) : measure_async(name, PROTOCOLS[name], port, host: HOST)
+    end
+    stats = Benchmarks.stats(result.times)
+    {rps: result.rps, p50: stats[:p50], p95: stats[:p95], p99: stats[:p99], failed: result.failed,
+     completed: result.times.size, events: counts.scenario_events, measured: counts.loss_rate}
+  rescue StandardError => error
+    warn "#{name} failed: #{error.class}: #{error.message}"
+    warn error.backtrace.first(3).join("\n") if ENV["DEBUG"]
+    nil
+  end
+  next if attempts.empty?
+
+  [name, attempts]
+end
+
+puts format("%-10s %-8s %8s %7s %9s %9s %9s %9s %7s", "server", "protocol", "measured", "Req/s", "p50", "p95", "p99", "completed", "Failed")
+puts "-" * 86
+rows.each do |(name, attempts)|
+  puts format("%-10s %-8s %7.2f%% %7.0f %7.2fms %7.2fms %7.2fms %9d %7d",
+    name, PROTOCOLS[name],
+    median_of(attempts.map { |a| a[:measured] }) * 100,
+    median_of(attempts.map { |a| a[:rps] }),
+    median_of(attempts.map { |a| a[:p50] }),
+    median_of(attempts.map { |a| a[:p95] }),
+    median_of(attempts.map { |a| a[:p99] }),
+    attempts.sum { |a| a[:completed] },
+    attempts.sum { |a| a[:failed] })
+end
+puts
+puts "Failed is requests that got no 200, with RETRIES=#{RETRIES}. At 0 that is every"
+puts "TCP request in flight when the reset landed; a browser would retry them,"
+puts "so RETRIES=3 shows the user's view and 0 shows the transport's."

data/docs/connection_identity.md

@@ -0,0 +1,141 @@
+# Connection identity and QUIC routing IDs
+
+## Rack request identity
+
+Rack apps receive these env values:
+
+- `env["quicsilver.connection_id"]`
+  - Opaque QUIC connection identity.
+  - Stable across requests/streams on the same QUIC connection.
+  - Currently backed by MsQuic's original destination connection ID.
+  - Do not parse this for load-balancing or backend routing decisions.
+
+- `env["quicsilver.stream_id"]`
+  - QUIC stream id for this HTTP/3 request.
+  - Different requests on the same connection have different stream ids.
+
+- `env["quicsilver.request_id"]`
+  - Recommended app/log/correlation identity.
+  - Format without fixed server id:
+    - `<connection_id>:<stream_id>`
+  - Format with fixed server id:
+    - `<transport_server_id>:<connection_id>:<stream_id>`
+  - This is the value applications and middleware should prefer.
+
+Quicsilver does not expose separate Rack env fields for transport-only routing metadata such as `transport_server_id` or the original destination CID. Use `quicsilver.request_id` for request correlation.
+
+## Fixed MsQuic Server ID
+
+`transport_server_id` configures MsQuic's fixed 4-byte Server ID.
+
+- Purpose:
+  - Allows QUIC-aware load balancers to route using the server id embedded in MsQuic-generated connection IDs.
+  - Useful after the server has generated CIDs for an established connection.
+
+- Configuration:
+
+  ```ruby
+  config = Quicsilver::Transport::Configuration.new(
+    cert_file,
+    key_file,
+    transport_server_id: "01020304"
+  )
+  ```
+
+- Rules:
+  - Must be exactly 4 bytes encoded as 8 hex characters.
+  - Hex is normalized to lowercase.
+  - Server startup applies this before MsQuic is opened.
+  - This is MsQuic process-global state, so set it once per server process/pod.
+
+- Common deployment pattern:
+
+  ```ruby
+  config = Quicsilver::Transport::Configuration.new(
+    cert_file,
+    key_file,
+    transport_server_id: ENV["QUICSILVER_TRANSPORT_SERVER_ID"]
+  )
+  ```
+
+  ```sh
+  QUICSILVER_TRANSPORT_SERVER_ID=01020304 bundle exec ruby server.rb
+  ```
+
+When configured, Rack request ids include the server id prefix:
+
+```text
+01020304:7f9a23c001de88b0:4
+```
+
+## CIBIR ID
+
+`cibir_id` configures MsQuic CIBIR: Connection ID Based Implicit Routing.
+
+- Purpose:
+  - Provides routing bytes in the client's destination connection ID.
+  - Useful for routing the first packet/initial connection to the right listener or shard.
+  - The meaning of the bytes is application/load-balancer defined.
+
+- Server/listener configuration:
+
+  ```ruby
+  config = Quicsilver::Transport::Configuration.new(
+    cert_file,
+    key_file,
+    cibir_id: "0a"
+  )
+  ```
+
+- Client configuration:
+
+  ```ruby
+  client = Quicsilver::Client.new(
+    "example.com",
+    4433,
+    transport_cibir_id: "0a"
+  )
+  ```
+
+- Rules:
+  - Must be 1..6 bytes encoded as an even-length hex string.
+  - Hex is normalized to lowercase.
+  - MsQuic currently supports CIBIR at offset `0` only.
+  - CIBIR must be configured consistently on both ends:
+    - Server/listener: `cibir_id: "0a"`
+    - Client: `transport_cibir_id: "0a"`
+  - If one side uses CIBIR and the other side does not, MsQuic rejects the connection during handshake.
+  - If the client sends the wrong CIBIR bytes, packets may not route to the configured listener/backend.
+  - CIBIR is transport routing configuration, not Rack request identity.
+
+## How the pieces differ
+
+- `cibir_id`
+  - Client-selected routing bytes.
+  - Used at listener/connection start time.
+  - Helps route initial packets before server-generated CIDs matter.
+
+- `transport_server_id`
+  - Server-selected fixed 4-byte id.
+  - Embedded by MsQuic in server-generated CIDs.
+  - Helps QUIC-aware load balancers route established connections by backend/server.
+
+- `connection_id`
+  - App-facing opaque connection identity.
+  - Stable across streams on the same QUIC connection.
+  - Not guaranteed to be the same CID a load balancer sees on the wire.
+
+- `stream_id`
+  - Per-request QUIC stream identity.
+
+- `request_id`
+  - App-facing request correlation value.
+  - Combines the stable connection identity and stream id.
+  - Includes `transport_server_id` as a prefix when configured.
+
+## Recommended usage
+
+- Log `env["quicsilver.request_id"]` for application request correlation.
+- Treat `env["quicsilver.connection_id"]` as opaque.
+- Configure `transport_server_id` when QUIC-aware infrastructure needs backend routing by server-generated CIDs.
+- Configure `cibir_id` / `transport_cibir_id` together when client-chosen destination CID bytes are part of your routing scheme.

data/examples/benchmark.rb

@@ -15,6 +15,9 @@ app = ->(env) {
   case env["PATH_INFO"]
   when "/large"
     [200, { "content-type" => "application/octet-stream" }, ["x" * 50_000]]
+  when "/work"
+    sleep 0.001
+    [200, { "content-type" => "application/json" }, ['{"ok":true}']]
   else
     [200, { "content-type" => "application/json" }, ['{"ok":true}']]
   end
@@ -102,6 +105,83 @@ end
 
 client.disconnect
 
+# Cleanup
+Quicsilver::Client.close_pool
+# === 5. Multi-threaded concurrency ===
+puts "\n📊 Multi-threaded — concurrent clients, #{ITERATIONS} total requests"
+puts "-" * 60
+
+[1, 2, 4, 8].each do |thread_count|
+  requests_per_thread = ITERATIONS / thread_count
+  err_count = 0
+  mu = Mutex.new
+
+  # Connect all clients sequentially (connection setup is serialized)
+  clients = thread_count.times.map do
+    c = Quicsilver::Client.new(HOST, PORT, unsecure: true, request_timeout: 10)
+    c.open_connection
+    c
+  end
+
+  # Run requests in parallel
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  threads = clients.map do |client|
+    Thread.new do
+      requests_per_thread.times do
+        client.get("/ping")
+      rescue => e
+        mu.synchronize { err_count += 1 }
+      end
+    end
+  end
+  threads.each(&:join)
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+  clients.each(&:disconnect)
+
+  rps = (ITERATIONS / (elapsed / 1000.0)).round(0)
+  err = err_count > 0 ? "  (#{err_count} errors)" : ""
+  puts "  #{thread_count.to_s.rjust(3)} threads: #{elapsed.to_s.rjust(7)}ms  #{rps} req/s#{err}"
+  sleep 0.1
+end
+
+# === 6. Multi-threaded with simulated work ===
+puts "\n📊 Multi-threaded with 1ms app work, 50 total requests"
+puts "-" * 60
+
+[1, 2, 4, 8].each do |thread_count|
+  reqs = 50
+  requests_per_thread = reqs / thread_count
+  err_count = 0
+  mu = Mutex.new
+
+  clients = thread_count.times.map do
+    c = Quicsilver::Client.new(HOST, PORT, unsecure: true, request_timeout: 10)
+    c.open_connection
+    c
+  end
+
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  threads = clients.map do |client|
+    Thread.new do
+      requests_per_thread.times do
+        client.get("/work")
+      rescue => e
+        mu.synchronize { err_count += 1 }
+      end
+    end
+  end
+  threads.each(&:join)
+  elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+  clients.each(&:disconnect)
+
+  rps = (reqs / (elapsed / 1000.0)).round(0)
+  err = err_count > 0 ? "  (#{err_count} errors)" : ""
+  puts "  #{thread_count.to_s.rjust(3)} threads: #{elapsed.to_s.rjust(7)}ms  #{rps} req/s#{err}"
+  sleep 0.1
+end
+
 # Cleanup
 Quicsilver::Client.close_pool
 server.stop

data/examples/connection_pool_demo.rb

@@ -34,7 +34,7 @@ puts "-" * 50
   elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
 
   label = i == 0 ? "← new connection + QUIC handshake" : "← reused"
-  puts "  Request #{i}: #{response[:status]} — #{elapsed}ms #{label}"
+  puts "  Request #{i}: #{response.status} — #{elapsed}ms #{label}"
 end
 
 puts "\n  Pool: #{Quicsilver::Client.pool.size} connection(s) ready for reuse"