protovalidate 0.1.0.beta2-x86_64-linux-musl → 0.1.0.beta3-x86_64-linux-musl

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c2ccec5b488156236cf492a05e6fbb1ddb6d796da9ce9a7ca80e6ef5a41838d
-  data.tar.gz: 8713a240d5d9638f9733bdc27e4bf34674324471eea883ef8e205db4016ebb16
+  metadata.gz: e031f847eb9af657c7b9889fd7d193bc06b5bfb229f6f87acaa6d0a043da734c
+  data.tar.gz: 1cae86079996f8eac7c9e997bf8a488c8ad060df02290225a7a017f3d1f9e1d8
 SHA512:
-  metadata.gz: 909472c403f0bb2e3ad1bbdee69b06f5b29c395abebe54a50817f8f9ae76ad8f48bfa1376b9d3c553bf8913ae716e9f74db3771cecb56e93a3253e4f78c733bb
-  data.tar.gz: f53477b297f1ea47619b0a8c834188ef68ee77cd6f1379421a04904857cd8e6111cd273225ca93fa8ad721657299416783e4d40dea990de075c6d7ea9f79ea85
+  metadata.gz: 77af95b01c8e02e98a753351bc170fdee47f087341fa6be5f8c5c06c14e753bfee86c4bcaa31f55a0c108d749ce5a58f3b75b76ded25bc9e94bb79cff7c62ff5
+  data.tar.gz: 139ecc9b4a46773ff00dc02fc9b831f9d0e267be8a5a0f88a0899a674ac992add1b32c6ec9dc9ab9660f01298f57dfa644411a0d320b46fe79f70374d86da3c3

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.0.beta3 (2026-09-22)
+
+- `Protovalidate.register` and `Validator#register` compile the rules of message types ahead of their first validation, so the compilation, which blocks concurrent validations, can run at boot instead of inside a request. `register_all` does the same for every loaded message class.
+- Validating an already seen message type no longer takes a lock or allocates its type name on the Ruby side.
+
 ## 0.1.0.beta2 (2026-09-21)
 
 - Precompiled gems for `x86_64-linux-musl`, `aarch64-linux-musl`, `arm-linux-gnu` and `x64-mingw-ucrt`.

data/README.md

@@ -77,6 +77,23 @@ All inherit from `Protovalidate::Error` except `ArgumentError`.
 
 A `Validator` compiles the rules of each message type once and caches them, so reuse one instance. Validating from several threads at once is supported and releases the GVL while protovalidate-cc runs. Ractors are not supported.
 
