connect_rpc_rails 0.1.0 → 0.2.0

data/lib/connect_rpc_rails/controller.rb

@@ -63,6 +63,9 @@ module ConnectRpcRails
     UNKNOWN_METHOD_ACTION = "connect_unknown_method"
     UNKNOWN_METHOD_PARAM = "connect_method"
 
+    # The request compression the transport accepts, advertised when a call uses another.
+    SUPPORTED_COMPRESSION = ["identity"].freeze #: Array[String]
+
     # The one `rescue_responses` entry that doesn't become a Connect error: #action_missing
     # raises ActionNotFound for a name that isn't an RPC, which means the app routed
     # something to an action this controller doesn't have. That is a misconfiguration for
@@ -85,7 +88,7 @@ module ConnectRpcRails
       # Registered first, so both the Error handler and anything `map_connect_errors` adds
       # later take precedence: Rails picks the most recently registered matching handler.
       install_rescue_response_defaults(base)
-      base.rescue_from(Error, with: :render_connect_error)
+      base.rescue_from(Error, with: :render_connect_exception)
       base.around_action(:enforce_connect_deadline)
       base.prepend_before_action(:validate_connect_request)
     end
@@ -102,7 +105,7 @@ module ConnectRpcRails
       ActionDispatch::ExceptionWrapper.rescue_responses.each_key do |class_name|
         next if RESCUE_RESPONSE_EXCLUSIONS.include?(class_name)
 
-        base.rescue_from(class_name, with: :render_rescue_response_error)
+        base.rescue_from(class_name, with: :render_connect_exception)
       end
     end
 
@@ -140,24 +143,26 @@ module ConnectRpcRails
       #: (Hash[Class, Symbol]) -> void
       def map_connect_errors(mapping)
         self.connect_error_mapping = connect_error_mapping.merge(mapping)
-        mapping.each_key { |klass| rescue_from(klass, with: :render_mapped_connect_error) }
+        mapping.each_key { |klass| rescue_from(klass, with: :render_connect_exception) }
       end
     end
 
     # Connect actions decode the body themselves and never read `params`, so skip
     # Rails' lazy body param parsing: it would deserialize a JSON body a second time
     # (instrumentation reads filtered_parameters) and leak request payloads into
-    # logs. Query params still parse; instrumentation is otherwise unaffected.
-    # Runs before instrumentation reads the params, so it decodes the Connect body
-    # here (exactly once) and reuses it two ways: the typed message drives the action,
-    # and its hash form populates `request_parameters` — so the standard Rails request
-    # log, `config.filter_parameters`, and APM see the request without Rails parsing
-    # the body a second time. Also reports the wire format for logs/instrumentation
-    # (via the formats header rather than `request.format=`, which would inject a
-    # :format key into params).
+    # logs. Query params other than a GET's Connect parameters still parse; instrumentation
+    # is otherwise unaffected.
+    # Runs before instrumentation reads the params, so it decodes the Connect message (a
+    # POST's body, a GET's `message`) here, exactly once, and reuses it two ways: the
+    # typed message drives the action, and its hash form populates `request_parameters`
+    # — so the standard Rails request log, `config.filter_parameters`, and APM see the
+    # request without Rails parsing it a second time. Also reports the wire format for
+    # logs/instrumentation (via the formats header rather than `request.format=`, which
+    # would inject a :format key into params).
     def process_action(*)
       request.request_parameters = connect_request_params
-      format = request.content_type.to_s.start_with?("application/proto") ? :proto : :json
+      exclude_connect_query_parameters if connect_get?
+      format = Codec::Proto == connect_requested_codec ? :proto : :json
       request.set_header("action_dispatch.request.formats", [Mime[format]])
       super
     end
@@ -212,16 +217,18 @@ module ConnectRpcRails
 
       @connect_full_method = "#{self.class.connect_registration.service_name}/#{rpc.name}"
 
