quicsilver 0.4.0 → 0.5.0

data/lib/quicsilver/protocol/unidirectional_stream.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    module UnidirectionalStream
+      CONTROL = 0x00
+      PUSH = 0x01
+      QPACK_ENCODER = 0x02
+      QPACK_DECODER = 0x03
+    end
+  end
+end

data/lib/quicsilver/protocol/web_transport.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    module WebTransport
+      SESSION_GONE = 0x170d7b68
+      BUFFERED_STREAM_REJECTED = 0x3994bd84
+
+      BIDI_STREAM_TYPE = 0x41
+      UNI_STREAM_TYPE = 0x54
+      CLOSE_SESSION_CAPSULE = 0x2843
+
+      # draft-ietf-webtrans-http3-16 §4.7. Advisory: either endpoint asks the
+      # other to wind the session down, but the session stays usable until it
+      # is actually closed.
+      DRAIN_SESSION_CAPSULE = 0x78ae
+
+      # Session-level flow control (§5.6). These sit above QUIC's own limits:
+      # QUIC bounds the connection and each stream, these bound one session
+      # across all of its streams.
+      #
+      # MAX_* raise a limit. *_BLOCKED are advisory, saying a limit was hit;
+      # §5.6 forbids waiting for one before raising a limit.
+      MAX_DATA_CAPSULE = 0x190B4D3D
+      MAX_STREAMS_BIDI_CAPSULE = 0x190B4D3F
+      MAX_STREAMS_UNI_CAPSULE = 0x190B4D40
+      DATA_BLOCKED_CAPSULE = 0x190B4D41
+      STREAMS_BLOCKED_BIDI_CAPSULE = 0x190B4D43
+      STREAMS_BLOCKED_UNI_CAPSULE = 0x190B4D44
+
+      # A flow control violation closes the session, not the connection (§5.6).
+      FLOW_CONTROL_ERROR = 0x045d4487
+
+      # Per-stream data limits belong to the HTTP/2 binding. Over HTTP/3 every
+      # WebTransport stream is a real QUIC stream, so QUIC provides them
+      # natively and these two capsules are prohibited: receipt is a session
+      # error (§5.4).
+      #
+      # Defined in draft-ietf-webtrans-http2-14 §6.6 and §6.9, which the HTTP/3
+      # draft cites without restating the code points. They fill the two gaps
+      # in the 0x190B4D3D..0x190B4D44 block the §9.6 registry allocates.
+      #
+      # That draft is not in docs/specs, so these are the only values here
+      # without a local citation. Re-verify them when it is vendored.
+      MAX_STREAM_DATA_CAPSULE = 0x190B4D3E
+      STREAM_DATA_BLOCKED_CAPSULE = 0x190B4D42
+
+      PROHIBITED_CAPSULES = [MAX_STREAM_DATA_CAPSULE, STREAM_DATA_BLOCKED_CAPSULE].freeze
+
+      # Prohibited whether or not flow control was negotiated. §5.1 says to
+      # ignore "flow control capsules" when flow control is off, but §5.6
+      # defines that term as MAX_DATA, MAX_STREAMS, DATA_BLOCKED and
+      # STREAMS_BLOCKED only. These two are never legal over HTTP/3.
+      def self.prohibited_capsule?(type)
+        PROHIBITED_CAPSULES.include?(type)
+      end
+
+      # Stream limits cannot exceed 2^60: a larger count could not be encoded
+      # as a stream ID (§5.6.2, §5.6.3).
+      MAX_STREAMS_LIMIT = 1 << 60
+
+      # Largest value a QUIC variable-length integer can carry (RFC 9000 §16).
+      VARINT_MAX = (1 << 62) - 1
+
+      # Raised for a capsule whose contents break a flow control rule, as
+      # opposed to one we cannot parse. The session is closed with
+      # FLOW_CONTROL_ERROR; the connection survives.
+      class FlowControlError < StandardError
+        def error_code = FLOW_CONTROL_ERROR
+      end
+
+      # We wanted to send but the peer's session limit forbids it (§5.3,
+      # §5.4). Local and recoverable: nothing is wrong on the wire, there is
+      # simply no credit. Distinct from FlowControlError, which means the peer
+      # broke a rule and the session must close.
+      class SendBlocked < StandardError
+        attr_reader :limit, :needed
+
+        def initialize(message, limit:, needed:)
+          super(message)
+          @limit = limit
+          @needed = needed
+        end
+      end
+
+      # What a flow control capsule says. `limit` is cumulative for MAX_DATA
+      # and MAX_STREAMS, and for the BLOCKED capsules it is the limit that was
+      # in force when the sender was blocked.
+      Limit = Data.define(:kind, :direction, :limit) do
+        def max? = kind == :max_data || kind == :max_streams
+        def blocked? = !max?
+      end
+
+      # kind and direction for each flow control capsule type. Direction is nil
+      # where the capsule covers the whole session rather than one stream type.
+      FLOW_CONTROL_CAPSULES = {
+        MAX_DATA_CAPSULE => [:max_data, nil],
+        MAX_STREAMS_BIDI_CAPSULE => [:max_streams, :bidi],
+        MAX_STREAMS_UNI_CAPSULE => [:max_streams, :uni],
+        DATA_BLOCKED_CAPSULE => [:data_blocked, nil],
+        STREAMS_BLOCKED_BIDI_CAPSULE => [:streams_blocked, :bidi],
+        STREAMS_BLOCKED_UNI_CAPSULE => [:streams_blocked, :uni]
+      }.freeze
+
+      def self.flow_control_capsule?(type)
+        FLOW_CONTROL_CAPSULES.key?(type)
+      end
+
+      # Decode a flow control capsule payload: a single varint (§5.6.2-5.6.5).
+      #
+      # Raises Capsule::ParseError when the payload is not exactly one varint,
+      # and FlowControlError when a stream count exceeds what a stream ID can
+      # encode. Those are different outcomes on the wire: the first is a
+      # malformed message, the second a flow control violation.
+      def self.parse_flow_control_capsule(type, payload)
+        kind, direction = FLOW_CONTROL_CAPSULES.fetch(type) do
+          raise ArgumentError, "Not a flow control capsule: 0x#{type.to_s(16)}"
+        end
+
+        value, length = Protocol.decode_varint_str(payload, 0)
+        raise Capsule::ParseError, "Truncated #{kind} capsule" if length == 0
+        raise Capsule::ParseError, "Trailing bytes in #{kind} capsule" unless length == payload.bytesize
+
+        if (kind == :max_streams || kind == :streams_blocked) && value > MAX_STREAMS_LIMIT
+          raise FlowControlError, "#{kind} of #{value} exceeds the 2^60 stream limit"
+        end
+
+        Limit.new(kind: kind, direction: direction, limit: value)
+      end
+
+      def self.build_max_data(limit)
+        Capsule.encode(MAX_DATA_CAPSULE, Protocol.encode_varint(validate_limit!(limit)))
+      end
+
+      def self.build_data_blocked(limit)
+        Capsule.encode(DATA_BLOCKED_CAPSULE, Protocol.encode_varint(validate_limit!(limit)))
+      end
+
+      def self.build_max_streams(direction, limit)
+        type = (direction == :bidi) ? MAX_STREAMS_BIDI_CAPSULE : MAX_STREAMS_UNI_CAPSULE
+        Capsule.encode(type, Protocol.encode_varint(validate_stream_limit!(direction, limit)))
+      end
+
+      def self.build_streams_blocked(direction, limit)
+        type = (direction == :bidi) ? STREAMS_BLOCKED_BIDI_CAPSULE : STREAMS_BLOCKED_UNI_CAPSULE
+        Capsule.encode(type, Protocol.encode_varint(validate_stream_limit!(direction, limit)))
+      end
+
+      # Building a capsule the peer would have to reject is our bug, so these
+      # raise ArgumentError rather than a protocol error.
+      def self.validate_limit!(limit)
+        unless limit.is_a?(Integer) && limit >= 0 && limit <= VARINT_MAX
+          raise ArgumentError, "Limit must be a varint-encodable non-negative integer"
+        end
+
+        limit
+      end
+
+      def self.validate_stream_limit!(direction, limit)
+        unless direction == :bidi || direction == :uni
+          raise ArgumentError, "Direction must be :bidi or :uni"
+        end
+        validate_limit!(limit)
+        raise ArgumentError, "Stream limit #{limit} exceeds 2^60" if limit > MAX_STREAMS_LIMIT
+
+        limit
+      end
+
+      # Extended CONNECT :protocol values.
+      #
+      # draft-ietf-webtrans-http3-16 §3.2 requires "webtransport-h3". The bare
+      # "webtransport" token identifies the capsule-based HTTP/2 binding
+      # (§2.1.2) and was what pre-15 drafts used over HTTP/3. We retain it
+      # for legacy interoperability; the token alone does not identify a
+      # browser version or prove support for every feature of an older draft.
+      PROTOCOL = "webtransport-h3"
+      PROTOCOL_LEGACY = "webtransport"
+
+      def self.protocol?(value)
+        value == PROTOCOL || value == PROTOCOL_LEGACY
+      end
+
+      # WebTransport shares the HTTP/3 error space, so 32-bit application error
+      # codes are mapped into a reserved range (§4.4, §9.5). Codepoints of the
+      # form 0x1f * N + 0x21 are reserved by HTTP/3 §8.1 and skipped, which is
+      # why this is not a plain offset.
+      APPLICATION_ERROR_FIRST = 0x52e4a40fa8db
+      APPLICATION_ERROR_LAST = 0x52e5ac983162
+
+      RESERVED_STRIDE = 0x1f
+      RESERVED_OFFSET = 0x21
+
+      # Application code -> HTTP/3 code, stepping over reserved codepoints.
+      def self.application_error_to_http(code)
+        APPLICATION_ERROR_FIRST + code + (code / 0x1e)
+      end
+
+      # HTTP/3 code -> application code. nil when the code is outside the
+      # reserved range or lands on a reserved codepoint, neither of which a
+      # peer should ever send.
+      def self.http_to_application_error(code)
+        return nil unless code.between?(APPLICATION_ERROR_FIRST, APPLICATION_ERROR_LAST)
+        return nil if reserved_codepoint?(code)
+
+        shifted = code - APPLICATION_ERROR_FIRST
+        shifted - (shifted / RESERVED_STRIDE)
+      end
+
+      def self.reserved_codepoint?(code)
+        (code - RESERVED_OFFSET) % RESERVED_STRIDE == 0
+      end
+    end
+  end
+end

