quicsilver 0.4.0 → 0.5.0

data/examples/lifecycle_drain.rb

@@ -0,0 +1,264 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 1: graceful drain as an HTTP/3 lifecycle control loop.
+#
+#   bundle exec ruby examples/lifecycle_drain.rb
+#
+# This keeps the policy deliberately small and in one file:
+#
+#   Quicsilver::Server#stats -> LifecycleSignal -> readiness / drain / safe-to-exit
+#
+# A real quicsilver-health/quicsilver-lifecycle package could extract the
+# LifecycleSignal, but the core idea should stay this boring:
+#
+#   1. fail readiness
+#   2. send HTTP/3 GOAWAY via Server#shutdown
+#   3. refuse/avoid new work
+#   4. finish in-flight streams
+#   5. exit when active work reaches zero or the deadline expires
+
+require_relative "example_helper"
+
+$stdout.sync = true
+
+HOST = ENV.fetch("HOST", "127.0.0.1")
+PORT = Integer(ENV.fetch("PORT", "0"))
+SLOW_REQUESTS = Integer(ENV.fetch("SLOW_REQUESTS", "3"))
+SLOW_MS = Integer(ENV.fetch("SLOW_MS", "2_000"))
+SHUTDOWN_TIMEOUT = Integer(ENV.fetch("SHUTDOWN_TIMEOUT", "10"))
+
+class LifecycleSignal
+  def self.for(server)
+    new(server&.stats || {})
+  end
+
+  def initialize(stats)
+    @stats = stats || {}
+  end
+
+  def ready?
+    running? && !draining? && !queue_full?
+  end
+
+  def accepting_requests?
+    ready?
+  end
+
+  def safe_to_exit?
+    draining? && active_requests.zero? && pending_requests.zero?
+  end
+
+  def state
+    if !running?
+      "stopped"
+    elsif draining?
+      safe_to_exit? ? "drained" : "draining"
+    elsif queue_full?
+      "overloaded"
+    else
+      "ready"
+    end
+  end
+
+  def to_h
+    {
+      "state" => state,
+      "ready" => ready?,
+      "accepting_requests" => accepting_requests?,
+      "safe_to_exit" => safe_to_exit?,
+      "active_connections" => active_connections,
+      "active_requests" => active_requests,
+      "pending_requests" => pending_requests,
+      "queue_max" => @stats.dig("scheduler", "max_queue_size"),
+      "goaway_or_drain" => draining?
+    }
+  end
+
+  private
+    def running?
+      @stats["running"] == true
+    end
+
+    def draining?
+      @stats["shutting_down"] == true
+    end
+
+    def queue_full?
+      @stats.dig("scheduler", "full") == true
+    end
+
+    def active_connections
+      @stats.dig("connections", "active").to_i
+    end
+
+    def active_requests
+      @stats.dig("requests", "active").to_i
+    end
+
+    def pending_requests
+      if running? || draining?
+        @stats.dig("scheduler", "pending").to_i
+      else
+        0
+      end
+    end
+end
+
+def banner(title)
+  Example.heading(title, level: 1)
+end
+
+def section(number, title)
+  Example.heading("#{number}. #{title}")
+end
+
+def yes_no(value)
+  value ? "yes" : "no"
+end
+
+def lifecycle_header
+  Example.say
+  Example.say format(
+    "  %-22s %-10s %-5s %-7s %-5s %5s %6s %5s",
+    "sample", "state", "ready", "accept", "safe", "conns", "active", "queue"
+  )
+  Example.say "  #{'-' * 75}"
+end
+
+def lifecycle_row(label, server)
+  data = LifecycleSignal.for(server).to_h
+
+  Example.say format(
+    "  %-22s %-10s %-5s %-7s %-5s %5d %6d %5d",
+    label,
+    data["state"],
+    yes_no(data["ready"]),
+    yes_no(data["accepting_requests"]),
+    yes_no(data["safe_to_exit"]),
+    data["active_connections"],
+    data["active_requests"],
+    data["pending_requests"]
+  )
+end
+
+def elapsed_label(started_at)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+  "t+#{format('%.1f', elapsed)}s"
+end
+
+def attempt_new_request(client)
+  response = client.get("/hello", timeout: 2)
+  "#{response.status} #{response.body.inspect}"
+rescue => error
+  "#{error.class}: #{error.message}"
+end
+
+Quicsilver.logger = Logger.new(File::NULL)
+
+port = PORT.zero? ? Example.available_udp_port(HOST) : PORT
+server = nil
+
+app = ->(env) {
+  signal = LifecycleSignal.for(server)
+
+  case env["PATH_INFO"]
+  when "/_quicsilver/ready"
+    Example.json_response(signal.ready? ? 200 : 503, signal.to_h)
+  when "/_quicsilver/lifecycle"
+    Example.json_response(200, signal.to_h)
+  when %r{\A/slow/(\d+)}
+    request_id = Regexp.last_match(1)
+    sleep SLOW_MS / 1000.0
+    Example.text_response(200, "slow request #{request_id} completed while #{signal.state}\n")
+  when "/hello"
+    if signal.accepting_requests?
+      Example.text_response(200, "hello before drain\n")
+    else
+      Example.json_response(503, "error" => "server draining", "lifecycle" => signal.to_h)
+    end
+  else
+    Example.text_response(404, "not found\n")
+  end
+}
+
+server = Quicsilver::Server.new(
+  port,
+  app: app,
+  server_configuration: EXAMPLE_TLS_CONFIG,
+  threads: SLOW_REQUESTS + 2
+)
+server_thread = Thread.new { server.start }
+client = Quicsilver::Client.new(HOST, port, unsecure: true)
+shutdown_thread = nil
+monitor = nil
+slow_threads = []
+monitor_done = false
+
+begin
+  Example.wait_until { server.running? }
+
+  banner "HTTP/3 Lifecycle Drain Demo"
+  Example.detail "server", "https://#{HOST}:#{port}"
+  Example.detail "slow streams", "#{SLOW_REQUESTS} × #{SLOW_MS}ms"
+  Example.detail "shutdown timeout", "#{SHUTDOWN_TIMEOUT}s"
+  Example.detail "control loop", "readiness=false -> GOAWAY/drain -> active=0 -> safe exit"
+
+  section 1, "Warm up the connection"
+  Example.detail "GET /hello", attempt_new_request(client)
+  lifecycle_header
+  lifecycle_row "before drain", server
+
+  section 2, "Start long-running streams"
+  slow_threads = SLOW_REQUESTS.times.map do |index|
+    Thread.new do
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = client.get("/slow/#{index + 1}", timeout: SHUTDOWN_TIMEOUT + 5)
+      elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(1)
+      Example.say format("  stream #%-2d completed   status=%d   elapsed=%7.1fms", index + 1, response.status, elapsed_ms)
+    rescue => error
+      Example.say format("  stream #%-2d failed      %s: %s", index + 1, error.class, error.message)
+    end
+  end
+
+  Example.wait_until { server.stats.dig("requests", "active") >= SLOW_REQUESTS }
+  lifecycle_header
+  lifecycle_row "streams in flight", server
+
+  section 3, "Begin drain"
+  Example.detail "action", "Server#shutdown(timeout: #{SHUTDOWN_TIMEOUT})"
+  shutdown_thread = Thread.new { server.shutdown(timeout: SHUTDOWN_TIMEOUT) }
+  Example.wait_until { server.shutting_down }
+  sleep 0.05 # give GOAWAY/readiness state a moment to propagate, but keep streams in flight
+
+  Example.detail "readiness", "not ready"
+  Example.detail "routing", "new work should move to other endpoints"
+  Example.detail "in-flight", "existing streams continue until complete"
+  lifecycle_header
+  lifecycle_row "after GOAWAY", server
+
+  monitor_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  monitor = Thread.new do
+    until monitor_done
+      lifecycle_row elapsed_label(monitor_started_at), server
+      sleep 0.5
+    end
+  end
+
+  slow_threads.each(&:join)
+  shutdown_thread.join
+  monitor_done = true
+  monitor.join
+
+  section 4, "Shutdown complete"
+  lifecycle_header
+  lifecycle_row "after shutdown", server
+  Example.detail "takeaway", "routing changes immediately; in-flight HTTP/3 streams drain cleanly"
+ensure
+  monitor_done = true
+  monitor&.join(1)
+  client&.disconnect rescue nil
+  Quicsilver::Client.close_pool rescue nil
+  server&.stop if server&.running? rescue nil
+  server_thread&.join(2)
+end