+The rules of a message type are compiled the first time a message of that type is validated, and protovalidate-cc holds an exclusive lock while it compiles, so every concurrent validation on the same validator waits until the compilation finishes. To keep that off the request path, register the message types your application validates at boot, for example from a Rails initializer or before the server forks workers:
+
+```ruby
+Protovalidate.register(Example::User, Example::Order)
+```
+
+`Protovalidate.register_all` registers every message class loaded so far instead of a hand-maintained list, so call it once all generated code has been loaded. In a Rails application, `config.after_initialize` callbacks run in the `finisher_hook` initializer, after the `eager_load!` initializer, so with `config.eager_load` enabled every generated class under an autoload path is already loaded by then. Generated code outside the autoload paths, such as under `lib/`, must be required before the callback runs.
+
+```ruby
+# config/initializers/protovalidate.rb
+Rails.application.config.after_initialize do
+  Protovalidate.register_all if Rails.application.config.eager_load
+end
+```
+
+Types that were not registered still compile on first use, so registration is an optimization rather than a requirement. Both methods raise `Protovalidate::CompilationError` for a rule that does not compile, so a bad rule fails at boot rather than on the first request that reaches it. `register_all` skips message types the engine cannot see, which happens when google-protobuf ships a newer copy of a file compiled into the extension, such as `google/protobuf/descriptor.proto`; those types cannot be validated either way. Once a type is registered, validating it takes no lock on the Ruby side, and the shared validator returned by `Protovalidate.validator` is created once and then read without locking.
+
 ## Development
 
 ```bash

data/lib/protovalidate/validator.rb

@@ -9,17 +9,57 @@ module Protovalidate
   # type once and caches them, so reuse one instance rather than creating one
   # per validation. Instances may be shared between threads; Ractors are not
   # supported.
+  #
+  # The rules of a message type are compiled the first time it is validated,
+  # and concurrent validations wait while that happens. {#register} moves the
+  # compilation to a time of your choosing, such as application boot.
   class Validator
+    # Every generated message class is a direct subclass of this private
+    # google-protobuf class, so its subclasses are the loaded message classes.
+    MESSAGE_BASE = Google::Protobuf.const_get(:AbstractMessage)
+    private_constant :MESSAGE_BASE
+
     # @param descriptor_pool [Google::Protobuf::DescriptorPool] pool the
     #   validated messages' schema files and their imports are looked up in
     def initialize(descriptor_pool: Google::Protobuf::DescriptorPool.generated_pool)
       @descriptor_pool = descriptor_pool
       @engine = Native::Engine.new
       @registered_files = Set.new
-      @registered_types = Set.new
+      types = {} #: Hash[message_class, String]
+      @types = types.compare_by_identity.freeze
       @registration = Mutex.new
     end
 
+    # Compiles the rules of message classes ahead of their first validation.
+    #
+    # Classes not registered here are still compiled on first use, so this is
+    # an optimization, not a requirement.
+    #
+    # @param message_classes [Array<Class>] message classes generated by google-protobuf
+    # @return [void]
+    # @raise [CompilationError] when the rules of a message type cannot be compiled
+    # @raise [ArgumentError] when an import of a message's file is missing from the pool
+    # @raise [TypeError] when a class is not a Protobuf message class
+    def register(*message_classes)
+      message_classes.each { |klass| type_name_of(klass) }
+      nil
+    end
+
+    # Registers every message class loaded so far whose type is defined in
+    # this validator's descriptor pool. Call it once all generated code has
+    # been loaded, such as after eager loading.
+    #
+    # Types the engine cannot see are skipped: google-protobuf may ship a
+    # newer copy of a file compiled into the extension, such as
+    # descriptor.proto, and the types it added cannot be validated anyway.
+    #
+    # @return [void]
+    # @raise (see #register)
+    def register_all
+      loaded_message_classes.each { |klass| register_class(klass, skip_unknown: true) }
+      nil
+    end
+
     # Validates a message, raising when it is invalid.
     #
     # @param message [Google::Protobuf::MessageExts]
@@ -46,9 +86,8 @@ module Protovalidate
     # @raise [EvaluationError] when a rule fails during evaluation
     # @raise [TypeError] when `message` is not a Protobuf message
     def collect_violations(message, fail_fast: false)
-      descriptor = descriptor_of(message)
-      register(descriptor)
-      serialized = @engine.validate(descriptor.name, message.class.encode(message), fail_fast)
+      type_name = type_name_of(message.class)
+      serialized = @engine.validate(type_name, message.class.encode(message), fail_fast)
       return [] if serialized.nil?
 
       Buf::Validate::Violations.decode(serialized).violations.map do |proto|
@@ -56,24 +95,46 @@ module Protovalidate
       end
     end
 
-    private def descriptor_of(message)
-      klass = message.class
-      unless klass.respond_to?(:descriptor) && klass.descriptor.is_a?(Google::Protobuf::Descriptor)
-        raise TypeError, "expected a Google::Protobuf message, got #{klass}"
-      end
-
-      klass.descriptor
+    # The full name of a message class's type, registering and compiling it on
+    # first sight. Registered classes resolve with one lookup and no lock.
+    private def type_name_of(klass)
+      @types[klass] || register_class(klass)
     end
 
-    private def register(descriptor)
-      return if @registered_types.include?(descriptor.name)
-
+    # @types is replaced with a frozen copy rather than mutated, so a reader
+    # outside the lock never observes a Hash being written to.
+    private def register_class(klass, skip_unknown: false)
+      descriptor = descriptor_of(klass)
       @registration.synchronize do
-        next if @registered_types.include?(descriptor.name)
+        @types[klass] || begin
+          register_file(descriptor.file_descriptor)
+          name = descriptor.name.freeze
+          next if skip_unknown && !@engine.message_type?(name)
+
+          @engine.compile(name)
+          types = @types.dup
+          types[klass] = name
+          @types = types.freeze
+          name
+        end
+      end
+    end
+
+    # Classes generated from other pools are skipped, since their files are
+    # not resolvable against this one.
+    private def loaded_message_classes
+      MESSAGE_BASE.subclasses.select do |klass|
+        descriptor = klass.descriptor
+        @descriptor_pool.lookup(descriptor.name).equal?(descriptor)
+      end
+    end
 
-        register_file(descriptor.file_descriptor)
-        @registered_types << descriptor.name
+    private def descriptor_of(klass)
+      unless klass.is_a?(Google::Protobuf::MessageExts::ClassMethods)
+        raise TypeError, "expected a Google::Protobuf message class, got #{klass.inspect}"
       end
+
+      klass.descriptor
     end
 
     # The engine resolves imports eagerly, so they are added before the importer.

data/lib/protovalidate/version.rb

@@ -2,7 +2,7 @@
 
 module Protovalidate
   # Version of this gem.
-  VERSION = "0.1.0.beta2"
+  VERSION = "0.1.0.beta3"
 
   # Version of the protovalidate specification (buf.validate protos and
   # conformance suite) this gem bundles and is validated against.

data/lib/protovalidate.rb

@@ -32,6 +32,25 @@ module Protovalidate
     validator.validate(message, fail_fast:)
   end
 
+  # Compiles the rules of message classes ahead of their first validation with
+  # the shared validator, for example at application boot.
+  #
+  # @param (see Validator#register)
+  # @return [void]
+  # @raise (see Validator#register)
+  def self.register(*message_classes)
+    validator.register(*message_classes)
+  end
+
+  # Registers every loaded message class of the generated pool with the shared
+  # validator. Call it once all generated code has been loaded.
+  #
+  # @return [void]
+  # @raise (see Validator#register)
+  def self.register_all
+    validator.register_all
+  end
+
   # Collects the violations of a message with the shared validator.
   #
   # @param (see Validator#collect_violations)

data/sig/protovalidate/native.rbs

@@ -6,6 +6,13 @@ module Protovalidate
       # Adds a serialized google.protobuf.FileDescriptorProto to the pool.
       def add_file: (String file) -> void
 
+      # Whether the engine's pool knows the named message type.
+      def message_type?: (String type_name) -> bool
+
+      # Compiles the rules of the named type and of every type reachable from
+      # it, ahead of the first validate.
+      def compile: (String type_name) -> void
+
       # Validates a serialized message of the named type; returns serialized
       # buf.validate.Violations, or nil when the message is valid.
       def validate: (String type_name, String payload, bool fail_fast) -> String?

data/sig/protovalidate.rbs

@@ -11,11 +11,18 @@ module Protovalidate
   # A Protobuf message instance produced by google-protobuf.
   type message = Google::Protobuf::MessageExts
 
+  # A Protobuf message class generated by google-protobuf.
+  type message_class = Google::Protobuf::MessageExts::ClassMethods
+
   # The validator shared by the module-level functions.
   def self.validator: () -> Validator
 
   def self.validate: (message message, ?fail_fast: bool) -> void
 
+  def self.register: (*message_class message_classes) -> void
+
+  def self.register_all: () -> void
+
   def self.collect_violations: (message message, ?fail_fast: bool) -> Array[Violation]
 
   class Error < StandardError
@@ -36,21 +43,33 @@ module Protovalidate
   end
 
   class Validator
+    # google-protobuf's private base class of generated messages, reached with const_get.
+    MESSAGE_BASE: untyped
+
     @descriptor_pool: Google::Protobuf::DescriptorPool
     @engine: Native::Engine
     @registered_files: Set[String]
-    @registered_types: Set[String]
+    # Message class to its full type name, replaced as a whole on registration.
+    @types: Hash[message_class, String]
     @registration: Mutex
 
     def initialize: (?descriptor_pool: Google::Protobuf::DescriptorPool) -> void
 
+    def register: (*message_class message_classes) -> void
+
+    def register_all: () -> void
+
     def validate: (message message, ?fail_fast: bool) -> void
 
     def collect_violations: (message message, ?fail_fast: bool) -> Array[Violation]
 
-    private def descriptor_of: (message message) -> Google::Protobuf::Descriptor
+    private def loaded_message_classes: () -> Array[message_class]
+
+    private def type_name_of: (message_class klass) -> String
+
+    private def register_class: (message_class klass, ?skip_unknown: bool) -> String?
 
-    private def register: (Google::Protobuf::Descriptor descriptor) -> void
+    private def descriptor_of: (message_class klass) -> Google::Protobuf::Descriptor
 
     private def register_file: (Google::Protobuf::FileDescriptor file) -> void
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protovalidate
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta2
+  version: 0.1.0.beta3
 platform: x86_64-linux-musl
 authors:
 - Sorah Fukumori