protobufable 0.1.0

data/sig/generated/protobufable/request_parseable.rbs

@@ -0,0 +1,131 @@
+# Generated from lib/protobufable/request_parseable.rb with RBS::Inline
+
+module Protobufable
+  # Parses a JSON request body straight into a generated protobuf message, so a wrong type or
+  # an unknown field is rejected before the action runs and the action reads a typed object
+  # instead of `params`.
+  #
+  # The declaration sits above the action it describes, like a signature:
+  #
+  # @example
+  #   class WidgetsController < ApplicationController
+  #     include Protobufable::RequestParseable
+  #
+  #     protobuf_body Api::CreateWidgetRequest
+  #     def create
+  #       Widget.create!(name: message.name)
+  #     end
+  #   end
+  #
+  # {RequestPatch} has to be prepended to `ActionDispatch::Request` for any of this to happen;
+  # {Protobufable.install!} does that, and the railtie calls it.
+  #
+  # @rbs module-self _RequestParseableSelf
+  module RequestParseable : _RequestParseableSelf
+    extend ActiveSupport::Concern
+
+    # What `protobuf_body` records about one action.
+    class Declaration < Data
+      attr_reader message_class(): untyped
+
+      attr_reader ignore_unknown_fields(): untyped
+
+      def self.new: (untyped message_class, untyped ignore_unknown_fields) -> instance
+                  | (message_class: untyped, ignore_unknown_fields: untyped) -> instance
+
+      def self.members: () -> [ :message_class, :ignore_unknown_fields ]
+
+      def members: () -> [ :message_class, :ignore_unknown_fields ]
+    end
+
+    # Holds the parsed message in `params` without letting it be logged.
+    #
+    # Rails' parameter filtering cannot see inside a protobuf message, so a message reaching
+    # the log formatter would print every field it holds, secrets included.
+    class MessageWrapper
+      # Stands in for the message wherever `params` is rendered.
+      FILTERED: String
+
+      # @param message [Object] the parsed protobuf message
+      # @return [void]
+      # : (untyped message) -> void
+      def initialize: (untyped message) -> void
+
+      # @return [Array] always empty, so `inspect` does not reach the message
+      # : () -> Array[Symbol]
+      def instance_variables_to_inspect: () -> Array[Symbol]
+
+      # The JSON log formatter renders payloads with ActiveSupport's `#to_json`, and
+      # `Object#as_json` falls back to dumping instance variables.
+      #
+      # @return [String] {FILTERED}
+      # : (*untyped) -> String
+      def as_json: (*untyped) -> String
+
+      # @return [Object] the wrapped message
+      # : () -> untyped
+      def to_protobuf: () -> untyped
+
+      # @return [Object] the wrapped message
+      # : () -> untyped
+      def to_original_message: () -> untyped
+    end
+
+    # Replaces the `:json` body parser so the body is decoded once, into the declared class,
+    # rather than parsed as JSON and then converted.
+    module RequestPatch
+      # : () -> Hash[Symbol, untyped]
+      private def params_parsers: () -> Hash[Symbol, untyped]
+    end
+
+    # Decodes the body for a request whose action declared a message class, and falls through
+    # to the original parser for every other request.
+    #
+    # The declaration is read off the controller class the request already resolves, rather
+    # than a process-wide table keyed by controller path: a table outlives reloads and renames,
+    # and cannot describe an anonymous controller at all.
+    #
+    # @param request [ActionDispatch::Request]
+    # @param raw_post [String] the request body
+    # @param original_parser [Proc] the parser this one stands in front of
+    # @return [Hash] the request parameters, carrying the message under `:_protobuf`
+    # : (untyped request, String raw_post, ^(String) -> untyped original_parser) -> untyped
+    def self.param_parser: (untyped request, String raw_post, ^(String) -> untyped original_parser) -> untyped
+
+    # @param request [ActionDispatch::Request]
+    # @return [Declaration, nil] what the routed action declared, if anything
+    # : (untyped request) -> Declaration?
+    def self.declaration_for: (untyped request) -> Declaration?
+
+    # Class-level DSL installed by including the concern.
+    #
+    # @rbs module-self _RequestParseableClass
+    module ClassMethods : _RequestParseableClass
+      # Declares the message class the next action accepts.
+      #
+      # @param message_class [Class] the generated request message class
+      # @param ignore_unknown_fields [Boolean] whether a field the schema does not declare is
+      #   dropped rather than rejected. False by default, so a client's typo is a 400 rather
+      #   than a value that silently never arrives.
+      # @return [void]
+      # : (Google::Protobuf::_MessageClass message_class, ?ignore_unknown_fields: bool) -> void
+      def protobuf_body: (Google::Protobuf::_MessageClass message_class, ?ignore_unknown_fields: bool) -> void
+
+      # Binds a pending `protobuf_body` to the action defined under it.
+      #
+      # @param method_name [Symbol]
+      # @return [void]
+      # : (Symbol method_name) -> void
+      def method_added: (Symbol method_name) -> void
+    end
+
+    # Reads the message from the parsed body only: `params` also holds the query string, where a
+    # `_protobuf` parameter would otherwise stand in for the message.
+    #
+    # @return [Object] the parsed message for this action
+    # @raise [KeyError] when the action declared no message class
+    # @raise [ActionDispatch::Http::Parameters::ParseError] when the request carried no JSON body
+    # : () -> untyped
+    def message: () -> untyped
+  end
+end

