protovalidate 0.1.0.beta2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa9accbc06dca6c9a48cf7f7b944fd5831b2e453f63da38861e687bc24bc11e1
-  data.tar.gz: 45b07a1ee9e4faff86119af90d4d65dc5d1437bf9f68cf251b1d449433ca144d
+  metadata.gz: 5d8cc5dfbb7033d2c85cebe3484abc14f885ea17e4ba7bb3275d4c92f1c79d56
+  data.tar.gz: 5784af175464b4e8ab4789b7963a46d7ef4117c902da4097b9feb41896e5967a
 SHA512:
-  metadata.gz: 11cae4c40737c00931f7232fd0abefa846efcccce3b1eb64607c21af936b8b99753b2d0779ba9ba4386ea435f1b757f6e56403dd8b383051468fbb1f89674ed5
-  data.tar.gz: 39916ae1fcfa899a4231a1e813f51e1707a5cb829599b44dc987d7f822126cf99e6be2117cf15c6a11f8e99443ca0fc1d2f9da93a2f0e76d37053d3c04c8411d
+  metadata.gz: 7861da8a16afe9321252ad759b778a36585edc125c614cc57b4dd8a3f1395dd99cbb1f69573872211ca86bbffa541b3b7d7d1eb612420f41717659df7f5a08ef
+  data.tar.gz: d1b8918dc6f669ebba5756d7d042c4c950c5c94238ba040bb0ae134098b36adf9e6597739d5e18bed5f544096d049f1710e22a750f2ef18ea6911bdf943e803f

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0 (2026-10-14)
+
+- Graduate beta.
+
+## 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. Without eager loading, only the classes loaded so far are registered and the rest compile on first use. 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
+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/ext/protovalidate/src/lib.rs

@@ -6,8 +6,8 @@
 use magnus::Module as _;
 use magnus::Object as _;
 
