connectrpc 0.1.0

data/lib/connectrpc/streaming/client_scope.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    class ClientScope
+      attr_accessor :completed, :abandoned, :independent_error, :failure, :result, :delivered_error
+
+      def initialize(lifecycle)
+        @lifecycle = lifecycle
+        @completed = false
+        @abandoned = false
+      end
+
+      def run(timeout, cancellation, &)
+        # @type var error: Exception?
+        error = nil
+        execute(timeout, cancellation, &)
+      rescue Exception => e # rubocop:disable Lint/RescueException -- Finalization needs the actual escape, including fatal exceptions.
+        error = e
+        raise
+      ensure
+        finish_preserving_user(error)
+      end
+
+      def execute(timeout, cancellation)
+        active, deadline = start(timeout, cancellation)
+        yield active, deadline
+        active.commit! if @completed
+        @result
+      rescue StandardError => e
+        @lifecycle&.record_failure(e)
+        @state&.commit! unless @independent_error || @abandoned
+        raise
+      end
+      private :execute
+
+      def cleanup(session)
+        return if @completed || @delivered_error
+
+        @abandoned = true if implicit_abandonment?
+        session.abandon unless session.abandoned?
+      rescue StandardError => e
+        @lifecycle&.record_failure(e)
+      end
+
+      def record_user_error(error)
+        @independent_error = error
+        @lifecycle&.record_failure(error)
+      end
+
+      private
+
+      def finish_preserving_user(error)
+        finish(@independent_error || error)
+      ensure
+        original = @independent_error
+        raise original, cause: original.cause if original
+      end
+
+      def finish(error)
+        @state&.close
+        lifecycle = @lifecycle
+        return unless lifecycle
+
+        lifecycle.record_failure(error) if error
+        report_processing(lifecycle, error)
+        lifecycle.finish(delivery: delivery_completed?(error) ? :completed : :aborted)
+      end
+
+      def start(timeout, cancellation)
+        deadline = Deadline.new(timeout) unless timeout.nil?
+        active = @state = CallCancellation.new(deadline: deadline, cancellation: cancellation)
+        active.check!
+        [active, deadline]
+      end
+
+      def implicit_abandonment?
+        !@independent_error && (@failure.nil? || @failure.is_a?(StreamNotConsumedError))
+      end
+
+      def success?(error) = @completed && error.nil?
+
+      def delivery_completed?(error)
+        return true if success?(error)
+
+        delivered = @delivered_error
+        return false unless delivered
+
+        delivered.equal?(error)
+      end
+
+      def report_processing(lifecycle, error)
+        normalized = normalized_error(error)
+        lifecycle.processing_finished(code: normalized&.code || ("OK" if success?(error)),
+                                      error: error, normalized_error: normalized)
+      end
+
+      def normalized_error(error)
+        return Error.new(:canceled, "Stream abandoned") if @abandoned
+
+        error if error.is_a?(Error)
+      end
+    end
+  end
+end

