connectrpc 0.1.0

data/lib/connectrpc/instrumentation.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  # Synchronous, fixed per-RPC callbacks. Subscribers never own the application yield.
+  class Instrumentation
+    # The fixed call contract names its declared RPC method explicitly.
+    Call = Data.define(:role, :protocol, :method, :server_address, :server_port, :carrier) # rubocop:disable Lint/DataDefineOverride
+    Outcome = Data.define(:code, :http_status, :error, :normalized_error, :duration,
+                          :request_bytes, :response_bytes, :request_metadata, :response_metadata)
+    Completion = Data.define(:outcome, :processing_state, :decision, :delivery, :error, :http_status, :duration)
+
+    Callbacks = Data.define(:attach, :detach, :processing_finished, :finished)
+    private_constant :Callbacks
+
+    class Callbacks
+      def self.discover(observer, bus)
+        new(attach: callback(observer, :attach, bus), detach: callback(observer, :detach, bus),
+            processing_finished: callback(observer, :processing_finished, bus),
+            finished: callback(observer, :finished, bus))
+      end
+
+      # Reflection ends here; only typed callback records reach lifecycle work.
+      def self.callback(observer, name, bus)
+        bus.safely { observer.public_method(name).to_proc if observer.respond_to?(name) }
+      end
+      private_class_method :callback
+    end
+
+    def initialize(subscribers:, on_error: nil)
+      @subscribers = subscribers.dup.freeze
+      @on_error = on_error
+    end
+
+    # Internal constructor shared by client processing and the server hosting SPI.
+    def start(owner:, role:, method:, carrier:, server_address: nil, server_port: nil, path: nil, protocol: :connect)
+      call = Call.new(role: role, protocol: protocol, method: method,
+                      server_address: server_address, server_port: server_port, carrier: carrier)
+      observers = @subscribers.filter_map { |subscriber| safely { subscriber.start(call) } }
+      Handle.new(self, owner, path, observers)
+    end
+
+    def safely
+      yield
+    rescue StandardError => e
+      begin
+        @on_error&.call(e)
+      rescue StandardError
+        nil
+      end
+      nil
+    end
+
+    # Defensive read-only snapshot. Extraction must not validate/reorder protocol work.
+    # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+    def self.carrier(headers) # rubocop:disable Metrics/CyclomaticComplexity
+      # @type var result: headers
+      # @type var empty: headers
+      empty = {}
+      values = headers.each_with_object(empty) do |(key, entries), result|
+        next unless key.is_a?(String)
+
+        # Preserve Array coercion; the split lets Steep resolve Kernel.Array on each arm.
+        entries = entries.is_a?(Array) ? entries : Array(entries) # rubocop:disable Style/RedundantSelfAssignmentBranch
+        next unless entries.all?(String)
+
+        (result[key.downcase] ||= []).concat(entries.map { |entry| entry.dup.freeze })
+      end
+      values.transform_values!(&:freeze).freeze
+    rescue StandardError
+      empty = {} #: headers
+      empty.freeze
+    end
+
+    class Handle # rubocop:disable Metrics/ClassLength
+      attr_reader :outcome
+      attr_accessor :request_bytes, :request_metadata, :code, :normalized_error
+
+      def initialize(bus, owner, path, observers)
+        @bus = bus
+        @owner = owner
+        @path = path
+        # Resolve the optional callback surface once per observer.
+        @observers = observers.map { |observer| Callbacks.discover(observer, @bus) }
+        @started_at = now
+        @processing_state = :not_started
+        request_metadata = {} #: headers
+        @request_metadata = request_metadata.freeze
+      end
+
+      # Keep the application yield and reverse unwind in one exception boundary.
+      def activate # rubocop:disable Metrics/MethodLength
+        return yield if @terminal
+
+        # @type var tokens: Array[[(^(Object?) -> void)?, Object?]]
+        tokens = []
+        begin
+          @observers.each do |callbacks|
+            next unless callbacks.attach
+
+            @bus.safely do
+              token = callbacks.attach.call
+              tokens << [callbacks.detach, token]
+            end
+          end
+          yield
+        ensure
+          detach_tokens(tokens)
+        end
+      end
+
+      # Hosts may finish before processing unwinds. The first delivery fact wins.
+      def finish(delivery:, error: nil, decision: :processed, http_status: nil)
+        return if @terminal || @pending
+
+        @pending = { delivery: delivery, error: error, decision: decision, http_status: http_status }
+        complete unless @processing_held || @processing_state == :running || @notifying_processing
+        nil
+      end
+
+      def host_rejected!
+        @host_rejected = true
+      end
+
+      def host_rejected? = !!@host_rejected
+
+      def record_failure(error)
+        @error ||= error
+        nil
+      end
+
+      # Internal, bound single-use processing entry. Hosts only activate and finish.
+      def begin_processing(owner, path = nil)
+        unless @owner.equal?(owner) && @path == path && @processing_state == :not_started && !@pending && !@terminal
+          raise ArgumentError, "Lifecycle belongs to another call or has already been used"
+        end
+
+        @processing_state = :running
+        @processing_at = now
+      end
+
+      # Prepare immutable facts; the original processor owns their final notification.
+      def processing_finished(code:, http_status: nil, normalized_error: nil, error: nil,
+                              response_bytes: nil, response_metadata: {})
+        record_failure(error) if error
+        processing_at = @processing_at #: Float
+        @outcome = Outcome.new(code: code, http_status: http_status, error: @error,
+                               normalized_error: normalized_error, duration: now - processing_at,
+                               request_bytes: @request_bytes, response_bytes: response_bytes,
+                               request_metadata: Instrumentation.carrier(@request_metadata),
+                               response_metadata: Instrumentation.carrier(response_metadata))
+        complete_processing unless @processing_held
+      end
+
+      private
+
+      def detach_tokens(tokens)
+        while (entry = tokens.pop)
+          detach, token = entry
+          @bus.safely { detach&.call(token) }
+        end
+        nil
+      ensure
+        # Only an escaping detach leaves tokens for this continuation.
+        detach_tokens(tokens) unless tokens.empty?
+      end
+
+      # Native hosts hold preparation through the original application's cleanup.
+      # Delivery can arrive meanwhile, but neither observer callback can run yet.
+      def with_processing_completion
+        @processing_held = true
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException -- Retain fatal cleanup failures without swallowing them.
+        record_failure(e)
+        raise
+      ensure
+        @processing_held = false
+        complete_processing if @outcome
+        complete if @pending && !@outcome && !@terminal
+      end
+
+      def complete_processing
+        return if @processing_state == :finished
+
+        prepared = @outcome #: Outcome
+        processing_at = @processing_at #: Float
+        outcome = @outcome = prepared.with(duration: now - processing_at, error: @error)
+        @processing_state = :finished
+        notify_processing(outcome)
+        nil
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def notify_processing(outcome)
+        @notifying_processing = true
+        @observers.each { |callbacks| @bus.safely { callbacks.processing_finished&.call(outcome) } }
+      ensure
+        @notifying_processing = false
+        complete if @pending
+      end
+
+      def notify_finished(completion)
+        @observers.each { |callbacks| @bus.safely { callbacks.finished&.call(completion) } }
+      end
+
+      def complete
+        @terminal = true
+        pending = @pending #: pending
+        completion = Completion.new(outcome: @outcome, processing_state: @processing_state,
+                                    duration: now - @started_at, delivery: pending[:delivery], error: pending[:error],
+                                    decision: pending[:decision], http_status: pending[:http_status])
+        notify_finished(completion)
+      end
+    end
+  end
+end