-      # A Connect RPC is POST-only; other verbs are a 405, per the protocol. (Routes
-      # match all verbs so the wrong-verb case reaches here rather than 404-ing.)
-      return render(plain: "method not allowed", status: 405) unless request.post?
-      return render(plain: "unsupported media type", status: 415) unless Codec.for_content_type(request.content_type)
+      # A Connect RPC takes POST, and GET too when it is unary with no side effects; other
+      # verbs are a 405, per the protocol. (Routes match all verbs so the wrong-verb case reaches here
+      # rather than 404-ing.) HTTP requires a 405 to name the verbs the resource takes.
+      unless request.post? || connect_get?
+        response.headers["allow"] = connect_get_allowed?(rpc) ? "GET, POST" : "POST"
+        return render(plain: "method not allowed", status: 405)
+      end
+      return render(plain: "unsupported media type", status: 415) unless connect_requested_codec
 
       reject_unsupported_encoding
-      # A raw ParseError isn't a ConnectRpcRails::Error, so it would escape rescue_from and
-      # become a 500. A malformed body is client input: surface it as invalid_argument.
-      # (Don't echo the decoder message — it can quote payload fragments back.)
-      raise Error.new(:invalid_argument, "invalid request body") if @connect_decode_error
+      reject_unsupported_protocol_version if connect_get?
+      raise @connect_decode_error if @connect_decode_error
     end
 
     #: () -> String
@@ -231,20 +238,65 @@ module ConnectRpcRails
 
     private def connect_request_params
       rpc = self.class.connect_rpcs[action_name]
-      codec = Codec.for_content_type(request.content_type)
-      return {} unless request.post? && rpc && codec
+      codec = connect_requested_codec
+      return {} unless (request.post? || connect_get?) && rpc && codec
 
-      # Rack 3.1 lets a server omit rack.input for an empty body (Falcon does), and an
-      # empty message encodes to an empty proto body.
-      @connect_request = codec.decode(rpc.input_class, request.body&.read || "")
+      @connect_request = codec.decode(rpc.input_class, connect_request_bytes)
       @connect_request.to_h
-    rescue Google::Protobuf::ParseError => e
-      # Defer a malformed body to the action, so it flows through instrumentation and
-      # the normal error path instead of aborting before the request is even logged.
-      @connect_decode_error = e
+    rescue Google::Protobuf::ParseError
+      # Deferred to the action, so a malformed message flows through instrumentation and the
+      # normal error path. The decoder's message is not sent: it can quote the payload back.
+      @connect_decode_error = Error.new(
+        :invalid_argument,
+        connect_get? ? "invalid message query parameter" : "invalid request body",
+      )
+      {}
+    rescue GetQuery::InvalidMessage => e
+      @connect_decode_error = Error.new(:invalid_argument, e.message)
       {}
     end
 
+    # The serialized request message: the body of a POST, the `message` parameter of a GET.
+    #: () -> String
+    private def connect_request_bytes
+      return connect_get_query.message if connect_get?
+
+      # Rack 3.1 lets a server omit rack.input for an empty body (Falcon does), and an
+      # empty message encodes to an empty proto body.
+      request.body&.read || ""
+    end
+
+    # Connect serves an RPC over GET only when it is unary and its `.proto` declares it free of
+    # side effects.
+    #: (ServiceRegistration::Rpc) -> bool
+    private def connect_get_allowed?(rpc)
+      !rpc.streaming && rpc.idempotency_level == :NO_SIDE_EFFECTS
+    end
+
+    # Whether this call is a Connect GET, which carries its request in the query string.
+    #: () -> bool
+    private def connect_get?
+      rpc = self.class.connect_rpcs[action_name]
+      !rpc.nil? && request.get? && connect_get_allowed?(rpc)
+    end
+
+    #: () -> GetQuery
+    private def connect_get_query
+      @connect_get_query ||= GetQuery.parse(request.query_string)
+    end
+
+    # A GET's query parameters are its request, which `request_parameters` already holds
+    # decoded, so `params` shows the message once. A query Rails refuses, such as a binary
+    # message sent without base64, keeps no parameters.
+    private def exclude_connect_query_parameters
+      query = begin
+        request.query_parameters.except(*GetQuery::PARAMS)
+      rescue ActionController::BadRequest
+        {} #: Hash[String, untyped]
+      end
+      request.set_header("action_dispatch.request.query_parameters", query)
+    end
+
     # The transport preconditions have all passed by the time this runs (see
     # #validate_connect_request), so this is the wire round-trip and nothing else. The RPC
     # runs on this controller instance — the one Rails built for this request — and takes
