connect_rpc_rails 0.1.0 → 0.2.0

data/sig/generated/connect_rpc_rails/codec.rbs

@@ -15,6 +15,10 @@ module ConnectRpcRails
     # : (String?) -> _Codec?
     def self.for_content_type: (String?) -> _Codec?
 
+    # The codec a Connect GET names in its `encoding` query parameter.
+    # : (String?) -> _Codec?
+    def self.for_name: (String?) -> _Codec?
+
     module Json
       CONTENT_TYPE: String
 

data/sig/generated/connect_rpc_rails/controller.rbs

@@ -56,6 +56,9 @@ module ConnectRpcRails
 
     UNKNOWN_METHOD_PARAM: ::String
 
+    # The request compression the transport accepts, advertised when a call uses another.
+    SUPPORTED_COMPRESSION: 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
@@ -112,14 +115,15 @@ module ConnectRpcRails
     # 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: (*untyped) -> untyped
 
     # The RPC method is the controller's own method, so the transport wraps dispatch
@@ -153,6 +157,27 @@ module ConnectRpcRails
 
     private def connect_request_params: () -> untyped
 
+    # The serialized request message: the body of a POST, the `message` parameter of a GET.
+    # : () -> String
+    private def connect_request_bytes: () -> String
+
+    # 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?: (ServiceRegistration::Rpc) -> bool
+
+    # Whether this call is a Connect GET, which carries its request in the query string.
+    # : () -> bool
+    private def connect_get?: () -> bool
+
+    # : () -> GetQuery
+    private def connect_get_query: () -> GetQuery
+
+    # 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: () -> 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
@@ -160,15 +185,25 @@ module ConnectRpcRails
     # 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.
+    # 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::_Codec
 
-    # 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: () -> Codec::_Codec?
+
+    # 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: () -> untyped
 
+    # `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: () -> 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
@@ -206,17 +241,22 @@ module ConnectRpcRails
     # : () { (?) -> 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
+    # The handler every `rescue_from` the library installs points at.
+    private def render_connect_exception: (untyped exception) -> untyped
+
+    # 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) -> Error
 
     private def render_connect_error: (untyped error) -> untyped
 

data/sig/generated/connect_rpc_rails/exceptions_app.rbs

@@ -7,8 +7,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: ::String
@@ -19,6 +20,9 @@ module ConnectRpcRails
     # : (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
     def call: (Hash[String, untyped]) -> [ Integer, Hash[String, String], Array[String] ]
 
+    # : (Hash[String, untyped]) -> bool
+    private def connect_request?: (Hash[String, untyped]) -> bool
+
     # 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/sig/generated/connect_rpc_rails/get_query.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/connect_rpc_rails/get_query.rb with RBS::Inline
+
+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: Array[String]
+
+    # The `connect` value Connect clients send, the GET counterpart of `connect-protocol-version: 1`.
+    PROTOCOL_VERSION: 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: 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: (String) -> GetQuery
+
+    # : (Hash[String, String]) -> void
+    def initialize: (Hash[String, String]) -> void
+
+    # : () -> String?
+    def connect: () -> String?
+
+    # : () -> String?
+    def encoding: () -> String?
+
+    # : () -> String?
+    def compression: () -> String?
+
+    # 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: () -> String
+  end
+end

data/sig/generated/connect_rpc_rails/message_validatable.rbs

@@ -0,0 +1,96 @@
+# Generated from lib/connect_rpc_rails/message_validatable.rb with RBS::Inline
+
+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 : ActionController::API, Controller
+    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: (Array[untyped] violations, untyped request_message) -> void
+    end
+
+    BAD_REQUEST: String
+
+    # AIP-193: a FieldViolation's reason is UPPER_SNAKE_CASE and at most 63 characters.
+    REASON_PATTERN: Regexp
+
+    # Published for a rule id that cannot be a reason, such as a CEL rule named in lowercase.
+    FALLBACK_REASON: String
+
+    # 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: (untyped method_name) -> untyped
+
+    # 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: (untyped path, untyped message_class, json_names: bool) -> String
+
+    # 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: (untyped field) -> untyped
+
+    # : (untyped element) -> String
+    def self.subscript: (untyped element) -> String
+
+    # The rule id as a reason constant: `string.min_len` becomes `STRING_MIN_LEN`.
+    # : (String rule_id) -> String
+    def self.reason: (String rule_id) -> String
+
+    # A googleapis message class, looked up in the descriptor pool.
+    # : (String name) -> untyped
+    def self.googleapis_class: (String name) -> untyped
+
+    # : () -> void
+    private def validate_connect_message!: () -> void
+
+    # 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: (ViolationError error) -> Error
+
+    # 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: (ViolationError error) -> void
+  end
+end

data/sig/generated/connect_rpc_rails/protovalidate.rbs

@@ -0,0 +1,2 @@
+# Generated from lib/connect_rpc_rails/protovalidate.rb with RBS::Inline
+

data/sig/generated/connect_rpc_rails/routing.rbs

@@ -24,7 +24,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/sig/generated/connect_rpc_rails/service_registration.rbs

@@ -16,6 +16,8 @@ module ConnectRpcRails
   # so leftover instance state could leak between callers, whereas Rails builds a
   # controller per request.
   class ServiceRegistration
+    # `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.
     class Rpc < Struct[untyped]
       attr_accessor name(): untyped
 
@@ -25,8 +27,12 @@ module ConnectRpcRails
 
       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
+      attr_accessor idempotency_level(): untyped
+
+      attr_accessor streaming(): untyped
+
+      def self.new: (?name: untyped, ?action: untyped, ?input_class: untyped, ?output_class: untyped, ?idempotency_level: untyped, ?streaming: untyped) -> instance
+                  | ({ ?name: untyped, ?action: untyped, ?input_class: untyped, ?output_class: untyped, ?idempotency_level: untyped, ?streaming: untyped }) -> instance
     end
 
     attr_reader service_name: String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: connect_rpc_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - IVRy Inc.
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +51,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.26'
+- !ruby/object:Gem::Dependency
+  name: googleapis-common-protos-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: protovalidate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.beta3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.beta3
 - !ruby/object:Gem::Dependency
   name: puma
   requirement: !ruby/object:Gem::Requirement
@@ -166,6 +208,9 @@ files:
 - lib/connect_rpc_rails/controller.rb
 - lib/connect_rpc_rails/errors.rb
 - lib/connect_rpc_rails/exceptions_app.rb
+- lib/connect_rpc_rails/get_query.rb
+- lib/connect_rpc_rails/message_validatable.rb
+- lib/connect_rpc_rails/protovalidate.rb
 - lib/connect_rpc_rails/railtie.rb
 - lib/connect_rpc_rails/routing.rb
 - lib/connect_rpc_rails/service_registration.rb
@@ -175,6 +220,9 @@ files:
 - 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/get_query.rbs
+- sig/generated/connect_rpc_rails/message_validatable.rbs
+- sig/generated/connect_rpc_rails/protovalidate.rbs
 - sig/generated/connect_rpc_rails/railtie.rbs
 - sig/generated/connect_rpc_rails/routing.rbs
 - sig/generated/connect_rpc_rails/service_registration.rbs