quicsilver 0.3.0 → 0.5.0

data/lib/quicsilver/server/rack_adapter.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Server
+    # Subclass of Protocol::Rack's adapter that adds rack.trailers support.
+    #
+    # Protocol-rack's wrap_headers creates new Protocol::HTTP::Headers,
+    # losing any trailer! state. We override call to inject trailers
+    # from env["rack.trailers"] after wrap_headers runs.
+    #
+    # Usage in a Rack app:
+    #   env["rack.trailers"] = { "grpc-status" => "0", "grpc-message" => "OK" }
+    #
+    class RackAdapter < ::Protocol::Rack::Adapter::Rack31
+      def call(request)
+        env = self.make_environment(request)
+        add_transport_context(env, request)
+        add_rack_context(env, request.rack_context) if request.respond_to?(:rack_context) && request.rack_context
+
+        # Wire rack.early_hints for 103 Early Hints
+        if request.respond_to?(:interim_response) && request.interim_response
+          env["rack.early_hints"] = ->(hint_headers) {
+            request.send_interim_response(103, ::Protocol::HTTP::Headers[hint_headers.map { |k, v| [k, v] }])
+          }
+        end
+
+        status, headers, body = @app.call(env)
+
+        headers, meta = self.wrap_headers(headers)
+
+        # Inject trailers from rack.trailers into the protocol-http headers
+        if (trailers = env["rack.trailers"]) && trailers.is_a?(Hash) && !trailers.empty?
+          headers.trailer!
+          trailers.each { |k, v| headers.add(k, v) }
+        end
+
+        ::Protocol::Rack::Response.wrap(env, status, headers, meta, body, request)
+      rescue => error
+        self.handle_error(env, status, headers, body, error)
+      end
+
+      private
+
+      def add_rack_context(env, rack_context)
+        env["quicsilver.context"] = rack_context
+
+        if rack_context.respond_to?(:webtransport) && rack_context.webtransport
+          env["quicsilver.webtransport"] = rack_context.webtransport
+        end
+      end
+
+      def add_transport_context(env, request)
+        return unless request.respond_to?(:transport_context)
+        return unless (context = request.transport_context)
+
+        connection = context["connection"] || {}
+
+        if connection_id = connection["connection_id"]
+          env["quicsilver.connection_id"] = connection_id
+        end
+
+        if request_id = connection["request_id"]
+          env["quicsilver.request_id"] = request_id
+        end
+
+        if stream_id = connection["stream_id"]
+          env["quicsilver.stream_id"] = stream_id
+        end
+
+        env["quicsilver.context"] ||= ::Quicsilver::Rack::Context.new(
+          stream_id: connection["stream_id"],
+          metadata: context
+        )
+      end
+    end
+  end
+end

