connectrpc 0.1.0

data/lib/connectrpc/streaming/session.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    # Read and write guards release only their own accepted operation.
+    class Direction
+      attr_reader :busy
+
+      def initialize
+        @busy = false
+      end
+
+      def run
+        entered = false
+        begin
+          raise StreamStateError, "Overlapping stream operation" if @busy
+
+          @busy = entered = true
+          yield
+        ensure
+          @busy = false if entered
+        end
+      end
+    end
+
+    class Session
+      attr_reader :trailers, :received, :sent
+
+      def initialize(binding:, method:, codec:, state:, input:, output:, request_limit:, response_limit:,
+                     request_wire_limit:, response_wire_limit:, request_encoding:, response_encoding:,
+                     terminal_wire_limit:, terminal_limit:, server: false, context: nil, lifecycle: nil,
+                     accept_encoding: [:identity], strategy: ConnectStrategy.new, publish: nil)
+        @strategy = strategy
+        @publish = publish
+        initialize_owner(binding, method, codec, state)
+        initialize_channels(input, output, server, context, lifecycle)
+        @accept_encoding = accept_encoding
+        initialize_messages(request_limit, response_limit)
+        initialize_framing(request_wire_limit, response_wire_limit, request_encoding, response_encoding,
+                           terminal_wire_limit: terminal_wire_limit, terminal_limit: terminal_limit)
+      end
+
+      def abandoned? = @abandoned
+      def consumed? = @eof
+      def send_failure?(error) = error.equal?(@send_failure)
+
+      def owned_error?(error)
+        error.equal?(@reading_error) || error.equal?(@writing_error) || error.equal?(@abandon_error)
+      end
+
+      def close
+        @closed = true
+        nil
+      end
+
+      private
+
+      def initialize_owner(binding, method, codec, state)
+        @binding = binding
+        @method = method
+        @codec = codec
+        @state = state
+        @thread = Thread.current
+        @scheduler = Fiber.scheduler
+        @closed = @send_closed = @eof = @abandoned = false
+      end
+
+      def initialize_channels(input, output, server, context, lifecycle)
+        @input = input
+        @output = output
+        @server = server
+        @context = context
+        @lifecycle = lifecycle
+        @reading = Direction.new
+        @writing = Direction.new
+      end
+
+      def initialize_messages(request_limit, response_limit)
+        @received = @sent = 0
+        @read_limit = @server ? request_limit : response_limit
+        @write_limit = @server ? response_limit : request_limit
+        @read_type = @server ? @method.request_type : @method.response_type
+        @write_type = @server ? @method.response_type : @method.request_type
+      end
+
+      def initialize_framing(request_wire, response_wire, request_encoding, response_encoding,
+                             terminal_wire_limit:, terminal_limit:)
+        initialize_reader(request_wire, response_wire, request_encoding, response_encoding,
+                          terminal_wire_limit: terminal_wire_limit, terminal_limit: terminal_limit)
+        initialize_writer(request_wire, response_wire, request_encoding, response_encoding,
+                          terminal_wire_limit: terminal_wire_limit, terminal_limit: terminal_limit)
+      end
+
+      def initialize_reader(request_wire, response_wire, request_encoding, response_encoding,
+                            terminal_wire_limit:, terminal_limit:)
+        @reader = @strategy.framing.new(input: self, request: @server, limit: @read_limit, state: @state,
+                                        wire_limit: @server ? request_wire : response_wire,
+                                        encoding: @server ? request_encoding : response_encoding,
+                                        terminal_wire_limit:, terminal_limit:,
+                                        on_error: ->(error) { @lifecycle&.record_failure(error) })
+      end
+
+      def initialize_writer(request_wire, response_wire, request_encoding, response_encoding,
+                            terminal_wire_limit:, terminal_limit:)
+        @writer = @strategy.framing.new(input: nil, output: self, request: !@server, limit: @write_limit, state: @state,
+                                        wire_limit: @server ? response_wire : request_wire,
+                                        encoding: @server ? response_encoding : request_encoding,
+                                        terminal_wire_limit: terminal_wire_limit,
+                                        terminal_limit: terminal_limit,
+                                        on_error: ->(error) { @lifecycle&.record_failure(error) })
+      end
+
+      def check_open!
+        raise StreamStateError, "Stream scope is closed" if @closed || @abandoned
+        return if Thread.current.equal?(@thread) && Fiber.scheduler.equal?(@scheduler)
+
+        raise StreamStateError, "Use the stream's owning reactor and thread"
+      end
+
+      def operation(direction)
+        guard = direction == :reading ? @reading : @writing
+        guard.run do
+          check_open!
+          @state.check!
+          yield
+        end
+      rescue StandardError => e
+        record_operation_failure(e, direction)
+        raise
+      end
+
+      def record_operation_failure(error, direction)
+        # Independent directions retain one failure each across application unwind.
+        case direction
+        when :reading then @reading_error = error
+        when :writing then @writing_error = error
+        when :abandon then @abandon_error = error
+        end
+        @lifecycle&.record_failure(error)
+      end
+    end
+  end
+end