@@ -260,22 +312,45 @@ module ConnectRpcRails
       response.headers["content-type"] = connect_codec.content_type
     end
 
-    # The codec for this call's content-type. Never missing once the action runs:
-    # #validate_connect_request answers a content-type no codec handles with a 415.
+    # The codec for this call. Never missing once the action runs: #validate_connect_request
+    # answers a codec it has none for with a 415.
     #: () -> Codec::_Codec
     private def connect_codec
-      Codec.for_content_type(request.content_type) ||
-        raise(Error.new(:internal, "no codec for #{request.content_type}"))
+      connect_requested_codec || raise(Error.new(:internal, "no codec for this request"))
     end
 
-    # Connect rejects unsupported request compression with `unimplemented`, advertising
-    # what it can accept.
+    # The codec the caller named: a GET's `encoding` parameter, a POST's content-type. Nil
+    # when no codec handles it.
+    #: () -> Codec::_Codec?
+    private def connect_requested_codec
+      return Codec.for_name(connect_get_query.encoding) if connect_get?
+
+      Codec.for_content_type(request.content_type)
+    end
+
+    # Connect rejects unsupported request compression with `unimplemented`, naming what it
+    # can accept in both `accept-encoding` and the message. A GET names its compression in
+    # the query.
     private def reject_unsupported_encoding
-      encoding = request.headers["Content-Encoding"]
-      return if encoding.nil? || ["", "identity"].include?(encoding)
+      source, encoding = if connect_get?
+        ["compression", connect_get_query.compression]
+      else
+        ["content-encoding", request.headers["Content-Encoding"]]
+      end
+      return if encoding.nil? || encoding.empty? || SUPPORTED_COMPRESSION.include?(encoding)
 
-      response.headers["accept-encoding"] = "identity"
-      raise Error.new(:unimplemented, "unsupported content-encoding: #{encoding}")
+      supported = SUPPORTED_COMPRESSION.join(", ")
+      response.headers["accept-encoding"] = supported
+      raise Error.new(:unimplemented, "unsupported #{source} #{encoding.inspect}: supported encodings are #{supported}")
+    end
+
+    # `connect=v1` is optional, as the protocol lets a server accept a GET without it. Any
+    # other version is a revision of the protocol this server does not speak.
+    private def reject_unsupported_protocol_version
+      version = connect_get_query.connect
+      return if version.nil? || ["", GetQuery::PROTOCOL_VERSION].include?(version)
+
+      raise Error.new(:invalid_argument, "connect query parameter must be #{GetQuery::PROTOCOL_VERSION}")
     end
 
     # The decoded request message, for the action to read the way an HTTP action reads
@@ -355,32 +430,37 @@ module ConnectRpcRails
       end
     end
 
-    # The handler `map_connect_errors` installs: the mapping lives on the class, so the
-    # code for the exception at hand is looked up rather than baked into a closure.
-    private def render_mapped_connect_error(exception)
+    # The handler every `rescue_from` the library installs points at.
+    private def render_connect_exception(exception)
+      render_connect_error(connect_error_for(exception))
+    end
+
+    # The Connect error to send for a rescued exception. Override to add details every
+    # error should carry, the way ExceptionsApp#connect_error_for is overridden for errors
+    # that escape the controller.
+    #
+    # A mapped exception takes its code from `map_connect_errors`, which overrides the
+    # `rescue_responses` classification. That status is read off the nearest ancestor the
+    # registry names, since `rescue_from` matches subclasses too and a subclass isn't a key
+    # (an `ActiveRecord::RecordNotUnique` is classified as the `StatementInvalid` it
+    # descends from). Read with `fetch`, because the registry answers anything at all with
+    # a default of :internal_server_error — which would stop the walk on the first ancestor
+    # and call every subclass a 500.
+    #: (Exception) -> Error
+    private def connect_error_for(exception)
+      return exception if exception.is_a?(Error)
+
       _, code = self.class.connect_error_mapping.find { |klass, _| exception.is_a?(klass) }