data/lib/quicsilver/rack/context.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Rack
+    # Rack-visible Quicsilver transport context.
+    #
+    # This is the single env capability object for HTTP/3/QUIC-specific state.
+    # Normal Rack apps can ignore it; Quicsilver-aware apps can use it to opt into
+    # transport features like WebTransport.
+    class Context
+      attr_reader :stream_id, :webtransport
+
+      def initialize(stream_id: nil, early_data: false, webtransport: nil, metadata: {})
+        @stream_id = stream_id
+        @early_data = early_data
+        @webtransport = webtransport
+        @metadata = metadata || {}
+      end
+
+      def early_data?
+        !!@early_data
+      end
+
+      def webtransport?
+        !!@webtransport
+      end
+
+      def [](key)
+        @metadata[key]
+      end
+    end
+  end
+end

data/lib/quicsilver/response.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  # Unified HTTP/3 response object returned by the client.
+  #
+  # Used for both buffered and streaming responses:
+  # - Buffered: body is a String
+  # - Streaming: body is a StreamInput (call body.read in a loop)
+  #
+  #   response = client.get("/users")
+  #   response.status   # => 200
+  #   response.headers   # => {"content-type" => "application/json"}
+  #   response.body      # => '{"users":["alice"]}'
+  #   response.trailers  # => {}
+  #
+  #   # Streaming
+  #   req = client.build_request("GET", "/stream")
+  #   response = req.streaming_response(timeout: 10)
+  #   response.status   # => 200
+  #   while (chunk = response.body.read)
+  #     process(chunk)
+  #   end
+  #
+  class Response
+    attr_reader :status, :headers, :body, :trailers
+
+    def initialize(status:, headers: {}, body: nil, trailers: {})
+      @status = status
+      @headers = headers
+      @body = body
+      @trailers = trailers
+    end
+
+    def ok? = status == 200
+    def success? = status >= 200 && status < 300
+    def redirect? = status >= 300 && status < 400
+    def client_error? = status >= 400 && status < 500
+    def server_error? = status >= 500 && status < 600
+  end
+end

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

