connect_rpc_rails 0.1.0

data/lib/connect_rpc_rails/routing.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 IVRy Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require "active_support/core_ext/string/inflections"
+
+module ConnectRpcRails
+  # Routes DSL for one Connect service, installed on the Rails routes mapper. The service
+  # is named as the `.proto` names it and mapped to a controller the way Rails' own `to:`
+  # names one — as a string, so drawing the routes doesn't load the controller class:
+  #
+  #   Rails.application.routes.draw do
+  #     connect_service "greet.v1.GreetService" => :greet
+  #   end
+  #
+  # A block maps the RPCs to a controller each, for a service whose methods are better off
+  # not sharing one class — an RPC then gets its own `before_action`s rather than callbacks
+  # the whole service runs with `only:`:
+  #
+  #   connect_service "greet.v1.GreetService" do
+  #     rpc "SayHello" => :greet_say_hello
+  #     rpc "SayGoodbye" => :greet_say_goodbye
+  #   end
+  #
+  # Every mapped name has to be one the descriptor declares, so a typo or a rename fails at
+  # boot rather than drawing a route nothing reaches. The mapping does not have to cover the
+  # service: an RPC left out is routed to the first mapped controller, which serves the
+  # 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
+  # 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
+  # routes comes one catch-all over the service prefix, which is where a method the
+  # descriptor never declared becomes a 404.
+  module Routing
+    # Whether the routed controllers can be resolved right now. Only under eager loading:
+    # Rails eager loads before it draws the routes, so the classes are already in memory
+    # and constantizing one autoloads nothing. With lazy loading (dev, and a plain Rack
+    # host) the class is deliberately left untouched.
+    #: () -> bool
+    def self.verify_controllers?
+      return false unless defined?(::Rails.application)
+
+      !!::Rails.application&.config&.eager_load
+    end
+
+    # Checks that each routed service resolves to a controller that actually serves it, so
+    # a service wired to the wrong controller fails at boot instead of 404-ing in
+    # production. Called as the routes are drawn (see .verify_controllers?).
+    #: (String, String) -> void
+    def self.verify_controller!(service_name, controller_path)
+      controller = "#{controller_path.camelize}Controller".constantize
+      registration = controller.connect_registration if controller.respond_to?(:connect_registration)
+      unless registration
+        raise ArgumentError, "#{controller} does not serve a Connect service: it needs `connect_service`"
+      end
+      unless registration.service_name == service_name
+        raise ArgumentError, "#{controller} serves #{registration.service_name}, not #{service_name}"
+      end
+    end
+
+    #: (Hash[String | Symbol, String | Symbol] | String | Symbol) ?{ (?MethodMapping) [self: MethodMapping] -> void } -> void
+    def connect_service(mapping, &block)
+      if block
+        unless mapping.is_a?(String) || mapping.is_a?(Symbol)
+          raise ArgumentError, "connect_service takes a service name with a block, not a controller mapping"
+        end
+
+        return Service.new(self, mapping.to_s, MethodMapping.collect(&block)).draw
+      end
+
+      unless mapping.is_a?(Hash)
+        raise ArgumentError, "connect_service takes a service-to-controller mapping, or a service name with a block"
+      end
+
+      mapping.each do |service_name, controller|
+        Service.new(self, service_name.to_s, controller.to_s).draw
+      end
+    end
+
+    # Collects the per-RPC controller mapping a `connect_service` block declares. `rpc`
+    # takes the method name as the `.proto` spells it, so both ends of the mapping grep to
+    # the protobuf definition.
+    class MethodMapping
+      #: () { (?MethodMapping) [self: MethodMapping] -> void } -> Hash[String, String]
+      def self.collect(&block)
+        collector = new
+        collector.instance_eval(&block)
+        collector.mapping
+      end
+
+      attr_reader :mapping #: Hash[String, String]
+
+      #: () -> void
+      def initialize
+        @mapping = {} #: Hash[String, String]
+      end
+
+      #: (Hash[String | Symbol, String | Symbol]) -> void
+      def rpc(mapping)
+        mapping.each { |name, controller| @mapping[name.to_s] = controller.to_s }
+      end
+    end
+
+    # Draws the routes for one service: every RPC the descriptor declares, then the
+    # catch-all. The RPCs go to one controller, or to the controller each is mapped to.
+    class Service
+      #: (untyped mapper, String service_name, String | Hash[String, String] controllers) -> void
+      def initialize(mapper, service_name, controllers)
+        @mapper = mapper
+        @controllers = controllers
+        @registration = ServiceRegistration.new(service_name)
+        verify_mapping! if controllers.is_a?(Hash)
+      end
+
+      #: () -> void
+      def draw
+        @registration.rpcs.each { |rpc| route(rpc.name, rpc.action, controller_for(rpc.name)) }
+        # The catch-all renders a 404 and nothing else, which any controller serving the
+        # service answers identically, so it goes to the first one mapped.
+        route("*#{Controller::UNKNOWN_METHOD_PARAM}", Controller::UNKNOWN_METHOD_ACTION, controller_paths.first)
+
+        return unless Routing.verify_controllers?
+
+        controller_paths.each { |path| Routing.verify_controller!(@registration.service_name, path) }
+      end
+
+      # A mapping is checked against the descriptor as the routes are drawn: a controller
+      # mapped to a name the service does not declare is a typo or a rename, and it would
+      # otherwise draw a route nothing can reach. An RPC the block leaves out is *not* an
+      # error — it is routed too (see #controller_for), because a declared RPC nobody
+      # implements is what Connect answers `unimplemented`.
+      #: () -> void
+      private def verify_mapping!
+        raise ArgumentError, "#{@registration.service_name} is mapped to no controller" if @controllers.empty?
+
+        undeclared = @controllers.keys - @registration.rpcs.map(&:name)
+        return if undeclared.empty?
+
+        raise ArgumentError, "#{@registration.service_name} declares no RPC named #{undeclared.join(", ")}"
+      end
+
+      # An RPC the mapping leaves out still gets a route, at the first mapped controller:
+      # it serves the service but not that method, so #action_missing answers it
+      # `unimplemented` (501) exactly as the protocol wants — where no route at all would
+      # have made it a 404.
+      #: (String) -> String
+      private def controller_for(rpc_name)
+        return @controllers unless @controllers.is_a?(Hash)
+
+        @controllers.fetch(rpc_name) { controller_paths.first }
+      end
+
+      #: () -> Array[String]
+      private def controller_paths
+        @controllers.is_a?(Hash) ? @controllers.values.uniq : [@controllers]
+      end
+
+      # Routes match every verb (`via: :all`) so a wrong-verb request reaches the
+      # controller and becomes a Connect-correct 405 rather than a router 404.
+      # `format: false` keeps the dots in the service name from being parsed as a format
+      # suffix.
+      #: (String, String, String) -> void
+      private def route(path, action, controller_path)
+        @mapper.match(
+          "/#{@registration.service_name}/#{path}",
+          to: "#{controller_path}##{action}",
+          via: :all,
+          format: false,
+        )
+      end
+    end
+  end
+end