data/examples/priorities.rb

@@ -45,11 +45,11 @@ client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
 # Request with priority header (what a browser would send)
 puts "\n  CSS request (high priority):"
 response = client.get("/style.css", headers: { "priority" => "u=0, i" })
-puts "    Status: #{response[:status]}, Size: #{response[:body].bytesize} bytes"
+puts "    Status: #{response.status}, Size: #{response.body.bytesize} bytes"
 
 puts "\n  Image request (low priority):"
 response = client.get("/image.png", headers: { "priority" => "u=5" })
-puts "    Status: #{response[:status]}, Size: #{response[:body].bytesize} bytes"
+puts "    Status: #{response.status}, Size: #{response.body.bytesize} bytes"
 
 puts "\n  MsQuic schedules CSS data before image data"
 puts "  when both are in flight on the same connection."

data/examples/rails_feature_test.rb

@@ -25,51 +25,57 @@ rescue => e
   nil
 end
 
-puts "🚀 Quicsilver Rails Feature Test"
+puts "Quicsilver Rails Feature Test"
 puts "   Target: https://#{HOST}:#{PORT}"
 puts "=" * 60
 
 # === 1. Basic connectivity ===
-puts "\n1️⃣  Basic Connectivity"
+puts "\n1. Basic Connectivity"
 puts "-" * 60
 
 test("GET /h3/ping returns JSON over HTTP/3") do
   response = Quicsilver::Client.get(HOST, PORT, "/h3/ping", unsecure: true)