@@ -29,14 +29,15 @@ module Quicsilver
         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)})")
-        Quicsilver.stream_reset(stream.stream_handle, e.error_code) if stream.writable?
+        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) if @request_registry.include?(stream.stream_id)
-        @cancelled_mutex.synchronize { @cancelled_streams.delete(stream.stream_id) }
+        @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
@@ -66,7 +67,12 @@ module Quicsilver
           return
         end
 
-        request, body = @adapter.build_request(headers)
+        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)
 
         # Wire interim_response so apps can send 103 Early Hints.
@@ -94,7 +100,7 @@ module Quicsilver
       end
 
       def send_response(connection, stream, request, response)
-        if cancelled_stream?(stream.stream_id)
+        if cancelled_stream?(stream.stream_id, connection.handle)
           Quicsilver.logger.debug("Skipping response for cancelled stream #{stream.stream_id}")
           return
         end
@@ -111,27 +117,32 @@ module Quicsilver
           trailer_hash
         end
 
-        response_headers = {}
+        # 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 }
+          headers.header.each { |name, value| response_headers << [ name, value ] }
         else
-          headers&.each { |name, value| response_headers[name] = value }
+          headers&.each { |name, value| response_headers << [ name, value ] }
         end
 
         # Protocol-rack moves content-length from headers to body.length —
         # re-add it so the HTTP/3 response includes the header.
-        if !response_headers.key?("content-length") && response.body&.length
-          response_headers["content-length"] = response.body.length.to_s
+        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)
+        @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