data/lib/connect_rpc_rails/service_registration.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 IVRy Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require "google/protobuf"
+
+module ConnectRpcRails
+  # Reads a protobuf ServiceDescriptor (generated by protoc/buf and present in the
+  # descriptor pool) into the RPC table the transport dispatches from. Dispatch is
+  # reflection-based: the action names and the input/output message classes come
+  # entirely from the descriptor, so no per-service code generation is required.
+  #
+  # The service is named the way the `.proto` names it — `"greet.v1.GreetService"` — and
+  # looked up in the pool, so the string in the code is greppable from the protobuf
+  # definition. A ServiceDescriptor is accepted too, for a host that already holds one.
+  #
+  # The service is implemented by the controller itself — the RPC methods are ordinary
+  # controller instance methods. There is deliberately no handler object: a handler held
+  # on the controller class would be one instance shared by every request in the process,
+  # 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)
+
+    attr_reader :service_name #: String
+
+    #: (String | untyped service) -> void
+    def initialize(service)
+      descriptor = service.is_a?(String) ? self.class.lookup!(service) : service
+      @service_name = descriptor.name
+      @rpcs = {} #: Hash[String, Rpc]
+
+      descriptor.each do |method|
+        action = ConnectRpcRails.underscore(method.name)
+        @rpcs[action] = Rpc.new(
+          name: method.name,
+          action: action,
+          input_class: method.input_type.msgclass,
+          output_class: method.output_type.msgclass,
+        )
+      end
+    end
+
+    # The generated `_pb` file has to have been required, since requiring it is what puts
+    # the service in the pool. Say so, rather than let a typo and a missing require look
+    # the same.
+    #: (String) -> untyped
+    def self.lookup!(service_name)
+      Google::Protobuf::DescriptorPool.generated_pool.lookup(service_name) ||
+        raise(ArgumentError, "no service #{service_name.inspect} in the descriptor pool: is its generated _pb file required?")
+    end
+
+    #: () -> Array[Rpc]
+    def rpcs
+      @rpcs.values
+    end
+  end
+end