-      # Only classes in the mapping are rescued, so this can't miss; re-raise rather than
-      # invent a code if it somehow does.
+      unless code
+        responses = ActionDispatch::ExceptionWrapper.rescue_responses
+        status = exception.class.ancestors.lazy.filter_map { |klass| responses.fetch(klass.name, nil) }.first
+        code = Error.code_for_http_status(Rack::Utils.status_code(status)) if status
+      end
+      # Only mapped or classified exceptions are rescued, so this can't miss; re-raise
+      # rather than invent a code if it somehow does.
       raise exception unless code
 
-      render_connect_error(Error.new(code, exception.message))
-    end
-
-    # The handler installed for every `rescue_responses` entry. The status is read off the
-    # nearest ancestor the registry names, since `rescue_from` matches subclasses too and a
-    # subclass isn't a key (an `ActiveRecord::RecordNotUnique` is classified as the
-    # `StatementInvalid` it descends from). Read with `fetch`, because the registry answers
-    # anything at all with a default of :internal_server_error — which would stop the walk
-    # on the first ancestor and call every subclass a 500.
-    private def render_rescue_response_error(exception)
-      responses = ActionDispatch::ExceptionWrapper.rescue_responses
-      status = exception.class.ancestors.lazy.filter_map { |klass| responses.fetch(klass.name, nil) }.first
-      # Only registered names are rescued here, so this can't miss; re-raise rather than
-      # invent a code if it somehow does.
-      raise exception unless status
-
-      code = Error.code_for_http_status(Rack::Utils.status_code(status))
-      render_connect_error(Error.new(code, exception.message))
+      Error.new(code, exception.message)
     end
 
     private def render_connect_error(error)

data/lib/connect_rpc_rails/exceptions_app.rb

@@ -14,8 +14,9 @@ module ConnectRpcRails
   #
   #   config.exceptions_app = ConnectRpcRails::ExceptionsApp.new(MyExceptions.new(Rails.public_path))
   #
-  # A Connect request is recognized by `connect-protocol-version`, which the protocol
-  # requires on every unary call; anything else reaches the wrapped app untouched.
+  # A Connect request is recognized by the `connect-protocol-version` header Connect clients
+  # send on a unary POST, or by the `connect=v1` query parameter they send on a GET; anything
+  # else reaches the wrapped app untouched.
   class ExceptionsApp
     # `connect-protocol-version`, as Rack names it in the env.
     PROTOCOL_VERSION_HEADER = "HTTP_CONNECT_PROTOCOL_VERSION"
@@ -28,11 +29,20 @@ module ConnectRpcRails
     #: (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
     def call(env)
       exception = env["action_dispatch.exception"]
-      return @app.call(env) unless exception && env[PROTOCOL_VERSION_HEADER]
+      return @app.call(env) unless exception && connect_request?(env)
 
       render_connect_error(connect_error_for(exception, env))
     end
 
+    #: (Hash[String, untyped]) -> bool
+    private def connect_request?(env)
+      return true if env[PROTOCOL_VERSION_HEADER]
+
+      # ActionDispatch::ShowExceptions turns every request into a GET before calling this app.
+      method = env.fetch("action_dispatch.original_request_method") { env["REQUEST_METHOD"] }
+      method == "GET" && GetQuery.parse(env["QUERY_STRING"].to_s).connect == GetQuery::PROTOCOL_VERSION
+    end
+
     # The error to send for an escaped exception. The message is the status's own text,
     # never the exception's, which can quote internals. Override in a subclass to add
     # details every error should carry.