data/sig/generated/protobufable/request_validatable.rbs

@@ -0,0 +1,71 @@
+# Generated from lib/protobufable/request_validatable.rb with RBS::Inline
+
+module Protobufable
+  # Runs the `buf.validate` rules of a `protobuf_body` message before the action does.
+  #
+  # Decoding already rejects a wrong type; this adds what the rules declare — lengths, formats,
+  # ranges, cross-field conditions — so value validation lives in the schema next to the type
+  # rather than in the controller.
+  #
+  # @example
+  #   class WidgetsController < ApplicationController
+  #     include Protobufable::RequestValidatable
+  #
+  #     protobuf_body Api::CreateWidgetRequest
+  #     def create = ...
+  #   end
+  #
+  # Raises {InvalidMessage}, which carries the violations. Rescue it wherever the application
+  # turns errors into responses.
+  #
+  # @rbs module-self _RequestValidatableSelf
+  module RequestValidatable : _RequestValidatableSelf
+    extend ActiveSupport::Concern
+
+    include RequestParseable
+
+    # Raised when the request message breaks a rule its schema declares.
+    class InvalidMessage < Protobufable::Error
+      # @return [Array<Protovalidate::Violation>]
+      attr_reader violations: Array[untyped]
+
+      # @return [Class] the message the violations were produced from
+      attr_reader message_class: Google::Protobuf::_MessageClass
+
+      # @param violations [Array<Protovalidate::Violation>]
+      # @param message_class [Class]
+      # @return [void]
+      # : (Array[untyped] violations, Google::Protobuf::_MessageClass message_class) -> void
+      def initialize: (Array[untyped] violations, Google::Protobuf::_MessageClass message_class) -> void
+    end
+
+    # @rbs module-self _RequestValidatableClass
+    module ClassMethods : _RequestValidatableClass
+      # Re-registers the validation callback behind the action's own declaration.
+      #
+      # Rails appends a re-registered callback to the end of the chain. Without this, the
+      # callback stays where `included` put it — ahead of the authentication and authorization
+      # callbacks a controller declares afterwards — and an invalid body would be answered
+      # before an unauthenticated one, turning the endpoint into an oracle for what a valid
+      # body looks like.
+      #
+      # A controller that skipped the callback has no entry to move, and is left alone.
+      #
+      # @param method_name [Symbol]
+      # @return [void]
+      # : (Symbol method_name) -> void
+      def method_added: (Symbol method_name) -> void
+
+      # @return [Boolean] whether a `protobuf_body` is waiting to bind to the next action
+      # : () -> bool
+      def protobuf_body_pending?: () -> bool
+    end
+
+    # Validates the parsed message, if this action declared one.
+    #
+    # @return [void]
+    # @raise [InvalidMessage] when the message breaks a rule
+    # : () -> void
+    private def validate_protobuf_body!: () -> void
+  end
+end

