protobufable 0.1.0

data/lib/protobufable/problem.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+# The problem gem integration, required on its own because problem is not a dependency of
+# protobufable: a host that renders no problem details never loads it.
+#
+#   require "protobufable/problem"
+#
+# Brings Protobufable::ProblemTypeOptions with it, the message an application annotates its
+# problem type enum with. Requiring it registers that descriptor, so an application must not
+# also generate protobufable/problem.proto itself.
+
+require "protobufable/problem_pb"
+
+module Protobufable
+  # The problem gem integration: a catalogue backed by a protobuf enum, and protobuf messages in
+  # a problem document. Code in here names the problem gem's own constants as `::Problem`.
+  module Problem
+  end
+end
+
+require "protobufable/problem/typeable"
+require "protobufable/problem/information"
+require "protobufable/problem/retry_info"

data/lib/protobufable/problem_details_pb.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: protobufable/problem_details.proto
+
+require 'google/protobuf'
+
+require 'google/protobuf/any_pb'
+
+
+descriptor_data = "\n\"protobufable/problem_details.proto\x12\x0cprotobufable\x1a\x19google/protobuf/any.proto\"\xbe\x01\n\x0eProblemDetails\x12\x12\n\x04type\x18\x01 \x01(\tR\x04type\x12\x14\n\x05title\x18\x02 \x01(\tR\x05title\x12\x16\n\x06status\x18\x03 \x01(\x05R\x06status\x12\x16\n\x06\x64\x65tail\x18\x04 \x01(\tR\x06\x64\x65tail\x12\x1a\n\x08instance\x18\x05 \x01(\tR\x08instance\x12\x36\n\x0binformation\x18\x06 \x03(\x0b\x32\x14.google.protobuf.AnyR\x0binformationb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Protobufable
+  ProblemDetails = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("protobufable.ProblemDetails").msgclass
+end

data/lib/protobufable/problem_pb.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: protobufable/problem.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n\x1aprotobufable/problem.proto\x12\x0cprotobufable\"G\n\x12ProblemTypeOptions\x12\x10\n\x03uri\x18\x01 \x01(\tR\x03uri\x12\x1f\n\x0bhttp_status\x18\x02 \x01(\rR\nhttpStatusb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Protobufable
+  ProblemTypeOptions = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("protobufable.ProblemTypeOptions").msgclass
+end

data/lib/protobufable/protovalidate.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+# The protovalidate integration, required on its own because protovalidate is not a dependency
+# of protobufable: a host that declares no buf.validate rules never loads it.
+#
+#   require "protobufable/protovalidate"
+
+require "protobufable/bad_request"
+require "protobufable/column_validatable"
+require "protobufable/field_path"
+require "protobufable/request_validatable"

data/lib/protobufable/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "rails/railtie"
+require "action_dispatch/railtie"
+
+require "protobufable"
+
+module Protobufable
+  # Installs the renderers and the request body parser on boot, and classifies a broken
+  # `buf.validate` rule as a 400.
+  class Railtie < ::Rails::Railtie
+    # A string, so protovalidate stays unloaded for an application that does not use it.
+    # `config.action_dispatch` is answered by method_missing, which RBS cannot describe.
+    # steep:ignore:start
+    config.action_dispatch.rescue_responses["Protobufable::RequestValidatable::InvalidMessage"] = :bad_request
+    # steep:ignore:end
+
+    initializer "protobufable.install" do
+      Protobufable.install!
+    end
+  end
+end