data/lib/connectrpc/streaming/session_completion.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    class Session
+      # Recovery runs only after the scope relinquishes normal consumption.
+      # It cannot steal a live reader, decode skipped data or resume the endpoint.
+      def recover_send_failure
+        return @remote_error if @eof
+        return unless recovery_available?
+
+        @recovering = true
+        @recovery_expires ||= now + RECOVERY_SECONDS
+        @recovery_remaining ||= RECOVERY_LIMIT
+        operation(:reading) { recover_terminal }
+      rescue StandardError => e
+        @lifecycle&.record_failure(e)
+        nil
+      end
+
+      private
+
+      def recovery_available? = !@reading.busy && !@server && !@abandoned
+
+      def recover_terminal # rubocop:disable Metrics/MethodLength
+        leading
+        loop do
+          frame = @reader.read_frame(skip_data: true)
+          unless frame
+            return recovered_grpc_error if @strategy.grpc?
+
+            return
+          end
+          return recovered_error(frame.last) if frame.first.anybits?(2)
+
+          @received += 1
+          return if !@strategy.grpc? && @method.is_a?(ClientStreamMethod) && @received > 1
+        end
+      end
+
+      def recovered_grpc_error
+        strategy = @strategy #: GRPCProtocol::Strategy
+        exchange = @input #: _GRPCStreamExchange
+        return unless strategy.recoverable?(exchange)
+
+        accept_grpc_terminal
+        nil
+      rescue Error => e
+        return e if e.equal?(@remote_error) && @eof
+
+        raise
+      end
+
+      def accept_grpc_terminal
+        strategy = @strategy #: GRPCProtocol::Strategy
+        exchange = @input #: _GRPCStreamExchange
+        @remote_error, @trailers = strategy.terminal(exchange, @headers || Metadata.new)
+        validate_terminal_count
+        expires = @recovery_expires || (now + Deadline::MAX_NATIVE_WAIT)
+        finish_transport(expires)
+        @eof = true
+        error = @remote_error
+        raise error, cause: nil if error
+
+        nil
+      end
+
+      def recovered_error(bytes)
+        accept_terminal(bytes)
+        nil
+      rescue Error => e
+        return e if e.equal?(@remote_error) && @eof
+
+        raise
+      end
+
+      def accept_terminal(bytes)
+        @remote_error, @trailers = parse_terminal(bytes)
+        validate_terminal_count
+        expires = @recovery_expires || (now + TAIL_SECONDS)
+        verify_tail(expires)
+        finish_transport(expires)
+        @eof = true
+        error = @remote_error
+        raise error, cause: nil if error
+
+        nil
+      end
+
+      def parse_terminal(bytes)
+        Streaming.parse_terminal(bytes, metadata: @headers || Metadata.new,
+                                        on_error: ->(error) { @lifecycle&.record_failure(error) })
+      end
+
+      def validate_terminal_count
+        return unless !@remote_error && @strategy.single_response?(@method) && @received != 1
+
+        raise Error.new(:unimplemented, "Expected exactly one response"), cause: nil
+      end
+
+      def verify_tail(expires)
+        extra = read(1, timeout: completion_timeout(expires))
+        return unless extra && !extra.empty?
+
+        raise Error.new(:internal, "Body bytes after streaming terminal"), cause: nil
+      end
+
+      def finish_transport(expires)
+        exchange = @input #: _StreamExchange
+        output = @output #: _StreamExchange
+        output.close_send
+        @send_closed = true
+        exchange.finish(timeout: completion_timeout(expires))
+        @state.check!
+        completion_timeout(expires)
+        nil
+      end
+
+      def completion_timeout(expires)
+        remaining = expires - now
+        raise Error.new(:unavailable, "Streaming completion policy expired"), cause: nil unless remaining.positive?
+
+        remaining
+      end
+
+      def recovery_timeout
+        expires = @recovery_expires #: Float
+        completion_timeout(expires)
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/connectrpc/streaming/session_io.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    class Session
+      def write(bytes)
+        check_open!
+        write_chunk(bytes)
+        check_open!
+        nil
+      rescue StandardError => e
+        record_send_failure(e)
+      end
+
+      def read(length, timeout: nil)
+        check_open!
+        timeout = recovery_read_timeout(length) if @recovery_expires
+        deadline = @context&.deadline
+        timeout = deadline.remaining if @server && deadline
+        bytes = @input.read(length, timeout: @strategy.wait(timeout))
+        check_open!
+        count_recovery_bytes(bytes)
+        bytes
+      end
+
+      private
+
+      def write_chunk(bytes)
+        if @server
+          output = @output #: _StreamingOutput
+          output.write(bytes, timeout: @strategy.wait(@context&.deadline&.remaining))
+        else
+          @output.write(bytes)
+        end
+      end
+
+      def record_send_failure(error)
+        @lifecycle&.record_failure(error)
+        @state.check!
+        if error.is_a?(IOError) || error.is_a?(SystemCallError)
+          failure = @send_failure = Error.new(:unavailable, "Streaming write failed")
+          raise failure, cause: nil
+        end
+        @send_failure = error if error.is_a?(Error) && error.code == "unavailable"
+        raise error
+      end
+
+      def recovery_read_timeout(length)
+        remaining = @recovery_remaining #: Integer
+        raise Error.new(:resource_exhausted, "Streaming recovery byte limit"), cause: nil if length > remaining
+
+        recovery_timeout
+      end
+
+      def count_recovery_bytes(bytes)
+        remaining = @recovery_remaining
+        @recovery_remaining = remaining - bytes.bytesize if remaining && bytes
+      end
+
+      def leading
+        snapshot = @headers
+        return snapshot if snapshot
+
+        @headers = if @server
+                     @context #: StreamingContext
+                       .request_metadata.freeze
+                   else
+                     response_metadata
+                   end
+      end
+
+      def response_metadata # rubocop:disable Metrics/MethodLength
+        exchange = @input #: _StreamExchange
+        strategy = @strategy
+        if strategy.is_a?(GRPCProtocol::Strategy)
+          grpc = @input #: _GRPCStreamExchange
+          return strategy.leading(grpc, @reader, @accept_encoding, @recovery_expires ? recovery_timeout : nil,
+                                  input: self)
+        end
+        head = @recovery_expires ? exchange.response_head(timeout: recovery_timeout) : exchange.response_head
+        validate_response_status(head.status)
+        values = Protocol.headers(head.headers)
+        validate_response_headers(values)
+        Protocol.metadata(values).freeze
+      end
+
+      def validate_response_status(status)
+        return if status == 200
+
+        raise Error.new(Error::HTTP_FALLBACK.fetch(status, "unknown"), "HTTP #{status}"), cause: nil
+      end
+
+      def validate_response_headers(values)
+        unless Streaming.codec(Protocol.single(values, "content-type")) == @codec
+          raise Error.new(:internal, "Unexpected streaming response content type"), cause: nil
+        end
+
+        encoding = Protocol.content_encoding(Streaming.coding_headers(values))
+        unless encoding && @accept_encoding.include?(encoding)
+          raise Error.new(:internal, "Unsupported streaming response encoding"), cause: nil
+        end
+
+        @reader.encoding = encoding
+      end
+    end
+  end
+end