data/lib/quicsilver/server/receive_queue.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Server
+    # Nonblocking admission for Body::Writable; only the consumer may wait.
+    class ReceiveQueue
+      def self.validate_limits(bytes, chunks)
+        [bytes, chunks].each do |limit|
+          raise ArgumentError, "Receive limits must be positive integers" unless limit.is_a?(Integer) && limit.positive?
+        end
+      end
+
+      # Accounting only. Every byte pushed here was sent inside a limit this
+      # endpoint advertised (RFC 9000 §4.1), so there is no refusing it; the
+      # receiver controls the rate by deciding when to advertise more (§4.2),
+      # which is what native receive credit does. Whether being over the limit
+      # means "stop granting" or "stop the stream" is the caller's policy.
+      def initialize(bytes:, chunks:)
+        self.class.validate_limits(bytes, chunks)
+        @byte_limit = bytes
+        @chunk_limit = chunks
+        @queue = Thread::Queue.new
+        @mutex = Mutex.new
+        @bytes = 0
+        @chunks = 0
+        @generation = 0
+      end
+
+      def push(data)
+        @mutex.synchronize do
+          raise ClosedQueueError if @queue.closed?
+
+          @queue.push([data, data.bytesize, @generation])
+          @bytes += data.bytesize
+          @chunks += 1
+        end
+        self
+      end
+
+      def over_limit?
+        @mutex.synchronize { @bytes > @byte_limit || @chunks > @chunk_limit }
+      end
+
+      def available_bytes
+        @mutex.synchronize { @chunks < @chunk_limit ? [@byte_limit - @bytes, 0].max : 0 }
+      end
+
+      def release_capacity_to(&callback)
+        capacity = @mutex.synchronize do
+          return if @queue.closed? || @release_capacity
+
+          @release_capacity = callback
+          [[@byte_limit - @bytes, 0].max, [@chunk_limit - @chunks, 0].max]
+        end
+        callback.call(*capacity)
+      end
+
+      def pop
+        entry = @queue.pop
+        return unless entry
+
+        data, bytes, generation = entry
+        grant_bytes = grant_chunks = 0
+        release_capacity = @mutex.synchronize do
+          # A concurrent discard already released entries from the old queue.
+          if generation == @generation
+            @bytes -= bytes
+            @chunks -= 1
+            # Grant back what was freed, capped at the capacity that is now
+            # actually spare. After an oversized first receive the two differ,
+            # and granting the full amount would admit another oversized one.
+            grant_bytes = [bytes, @byte_limit - @bytes].min.clamp(0..)
+            grant_chunks = [1, @chunk_limit - @chunks].min.clamp(0..)
+            @release_capacity unless @queue.closed?
+          end
+        end
+        release_capacity&.call(grant_bytes, grant_chunks) if grant_bytes.positive? || grant_chunks.positive?
+        data
+      end
+
+      def clear
+        @mutex.synchronize do
+          # Writable clears only when discarding input; prevent a racing push
+          # between its clear and close calls.
+          @release_capacity = nil
+          @queue.close
+          @queue.clear
+          @generation += 1
+          @bytes = @chunks = 0
+        end
+        self
+      end
+
+      def close
+        @mutex.synchronize do
+          @release_capacity = nil
+          @queue.close
+        end
+        self
+      end
+
+      def closed? = @queue.closed?
+      def empty? = @queue.empty?
+    end
+  end
+end

data/lib/quicsilver/server/request_handler.rb

@@ -3,18 +3,46 @@
 module Quicsilver
   class Server
     class RequestHandler
-      # Safe HTTP methods allowed in 0-RTT early data (RFC 9110 §9.2.1)
       SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
 
+      attr_reader :adapter
+
       def initialize(app:, configuration:, request_registry:, cancelled_streams:, cancelled_mutex:)
-        @app = app
         @configuration = configuration
         @request_registry = request_registry
         @cancelled_streams = cancelled_streams
         @cancelled_mutex = cancelled_mutex
+        @adapter = Protocol::Adapter.new(app)
       end
 
       def call(connection, stream, early_data: false)
+        request = parse_request(connection, stream, early_data: early_data)
+        return unless request
+
+        response = @adapter.call(request)
+
+        send_response(connection, stream, request, response)
+      rescue Server::DrainTimeoutError
+        Quicsilver.logger.debug("Request interrupted by drain: stream #{stream.stream_id}")
+      rescue Protocol::FrameError => e
+        Quicsilver.logger.error("Frame error: #{e.message} (0x#{e.error_code.to_s(16)})")
+        Quicsilver.connection_shutdown(connection.handle, e.error_code, false) rescue nil
+      rescue Protocol::MessageError => e
+        Quicsilver.logger.error("Message error: #{e.message} (0x#{e.error_code.to_s(16)})")
+        stream.reset(e.error_code) if stream.writable?
+      rescue => e
+        Quicsilver.logger.error("Error handling request: #{e.class} - #{e.message}")
+        Quicsilver.logger.debug(e.backtrace.first(5).join("\n"))
+        connection.send_error(stream, 500, "Internal Server Error") if stream.writable?
+      ensure
+        @request_registry.complete(stream.stream_id, connection.handle)
+        @cancelled_mutex.synchronize { @cancelled_streams.delete([connection.handle, stream.stream_id]) }
+        connection.remove_stream(stream.stream_id)
+      end
+
+      private
+
+      def parse_request(connection, stream, early_data: false)
         parser = Protocol::RequestParser.new(
           stream.data,
           max_body_size: @configuration.max_body_size,
@@ -23,63 +51,98 @@ module Quicsilver
           max_frame_payload_size: @configuration.max_frame_payload_size
         )
         parser.parse
-        parser.validate_headers!  # raises MessageError for missing/invalid pseudo-headers
-        env = parser.to_rack_env
+        parser.validate_headers!
 