data/lib/connect_rpc_rails/get_query.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 IVRy Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require "base64"
+require "uri"
+
+module ConnectRpcRails
+  # The query string of a Connect unary GET, which carries the codec, compression and message
+  # a POST sends as headers and body:
+  #
+  #   GET /greet.v1.GreetService/SayHello?connect=v1&encoding=json&message=%7B%22name%22%3A%22Ada%22%7D
+  class GetQuery
+    # The parameters the protocol defines. Any other parameter is allowed and ignored.
+    PARAMS = ["connect", "base64", "compression", "encoding", "message"].freeze #: Array[String]
+
+    # The `connect` value Connect clients send, the GET counterpart of `connect-protocol-version: 1`.
+    PROTOCOL_VERSION = "v1" #: String
+
+    # The RFC 4648 §5 alphabet. Base64.urlsafe_decode64 checks the padding and the length, but
+    # also takes "+" and "/" from the standard alphabet.
+    URL_SAFE_BASE64 = /\A[A-Za-z0-9_-]*={0,2}\z/ #: Regexp
+
+    # Raised when the `message` parameter is missing or is not the base64 it claims to be.
+    class InvalidMessage < StandardError; end
+
+    # Each parameter takes its first value. An invalid percent-escape is kept as written, as
+    # URI.decode_www_form does, so it fails as an unknown value rather than being dropped. The
+    # query is decoded as binary, because decoding as UTF-8 scrubs the bytes of an unencoded
+    # binary message; values are then tagged UTF-8 without being checked.
+    #: (String) -> GetQuery
+    def self.parse(query_string)
+      params = {} #: Hash[String, String]
+      URI.decode_www_form(query_string, Encoding::BINARY).each do |key, value|
+        key = key.force_encoding(Encoding::UTF_8)
+        params[key] = value.force_encoding(Encoding::UTF_8) if PARAMS.include?(key) && !params.key?(key)
+      end
+      new(params)
+    end
+
+    #: (Hash[String, String]) -> void
+    def initialize(params)
+      @params = params
+    end
+
+    #: () -> String?
+    def connect = @params["connect"]
+
+    #: () -> String?
+    def encoding = @params["encoding"]
+
+    #: () -> String?
+    def compression = @params["compression"]
+
+    # The `message` parameter's bytes. With `base64=1` it is URL-safe base64, padded or not;
+    # any other `base64` value is ignored, per the protocol.
+    #: () -> String
+    def message
+      message = @params["message"] || raise(InvalidMessage, "missing message query parameter")
+      return message unless @params["base64"] == "1"
+      raise InvalidMessage, "invalid message query parameter" unless URL_SAFE_BASE64.match?(message)
+
+      Base64.urlsafe_decode64(message)
+    rescue ArgumentError
+      raise InvalidMessage, "invalid message query parameter"
+    end
+  end
+end