data/lib/connectrpc/streaming/session_messages.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    class Session
+      def remote_completed?(error)
+        @strategy.grpc? && @eof && error.equal?(@remote_error)
+      end
+
+      def headers
+        @headers || operation(:reading) { leading }
+      end
+
+      def receive
+        operation(:reading) { receive_message }
+      end
+
+      def send_message(message)
+        operation(:writing) do
+          validate_send(message)
+          encode_message(message)
+        end
+      end
+
+      def close_send
+        operation(:writing) do
+          return nil if @send_closed
+
+          @send_closed = true
+          output = @output #: _StreamExchange
+          output.close_send
+          nil
+        end
+      end
+
+      def abandon
+        check_open!
+        @abandoned = true
+        @output.abort
+        nil
+      rescue StandardError => e
+        record_operation_failure(e, :abandon)
+        raise
+      end
+
+      private
+
+      def receive_message
+        raise StreamStateError, "Normal response consumption was relinquished" if @recovering
+
+        return completed_receive if @eof
+
+        leading
+        frame = @reader.read_frame
+        return receive_eof unless frame
+        return accept_terminal(frame.last) if frame.first.anybits?(2)
+
+        decode_message(frame.last)
+      end
+
+      def completed_receive
+        error = @remote_error
+        raise error, cause: nil if error
+
+        nil
+      end
+
+      def receive_eof
+        return accept_grpc_terminal unless @server || !@strategy.grpc?
+
+        raise Error.new(:internal, "Missing streaming terminal"), cause: nil unless @server
+
+        @eof = true
+        nil
+      end
+
+      def decode_message(bytes)
+        @received += 1
+        validate_response_count unless @strategy.grpc?
+        message = @binding.decode(bytes, type: @read_type, codec: @codec)
+        @state.check!
+        raise Error.new(:internal, "Binding decoded a nil streaming message"), cause: nil if message.nil?
+
+        message
+      rescue CodecError => e
+        @lifecycle&.record_failure(e)
+        raise Error.new(@strategy.decode_error(@server), "Cannot decode streaming message"), cause: nil
+      end
+
+      def validate_response_count
+        return unless !@server && @method.is_a?(ClientStreamMethod) && @received > 1
+
+        raise Error.new(:unimplemented, "Expected exactly one response"), cause: nil
+      end
+
+      def validate_send(message)
+        raise StreamStateError, "Request sending is closed" if @send_closed
+        raise Error.new(:invalid_argument, "Nil is not a streaming message"), cause: nil if message.nil?
+        return unless !@server && @method.is_a?(ServerStreamMethod) && @sent.positive?
+
+        raise StreamStateError, "Server streaming accepts one request"
+      end
+
+      def encode_message(message) # rubocop:disable Metrics/MethodLength
+        bytes = @binding.encode(message, type: @write_type, codec: @codec)
+        @state.check!
+        Protocol.check_size!(bytes, @write_limit)
+        publisher = @publish
+        publisher ? publisher.call : @context&.send(:publish_headers)
+        @writer.emit(bytes)
+        @sent += 1
+        nil
+      rescue CodecError => e
+        @lifecycle&.record_failure(e)
+        raise Error.new(@server ? :internal : :invalid_argument, "Cannot encode streaming message"), cause: nil
+      end
+    end
+  end
+end