-        if env && @app
-          env["quicsilver.early_data"] = early_data
+        headers = parser.headers
+        unless headers && !headers.empty?
+          connection.send_error(stream, 400, "Bad Request") if stream.writable?
+          return
+        end
 
-          # RFC 8470: reject unsafe methods on 0-RTT unless app opted in
-          if @configuration.early_data_policy == :reject &&
-             early_data && !SAFE_METHODS.include?(env["REQUEST_METHOD"])
-            connection.send_error(stream, 425, "Too Early") if stream.writable?
-            return
-          end
+        method = headers[":method"]
 
-          @request_registry.track(
-            stream.stream_id,
-            connection.handle,
-            path: env["PATH_INFO"] || "/",
-            method: env["REQUEST_METHOD"] || "GET"
-          )
+        if @configuration.early_data_policy == :reject &&
+           early_data && !SAFE_METHODS.include?(method)
+          connection.send_error(stream, 425, "Too Early") if stream.writable?
+          return
+        end
+
+        request, body = @adapter.build_request(
+          headers,
+          remote_address: connection.remote_address,
+          remote_port: connection.remote_port,
+          transport_context: connection.request_context(stream_id: stream.stream_id)
+        )
+        request.headers.add("quicsilver-early-data", early_data.to_s)
 
-          status, headers, body = @app.call(env)
+        # Wire interim_response so apps can send 103 Early Hints.
+        # Falcon mode: app calls request.send_interim_response(103, headers)
+        # Rack mode: bridged to rack.early_hints via EarlyHintsMiddleware
+        request.interim_response = ->(status, headers) {
+          connection.send_informational(stream, status, headers)
+        }
 
-          if cancelled_stream?(stream.stream_id)
-            Quicsilver.logger.debug("Skipping response for cancelled stream #{stream.stream_id}")
-            return
-          end
+        if body && parser.body && parser.body.size > 0
+          parser.body.rewind
+          body_data = parser.body.read
+          body.write(body_data) unless body_data.empty?
+        end
+        body&.close_write
+
+        connection.apply_stream_priority(stream, parser.priority)
 
-          raise "Stream handle not found for stream #{stream.stream_id}" unless stream.writable?
+        @request_registry.track(
+          stream.stream_id, connection.handle,
+          path: headers[":path"] || "/", method: method || "GET"
+        )
 
-          connection.send_response(stream, status, headers, body, head_request: env["REQUEST_METHOD"] == "HEAD")
-          @request_registry.complete(stream.stream_id)
+        request
+      end
+
+      def send_response(connection, stream, request, response)
+        if cancelled_stream?(stream.stream_id, connection.handle)
+          Quicsilver.logger.debug("Skipping response for cancelled stream #{stream.stream_id}")
+          return
+        end
+
+        raise "Stream handle not found for stream #{stream.stream_id}" unless stream.writable?
+
+        headers = response.headers
+
+        # Extract trailers before flattening (Protocol::HTTP::Headers tracks
+        # trailer! state that a plain Hash would lose — needed for gRPC).
+        trailers = if headers.respond_to?(:trailer?) && headers.trailer?
+          trailer_hash = {}
+          headers.trailer.each { |name, value| trailer_hash[name] = value }
+          trailer_hash
+        end
+
+        # Pairs, not a Hash: a field can legitimately repeat, and set-cookie MUST NOT be combined
+        # (RFC 9110 §5.3). Keying by name dropped every repeat but the last, which silently discarded
+        # the session cookie of any Rails response that set more than one — sign-in appeared to work
+        # and then forgot the request it had just authenticated.
+        response_headers = []
+        if headers.respond_to?(:header)
+          headers.header.each { |name, value| response_headers << [ name, value ] }
         else
-          connection.send_error(stream, 400, "Bad Request") if stream.writable?
+          headers&.each { |name, value| response_headers << [ name, value ] }
         end