data/lib/connectrpc/streaming/framing.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    # @type var types: Hash[codec, String]
+    types = { proto: "application/connect+proto", json: "application/connect+json" }
+    CONTENT_TYPES = types.freeze
+    TERMINAL_LIMIT = 65_536
+    FRAGMENT_SIZE = 16_384
+    RECOVERY_LIMIT = 262_144
+    RECOVERY_SECONDS = 0.1
+    TAIL_SECONDS = 1.0
+
+    def self.codec(content_type)
+      return :proto if content_type&.match?(%r{\Aapplication/connect\+proto\z}i)
+      return :json if content_type&.match?(%r{\Aapplication/connect\+json\z}i)
+
+      nil
+    end
+
+    # Streaming content coding uses distinct protocol headers; reuse only the
+    # validated unary negotiation rules, never whole-stream compression.
+    def self.coding_headers(headers)
+      result = headers.except("content-encoding", "accept-encoding")
+      result["content-encoding"] = headers["connect-content-encoding"] if headers.key?("connect-content-encoding")
+      result["accept-encoding"] = headers["connect-accept-encoding"] if headers.key?("connect-accept-encoding")
+      result
+    end
+
+    class Framing
+      attr_reader :messages, :terminal
+      attr_writer :encoding
+
+      def initialize(input:, request:, wire_limit:, limit:, output: nil, encoding: :identity,
+                     terminal_wire_limit: TERMINAL_LIMIT, terminal_limit: TERMINAL_LIMIT, state: nil, on_error: nil)
+        @input = input
+        @output = output
+        @request = request
+        @wire_limit = wire_limit
+        @limit = limit
+        @encoding = encoding
+        @terminal_wire_limit = terminal_wire_limit
+        @terminal_limit = terminal_limit
+        @on_error = on_error
+        initialize_state(state)
+      end
+
+      def read_frame(timeout: nil, skip_data: false)
+        prefix = exact(5, eof: true, timeout: timeout)
+        return if prefix.nil?
+
+        flags, length = prefix.unpack("CN") #: [Integer, Integer]
+        validate_envelope(flags, length)
+        bytes = payload(flags, length, timeout: timeout, skip_data: skip_data)
+        @terminal = true if flags.anybits?(2)
+        @messages += 1 unless @terminal
+        [flags, bytes]
+      end
+
+      def emit(bytes, terminal: false)
+        flags, bytes = prepare_payload(bytes, terminal)
+        @state&.check!
+        output = @output #: _StreamingWriter
+        output.write([flags, bytes.bytesize].pack("CN"))
+        emit_fragments(bytes, output)
+        nil
+      end
+
+      private
+
+      def initialize_state(state)
+        @state = state
+        @messages = 0
+        @terminal = false
+      end
+
+      def validate_envelope(flags, length)
+        validate_flags(flags)
+        bound = flags.anybits?(2) ? @terminal_wire_limit : @wire_limit
+        raise Error.new(:resource_exhausted, "Envelope exceeds wire byte limit"), cause: nil if length > bound
+      end
+
+      def validate_flags(flags)
+        protocol_error("Invalid envelope flags") unless [0, 1, 2, 3].include?(flags)
+        protocol_error("Request terminal is forbidden") if flags.anybits?(2) && @request
+        protocol_error("Envelope after terminal") if @terminal
+        raise Error.new(:internal, "Unnegotiated compression"), cause: nil if flags.anybits?(1) && @encoding != :gzip
+      end
+
+      def payload(flags, length, timeout:, skip_data:)
+        return skip_payload(length, timeout) if skip_data && !flags.anybits?(2)
+
+        bytes = exact(length, timeout: timeout) #: String
+        bound = flags.anybits?(2) ? @terminal_limit : @limit
+        bytes = inflate(bytes, bound) if flags.anybits?(1)
+        Protocol.check_size!(bytes, bound)
+        bytes
+      end
+
+      def inflate(bytes, bound)
+        protocol_error("Empty compressed envelope") if bytes.empty?
+        Compression.decode(bytes, limit: bound, deadline: @state, on_error: @on_error)
+      rescue Compression::Malformed, Zlib::Error => e
+        @on_error&.call(e)
+        protocol_error("Malformed compressed envelope")
+      end
+
+      def skip_payload(length, timeout)
+        remaining = length
+        while remaining.positive?
+          chunk = exact([remaining, FRAGMENT_SIZE].min, timeout: timeout) #: String
+          remaining -= chunk.bytesize
+        end
+        ""
+      end
+
+      def protocol_error(message)
+        raise Error.new(@request ? :invalid_argument : :internal, message), cause: nil
+      end
+    end
+  end
+  private_constant :Streaming
+end

data/lib/connectrpc/streaming/framing_io.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    class Framing
+      private
+
+      def prepare_payload(bytes, terminal)
+        bound = terminal ? @terminal_wire_limit : @wire_limit
+        Protocol.check_size!(bytes, terminal ? @terminal_limit : @limit)
+        flags = terminal ? 2 : 0
+        if !terminal && @encoding == :gzip
+          bytes = Compression.encode(bytes, limit: bound, deadline: @state, on_error: @on_error)
+          flags = 1
+        end
+        check_output_size(bytes, bound)
+        [flags, bytes]
+      end
+
+      def check_output_size(bytes, bound)
+        Protocol.check_size!(bytes, bound)
+        return if bytes.bytesize <= 0xffff_ffff
+
+        raise Error.new(:resource_exhausted, "Envelope exceeds uint32 length"), cause: nil
+      end
+
+      def emit_fragments(bytes, output)
+        offset = 0
+        while offset < bytes.bytesize
+          @state&.check!
+          fragment = bytes.byteslice(offset, FRAGMENT_SIZE) #: String
+          output.write(fragment)
+          offset += fragment.bytesize
+        end
+      end
+
+      def exact(length, eof: false, timeout: nil)
+        bytes = +"".b
+        while bytes.bytesize < length
+          chunk = read_chunk(length - bytes.bytesize, timeout)
+          if chunk.nil? || chunk.empty?
+            return if eof && bytes.empty?
+
+            protocol_error("Truncated envelope")
+          end
+          bytes << chunk
+        end
+        bytes
+      end
+
+      def read_chunk(length, timeout)
+        @state&.check!
+        input = @input #: _StreamingInput
+        chunk = input.read([length, FRAGMENT_SIZE].min, timeout: timeout)
+        @state&.check!
+        protocol_error("Input exceeded requested fragment") if chunk && chunk.bytesize > length
+        chunk
+      end
+    end
+  end
+end