data/lib/connect_rpc_rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 IVRy Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module ConnectRpcRails
+  VERSION = '0.1.0'
+end

data/lib/connect_rpc_rails.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 IVRy Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require 'connect_rpc_rails/version'
+require 'connect_rpc_rails/errors'
+require 'connect_rpc_rails/codec'
+require 'connect_rpc_rails/service_registration'
+require 'connect_rpc_rails/controller'
+require 'connect_rpc_rails/routing'
+require 'connect_rpc_rails/exceptions_app'
+
+module ConnectRpcRails
+  # Installs what the gem adds to Action Dispatch: the routes DSL, and Connect's binary
+  # content-type so `request.format` (and thus the instrumentation payload / request log)
+  # reports :proto instead of defaulting to :html. In a Rails app the Railtie calls this
+  # during boot; a plain Rack host (or a spec) calls it itself.
+  #: () -> void
+  def self.install!
+    require 'action_dispatch'
+
+    ActionDispatch::Routing::Mapper.include(Routing)
+    Mime::Type.register('application/proto', :proto) unless Mime[:proto]
+  end
+
+  # "SayHello" -> "say_hello". Maps a Connect method name to the controller action
+  # implementing it, so dispatch stays reflection-driven (no per-service codegen).
+  #: (String) -> String
+  def self.underscore(name)
+    name.to_s
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .downcase
+  end
+end
+
+require 'connect_rpc_rails/railtie' if defined?(Rails::Railtie)

data/sig/generated/connect_rpc_rails/codec.rbs

@@ -0,0 +1,44 @@
+# Generated from lib/connect_rpc_rails/codec.rb with RBS::Inline
+
+module ConnectRpcRails
+  # Encodes/decodes bare unary message bodies. Both codecs delegate to
+  # google-protobuf, so serialization is not something this library implements.
+  module Codec
+    interface _Codec
+      def decode: (untyped message_class, String bytes) -> untyped
+
+      def encode: (untyped message) -> String
+
+      def content_type: () -> String
+    end
+
+    # : (String?) -> _Codec?
+    def self.for_content_type: (String?) -> _Codec?
+
+    module Json
+      CONTENT_TYPE: String
+
+      # : (untyped, String) -> untyped
+      def self.decode: (untyped, String) -> untyped
+
+      # : (untyped) -> String
+      def self.encode: (untyped) -> String
+
+      # : () -> String
+      def self.content_type: () -> String
+    end
+
+    module Proto
+      CONTENT_TYPE: String
+
+      # : (untyped, String) -> untyped
+      def self.decode: (untyped, String) -> untyped
+
+      # : (untyped) -> String
+      def self.encode: (untyped) -> String
+
+      # : () -> String
+      def self.content_type: () -> String
+    end
+  end
+end

data/sig/generated/connect_rpc_rails/controller.rbs