data/sig/generated/protobufable/version.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/protobufable/version.rb with RBS::Inline
+
+module Protobufable
+  # The gem's version.
+  VERSION: String
+end

data/sig/generated/protobufable.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/protobufable.rb with RBS::Inline
+
+# Protocol Buffers as the schema of record for a Rails API: request bodies, stored columns,
+# error catalogues and responses all described by generated message classes.
+#
+# Each integration is required on its own, so a host pays only for what it uses:
+#
+#   require "protobufable/problem"        # needs the problem gem
+#   require "protobufable/protovalidate"  # needs the protovalidate gem
+#   require "protobufable/alba_binding"   # needs the alba gem
+module Protobufable
+  # Raised when a declaration cannot be honoured, such as an enum value the catalogue does not
+  # define or a serializer that has drifted from its message.
+  class Error < StandardError
+  end
+
+  # Registers the renderers and installs the request body parser. Called by the railtie on
+  # boot; a Rack host, or a spec that never boots Rails, calls it itself. Installing twice is
+  # harmless.
+  #
+  # @return [void]
+  # : () -> void
+  def self.install!: () -> void
+end

data/sig/manual/alba_binding.rbs

@@ -0,0 +1,29 @@
+# Alba ships no signatures and is not in ruby/gem_rbs_collection. Only what this gem touches
+# is declared, and the resource DSL stays untyped: it is Alba's to describe, not ours.
+module Alba
+  def self.register_type: (Symbol name, converter: untyped, ?auto_convert: bool) -> void
+
+  module Resource
+  end
+end
+
+module Protobufable
+  module AlbaBinding
+    # What an Alba resource instance supplies. A module self-type constrains includers, not the
+    # module itself, so it is spelled out here.
+    interface _AlbaBindingSelf
+      def class: () -> _AlbaBindingClass
+      def as_json: (*untyped) -> untyped
+    end
+
+    # The class side: the binding this installs, plus the parts of Class the DSL uses.
+    interface _AlbaBindingClass
+      def message_class: () -> Google::Protobuf::_MessageClass
+      def name: () -> String?
+      def module_eval: () { () -> void } -> untyped
+      def helper: (Module) -> void
+      def instance_variable_get: (Symbol) -> untyped
+      def class_eval: () { () -> void } -> untyped
+    end
+  end
+end

data/sig/manual/connect/problem_rescuable.rbs

@@ -0,0 +1,13 @@
+module Protobufable
+  module Connect
+    module ProblemRescuable
+      # What a controller including the concern supplies: ::Problem::Rescuable's needs, plus the
+      # renderer ConnectRpcRails::Controller defines.
+      interface _ProblemRescuableSelf
+        include ::Problem::_RescuableSelf
+
+        def render_connect_error: (::ConnectRpcRails::Error) -> untyped
+      end
+    end
+  end
+end

data/sig/manual/connect_rpc_rails.rbs

@@ -0,0 +1,9 @@
+# The part of connect_rpc_rails the Connect integration calls. Declared here rather than loaded
+# from the gem: see rbs_collection.yaml.
+module ConnectRpcRails
+  class Error < StandardError
+    def self.code_for_http_status: (Integer) -> Symbol
+
+    def initialize: (Symbol code, ?String? message, ?details: Array[untyped]) -> void
+  end
+end

data/sig/manual/problem/typeable.rbs