data/lib/connect_rpc_rails/message_validatable.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 IVRy Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require "active_support/concern"
+require "google/protobuf/well_known_types"
+require "protovalidate"
+
+require "connect_rpc_rails"
+
+module ConnectRpcRails
+  # Checks a Connect request against the `buf.validate` rules of its message before the RPC
+  # runs, and answers a violation the way AIP-193 describes: `invalid_argument`, with a
+  # `google.rpc.BadRequest` naming each field.
+  #
+  #   class GreetController < ActionController::API
+  #     include ConnectRpcRails::Controller
+  #     include ConnectRpcRails::MessageValidatable
+  #     include BearerAuthentication
+  #     connect_service "greet.v1.GreetService"
+  #
+  #     def say_hello = ...
+  #   end
+  #
+  # Fields are named in the caller's encoding: `preferredLanguage` for a JSON request,
+  # `preferred_language` for a binary one. `google.rpc.BadRequest` is looked up in the
+  # descriptor pool rather than required, because googleapis belongs to the application: it
+  # generates `google/rpc/error_details.proto` alongside its own protos, or bundles
+  # googleapis-common-protos-types.
+  #
+  # A violation raises ViolationError, which the concern rescues into the Connect error
+  # #connect_error_for_violation builds. Override that method to answer differently. Opt a
+  # controller out with `skip_before_action :validate_connect_message!` at its top.
+  # @rbs module-self ActionController::API
+  # @rbs module-self Controller
+  module MessageValidatable
+    extend ActiveSupport::Concern
+
+    # Raised when `google.rpc.BadRequest` is not in the descriptor pool.
+    class MissingDescriptorError < StandardError; end
+
+    # Raised when a request breaks a rule its message declares.
+    class ViolationError < StandardError
+      # @return [Array<Protovalidate::Violation>]
+      attr_reader :violations #: Array[untyped]
+
+      # @return [Object] the request message the violations were found in
+      attr_reader :request_message #: untyped
+
+      #: (Array[untyped] violations, untyped request_message) -> void
+      def initialize(violations, request_message)
+        @violations = violations
+        @request_message = request_message
+        super(violations.map(&:to_s).join("; "))
+      end
+    end
+
+    BAD_REQUEST = "google.rpc.BadRequest" #: String
+
+    # AIP-193: a FieldViolation's reason is UPPER_SNAKE_CASE and at most 63 characters.
+    REASON_PATTERN = /\A[A-Z][A-Z0-9_]{1,61}[A-Z0-9]\z/ #: Regexp
+
+    # Published for a rule id that cannot be a reason, such as a CEL rule named in lowercase.
+    FALLBACK_REASON = "INVALID_VALUE" #: String
+
+    # `self` inside an ActiveSupport::Concern block is the including class, which RBS has no
+    # way to name.
+    # steep:ignore:start
+    included do
+      # Registered at include time so `skip_before_action` at the top of a controller has an
+      # entry to delete. .method_added moves it behind the callbacks declared after this.
+      before_action(:validate_connect_message!)
+      rescue_from(ViolationError, with: :render_connect_violation)
+    end
+
+    class_methods do
+      # Rails appends a re-registered callback to the end of the chain, so defining an RPC
+      # moves the validation behind the authentication a controller declares above it. An
+      # invalid request answered before an unauthenticated one would tell a caller what a valid
+      # request looks like. No entry means the controller skipped it, and it stays skipped.
+      def method_added(method_name)
+        super
+        return unless connect_rpcs&.key?(method_name.to_s)
+        return unless _process_action_callbacks.any? { |callback| callback.filter == :validate_connect_message! }
+
+        before_action(:validate_connect_message!)
+      end
+    end
+    # steep:ignore:end
+
+    # The violated field as `parts[0].part_name`, each segment resolved against the descriptor
+    # so it is spelled the way the caller's encoding spells it. Empty for a message-level rule.
+    #: (untyped path, untyped message_class, json_names: bool) -> String
+    def self.field_path(path, message_class, json_names:)
+      return "" if path.nil?
+
+      descriptor = message_class.descriptor
+      path.elements.map do |element|
+        field = descriptor&.lookup(element.field_name)
+        descriptor = field_message(field)
+        # A segment the descriptor cannot resolve keeps the violation's spelling, rather than
+        # being dropped and shifting the rest of the path.
+        name = if field.nil?
+          element.field_name
+        else
+          json_names ? field.json_name : field.name
+        end
+        "#{name}#{subscript(element)}"
+      end.join(".")
+    end
+
+    # The message a path continues into after this field: for a map, the value's type rather
+    # than the synthetic entry, because the key is the subscript and not a segment.
+    #: (untyped field) -> untyped
+    def self.field_message(field)
+      return unless field&.type == :message
+
+      entry = field.subtype
+      return entry unless entry.options.map_entry
+
+      value = entry.lookup("value")
+      value.type == :message ? value.subtype : nil
+    end
+
+    #: (untyped element) -> String
+    def self.subscript(element)
+      case element.subscript
+      when :index then "[#{element.index}]"
+      when :bool_key then "[#{element.bool_key}]"
+      when :int_key then "[#{element.int_key}]"
+      when :uint_key then "[#{element.uint_key}]"
+      when :string_key then "[#{element.string_key.inspect}]"
+      else ""
+      end
+    end
+
+    # The rule id as a reason constant: `string.min_len` becomes `STRING_MIN_LEN`.
+    #: (String rule_id) -> String
+    def self.reason(rule_id)
+      reason = rule_id.upcase.tr(".", "_")
+      REASON_PATTERN.match?(reason) ? reason : FALLBACK_REASON
+    end
+
+    # A googleapis message class, looked up in the descriptor pool.
+    #: (String name) -> untyped
+    def self.googleapis_class(name)
+      descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(name)
+      if descriptor.nil?
+        raise MissingDescriptorError,
+          "#{name} is not in the descriptor pool; generate google/rpc/error_details.proto " \
+            "or bundle googleapis-common-protos-types"
+      end
+
+      descriptor.msgclass
+    end
+
+    private_class_method :field_message, :subscript
+
+    #: () -> void
+    private def validate_connect_message!
+      return unless self.class.connect_rpcs[action_name]
+
+      message = connect_request
+      return if message.nil?
+
+      # protovalidate's signatures are not loaded: see rbs_collection.yaml.
+      violations = Protovalidate.collect_violations(message) # steep:ignore
+      return if violations.empty?
+
+      raise ViolationError.new(violations, message)
+    end
+
+    # The Connect error a violation is answered with: `invalid_argument` with a
+    # `google.rpc.BadRequest`, naming each field the way this request's encoding spells it.
+    # Override to answer differently.
+    #: (ViolationError error) -> Error
+    private def connect_error_for_violation(error)
+      bad_request = MessageValidatable.googleapis_class(BAD_REQUEST)
+      field_violation = MessageValidatable.googleapis_class("#{BAD_REQUEST}.FieldViolation")
+      json_names = Codec::Json == connect_codec
+      field_violations = error.violations.map do |violation|
+        field_violation.new(
+          field: MessageValidatable.field_path(violation.field, error.request_message.class, json_names:),
+          reason: MessageValidatable.reason(violation.rule_id),
+          description: violation.message,
+        )
+      end
+      detail = field_violations.map { |v| v.field.empty? ? v.description : "#{v.field}: #{v.description}" }
+
+      Error.new(
+        :invalid_argument,
+        detail.join("; "),
+        details: [Google::Protobuf::Any.pack(bad_request.new(field_violations:))],
+      )
+    end
+
+    # Raised rather than only built, so the Connect error carries the violation as its cause for
+    # whatever reports it.
+    #: (ViolationError error) -> void
+    private def render_connect_violation(error)
+      raise connect_error_for_violation(error), cause: error
+    rescue Error => connect_error
+      render_connect_exception(connect_error)
+    end
+  end
+end