@@ -0,0 +1,228 @@
+# Generated from lib/connect_rpc_rails/controller.rb with RBS::Inline
+
+module ConnectRpcRails
+  # Connect unary transport as an ActionController::API mix-in.
+  #
+  # Include this in an `ActionController::API` subclass and call `connect_service`:
+  # each RPC in the descriptor is one Rails *action* on that controller, so every call
+  # flows through the normal controller lifecycle. That is the whole point —
+  # `process_action.action_controller` fires, so the entire Rails observability
+  # ecosystem (Datadog resource naming, Sentry transactions, lograge, the
+  # "Completed 200 in Xms" request log) lights up for free. The transport wraps the
+  # action rather than generating it: decode the Connect body, call the action, encode the
+  # reply. Errors become Connect wire errors in one place (`rescue_from`), the deadline is
+  # one `around_action`.
+  #
+  #   class GreetController < ActionController::API
+  #     include ConnectRpcRails::Controller
+  #     include BearerAuthentication
+  #     connect_service "greet.v1.GreetService"
+  #
+  #     def say_hello
+  #       SayHelloResponse.new(greeting: "Hello, #{connect_request.name}!")
+  #     end
+  #   end
+  #
+  # An action takes no arguments, like every other Rails action: the decoded request is
+  # `connect_request`, read the way `params` is read in an HTTP controller. It is an
+  # ordinary instance method, so it gets the per-request instance Rails already builds for
+  # every action — nothing holding request state outlives the request. There is
+  # deliberately no handler object registered on the controller class: that one instance
+  # would be shared by every request in the process.
+  #
+  # A Connect call is an HTTP request, so cross-cutting concerns are Rails callbacks and
+  # nothing else: `before_action` for auth (writing an ivar, not a context bag),
+  # `around_action` to wrap a call, `rescue_from` (or `map_connect_errors`) to turn a
+  # domain exception into a Connect code. The decode happens before the callbacks run, so
+  # a `before_action` can already read `connect_request`. There is no interceptor layer:
+  # callbacks do the same job with `only:`/`except:`, inheritance and `skip_*` on top.
+  #
+  # Exceptions the host app already classifies need no mapping at all: Rails keeps that
+  # classification in `config.action_dispatch.rescue_responses`, which every railtie and
+  # gem registers into (`ActiveRecord::RecordNotFound` is `:not_found` there), so including
+  # this module installs a Connect code for each of those entries. `map_connect_errors` is
+  # for the ones Rails doesn't know about, and overrides these.
+  #
+  # Routes are 1 RPC = 1 action, drawn per service from the descriptor (see
+  # ConnectRpcRails::Routing). A declared RPC the controller doesn't implement is answered
+  # `unimplemented` by #action_missing; a method the descriptor never declared lands on the
+  # routes' catch-all, #connect_unknown_method, and is a 404. Routes match every verb, so a
+  # wrong-verb request does reach the controller and becomes a Connect-correct 405.
+  # @rbs module-self ActionController::API
+  # @rbs module-self _ConnectControllerSelf
+  module Controller : ActionController::API, _ConnectControllerSelf
+    # The action and path parameter the routes DSL points its per-service catch-all at.
+    UNKNOWN_METHOD_ACTION: ::String
+
+    UNKNOWN_METHOD_PARAM: ::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
+    # the host's error handling to surface, not a result to hand a caller.
+    RESCUE_RESPONSE_EXCLUSIONS: untyped
+
+    # Raised inside Timeout so it can't be confused with an unrelated Timeout::Error.
+    class DeadlineExceeded < StandardError
+    end
+
+    # : (untyped) -> void
+    def self.included: (untyped) -> void
+
+    # Gives every exception Rails already assigns an HTTP status a Connect code, so an app
+    # doesn't restate a mapping the framework ships. Registered by class *name*, which is
+    # both what `rescue_responses` is keyed by and what keeps this from loading the classes
+    # (`rescue_from` resolves the name when it has to rescue something).
+    #
+    # This reads `rescue_responses` once, when the controller is loaded — in a Rails app
+    # that is after the initializers have merged the app's own entries in.
+    # : (untyped) -> void
+    def self.install_rescue_response_defaults: (untyped) -> void
+
+    # @rbs module-self Module
+    # @rbs module-self _ConnectControllerClass
+    module ClassMethods : Module, _ConnectControllerClass
+      # Declares which Connect service this controller serves, named as the `.proto` names
+      # it: `connect_service "greet.v1.GreetService"`. The string is looked up in the
+      # descriptor pool, so it greps straight to the protobuf definition (and back).
+      #
+      # Subclasses inherit the declaration, so a service split across a controller per RPC
+      # declares it once on their shared base class.
+      # : (String | untyped service) -> void
+      def connect_service: (String | untyped service) -> void
+
+      # Turns domain exceptions into Connect errors for every RPC on the controller:
+      #
+      #   map_connect_errors MyDomain::Invalid => :invalid_argument,
+      #     MyDomain::QuotaReached => :resource_exhausted
+      #
+      # Only for exceptions Rails doesn't already classify — anything in
+      # `config.action_dispatch.rescue_responses` has a code without being named here (see
+      # .install_rescue_response_defaults) — or to override the code one of those got.
+      #
+      # This is `rescue_from` with the conversion filled in — each class gets its own
+      # handler, so nothing is blanket-rescued and an unmapped exception still propagates
+      # to the host's error middleware. The handler renders rather than re-raising because
+      # Rails calls one `rescue_from` handler per exception: an Error raised inside a
+      # handler would escape instead of reaching the one that renders the wire error.
+      # : (Hash[Class, Symbol]) -> void
+      def map_connect_errors: (Hash[Class, Symbol]) -> void
+    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).
+    def process_action: (*untyped) -> untyped
+
+    # The RPC method is the controller's own method, so the transport wraps dispatch
+    # instead of defining the action body: `send_action` is
+    # Rails' documented seam for "change how action methods are called".
+    private def send_action: (untyped action, *untyped args) -> untyped
+
+    # The service-prefix catch-all the routes DSL draws after the RPC routes. Every method
+    # the descriptor declares has its own route, so reaching here means this one isn't part
+    # of the service's contract at all: a 404 whatever the verb — rendered rather than
+    # raised as a RoutingError, so it doesn't depend on the host having Rails' exception
+    # middleware in the stack. No body is decoded for it either.
+    def connect_unknown_method: () -> untyped
+
+    # Every RPC the descriptor declares is routed, whether or not this controller has the
+    # method, because what the service serves is the descriptor's business and not the
+    # router's. A routed RPC with no action is exactly the case Connect answers
+    # `unimplemented`, and Rails' own hook for "this action doesn't exist" is where that is
+    # answered. An action name that isn't an RPC at all raises what Rails would have raised
+    # had this hook not been defined.
+    private def action_missing: (untyped name) -> untyped
+
+    # Transport preconditions, prepended so they run ahead of any application callback: a
+    # wrong verb or a body nothing can read is answered the way the protocol says instead
+    # of being handed to auth (or anything else the controller declared) first. Halting
+    # with `render` is Rails' own way to stop a callback chain.
+    private def validate_connect_request: () -> untyped
+
+    # : () -> String
+    private def connect_method_param: () -> String
+
+    private def connect_request_params: () -> untyped
+
+    # 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
+    # no arguments, like any other action. Only implemented methods are routed (the routes
+    # DSL checks that at boot), so there is no missing-method case.
+    private def dispatch_connect_rpc: (untyped rpc) -> untyped
+
+    # 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.
+    # : () -> Codec::_Codec
+    private def connect_codec: () -> Codec::_Codec
+
+    # Connect rejects unsupported request compression with `unimplemented`, advertising
+    # what it can accept.
+    private def reject_unsupported_encoding: () -> untyped
+
+    # The decoded request message, for the action to read the way an HTTP action reads
+    # `params`. Assigned during decode, so callbacks see it too.
+    # : () -> untyped
+    private def connect_request: () -> untyped
+
+    # Request metadata: the request's HTTP headers, downcased and dasherized, which is
+    # what Connect metadata is on the wire. Response metadata needs no helper — leading
+    # metadata is `response.headers`.
+    # : () -> Hash[String, String]
+    private def connect_metadata: () -> Hash[String, String]
+
+    # Trailing metadata to send. Unary Connect puts trailers in the response as
+    # `trailer-`-prefixed headers, so this collects them and #apply_connect_trailers does
+    # the prefixing — a caller writes `connect_trailers["x-audit"] = ["1"]` and doesn't
+    # encode the wire form itself.
+    # : () -> Hash[String, Array[String]]
+    private def connect_trailers: () -> Hash[String, Array[String]]
+
+    # Rack joins repeated headers with a newline, which is also how multi-value Connect
+    # metadata is sent.
+    private def apply_connect_trailers: () -> untyped
+
+    # The deadline this call must finish by, from `connect-timeout-ms`, or nil when the
+    # caller sent no timeout. The library enforces it; an RPC reads it to budget its own
+    # downstream calls.
+    # : () -> Time?
+    private def connect_deadline: () -> Time?
+
+    # : () -> Integer?
+    private def connect_timeout_ms: () -> Integer?
+
+    # Enforces connect-timeout-ms. Runs as an around_action so the whole action (the
+    # callbacks and the RPC) is under the deadline; the Error it raises is rendered by
+    # rescue_from.
+    # : () { (?) -> untyped } -> untyped
+    private def enforce_connect_deadline: () { (?) -> untyped } -> untyped
+
+    # 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: (untyped exception) -> untyped
+
+    # 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: (untyped exception) -> untyped
+
+    private def render_connect_error: (untyped error) -> untyped
+
+    # The official hook for enriching the process_action.action_controller payload
+    # (same mechanism lograge/Datadog custom fields use). Adds the fully-qualified
+    # Connect method so a trace/log resource can read "pkg.Service/Method".
+    private def append_info_to_payload: (untyped payload) -> untyped
+  end
+end