data/lib/connectrpc/streaming/method.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  # Streaming declarations share validation, but are never unary Methods.
+  class StreamDeclaration
+    attr_reader :service, :name, :request_type, :response_type, :path, :idempotency
+
+    def initialize(service:, name:, request_type:, response_type:, idempotency: :unknown)
+      declaration = Method.new(service: service, name: name, request_type: request_type,
+                               response_type: response_type, idempotency: idempotency)
+      @service = declaration.service
+      @name = declaration.name
+      @request_type = declaration.request_type
+      @response_type = declaration.response_type
+      @path = declaration.path
+      @idempotency = declaration.idempotency
+      freeze
+    end
+  end
+  private_constant :StreamDeclaration
+
+  class ServerStreamMethod < StreamDeclaration
+    def cardinality = :server_stream
+  end
+
+  class ClientStreamMethod < StreamDeclaration
+    def cardinality = :client_stream
+  end
+
+  class BidiStreamMethod < StreamDeclaration
+    def cardinality = :bidi_stream
+  end
+end

data/lib/connectrpc/streaming/server.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  class Server
+    # Explicit native-host SPI. Portable adapters retain the unary entry point.
+    def call_stream(path:, http_method:, headers:, input:, output:, publish:, lifecycle: nil, cancellation: nil, # rubocop:disable Metrics/MethodLength
+                    http2: false, capabilities: nil)
+      capabilities = stream_capabilities(http2, capabilities)
+      unless capabilities
+        return call(path: path, http_method: http_method, headers: headers, input: input,
+                    lifecycle: lifecycle, cancellation: cancellation)
+      end
+
+      if @methods[path].is_a?(BidiStreamMethod) && !capabilities.include?(:bidi_stream)
+        return bare(505, {}, cancellation: cancellation)
+      end
+
+      return bare(415, {}, cancellation: cancellation) unless @protocol.include?(:connect)
+
+      values = Protocol.headers(headers)
+      codec = Streaming.codec(Protocol.single(values, "content-type"))
+      rejection = stream_preflight(http_method, codec, cancellation)
+      return rejection if rejection || !codec
+
+      execute_native_stream(path, values, codec, http_method: http_method,
+                                                 input: input, output: output, publish: publish,
+                                                 lifecycle: lifecycle, cancellation: cancellation,
+                                                 capabilities: capabilities)
+    end
+
+    private
+
+    def stream_capabilities(http2, capabilities)
+      # @type var shapes: Array[streaming_cardinality]
+      shapes = %i[server_stream client_stream bidi_stream]
+      return (http2 ? shapes : nil) if capabilities.nil?
+
+      raise ArgumentError, "Invalid streaming capabilities" if http2 || !stream_capability_list?(capabilities)
+
+      capabilities
+    end
+
+    def stream_capability_list?(capabilities)
+      # @type var shapes: Array[streaming_cardinality]
+      shapes = %i[server_stream client_stream bidi_stream]
+      capabilities.is_a?(Array) && !capabilities.empty? && capabilities.uniq == capabilities &&
+        (capabilities - shapes).empty?
+    end
+
+    def stream_preflight(http_method, codec, cancellation)
+      return bare(405, { "allow" => ["POST"] }, cancellation: cancellation) unless http_method == "POST"
+      return if codec
+
+      bare(415, { "accept-post" => [Streaming::CONTENT_TYPES.values.join(", ")] }, cancellation: cancellation)
+    end
+
+    def execute_native_stream(path, headers, codec, http_method:, input:, output:, publish:, lifecycle:,
+                              cancellation:, capabilities:) # rubocop:disable Metrics/MethodLength
+      # @type var owned: bool?
+      owned = nil
+      # @type var error: Exception?
+      error = nil
+      lifecycle, owned = begin_native_processing(path, headers, lifecycle, http_method)
+      work = lambda {
+        process_stream(path, headers, codec, input: input, output: output, publish: publish,
+                                             lifecycle: lifecycle, cancellation: cancellation,
+                                             capabilities: capabilities)
+      }
+      lifecycle ? lifecycle.activate(&work) : work.call
+      nil
+    rescue Exception => e # rubocop:disable Lint/RescueException -- observe the actual escape and preserve it
+      error = e
+      raise
+    ensure
+      finish_native_processing(lifecycle, owned, error) unless owned.nil?
+    end
+
+    def begin_native_processing(path, headers, lifecycle, http_method)
+      owned = lifecycle.nil?
+      lifecycle ||= start_call(path: path, headers: headers, http_method: http_method)
+      lifecycle&.begin_processing(self, path)
+      [lifecycle, owned]
+    end
+
+    def finish_native_processing(lifecycle, owned, error)
+      return unless lifecycle
+
+      lifecycle.processing_finished(code: nil, error: error) unless lifecycle.outcome
+      lifecycle.finish(delivery: :unobserved) if owned
+    end
+
+    def process_stream(path, headers, codec, input:, output:, publish:, lifecycle:, cancellation:, capabilities:)
+      # @type var state: Streaming::ServerState?
+      active = state = Streaming::ServerState.new(headers: headers, codec: codec, publish: publish,
+                                                  lifecycle: lifecycle, cancellation: cancellation)
+      capture_stream_error(active) do
+        require_stream_capability(path, capabilities)
+        execute_stream_handler(active, path, input, output)
+      end
+      render_stream_terminal(active, output)
+    ensure
+      state&.session&.close
+      state&.context&.close
+    end
+
+    def require_stream_capability(path, capabilities)
+      declaration = @methods[path]
+      return if !declaration || declaration.is_a?(Method) || capabilities.include?(declaration.cardinality)
+
+      raise Error.new(:unimplemented, "Unsupported streaming method"), cause: nil
+    end
+
+    def capture_stream_error(state)
+      yield
+    rescue StandardError => e
+      state.context&.record_failure(e)
+      state.lifecycle&.record_failure(e)
+      safe = e.is_a?(Error) ? e : Error.new(:internal, "Internal error")
+      state.error = terminal_error(safe, state.context, state.cancellation)
+    end
+  end
+end

