magicprotorb 0.1.0

data/DESIGN.md

@@ -0,0 +1,163 @@
+# Design
+
+`magicprotorb` is the Ruby counterpart of [magicproto](https://example.com/magicproto)
+(Python). The goal is identical: make a `.proto` file importable directly, with
+no `protoc` invocation, no checked-in generated code, and no build step in your
+edit/run loop. Only the host-language mechanics differ.
+
+## The core idea
+
+A generated protobuf file is a pure function of two things: the `.proto` source
+and the path it lives at. Checking the output into your repo creates a third,
+independent thing that has to be kept in sync by hand — and the failure mode
+everyone has hit is the generated `require`/`import` pointing somewhere the
+descriptor name doesn't actually live.
+
+`magicprotorb` removes the third thing. The require path *is* the proto path:
+
+```
+require "magicprotorb/greet/hello_pb"   <->   greet/hello.proto
+```
+
+There is exactly one source of truth (the `.proto`), and the mapping between the
+require name, the file on disk, and the descriptor's fully-qualified name is the
+identity function. They cannot drift because there is nothing to keep in sync.
+
+## The pipeline
+
+```
+require "magicprotorb/greet/hello_pb"
+        │
+        ▼
+RequireHook        claim "magicprotorb/<x>_pb" / "<x>_services_pb"; strip suffix
+        │           -> canonical proto path "greet/hello.proto"
+        ▼
+IncludePath        resolve against include roots (MAGICPROTORB_PATH, then $LOAD_PATH)
+        │
+        ▼
+Compiler._compile  Rust ext (protox) -> serialized FileDescriptorSet  [the missing piece]
+        │
+        ▼
+Registrar          decode FDS; add_serialized_file each file (dep order, idempotent);
+        │           assign Ruby constants exactly as a generated _pb.rb would
+        ▼
+ServiceBuilder     (only for _services_pb) synthesize GRPC::GenericService + Stub
+```
+
+### Why a native extension at all
+
+The stock `google-protobuf` runtime can *consume* a serialized
+`FileDescriptorSet` (`DescriptorPool#add_serialized_file`) and it ships the
+descriptor.proto message types (`Google::Protobuf::FileDescriptorSet` et al.) —
+but it cannot *produce* descriptors from `.proto` text. Compiling `.proto` is
+precisely the job of `protoc`.
+
+`magicprotorb` does that one step with [`protox`](https://crates.io/crates/protox),
+a pure-Rust protobuf compiler, wrapped in a tiny [`magnus`](https://crates.io/crates/magnus)
+extension (`ext/magicprotorb_native`). The extension exposes a single method:
+
+```ruby
+Magicprotorb::Compiler._compile(proto_path, include_dirs) # => String (serialized FileDescriptorSet)
+```
+
+Everything above that line is ordinary Ruby talking to the ordinary protobuf
+runtime. This mirrors magicproto, which wraps the same `protox` crate.
+
+### Why constants are assigned by hand
+
+`add_serialized_file` registers descriptors in the pool but does **not** create
+any Ruby constants — a generated `_pb.rb` is what does
+`HelloRequest = pool.lookup("greet.HelloRequest").msgclass`. So the `Registrar`
+walks the `FileDescriptorProto` and performs the same assignments, byte-for-byte
+compatible with `protoc`'s Ruby generator:
+
+- `package a_b.c` → nested modules `A_b`-style camelization → `AB::C`
+  (each `_`-delimited part of each segment is capitalized: `my_co` → `MyCo`).
+- messages → `lookup(full_name).msgclass`, nested messages under their parent
+  constant (`Book::Chapter`).
+- enums → `lookup(full_name).enummodule`.
+- synthetic `map<>` entry messages get no constant (protoc skips them too).
+
+The result is genuinely the same class you'd get from generated code — same
+descriptor object, same `#encode`/`#decode`, same `.name`.
+
+## Multi-package / namespacing model
+
+Two independent axes, deliberately kept separate:
+
+1. **File location** is what you import and what `protoc -I` resolves. It is
+   *not* required to match the proto `package`. Put `foo/bar.proto` where you'd
+   put `foo/bar.rb` and import `magicprotorb/foo/bar_pb`.
+
+2. **Proto `package`** is what determines the Ruby module nesting of the
+   resulting constants, via the protoc naming rule above.
+
+Because the include roots are `MAGICPROTORB_PATH` then `$LOAD_PATH`, a gem ships
+its protos under its own `lib/` and the **directory name namespaces them**: gem
+`acme` ships `lib/acme/widgets.proto`, you `require "magicprotorb/acme/widgets_pb"`,
+and a second gem physically cannot shadow it without colliding on the same
+directory. This is the `protoc -I` include model, reused verbatim.
+
+### Imports
+
+Compiling `greet/hello.proto` compiles its transitive imports too; every file in
+the returned `FileDescriptorSet` is registered into the pool (in dependency
+order, idempotently). Constants are also assigned for imported, non-well-known
+files, matching `protoc`'s behavior of emitting `require`s for each dependency.
+Well-known types (`google/protobuf/*`) are owned by the runtime and are neither
+re-registered nor re-named.
+
+## gRPC
+
+`require "magicprotorb/greet/hello_services_pb"` first does the message load
+(register + constants), then reads the service descriptors of *that file only*
+(matching `protoc`'s per-file output) and builds, for each service:
+
+```ruby
+module Greet
+  module Greeter
+    class Service
+      include GRPC::GenericService
+      self.marshal_class_method   = :encode
+      self.unmarshal_class_method = :decode
+      self.service_name = "greet.Greeter"
+      rpc :SayHello, Greet::HelloRequest, Greet::HelloReply
+      rpc :SayHelloStream, Greet::HelloRequest, stream(Greet::HelloReply)
+    end
+    Stub = Service.rpc_stub_class
+  end
+end
+```
+
+`require "grpc"` is lazy, so message-only users never load it. Streaming sides
+are wrapped with the DSL's `stream(...)`, exactly as generated code does.
+
+## Idempotency & concurrency
+
+- Compilation results are memoized per canonical proto path.
+- `add_serialized_file` rejects duplicate file names; the `Registrar` tracks
+  loaded files and also rescues that specific error, so re-requiring, shared
+  imports, and pre-registered well-known types are all no-ops.
+- A re-`require` of an already-loaded module returns `false`, like `Kernel#require`.
+- A process-wide mutex serializes the pool mutations.
+
+## Limitations
+
+- **A compiler is needed at *install* time.** The Rust extension is compiled
+  when the gem installs (a Rust toolchain / `cargo` must be present). The point
+  of magicprotorb is removing `protoc` from your *edit/run* loop, not removing
+  all native build steps; the trade is "compile a small Rust crate once at
+  install" for "never run protoc again."
+- **Constants appear at require time, not parse time.** Editors/static analyzers
+  that don't execute the require won't see `Greet::HelloRequest`. This is
+  inherent to runtime code generation (same caveat as magicproto).
+- **The hook only claims `magicprotorb/…_pb` / `…_services_pb`.** Anything else
+  (including the native extension and the version file) falls straight through to
+  the real `require`.
+- **One descriptor pool.** Everything registers into
+  `DescriptorPool.generated_pool`, exactly like generated code; two different
+  protos defining the same fully-qualified type still conflict, just as they
+  would with `protoc`.
+- **`required_ruby_version >= 3.0`**; descriptor types are loaded via
+  `google/protobuf/descriptor_pb`, which is required explicitly for compatibility
+  with protobuf 4.x where it is not auto-loaded.

data/README.md

@@ -0,0 +1,124 @@
+# magicprotorb
+
+Import `.proto` files directly in Ruby. No `protoc`, no generated `_pb.rb` files, no build step:
+
+```ruby
+require "magicprotorb"                          # installs the import hook
+require "magicprotorb/greet/hello_pb"           # compiles greet/hello.proto
+require "magicprotorb/greet/hello_services_pb"  # + synthesizes the gRPC stub
+
+req  = Greet::HelloRequest.new(name: "world")
+stub = Greet::Greeter::Stub.new("localhost:50051", :this_channel_is_insecure)
+```
+
+`require "magicprotorb/greet/hello_pb"` compiles `greet/hello.proto` (found on
+`MAGICPROTORB_PATH` / `$LOAD_PATH`) at require time and defines the message
+constants. The dotted require path mirrors the canonical proto path 1:1, so the
+require name, the file location, and the descriptor name can never drift apart —
+the classic "the generated import points at the wrong place" problem cannot occur.
+
+## How it works
+
+A `Kernel#require` hook claims names under `magicprotorb/` that end in `_pb` or
+`_services_pb` (only).
+
+- `magicprotorb/greet/hello_pb` → canonical `greet/hello.proto`, located on the
+  include roots (the `protoc -I` model: `MAGICPROTORB_PATH` then `$LOAD_PATH`).
+- A small Rust extension (`magicprotorb_native`, built on the pure-Rust
+  [`protox`](https://crates.io/crates/protox) compiler) turns the `.proto` into a
+  serialized `FileDescriptorSet` — the one thing the stock protobuf runtime can't
+  do itself.
+- Those descriptors are registered through the stock
+  `Google::Protobuf::DescriptorPool.generated_pool#add_serialized_file`, and the
+  message/enum constants are assigned exactly the way a generated `_pb.rb` does,
+  so the message classes are indistinguishable from generated ones.
+- `_services_pb` modules are synthesized directly from the service descriptors as
+  ordinary `GRPC::GenericService` classes (`require "grpc"` happens lazily).
+
+See [DESIGN.md](DESIGN.md) for the full rationale, the multi-package namespacing
+model, and the limitations.
+
+## Where to put protos
+
+Put `foo/bar.proto` where you'd want `foo/bar.rb`, and import it as
+`magicprotorb/foo/bar_pb`.
+
+A library ships its protos as data inside its own `lib/` directory (already on
+`$LOAD_PATH`); the directory name namespaces them, so two installed gems can't
+collide.
+
+### Finding your protos (include roots)
+
+magicprotorb resolves a proto by its canonical path against the include roots —
+`MAGICPROTORB_PATH` first, then `$LOAD_PATH` — exactly like `protoc -I`. Note that
+Ruby does **not** put the current directory on `$LOAD_PATH`, so a proto sitting
+next to your script isn't found automatically. Make its directory an include root:
+
+```ruby
+require "magicprotorb"
+$LOAD_PATH.unshift __dir__         # this script's dir is now an include root
+require "magicprotorb/keyvalue_pb" # resolves ./keyvalue.proto
+```
+
+or point `MAGICPROTORB_PATH` at it from the shell:
+
+```sh
+MAGICPROTORB_PATH="$PWD" ruby my_script.rb
+```
+
+
+## Naming
+
+| require | compiles | gives you |
+| --- | --- | --- |
+| `magicprotorb/greet/hello_pb` | `greet/hello.proto` | `Greet::HelloRequest`, ... |
+| `magicprotorb/greet/hello_services_pb` | `greet/hello.proto` | `Greet::Greeter::Service` / `::Stub` |
+
+The proto `package` becomes the Ruby module path the same way `protoc`'s Ruby
+generator does it: `package my_co.sub_pkg.v1;` → `MyCo::SubPkg::V1`.
+
+There is also a programmatic API equivalent to the requires:
+
+```ruby
+Magicprotorb.import("greet/hello")           # like require "magicprotorb/greet/hello_pb"
+Magicprotorb.import_services("greet/hello")  # like require "magicprotorb/greet/hello_services_pb"
+Magicprotorb.include_paths                   # the roots currently searched
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "magicprotorb"
+```
+
+Building the gem compiles the bundled Rust extension, so a Rust toolchain
+(`cargo`) is required at install time. The runtime needs only `google-protobuf`
+(and `grpc`, if you import services).
+
+### Installing from a local checkout
+
+```sh
+bundle exec rake install      # builds the gem and installs it (native ext included)
+```
+
+After this, `require "magicprotorb"` works from any script without `-I`. The gem
+installs into whichever Ruby is active (`rbenv`/`rvm`), so install under the same
+Ruby you'll run with.
+
+> The `install` task deliberately runs `gem install` **outside** the bundle
+> (`Bundler.with_unbundled_env`). A native-extension gem whose own gemspec is the
+> bundle's path gem otherwise fails to build at install time, because RubyGems'
+> per-extension build dir goes missing under `bundle exec`.
+
+## Development
+
+After checking out the repo:
+
+```sh
+bin/setup          # install dependencies
+bundle exec rake   # compile the extension, then run the tests
+```
+
+`bundle exec rake compile` builds `ext/magicprotorb_native` into
+`lib/magicprotorb/`. The fixture protos live in `test/protos`.

data/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rb_sys/extensiontask"
+
+GEMSPEC = Gem::Specification.load("magicprotorb.gemspec")
+
+# Builds ext/magicprotorb_native and drops the artifact in lib/magicprotorb/.
+RbSys::ExtensionTask.new("magicprotorb_native", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/magicprotorb"
+end
+
+Rake::TestTask.new(test: :compile) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+# bundler/gem_tasks defines `install`, but it shells out to `gem install` while
+# still inside the bundle. Because this gem's own gemspec is the bundle's path
+# gem, that breaks the native-extension build at install time (RubyGems' build
+# staging dir, ext/.../.gem.<ts>, ends up missing). Re-run the install outside
+# the bundle, where `gem install` of our compiled .gem works correctly.
+Rake::Task["install"].clear
+desc "Build magicprotorb and install it (native extension compiled outside the bundle)"
+task install: :build do
+  gem_file = "pkg/#{GEMSPEC.full_name}.gem"
+  Bundler.with_unbundled_env do
+    sh "gem", "install", gem_file
+  end
+end
+
+task default: %i[compile test]

data/ext/magicprotorb_native/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "magicprotorb_native"
+version = "0.1.0"
+edition = "2021"
+publish = false
+autobins = false
+
+# The compiled artifact is loaded by Ruby as `magicprotorb/magicprotorb_native`.
+# It deliberately does NOT end in `_pb`, so the require hook never claims it.
+[lib]
+name = "magicprotorb_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+# Ruby <-> Rust bindings.
+magnus = "0.7"
+# Pure-Rust protobuf *compiler* — the one thing the stock protobuf runtime
+# cannot do itself (turns .proto text into a FileDescriptorSet).
+protox = "0.9"
+# protox builds on prost's descriptor types; keep these in lockstep with it.
+prost = "0.14"
+prost-types = "0.14"

data/ext/magicprotorb_native/extconf.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+# Builds the Rust crate and installs the artifact as
+# lib/magicprotorb/magicprotorb_native.<dlext>.
+create_rust_makefile("magicprotorb/magicprotorb_native")

data/ext/magicprotorb_native/src/lib.rs

@@ -0,0 +1,35 @@
+//! The native half of magicprotorb.
+//!
+//! Exactly one job: take a canonical proto path plus a list of include roots
+//! (the `protoc -I` model) and return a *serialized `FileDescriptorSet`* — the
+//! same bytes a `protoc --descriptor_set_out` invocation would emit, and the
+//! same bytes the stock Ruby protobuf runtime knows how to register via
+//! `DescriptorPool#add_serialized_file`.
+//!
+//! The compiler is `protox`, a pure-Rust protobuf compiler, so there is no
+//! dependency on a `protoc` binary at run time.
+
+use magnus::{function, prelude::*, Error, RString, Ruby};
+use prost::Message;
+
+/// Compile `file` (resolved against `includes`) and return the serialized
+/// `FileDescriptorSet`, transitive dependencies included, as a binary string.
+fn compile(ruby: &Ruby, file: String, includes: Vec<String>) -> Result<RString, Error> {
+    let fds = protox::compile([file], includes).map_err(|e| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("magicprotorb: failed to compile proto: {e}"),
+        )
+    })?;
+    Ok(RString::from_slice(&fds.encode_to_vec()))
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Magicprotorb")?;
+    let compiler = module.define_class("Compiler", ruby.class_object())?;
+    // Underscore-prefixed: the Ruby Compiler wrapper adds path resolution and
+    // error context on top of this raw call.
+    compiler.define_singleton_method("_compile", function!(compile, 2))?;
+    Ok(())
+}

data/lib/magicprotorb/include_path.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Magicprotorb
+  # Resolves canonical proto paths against include roots, mirroring the
+  # `protoc -I` model: MAGICPROTORB_PATH first, then Ruby's $LOAD_PATH.
+  #
+  # This is the Ruby analogue of magicproto's "MAGICPROTO_PATH then sys.path":
+  # a library ships its protos as package data under its own lib directory, that
+  # directory is already on $LOAD_PATH, and the directory name namespaces the
+  # protos so two installed gems can't collide.
+  module IncludePath
+    ENV_VAR = "MAGICPROTORB_PATH"
+
+    module_function
+
+    # Ordered, de-duplicated list of existing directories to search, highest
+    # priority first. These become the `-I` include roots handed to the compiler.
+    def roots
+      raw = []
+      if (env = ENV.fetch(ENV_VAR, nil)) && !env.empty?
+        raw.concat(env.split(File::PATH_SEPARATOR))
+      end
+      raw.concat($LOAD_PATH)
+
+      seen = {}
+      raw.each_with_object([]) do |dir, out|
+        next if dir.nil? || dir.to_s.empty?
+
+        path = File.expand_path(dir.to_s)
+        next if seen[path] || !File.directory?(path)
+
+        seen[path] = true
+        out << path
+      end
+    end
+
+    # The first root under which +proto_path+ exists, or nil. Used to produce a
+    # LoadError-shaped failure before invoking the compiler.
+    def resolve(proto_path)
+      roots.find { |root| File.file?(File.join(root, proto_path)) }
+    end
+  end
+end

data/lib/magicprotorb/loader.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Magicprotorb
+  # Orchestrates a single import: resolve -> compile -> register (-> services).
+  # Compilation results are memoized per canonical proto path; a process-wide
+  # mutex serializes the descriptor-pool mutations.
+  module Loader
+    MUTEX = Mutex.new
+    @compiled = {}
+
+    module_function
+
+    # Register messages/enums for +proto_path+ (and its imports). Idempotent.
+    def load_messages(proto_path)
+      MUTEX.synchronize { Registrar.register(compile(proto_path)) }
+    end
+
+    # As load_messages, plus synthesize gRPC Service/Stub for the proto's own
+    # services (not those of its imports — matching protoc's per-file output).
+    def load_services(proto_path)
+      MUTEX.synchronize do
+        fds = compile(proto_path)
+        Registrar.register(fds)
+        primary = fds.file.find { |file| file.name == proto_path } || fds.file.last
+        ServiceBuilder.build(primary)
+      end
+    end
+
+    # Compile +proto_path+ to a FileDescriptorSet via the native protox-backed
+    # compiler, using the current include roots. Memoized.
+    def compile(proto_path)
+      @compiled[proto_path] ||= begin
+        if IncludePath.resolve(proto_path).nil?
+          raise LoadError,
+                "magicprotorb: cannot find #{proto_path} on #{IncludePath::ENV_VAR} or $LOAD_PATH"
+        end
+
+        bytes =
+          begin
+            Compiler._compile(proto_path, IncludePath.roots)
+          rescue StandardError => e
+            raise CompileError, e.message
+          end
+
+        Google::Protobuf::FileDescriptorSet.decode(bytes)
+      end
+    end
+  end
+end

data/lib/magicprotorb/naming.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Magicprotorb
+  # Translates proto identifiers into Ruby constant names exactly the way
+  # protoc's Ruby generator does, so the constants magicprotorb synthesizes are
+  # identical to those a checked-in `*_pb.rb` would define.
+  #
+  #   package my_co.sub_pkg.v1  ->  MyCo::SubPkg::V1
+  #   message OuterMsg          ->  OuterMsg            (nested under its parent)
+  #
+  # Each dot-separated package segment is split on "_" and each part is
+  # capitalized (my_co -> MyCo, v1 -> V1); message/enum names keep their own
+  # casing with only the first letter forced upper.
+  module Naming
+    module_function
+
+    # ["MyCo", "SubPkg", "V1"] for "my_co.sub_pkg.v1"; [] for an empty package.
+    def package_modules(package)
+      return [] if package.nil? || package.empty?
+
+      package.split(".").map { |segment| camelize(segment) }
+    end
+
+    def camelize(segment)
+      segment.split("_").map { |part| part.empty? ? "" : part[0].upcase + part[1..] }.join
+    end
+
+    # Constant name for a message/enum simple name (first letter upper).
+    def constant_name(simple_name)
+      simple_name[0].upcase + simple_name[1..]
+    end
+  end
+end

data/lib/magicprotorb/registrar.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "google/protobuf"
+require "google/protobuf/descriptor_pb"
+
+module Magicprotorb
+  # Takes a compiled FileDescriptorSet and registers it through the *stock*
+  # protobuf machinery — DescriptorPool.generated_pool#add_serialized_file plus
+  # the same constant assignments a generated `*_pb.rb` performs. The resulting
+  # message classes are therefore indistinguishable from generated ones.
+  module Registrar
+    # The protobuf runtime already owns google/protobuf/*; never re-register or
+    # assign constants for those (it would clobber Google::Protobuf::Timestamp
+    # and friends, and add_serialized_file would reject the duplicate).
+    WELL_KNOWN_PREFIX = "google/protobuf/"
+
+    @loaded_files = {}
+
+    module_function
+
+    # Register every file in the set (dependency-ordered by the compiler), then
+    # assign Ruby constants for each non-well-known file. Idempotent.
+    def register(file_descriptor_set)
+      pool = Google::Protobuf::DescriptorPool.generated_pool
+      file_descriptor_set.file.each { |file| register_file(pool, file) }
+    end
+
+    def register_file(pool, file)
+      name = file.name
+      return if @loaded_files[name]
+
+      begin
+        pool.add_serialized_file(file.to_proto)
+      rescue Google::Protobuf::TypeError => e
+        # Already present (a well-known type, or a shared import registered by a
+        # previously imported proto). Anything else is a real error.
+        raise unless e.message.include?("duplicate file name")
+      end
+
+      @loaded_files[name] = true
+      assign_constants(pool, file) unless name.start_with?(WELL_KNOWN_PREFIX)
+    end
+
+    # --- constant assignment (mirrors protoc's Ruby generator) ----------------
+
+    def assign_constants(pool, file)
+      package = file.package
+      scope = ensure_module(Naming.package_modules(package))
+      file.message_type.each { |msg| assign_message(pool, scope, package, msg) }
+      file.enum_type.each { |enum| assign_enum(pool, scope, package, enum.name) }
+    end
+
+    def assign_message(pool, parent, scope_fullname, msg)
+      full_name = qualify(scope_fullname, msg.name)
+      klass = pool.lookup(full_name).msgclass
+      set_const(parent, Naming.constant_name(msg.name), klass)
+
+      # Synthetic map-entry messages get no constant (protoc skips them too).
+      msg.nested_type.each do |nested|
+        next if nested.options&.map_entry
+
+        assign_message(pool, klass, full_name, nested)
+      end
+      msg.enum_type.each { |enum| assign_enum(pool, klass, full_name, enum.name) }
+    end
+
+    def assign_enum(pool, parent, scope_fullname, enum_name)
+      full_name = qualify(scope_fullname, enum_name)
+      set_const(parent, Naming.constant_name(enum_name), pool.lookup(full_name).enummodule)
+    end
+
+    # --- helpers --------------------------------------------------------------
+
+    def qualify(scope, name)
+      scope.nil? || scope.empty? ? name : "#{scope}.#{name}"
+    end
+
+    # Walk/create a chain of modules (e.g. %w[MyCo SubPkg V1]) under Object,
+    # returning the innermost. An empty list returns Object (no-package case).
+    def ensure_module(segments)
+      segments.reduce(Object) do |parent, segment|
+        if parent.const_defined?(segment, false)
+          parent.const_get(segment, false)
+        else
+          mod = Module.new
+          parent.const_set(segment, mod)
+          mod
+        end
+      end
+    end
+
+    def set_const(parent, name, value)
+      parent.const_set(name, value) unless parent.const_defined?(name, false)
+    end
+  end
+end

data/lib/magicprotorb/require_hook.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Magicprotorb
+  # Prepended onto Kernel so that a bare `require "magicprotorb/<proto>_pb"`
+  # compiles and registers <proto>.proto at require time. This is the Ruby
+  # counterpart to magicproto's sys.meta_path finder.
+  #
+  # Only names under "magicprotorb/" that end in "_pb" / "_services_pb" are
+  # claimed; everything else (including the native extension and version file)
+  # falls through to the real require via super.
+  module RequireHook
+    PREFIX = "magicprotorb/"
+    MUTEX = Mutex.new
+    @required = {}
+
+    def require(name)
+      handled = RequireHook.dispatch(name)
+      handled.nil? ? super : handled
+    end
+
+    # Returns true (loaded now), false (already loaded), or nil (not ours).
+    def self.dispatch(name)
+      return nil unless name.is_a?(String) && name.start_with?(PREFIX)
+
+      rest = name[PREFIX.length..]
+      if rest.end_with?("_services_pb")
+        proto = "#{rest.delete_suffix("_services_pb")}.proto"
+        loader = :load_services
+      elsif rest.end_with?("_pb")
+        proto = "#{rest.delete_suffix("_pb")}.proto"
+        loader = :load_messages
+      else
+        return nil
+      end
+
+      MUTEX.synchronize do
+        return false if @required[name]
+
+        Loader.public_send(loader, proto)
+        @required[name] = true
+      end
+      true
+    end
+  end
+end