quicsilver 0.4.0 → 0.5.0

data/lib/quicsilver/server/web_transport_session.rb

@@ -0,0 +1,812 @@
+# frozen_string_literal: true
+
+require_relative "../protocol/connect_stream_decoder"
+
+module Quicsilver
+  class Server
+    # A WebTransport session opened via Extended CONNECT (RFC 9220).
+    #
+    # WebTransport provides two messaging modes on the same session:
+    # - Datagrams: unreliable, unordered (live cursors, typing indicators)
+    # - Streams: reliable, ordered (chat messages, RPC)
+    #
+    # The Rack app owns Origin validation (draft-ietf-webtrans-http3-16 §3.2).
+    # Check HTTP_ORIGIN against trusted origins before calling accept!; return
+    # 403 to reject. Non-browser clients may omit Origin, so the app also decides
+    # whether to allow requests without it. Origin is not client authentication.
+    #
+    # Usage inside a Rack app (a browser-only endpoint):
+    #   session = env["quicsilver.context"].webtransport
+    #   return [403, {}, []] unless env["HTTP_ORIGIN"] == "https://app.example.com"
+    #   session.accept!
+    #   session.on_datagram { |data| session.send_datagram("echo: #{data}") }
+    #   [200, {}, []]
+    #
+    class WebTransportSession
+      attr_reader :path, :authority, :headers, :connection, :stream_id
+
+      # WebTransport stream types (draft-ietf-webtrans-http3), matching aioquic/Chrome.
+      WT_STREAM_BIDI = Protocol::WebTransport::BIDI_STREAM_TYPE
+      WT_STREAM_UNI = Protocol::WebTransport::UNI_STREAM_TYPE
+      WT_CLOSE_SESSION = Protocol::WebTransport::CLOSE_SESSION_CAPSULE
+      WT_DRAIN_SESSION = Protocol::WebTransport::DRAIN_SESSION_CAPSULE
+
+      # Why a session ended. A clean close with no capsule is code 0 and an
+      # empty reason (draft-ietf-webtrans-http3-16 §6).
+      #
+      # `remote` distinguishes the peer hanging up from us closing, which the
+      # wire format does not carry but applications need for reconnect logic.
+      CloseInfo = Data.define(:code, :reason, :remote) do
+        def remote? = remote
+        def local? = !remote
+      end
+
+      # WT_CLOSE_SESSION payload layout (§6):
+      #
+      #   [error code: 4 bytes, network order][reason: UTF-8, ≤ 1024 bytes]
+      ERROR_CODE_BYTES = 4
+      MAX_CLOSE_MESSAGE_LENGTH = 1024
+
+      # A client may send capsules before we answer CONNECT, and we must hold
+      # them unparsed until then (§3.2). Bound that hold so an unaccepted
+      # session cannot buffer without limit; matches the pre-SETTINGS cap in
+      # WebTransportManager.
+      MAX_OPTIMISTIC_CONNECT_BYTES = 65_536
+
+      # The receive policy for every child stream. This is the only place these
+      # defaults live; WebTransportStream requires them to be passed in.
+      DEFAULT_RECEIVE_OPTIONS = {
+        receive_buffer_bytes: 1_048_576,
+        receive_buffer_chunks: 1024,
+        receive_overflow_code: 0,
+        receive_backpressure: true
+      }.freeze
+
+      # Parse a bidirectional WebTransport stream prefix:
+      # [type=0x41 varint][session_id varint][data...]
+      # Returns [session_id, remainder] or nil if malformed.
+      # A session id is the stream id of the CONNECT request that established
+      # it, so it is always a client-initiated bidirectional stream
+      # (draft-ietf-webtrans-http3-16 §4). Anything else cannot name a session.
+      def self.validate_session_id!(session_id)
+        return if session_id % 4 == 0
+
+        raise Protocol::FrameError.new("Invalid WebTransport session ID #{session_id}", error_code: Protocol::H3_ID_ERROR)
+      end
+
+      def self.parse_stream_prefix(payload)
+        type, type_len = Protocol.decode_varint_str(payload, 0)
+        return nil unless type == WT_STREAM_BIDI && type_len > 0
+
+        session_id, sid_len = Protocol.decode_varint_str(payload, type_len)
+        return nil if sid_len == 0
+        validate_session_id!(session_id)
+
+        [session_id, payload.byteslice((type_len + sid_len)..-1) || "".b]
+      end
+
+      # Route an incoming WebTransport stream to the right session.
+      def self.accept_stream(sessions, stream_id, stream_handle, payload, fin: false)
+        session_id, initial_data = parse_stream_prefix(payload)
+        return unless session_id
+
+        session = sessions[session_id]
+        return unless session
+
+        wt_stream = session.add_stream(stream_handle, stream_id)
+        fin ? wt_stream.receive_fin(initial_data) : wt_stream.receive_data(initial_data)
+        wt_stream
+      end
+
+      # A bare FIN means a clean close; a CLOSE capsule must contain its
+      # four-byte code and a valid, bounded UTF-8 reason (draft-16 §6).
+      def self.parse_close_payload(payload)
+        raise Protocol::Capsule::ParseError, "Truncated close code" if payload.bytesize < ERROR_CODE_BYTES
+        code = payload.unpack1("N")
+        reason = payload.byteslice(ERROR_CODE_BYTES..).dup.force_encoding(Encoding::UTF_8)
+        unless reason.bytesize <= MAX_CLOSE_MESSAGE_LENGTH && reason.valid_encoding?
+          raise Protocol::Capsule::ParseError, "Invalid close reason"
+        end
+        CloseInfo.new(code: code, reason: reason, remote: true)
+      end
+
+      def self.build_close_payload(code, reason)
+        unless code.is_a?(Integer) && code.between?(0, 0xffff_ffff)
+          raise ArgumentError, "Close code must be an unsigned 32-bit integer"
+        end
+        [code].pack("N") + truncate_reason(reason).b
+      end
+
+      # Truncate only at a UTF-8 character boundary (draft-16 §6).
+      def self.truncate_reason(reason, limit = MAX_CLOSE_MESSAGE_LENGTH)
+        reason = reason.to_s
+        reason = reason.b.dup.force_encoding(Encoding::UTF_8) if reason.encoding == Encoding::ASCII_8BIT
+        reason = reason.encode(Encoding::UTF_8)
+        raise ArgumentError, "Close reason must be valid UTF-8" unless reason.valid_encoding?
+        return reason if reason.bytesize <= limit
+
+        truncated = reason.byteslice(0, limit)
+        truncated = truncated.byteslice(0, truncated.bytesize - 1) until truncated.valid_encoding?
+        truncated
+      end
+
+      def self.parse_uni_stream_data(payload)
+        session_id, sid_len = Protocol.decode_varint_str(payload, 0)
+        return nil if sid_len == 0
+        validate_session_id!(session_id)
+
+        [session_id, payload.byteslice(sid_len..-1) || "".b]
+      end
+
+      def initialize(connection:, stream:, headers:)
+        @connection = connection
+        @stream = stream
+        @stream_id = stream.stream_id
+        @path = headers[":path"]
+        @authority = headers[":authority"]
+        @headers = headers
+        @accepted = false
+        @open = false
+        @datagram_callback = nil
+        @drain_callback = nil
+        @stream_callback = nil
+        @uni_stream_callback = nil
+        @close_callback = nil
+        @streams = {}  # stream_id => WebTransportStream
+        @starting_streams = {}
+        @streams_mutex = Mutex.new
+        @connect_buffer = "".b
+        @connect_decoder = Protocol::ConnectStreamDecoder.new
+        @connect_send_finished = false
+        @received_close = false
+        @connect_failed = false
+        @closed = false
+        @flow_control_enabled = false
+        @receive_options = DEFAULT_RECEIVE_OPTIONS
+      end
+
+      def stream_manager=(manager)
+        @streams_mutex.synchronize do
+          @stream_manager = manager
+          @streams.each_key { |stream_id| manager.register_stream(stream_id, @stream_id) }
+          @starting_streams.each_value { |stream| manager.register_starting_stream(stream) }
+        end
+      end
+
+      # Accept the session — sends 200 HEADERS on the CONNECT stream.
+      # Call only after the app has checked Origin and authorized the request.
+      #
+      # Limits apply to each child's queued Ruby input, not native buffers or
+      # the whole connection.
+      #
+      # By default a child that fills its buffer stops being delivered until
+      # the application reads, so a slow reader keeps its stream. A reader that
+      # never drains leaves it paused indefinitely, and a paused stream holds
+      # connection credit, which can stall its siblings.
+      #
+      # With receive_backpressure: false an overflowing child is reset instead:
+      # we send STOP_SENDING with receive_overflow_code, discard its queued
+      # input, and fail its pending reads. Its write side stays open.
+      def accept!(**receive_options)
+        raise IOError, "Session closed" if @closed
+        return if @accepted
+
+        unknown = receive_options.keys - DEFAULT_RECEIVE_OPTIONS.keys
+        raise ArgumentError, "Unknown receive options: #{unknown.join(", ")}" if unknown.any?
+
+        options = DEFAULT_RECEIVE_OPTIONS.merge(receive_options)
+        ReceiveQueue.validate_limits(options[:receive_buffer_bytes], options[:receive_buffer_chunks])
+        WebTransportStream.validate_backpressure(options[:receive_backpressure],
+          options[:receive_buffer_bytes], options[:receive_buffer_chunks])
+        WebTransportStream.validate_overflow_code(options[:receive_overflow_code])
+        @receive_options = options
+        frame = Protocol.build_headers_frame([[:":status", "200"]])
+        @stream.send(frame, fin: false)
+        @accepted = true
+        @open = true
+        @flow_control_enabled = @connection.wt_flow_control_enabled?
+        # A client may send capsules optimistically before our response. We held
+        # those bytes unparsed; now that the 2xx is out they can be processed
+        # (draft-ietf-webtrans-http3-16 §3.2).
+        drain_connect_capsules
+      end
+
+      # Send a datagram to the client (unreliable, no retransmission).
+      def send_datagram(data)
+        raise "Session not accepted" unless @accepted
+        raise "Session not open" unless accepts_datagrams?
+
+        Quicsilver.datagram_send(@connection.data, Protocol::Datagram.encode(@stream_id, data))
+      end
+
+      # Register a callback for datagrams from the client.
+      def on_datagram(&block)
+        @datagram_callback = block
+      end
+
+      # Register a callback for incoming streams from the client.
+      def on_stream(&block)
+        @stream_callback = block
+      end
+
+      # Open a server-initiated bidirectional stream to the client.
+      def open_stream
+        open_outgoing_stream(unidirectional: false)
+      end
+
+      # Register a callback for incoming unidirectional streams (client → server, read-only).
+      def on_uni_stream(&block)
+        @uni_stream_callback = block
+      end
+
+      # Open a server-initiated unidirectional stream to the client (write-only).
+      def open_uni_stream
+        open_outgoing_stream(unidirectional: true)
+      end
+
+      # Called when the peer raises our send credit, so an application that
+      # hit SendBlocked knows to retry. Writes are all or nothing, so there is
+      # no partial progress to resume from.
+      #
+      #   session.on_writable { flush_pending }
+      def on_writable(&block)
+        @writable_callback = block
+      end
+
+      # Register a callback for session close.
+      def on_close(&block)
+        @close_callback = block
+      end
+
+      # The peer is asking us to wind this session down. Advisory: the session
+      # stays usable, and the application decides when to close (draft-16 §4.7).
+      #
+      #   session.on_drain { stop_accepting_work }
+      def on_drain(&block)
+        @drain_callback = block
+      end
+
+      # Ask the peer to wind the session down. Does not close it.
+      def drain!
+        @stream.send(Protocol.build_frame(Protocol::FRAME_DATA, Protocol::Capsule.encode(WT_DRAIN_SESSION, "")), fin: false)
+      rescue
+        # Best-effort — connection may already be gone
+      end
+
+      def accepted?
+        @accepted
+      end
+
+      def open?
+        @open && !@closed
+      end
+
+      def closed?
+        @closed
+      end
+
+      def routable?
+        !@closed
+      end
+
+      def accepts_new_streams?
+        open?
+      end
+
+      def accepts_datagrams?
+        open?
+      end
+
+      def reject!(status = 403, headers = {})
+        return if @accepted || @rejected
+        @rejected = true
+
+        response_headers = [[":status", status.to_i.to_s]]
+        headers.each { |name, value| response_headers << [name.to_s.downcase, value.to_s] }
+        @stream.send(Protocol.build_headers_frame(response_headers), fin: true)
+        @open = false
+        # Optimistic capsules are discarded when the session is rejected (§3.2).
+        @connect_buffer = "".b
+      end
+
+      # Both endpoints must have advertised a non-zero WT_INITIAL_MAX_*
+      # setting (§5.1). We advertise none, so this is false today.
+      # Resolved once when the session is accepted, not asked per chunk: the
+      # answer cannot change afterwards, and the receive path reads it for
+      # every arriving byte.
+      def flow_control_enabled?
+        @flow_control_enabled
+      end
+
+      # What the peer permits us to send in this session. Seeded from its
+      # SETTINGS, then raised by capsules (§5.5, §5.6).
+      def flow_control
+        @flow_control ||= WebTransportFlowControl.from_settings(peer_settings)
+      end
+
+      # What the peer may send us, from the limits we advertised (§5.3, §5.4).
+      def receive_limits
+        @receive_limits ||= WebTransportReceiveLimits.from_settings(@connection.local_settings)
+      end
+
+      # Charge an incoming child stream against the limit we advertised
+      # (§5.6.2). Returns false when the limit is exceeded, having failed the
+      # session; the caller must not deliver the stream to the application.
+      #
+      # Exceeding a limit is a session error, so it must not escape into the
+      # transport callback that routed the stream: that runs on the poll
+      # thread and would take the whole connection down with it.
+      def count_incoming_stream(direction) # :nodoc:
+        return true unless flow_control_enabled?
+
+        receive_limits.open_stream!(direction)
+        true
+      rescue Protocol::WebTransport::FlowControlError => error
+        handle_capsule_error(error)
+        false
+      end
+
+      # Charge received stream body bytes (§5.6.4). Called per chunk, so it
+      # stays a plain integer add when flow control is off.
+      def count_received_data(bytes) # :nodoc:
+        return unless flow_control_enabled?
+
+        receive_limits.receive_data!(bytes)
+      rescue Protocol::WebTransport::FlowControlError => error
+        handle_capsule_error(error)
+      end
+
+      # Charge an outgoing stream against what the peer granted. Tells the peer
+      # we were blocked before raising, so it can raise the limit (§5.6.3).
+      def count_outgoing_stream(direction) # :nodoc:
+        return unless flow_control_enabled?
+
+        flow_control.open_stream!(direction)
+      rescue Protocol::WebTransport::SendBlocked => blocked
+        send_capsule(Protocol::WebTransport.build_streams_blocked(direction, blocked.limit))
+        raise
+      end
+
+      # Can this session send `bytes` right now? Ask before writing to avoid
+      # handling SendBlocked; writes are all or nothing, so a write larger
+      # than the remaining credit sends nothing.
+      #
+      # Credit rises only when the peer sends a WT_MAX_DATA capsule, so an
+      # application that is blocked has to retry. A notification for that
+      # arrives with grant handling.
+      def can_send?(bytes = 1) # :nodoc:
+        return true unless flow_control_enabled?
+
+        flow_control.data_remaining >= bytes
+      end
+
+      # Charge outgoing stream body bytes (§5.6.4). Body only: the prefix that
+      # links a stream to this session costs nothing.
+      def count_sent_data(bytes) # :nodoc:
+        return unless flow_control_enabled?
+
+        flow_control.send_data!(bytes)
+      rescue Protocol::WebTransport::SendBlocked => blocked
+        send_capsule(Protocol::WebTransport.build_data_blocked(blocked.limit))
+        raise
+      end
+
+      # Capsules ride the CONNECT stream as HTTP/3 DATA, like CLOSE and DRAIN.
+      # Signalling is advisory, so a send failure must not break the session.
+      def send_capsule(capsule)
+        @stream.send(Protocol.build_frame(Protocol::FRAME_DATA, capsule), fin: false)
+      rescue StandardError => error
+        Quicsilver.logger.debug(
+          "WebTransport session #{@stream_id} could not send a flow control capsule: #{error.message}"
+        )
+      end
+
+      # The application read `bytes`, freeing that much of the window. Grant
+      # the peer more without waiting to be told we blocked it: "An endpoint
+      # MUST NOT wait for a WT_DATA_BLOCKED... capsule before sending a
+      # WT_MAX_DATA" (§5.6).
+      def count_consumed_data(bytes) # :nodoc:
+        return unless flow_control_enabled?
+
+        granted = receive_limits.consume_data(bytes)
+        send_capsule(Protocol::WebTransport.build_max_data(granted)) if granted
+      end
+
+      # A child closed, so the session can afford another (§5.6).
+      def count_closed_stream(direction) # :nodoc:
+        return unless flow_control_enabled?
+
+        granted = receive_limits.close_stream(direction)
+        send_capsule(Protocol::WebTransport.build_max_streams(direction, granted)) if granted
+      end
+
+      # A reset charges what the sender counted, not what reached us (§5.4).
+      def count_reset_stream(final_size, delivered) # :nodoc:
+        return unless flow_control_enabled?
+
+        receive_limits.reset_stream!(final_size, delivered)
+      rescue Protocol::WebTransport::FlowControlError => error
+        handle_capsule_error(error)
+      end
+
+      def notify_writable
+        @writable_callback&.call
+      rescue StandardError => error
+        Quicsilver.logger.error("WebTransport on_writable callback failed: #{error.message}")
+      end
+
+      def peer_settings
+        @connection.settings
+      end
+
+      # Look up a stream by ID within this session.
+      def stream(stream_id)
+        @streams[stream_id]
+      end
+
+      # Close the session with an optional error code and message.
+      # Sends a WT_CLOSE_SESSION capsule (RFC draft-ietf-webtrans-http3)
+      # on the CONNECT stream before closing.
+      def close(code: 0, reason: "")
+        return if closed?
+        # Conversion can invoke application code or raise. Do it before
+        # changing lifecycle state so invalid input leaves the session usable.
+        payload = self.class.build_close_payload(code, reason)
+        was_open = @streams_mutex.synchronize do
+          was_open = @open
+          @open = false
+          was_open
+        end
+
+        if was_open
+          capsule = Protocol::Capsule.encode(WT_CLOSE_SESSION, payload)
+          finish_connect(Protocol.build_frame(Protocol::FRAME_DATA, capsule))
+        end
+
+        notify_close(code: code, reason: reason, remote: false)
+      end
+
+      # Decode CONNECT body bytes, then apply session-close policy.
+      def receive_connect_stream_data(data, fin: false)
+        return if @connect_failed
+        if @received_close
+          if data && !data.empty?
+            return handle_capsule_error(Protocol::Capsule::ParseError.new("Stream data after close capsule"))
+          end
+          @connect_decoder.finish! if fin
+        end
+        return if closed?
+
+        begin
+          @connect_decoder.each(data) do |chunk|
+            receive_connect_data(chunk)
+            break if @connect_failed || @received_close
+          end
+        ensure
+          # Application callbacks must not bypass trailing-byte or FIN checks.
+          if @received_close && !@connect_failed
+            if @connect_decoder.buffered?
+              handle_capsule_error(Protocol::Capsule::ParseError.new("Stream data after close capsule"))
+            elsif fin
+              @connect_decoder.finish!
+            end
+          end
+        end
+        return if @connect_failed
+        @connect_decoder.finish! if fin && !@received_close
+        receive_connect_fin("") if fin
+      rescue Protocol::FrameError => error
+        @connect_failed = true
+        @connect_decoder.clear
+        begin
+          @connection.shutdown(error.error_code)
+        ensure
+          notify_close
+        end
+      end
+
+      # Capsule bytes extracted from the CONNECT HTTP message body. :nodoc:
+      def receive_connect_data(data)
+        return if @connect_failed
+        if @received_close && data && !data.empty?
+          return handle_capsule_error(Protocol::Capsule::ParseError.new("Data after close capsule"))
+        end
+        return if closed?
+        @connect_buffer << data if data && !data.empty?
+        # Hold optimistic capsules unparsed until we have sent the 2xx (§3.2).
+        unless @accepted
+          if @connect_buffer.bytesize > MAX_OPTIMISTIC_CONNECT_BYTES
+            handle_capsule_error(
+              Protocol::Capsule::ParseError.new("Too many capsule bytes before the session was accepted")
+            )
+          end
+          return
+        end
+
+        drain_connect_capsules
+      end
+
+      # Parse whatever complete capsules the CONNECT buffer holds. Only reached
+      # once the session is accepted. :nodoc:
+      def drain_connect_capsules
+        while (capsule = Protocol::Capsule.parse(@connect_buffer))
+          type, payload, @connect_buffer = capsule
+          begin
+            handle_capsule(type, payload)
+          ensure
+            if @received_close && !@connect_buffer.empty?
+              handle_capsule_error(Protocol::Capsule::ParseError.new("Data after close capsule"))
+            end
+          end
+          break if @received_close
+        end
+      rescue Protocol::Capsule::ParseError, Protocol::WebTransport::FlowControlError => error
+        handle_capsule_error(error)
+      end
+
+      # Called by Server when the CONNECT/session stream receives FIN. :nodoc:
+      def receive_connect_fin(data)
+        receive_connect_data(data)
+        # An unaccepted session never parsed these bytes, so a partial capsule
+        # is not a peer error we can report (§3.2).
+        if @accepted && !@connect_buffer.empty?
+          handle_capsule_error(Protocol::Capsule::ParseError.new("Truncated capsule"))
+        end
+        finish_connect if @accepted && !@connect_failed
+        notify_close
+      end
+
+      # Called by Server when a datagram arrives for this session.
+      def receive_datagram(data) # :nodoc:
+        @datagram_callback&.call(data)
+      end
+
+      # Called by Server when the CONNECT stream is reset/closed.
+      #
+      # Idempotent: subsequent calls are a no-op. This matters because the FIN
+      # and capsule-error paths both fan into notify_close, and a CLOSE_SESSION
+      # capsule followed by FIN would otherwise fire @close_callback twice and
+      # re-walk an already-cleared @streams map.
+      def notify_close(code: 0, reason: "", remote: true) # :nodoc:
+        streams = @streams_mutex.synchronize do
+          return if @closed
+          @closed = true
+          @open = false
+          streams = @streams.values + @starting_streams.values
+          @streams.clear
+          @starting_streams.clear
+          streams
+        end
+
+        Quicsilver.logger.debug("WebTransport session #{@stream_id} notify_close")
+        begin
+          terminate_streams(streams)
+        ensure
+          @close_callback&.call(CloseInfo.new(code: code, reason: reason, remote: remote))
+        end
+      end
+
+      # Called by Server when a new stream with our session ID arrives.
+      def add_stream(stream_handle, stream_id) # :nodoc:
+        stream = Transport::Stream.new(stream_handle)
+        wt_stream = WebTransportStream.new(
+          session: self, stream: stream, stream_id: stream_id, **@receive_options
+        )
+        return wt_stream unless count_incoming_stream(:bidi)
+        return wt_stream unless register_stream(wt_stream)
+        @stream_callback&.call(wt_stream)
+        wt_stream
+      end
+
+      # Route data to the right stream.
+      def route_stream_data(stream_id, data) # :nodoc:
+        @streams[stream_id]&.receive_data(data)
+      end
+
+      # Called by Server when an incoming uni stream arrives.
+      def add_uni_stream(stream_handle, stream_id) # :nodoc:
+        stream = Transport::Stream.new(stream_handle)
+        wt_stream = WebTransportStream.new(
+          session: self, stream: stream, stream_id: stream_id,
+          direction: :receive_only, **@receive_options
+        )
+        return wt_stream unless count_incoming_stream(:uni)
+        return wt_stream unless register_stream(wt_stream)
+        @uni_stream_callback&.call(wt_stream)
+        wt_stream
+      end
+
+      def stream_started(stream, stream_id)
+        @streams_mutex.synchronize do
+          starting = @starting_streams.delete(stream.stream_handle)
+          stream.notify_start(stream_id)
+          @stream_manager&.register_stream(stream_id, @stream_id)
+          @streams[stream_id] = stream if starting && !@closed
+        end
+      end
+
+      def remove_starting_stream(handle)
+        stream = @streams_mutex.synchronize { @starting_streams.delete(handle) }
+        stream&.notify_close
+      end
+
+      # Called when a stream within this session is reset.
+      # `error_code` is the raw HTTP/3 code from a peer RESET_STREAM, so the
+      # stream can report it to the application (§4.4). nil for an ordinary
+      # close, where there is no code to deliver.
+      def remove_stream(stream_id, error_code: nil) # :nodoc:
+        stream = @streams_mutex.synchronize { @streams.delete(stream_id) }
+        return unless stream
+
+        error_code ? stream.notify_peer_reset(error_code) : stream.notify_close
+      end
+
+      private
+
+      def open_outgoing_stream(unidirectional:)
+        raise "Session not accepted" unless @accepted
+        raise "Session not open" unless accepts_new_streams?
+
+        count_outgoing_stream(unidirectional ? :uni : :bidi)
+        stream = @connection.open_stream(unidirectional: unidirectional)
+        wt_stream = WebTransportStream.new(
+          session: self, stream: stream, stream_id: stream.stream_id,
+          direction: unidirectional ? :send_only : :bidi, **@receive_options
+        )
+        type = unidirectional ? WT_STREAM_UNI : WT_STREAM_BIDI
+        prefix = Protocol.encode_varint(type) + Protocol.encode_varint(@stream_id)
+        # Grant receive credit before the prefix goes out. Native credit
+        # enforcement is off until the first grant, so data arriving in that
+        # window would bypass the budget entirely rather than be paused.
+        wt_stream.enable_receive_backpressure
+        stream.send(prefix)
+        stream.reliable_offset = prefix.bytesize if @connection.reliable_reset_enabled?
+        # Teardown may reset registered streams, so protect the header first.
+        # Registration also rejects and aborts if the session closed meanwhile.
+        raise "Session not open" unless register_stream(wt_stream, outgoing: true)
+
+        @stream_manager&.stream_started(stream.stream_id, stream.handle)
+        wt_stream
+      rescue StandardError
+        discard_outgoing_stream(wt_stream) if wt_stream
+        raise
+      end
+
+      def discard_outgoing_stream(stream)
+        @streams_mutex.synchronize do
+          @streams.delete(stream.stream_id)
+          @starting_streams.delete(stream.stream_handle)
+          @stream_manager&.discard_starting_stream(stream.stream_handle)
+        end
+        stream.abort(Protocol::WebTransport::SESSION_GONE) if stream.open?
+      end
+
+      def register_stream(stream, outgoing: false)
+        registered = @streams_mutex.synchronize do
+          if stream.stream_id
+            @stream_manager&.register_stream(stream.stream_id, @stream_id)
+          else
+            @stream_manager&.register_starting_stream(stream)
+          end
+          next false if @closed || (outgoing && !@open)
+
+          if stream.stream_id
+            @streams[stream.stream_id] = stream
+          else
+            @starting_streams[stream.stream_handle] = stream
+          end
+          true
+        end
+        stream.abort(Protocol::WebTransport::SESSION_GONE) unless registered
+        registered
+      end
+
+      def terminate_streams(streams)
+        failure = nil
+        streams.each do |stream|
+          stream.abort(Protocol::WebTransport::SESSION_GONE)
+        rescue StandardError => error
+          failure ||= error
+        end
+        raise failure if failure
+      end
+
+      def handle_capsule(type, payload)
+        case type
+        when WT_CLOSE_SESSION
+          closed_with = self.class.parse_close_payload(payload)
+          Quicsilver.logger.debug(
+            "WebTransport session #{@stream_id} received close capsule " \
+            "code=#{closed_with.code} reason=#{closed_with.reason.inspect}"
+          )
+          # draft-16 §6 requires the recipient to close or reset CONNECT.
+          # Finish our send side without discarding any queued response bytes.
+          @received_close = true
+          if @accepted
+            finish_connect
+          else
+            abort_connect(Protocol::H3_REQUEST_REJECTED)
+          end
+          notify_close(**closed_with.to_h)
+        when *Protocol::WebTransport::PROHIBITED_CAPSULES
+          # Per-stream limits are QUIC's job over HTTP/3, so these are a
+          # session error however flow control was negotiated (draft-16 §5.4).
+          raise Protocol::WebTransport::FlowControlError,
+            "Capsule 0x#{type.to_s(16)} is prohibited over HTTP/3"
+        when *Protocol::WebTransport::FLOW_CONTROL_CAPSULES.keys
+          # "if flow control is not enabled, an endpoint MUST ignore receipt
+          # of any flow control capsules... since the peer might not have
+          # received SETTINGS at the time they were sent" (§5.1). Ignoring is
+          # deliberate here, not a side effect of the type being unknown.
+          unless flow_control_enabled?
+            Quicsilver.logger.debug(
+              "WebTransport session #{@stream_id} ignoring flow control capsule " \
+              "0x#{type.to_s(16)}: flow control was not negotiated"
+            )
+            return
+          end
+
+          # Raises FlowControlError for a limit that does not increase, or a
+          # stream count above 2^60 (§5.6.2, §5.6.4).
+          before = flow_control.data_remaining
+          flow_control.apply(Protocol::WebTransport.parse_flow_control_capsule(type, payload))
+          notify_writable if flow_control.data_remaining > before
+        when WT_DRAIN_SESSION
+          # §4.7 fixes the capsule at Length = 0, so anything in the payload
+          # is a malformed message rather than an extension we can ignore.
+          unless payload.empty?
+            raise Protocol::Capsule::ParseError, "WT_DRAIN_SESSION takes no payload"
+          end
+
+          # Advisory only. The session stays open and usable; it is up to the
+          # application to wind down (draft-16 §4.7).
+          Quicsilver.logger.debug("WebTransport session #{@stream_id} received drain capsule")
+          @drain_callback&.call
+        else
+          # Unknown capsules are ignored, matching HTTP Capsule extensibility.
+        end
+      end
+
+      # A malformed capsule is a message error; a capsule whose contents break
+      # a flow control rule closes the session with its own code (§5.6).
+      def handle_capsule_error(error)
+        return if @connect_failed
+        @connect_failed = true
+        Quicsilver.logger.debug("WebTransport session #{@stream_id} capsule error: #{error.message}")
+        @connect_buffer.clear
+        @connect_decoder.clear
+        code = error.respond_to?(:error_code) ? error.error_code : Protocol::H3_MESSAGE_ERROR
+        abort_connect(code)
+        notify_close
+      end
+
+      def abort_connect(code)
+        # FIN may already be acknowledged, making a send-only RESET a no-op.
+        # Also stop receiving so a peer cannot hold failed CONNECT streams open.
+        @stream.abort(code)
+      rescue StandardError
+        # The native stream may already have gone; still clean up locally.
+      end
+
+      def finish_connect(data = "")
+        @streams_mutex.synchronize do
+          return if @connect_send_finished
+          @connect_send_finished = true
+        end
+
+        # Successful submission preserves queued bytes and sends FIN. If native
+        # submission fails on a live stream, abort both directions as a fallback.
+        @stream.send(data, fin: true)
+      rescue StandardError => error
+        begin
+          Quicsilver.logger.warn(
+            "WebTransport session #{@stream_id} close FIN submission failed (#{error.class}); aborting CONNECT"
+          )
+        rescue StandardError
+          # A broken logger must not prevent transport or session cleanup.
+        end
+        abort_connect(Protocol::H3_INTERNAL_ERROR)
+      end
+    end
+  end
+end