-      rescue Server::DrainTimeoutError
-        Quicsilver.logger.debug("Request interrupted by drain: stream #{stream.stream_id}")
-      rescue Protocol::FrameError => e
-        # Frame errors are connection-level: signal via CONNECTION_CLOSE with H3 error code
-        Quicsilver.logger.error("Frame error: #{e.message} (0x#{e.error_code.to_s(16)})")
-        Quicsilver.connection_shutdown(connection.handle, e.error_code, false) rescue nil
-      rescue Protocol::MessageError => e
-        # Message errors are stream-level: signal via RESET_STREAM with H3 error code
-        Quicsilver.logger.error("Message error: #{e.message} (0x#{e.error_code.to_s(16)})")
-        Quicsilver.stream_reset(stream.stream_handle, e.error_code) if stream.writable?
-      rescue => e
-        Quicsilver.logger.error("Error handling request: #{e.class} - #{e.message}")
-        Quicsilver.logger.debug(e.backtrace.first(5).join("\n"))
-        connection.send_error(stream, 500, "Internal Server Error") if stream.writable?
-      ensure
-        @request_registry.complete(stream.stream_id) if @request_registry.include?(stream.stream_id)
-        @cancelled_mutex.synchronize { @cancelled_streams.delete(stream.stream_id) }
-      end
 
-      private
+        # Protocol-rack moves content-length from headers to body.length —
+        # re-add it so the HTTP/3 response includes the header.
+        unless response_headers.any? { |name, _| name == "content-length" }
+          response_headers << [ "content-length", response.body.length.to_s ] if response.body&.length
+        end
+
+        body = response.body || []
+        connection.send_response(stream, response.status, response_headers, body,
+          head_request: request.head?, trailers: trailers)
+        @request_registry.complete(stream.stream_id, connection.handle)
+        connection.remove_stream(stream.stream_id)
+      end
 
-      def cancelled_stream?(stream_id)
-        @cancelled_mutex.synchronize { @cancelled_streams.include?(stream_id) }
+      def cancelled_stream?(stream_id, connection_handle)
+        @cancelled_mutex.synchronize { @cancelled_streams.include?([connection_handle, stream_id]) }
       end
     end
   end

data/lib/quicsilver/server/request_registry.rb

@@ -10,8 +10,9 @@ module Quicsilver
 
       def track(stream_id, connection_handle, path:, method:, started_at: Time.now)
         @mutex.synchronize do