data/lib/connectrpc/streaming/server_execution.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Streaming
+    # Mutable state is local to one original processing task, never the Server.
+    class ServerState
+      attr_reader :headers, :codec, :publish, :lifecycle, :cancellation
+      attr_accessor :context, :session, :encoding, :error
+
+      def initialize(headers:, codec:, publish:, lifecycle:, cancellation:)
+        @headers = headers
+        @codec = codec
+        @publish = publish
+        @lifecycle = lifecycle
+        @cancellation = cancellation
+        @encoding = :identity
+      end
+    end
+  end
+
+  class Server
+    private
+
+    def execute_stream_handler(state, path, input, output)
+      state.encoding = stream_encoding(state.headers)
+      context = state.context = streaming_context(state)
+      declaration = streaming_declaration(path)
+      session = state.session = new_stream_session(state, declaration, input, output)
+      invoke_stream_handler(@handlers.fetch(path), declaration, session, context)
+      context.check!
+    end
+
+    def stream_encoding(headers)
+      normalized = Streaming.coding_headers(headers)
+      validate_headers!(normalized)
+      request_encoding = Protocol.content_encoding(normalized) #: encoding
+      Protocol.response_encoding(normalized, request_encoding, @encoding)
+    end
+
+    def streaming_declaration(path)
+      declaration = @methods[path]
+      return declaration if declaration && !declaration.is_a?(Method) && @handlers[path]
+
+      raise Error.new(:unimplemented, "Unknown streaming method"), cause: nil
+    end
+
+    def new_stream_session(state, declaration, input, output)
+      context = state.context #: StreamingContext
+      coding = Protocol.content_encoding(Streaming.coding_headers(state.headers)) #: encoding
+      Streaming::Session.new(binding: @binding, method: declaration, codec: state.codec, state: context,
+                             input: input, output: output, request_limit: @request_limit,
+                             response_limit: @response_limit, request_wire_limit: @request_wire_limit,
+                             response_wire_limit: @response_wire_limit,
+                             request_encoding: coding,
+                             response_encoding: state.encoding, terminal_wire_limit: @terminal_wire_limit,
+                             terminal_limit: @terminal_limit, server: true, context: state.context,
+                             lifecycle: state.lifecycle)
+    end
+
+    def invoke_stream_handler(handler, declaration, session, context) # rubocop:disable Metrics/MethodLength
+      context.check!
+      case declaration
+      when ServerStreamMethod
+        ss = handler #: _ServerStreamHandler[untyped, untyped]
+        request = single_stream_request(session)
+        context.check!
+        ss.call(request, ResponseWriter.new(session, context), context)
+      when ClientStreamMethod
+        cs = handler #: _ClientStreamHandler[untyped, untyped]
+        session.send_message(cs.call(RequestReader.new(session), context))
+      when BidiStreamMethod
+        invoke_bidi_stream(handler, session, context)
+      end
+    end
+
+    def invoke_bidi_stream(handler, session, context)
+      bidi = handler #: _BidiStreamHandler[untyped, untyped]
+      bidi.call(ServerDuplex.new(session, context), context)
+    end
+
+    def single_stream_request(session)
+      request = session.receive
+      return request if !request.nil? && session.receive.nil?
+
+      raise Error.new(:unimplemented, "Expected exactly one request"), cause: nil
+    end
+  end
+end