@@ -0,0 +1,28 @@
+module Protobufable
+  module Problem
+    module Typeable
+      # The class-level state Typeable installs, plus the parts of ::Problem::Detailable's
+      # DSL that Derivation reaches through `super` or reads to decide whether to. Declared by
+      # hand because `class_attribute` defines its accessors at runtime, and because a module
+      # self-type constrains includers rather than the module itself.
+      interface _TypeableClass
+        def name: () -> String?
+
+        def problem_type_value: () -> Symbol?
+        def problem_type_value=: (Symbol?) -> void
+
+        def problem_type: (?Symbol?) -> Symbol?
+        def problem_type_enum: () -> String
+        def problem_type_annotation: () -> String
+        def problem_uri_annotation: () -> String?
+        def problem_status_annotation: () -> String?
+        def problem_type_catalogue: () -> Hash[Symbol, Entry]
+        def problem_type_entry: () -> Entry
+
+        # Reached by Derivation, which decides between the catalogue and a literal declaration.
+        def problem_uri: () -> String?
+        def problem_status: () -> Integer?
+      end
+    end
+  end
+end

data/sig/manual/problem_details_pb.rbs

@@ -0,0 +1,12 @@
+module Protobufable
+  # Generated from proto/protobufable/problem_details.proto. Hand-written because the generation
+  # pipeline emits Ruby only; problem_details_spec.rb checks the two still agree.
+  class ProblemDetails < ::Google::Protobuf::AbstractMessage
+    attr_reader type: ::String
+    attr_reader title: ::String
+    attr_reader status: ::Integer
+    attr_reader detail: ::String
+    attr_reader instance: ::String
+    attr_reader information: ::Google::Protobuf::RepeatedField[::Google::Protobuf::Any]
+  end
+end

data/sig/manual/problem_pb.rbs

@@ -0,0 +1,8 @@
+module Protobufable
+  # Generated from proto/protobufable/problem.proto. Hand-written because the generation
+  # pipeline emits Ruby only; problem_type_options_spec.rb checks the two still agree.
+  class ProblemTypeOptions < ::Google::Protobuf::AbstractMessage
+    attr_reader uri: ::String
+    attr_reader http_status: ::Integer
+  end
+end

data/sig/manual/protovalidate.rbs

@@ -0,0 +1,38 @@
+module Protobufable
+  module RequestValidatable
+    # What a controller including the concern supplies. A module self-type constrains
+    # includers, not the module itself, so these are spelled out here.
+    interface _RequestValidatableSelf
+      include RequestParseable::_RequestParseableSelf
+
+      def action_name: () -> String
+      def message: () -> untyped
+      def class: () -> _RequestValidatableClass
+    end
+
+    # The class-level state this reads, both its own and RequestParseable's. Declared by hand
+    # because `class_attribute` and the callback DSL define their methods at runtime.
+    interface _RequestValidatableClass
+      include RequestParseable::_RequestParseableClass
+
+      def before_action: (*untyped) -> void
+      def _process_action_callbacks: () -> untyped
+      def instance_variable_get: (Symbol) -> untyped
+      def protobuf_body_pending?: () -> bool
+    end
+  end
+
+module ColumnValidatable
+  # The attribute table the validation walks, which ActiveRecord defines on the class.
+  interface _ColumnValidatableClass
+    def attribute_types: () -> Hash[String, untyped]
+  end
+
+  # What an ActiveRecord model supplies to the validation this installs.
+  interface _ColumnValidatableSelf
+    def class: () -> _ColumnValidatableClass
+    def []: (String name) -> untyped
+    def errors: () -> untyped
+  end
+end
+end

data/sig/manual/request_parseable.rbs

@@ -0,0 +1,17 @@
+module Protobufable
+  module RequestParseable
+    # What `params` a controller including the concern supplies. A module self-type constrains
+    # includers, not the module's own type, so it has to be spelled out here.
+    interface _RequestParseableSelf
+      def params: () -> untyped
+      def request: () -> untyped
+    end
+
+    # The class-level state RequestParseable installs. Declared by hand because
+    # `class_attribute` defines its accessors at runtime, which RBS cannot infer.
+    interface _RequestParseableClass
+      def protobuf_body_declarations: () -> Hash[String, Declaration]
+      def protobuf_body_declarations=: (Hash[String, Declaration]) -> void
+    end
+  end
+end