data/lib/protobufable/renderers.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "action_controller"
+
+module Protobufable
+  # The media types and renderers for answering with a protobuf message.
+  #
+  # @example Binary, for a client that asked for it
+  #   render protobuf: Api::GetWidgetResponse.new(widget:)
+  #
+  # @example ProtoJSON, which is ordinary JSON a client needs to know nothing about
+  #   render proto_json: Api::GetWidgetResponse.new(widget:)
+  module Renderers
+    # The media type the binary renderer answers with.
+    CONTENT_TYPE = "application/protobuf" #: String
+
+    # Registers the media type and both renderers. Idempotent, so a second host installing on
+    # the same process is harmless.
+    #
+    # @return [void]
+    #: () -> void
+    def self.install!
+      Mime::Type.register(CONTENT_TYPE, :protobuf) unless Mime[:protobuf]
+
+      # `self` inside a renderer block is the controller, which RBS has no way to name.
+      # steep:ignore:start
+      ActionController::Renderers.add(:protobuf) do |message, _options|
+        self.content_type = if message.is_a?(String)
+          Protobufable::Renderers::CONTENT_TYPE
+        else
+          # The descriptor name tells a caller which message it received without having to
+          # infer it from the endpoint.
+          "#{Protobufable::Renderers::CONTENT_TYPE}; " \
+            "proto=#{message.class.descriptor.name}"
+        end
+        # After content_type=, which re-applies the default charset.
+        response.charset = false
+
+        message.is_a?(String) ? message : message.class.encode(message)
+      end
+
+      ActionController::Renderers.add(:proto_json) do |message, _options|
+        self.content_type = "application/json"
+        message.class.encode_json(
+          message,
+          # ProtoJSON defaults to lowerCamelCase. snake_case matches what the rest of a Rails
+          # API sends and what the generated OpenAPI describes, and it is a one-way door for
+          # clients, so it is not left to chance.
+          preserve_proto_fieldnames: true,
+          # Responses stay small and an absent `optional` field stays distinguishable from one
+          # set to its default. Stored columns take the opposite setting, deliberately; see
+          # Protobufable::JsonType.
+          emit_defaults: false,
+        )
+      end
+      # steep:ignore:end
+    end
+  end
+end

data/lib/protobufable/request_parseable.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "active_support/concern"
+require "action_dispatch"
+
+require "protobufable"
+
+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
+    extend ActiveSupport::Concern
+
+    # What `protobuf_body` records about one action.
+    Declaration = Data.define(:message_class, :ignore_unknown_fields)
+
+    # 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 = "[FILTERED]" #: String
+
+      # @param message [Object] the parsed protobuf message
+      # @return [void]
+      #: (untyped message) -> void
+      def initialize(message)
+        @message = message
+      end
+
+      # @return [Array] always empty, so `inspect` does not reach the message
+      #: () -> Array[Symbol]
+      def instance_variables_to_inspect = []
+
+      # 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(*) = FILTERED
+
+      # @return [Object] the wrapped message
+      #: () -> untyped
+      def to_protobuf = to_original_message
+
+      # @return [Object] the wrapped message
+      #: () -> untyped
+      def to_original_message
+        @message
+      end
+    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
+        original_parsers = super
+        original_json_parser = original_parsers[Mime[:json].symbol]
+
+        original_parsers.merge(
+          Mime[:json].symbol => ->(raw_post) {
+            RequestParseable.param_parser(self, raw_post, original_json_parser)
+          },
+        )
+      end
+    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(request, raw_post, original_parser)
+      declaration = declaration_for(request)
+      return original_parser.call(raw_post) unless declaration
+
+      message = declaration.message_class.decode_json(
+        raw_post,
+        ignore_unknown_fields: declaration.ignore_unknown_fields,
+      )
+      message.to_h.merge(_protobuf: MessageWrapper.new(message))
+    end
+
+    # @param request [ActionDispatch::Request]
+    # @return [Declaration, nil] what the routed action declared, if anything
+    #: (untyped request) -> Declaration?
+    def self.declaration_for(request)
+      action = request.path_parameters[:action]
+      return if action.nil?
+
+      controller = request.controller_class
+      return unless controller.respond_to?(:protobuf_body_declarations)
+
+      controller.protobuf_body_declarations[action.to_s]
+    rescue NameError
+      # An unresolvable controller is not this parser's problem; routing reports it.
+      nil
+    end
+
+    # `self` inside an ActiveSupport::Concern block is the including class, which RBS has no
+    # way to name; the accessor this installs is declared in sig/manual instead.
+    # steep:ignore:start
+    included do
+      class_attribute(:protobuf_body_declarations, default: {}.freeze, instance_accessor: false)
+    end
+    # steep:ignore:end
+
+    # Class-level DSL installed by including the concern.
+    #
+    # @rbs module-self _RequestParseableClass
+    module ClassMethods
+      # 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(message_class, ignore_unknown_fields: false)
+        @next_protobuf_body = Declaration.new(message_class:, ignore_unknown_fields:)
+        nil
+      end
+
+      # Binds a pending `protobuf_body` to the action defined under it.
+      #
+      # @param method_name [Symbol]
+      # @return [void]
+      #: (Symbol method_name) -> void
+      def method_added(method_name)
+        super
+        declaration = @next_protobuf_body
+        return unless declaration
+
+        @next_protobuf_body = nil
+        self.protobuf_body_declarations =
+          protobuf_body_declarations.merge(method_name.to_s => declaration).freeze
+      end
+    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
+      wrapper = request.request_parameters[:_protobuf]
+      return wrapper.to_original_message if wrapper.is_a?(MessageWrapper)
+
+      raise KeyError, "this action declared no protobuf_body" unless RequestParseable.declaration_for(request)
+
+      raise ActionDispatch::Http::Parameters::ParseError, "expected a JSON request body"
+    end
+  end
+end