data/lib/connectrpc/streaming/server_terminal.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  class Server
+    private
+
+    def render_stream_terminal(state, output)
+      context = state.context ||= streaming_context(state, headers: {})
+      merge_stream_error_metadata(state.error, context)
+      bytes, effective = stream_terminal_bytes(state, context)
+      handler_error = state.error
+      # A peer reset may reject terminal delivery. Retain the handler failure
+      # independently of that later delivery error.
+      observe_stream_result(state, effective) if handler_error
+      context.send(:publish_headers, check: false)
+      emit_stream_terminal(bytes, output)
+      context.commit! unless handler_error
+      observe_stream_result(state, effective) unless handler_error
+    end
+
+    def stream_terminal_bytes(state, context)
+      trailers = stream_trailers(state.error, context)
+      Streaming.terminal_bytes(state.error, trailers, wire_limit: @terminal_wire_limit, limit: @terminal_limit)
+    end
+
+    def merge_stream_error_metadata(error, context)
+      return unless error && !context.response_metadata.frozen?
+
+      error.metadata.each do |key, values|
+        context.response_metadata[key] = (context.response_metadata[key] || []) + values
+      end
+    end
+
+    def stream_trailers(error, context)
+      trailers = Metadata.new(context.response_trailers)
+      error&.trailers&.each { |key, values| trailers[key] = (trailers[key] || []) + values }
+      context.response_trailers.freeze
+      trailers
+    end
+
+    def emit_stream_terminal(bytes, output)
+      framing = Streaming::Framing.new(input: nil, output: output, request: false,
+                                       limit: @response_limit, wire_limit: @response_wire_limit,
+                                       terminal_wire_limit: @terminal_wire_limit, terminal_limit: @terminal_limit)
+      framing.emit(bytes, terminal: true)
+    end
+
+    def observe_stream_result(state, effective)
+      context = state.context #: StreamingContext
+      state.lifecycle&.processing_finished(code: effective ? effective.code : "OK", error: state.error,
+                                           normalized_error: effective, http_status: 200,
+                                           response_metadata: Instrumentation.carrier(context.response_metadata))
+    end
+
+    def streaming_context(state, headers: state.headers)
+      metadata = Protocol.metadata(headers)
+      state.lifecycle.request_metadata = Instrumentation.carrier(metadata) if state.lifecycle
+      leading = ->(snapshot) { state.publish.call(stream_head(snapshot, state.codec, state.encoding)) }
+      StreamingContext.new(publish: leading, request_metadata: metadata, deadline: request_deadline(headers),
+                           cancellation: state.cancellation, lifecycle: state.lifecycle)
+    end
+
+    def stream_head(metadata, codec, encoding)
+      values = metadata.to_h.merge("content-type" => [Streaming::CONTENT_TYPES.fetch(codec)])
+      values["connect-content-encoding"] = ["gzip"] if encoding == :gzip
+      values["connect-accept-encoding"] = ["gzip, identity"] if @encoding == :gzip
+      StreamHead.new(status: 200, headers: values)
+    end
+  end
+end