data/lib/connectrpc/message_io.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  # Bounded host-neutral input reader. A synchronous host still owns blocking I/O.
+  class MessageIO
+    def initialize(input, limit, context)
+      @input = input
+      @limit = limit
+      @context = context
+    end
+
+    def read(length)
+      raise Error.new(:resource_exhausted, "Message exceeds byte limit") if length && length > @limit
+
+      body = +"".b
+      read_chunks(body) if @input
+      @context.check!
+      raise Error.new(:invalid_argument, "Content-Length does not match body") if length && body.bytesize != length
+
+      body
+    end
+
+    private
+
+    def read_chunk(input, length)
+      input.read(length)
+    rescue StandardError => e
+      @context.record_failure(e)
+      @context.check!
+      raise
+    end
+
+    def read_chunks(body)
+      input = @input #: _Input
+      loop do
+        @context.check!
+        chunk = read_chunk(input, [16_384, @limit + 1 - body.bytesize].min)
+        @context.check!
+        break if chunk.nil? || chunk.empty?
+
+        raise Error.new(:resource_exhausted, "Message exceeds byte limit") if body.bytesize + chunk.bytesize > @limit
+
+        body << chunk
+      end
+    end
+  end
+end

data/lib/connectrpc/metadata.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  class Metadata
+    include Enumerable
+
+    RESERVED = %w[accept accept-encoding accept-post allow connection content-encoding content-length content-type
+                  expect host keep-alive proxy-authenticate proxy-authorization proxy-connection te trailer
+                  transfer-encoding upgrade].freeze
+
+    def self.reserved?(key)
+      RESERVED.include?(key) || key.start_with?("connect-", "trailer-", "grpc-")
+    end
+
+    def self.encode_binary(bytes)
+      [bytes].pack("m0").delete_suffix("==").delete_suffix("=")
+    end
+
+    def self.decode_binary(value)
+      raw = base64_payload(value)
+      # @type var bytes: String
+      bytes = (raw + ("=" * ((4 - (raw.size % 4)) % 4))).unpack1("m0") #: String
+      raise ArgumentError, "Noncanonical base64" unless encode_binary(bytes) == raw
+
+      bytes
+    end
+
+    def self.base64_payload(value)
+      raise ArgumentError, "Malformed base64" unless value.is_a?(String) && %r{\A[A-Za-z0-9+/]*={0,2}\z}.match?(value)
+
+      raw = value.delete_suffix("==").delete_suffix("=")
+      raise ArgumentError, "Malformed base64" if raw.size % 4 == 1
+      raise ArgumentError, "Malformed base64 padding" if value.include?("=") && value.size % 4 != 0
+
+      raw
+    end
+    private_class_method :base64_payload
+
+    def initialize(values = {})
+      @values = {}
+      values.each { |(key, entries)| self[key] = entries }
+    end
+
+    def [](key)
+      @values[key.downcase]&.dup
+    end
+
+    def []=(key, entries)
+      key = validate_key(key)
+      values = entries.is_a?(Array) ? entries : Array(entries)
+      @values[key] = values.map { |value| validate_value(value) }.freeze
+    end
+
+    def add(key, value)
+      self[key] = (self[key] || []) + [value]
+      self
+    end
+
+    def each(&block)
+      return @values.each unless block
+
+      @values.each(&block)
+    end
+
+    def freeze
+      @values.freeze
+      super
+    end
+
+    def to_h
+      @values.dup
+    end
+
+    def add_binary(key, bytes)
+      raise ArgumentError, "Binary metadata keys must end in -bin" unless key.end_with?("-bin")
+
+      add(key, self.class.encode_binary(bytes))
+    end
+
+    def binary(key)
+      (self[key] || []).flat_map do |value|
+        parts = value.empty? ? [""] : value.split(",", -1)
+        parts.map { |part| self.class.decode_binary(part.strip) }
+      end
+    end
+
+    private
+
+    def validate_key(key)
+      unless key.is_a?(String) && /\A[0-9A-Za-z_.-]+\z/.match?(key) && !self.class.reserved?(key.downcase)
+        raise ArgumentError, "Invalid or reserved metadata key"
+      end
+
+      key.downcase.freeze
+    end
+
+    def validate_value(value)
+      unless value.is_a?(String) && value.ascii_only? && /\A[\x20-\x7e]*\z/.match?(value)
+        raise ArgumentError, "Metadata values must be printable ASCII header strings"
+      end
+
+      value.dup.freeze
+    end
+  end
+end

