connect_rpc_rails 0.1.0

data/sig/generated/connect_rpc_rails/routing.rbs

@@ -0,0 +1,101 @@
+# Generated from lib/connect_rpc_rails/routing.rb with RBS::Inline
+
+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?: () -> bool
+
+    # 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!: (String, String) -> void
+
+    # : (Hash[String | Symbol, String | Symbol] | String | Symbol) ?{ (?MethodMapping) [self: MethodMapping] -> void } -> void
+    def connect_service: (Hash[String | Symbol, String | Symbol] | String | Symbol) ?{ (?MethodMapping) [self: MethodMapping] -> void } -> void
+
+    # 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: () { (?MethodMapping) [self: MethodMapping] -> void } -> Hash[String, String]
+
+      attr_reader mapping: Hash[String, String]
+
+      # : () -> void
+      def initialize: () -> void
+
+      # : (Hash[String | Symbol, String | Symbol]) -> void
+      def rpc: (Hash[String | Symbol, String | Symbol]) -> void
+    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: (untyped mapper, String service_name, String | Hash[String, String] controllers) -> void
+
+      # : () -> void
+      def draw: () -> void
+
+      # 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!: () -> void
+
+      # 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: (String) -> String
+
+      # : () -> Array[String]
+      private def controller_paths: () -> Array[String]
+
+      # 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: (String, String, String) -> void
+    end
+  end
+end

data/sig/generated/connect_rpc_rails/service_registration.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/connect_rpc_rails/service_registration.rb with RBS::Inline
+
+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
+    class Rpc < Struct[untyped]
+      attr_accessor name(): untyped
+
+      attr_accessor action(): untyped
+
+      attr_accessor input_class(): untyped
+
+      attr_accessor output_class(): untyped
+
+      def self.new: (?name: untyped, ?action: untyped, ?input_class: untyped, ?output_class: untyped) -> instance
+                  | ({ ?name: untyped, ?action: untyped, ?input_class: untyped, ?output_class: untyped }) -> instance
+    end
+
+    attr_reader service_name: String
+
+    # : (String | untyped service) -> void
+    def initialize: (String | untyped service) -> void
+
+    # 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!: (String) -> untyped
+
+    # : () -> Array[Rpc]
+    def rpcs: () -> Array[Rpc]
+  end
+end

data/sig/generated/connect_rpc_rails/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/connect_rpc_rails/version.rb with RBS::Inline
+
+module ConnectRpcRails
+  VERSION: ::String
+end

data/sig/generated/connect_rpc_rails.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/connect_rpc_rails.rb with RBS::Inline
+
+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!: () -> void
+
+  # "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: (String) -> String
+end

data/sig/manual/controller_self.rbs

@@ -0,0 +1,32 @@
+# The class-level state ConnectRpcRails::Controller installs via `extend ClassMethods`.
+# `self.class` on the including controller can't be typed from the module body alone,
+# so the mix-in declares this as part of its self-type.
+module ConnectRpcRails
+  interface _ConnectControllerClass
+    # class_attribute, so a base controller's declaration is readable from a subclass
+    # serving one RPC of the service.
+    def connect_registration: () -> ServiceRegistration
+
+    def connect_registration=: (ServiceRegistration) -> void
+
+    def connect_rpcs: () -> Hash[String, untyped]
+
+    def connect_rpcs=: (Hash[String, untyped]) -> void
+
+    def name: () -> String?
+
+    # ActiveSupport::Rescuable, and the class_attribute `map_connect_errors` stores its
+    # mapping in.
+    def rescue_from: (untyped, with: Symbol) -> void
+
+    def connect_error_mapping: () -> Hash[Class, Symbol]
+
+    def connect_error_mapping=: (Hash[Class, Symbol]) -> void
+  end
+
+  interface _ConnectControllerSelf
+    def class: () -> _ConnectControllerClass
+
+    def dispatch_connect_rpc: (ServiceRegistration::Rpc) -> void
+  end
+end

data/sig/manual/rails.rbs

@@ -0,0 +1,25 @@
+# The Rails APIs the gem touches that gem_rbs_collection's actionpack/activesupport
+# signatures don't declare. railties itself has no published signatures, so `Rails` and
+# `Rails::Railtie` are only stubbed there (activesupport's patch.rbs) as empty.
+module Rails
+  def self.application: () -> untyped
+
+  class Railtie
+    def self.initializer: (String, **untyped) ?{ (?untyped) -> void } -> void
+  end
+end
+
+module ActionDispatch
+  class ExceptionWrapper
+    # Keyed by exception class *name*, valued by an HTTP status (a Rack symbol or an
+    # integer). The Hash answers an unregistered name with :internal_server_error, so read
+    # it with `fetch` when a miss has to be distinguishable.
+    def self.rescue_responses: () -> Hash[String, Symbol | Integer]
+  end
+end
+
+module AbstractController
+  class ActionNotFound < StandardError
+    def initialize: (?String? message, ?untyped controller, ?String? action) -> void
+  end
+end

metadata

@@ -0,0 +1,210 @@
+--- !ruby/object:Gem::Specification
+name: connect_rpc_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- IVRy Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.26'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.26'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rbs-inline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-shopify
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: steep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Serves Connect unary RPCs as ordinary Rails controller actions, so every
+  call flows through the normal ActionController::API lifecycle and the Rails observability
+  stack works with no extra wiring.
+email:
+- arch@ivry.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/connect_rpc_rails.rb
+- lib/connect_rpc_rails/codec.rb
+- lib/connect_rpc_rails/controller.rb
+- lib/connect_rpc_rails/errors.rb
+- lib/connect_rpc_rails/exceptions_app.rb
+- lib/connect_rpc_rails/railtie.rb
+- lib/connect_rpc_rails/routing.rb
+- lib/connect_rpc_rails/service_registration.rb
+- lib/connect_rpc_rails/version.rb
+- sig/generated/connect_rpc_rails.rbs
+- sig/generated/connect_rpc_rails/codec.rbs
+- sig/generated/connect_rpc_rails/controller.rbs
+- sig/generated/connect_rpc_rails/errors.rbs
+- sig/generated/connect_rpc_rails/exceptions_app.rbs
+- sig/generated/connect_rpc_rails/railtie.rbs
+- sig/generated/connect_rpc_rails/routing.rbs
+- sig/generated/connect_rpc_rails/service_registration.rbs
+- sig/generated/connect_rpc_rails/version.rbs
+- sig/manual/controller_self.rbs
+- sig/manual/rails.rbs
+homepage: https://github.com/ivry-inc/connect_rpc_rails
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ivry-inc/connect_rpc_rails
+  source_code_uri: https://github.com/ivry-inc/connect_rpc_rails
+  changelog_uri: https://github.com/ivry-inc/connect_rpc_rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Minimal Connect RPC (unary) server for Rails, built on ActionController::API.
+test_files: []