data/sig/generated/connect_rpc_rails/errors.rbs

@@ -0,0 +1,53 @@
+# Generated from lib/connect_rpc_rails/errors.rb with RBS::Inline
+
+module ConnectRpcRails
+  # A Connect protocol error. The code set and its HTTP status mapping are defined
+  # by the spec (https://connectrpc.com/docs/protocol/). Handlers raise these; the
+  # transport turns them into the wire error body.
+  class Error < StandardError
+    CODE_TO_HTTP_STATUS: Hash[Symbol, Integer]
+
+    # Rails keeps its exception taxonomy in HTTP statuses
+    # (`config.action_dispatch.rescue_responses`), so reusing it means reading a status back
+    # as a Connect code. This is the inverse of CODE_TO_HTTP_STATUS above — the same
+    # code↔status pairing `google.rpc.Code` defines, read the other way.
+    #
+    # It is *not* gRPC's HTTP-to-status mapping
+    # (https://grpc.github.io/grpc/core/md_doc_http-grpc-status-mapping.html), and Connect's
+    # equivalent table doesn't apply here either. Those describe a client reading an HTTP
+    # response that carries no RPC status at all — a proxy's 502, a load balancer's 404 —
+    # where 400 means "an intermediary rejected the request" (`internal`) and 404 means "no
+    # such service here" (`unimplemented`). Read that way round, a `RecordNotFound` would go
+    # out as `unimplemented`, colliding with the one thing that code means on this server: a
+    # routed RPC with no action. The table also stops at seven statuses and sends the rest to
+    # `unknown`, which is most of what Active Record raises (409, 422).
+    #
+    # Where several codes share a status, the entry is the one that fits what Rails raises
+    # there: 409 is `aborted` for a `StaleObjectError`'s lost race, not `already_exists`; 400
+    # is plain `invalid_argument`. Statuses no code claims (405, 406, 415, 422) take the
+    # nearest code by meaning.
+    HTTP_STATUS_TO_CODE: Hash[Integer, Symbol]
+
+    # The Connect code for an HTTP status. Statuses the table doesn't name fall back on
+    # their class, so a mapping Rails (or a gem) adds is never left without a code.
+    # : (Integer) -> Symbol
+    def self.code_for_http_status: (Integer) -> Symbol
+
+    attr_reader code: Symbol
+
+    attr_reader details: Array[untyped]
+
+    # : (Symbol, ?String?, ?details: Array[untyped]) -> void
+    def initialize: (Symbol, ?String?, ?details: Array[untyped]) -> void
+
+    # : () -> Integer
+    def http_status: () -> Integer
+
+    # : () -> Hash[Symbol, untyped]
+    def to_wire: () -> Hash[Symbol, untyped]
+
+    # A detail is a google.protobuf.Any; its Connect wire form is the bare message
+    # type name plus the serialized bytes as unpadded standard base64.
+    private def encode_detail: (untyped any) -> untyped
+  end
+end