data/lib/connectrpc/method.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  class Method
+    IDENTIFIER = /\A[A-Za-z_][A-Za-z_0-9]*\z/
+    QUALIFIED_NAME = /\A[A-Za-z_][A-Za-z_0-9]*(?:\.[A-Za-z_][A-Za-z_0-9]*)*\z/
+
+    attr_reader :service, :name, :request_type, :response_type, :path, :idempotency
+
+    def cardinality = :unary
+
+    def self.validate_name!(value, qualified: false)
+      pattern = qualified ? QUALIFIED_NAME : IDENTIFIER
+      raise ArgumentError, "Invalid protobuf name" unless value.is_a?(String) && pattern.match?(value)
+    end
+
+    # Validate and assign the immutable declaration together.
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    def initialize(service:, name:, request_type:, response_type:, cardinality: :unary, idempotency: :unknown)
+      raise ArgumentError, "Only unary methods are supported" unless cardinality == :unary
+
+      unless %i[unknown no_side_effects idempotent].include?(idempotency)
+        raise ArgumentError, "Invalid method idempotency"
+      end
+
+      self.class.validate_name!(service, qualified: true)
+      self.class.validate_name!(name)
+      raise ArgumentError, "Message types are required" if request_type.nil? || response_type.nil?
+
+      @idempotency = idempotency
+      @service = service.dup.freeze
+      @name = name.dup.freeze
+      @request_type = request_type
+      @response_type = response_type
+      @path = "/#{service}/#{name}".freeze
+      freeze
+    end
+  end
+
+  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+  class Service
+    attr_reader :name, :methods
+
+    def initialize(name:, methods:)
+      Method.validate_name!(name, qualified: true)
+      validate_methods!(name, methods)
+
+      @name = name.dup.freeze
+      @methods = methods.dup.freeze
+      freeze
+    end
+
+    private
+
+    def validate_methods!(name, methods)
+      unless methods.is_a?(Array) && methods.all? { |method| service_method?(method, name) }
+        raise ArgumentError, "Methods must belong to this service"
+      end
+      raise ArgumentError, "Duplicate methods" unless methods.map(&:name).uniq.size == methods.size
+    end
+
+    def service_method?(method, name)
+      [Method, ServerStreamMethod, ClientStreamMethod, BidiStreamMethod].any? { |type| method.is_a?(type) } &&
+        method.service == name
+    end
+  end
+end