-/// The engine, shared between Ruby threads. `validate` takes the read lock and
-/// `add_file` the write lock, matching the shim's thread-safety contract.
+/// The engine, shared between Ruby threads. `validate` and `message_type?`
+/// take the read lock; `add_file` and `compile` take the write lock.
 #[magnus::wrap(class = "Protovalidate::Native::Engine", free_immediately)]
 struct Engine {
     inner: std::sync::RwLock<protovalidate_cc_sys::Engine>,
@@ -39,6 +39,37 @@ impl Engine {
             .map_err(|error| crate::to_ruby_error(ruby, error))
     }
 
+    /// Whether the engine knows the named message type.
+    fn message_type(rb_self: &Self, type_name: String) -> bool {
+        let engine = rb_self
+            .inner
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        engine.has_message_type(&type_name)
+    }
+
+    /// Compiles the rules of the named type ahead of its first validation.
+    ///
+    /// Compilation inserts into the factory's `flat_hash_map` of rules, and a
+    /// rehash there moves every entry. A concurrent `Validate` holds a pointer
+    /// into that map after releasing the factory's reader lock, so compiling
+    /// under the shared read lock could leave it reading freed memory. The
+    /// write lock keeps validations out until the insert is done.
+    fn compile(
+        ruby: &magnus::Ruby,
+        rb_self: &Self,
+        type_name: String,
+    ) -> Result<(), magnus::Error> {
+        let result = crate::gvl::without_gvl(|| {
+            let engine = rb_self
+                .inner
+                .write()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            engine.compile(&type_name)
+        });
+        result.map_err(|error| crate::to_ruby_error(ruby, error))
+    }
+
     /// Validates a serialized message of the named type, returning serialized
     /// violations or `nil` when it is valid.
     fn validate(
@@ -156,6 +187,8 @@ fn init(ruby: &magnus::Ruby) -> Result<(), magnus::Error> {
     let class = module.define_class("Engine", ruby.class_object())?;
     class.define_singleton_method("new", magnus::function!(Engine::new, 0))?;
     class.define_method("add_file", magnus::method!(Engine::add_file, 1))?;
+    class.define_method("message_type?", magnus::method!(Engine::message_type, 1))?;
+    class.define_method("compile", magnus::method!(Engine::compile, 1))?;
     class.define_method("validate", magnus::method!(Engine::validate, 3))?;
     Ok(())
 }

data/ext/protovalidate/sys/shim/pv_shim.cc

@@ -154,6 +154,43 @@ struct pv_engine {
       ABSL_GUARDED_BY(compiled_mutex);
 };
 
+namespace {
+
+const google::protobuf::Descriptor* FindMessageType(pv_engine* engine,
+                                                    absl::string_view name,
+                                                    char** error) {
+  const google::protobuf::Descriptor* descriptor =
+      engine->pool.FindMessageTypeByName(name);
+  if (descriptor == nullptr) {
+    SetError(error, absl::StrCat("unknown message type: ", name));
+  }
+  return descriptor;
+}
+
+// Compiles the rules reachable from `descriptor` unless a previous call
+// already did. Compilation holds protovalidate-cc's own writer lock, so
+// concurrent validations wait for it; only the first call per type pays.
+int EnsureCompiled(pv_engine* engine,
+                   const google::protobuf::Descriptor* descriptor,
+                   char** error) {
+  {
+    absl::ReaderMutexLock lock(&engine->compiled_mutex);
+    if (engine->compiled.contains(descriptor)) return PV_OK;
+  }
+  absl::flat_hash_set<const google::protobuf::Descriptor*> seen;
+  absl::Status compiled =
+      CompileRules(*engine->validator_factory, descriptor, seen);
+  if (!compiled.ok()) {
+    SetError(error, std::string(compiled.message()));
+    return PV_ERR_COMPILATION;
+  }
+  absl::WriterMutexLock lock(&engine->compiled_mutex);
+  engine->compiled.insert(descriptor);
+  return PV_OK;
+}
+
+}  // namespace
+
 extern "C" {
 
 pv_engine* pv_engine_new(char** error) {
@@ -192,33 +229,30 @@ int pv_engine_add_file(pv_engine* engine, const uint8_t* file_descriptor_proto,
   return PV_OK;
 }
 
+int pv_engine_has_message_type(pv_engine* engine, const char* type_name,
+                               size_t type_name_len) {
+  return engine->pool.FindMessageTypeByName(
+             absl::string_view(type_name, type_name_len)) != nullptr;
+}
+
+int pv_engine_compile(pv_engine* engine, const char* type_name,
+                      size_t type_name_len, char** error) {
+  const google::protobuf::Descriptor* descriptor =
+      FindMessageType(engine, absl::string_view(type_name, type_name_len), error);
+  if (descriptor == nullptr) return PV_ERR_ARGUMENT;
+  return EnsureCompiled(engine, descriptor, error);
+}
+
 int pv_engine_validate(pv_engine* engine, const char* type_name,
                        size_t type_name_len, const uint8_t* payload,
                        size_t payload_len, int fail_fast, uint8_t** out,
                        size_t* out_len, char** error) {
   absl::string_view name(type_name, type_name_len);
   const google::protobuf::Descriptor* descriptor =
-      engine->pool.FindMessageTypeByName(name);
-  if (descriptor == nullptr) {
-    SetError(error, absl::StrCat("unknown message type: ", name));
-    return PV_ERR_ARGUMENT;
-  }
-
-  bool known;
-  {
-    absl::ReaderMutexLock lock(&engine->compiled_mutex);
-    known = engine->compiled.contains(descriptor);
-  }
-  if (!known) {
-    absl::flat_hash_set<const google::protobuf::Descriptor*> seen;
-    absl::Status compiled =
-        CompileRules(*engine->validator_factory, descriptor, seen);
-    if (!compiled.ok()) {
-      SetError(error, std::string(compiled.message()));
-      return PV_ERR_COMPILATION;
-    }
-    absl::WriterMutexLock lock(&engine->compiled_mutex);
-    engine->compiled.insert(descriptor);
+      FindMessageType(engine, name, error);
+  if (descriptor == nullptr) return PV_ERR_ARGUMENT;
+  if (int code = EnsureCompiled(engine, descriptor, error); code != PV_OK) {
+    return code;
   }
 
   google::protobuf::Arena arena;

data/ext/protovalidate/sys/shim/pv_shim.h

@@ -60,6 +60,24 @@ void pv_engine_free(pv_engine* engine);
 int pv_engine_add_file(pv_engine* engine, const uint8_t* file_descriptor_proto,
                        size_t len, char** error);
 
+// Returns 1 when the pool knows the fully-qualified message type named by
+// `type_name` and `type_name_len`, 0 otherwise. A type can be missing after
+// its file was added when the file is one compiled into this extension and
+// the caller's copy is newer.
+int pv_engine_has_message_type(pv_engine* engine, const char* type_name,
+                               size_t type_name_len);
+
+// Compiles the rules of the fully-qualified message type named by `type_name`
+// and `type_name_len`, and of every message type reachable from its fields,
+// so that a later pv_engine_validate finds them ready. pv_engine_validate
+// compiles on demand as well; this only moves the work earlier. The name need
+// not be NUL-terminated.
+//
+// Returns PV_OK, PV_ERR_ARGUMENT for an unknown type, or PV_ERR_COMPILATION
+// with a malloc'd message in *error.
+int pv_engine_compile(pv_engine* engine, const char* type_name,
+                      size_t type_name_len, char** error);
+
 // Validates `payload`, a serialized message of the fully-qualified type named
 // by `type_name` and `type_name_len`. The name need not be NUL-terminated:
 // the pool lookup takes a string view, so callers pass their own string

data/ext/protovalidate/sys/src/lib.rs

@@ -28,6 +28,17 @@ unsafe extern "C" {
         len: usize,
         error: *mut *mut c_char,
     ) -> c_int;
+    fn pv_engine_has_message_type(
+        engine: *mut PvEngine,
+        type_name: *const c_char,
+        type_name_len: usize,
+    ) -> c_int;
+    fn pv_engine_compile(
+        engine: *mut PvEngine,
+        type_name: *const c_char,
+        type_name_len: usize,
+        error: *mut *mut c_char,
+    ) -> c_int;
     fn pv_engine_validate(
         engine: *mut PvEngine,
         type_name: *const c_char,
@@ -105,6 +116,33 @@ impl Engine {
         }
     }
 
+    /// Whether the engine's pool knows the message type `type_name`.
+    pub fn has_message_type(&self, type_name: &str) -> bool {
+        unsafe {
+            pv_engine_has_message_type(self.0, type_name.as_ptr().cast::<c_char>(), type_name.len())
+                != 0
+        }
+    }
+
+    /// Compiles the rules of `type_name` and of every message type reachable
+    /// from it, ahead of the first `validate`.
+    pub fn compile(&self, type_name: &str) -> Result<(), PvError> {
+        let mut error: *mut c_char = ptr::null_mut();
+        let code = unsafe {
+            pv_engine_compile(
+                self.0,
+                type_name.as_ptr().cast::<c_char>(),
+                type_name.len(),
+                &raw mut error,
+            )
+        };
+        if code == PV_OK {
+            Ok(())
+        } else {
+            Err(unsafe { status_error(code, error) })
+        }
+    }
+
     /// Validates a serialized message against the rules of `type_name`,
     /// returning the serialized `buf.validate.Violations`, or `None` when the
     /// message is valid.

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"
 
   # 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
 platform: ruby
 authors:
 - Sorah Fukumori