protobufable 0.1.0

data/lib/protobufable/connect/problem_rescuable.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "active_support/concern"
+require "connect_rpc_rails"
+require "problem"
+
+require "protobufable"
+require "protobufable/problem_details_pb"
+require "protobufable/problem/information"
+
+module Protobufable
+  module Connect
+    # Answers a ::Problem::Detailable raised in a Connect RPC as a Connect error rather than as
+    # application/problem+json.
+    #
+    # The code is read off the problem's status and the message is its detail, or its title when
+    # there is none. The document itself travels as a detail, so a caller dispatches on the same
+    # `type` over Connect as over REST.
+    #
+    # @example
+    #   class WidgetsController < ActionController::API
+    #     include ConnectRpcRails::Controller
+    #     include Protobufable::Connect::ProblemRescuable
+    #
+    #     connect_service "myapp.api.WidgetsService"
+    #   end
+    #
+    # Include it after ConnectRpcRails::Controller. Only a problem raised inside the controller is
+    # answered this way; one escaping before dispatch reaches the exceptions app.
+    #
+    # @rbs module-self _ProblemRescuableSelf
+    module ProblemRescuable
+      extend ActiveSupport::Concern
+
+      include ::Problem::Rescuable
+
+      # `self` inside an ActiveSupport::Concern block is the including class, which RBS has no
+      # way to name.
+      # steep:ignore:start
+      included do
+        # Registered again for a controller whose parent already included ::Problem::Rescuable, so
+        # it follows the rescue_responses handlers ConnectRpcRails::Controller installed since:
+        # Rails picks the most recently registered match.
+        rescue_from(::Problem::Detailable, with: :render_problem_detailable)
+      end
+      # steep:ignore:end
+
+      # Builds the message the document travels as. Override to build the application's own copy
+      # of the message instead.
+      #
+      # `information` carries the error's {Problem::Information} messages, packed as they are rather
+      # than re-read from the rendered document. Other extension members are dropped, because the
+      # message has no slot for them.
+      #
+      # @param problem [::Problem::Details]
+      # @param error [Exception] the error the document was built from
+      # @return [Object] a protobuf message
+      #: (::Problem::Details problem, untyped error) -> untyped
+      private def problem_message_for(problem, error)
+        information = [] #: Array[untyped]
+        information = error.problem_information if error.is_a?(Protobufable::Problem::Information)
+
+        ProblemDetails.new(
+          type: problem.type || "",
+          title: problem.title || "",
+          status: problem.status,
+          detail: problem.detail || "",
+          instance: problem.instance || "",
+          information: information.map { |info| Google::Protobuf::Any.pack(info) },
+        )
+      end
+
+      # @param problem [::Problem::Details]
+      # @param error [Exception]
+      # @return [void]
+      #: (::Problem::Details problem, untyped error) -> void
+      private def render_problem(problem, error)
+        render_connect_error(
+          ConnectRpcRails::Error.new(
+            ConnectRpcRails::Error.code_for_http_status(problem.status),
+            problem.detail.presence || problem.title,
+            details: [Google::Protobuf::Any.pack(problem_message_for(problem, error))],
+          ),
+        )
+      end
+    end
+  end
+end

data/lib/protobufable/connect.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+# The connect_rpc_rails integration, required on its own because neither connect_rpc_rails nor
+# problem is a dependency of protobufable: a host that serves no Connect RPC never loads it.
+#
+#   require "protobufable/connect"
+
+require "protobufable/problem"
+
+module Protobufable
+  # The connect_rpc_rails integration: problems answered as Connect errors.
+  module Connect
+  end
+end
+
+require "protobufable/connect/problem_rescuable"