-  raise "Expected 200, got #{response[:status]}" unless response[:status] == 200
-  raise "Expected JSON" unless response[:body].include?('"status":"ok"')
-  raise "Expected HTTP/3" unless response[:body].include?("HTTP/3")
-  puts "    Response: #{response[:body]}"
+  raise "Expected 200, got #{response.status}" unless response.status == 200
+  raise "Expected JSON" unless response.body.include?('"status":"ok"')
+  raise "Expected HTTP/3" unless response.body.include?("HTTP/3")
+  puts "    Response: #{response.body}"
 end
 
 # === 2. Connection Pooling ===
-puts "\n2️⃣  Connection Pooling"
+puts "\n2. Connection Pooling"
 puts "-" * 60
 
-test("Multiple requests reuse the same connection") do
-  5.times do |i|
+test("5 requests reuse one connection (no repeat handshakes)") do
+  Quicsilver::Client.close_pool
+  times = 5.times.map do |i|
     t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     Quicsilver::Client.get(HOST, PORT, "/h3/ping", unsecure: true)
     elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
-    puts "    Request #{i}: #{elapsed}ms (#{i == 0 ? 'new connection' : 'same connection'})"
+    label = i == 0 ? "new connection + handshake" : "reused"
+    puts "    Request #{i}: #{elapsed}ms (#{label})"
+    elapsed
   end
   puts "    Pool: #{Quicsilver::Client.pool.size} connection(s)"
   raise "Pool should have 1 connection" unless Quicsilver::Client.pool.size == 1
+  # First request includes handshake, subsequent should be faster on average
+  avg_reused = times[1..].sum / times[1..].size
+  puts "    First request: #{times[0]}ms, avg reused: #{avg_reused.round(1)}ms"
 end
 
 # === 3. Streaming ===