data/lib/protobufable/request_validatable.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "active_support/concern"
+require "protovalidate"
+
+require "protobufable"
+require "protobufable/request_parseable"
+
+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
+    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(violations, message_class)
+        @violations = violations
+        @message_class = message_class
+        super(violations.map(&:to_s).join("; "))
+      end
+    end
+
+    # `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 a controller can opt out at the top of the class with
+      # `skip_before_action :validate_protobuf_body!`.
+      before_action(:validate_protobuf_body!)
+    end
+    # steep:ignore:end
+
+    # @rbs module-self _RequestValidatableClass
+    module ClassMethods
+      # 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(method_name)
+        pending = protobuf_body_pending?
+        super
+        return unless pending
+        return unless _process_action_callbacks.any? { |cb| cb.filter == :validate_protobuf_body! }
+
+        before_action(:validate_protobuf_body!)
+      end
+
+      # @return [Boolean] whether a `protobuf_body` is waiting to bind to the next action
+      #: () -> bool
+      def protobuf_body_pending? = !instance_variable_get(:@next_protobuf_body).nil?
+    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!
+      declaration = self.class.protobuf_body_declarations[action_name]
+      return if declaration.nil?
+      return unless params.key?(:_protobuf)
+
+      violations = Protovalidate.collect_violations(message)
+      return if violations.empty?
+
+      raise InvalidMessage.new(violations, declaration.message_class)
+    end
+  end
+end

data/lib/protobufable/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+module Protobufable
+  # The gem's version.
+  VERSION = "0.1.0" #: String
+end

data/lib/protobufable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "google/protobuf"
+require "google/protobuf/well_known_types"
+
+require "protobufable/version"
+require "protobufable/json_type"
+require "protobufable/request_parseable"
+require "protobufable/renderers"
+
+# 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!
+    Renderers.install!
+    ActionDispatch::Request.prepend(RequestParseable::RequestPatch)
+  end
+end
+
+require "protobufable/railtie" if defined?(Rails::Railtie)