data/lib/protobufable/field_path.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "protobufable"
+
+module Protobufable
+  # Renders a `buf.validate.FieldPath` in the spelling the caller sent.
+  #
+  # A field path is only useful if the client can find the field it names, and a protobuf field
+  # has two published names: `preferred_language` in the binary encoding and in ProtoJSON with
+  # `preserve_proto_fieldnames`, `preferredLanguage` in ProtoJSON without it. Which one to use
+  # is a property of the encoding in play, so each segment is resolved against the descriptor
+  # rather than interpolated from the name the violation happened to carry.
+  #
+  # @example
+  #   Protobufable::FieldPath.render(violation.field, CreateWidgetRequest, json_names: true)
+  #   #=> "widget.tags[0]"
+  module FieldPath
+    # Renders a path against the message it was produced from.
+    #
+    # @param path [Object, nil] a `buf.validate.FieldPath`
+    # @param message_class [Class] the message the path is rooted in
+    # @param json_names [Boolean] whether to publish `json_name` rather than the proto name
+    # @return [String] the path, empty for a message-level rule
+    #: (untyped path, Google::Protobuf::_MessageClass message_class, ?json_names: bool) -> String
+    def self.render(path, message_class, json_names: false)
+      return "" if path.nil?
+
+      descriptor = message_class.descriptor #: untyped
+      path.elements.map do |element|
+        field = descriptor&.lookup(element.field_name)
+        descriptor = field&.subtype
+        "#{publish(field, element, json_names:)}#{subscript(element)}"
+      end.join(".")
+    end
+
+    # @return [String] the name this segment is published under
+    #: (untyped field, untyped element, json_names: bool) -> String
+    def self.publish(field, element, json_names:)
+      # A path segment the descriptor cannot resolve is published as the violation spelled it,
+      # which is better than dropping the segment and renumbering the rest of the path.
+      return element.field_name if field.nil?
+
+      json_names ? field.json_name : field.name
+    end
+
+    # @return [String] the `[...]` suffix for a repeated or map element, empty otherwise
+    #: (untyped element) -> String
+    def self.subscript(element)
+      case element.subscript
+      when :index then "[#{element.index}]"
+      when :bool_key then "[#{element.bool_key}]"
+      when :int_key then "[#{element.int_key}]"
+      when :uint_key then "[#{element.uint_key}]"
+      when :string_key then "[#{element.string_key.inspect}]"
+      else ""
+      end
+    end
+
+    private_class_method :publish, :subscript
+  end
+end