data/lib/connectrpc/protocol.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ConnectRPC
+  TransportRequest = Struct.new(:url, :http_method, :headers, :body, :response_limit, :deadline, :lifecycle,
+                                :cancellation,
+                                keyword_init: true)
+  TransportResponse = Struct.new(:status, :headers, :body, keyword_init: true)
+  Response = Struct.new(:message, :metadata, :trailers, keyword_init: true)
+
+  module Protocol # rubocop:disable Metrics/ModuleLength
+    DEFAULT_LIMIT = 4 * 1024 * 1024
+    CONTENT_TYPES = { proto: "application/proto", json: "application/json" }.freeze
+
+    def self.limit!(value)
+      raise ArgumentError, "Message limits must be positive integers" unless value.is_a?(Integer) && value.positive?
+
+      value
+    end
+
+    def self.codec!(codec)
+      raise ArgumentError, "Supported codecs: proto, json" unless CONTENT_TYPES.key?(codec)
+
+      codec
+    end
+
+    def self.profile!(protocol, mode, encoding, server: false)
+      valid = server ? valid_server_protocol?(protocol) : %i[connect grpc].include?(protocol)
+      return if valid &&
+                mode == :unary && %i[identity gzip].include?(encoding)
+
+      raise ArgumentError, "Unsupported protocol, compatibility mode or encoding"
+    end
+
+    def self.valid_server_protocol?(protocol)
+      return true if %i[connect grpc grpc_web auto].include?(protocol)
+
+      protocol.is_a?(Array) && !protocol.empty? && protocol.uniq.size == protocol.size &&
+        protocol.all? { |value| %i[connect grpc grpc_web].include?(value) }
+    end
+
+    def self.server_protocols(protocol)
+      defaults = %i[connect grpc] #: Array[server_protocol]
+      return defaults.freeze if protocol == :auto
+
+      selected = protocol #: server_protocol | Array[server_protocol]
+      (selected.is_a?(Array) ? selected.dup : [selected]).freeze
+    end
+
+    def self.content_codec(value)
+      return :proto if value&.match?(%r{\Aapplication/proto\z}i)
+      return :json if value&.match?(%r{\Aapplication/json(?:\s*;\s*charset=(?:utf-8|"utf-8"))?\z}i)
+
+      nil
+    end
+
+    def self.headers(values)
+      result = {} #: headers
+      values.each_with_object(result) { |(key, entries), result| (result[key.downcase] ||= []).concat(Array(entries)) }
+    end
+
+    def self.single(headers, key)
+      entries = headers[key]
+      entries&.size == 1 ? entries.first : nil
+    end
+
+    def self.identity_encoding?(headers)
+      !headers.key?("content-encoding") || single(headers, "content-encoding")&.casecmp?("identity")
+    end
+
+    def self.content_encoding(headers)
+      return :identity unless headers.key?("content-encoding")
+
+      value = single(headers, "content-encoding")
+      return :identity if value&.casecmp?("identity")
+      return :gzip if value&.casecmp?("gzip")
+
+      nil
+    end
+
+    def self.accept_encoding!(value, encoding)
+      # @type var defaults: Array[encoding]
+      defaults = [encoding, :identity]
+      return defaults.uniq if value.nil?
+      unless value.is_a?(Array) && !value.empty? && value.uniq.size == value.size &&
+             value.all? { |entry| %i[identity gzip].include?(entry) }
+        raise ArgumentError, "Response encodings must be distinct identity/gzip symbols"
+      end
+
+      identity = [:identity] #: Array[encoding]
+      (value - identity) + identity
+    end
+
+    def self.response_encoding(headers, request_encoding, enabled)
+      return :identity unless enabled == :gzip
+      return request_encoding unless headers.key?("accept-encoding")
+
+      tokens = headers.fetch("accept-encoding").flat_map { |entry| entry.split(",") }
+      tokens.any? { |token| token.strip.casecmp?("gzip") } ? :gzip : :identity
+    end
+
+    def self.metadata(headers, trailers: false)
+      headers.each_with_object(Metadata.new) do |(key, entries), result|
+        if trailers
+          next unless key.start_with?("trailer-")
+
+          key = key.delete_prefix("trailer-")
+        end
+        next if Metadata.reserved?(key)
+
+        result[key] = entries
+      rescue ArgumentError
+        # HTTP permits names and values outside Connect's metadata contract.
+        # Omit the whole field while retaining adjacent valid metadata.
+        next
+      end
+    end
+
+    def self.check_size!(bytes, limit)
+      raise Error.new(:resource_exhausted, "Message exceeds byte limit") if bytes.bytesize > limit
+    end
+
+    def self.content_length!(entries, invalid_code:)
+      return unless entries
+      unless entries.size == 1 && /\A[0-9]{1,20}\z/.match?(entries.first)
+        raise Error.new(invalid_code, "Invalid Content-Length")
+      end
+
+      entries.first.to_i
+    end
+
+    def self.error_body(error, limit) # rubocop:disable Metrics/AbcSize
+      body = JSON.generate(error.to_h)
+      if body.bytesize <= limit
+        yield error, error.code if block_given?
+        return [body, error.http_status]
+      end
+
+      error = Error.new(:resource_exhausted, "Error exceeds byte limit")
+      body = JSON.generate(error.to_h)
+      emitted = body.bytesize <= limit
+      yield error, (error.code if emitted) if block_given?
+      [emitted ? body : "", error.http_status]
+    end
+
+    def self.parse_error(status, headers, body)
+      values = { metadata: metadata(headers), trailers: metadata(headers, trailers: true) }
+      if content_codec(single(headers, "content-type")) == :json
+        wire = wire_error(body, fallback: Error::HTTP_FALLBACK.fetch(status, "unknown"))
+        return Error.new(wire.fetch(:code), wire.fetch(:message), details: wire.fetch(:details), **values) if wire
+      end
+      Error.new(Error::HTTP_FALLBACK.fetch(status, "unknown"), "HTTP #{status}", **values)
+    end
+
+    def self.wire_error(body, fallback:)
+      # JSON.parse is the external data boundary; validate before assembling wire_error.
+      object = JSON.parse(body)
+      return unless valid_wire_error?(object)
+
+      code = Error::HTTP_STATUS.key?(object["code"]) ? object["code"] : fallback
+      # @type var details: Array[ErrorDetail]
+      details = []
+      { code: code, message: object.fetch("message", ""), details: wire_details(object.fetch("details", details)) }
+    rescue JSON::ParserError, ArgumentError, TypeError, EncodingError
+      # Invalid Connect error bodies use the protocol's HTTP fallback table.
+      nil
+    end
+
+    def self.valid_wire_error?(object)
+      return false unless object.is_a?(Hash)
+
+      code = object["code"]
+      message = object.fetch("message", "")
+      (code.nil? || (code.is_a?(String) && code.valid_encoding?)) &&
+        message.is_a?(String) && message.valid_encoding?
+    end
+
+    def self.wire_details(details)
+      raise ArgumentError unless details.is_a?(Array)
+
+      details.map do |detail|
+        raise ArgumentError unless detail.is_a?(Hash)
+
+        ErrorDetail.new(type: detail["type"], value: Metadata.decode_binary(detail["value"]))
+      end
+    end
+  end
+end