-          @requests[stream_id] = {
+          @requests[key_for(stream_id, connection_handle)] = {
             connection_handle: connection_handle,
+            stream_id: stream_id,
             path: path,
             method: method,
             started_at: started_at
@@ -19,8 +20,10 @@ module Quicsilver
         end
       end
 
-      def complete(stream_id)
-        @mutex.synchronize { @requests.delete(stream_id) }
+      def complete(stream_id, connection_handle)
+        @mutex.synchronize do
+          @requests.delete(key_for(stream_id, connection_handle))
+        end
       end
 
       def active_count
@@ -42,8 +45,18 @@ module Quicsilver
         @mutex.synchronize { @requests.empty? }
       end
 
-      def include?(stream_id)
-        @mutex.synchronize { @requests.key?(stream_id) }
+      def include?(stream_id, connection_handle)
+        @mutex.synchronize do
+          @requests.key?(key_for(stream_id, connection_handle))
+        end
+      end
+
+      private
+
+      def key_for(stream_id, connection_handle)
+        raise ArgumentError, "Connection handle is required" if connection_handle.nil?
+
+        [connection_handle, stream_id]
       end
     end
   end

data/lib/quicsilver/server/scheduler.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  class Server
+    # Base class for work schedulers.
+    #
+    # A scheduler controls how incoming request work units are executed —
+    # via threads, fibers, or any other concurrency model. Subclasses
+    # implement the delivery mechanism.
+    #
+    # Usage:
+    #   scheduler = ThreadScheduler.new(size: 10, max_queue_size: 100, &handler)
+    #   scheduler.start               # start workers
+    #   scheduler.enqueue(work)        # schedule a work unit
+    #   scheduler.drain(timeout: 5)    # wait for queue to empty
+    #   scheduler.stop                 # shut down workers
+    #
+    class Scheduler
+      # Schedule a work unit for execution.
+      def enqueue(work)
+        raise NotImplementedError
+      end
+
+      # Is the work queue at capacity?
+      def full?
+        raise NotImplementedError
+      end
+
+      # Number of pending work units.
+      def pending
+        raise NotImplementedError
+      end
+
+      # Wait for the queue to empty.
+      def drain(timeout: 5)
+        raise NotImplementedError
+      end
+
+      # Start processing work units.
+      def start
+        raise NotImplementedError
+      end
+
+      # Shut down workers.
+      def stop
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/quicsilver/server/schedulers/fiber_scheduler.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../scheduler"
+
+module Quicsilver
+  class Server
+    module Schedulers
+      # Fiber-based scheduler — uses Async::Queue for cooperative scheduling.
+      # Expects to be running inside an Async reactor (e.g. Falcon provides one).
+      # Requires the async gem.
+      class FiberScheduler < Scheduler
+        def initialize(concurrency:, max_queue_size:, &handler)
+          require "async"
+          require "async/queue"
+          require "async/barrier"
+
+          @concurrency = concurrency
+          @max_queue_size = max_queue_size
+          @handler = handler
+          @queue = Async::Queue.new
+          @running = false
+          @barrier = nil
+        end
+
+        def enqueue(work)
+          @queue.enqueue(work)
+        end
+
+        def full?
+          @queue.size >= @max_queue_size
+        end
+
+        def pending
+          @queue.size
+        end
+
+        # Spawn fiber workers inside the current Async reactor.
+        # Caller must already be inside Async do (e.g. Falcon).
+        def start
+          @running = true
+          @barrier = Async::Barrier.new
+
+          @concurrency.times do
+            @barrier.async do
+              while @running
+                work = @queue.dequeue
+                break if work == :shutdown
+
+                run(work)
+              end
+            end
+          end
+        end
+
+        # One unit of work must not take the worker fiber down with it; see
+        # the thread scheduler for the same reasoning.
+        private def run(work)
+          @handler.call(work)
+        rescue => e
+          Quicsilver.logger.error("Unhandled error in worker: #{e.class} - #{e.message}")
+          Quicsilver.logger.debug(e.backtrace&.first(5)&.join("\n").to_s)
+        end
+
+        def drain(timeout: 5)
+          deadline = Time.now + timeout
+          while @queue.size > 0 && Time.now < deadline
+            sleep 0.05
+          end
+        end
+
+        def stop
+          @running = false
+          @concurrency.times { @queue.enqueue(:shutdown) }
+          @barrier&.wait
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/server/schedulers/thread_scheduler.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../scheduler"
+
+module Quicsilver
+  class Server
+    module Schedulers
+      # Thread-based scheduler — uses a thread pool with Thread::Queue.
+      class ThreadScheduler < Scheduler
+        def initialize(concurrency:, max_queue_size:, &handler)
+          @size = concurrency
+          @max_queue_size = max_queue_size
+          @handler = handler
+          @queue = Queue.new
+          @threads = []
+          @mutex = Mutex.new
+        end
+
+        def enqueue(work)
+          @queue.push(work)
+        end
+
+        def full?
+          @queue.size >= @max_queue_size
+        end
+
+        def pending
+          @queue.size
+        end
+
+        def start
+          @size.times do
+            thread = Thread.new do
+              while (work = @queue.pop)
+                break if work == :shutdown
+
+                run(work)
+              end
+            end
+            @mutex.synchronize { @threads << thread }
+          end
+        end
+
+        def drain(timeout: 5)
+          deadline = Time.now + timeout
+          while @queue.size > 0 && Time.now < deadline
+            sleep 0.05
+          end
+        end
+
+        # One unit of work must not take the worker down with it. An escaping
+        # error would end the thread, shrinking the pool for the rest of the
+        # process, and Thread#join would re-raise it in whoever stops the
+        # server. DrainTimeoutError is our own interruption, so it ends the
+        # worker as intended.
+        private def run(work)
+          @handler.call(work)
+        rescue DrainTimeoutError
+          raise
+        rescue => e
+          Quicsilver.logger.error("Unhandled error in worker: #{e.class} - #{e.message}")
+          Quicsilver.logger.debug(e.backtrace&.first(5)&.join("\n").to_s)
+        end
+
+        def stop
+          @size.times { @queue.push(:shutdown) }
+          @mutex.synchronize do
+            @threads.each { |t| t.join(2) }
+            @threads.each { |t| t.raise(DrainTimeoutError, "drain timeout") if t.alive? }
+            @threads.clear
+          end
+        end
+      end
+    end
+  end
+end