data/lib/protobufable/json_type.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "active_model"
+require "active_support/json"
+
+require "protobufable"
+
+module Protobufable
+  # An ActiveModel type storing a protobuf message in a native `json` or `jsonb` column.
+  #
+  # Encoding goes through the message's own `encode_json` and `decode_json`, so the stored
+  # document is constrained to the protobuf schema rather than to whatever a Hash happened to
+  # hold. Being a type rather than a `serialize` coder is what buys dirty tracking, casting
+  # from a Hash, and a column the adapter knows is JSON.
+  #
+  # @example A column that is never null in Ruby
+  #   class Widget < ApplicationRecord
+  #     attribute :settings, Protobufable::JsonType.new(Internal::WidgetSettings),
+  #       default: -> { Internal::WidgetSettings.new }
+  #   end
+  class JsonType < ActiveModel::Type::Value
+    # @return [Class] the generated message class this column holds
+    attr_reader :message_class #: Google::Protobuf::_MessageClass
+
+    # @param message_class [Class] the generated message class this column holds
+    # @param nil_as_default [Boolean] whether a null column reads back as an empty message,
+    #   for a nullable column whose Ruby value is semantically non-null
+    # @param preserve_proto_fieldnames [Boolean] whether documents are written with the
+    #   `.proto` field names (`snake_case`) rather than their lowerCamelCase JSON names
+    # @return [void]
+    #: (Google::Protobuf::_MessageClass message_class, ?nil_as_default: bool, ?preserve_proto_fieldnames: bool) -> void
+    def initialize(message_class, nil_as_default: false, preserve_proto_fieldnames: false)
+      super()
+      @message_class = message_class
+      @nil_as_default = nil_as_default
+      @preserve_proto_fieldnames = preserve_proto_fieldnames
+    end
+
+    # @return [Symbol] always `:json`, so Rails and the adapter treat the column as JSON
+    #: () -> Symbol
+    def type = :json
+
+    # Decodes a stored document into a message.
+    #
+    # Unknown fields are tolerated: during a rolling deploy a row written by a newer schema has
+    # to stay readable on a node that has not picked it up yet.
+    #
+    # @param value [String, nil] the document as the adapter hands it back
+    # @return [Object, nil] the decoded message, or nil for a null column
+    #: (String? value) -> untyped
+    def deserialize(value)
+      return @message_class.new if value.nil? && @nil_as_default
+      return if value.nil?
+
+      @message_class.decode_json(value, ignore_unknown_fields: true)
+    end
+
+    # Encodes a message for storage.
+    #
+    # Defaults are emitted so the stored shape does not depend on which fields happened to be
+    # set, which is what makes {#changed_in_place?} meaningful and spares anything reading the
+    # column in SQL from telling absent from default.
+    #
+    # @param value [Object, nil] the message to store
+    # @return [String, nil] the document to write, or nil
+    #: (untyped value) -> String?
+    def serialize(value)
+      return if value.nil?
+
+      @message_class.encode_json(
+        value,
+        emit_defaults: true,
+        preserve_proto_fieldnames: @preserve_proto_fieldnames,
+      )
+    end
+
+    # Coerces an assigned value into a message, accepting what a form, a fixture or a seed
+    # would supply as well as a message itself.
+    #
+    # @param value [Object, String, Hash, nil]
+    # @return [Object, nil] the message, or the value unchanged when it is none of those
+    #: (untyped value) -> untyped
+    def cast(value)
+      return deserialize(nil) if value.nil?
+
+      case value
+      when @message_class
+        value
+      when ::String
+        deserialize(value)
+      when ::Hash
+        deserialize(::ActiveSupport::JSON.encode(value))
+      else
+        value
+      end
+    end
+
+    # Compares decoded messages rather than encoded text: a jsonb column hands back a
+    # canonicalized document whose key order and spacing need not match what `encode_json`
+    # produced, which would otherwise read as a change on every load.
+    #
+    # @param raw_old_value [String, nil] the document as it was loaded
+    # @param new_value [Object, nil] the message currently held
+    # @return [Boolean]
+    #: (String? raw_old_value, untyped new_value) -> bool
+    def changed_in_place?(raw_old_value, new_value)
+      deserialize(raw_old_value) != new_value
+    end
+  end
+end

data/lib/protobufable/problem/information.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "json"
+require "problem/detailable"
+
+require "protobufable"
+
+module Protobufable
+  module Problem
+    # Publishes machine-readable data about an occurrence as protobuf messages, in an
+    # `information` extension member.
+    #
+    # RFC 9457 reserves `detail` for prose, so anything a client is meant to act on rather than
+    # read goes somewhere else. This packs each message as a `google.protobuf.Any`, which is what
+    # lets one member carry `google.rpc.BadRequest`, `ErrorInfo` and whatever else an occurrence
+    # has to say without the document declaring a slot for each.
+    #
+    # @example
+    #   class InvalidWidget < Errors::ApiError
+    #     include Protobufable::Problem::Information
+    #
+    #     def problem_information
+    #       super + [Google::Rpc::BadRequest.new(field_violations: violations)]
+    #     end
+    #   end
+    #
+    #   {"type": "...", "status": 400, "information": [
+    #     {"@type": "type.googleapis.com/google.rpc.BadRequest", "field_violations": [...]}
+    #   ]}
+    #
+    # Every hook calls `super`, so this composes with ::Problem::RetryAfter and with another mixin
+    # of your own rather than replacing what they contribute.
+    #
+    # @rbs module-self ::Problem::Detailable
+    module Information
+      # The extension member the packed messages are published in.
+      MEMBER = :information #: Symbol
+
+      # Protobuf messages this occurrence publishes. Override and call `super`.
+      #
+      # @return [Array<Object>]
+      #: () -> Array[untyped]
+      def problem_information = []
+
+      # Adds the packed messages to the document, and nothing at all when there are none: an
+      # empty member would be noise on every error that carries no detail of this kind.
+      #
+      # @return [Hash{Symbol => Object}]
+      #: () -> Hash[Symbol, untyped]
+      def problem_extensions
+        messages = problem_information
+        return super if messages.empty?
+
+        super.merge(MEMBER => messages.map { |message| Information.pack(message) })
+      end
+
+      # Packs one message as a `google.protobuf.Any` and renders it as ProtoJSON.
+      #
+      # Field names are preserved rather than lowerCamelCased, matching what the proto_json
+      # renderer sends, so a client reads one spelling across the whole API.
+      #
+      # @param message [Object] a protobuf message
+      # @return [Hash] the Any as ProtoJSON, carrying an `@type` alongside the message's fields
+      #: (untyped message) -> untyped
+      def self.pack(message)
+        any = Google::Protobuf::Any.pack(message)
+        JSON.parse(Google::Protobuf::Any.encode_json(any, preserve_proto_fieldnames: true))
+      end
+    end
+  end
+end

