protobufable 0.1.0

data/docs/errors.md

@@ -0,0 +1,190 @@
+# Errors
+
+Built on [problem](https://github.com/sorah/problem), which owns RFC 9457 itself. This supplies
+the catalogue: an enum whose values carry the identifier and status they publish.
+
+The gem supplies the option message. Declare the extension that carries it in your own `.proto`,
+with a field number of your own — see [Caveats](#caveats) for why that part is yours — and
+annotate the enum:
+
+```proto
+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}];
+  PROBLEM_TYPE_WIDGET_NOT_READY = 2 [(problem_type) = {uri: "widget-not-ready", http_status: 409}];
+}
+```
+
+Point the base class at it, then declare a value per error:
+
+```ruby
+require "protobufable/problem"
+
+module Errors
+  class ApiError < StandardError
+    include Protobufable::Problem::Typeable
+
+    def self.problem_type_enum = "myapp.api.ProblemType"
+    def self.problem_type_annotation = "myapp.api.problem_type"
+  end
+
+  class NotFound < ApiError
+    problem_type :PROBLEM_TYPE_NOT_FOUND
+  end
+end
+
+raise Errors::NotFound.new(detail: "no widget w_123")
+```
+
+A controller renders them as `application/problem+json` once it includes `Problem::Rescuable`,
+from problem. An error escaping before dispatch needs problem's `Problem::ExceptionsApp`
+instead; see its README.
+
+```ruby
+class ApplicationController < ActionController::API
+  include Problem::Rescuable
+end
+```
+
+A value the enum does not define, or one carrying no annotation, raises when the class is
+defined, so a typo fails on boot rather than on the first request that reaches the error.
+
+The status is a property of the problem type, not of the code path that raised it. Several
+values may publish one identifier where telling them apart would leak something; because
+`Problem::I18nable` keys titles by the identifier, such values share a title too, so the
+distinction cannot come back through the title instead.
+
+To answer these errors over Connect RPC, see [Connect RPC](connect.md).
+
+## An enum annotated one option per property
+
+A catalogue whose values carry the identifier and the status as two separate options, rather
+than one message, is read by overriding the other pair:
+
+```ruby
+class ApiError < StandardError
+  include Protobufable::Problem::Typeable
+
+  def self.problem_type_enum = "myapp.api.ProblemType"
+  def self.problem_uri_annotation = "myapp.api.problem_uri"
+  def self.problem_status_annotation = "myapp.api.http_status"
+end
+```
+
+Both halves are required, and they replace `problem_type_annotation` rather than supplementing
+it. Everything else behaves the same. This is for a schema that is already shaped that way; a
+new catalogue should use the single option message, which spends one registered extension number
+instead of two.
+
+## Publishing the enum value
+
+The enum is internal by default: RFC 9457 requires `type` to be a URI reference, so what goes
+on the wire is the identifier the value publishes, and the value itself stays a server-side
+label. An API that wants clients to dispatch on the value instead can publish it as an
+extension member, in one mixin:
+
+```ruby
+module PublishesProblemType
+  def problem_extensions = super.merge(problem_type: self.class.problem_type.to_s)
+end
+
+module Errors
+  class ApiError < StandardError
+    include Protobufable::Problem::Typeable
+    include PublishesProblemType
+
+    def self.problem_type_enum = "myapp.api.ProblemType"
+    def self.problem_type_annotation = "myapp.api.problem_type"
+  end
+end
+```
+
+```json
+{"type": "not-found", "title": "Not Found", "status": 404, "problem_type": "PROBLEM_TYPE_NOT_FOUND"}
+```
+
+Every class under that base publishes its own value, and `super.merge` means it composes with
+`Problem::Information` and anything else contributing members.
+
+> [!WARNING]
+> This publishes the finer grain. If two values deliberately share an identifier because telling
+> them apart would leak something, the extension hands the caller exactly that distinction back.
+> Publish the value only when no pair in the catalogue is hiding one — or override
+> `problem_extensions` on the classes that are.
+
+The value is also permanent once published: renaming an enum value is then a breaking change for
+clients, on top of the usual protobuf reasons to treat values as append-only.
+
+## Machine-readable detail
+
+RFC 9457 reserves `detail` for prose. Anything a client acts on goes in `information`, as packed
+`google.protobuf.Any`:
+
+```ruby
+class InvalidRequest < Errors::ApiError
+  include Protobufable::Problem::Information
+
+  problem_type :PROBLEM_TYPE_BAD_REQUEST
+
+  def initialize(violations:, message_class:, **kwargs)
+    @violations = violations
+    @message_class = message_class
+    super(**kwargs)
+  end
+
+  def problem_information
+    super + [Protobufable::BadRequest.for(@violations, @message_class, json_names: true)]
+  end
+end
+```
+
+```json
+{"type": "bad-request", "status": 400, "information": [
+  {"@type": "type.googleapis.com/google.rpc.BadRequest",
+   "field_violations": [{"field": "name", "description": "must be at least 1 characters"}]}
+]}
+```
+
+To answer a broken `buf.validate` rule with it, see
+[Answering a broken rule](validation.md#answering-a-broken-rule).
+
+`Protobufable::Problem::RetryInfo` is the ready-made one: it publishes a `google.rpc.RetryInfo` alongside
+the `Retry-After` header `Problem::RetryAfter` already sends, so a generic HTTP client and a
+generated client get the same answer.
+
+```ruby
+class TooManyRequests < Errors::ApiError
+  include Protobufable::Problem::RetryInfo
+
+  problem_type :PROBLEM_TYPE_TOO_MANY_REQUESTS
+end
+
+raise TooManyRequests.new(retry_after: 30)
+```
+
+## Caveats
+
+- **The extension is yours to declare, and the enum always will be.** The catalogue is your
+  API's own vocabulary, so the gem cannot supply it, nor anything referencing it;
+  `Problem::Typeable` reads whichever enum you point it at. It does supply the option message. The
+  `extend` that carries it is still yours for now: extension field numbers are a global
+  namespace registered in
+  [protocolbuffers/protobuf](https://github.com/protocolbuffers/protobuf/blob/main/docs/options.md),
+  protobufable claims 1376 but does not hold it, and an extension whose number can still move
+  would break every `.proto` that imported it. Pick a number from the internal-use range
+  (50000–99999) meanwhile.
+- **Importing `protobufable/problem.proto` or `protobufable/problem_details.proto` means
+  vendoring it.** The files ship in the gem, but buf and protoc resolve imports from your own
+  module, not from a gem path, so copy them into your proto tree and generate from there. Then
+  drop the generated `protobufable/*_pb.rb`, which the gem already loads: a duplicate
+  descriptor is a boot failure, not a warning.
+- **`google.rpc` descriptors are not shipped either.** `Problem::RetryInfo` and `BadRequest` look their
+  message classes up in the pool, so generate `google/rpc/error_details.proto` alongside your
+  own protos. A second copy of those descriptors in one process is a boot failure.

data/docs/request-bodies.md

@@ -0,0 +1,42 @@
+# Request bodies
+
+Declare the message an action accepts, above the action:
+
+```ruby
+class WidgetsController < ApplicationController
+  include Protobufable::RequestParseable
+
+  protobuf_body Api::CreateWidgetRequest
+  def create
+    Widget.create!(name: message.name, tags: message.tags.to_a)
+  end
+end
+```
+
+`message` is the decoded message. `params` is still filled from it, so anything already reading
+`params[:name]` keeps working and an endpoint can be moved over one at a time.
+
+| option | default | meaning |
+|---|---|---|
+| `ignore_unknown_fields` | `false` | When true, a field the schema does not declare is dropped. Left false, it is a 400, so a client's typo is not a value that silently never arrives. |
+
+The body is decoded once, by replacing the `:json` parser, so nothing parses the JSON twice.
+The parsed message is held behind a wrapper that renders as `[FILTERED]`, because Rails'
+parameter filtering cannot see inside a protobuf message and would otherwise log every field it
+holds.
+
+To check values as well as types, see [Value validation](validation.md).
+
+## Sorbet
+
+With [tapioca](https://github.com/Shopify/tapioca) in the bundle, `tapioca dsl` picks up a
+compiler shipped in this gem that types `message` on every controller declaring
+`protobuf_body`: as the declared class when all of the controller's actions declare the same one,
+and as their union otherwise, which an action narrows itself.
+
+```rbi
+class WidgetsController
+  sig { returns(::Api::CreateWidgetRequest) }
+  def message; end
+end
+```

data/docs/responses.md

@@ -0,0 +1,49 @@
+# Responses
+
+```ruby
+render proto_json: Api::GetWidgetResponse.new(widget:)   # application/json
+render protobuf: Api::GetWidgetResponse.new(widget:)     # application/protobuf
+```
+
+`proto_json` sends ProtoJSON with `preserve_proto_fieldnames: true` and `emit_defaults: false`:
+snake_case, matching the rest of a Rails API, and no key for a field that was never set, so an
+absent `optional` field stays distinguishable from one set to its default. Both are one-way
+doors for clients, which is why they are not left to chance.
+
+`protobuf` sends binary, with the descriptor name in the content type
+(`application/protobuf; proto=myapp.api.GetWidgetResponse`).
+
+## Bound Alba resources
+
+```ruby
+class WidgetResource < ApplicationResource
+  include Protobufable::AlbaBinding
+
+  with_protobuf Api::Widget do
+    attributes :id, :name
+    attributes created_at: :timestamp
+    one :owner, resource: OwnerResource
+  end
+end
+```
+
+`with_protobuf` checks both directions when the class loads: an attribute the message does not
+declare, and a field no attribute produces, each raise there rather than at response time. Put
+every attribute inside the block — the check runs when `with_protobuf` does, so anything
+declared after it is never compared.
+
+`attributes created_at: :timestamp` needs the converter, because a `google.protobuf.Timestamp`
+field refuses the `ActiveSupport::TimeWithZone` an ActiveRecord column hands back:
+
+```ruby
+# config/initializers/protobufable.rb
+Protobufable::AlbaBinding.register_timestamp_type!
+```
+
+`AlbaBinding` needs the [alba](https://github.com/okuramasafumi/alba) gem.
+
+## Caveats
+
+- **`AlbaBinding` reads Alba internals.** The parity check uses `@_attributes` and `@_traits`,
+  which are private to Alba, so an Alba release can break it. A spec pins the assumption against
+  the installed version.

data/docs/validation.md

@@ -0,0 +1,121 @@
+# Value validation
+
+Decoding rejects a wrong type. `buf.validate` rules add what the type cannot say:
+
+```proto
+message CreateWidgetRequest {
+  string name = 1 [(buf.validate.field).string = {min_len: 1, max_len: 100}];
+  repeated string tags = 2 [(buf.validate.field).repeated = {max_items: 8, unique: true}];
+}
+```
+
+```ruby
+require "protobufable/protovalidate"
+
+class WidgetsController < ApplicationController
+  include Protobufable::RequestValidatable   # brings RequestParseable
+
+  protobuf_body Api::CreateWidgetRequest
+  def create = ...
+end
+```
+
+Only a controller including `RequestValidatable` validates. A broken rule raises
+`Protobufable::RequestValidatable::InvalidMessage`, carrying the violations and the message
+class, and is a 400 with no further setup; to tell the client which fields failed, see
+[Answering a broken rule](#answering-a-broken-rule).
+
+The validation callback runs *after* the callbacks declared above the action, so an
+unauthenticated request is answered before an invalid one and the endpoint does not become an
+oracle for what a valid body looks like. Opt an action out with
+`skip_before_action :validate_protobuf_body!`.
+
+Compile the rules at boot, so a CEL typo fails startup rather than the first request, and no
+request pays the compilation:
+
+```ruby
+# config/initializers/protobufable.rb
+Rails.application.config.after_initialize { Protovalidate.register_all }
+```
+
+## Answering a broken rule
+
+The railtie lists `InvalidMessage` in `rescue_responses` as `:bad_request`, so unrescued it
+reaches the exceptions app and goes out as a 400 with that app's generic body, a bare problem
+document under `Problem::ExceptionsApp`. That body says nothing about which fields failed.
+
+Reporting them is left to the application, because the response belongs to the API: its shape,
+the spelling of its field paths, and whether googleapis is generated. Rescue `InvalidMessage`
+with an error type of your own, or with one from the problem catalogue; either takes precedence
+over `rescue_responses`.
+
+An error type of your own renders whatever the API already sends for a client error:
+
+```ruby
+class ApplicationController < ActionController::API
+  rescue_from Protobufable::RequestValidatable::InvalidMessage do |error|
+    render status: 400,
+      proto_json: Protobufable::BadRequest.for(error.violations, error.message_class, json_names: true)
+  end
+end
+```
+
+```json
+{"field_violations": [{"field": "name", "description": "must be at least 1 characters"}]}
+```
+
+A problem-based error is a catalogue entry carrying the violations, such as `InvalidRequest` in
+[Machine-readable detail](errors.md#machine-readable-detail), handed to `Problem::Rescuable`:
+
+```ruby
+class ApplicationController < ActionController::API
+  include Problem::Rescuable
+
+  rescue_from Protobufable::RequestValidatable::InvalidMessage do |error|
+    render_problem_detailable(
+      InvalidRequest.new(violations: error.violations, message_class: error.message_class),
+    )
+  end
+end
+```
+
+```json
+{"type": "bad-request", "status": 400, "information": [
+  {"@type": "type.googleapis.com/google.rpc.BadRequest",
+   "field_violations": [{"field": "name", "description": "must be at least 1 characters"}]}
+]}
+```
+
+Call `render_problem_detailable` rather than raising the problem: Rails does not rescue an
+exception raised inside a `rescue_from` handler.
+
+## Stored columns
+
+The same rules run over [`JsonType` columns](columns.md) before save, so they hold wherever a
+record is written — application code, a seed, the console. This is opted into on the model,
+independently of `RequestValidatable`:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Protobufable::ColumnValidatable
+end
+```
+
+## Field paths
+
+`Protobufable::FieldPath` renders a violation's path in the spelling the caller sent. A protobuf
+field has two published names, and a client that reads lowerCamelCase ProtoJSON cannot find a
+field named the other way, so each segment is resolved against the descriptor rather than taken
+from the name the violation carried:
+
+```ruby
+Protobufable::FieldPath.render(violation.field, Api::CreateWidgetRequest)
+#=> "parts[0].part_name"
+Protobufable::FieldPath.render(violation.field, Api::CreateWidgetRequest, json_names: true)
+#=> "parts[0].partName"
+```
+
+## Caveats
+
+- **`google.rpc` descriptors are not shipped.** `BadRequest` looks `google.rpc.BadRequest` up in
+  the pool; see [Errors](errors.md#caveats).

data/lib/protobufable/alba_binding.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "alba"
+
+require "protobufable"
+
+module Protobufable
+  # Binds an Alba resource to the protobuf message it produces, and checks at load time that
+  # the two agree on every field.
+  #
+  # Serialization stays idiomatic — one resource per model, with Alba's association DSL — while
+  # the wire format belongs to the schema. The parity check is the point: without it a field
+  # added to the .proto has no producer and simply comes back empty, which nothing reports.
+  #
+  # @example
+  #   class WidgetResource < ApplicationResource
+  #     with_protobuf Api::Widget do
+  #       attributes :id, :name
+  #       attribute(:created_at) { |w| w.created_at.to_time }
+  #     end
+  #   end
+  #
+  #   render proto_json: Api::GetWidgetResponse.new(widget: WidgetResource.new(widget).as_protobuf)
+  #
+  # The check reads Alba's `@_attributes` and `@_traits`, which are internal to Alba, so an
+  # Alba release can break it. A spec pins the assumption against the installed version.
+  #
+  # @rbs module-self _AlbaBindingSelf
+  module AlbaBinding
+    # @param base [Class] the Alba resource class including this
+    # @return [void]
+    #: (untyped base) -> void
+    def self.included(base)
+      base.helper(HelperMethods)
+    end
+
+    # Each of these reaches the binding through `self.class`: Alba installs HelperMethods on
+    # instances too, so a bare `message_class` here would resolve to the class-level reader with
+    # `self` being the instance, whose ivar is never set.
+    #
+    # @return [Object] the bound message, built from the serialized attributes
+    #: () -> untyped
+    def as_protobuf = self.class.message_class.new(as_json)
+
+    # @return [String] the bound message encoded as binary protobuf
+    #: () -> String
+    def to_protobuf = self.class.message_class.encode(as_protobuf)
+
+    # Renders through the message's own encoder rather than Alba's, so the wire format is the
+    # schema's. Field names and default omission match the proto_json renderer.
+    #
+    # @return [String] the bound message as ProtoJSON
+    #: (*untyped) -> String
+    def to_json(*)
+      self.class.message_class
+        .encode_json(as_protobuf, preserve_proto_fieldnames: true, emit_defaults: false)
+    end
+
+    # Class-level DSL, installed through Alba's own helper mechanism.
+    #
+    # @rbs module-self _AlbaBindingClass
+    module HelperMethods
+      # @return [Class] the message class this resource is bound to
+      # @raise [Protobufable::Error] when the resource declared no binding
+      #: () -> Google::Protobuf::_MessageClass
+      def message_class
+        @message_class || raise(
+          Protobufable::Error,
+          "#{name || self} is not bound to a message: declare one with `with_protobuf`",
+        )
+      end
+
+      # Binds this resource to a message and declares its attributes.
+      #
+      # Both directions are checked: an attribute the message does not declare, and a field no
+      # attribute produces, each fail here rather than at response time. The check runs when this
+      # does, so an attribute declared after it is never compared; everything belongs inside the
+      # block.
+      #
+      # @param klass [Class] the generated message class
+      # @yield the resource's attribute declarations
+      # @return [void]
+      # @raise [Protobufable::Error] when the two have drifted apart
+      #: (Google::Protobuf::_MessageClass klass) { () -> void } -> void
+      def with_protobuf(klass, &block)
+        module_eval(&block)
+        @message_class = klass
+
+        declared = klass.descriptor.map { |field| field.name.to_sym }
+        produced = AlbaBinding.produced_attributes(self)
+
+        unknown = declared - produced
+        undeclared = produced - declared
+        unless undeclared.empty?
+          raise Protobufable::Error,
+            "#{name} serializes #{undeclared.inspect}, which #{klass.name} does not declare"
+        end
+        unless unknown.empty?
+          raise Protobufable::Error,
+            "#{name} is missing #{unknown.inspect}, which #{klass.name} declares"
+        end
+
+        nil
+      end
+    end
+
+    # Registers a `:timestamp` Alba type that converts to Time.
+    #
+    # A `google.protobuf.Timestamp` field accepts a Time but refuses an
+    # ActiveSupport::TimeWithZone, which is what an ActiveRecord timestamp column hands back,
+    # so a resource serializing one needs the conversion.
+    #
+    #   Protobufable::AlbaBinding.register_timestamp_type!
+    #
+    #   attribute :created_at, :timestamp
+    #
+    # Opt-in rather than done on require: Alba's type registry is global, and a gem should not
+    # add to it behind a host's back.
+    #
+    # @return [void]
+    #: () -> void
+    def self.register_timestamp_type!
+      Alba.register_type(:timestamp, converter: :to_time.to_proc, auto_convert: true)
+      nil
+    end
+
+    # Every attribute a resource can produce, including the ones a trait adds.
+    #
+    # A trait is a block rather than a list, so the only way to see what it declares is to
+    # evaluate it, which is what the throwaway subclass is for.
+    #
+    # @param resource [Class] the Alba resource
+    # @return [Array<Symbol>]
+    #: (untyped resource) -> Array[Symbol]
+    def self.produced_attributes(resource)
+      attributes = resource.instance_variable_get(:@_attributes).keys
+      traits = resource.instance_variable_get(:@_traits) || {}
+
+      attributes + traits.each_value.flat_map do |trait|
+        Class.new(resource).tap { it.class_eval(&trait) }
+          .instance_variable_get(:@_attributes).keys
+      end
+    end
+  end
+end

data/lib/protobufable/bad_request.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "protobufable"
+require "protobufable/field_path"
+
+module Protobufable
+  # Turns protovalidate violations into a `google.rpc.BadRequest`, the form AIP-193 defines for
+  # telling a client which fields it got wrong.
+  #
+  # Hand the result to {Problem::Information}, which publishes it in the document.
+  #
+  # @example
+  #   class InvalidMessage < Errors::BadRequest
+  #     include Protobufable::Problem::Information
+  #
+  #     def initialize(violations:, **kwargs)
+  #       @violations = violations
+  #       super(**kwargs)
+  #     end
+  #
+  #     def problem_information
+  #       super + [Protobufable::BadRequest.for(@violations, message_class)]
+  #     end
+  #   end
+  #
+  # `google.rpc` descriptors are not shipped with this gem; the app that generates googleapis
+  # alongside its own protos supplies them.
+  module BadRequest
+    # The message this builds.
+    MESSAGE = "google.rpc.BadRequest" #: String
+
+    # @param violations [Array<Protovalidate::Violation>]
+    # @param message_class [Class] the message the violations were produced from
+    # @param json_names [Boolean] whether field paths name fields as ProtoJSON spells them
+    # @return [Object] a `google.rpc.BadRequest`, one FieldViolation per violation
+    # @raise [Protobufable::Error] when googleapis has not been generated into the pool
+    #: (Array[untyped] violations, Google::Protobuf::_MessageClass message_class, ?json_names: bool) -> untyped
+    def self.for(violations, message_class, json_names: false)
+      pool = Google::Protobuf::DescriptorPool.generated_pool
+      bad_request = pool.lookup(MESSAGE) or
+        raise Protobufable::Error,
+          "#{MESSAGE} is not in the descriptor pool; generate google/rpc/error_details.proto"
+      field_violation = pool.lookup("#{MESSAGE}.FieldViolation") #: untyped
+
+      bad_request.msgclass.new(
+        field_violations: violations.map do |violation|
+          field_violation.msgclass.new(
+            field: FieldPath.render(violation.field, message_class, json_names:),
+            description: violation.message,
+            reason: violation.rule_id,
+          )
+        end,
+      )
+    end
+  end
+end

data/lib/protobufable/column_validatable.rb

@@ -0,0 +1,56 @@
+# 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/field_path"
+require "protobufable/json_type"
+
+module Protobufable
+  # Runs the `buf.validate` rules of every {JsonType} column before the record is saved, so a
+  # column holding a message enforces what its .proto declares wherever the record is written:
+  # application code, a seed, the console.
+  #
+  # @example
+  #   class ApplicationRecord < ActiveRecord::Base
+  #     include Protobufable::ColumnValidatable
+  #   end
+  #
+  # @rbs module-self _ColumnValidatableSelf
+  module ColumnValidatable
+    extend ActiveSupport::Concern
+
+    # `self` inside an ActiveSupport::Concern block is the including class, which RBS has no
+    # way to name.
+    # steep:ignore:start
+    included do
+      validate(:validate_protobuf_message_columns)
+    end
+    # steep:ignore:end
+
+    # Adds one error per violation, under the attribute that holds the message.
+    #
+    # @return [void]
+    #: () -> void
+    private def validate_protobuf_message_columns
+      self.class.attribute_types.each do |name, type|
+        next unless type.is_a?(JsonType)
+
+        # read_attribute rather than the reader, which a model may have overridden to wrap the
+        # message in something of its own.
+        message = self[name]
+        next if message.nil?
+
+        Protovalidate.collect_violations(message).each do |violation|
+          path = FieldPath.render(violation.field, type.message_class)
+          errors.add(name, path.empty? ? violation.message : "#{path}: #{violation.message}")
+        end
+      end
+    end
+  end
+end