data/lib/tapioca/dsl/compilers/protobufable_request_parseable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+return unless defined?(Protobufable::RequestParseable)
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Types `message` on each controller that declares `protobuf_body`, so an action reads the
+      # decoded request body as its message class without a cast.
+      #
+      # A controller whose actions declare one class gets that class:
+      #
+      # ~~~rb
+      # class WidgetsController < ApplicationController
+      #   include Protobufable::RequestParseable
+      #
+      #   protobuf_body Api::CreateWidgetRequest
+      #   def create; end
+      # end
+      # ~~~
+      #
+      # ~~~rbi
+      # # widgets_controller.rbi
+      # # typed: true
+      # class WidgetsController
+      #   sig { returns(::Api::CreateWidgetRequest) }
+      #   def message; end
+      # end
+      # ~~~
+      #
+      # A controller whose actions declare different classes gets their union, which an action
+      # narrows itself, for example with `#: self as WidgetsController & ...` or a cast.
+      #: [ConstantType = Class[top]]
+      class ProtobufableRequestParseable < Compiler
+        # @override
+        #: -> void
+        def decorate
+          root.create_path(constant) do |controller|
+            controller.create_method("message", return_type: return_type)
+          end
+        end
+
+        class << self
+          # @override
+          #: -> Enumerable[Module[top]]
+          def gather_constants
+            all_classes.select do |klass|
+              klass < ::Protobufable::RequestParseable && !declared_classes(klass).empty?
+            end
+          end
+
+          #: (Class[top] klass) -> Array[Module[top]]
+          def declared_classes(klass)
+            klass.protobuf_body_declarations.values.map(&:message_class).uniq
+          end
+        end
+
+        #: -> String
+        private def return_type
+          names = self.class.declared_classes(constant).map { |klass| "::#{klass.name}" }.sort
+          names.one? ? names.first : "T.any(#{names.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/proto/protobufable/problem.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+package protobufable;
+
+// What an enum value publishes when it is rendered as an RFC 9457 problem document.
+//
+// Carried by a custom option on the value, which an application declares itself:
+//
+//     import "google/protobuf/descriptor.proto";
+//     import "protobufable/problem.proto";
+//
+//     extend google.protobuf.EnumValueOptions {
+//       optional protobufable.ProblemTypeOptions problem_type = 50001;
+//     }
+//
+//     enum ProblemType {
+//       PROBLEM_TYPE_UNSPECIFIED = 0;
+//       PROBLEM_TYPE_NOT_FOUND = 1 [(problem_type) = {uri: "not-found", http_status: 404}];
+//     }
+//
+// The extension is declared by the application rather than here because its field number is a
+// global namespace: numbers are registered in protocolbuffers/protobuf docs/options.md, and
+// protobufable does not hold one yet. This message needs none, so it ships now, and an
+// application picks its own number from the internal-use range meanwhile.
+//
+// One message rather than one option per property: the extension then spends one number where
+// separate scalars would spend one each, and a property added later is a field here.
+message ProblemTypeOptions {
+  // Identifier this problem type publishes, resolved against the deployment's type prefix to
+  // form the document's `type`. Several values may deliberately publish the same one.
+  string uri = 1;
+
+  // HTTP status this problem type is returned with. A property of the problem type rather than
+  // of the code path that raised it: two errors needing different statuses are different types.
+  uint32 http_status = 2;
+}

data/proto/protobufable/problem_details.proto

@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package protobufable;
+
+import "google/protobuf/any.proto";
+
+// An RFC 9457 problem document as a message, for a transport whose errors carry protobuf
+// messages rather than a JSON body, such as a Connect error's details.
+//
+// Kept apart from problem.proto so an application can vendor this file to reference the
+// message from its own schema without vendoring the option message too.
+message ProblemDetails {
+  // URI reference identifying the problem type.
+  string type = 1;
+
+  // Short, human-readable summary of the problem type.
+  string title = 2;
+
+  // HTTP status of this occurrence.
+  int32 status = 3;
+
+  // Human-readable explanation specific to this occurrence.
+  string detail = 4;
+
+  // URI reference identifying this occurrence.
+  string instance = 5;
+
+  // Machine-readable data about this occurrence, such as a google.rpc.BadRequest. Named apart
+  // from `detail`, which RFC 9457 reserves for prose.
+  repeated google.protobuf.Any information = 6;
+}