data/lib/protobufable/problem/retry_info.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "problem/retry_after"
+
+require "protobufable"
+require "protobufable/problem/information"
+
+module Protobufable
+  module Problem
+    # Publishes a retry interval as a `google.rpc.RetryInfo` as well as a Retry-After header.
+    #
+    # ::Problem::RetryAfter already sends the header and a `retry_after` member, which a generic
+    # HTTP client obeys. This adds the form a client generated from the same protos already knows
+    # how to read, so the two kinds of caller get the same answer.
+    #
+    # @example
+    #   class TooManyRequests < Errors::ApiError
+    #     include Protobufable::Problem::RetryInfo
+    #
+    #     problem_type :PROBLEM_TYPE_TOO_MANY_REQUESTS
+    #   end
+    #
+    #   raise TooManyRequests.new(retry_after: 30)
+    #
+    # `google.rpc` descriptors are not shipped with this gem: they belong to the app that
+    # generates googleapis alongside its own protos. The message class is looked up when it is
+    # first needed, and the error names what to generate if it is missing.
+    #
+    # @rbs module-self ::Problem::Detailable
+    module RetryInfo
+      include ::Problem::RetryAfter
+      include Information
+
+      # The message this publishes.
+      MESSAGE = "google.rpc.RetryInfo" #: String
+
+      # @return [Array<Object>] the occurrence's messages, with the retry interval appended
+      #: () -> Array[untyped]
+      def problem_information
+        super + [RetryInfo.message_for(retry_after_seconds)]
+      end
+
+      # @param seconds [Integer] the wait
+      # @return [Object] a `google.rpc.RetryInfo` carrying it
+      # @raise [Protobufable::Error] when googleapis has not been generated into the pool
+      #: (Integer seconds) -> untyped
+      def self.message_for(seconds)
+        descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(MESSAGE) or
+          raise Protobufable::Error,
+            "#{MESSAGE} is not in the descriptor pool; generate google/rpc/error_details.proto"
+
+        descriptor.msgclass.new(
+          retry_delay: Google::Protobuf::Duration.new(seconds: seconds),
+        )
+      end
+    end
+  end
+end