data/lib/connectrpc/streaming/strategy.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    # Protocol policy alone varies; Session owns all scope and I/O arbitration.
+    class ConnectStrategy
+      def grpc? = false
+      def framing = Framing
+      def wait(timeout) = timeout
+      def single_response?(method) = method.is_a?(ClientStreamMethod)
+      def decode_error(server) = server ? :invalid_argument : :internal
+    end
+  end
+
+  module GRPCProtocol
+    class Framing < Streaming::Framing
+      private
+
+      def validate_flags(flags)
+        protocol_error("Invalid gRPC envelope flags") unless [0, 1].include?(flags)
+        protocol_error("Unnegotiated compression") if flags == 1 && @encoding != :gzip
+      end
+
+      def protocol_error(message)
+        raise Error.new(:internal, message), cause: nil
+      end
+    end
+
+    class Strategy
+      def initialize(codec:, wire_limit:, limit:, on_error: nil)
+        @on_error = on_error
+        @codec = codec
+        @wire_limit = wire_limit
+        @limit = limit
+      end
+
+      def grpc? = true
+      def framing = Framing
+      def wait(timeout) = [timeout || Deadline::MAX_NATIVE_WAIT, Deadline::MAX_NATIVE_WAIT].min
+      def single_response?(method) = method.is_a?(Method) || method.is_a?(ClientStreamMethod)
+      def decode_error(_server) = :internal
+
+      def leading(exchange, reader, accept_encoding, timeout, input:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        head = @head = exchange.response_head(timeout: wait(timeout))
+        values = Protocol.headers(head.headers)
+        GRPCProtocol.check_fields!(values)
+        reject_media(input, exchange, head, timeout) unless GRPCProtocol.media?(Protocol.single(values, "content-type"))
+        if !head.end_stream && values.key?("grpc-status") && GRPCProtocol.status_value(values).nil?
+          raise Error.new(:unknown, "Malformed initial grpc-status"), cause: nil
+        end
+
+        coding = GRPCProtocol.encoding(values)
+        raise Error.new(:internal, "Unadvertised gRPC encoding"), cause: nil unless accept_encoding.include?(coding)
+
+        reader.encoding = coding
+        head.end_stream ? Metadata.new.freeze : Protocol.metadata(values).freeze
+      end
+
+      def reject_media(input, exchange, head, timeout) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+        if head.end_stream
+          terminal = head.headers
+        else
+          loop do
+            bytes = input.read(Streaming::FRAGMENT_SIZE, timeout: wait(timeout))
+            break if bytes.nil? || bytes.empty?
+          end
+          terminal = exchange.response_trailers || {}
+        end
+        GRPCProtocol.check_fields!(terminal, @wire_limit)
+        code = if terminal.key?("grpc-status") || head.headers.key?("grpc-status")
+                 "internal"
+               else
+                 Error::HTTP_FALLBACK.fetch(head.status, "unknown")
+               end
+        raise Error.new(code, "Unexpected gRPC response content type"), cause: nil
+      end
+
+      def recoverable?(exchange)
+        head = @head #: GRPCHead
+        fields = head.end_stream ? head.headers : exchange.response_trailers
+        return false unless fields
+
+        number = GRPCProtocol.status_value(fields)
+        !!number&.positive?
+      end
+
+      def terminal(exchange, metadata)
+        head = @head #: GRPCHead
+        fields = head.end_stream ? head.headers : exchange.response_trailers
+        GRPCProtocol.parse_status(fields || {}, codec: @codec, http_status: head.status, metadata: metadata,
+                                                wire_limit: @wire_limit, limit: @limit, on_error: @on_error)
+      end
+    end
+  end
+end