-puts "\n3️⃣  Streaming Response"
+puts "\n3. Streaming Response"
 puts "-" * 60
 
 test("GET /h3/stream returns chunked SSE data") do
   response = Quicsilver::Client.get(HOST, PORT, "/h3/stream", unsecure: true)
-  raise "Expected 200" unless response[:status] == 200
-  chunks = response[:body].scan(/data: chunk \d+/)
+  raise "Expected 200" unless response.status == 200
+  chunks = response.body.scan(/data: chunk \d+/)
   raise "Expected 5 chunks, got #{chunks.size}" unless chunks.size == 5
   puts "    Received #{chunks.size} streamed chunks"
 end
 
 # === 4. POST with Body (Echo) ===
-puts "\n4️⃣  POST with Body"
+puts "\n4. POST with Body"
 puts "-" * 60
 
 test("POST /h3/echo returns the request body") do
@@ -78,90 +84,99 @@ test("POST /h3/echo returns the request body") do
     body: body,
     headers: { "content-type" => "application/json" },
     unsecure: true)
-  raise "Expected 200" unless response[:status] == 200
-  raise "Body not echoed" unless response[:body].include?("Hello HTTP/3!")
-  puts "    Echoed: #{response[:body][0..80]}"
+  raise "Expected 200" unless response.status == 200
+  raise "Body not echoed" unless response.body.include?("Hello HTTP/3!")
+  puts "    Echoed: #{response.body[0..80]}"
 end
 
 # === 5. HEAD Request ===
-puts "\n5️⃣  HEAD Request"
+puts "\n5. HEAD Request"
 puts "-" * 60
 
 test("HEAD /h3/head returns headers but no body") do
   client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
   response = client.head("/h3/head")
-  raise "Expected 200" unless response[:status] == 200
-  raise "HEAD should have empty body" unless response[:body].nil? || response[:body].empty?
-  puts "    Status: #{response[:status]}, body size: #{response[:body]&.bytesize || 0}"
+  raise "Expected 200" unless response.status == 200
+  raise "HEAD should have empty body" unless response.body.nil? || response.body.empty?
+  puts "    Status: #{response.status}, body size: #{response.body&.bytesize || 0}"
   client.disconnect
 end
 
-# === 6. Multiplexing (Sequential on single connection) ===
-puts "\n6️⃣  Multiplexing (10 requests, single connection)"
+# === 6. True Multiplexing (concurrent streams, single connection) ===
+puts "\n6. True Multiplexing (concurrent streams, single connection)"
 puts "-" * 60
 
-test("10 sequential requests on one connection") do
+test("10 concurrent requests on one connection") do
   client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
+  client.get("/h3/ping") # warmup + handshake
+
   t_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-  10.times { client.get("/h3/ping") }
+  requests = 10.times.map { client.build_request("GET", "/h3/ping") }
+  responses = requests.map { |r| r.response(timeout: 10) }
   total = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t_start) * 1000).round(1)
-  puts "    10 requests in #{total}ms (single connection)"
+
+  ok = responses.count { |r| r.status == 200 }
+  rps = (10 / (total / 1000.0)).round(0)
+  puts "    10 concurrent requests in #{total}ms (#{ok}/10 ok, #{rps} req/s)"
+  raise "Not all 200" unless ok == 10
   client.disconnect
 end
 
 # === 7. Priority Endpoints (CSS vs Image) ===
-puts "\n7️⃣  Priority Endpoints"
+puts "\n7. Priority Endpoints"
 puts "-" * 60
 
 test("GET /h3/css returns CSS content") do
   response = Quicsilver::Client.get(HOST, PORT, "/h3/css", unsecure: true)
-  raise "Expected 200" unless response[:status] == 200
-  puts "    CSS: #{response[:body].bytesize} bytes"
+  raise "Expected 200" unless response.status == 200
+  puts "    CSS: #{response.body.bytesize} bytes"
 end
 
 test("GET /h3/image returns large binary payload") do
   response = Quicsilver::Client.get(HOST, PORT, "/h3/image", unsecure: true)
