gritz-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cdb05adc6d6f492115eb0e7d9de033bd3e4509a65f60db732377e254b7f28d5f
+  data.tar.gz: 927579595d4645896cac9dfe6f8514ccd2e52abf94ad10f1cb77c07158dff833
+SHA512:
+  metadata.gz: dac749d3fc8f50ac2716e3de2557f5fd62b9cb61cd62c5fdfaa0a37dbaa76d690279a4de3cf8cd0baf53128878e08cbe7228e940317f7ab2b1c8a896f08ec6f1
+  data.tar.gz: 02d442a42de49ba6a6c0a27587e74b380f510c6baebb28b9ab6c79318774cb75cd1f878f6af4c08d856d8923cd0b9081b5b2f7e31ae7ef34e721bbb8d832a21f

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ydah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,59 @@
+# Gritz Rails
+
+Rails integration for [Gritz](https://github.com/gritzrpc/gritz): RPC controller loading, generators, complete-RPC execution and single-process development reloading. Requires CRuby 3.3+, Rails 8.0 or 8.1, and Gritz 0.5.0. Runtime dependencies are `gritz-core` and `railties`; applications choose their transport separately.
+
+## Install
+
+```ruby
+gem "gritz", "~> 0.5.0"
+gem "gritz-rails", "~> 0.1.0"
+```
+
+The first `gritz-rails` release is prepared for the project owner. Until it is published, use `gem "gritz-rails", git: "https://github.com/gritzrpc/gritz-rails.git", branch: "main"`.
+
+```sh
+bin/rails generate gritz:install
+# Generate protobufs into lib/protos, then generate a bound controller:
+bin/rails generate gritz:controller Greeter SayHello --service Helloworld::Greeter::Service
+bin/gritz routes
+bin/gritz check
+bin/gritz start
+```
+
+Implement each generated action using `request.message` or `request.each_message`, and `stream.write` for response streams. The controller generator accepts RPC names and `--service` names; it adds the controller to `config/gritz.rb`. Set `strict_routes true` after all actions are implemented.
+
+## Rails lifecycle
+
+Generated `config/gritz.rb` loads the application through `rails_app`, selects four workers in production and zero elsewhere, and registers controllers. Additional settings come after `rails_app`, including explicit `reflection false` or `true`. Rails development enables Reflection by default; other environments keep the core's disabled default.
+
+Every complete application RPC runs inside the Rails executor. Development uses the Rails reloader and resolves controller constants after reload. Active Record connections return to their pools, query caches finish and CurrentAttributes reset on successful and failed calls. Application threads created inside a handler must use Rails' own executor wrapping. See the [Rails execution guide](https://guides.rubyonrails.org/threading_and_code_execution.html).
+
+Application code is eager loaded before fork. In prefork mode, all Active Record pools disconnect after eager loading, before Ruby warmup, and again before each fork. Ruby's Rails fork tracking remains active. Development reloading requires `workers 0`; changing protobuf definitions, bound services or registered routes requires a server restart. Production code changes use Gritz's `USR2` fresh-interpreter replacement.
+
+`app/rpc` participates in Rails autoloading and eager loading. Generated protobuf files in `lib/protos` are excluded from both Zeitwerk loaders and required explicitly by the generated initializer. Keep generated files outside normal autoload directories.
+
+For an already initialized application, use `Gritz::Rails.install(config, application: Rails.application)` once before starting the server. Match Active Record pool capacity to RPC concurrency with `RAILS_MAX_THREADS` or your database configuration.
+
+## Examples and migration
+
+The [Rails catalog sample](examples/rails_app) serves SQLite-backed unary and streaming RPCs with four production workers. It includes the [memory validation](docs/reports/T5-07-rails-memory.md).
+
+Existing Gruf applications can use the optional `Gritz::Compat::Gruf` controller and interceptor adapter in `gritz-core`. See the [migration guide](https://github.com/gritzrpc/gritz-core/blob/main/docs/guides/migrating-from-gruf.md).
+
+## Development
+
+```sh
+bundle install
+COVERAGE=1 bundle exec rake
+bundle exec rubocop
+bundle exec bundler-audit check --update
+bundle exec rake build
+```
+
+CI tests Ruby 3.3, 3.4 and 4.0 against Rails 8.0 and 8.1. Tests include real RPCs, file-change reloading, all-pool fork cleanup, executable generated configuration and Linux four-worker sample lifecycle. Sibling checkout overrides follow [CONTRIBUTING.md](CONTRIBUTING.md).
+
+The initial package is `pkg/gritz-rails.gem`. Stop before its first tag/publication and configure [Trusted Publishing](docs/guides/releasing.md) after the owner releases it.
+
+## License
+
+[MIT](LICENSE.txt).

data/lib/generators/gritz/controller/controller_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Gritz
+  module Generators
+    # Generates a controller bound to an application's generated service.
+    # @api public
+    class ControllerGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+      desc "Generate an RPC controller and register it in config/gritz.rb."
+      argument :actions, type: :array, default: [], banner: "RPC_ACTIONS"
+      class_option :service, type: :string, desc: "Generated service class (defaults to NAME::Service)"
+
+      def create_controller
+        raise Thor::Error, "service must be a Ruby constant name" unless /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/.match?(service_class_name)
+        unless actions.all? { |action| /\A[a-z_]\w*\z/.match?(action.underscore) }
+          raise Thor::Error, "action must be a Ruby method name"
+        end
+
+        template "controller.rb.tt", "app/rpc/#{file_path}_controller.rb"
+        append_to_file "config/gritz.rb", "\nregister_controller #{class_name}Controller\n"
+      end
+
+      private
+
+      def service_class_name
+        (options[:service] || "#{class_name}::Service").delete_prefix("::")
+      end
+    end
+  end
+end

data/lib/generators/gritz/controller/templates/controller.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Controller < Gritz::Controller
+  bind ::<%= service_class_name %>
+<% actions.each do |action| -%>
+
+  def <%= action.underscore %>
+    fail!(:unimplemented, "Implement <%= action.underscore %>")
+  end
+<% end -%>
+end

data/lib/generators/gritz/install/install_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Gritz
+  module Generators
+    # Creates the configuration and binstub for a Rails RPC server.
+    # @api public
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Install Gritz configuration, protobuf loading, and bin/gritz."
+
+      def install
+        template "gritz.rb", "config/gritz.rb"
+        copy_file "initializer.rb", "config/initializers/gritz.rb"
+        copy_file "gritz", "bin/gritz"
+        chmod "bin/gritz", 0o755
+        empty_directory "lib/protos"
+        create_file "lib/protos/.keep"
+        empty_directory "app/rpc"
+        create_file "app/rpc/.keep"
+      end
+    end
+  end
+end

data/lib/generators/gritz/install/templates/gritz

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "gritz/rails"
+
+exit Gritz::CLI.new(launch: true).run(ARGV)

data/lib/generators/gritz/install/templates/gritz.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "gritz/rails"
+
+rails_app
+workers ::Rails.env.production? ? 4 : 0 # rubocop:disable Style/RedundantConstantBase -- The config is evaluated inside Gritz::DSL.
+threads 16
+
+# Add controllers with: bin/rails generate gritz:controller Greeter SayHello --service Example::Greeter::Service

data/lib/generators/gritz/install/templates/initializer.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# protoc output does not follow Zeitwerk's naming rules.
+$LOAD_PATH.unshift Rails.root.join("lib/protos").to_s
+Dir[Rails.root.join("lib/protos/**/*_pb.rb")].each { |path| require path }

data/lib/gritz/rails/executor.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Rails
+    # Keeps Rails resources and reload interlocks scoped to the entire RPC.
+    # @api public
+    class Executor
+      def initialize(app, application:, development: false)
+        @app = app
+        @executor = development ? application.reloader : application.executor
+      end
+
+      def call(context)
+        @executor.wrap { @app.call(context) }
+      end
+    end
+  end
+end

data/lib/gritz/rails/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Rails
+    # Adds RPC controllers to Rails loading while keeping protoc output explicit.
+    # @api private
+    class Railtie < ::Rails::Railtie
+      initializer "gritz.paths", before: :set_autoload_paths do |application|
+        application.config.paths.add("app/rpc", eager_load: true)
+        application.autoloaders.each { |loader| loader.ignore(application.root.join("lib/protos")) }
+      end
+    end
+  end
+end

data/lib/gritz/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/gritz/rails.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "gritz/core"
+require "rails"
+require "active_support/fork_tracker"
+require_relative "rails/version"
+require_relative "rails/executor"
+require_relative "rails/railtie"
+
+module Gritz
+  module Rails
+    # Installs Rails execution and fork lifecycle hooks into one server configuration.
+    # @api public
+    def self.install(config, application: ::Rails.application)
+      raise ConfigurationError, "rails_app requires an initialized Rails application" unless application&.initialized?
+
+      installed = config.middleware.entries.find { |entry| entry.middleware == Executor }
+      if installed
+        raise ConfigurationError, "Rails integration is already installed for another application" unless installed.options[:application].equal?(application)
+
+        return config
+      end
+
+      development = ::Rails.env.development?
+      config.reflection = true if development
+      first = config.middleware.entries.first
+      if first
+        config.middleware.insert_before(first.middleware, Executor, application:, development:)
+      else
+        config.middleware.use(Executor, application:, development:)
+      end
+      disconnect_pools = lambda do |_index = nil|
+        if defined?(ActiveRecord::Base)
+          ActiveRecord::Base.connection_handler.connection_pool_list(:all).each(&:disconnect!)
+        end
+      end
+      config.add_preloader do
+        raise ConfigurationError, "Rails development mode requires workers 0" if development && config.workers.positive?
+
+        application.eager_load!
+        config.controllers.map! { |controller| reloadable_controller(controller) } if development
+        disconnect_pools.call if config.workers.positive?
+      end
+      config.add_hook(:before_fork, &disconnect_pools)
+      config
+    end
+
+    # Route descriptors stay fixed, while the controller constant is resolved after Rails reloads.
+    # @api private
+    def self.reloadable_controller(controller)
+      name = controller.name
+      raise ConfigurationError, "Rails development mode requires a named controller" unless name
+
+      Class.new(Gritz::Controller) do
+        bind controller.service_class
+        define_singleton_method(:name) { name }
+        define_singleton_method(:to_s) { name }
+        define_singleton_method(:action_defined?) { |action| name.constantize.action_defined?(action) }
+        define_singleton_method(:new) { |**options| name.constantize.new(**options) }
+      end
+    end
+
+    # @api public
+    module ConfigurationDSL
+      def rails_app(path = "config/environment.rb")
+        require File.expand_path(path)
+        Gritz::Rails.install(@config)
+      end
+    end
+  end
+end
+
+Gritz::DSL.include(Gritz::Rails::ConfigurationDSL)

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: gritz-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gritz-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Rails autoloading, RPC execution, generators and safe preloading for
+  Gritz.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/gritz/controller/controller_generator.rb
+- lib/generators/gritz/controller/templates/controller.rb.tt
+- lib/generators/gritz/install/install_generator.rb
+- lib/generators/gritz/install/templates/gritz
+- lib/generators/gritz/install/templates/gritz.rb
+- lib/generators/gritz/install/templates/initializer.rb
+- lib/gritz/rails.rb
+- lib/gritz/rails/executor.rb
+- lib/gritz/rails/railtie.rb
+- lib/gritz/rails/version.rb
+homepage: https://github.com/gritzrpc/gritz-rails
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/gritzrpc/gritz-rails/
+  source_code_uri: https://github.com/gritzrpc/gritz-rails
+  changelog_uri: https://github.com/gritzrpc/gritz-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Rails integration for Gritz RPC servers
+test_files: []