data/lib/protobufable/problem/typeable.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "problem/i18nable"
+
+require "protobufable"
+
+module Protobufable
+  module Problem
+    # Derives an error's RFC 9457 type and status from a protobuf enum, whose values carry them
+    # as a custom option.
+    #
+    # This is the catalogue layer ::Problem::Detailable documents: it prepends a module to the
+    # error class's singleton that overrides `type` and `status`, and calls `super` for a class
+    # the catalogue does not cover, so a literal declaration still works.
+    #
+    # Applications whose enum is annotated with one option per property override
+    # {ClassMethods#problem_uri_annotation} and {ClassMethods#problem_status_annotation} instead.
+    #
+    # @example
+    #   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 WidgetNotReady < ApiError
+    #       problem_type :PROBLEM_TYPE_WIDGET_NOT_READY
+    #     end
+    #   end
+    #
+    # The status is an annotation on the value rather than a property of the code path that
+    # raised it: two errors needing different statuses are different types. Several values may
+    # publish one identifier on purpose, where telling them apart would leak something; because
+    # ::Problem::I18nable keys titles by the published identifier, they share a title too, which is
+    # the invariant that keeps the distinction hidden.
+    #
+    # @rbs module-self ::Exception
+    # @rbs module-self ::Problem::_DetailableSelf
+    module Typeable
+      extend ActiveSupport::Concern
+
+      # Brings the DSL this overrides, and the title lookup, so one include covers all three.
+      include ::Problem::I18nable
+
+      # What one enum value publishes.
+      Entry = Data.define(:uri, :http_status)
+
+      # Overrides ::Problem::Detailable's literal DSL for a class that declared a value, and falls
+      # through to it for one that did not.
+      #
+      # Prepended to the singleton class rather than defined in ClassMethods so it wins whichever
+      # order the concerns were mixed in. A class that spells out a literal keeps it, the rule
+      # ::Problem::I18nable already follows, so a codebase can move onto a catalogue gradually.
+      #
+      # @rbs module-self _TypeableClass
+      module Derivation
+        # The identifier the declared value publishes, which is its annotation rather than its
+        # name: several values deliberately publish the same one.
+        #
+        # @param value [String, nil] a literal declaration, which takes precedence
+        # @return [String, nil]
+        #: (?String?) -> String?
+        def type(value = nil)
+          return super if value || problem_uri || problem_type.nil?
+
+          @problem_type_uri ||= problem_type_entry.uri
+        end
+
+        # The status the declared value is returned with.
+        #
+        # @param value [Integer, nil] a literal declaration, which takes precedence
+        # @return [Integer, nil]
+        #: (?Integer?) -> Integer?
+        def status(value = nil)
+          return super if value || problem_status || problem_type.nil?
+
+          @problem_type_status ||= problem_type_entry.http_status
+        end
+      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(:problem_type_value, instance_accessor: false)
+
+        singleton_class.prepend(Derivation)
+      end
+      # steep:ignore:end
+
+      # @rbs module-self _TypeableClass
+      module ClassMethods
+        # The full name of the enum this class's catalogue lives in.
+        #
+        # No default: an app's catalogue is the one thing a gem cannot guess. Override it on the
+        # base class the rest of the errors inherit from.
+        #
+        # @return [String]
+        # @raise [Protobufable::Error] when it has not been overridden
+        #: () -> String
+        def problem_type_enum
+          raise Protobufable::Error,
+            "#{name || self} declares no problem type enum: define " \
+              "`def self.problem_type_enum` returning the full name of the enum its values live in"
+        end
+
+        # The full name of the extension carrying a value's uri and http_status as one message.
+        #
+        # No default either, because nothing generated from the gem's own .proto is shipped while
+        # its option number is provisional. See DESIGN.md.
+        #
+        # @return [String]
+        # @raise [Protobufable::Error] when neither this nor the split pair has been overridden
+        #: () -> String
+        def problem_type_annotation
+          raise Protobufable::Error,
+            "#{name || self} declares no problem type annotation: define " \
+              "`def self.problem_type_annotation` returning the full name of the extension its " \
+              "values are annotated with"
+        end
+
+        # The extension carrying a value's identifier, for a catalogue that spends one option
+        # number per property rather than carrying both in one message.
+        #
+        # Override this and {problem_status_annotation} together, instead of
+        # {problem_type_annotation}, when the enum is already annotated that way. An established
+        # schema does not have to be rewritten to be read from here.
+        #
+        # @return [String, nil]
+        #: () -> String?
+        def problem_uri_annotation = nil
+
+        # The extension carrying a value's status, alongside {problem_uri_annotation}.
+        #
+        # @return [String, nil]
+        #: () -> String?
+        def problem_status_annotation = nil
+
+        # Declares which enum value this class renders as, or reads back what was declared.
+        #
+        # An unknown or unannotated value raises here, at class definition time, so a typo fails
+        # on boot rather than on the first request that reaches the error.
+        #
+        # @param value [Symbol, nil] the enum value name
+        # @return [Symbol, nil]
+        # @raise [Protobufable::Error] when the catalogue does not cover the value
+        #: (?Symbol?) -> Symbol?
+        def problem_type(value = nil)
+          return problem_type_value if value.nil?
+
+          name = value.to_sym
+          unless problem_type_catalogue.key?(name)
+            raise Protobufable::Error,
+              "unknown or unannotated value #{name} in #{problem_type_enum}"
+          end
+
+          self.problem_type_value = name
+        end
+
+        # The catalogue this class reads, built from the enum on first use.
+        #
+        # Memoized on the class that asked rather than in a table keyed by enum name: a reloaded
+        # or anonymous class then cannot read a catalogue built for a previous one.
+        #
+        # @return [Hash{Symbol => Entry}]
+        #: () -> Hash[Symbol, Entry]
+        def problem_type_catalogue
+          @problem_type_catalogue ||= Typeable.build_catalogue(
+            enum: problem_type_enum,
+            annotation: problem_uri_annotation ? nil : problem_type_annotation,
+            uri_annotation: problem_uri_annotation,
+            status_annotation: problem_status_annotation,
+          )
+        end
+
+        # @return [Entry] what the declared value publishes
+        #: () -> Entry
+        def problem_type_entry = problem_type_catalogue.fetch(problem_type)
+      end
+
+      # Reads every annotated value of an enum.
+      #
+      # @param enum [String] full name of the enum
+      # @param annotation [String, nil] full name of the single sub-message extension
+      # @param uri_annotation [String, nil] full name of the identifier extension
+      # @param status_annotation [String, nil] full name of the status extension
+      # @return [Hash{Symbol => Entry}] one entry per value carrying both properties
+      # @raise [Protobufable::Error] when a name does not resolve, or the split pair is half given
+      #: (enum: String, annotation: String?, uri_annotation: String?, status_annotation: String?) -> Hash[Symbol, Entry]
+      def self.build_catalogue(enum:, annotation:, uri_annotation:, status_annotation:)
+        pool = Google::Protobuf::DescriptorPool.generated_pool
+        descriptor = pool.lookup(enum) or
+          raise Protobufable::Error, "enum #{enum} is not in the descriptor pool"
+
+        readers = entry_readers(pool, annotation, uri_annotation, status_annotation)
+
+        catalogue = {} #: Hash[Symbol, Entry]
+        descriptor.to_proto.value.each do |value|
+          options = value.options
+          next if options.nil?
+
+          entry = readers.call(options)
+          next if entry.nil?
+
+          catalogue[value.name.to_sym] = entry
+        end
+        catalogue.freeze
+      end
+
+      # @return [Proc] reads one value's options into an Entry, or nil when it carries none
+      #: (untyped pool, String? annotation, String? uri_annotation, String? status_annotation) -> ^(untyped) -> Entry?
+      def self.entry_readers(pool, annotation, uri_annotation, status_annotation)
+        if uri_annotation || status_annotation
+          unless uri_annotation && status_annotation
+            raise Protobufable::Error,
+              "a split annotation needs both problem_uri_annotation and problem_status_annotation"
+          end
+
+          uri = lookup_extension!(pool, uri_annotation)
+          status = lookup_extension!(pool, status_annotation)
+          return ->(options) {
+            found = uri.get(options)
+            code = status.get(options)
+            next nil if found.nil? || found.empty? || code.nil? || code.zero?
+
+            Entry.new(uri: found, http_status: code)
+          }
+        end
+
+        extension = lookup_extension!(pool, annotation.to_s)
+        ->(options) {
+          found = extension.get(options)
+          next nil if found.nil? || found.uri.empty? || found.http_status.zero?
+
+          Entry.new(uri: found.uri, http_status: found.http_status)
+        }
+      end
+
+      # @return [Google::Protobuf::FieldDescriptor]
+      # @raise [Protobufable::Error] when the extension is not in the pool
+      #: (untyped pool, String name) -> untyped
+      def self.lookup_extension!(pool, name)
+        pool.lookup(name) or
+          raise Protobufable::Error,
+            "extension #{name} is not in the descriptor pool; is its _pb.rb required?"
+      end
+
+      private_class_method :entry_readers, :lookup_extension!
+    end
+  end
+end