-  raise "Expected 200" unless response[:status] == 200
-  raise "Expected 50KB" unless response[:body].bytesize == 50_000
-  puts "    Image: #{response[:body].bytesize} bytes"
+  raise "Expected 200" unless response.status == 200
+  raise "Expected 50KB" unless response.body.bytesize == 50_000
+  puts "    Image: #{response.body.bytesize} bytes"
 end
 
 # === 8. Slow Response (Delay) ===
-puts "\n8️⃣  Slow Response"
+puts "\n8. Slow Response"
 puts "-" * 60
 
 test("GET /h3/slow?delay=0.2 respects delay") do
   t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   response = Quicsilver::Client.get(HOST, PORT, "/h3/slow?delay=0.2", unsecure: true)
   elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
-  raise "Expected 200" unless response[:status] == 200
+  raise "Expected 200" unless response.status == 200
   raise "Should take ~200ms, took #{elapsed}ms" unless elapsed > 150
   puts "    Delayed response in #{elapsed}ms"
 end
 
-# === 9. Concurrent Multiplexing ===
-puts "\n9️⃣  Concurrent Multiplexing"
+# === 9. Concurrent Connections ===
+puts "\n9. Concurrent Connections (4 threads, 4 connections)"
 puts "-" * 60
 
-test("4 concurrent requests on separate connections") do
+test("4 concurrent requests on separate connections complete in parallel") do
+  Quicsilver::Client.close_pool
   threads = 4.times.map do |i|
     Thread.new do
+      client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
       t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      response = Quicsilver::Client.get(HOST, PORT, "/h3/slow?delay=0.2", unsecure: true)
+      response = client.get("/h3/slow?delay=0.2")
       elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t) * 1000).round(1)
-      [i, response[:status], elapsed]
+      client.disconnect
+      [i, response.status, elapsed]
     end
   end
   results = threads.map(&:value).sort_by(&:first)
-  results.each { |i, status, elapsed| puts "    Stream #{i}: #{status} — #{elapsed}ms" }
+  results.each { |i, status, elapsed| puts "    Connection #{i}: #{status} -- #{elapsed}ms" }
   total = results.map { |_, _, e| e }.max
-  # All 4 should complete in roughly the same time (~200ms) not 4x (800ms)
-  raise "Expected concurrent, took #{total}ms" if total > 600
-  puts "    All 4 concurrent in #{total}ms (not #{200 * 4}ms sequential)"
+  sequential = 200 * 4
+  puts "    Total: #{total}ms (sequential would be ~#{sequential}ms)"
 end
 
 # === 10. Large Upload ===
-puts "\n🔟  Large Upload"
+puts "\n10. Large Upload"
 puts "-" * 60
 
 test("POST 100KB body") do
@@ -170,13 +185,13 @@ test("POST 100KB body") do
     body: big_body,
     headers: { "content-type" => "application/octet-stream" },
     unsecure: true)
-  raise "Expected 200" unless response[:status] == 200
-  raise "Size mismatch" unless response[:body].include?('"received_bytes":100000')
+  raise "Expected 200" unless response.status == 200
+  raise "Size mismatch" unless response.body.include?('"received_bytes":100000')
   puts "    Uploaded 100KB, server received 100,000 bytes"
 end
 
 # === 11. Content-Length Validation ===
-puts "\n1️⃣1️⃣  Content-Length Validation"
+puts "\n11. Content-Length Validation"
 puts "-" * 60
 
 test("POST with content-length header") do
@@ -185,76 +200,81 @@ test("POST with content-length header") do
     body: body,
     headers: { "content-type" => "text/plain" },
     unsecure: true)
-  raise "Expected 200, got #{response[:status]}" unless response[:status] == 200
-  raise "Size mismatch" unless response[:body].include?('"received_bytes":5')
+  raise "Expected 200, got #{response.status}" unless response.status == 200
+  raise "Size mismatch" unless response.body.include?('"received_bytes":5')
   puts "    Sent 5 bytes, server received 5 bytes"
 end
 