data/lib/connect_rpc_rails/protovalidate.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 IVRy Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# The protovalidate integration, required on its own because protovalidate is not a dependency
+# of connect_rpc_rails: a service that declares no buf.validate rules never loads it.
+#
+#   require "connect_rpc_rails/protovalidate"
+
+require "connect_rpc_rails/message_validatable"

data/lib/connect_rpc_rails/routing.rb

@@ -30,7 +30,7 @@ module ConnectRpcRails
   # service but not that method, so it is answered `unimplemented` the way a declared RPC
   # nobody implements always is.
   #
-  # Every RPC the descriptor declares becomes one `POST /<pkg.Service>/<Method>` route to
+  # Every RPC the descriptor declares becomes one `/<pkg.Service>/<Method>` route to
   # the action implementing it (1 RPC = 1 action), so the protobuf definition is the only
   # place the method list lives. A declared RPC the controller doesn't implement is
   # answered Connect `unimplemented` by the controller, not by a route. After the RPC

data/lib/connect_rpc_rails/service_registration.rb

@@ -5,6 +5,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require "google/protobuf"
+# MethodDescriptor#options decodes into MethodOptions, which generated code does not load.
+require "google/protobuf/descriptor_pb"
 
 module ConnectRpcRails
   # Reads a protobuf ServiceDescriptor (generated by protoc/buf and present in the
@@ -22,7 +24,9 @@ module ConnectRpcRails
   # so leftover instance state could leak between callers, whereas Rails builds a
   # controller per request.
   class ServiceRegistration
-    Rpc = Struct.new(:name, :action, :input_class, :output_class, keyword_init: true)
+    # `idempotency_level` is the method option's enum symbol: `:NO_SIDE_EFFECTS`, `:IDEMPOTENT`
+    # or `:IDEMPOTENCY_UNKNOWN`. `streaming` is true when either side of the RPC streams.
+    Rpc = Struct.new(:name, :action, :input_class, :output_class, :idempotency_level, :streaming, keyword_init: true)
 
     attr_reader :service_name #: String
 
@@ -39,6 +43,8 @@ module ConnectRpcRails
           action: action,
           input_class: method.input_type.msgclass,
           output_class: method.output_type.msgclass,
+          idempotency_level: method.options.idempotency_level,
+          streaming: method.client_streaming || method.server_streaming,
         )
       end
     end

data/lib/connect_rpc_rails/version.rb

@@ -5,5 +5,5 @@
 # SPDX-License-Identifier: Apache-2.0
 
 module ConnectRpcRails
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/connect_rpc_rails.rb

@@ -7,6 +7,7 @@
 require 'connect_rpc_rails/version'
 require 'connect_rpc_rails/errors'
 require 'connect_rpc_rails/codec'
+require 'connect_rpc_rails/get_query'
 require 'connect_rpc_rails/service_registration'
 require 'connect_rpc_rails/controller'
 require 'connect_rpc_rails/routing'