gritz-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9d69bbe23da7b5ec3c973bdbe3a2c2c1d1596b6632695f446ae6fb242d0d1f94
+  data.tar.gz: 89929d525c1709e164057aa7d684317db596734395371cf942019832cf7189bd
+SHA512:
+  metadata.gz: c4c61c0a88eedb466c3f556f9cd9861468f496b0ba6303be58133d58c6761d8d6fa6a1a9c4b51e7dd6bec168b8207aa8b82562d096f0ead5f8745e351a67c790
+  data.tar.gz: 5e7d9a717648f45c0f3774f3de35511608d6b6fa7fc5fc6f6be61fbf4d7b874c1cfafdd348b9441e0f37a528a30d341f3eddfa45aa50760255a42f7b644a58cf

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 Yudai Takada
+
+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,28 @@
+# Gritz Core
+
+Transport-independent controllers, routing, middleware, configuration and network-free testing for Ruby gRPC applications. Requires CRuby 3.3 or later. This gem has no grpc dependency and never loads a transport by itself.
+
+```ruby
+require "gritz/core"
+```
+
+Use [gritz](https://github.com/gritzrpc/gritz) for the default framework and executable, or combine this gem with [gritz-native](https://github.com/gritzrpc/gritz-native) for the official grpc gem adapter. The Fiber adapter `gritz-async` is planned.
+
+Controller tests can load `gritz/testing/rspec` or `gritz/testing/minitest` and run without a network or the grpc gem. See the [controller examples](https://github.com/gritzrpc/gritz#controllers) and [configuration guide](docs/guides/configuration.md).
+
+## Development
+
+```sh
+git clone https://github.com/gritzrpc/gritz-core.git
+cd gritz-core
+bundle install
+COVERAGE=1 bundle exec rake
+bundle exec rubocop
+bundle exec rake build
+```
+
+Tests, lint and packaging run independently in this repository. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) and the [release guide](docs/guides/releasing.md).
+
+## License
+
+[MIT](LICENSE.txt).

data/lib/gritz/call.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Contract implemented by transports and in-memory RPC calls.
+  # @api public
+  module Call
+    def method_descriptor = raise NotImplementedError
+    def metadata = raise NotImplementedError
+    def deadline = nil
+    def peer = nil
+    def peer_identity = nil
+    def cancelled? = false
+    def read = raise NotImplementedError
+    def write(message) = raise NotImplementedError
+    def send_initial_metadata(metadata = {}) = raise NotImplementedError
+    def merge_initial_metadata(metadata = {}) = send_initial_metadata(metadata)
+    def trailing_metadata = raise NotImplementedError
+
+    def each_message
+      return enum_for(__method__) unless block_given?
+
+      while (message = read)
+        yield message
+      end
+    end
+  end
+end

data/lib/gritz/cli.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "logger"
+
+module Gritz
+  # Command line entry point for the single-process server and route listing.
+  # @api public
+  class CLI
+    def initialize(stdout: $stdout, stderr: $stderr, env: ENV)
+      @stdout = stdout
+      @stderr = stderr
+      @env = env
+    end
+
+    def run(argv)
+      args = argv.dup
+      path = nil
+      overrides = {}
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: gritz [start|routes] [-C config/gritz.rb] [options]"
+        options.on("-C", "--config PATH", "Configuration file") { |value| path = value }
+        options.on("--workers N", Integer) { |value| overrides[:workers] = value }
+        options.on("--threads N", Integer) { |value| overrides[:threads] = value }
+        options.on("--bind ADDRESS") { |value| overrides[:bind] = value }
+        options.on("--strict-routes") { overrides[:strict_routes] = true }
+        options.on("-v", "--version") {
+          @stdout.puts(Core::VERSION)
+          return 0
+        }
+        options.on("-h", "--help") {
+          @stdout.puts(options)
+          return 0
+        }
+      end
+      parser.parse!(args)
+      command = args.shift || "start"
+      raise ConfigurationError, "Unknown command #{command}" unless %w[start routes].include?(command)
+      raise ConfigurationError, "Unexpected argument #{args.first}" unless args.empty?
+
+      path ||= "config/gritz.rb" if File.file?("config/gritz.rb")
+      config = Configuration.load(path: path, env: @env, overrides: overrides)
+      config.validate_single_process! if command == "start"
+      config.preload! if config.preload_app?
+      logger = Logger.new(@stdout)
+      logger.formatter = ->(_severity, _time, _progname, message) { "#{message}\n" }
+      router = Router.new(controllers: config.controllers, strict: config.strict_routes, logger: logger)
+      if command == "routes"
+        router.routes.each_value do |route|
+          @stdout.puts "#{route.full_name} #{route.kind} #{route.controller}##{route.action}"
+        end
+      else
+        start(config, router, logger)
+      end
+      0
+    rescue ConfigurationError, OptionParser::ParseError, ArgumentError, Errno::ENOENT, SyntaxError, LoadError => e
+      @stderr.puts "gritz: #{e.message}"
+      1
+    end
+
+    private
+
+    def start(config, router, logger)
+      @stdout.sync = true if @stdout.respond_to?(:sync=)
+      # Load the adapter only when starting; route inspection stays transport-independent.
+      require "gritz/native"
+      dispatcher = Dispatcher.new(router: router, middleware: config.middleware, logger: logger)
+      adapter = Transport::Native.new(config: config, dispatcher: dispatcher, logger: logger)
+      signals = []
+      previous = %w[TERM INT QUIT].to_h { |name| [name, Signal.trap(name) { signals << name }] }
+      config.run_hooks(:on_worker_boot, 0)
+      port = adapter.bind(config.bind)
+      adapter.start
+      logger.info("Gritz #{Core::VERSION} listening on #{config.bind.sub(/:\d+\z/, ":#{port}")}")
+      while signals.empty?
+        sleep 0.05
+        raise ConfigurationError, "gRPC server stopped unexpectedly" unless adapter.running?
+      end
+      signals.shift == "QUIT" ? adapter.kill : adapter.stop(deadline: Time.now + config.shutdown_timeout)
+    ensure
+      previous&.each { |name, handler| Signal.trap(name, handler) }
+      adapter&.kill if adapter&.running?
+      config.run_hooks(:on_worker_shutdown, 0)
+    end
+  end
+end

data/lib/gritz/configuration.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gritz
+  # Startup settings. Process-related settings are reserved for the supervisor.
+  # @api public
+  class Configuration
+    DEFAULTS = {
+      workers: 0, threads: 16, max_waiting_requests: 64,
+      transport: :native, listener_strategy: :reuseport,
+      bind: "0.0.0.0:50051", admin_bind: "127.0.0.1:9090",
+      fork_mode: :clean, fork_guard: :raise, strict_routes: false,
+      drain_delay: 5.0, shutdown_timeout: 25.0, worker_boot_timeout: 60.0,
+      worker_timeout: 30.0, status_interval: 1.0, min_ready_workers: 1,
+      phased_restart_surge: 1, max_connection_age: 300.0,
+      max_connection_age_grace: 30.0, keepalive_time: 60.0,
+      keepalive_permit_without_calls: true,
+      max_receive_message_size: 4 * 1024 * 1024,
+      max_send_message_size: 4 * 1024 * 1024, max_metadata_size: 8192,
+      metrics_backend: :pipe, log_format: :json, worker_recycle: {}, tls: {}
+    }.freeze
+    ENUMS = {
+      transport: %i[native async], listener_strategy: %i[reuseport inherited_fd port_per_worker],
+      fork_mode: %i[clean grpc_fork_support], fork_guard: %i[raise warn off],
+      metrics_backend: %i[pipe otlp mmap], log_format: %i[json logfmt]
+    }.freeze
+    HOOKS = %i[before_fork on_worker_boot on_worker_shutdown].freeze
+
+    attr_accessor(*DEFAULTS.keys, :controllers, :middleware, :preload_app)
+    attr_reader :health_checks
+
+    def initialize
+      DEFAULTS.each { |name, value| public_send("#{name}=", value.dup) }
+      @controllers = []
+      @middleware = Middleware::Stack.default
+      @hooks = HOOKS.to_h { |name| [name, []] }
+      @health_checks = {}
+      @preload_app = false
+      @preloaders = []
+    end
+
+    # CLI overrides > environment > configuration file > defaults.
+    def self.load(path: nil, env: ENV, overrides: {})
+      config = new
+      DSL.new(config).evaluate(path) if path
+      env.each do |key, value|
+        next unless key.start_with?("GRITZ_")
+
+        name = key.delete_prefix("GRITZ_").downcase.to_sym
+        raise ConfigurationError, "Unknown environment setting #{key}" unless DEFAULTS.key?(name)
+        next if overrides.key?(name)
+
+        config.public_send("#{name}=", parse_environment(name, value))
+      end
+      overrides.each { |name, value| config.public_send("#{name}=", value) }
+      config.validate!
+    end
+
+    def self.parse_environment(name, value)
+      case DEFAULTS.fetch(name)
+      when Integer then Integer(value, 10)
+      when Float then Float(value)
+      when Symbol then value.to_sym
+      when Hash then JSON.parse(value, symbolize_names: true)
+      when true, false
+        return true if %w[true 1].include?(value)
+        return false if %w[false 0].include?(value)
+
+        raise ArgumentError, "expected true or false"
+      else value
+      end
+    rescue ArgumentError, TypeError, JSON::ParserError => e
+      raise ConfigurationError, "Invalid GRITZ_#{name.to_s.upcase}: #{e.message}"
+    end
+
+    def validate!
+      DEFAULTS.each do |name, default|
+        value = public_send(name)
+        valid = case default
+                when Integer then value.is_a?(Integer) && value.between?(name == :workers ? 0 : 1, 2_147_483_647)
+                when Float then value.is_a?(Numeric) && value.real? && value.finite? && value.between?(0, 2_147_483.647)
+                when true, false then [true, false].include?(value)
+                else value.is_a?(default.class)
+                end
+        raise ConfigurationError, "Invalid #{name}: #{value.inspect}" unless valid
+      end
+      %i[shutdown_timeout worker_boot_timeout worker_timeout status_interval].each do |name|
+        raise ConfigurationError, "#{name} must be positive" unless public_send(name).positive?
+      end
+      ENUMS.each do |name, allowed|
+        raise ConfigurationError, "#{name} must be one of #{allowed.join(', ')}" unless allowed.include?(public_send(name))
+      end
+      validate_addresses!
+      validate_recycle!
+      validate_tls!
+      raise ConfigurationError, "controllers must be an Array of classes" unless controllers.is_a?(Array) && controllers.all?(Class)
+      raise ConfigurationError, "middleware must be a Stack" unless middleware.is_a?(Middleware::Stack)
+      raise ConfigurationError, "preload_app must be boolean" unless [true, false].include?(preload_app)
+
+      self
+    end
+
+    def preload_app? = preload_app
+
+    # Fail before allocating transport resources for unsupported release features.
+    def validate_single_process!
+      validate!
+      raise ConfigurationError, "v0.1 supports workers 0; the supervisor is planned for v0.2" unless workers.zero?
+      raise ConfigurationError, "v0.1 supports transport :native" unless transport == :native
+      raise ConfigurationError, "v0.1 supports listener_strategy :reuseport" unless listener_strategy == :reuseport
+      raise ConfigurationError, "TLS is planned for v0.3" unless tls.empty?
+      raise ConfigurationError, "worker_recycle requires the supervisor" unless worker_recycle.empty?
+      raise ConfigurationError, "Health checks are planned for v0.3" unless health_checks.empty?
+      raise ConfigurationError, "v0.1 supports log_format :json" unless log_format == :json
+      raise ConfigurationError, "v0.1 reserves metrics_backend :pipe; metrics export is planned for v0.3" unless metrics_backend == :pipe
+      raise ConfigurationError, "grpc_fork_support requires the supervisor" unless fork_mode == :clean
+      raise ConfigurationError, "at least one controller must be registered" if controllers.empty?
+
+      self
+    end
+
+    def add_preloader(&block)
+      @preload_app = true
+      @preloaders << block if block
+    end
+
+    def preload!
+      @preloaders.each(&:call)
+    end
+
+    def add_hook(name, &block)
+      raise ConfigurationError, "#{name} requires a block" unless block
+
+      @hooks.fetch(name) << block
+    end
+
+    def run_hooks(name, *args)
+      @hooks.fetch(name).each { |hook| hook.call(*args) }
+    end
+
+    def server_args
+      {
+        "grpc.so_reuseport" => listener_strategy == :reuseport ? 1 : 0,
+        "grpc.max_connection_age_ms" => (max_connection_age * 1000).to_i,
+        "grpc.max_connection_age_grace_ms" => (max_connection_age_grace * 1000).to_i,
+        "grpc.keepalive_time_ms" => (keepalive_time * 1000).to_i,
+        "grpc.keepalive_permit_without_calls" => keepalive_permit_without_calls ? 1 : 0,
+        "grpc.max_receive_message_length" => max_receive_message_size,
+        "grpc.max_send_message_length" => max_send_message_size,
+        "grpc.max_metadata_size" => max_metadata_size
+      }
+    end
+
+    private
+
+    def validate_addresses!
+      %i[bind admin_bind].each do |name|
+        match = /\A(?:\[[^\]\s]+\]|[^:\s]+):(\d+)\z/.match(public_send(name))
+        raise ConfigurationError, "#{name} must be a host:port address" unless match && match[1].to_i <= 65_535
+      end
+      if listener_strategy == :reuseport && workers > 1 && bind.end_with?(":0")
+        raise ConfigurationError, "reuseport with multiple workers cannot use port 0"
+      end
+      if transport == :native && listener_strategy == :inherited_fd
+        raise ConfigurationError, "native does not support inherited_fd"
+      end
+      return unless fork_mode == :grpc_fork_support && !RUBY_PLATFORM.include?("linux")
+
+      raise ConfigurationError, "grpc_fork_support requires Linux"
+    end
+
+    def validate_recycle!
+      worker_recycle.each do |name, value|
+        valid = if name == :jitter
+                  value.is_a?(Numeric) && value.real? && value.finite? && value.between?(0, 1)
+                elsif %i[max_requests max_rss_mb max_pss_mb max_lifetime].include?(name)
+                  value.is_a?(Numeric) && value.real? && value.finite? && value.positive? && (name != :max_requests || value.is_a?(Integer))
+                end
+        raise ConfigurationError, "Invalid worker_recycle #{name}" unless valid
+      end
+    end
+
+    def validate_tls!
+      return if tls.empty?
+
+      unless %i[cert key].all? { |name| tls[name].is_a?(String) && File.readable?(tls[name]) }
+        raise ConfigurationError, "tls requires readable cert and key files"
+      end
+
+      tls.each do |name, path|
+        raise ConfigurationError, "Invalid tls #{name}" unless %i[cert key client_ca].include?(name) && path.is_a?(String) && File.readable?(path)
+      end
+    end
+  end
+end

data/lib/gritz/configuration_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Invalid startup configuration.
+  # @api public
+  class ConfigurationError < StandardError; end
+end

data/lib/gritz/context.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Request state inherited by child fibers and threads using Ruby Fiber storage.
+  # @api public
+  class Context
+    attr_reader :call, :logger, :store
+    attr_accessor :request_id, :trace_context
+
+    def initialize(call:, logger:)
+      @call = call
+      @logger = logger
+      @store = {}
+    end
+
+    def self.current = Fiber[:gritz_context]
+
+    def self.with(context)
+      previous = current
+      Fiber[:gritz_context] = context
+      yield
+    ensure
+      Fiber[:gritz_context] = previous
+    end
+
+    def metadata = call.metadata
+    def deadline = call.deadline
+    def method = call.method_descriptor
+    def peer = call.peer
+    def peer_identity = call.peer_identity
+    def cancelled? = call.cancelled?
+    def remaining = deadline && [deadline - Time.now, 0.0].max
+
+    def check_deadline!
+      raise Errors::DeadlineExceeded, "deadline exceeded" if deadline && remaining.zero?
+    end
+
+    def check_cancelled!
+      raise Errors::Cancelled, "request cancelled" if cancelled?
+    end
+
+    # Keep serialization failures within the request's exception mapper.
+    # @api private
+    def validate_response!(message)
+      raise TypeError, "RPC response must be #{method.output_type}, got #{message.class}" unless message.is_a?(method.output_type)
+
+      message
+    end
+  end
+end

data/lib/gritz/controller.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Gritz
+  # One instance is created per RPC; application actions use request and stream.
+  # @api public
+  class Controller
+    class << self
+      def bind(service)
+        raise ArgumentError, "service must expose service_name and rpc_descs" unless service.respond_to?(:service_name) && service.respond_to?(:rpc_descs)
+
+        @service_class = service
+      end
+
+      def service_class = @service_class || (superclass.service_class if superclass.respond_to?(:service_class))
+
+      def action_defined?(action)
+        public_method_defined?(action) && ancestors.take_while { |ancestor| ancestor != Controller }.include?(instance_method(action).owner)
+      end
+
+      %i[before around after].each do |kind|
+        define_method("#{kind}_action") do |method = nil, only: nil, except: nil, &block|
+          callback = method || block
+          raise ArgumentError, "callback required" unless callback
+
+          (@filters ||= []) << [kind, callback, Array(only).map(&:to_sym), Array(except).map(&:to_sym)]
+        end
+      end
+
+      def filters = (superclass.respond_to?(:filters) ? superclass.filters : []) + (@filters || [])
+
+      def rescue_from(*errors, with: nil, &block)
+        handler = with || block
+        raise ArgumentError, "handler required" unless handler
+
+        (@rescue_handlers ||= []).concat(errors.map { |error| [error, handler] })
+      end
+
+      def rescue_handlers = (superclass.respond_to?(:rescue_handlers) ? superclass.rescue_handlers : []) + (@rescue_handlers || [])
+    end
+
+    attr_reader :context, :request, :stream
+
+    def initialize(context:)
+      @context = context
+      @request = Request.new(context.call, context)
+      @stream = Stream.new(context.call, context)
+    end
+
+    def process(action)
+      raise Errors::Unimplemented, "unimplemented RPC action: #{action}" unless self.class.action_defined?(action)
+
+      applicable = self.class.filters.select do |_, _, only, except|
+        (only.empty? || only.include?(action)) && !except.include?(action)
+      end
+      endpoint = lambda do
+        applicable.each { |kind, callback, _, _| invoke_callback(callback) if kind == :before }
+        result = public_send(action)
+        applicable.each { |kind, callback, _, _| invoke_callback(callback) if kind == :after }
+        result
+      end
+      applicable.select { |kind,| kind == :around }.reverse_each do |_, callback, _, _|
+        inner = endpoint
+        endpoint = lambda do
+          called = false
+          result = nil
+          callback_result = invoke_callback(callback, lambda {
+            called = true
+            result = inner.call
+          })
+          called ? result : callback_result
+        end
+      end
+      endpoint.call
+    rescue StandardError => e
+      handler = self.class.rescue_handlers.reverse.find { |klass, _| e.is_a?(klass) }
+      raise unless handler
+
+      invoke_callback(handler.last, e)
+    end
+
+    def fail!(code, message = nil, details: [], metadata: {})
+      raise Errors.for_code(code).new(message, details:, metadata:)
+    end
+
+    private
+
+    def invoke_callback(callback, argument = nil)
+      return argument ? instance_exec(argument, &callback) : instance_exec(&callback) if callback.respond_to?(:call)
+      return __send__(callback, &argument) if argument.is_a?(Proc)
+
+      argument ? __send__(callback, argument) : __send__(callback)
+    end
+
+    # @api public
+    class Request
+      def initialize(call, context)
+        @call = call
+        @context = context
+      end
+
+      def message
+        @context.check_deadline!
+        @context.check_cancelled!
+        return @message if defined?(@message)
+
+        @message = @call.read
+      end
+
+      def each_message
+        return enum_for(__method__) unless block_given?
+
+        @call.each_message do |message|
+          @context.check_deadline!
+          @context.check_cancelled!
+          yield message
+        end
+      end
+
+      alias messages each_message
+    end
+
+    # @api public
+    class Stream
+      def initialize(call, context)
+        @call = call
+        @context = context
+      end
+
+      def write(message)
+        raise TypeError, "RPC method does not stream responses" unless @context.method.server_streaming?
+
+        @context.check_deadline!
+        @context.check_cancelled!
+        @context.validate_response!(message)
+        @call.write(message)
+      end
+    end
+  end
+end

data/lib/gritz/core/version.rb

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

data/lib/gritz/core.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require_relative "errors"
+require_relative "core/version"
+
+module Gritz
+  module Core
+    # Core loading deliberately does not require grpc or initialize transports.
+    # @api private
+    LOADER = Zeitwerk::Loader.new
+    LOADER.tag = "gritz-core"
+    LOADER.inflector.inflect("dsl" => "DSL", "cli" => "CLI")
+    LOADER.push_dir(__dir__, namespace: Gritz)
+    LOADER.ignore(__FILE__, File.join(__dir__, "errors.rb"), File.join(__dir__, "core/version.rb"))
+    LOADER.do_not_eager_load(File.join(__dir__, "testing/rspec.rb"), File.join(__dir__, "testing/minitest.rb"))
+    LOADER.setup
+  end
+end

data/lib/gritz/dispatcher.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Gritz
+  # Routes one Call through the configured middleware and a fresh controller.
+  # @api public
+  class Dispatcher
+    attr_reader :router
+
+    def initialize(router:, middleware: Middleware::Stack.default, logger: Logger.new($stdout))
+      @router = router
+      @logger = logger
+      endpoint = lambda do |context|
+        context.check_deadline!
+        context.check_cancelled!
+        descriptor = router.resolve(context.method.full_name)
+        result = descriptor.controller.new(context:).process(descriptor.action)
+        context.check_deadline!
+        context.check_cancelled!
+        descriptor.server_streaming? ? result : context.validate_response!(result)
+      end
+      @app = middleware ? middleware.build(endpoint) : endpoint
+    end
+
+    def call(call)
+      @app.call(Context.new(call:, logger: @logger))
+    end
+  end
+end

data/lib/gritz/dsl.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Puma-style configuration file evaluator.
+  # @api public
+  class DSL
+    def initialize(config)
+      @config = config
+    end
+
+    def evaluate(path)
+      instance_eval(File.read(path), File.expand_path(path), 1)
+    end
+
+    Configuration::DEFAULTS.each_key do |name|
+      define_method(name) { |value| @config.public_send("#{name}=", value) }
+    end
+
+    Configuration::HOOKS.each do |name|
+      define_method(name) { |&block| @config.add_hook(name, &block) }
+    end
+
+    def preload_app!(&)
+      @config.add_preloader(&)
+    end
+
+    def register_controller(*controllers)
+      @config.controllers.concat(controllers)
+    end
+
+    def middleware
+      yield @config.middleware
+    end
+
+    def health_check(name, &block)
+      raise ConfigurationError, "health_check requires a block" unless block
+
+      @config.health_checks[name] = block
+    end
+
+    def method_missing(name, *_args)
+      raise ConfigurationError, "Unknown configuration setting #{name}"
+    end
+
+    def respond_to_missing?(_name, _include_private = false) = false
+  end
+end

data/lib/gritz/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Transport-independent status and rich error details.
+  # @api public
+  class Error < StandardError
+    attr_reader :details, :metadata
+
+    def initialize(message = nil, details: [], metadata: {})
+      super(message || code.to_s.tr("_", " "))
+      @details = details
+      @metadata = metadata
+    end
+
+    def code = self.class::CODE
+    def grpc_code = self.class::GRPC_CODE
+
+    CODE = :unknown
+    GRPC_CODE = 2
+  end
+
+  # gRPC's canonical codes, without a dependency on the grpc gem.
+  # @api public
+  module Errors
+    CODES = %i[ok cancelled unknown invalid_argument deadline_exceeded not_found already_exists permission_denied
+               resource_exhausted failed_precondition aborted out_of_range unimplemented internal unavailable data_loss unauthenticated].freeze
+
+    CODES.each_with_index do |code, number|
+      klass = Class.new(Error)
+      klass.const_set(:CODE, code)
+      klass.const_set(:GRPC_CODE, number)
+      const_set(code.to_s.split("_").map(&:capitalize).join, klass)
+    end
+
+    def self.for_code(code)
+      name = case code
+             when Integer then CODES[code] if code >= 0
+             when String, Symbol then code.to_sym
+             end
+      raise ArgumentError, "unknown RPC status: #{code.inspect}" unless CODES.include?(name)
+
+      const_get(name.to_s.split("_").map(&:capitalize).join, false)
+    end
+  end
+
+  DeadlineExceeded = Errors::DeadlineExceeded
+end

data/lib/gritz/method_descriptor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Immutable route and protobuf type information for one RPC.
+  # @api public
+  class MethodDescriptor
+    attr_reader :service, :name, :input_type, :output_type, :controller, :service_class, :action
+
+    def initialize(service:, name:, input_type:, output_type:, client_streaming: false, server_streaming: false,
+                   controller: nil, service_class: nil)
+      @service = service.to_s
+      @name = name.to_s
+      @input_type = input_type
+      @output_type = output_type
+      @client_streaming = client_streaming
+      @server_streaming = server_streaming
+      @controller = controller
+      @service_class = service_class
+      @action = @name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+      freeze
+    end
+
+    def full_name = "/#{service}/#{name}"
+    def client_streaming? = @client_streaming
+    def server_streaming? = @server_streaming
+
+    def kind
+      return :bidi if client_streaming? && server_streaming?
+      return :client_streaming if client_streaming?
+      return :server_streaming if server_streaming?
+
+      :unary
+    end
+  end
+end

data/lib/gritz/middleware/context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Middleware
+    # Sets request-local state for the entire lifetime of an RPC.
+    # @api public
+    class Context
+      def initialize(app)
+        @app = app
+      end
+
+      def call(context)
+        Gritz::Context.with(context) { @app.call(context) }
+      end
+    end
+  end
+end

data/lib/gritz/middleware/exception_mapper.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module Gritz
+  module Middleware
+    # Converts application exceptions to safe RPC errors.
+    # @api public
+    class ExceptionMapper
+      def initialize(app, mappings: {}, expose_errors: false)
+        @app = app
+        @mappings = mappings
+        @expose_errors = expose_errors
+      end
+
+      def call(context)
+        @app.call(context)
+      rescue Gritz::Error
+        raise
+      rescue StandardError => e
+        mapping = @mappings.find { |klass, _| e.is_a?(klass) }&.last
+        if mapping
+          raise(mapping.respond_to?(:call) ? mapping.call(e) : Errors.for_code(mapping).new(e.message))
+        end
+
+        case e.class.name
+        when "ActiveRecord::RecordNotFound"
+          raise Errors::NotFound, "record not found"
+        when "ActiveRecord::RecordInvalid"
+          raise Errors::InvalidArgument, "invalid record"
+        end
+
+        error_id = SecureRandom.uuid
+        context.logger.error(JSON.generate(error_id:, request_id: context.request_id, error: e.class.name,
+                                           message: e.message, backtrace: e.backtrace))
+        raise Errors::Internal.new(@expose_errors ? e.message : "internal error (#{error_id})", metadata: { "error-id" => error_id })
+      end
+    end
+  end
+end

data/lib/gritz/middleware/logging.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gritz
+  module Middleware
+    # Logs one structured completion row per RPC, including streaming failures.
+    # @api public
+    class Logging
+      def initialize(app)
+        @app = app
+      end
+
+      def call(context)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        code = :ok
+        @app.call(context)
+      rescue Gritz::Error => e
+        code = e.code
+        raise
+      rescue StandardError
+        code = :internal
+        raise
+      ensure
+        duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000
+        context.logger.info(JSON.generate(request_id: context.request_id, service: context.method.service,
+                                          method: context.method.name, code:, duration_ms: duration.round(3),
+                                          peer: context.peer, pid: Process.pid))
+      end
+    end
+  end
+end

data/lib/gritz/middleware/request_id.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Gritz
+  module Middleware
+    # Assigns and echoes a correlation ID for each RPC.
+    # @api public
+    class RequestId
+      def initialize(app)
+        @app = app
+      end
+
+      def call(context)
+        incoming = Array(context.metadata["x-request-id"]).first
+        context.request_id = incoming.is_a?(String) && incoming.match?(/\A[\x21-\x7e]{1,128}\z/) ? incoming : SecureRandom.uuid
+        metadata = { "x-request-id" => context.request_id }
+        if context.call.respond_to?(:merge_initial_metadata)
+          context.call.merge_initial_metadata(metadata)
+        else
+          context.call.send_initial_metadata(metadata)
+        end
+        @app.call(context)
+      end
+    end
+  end
+end

data/lib/gritz/middleware/stack.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Middleware
+    # Mutable middleware configuration; build creates an immutable call chain.
+    # @api public
+    class Stack
+      Entry = Struct.new(:middleware, :options, :block)
+      attr_reader :entries
+
+      def initialize
+        @entries = []
+      end
+
+      def initialize_copy(other)
+        super
+        @entries = other.entries.dup
+      end
+
+      def self.default
+        new.use(RequestId).use(Context).use(Logging).use(ExceptionMapper)
+      end
+
+      def use(middleware, **options, &block)
+        entries << Entry.new(middleware, options, block)
+        self
+      end
+
+      def insert_before(target, middleware, **options, &block)
+        entries.insert(index_of(target), Entry.new(middleware, options, block))
+        self
+      end
+
+      def insert_after(target, middleware, **options, &block)
+        entries.insert(index_of(target) + 1, Entry.new(middleware, options, block))
+        self
+      end
+
+      def swap(target, middleware, **options, &block)
+        entries[index_of(target)] = Entry.new(middleware, options, block)
+        self
+      end
+
+      def delete(middleware)
+        entries.reject! { |entry| entry.middleware == middleware }
+        self
+      end
+
+      def build(app)
+        entries.reverse_each.reduce(app) do |endpoint, entry|
+          entry.middleware.new(endpoint, **entry.options, &entry.block)
+        end
+      end
+
+      private
+
+      def index_of(middleware)
+        entries.index { |entry| entry.middleware == middleware } || raise(ArgumentError, "middleware not found: #{middleware}")
+      end
+    end
+  end
+end

data/lib/gritz/router.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Resolves generated service descriptors to controller actions at boot.
+  # @api public
+  class Router
+    attr_reader :routes
+
+    def initialize(controllers:, strict: false, logger: nil)
+      @routes = {}
+      services = {}
+      missing = []
+      controllers.each do |controller|
+        service = controller.service_class
+        raise ArgumentError, "#{controller} has no bound service" unless service
+        raise ArgumentError, "service #{service.service_name} is already bound" if services.key?(service.service_name)
+
+        services[service.service_name] = controller
+        service.rpc_descs.each do |name, rpc|
+          input_stream = rpc.client_streamer? || rpc.bidi_streamer?
+          output_stream = rpc.server_streamer? || rpc.bidi_streamer?
+          route = MethodDescriptor.new(service: service.service_name, name:, input_type: input_stream ? rpc.input.type : rpc.input,
+                                       output_type: output_stream ? rpc.output.type : rpc.output, client_streaming: input_stream,
+                                       server_streaming: output_stream, controller:, service_class: service)
+          @routes[route.full_name] = route
+          missing << "#{controller}##{route.action}" unless controller.action_defined?(route.action)
+        end
+      end
+      unless missing.empty?
+        message = "unimplemented RPC actions: #{missing.join(', ')}"
+        raise ArgumentError, message if strict
+
+        logger&.warn(message)
+      end
+      @routes.freeze
+    end
+
+    def resolve(full_name)
+      routes.fetch(full_name) { raise Errors::Unimplemented, "unknown RPC: #{full_name}" }
+    end
+  end
+end

data/lib/gritz/testing/in_memory_call.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Testing
+    # Runs all RPC shapes without sockets or grpc initialization.
+    # @api public
+    class InMemoryCall
+      include Gritz::Call
+
+      attr_reader :method_descriptor, :metadata, :deadline, :peer, :peer_identity,
+                  :responses, :initial_metadata, :trailing_metadata
+
+      def initialize(method_descriptor:, messages:, metadata: {}, deadline: nil, peer: nil, peer_identity: nil)
+        @method_descriptor = method_descriptor
+        @messages = messages.to_enum
+        @metadata = metadata
+        @deadline = deadline
+        @peer = peer
+        @peer_identity = peer_identity
+        @responses = []
+        @initial_metadata = {}
+        @trailing_metadata = {}
+        @cancelled = false
+      end
+
+      def read
+        @messages.next
+      rescue StopIteration
+        nil
+      end
+
+      def write(message) = @responses << message
+      def send_initial_metadata(metadata = {}) = @initial_metadata.merge!(metadata)
+      alias merge_initial_metadata send_initial_metadata
+      def cancelled? = @cancelled
+      def cancel! = @cancelled = true
+    end
+  end
+end

data/lib/gritz/testing/minitest.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../core"
+
+module Gritz
+  module Testing
+    # Include in a Minitest test and pass controller: to rpc.
+    # @api public
+    module Minitest
+      include RpcHelper
+
+      def assert_rpc_error(code, message = nil, &)
+        error = assert_raises(Gritz::Error, *[message].compact, &)
+        assert_equal(code.to_sym, error.code, message)
+        error
+      end
+    end
+  end
+end

data/lib/gritz/testing/rpc_helper.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Gritz
+  module Testing
+    # Controller tests exercise the real dispatcher without opening a socket.
+    # @api public
+    module RpcHelper
+      attr_reader :last_rpc_call
+
+      def rpc(action, messages, controller: nil, metadata: {}, deadline: nil, peer: nil, peer_identity: nil,
+              middleware: true, logger: Logger.new(File::NULL))
+        controller ||= described_class if respond_to?(:described_class)
+        raise ArgumentError, "pass controller: or use an RSpec controller example group" unless controller
+
+        router = Router.new(controllers: [controller], logger:)
+        descriptor = router.routes.values.find { |route| route.action == action.to_sym || route.name == action.to_s }
+        raise ArgumentError, "unknown RPC action: #{action}" unless descriptor
+
+        input = descriptor.client_streaming? ? messages : [messages]
+        @last_rpc_call = InMemoryCall.new(method_descriptor: descriptor, messages: input, metadata:, deadline:, peer:, peer_identity:)
+        stack = middleware == true ? Middleware::Stack.default : middleware
+        result = Dispatcher.new(router:, middleware: stack, logger:).call(@last_rpc_call)
+        descriptor.server_streaming? ? @last_rpc_call.responses : result
+      end
+    end
+  end
+end

data/lib/gritz/testing/rspec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "rspec/expectations"
+require_relative "../core"
+
+module Gritz
+  module Testing
+    # Requiring gritz/testing/rspec enables type: :rpc controller tests.
+    # @api public
+    module Rspec
+      def self.install
+        ::RSpec.configure { |config| config.include RpcHelper, type: :rpc }
+        ::RSpec::Matchers.define :raise_rpc_error do |code|
+          supports_block_expectations
+
+          match do |block|
+            @error = nil
+            begin
+              block.call
+              false
+            rescue Gritz::Error => e
+              @error = e
+              e.code == code.to_sym
+            end
+          end
+
+          failure_message do
+            "expected RPC error #{code}, got #{@error ? @error.code : 'no error'}"
+          end
+
+          failure_message_when_negated do
+            "expected no RPC error #{code}, got #{@error.code}"
+          end
+        end
+      end
+    end
+  end
+end
+
+Gritz::Testing::Rspec.install

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: gritz-core
+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: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.33'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.33'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Transport-independent controllers, routing, middleware, configuration
+  and testing for Gritz.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gritz/call.rb
+- lib/gritz/cli.rb
+- lib/gritz/configuration.rb
+- lib/gritz/configuration_error.rb
+- lib/gritz/context.rb
+- lib/gritz/controller.rb
+- lib/gritz/core.rb
+- lib/gritz/core/version.rb
+- lib/gritz/dispatcher.rb
+- lib/gritz/dsl.rb
+- lib/gritz/errors.rb
+- lib/gritz/method_descriptor.rb
+- lib/gritz/middleware/context.rb
+- lib/gritz/middleware/exception_mapper.rb
+- lib/gritz/middleware/logging.rb
+- lib/gritz/middleware/request_id.rb
+- lib/gritz/middleware/stack.rb
+- lib/gritz/router.rb
+- lib/gritz/testing/in_memory_call.rb
+- lib/gritz/testing/minitest.rb
+- lib/gritz/testing/rpc_helper.rb
+- lib/gritz/testing/rspec.rb
+homepage: https://github.com/gritzrpc/gritz-core
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/gritzrpc/gritz-core
+  changelog_uri: https://github.com/gritzrpc/gritz-core/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: Transport-independent controllers and middleware for Gritz
+test_files: []