-# === 12. 0-RTT Reconnection ===
-puts "\n1️⃣2️⃣  0-RTT Reconnection"
+# === 12. Handshake Cost (connection pooling benefit) ===
+puts "\n12. Handshake Cost"
 puts "-" * 60
 
-test("Two separate connections show handshake cost") do
+test("Fresh connections pay handshake cost -- pooling avoids this") do
   Quicsilver::Client.close_pool
 
-  # First connection — full handshake
+  # First connection -- full handshake
   client1 = Quicsilver::Client.new(HOST, PORT, unsecure: true)
   t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   client1.get("/h3/ping")
   first = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t1) * 1000).round(1)
   client1.disconnect
 
-  sleep 0.1
-
-  # Second connection — new handshake (0-RTT depends on MsQuic session cache)
+  # Second connection -- another full handshake
   client2 = Quicsilver::Client.new(HOST, PORT, unsecure: true)
   t2 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   client2.get("/h3/ping")
   second = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t2) * 1000).round(1)
   client2.disconnect
 
-  puts "    First connection:  #{first}ms"
-  puts "    Second connection: #{second}ms"
-  puts "    Pooling saves: ~#{first}ms per request by avoiding handshakes"
+  # Pooled -- reuses existing connection, no handshake
+  Quicsilver::Client.close_pool
+  Quicsilver::Client.get(HOST, PORT, "/h3/ping", unsecure: true) # establish
+  t3 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  Quicsilver::Client.get(HOST, PORT, "/h3/ping", unsecure: true)
+  pooled = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t3) * 1000).round(1)
+
+  puts "    Fresh connection 1: #{first}ms"
+  puts "    Fresh connection 2: #{second}ms"
+  puts "    Pooled (no handshake): #{pooled}ms"
 end
 
-# === 13. GOAWAY Graceful Shutdown ===
-puts "\n1️⃣3️⃣  GOAWAY (server keeps serving during test)"
+# === 13. Server Health ===
+puts "\n13. Server Health"
 puts "-" * 60
 
-test("Server responds after many requests (no GOAWAY yet)") do
+test("Server still responding after all tests") do
   response = Quicsilver::Client.get(HOST, PORT, "/h3/ping", unsecure: true)
-  raise "Expected 200" unless response[:status] == 200
-  puts "    Server still healthy after all tests"
+  raise "Expected 200" unless response.status == 200
+  puts "    Server healthy"
 end
 
 # === 14. Rails CRUD ===
-puts "\n1️⃣4️⃣  Rails CRUD"
+puts "\n14. Rails CRUD"
 puts "-" * 60
 
 test("GET /posts.json returns posts array") do
   response = Quicsilver::Client.get(HOST, PORT, "/posts.json", unsecure: true)
-  raise "Expected 200" unless response[:status] == 200
-  puts "    Posts: #{response[:body][0..40]}"
+  raise "Expected 200" unless response.status == 200
+  puts "    Posts: #{response.body[0..40]}"
 end
 
 # === 15. HTTP Methods ===
-puts "\n1️⃣5️⃣  HTTP Methods"
+puts "\n15. HTTP Methods"
 puts "-" * 60
 
 client = Quicsilver::Client.new(HOST, PORT, unsecure: true)
 %i[get post put patch delete head].each do |method|
   test("#{method.to_s.upcase} /h3/ping") do
     response = client.public_send(method, "/h3/ping")
-    body_size = response[:body]&.bytesize || 0
-    puts "    #{response[:status]} (#{body_size} bytes)"
+    body_size = response.body&.bytesize || 0
+    puts "    #{response.status} (#{body_size} bytes)"
   end
 end
 client.disconnect
 
 # === Summary ===
 puts "\n" + "=" * 60
-puts "🏁 Feature test complete!"
+puts "Feature test complete!"
 puts "   Pool: #{Quicsilver::Client.pool.size} connection(s)"
 Quicsilver::Client.close_pool
-puts "👋 Done"
+puts "Done"