data/sig/generated/connect_rpc_rails/exceptions_app.rbs

@@ -0,0 +1,33 @@
+# Generated from lib/connect_rpc_rails/exceptions_app.rb with RBS::Inline
+
+module ConnectRpcRails
+  # Wraps a Rails `config.exceptions_app` so an exception escaping a Connect call — one
+  # raised before dispatch, which no controller `rescue_from` ever sees — is still answered
+  # in the protocol's error shape.
+  #
+  #   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.
+  class ExceptionsApp
+    # `connect-protocol-version`, as Rack names it in the env.
+    PROTOCOL_VERSION_HEADER: ::String
+
+    # : (untyped app) -> void
+    def initialize: (untyped app) -> void
+
+    # : (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def call: (Hash[String, untyped]) -> [ Integer, Hash[String, String], Array[String] ]
+
+    # 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.
+    # : (Exception, Hash[String, untyped]) -> Error
+    private def connect_error_for: (Exception, Hash[String, untyped]) -> Error
+
+    # A unary Connect error is a JSON body whatever the request's codec was, per the
+    # protocol.
+    # : (Error) -> [Integer, Hash[String, String], Array[String]]
+    private def render_connect_error: (Error) -> [ Integer, Hash[String, String], Array[String] ]
+  end
+end

data/sig/generated/connect_rpc_rails/railtie.rbs

@@ -0,0 +1,10 @@
+# Generated from lib/connect_rpc_rails/railtie.rb with RBS::Inline
+
+module ConnectRpcRails
+  # Hooks the gem into a Rails app at the framework's own boot point rather than by
+  # patching Action Dispatch when the gem is required: the initializer runs once the
+  # frameworks are loaded and before the routes are drawn, which is all the routes DSL
+  # needs.
+  class Railtie < ::Rails::Railtie
+  end
+end