gritz-core 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03bd5114b9267c0bc0b5daa80d14433d4941c753321338fc5b83b2281f4d6bf1
-  data.tar.gz: 67fabc1d94c5cca35149679a2e582c983a88122a5299638d05c639387ea48fa4
+  metadata.gz: ed1b7320b17241d7bf44746aff7108965c5bd4ef5c5acfeb26bade59786c5775
+  data.tar.gz: 062fa21a3446621c20990013a0bb7a6dd23c38803d5e58597902f83079dba21c
 SHA512:
-  metadata.gz: 22ba419be6cd7bf1754eaccc7af3bde09ac0ca9dcac494f5d1932306aa73d595e0861b1c9ff1af9e694195f86d6c19e3103161a721ccd8e3f4c88ae72c93c56d
-  data.tar.gz: 1986b1cc2c4a32d0baf218b8268b1ced8399931c1a48379f46071f891c09d4c89cfe489fb707683dcf0d4ed239c708b3bfdd36a156efb0696f14d1764a10eeb6
+  metadata.gz: 0f4702d111e9e72546b8a0a219703e355fba71a7ecbcd064d7c2fca60461789ee8c5c03dc98d050d843302f71506e9a9169bc88c9c8d73671231ff8ca8ca6035
+  data.tar.gz: 3fc17735fed2dc9068e54aae5853d6595d344458cb535eaa3be2ec8a63d2cd1c5d1f546175183639b3fa6f3309506bfa8d3041b91211456982023b187b6cb1a7

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.0
+
+- Migrate Gruf controllers and server interceptors through `Gritz::Compat::Gruf`, with a configuration conversion tool.
+- Configure optional gRPC Reflection through the `reflection` setting.
+- Avoid unnecessary supervisor snapshot allocation when status consumers are paused.
+- Publish worker metrics at `status_interval` to reduce supervisor overhead; retain retries and final shutdown totals.
+- Eagerly load the transport-independent framework before application warmup so forked workers can share its memory.
+- Send supervisor snapshots at `status_interval`, with immediate lifecycle and health changes, to reduce parent-process allocation.
+- Reuse signal, status and admin read buffers to avoid allocating memory on every idle poll.
+
+## 0.4.0
+
+- Define lazy, fork-safe clients with process-local shared connections, per-call middleware, deadline propagation and selected request headers.
+- Treat unhandled downstream errors as safe `INTERNAL` responses by default; allow explicit status passthrough.
+- Support optional worker telemetry integrations with the remaining graceful shutdown budget.
+
 ## 0.3.0
 
 - Replace workers one at a time with `USR1` and recycle them by request count, memory or lifetime.

data/README.md

@@ -12,6 +12,10 @@ Controller tests can load `gritz/testing/rspec` or `gritz/testing/minitest` and
 
 Supervised servers support phased replacement, fresh-interpreter hot reexec, request/memory/lifetime recycling, Admin HTTP probes and process-wide Prometheus totals. The CLI keeps one lifecycle owner across master generations; application controllers and gRPC resources stay in serving processes.
 
+`Gritz::Client.define` creates lazy, fork-safe client constants with deadline propagation, selected request headers and middleware around complete streams. See the [client guide](docs/guides/clients.md). Optional [gritz-otel](https://github.com/gritzrpc/gritz-otel) adds server/client spans and worker OTLP metrics after fork.
+
+The optional `Gritz::Compat::Gruf` module adapts Gruf controllers, returned response streams and server interceptors. `gritz-migrate-gruf` converts supported static configuration without executing the source file. See the [Gruf migration guide](docs/guides/migrating-from-gruf.md). Add [gritz-rails](https://github.com/gritzrpc/gritz-rails) for Rails execution, generators and development reloading.
+
 ## Development
 
 ```sh

data/exe/gritz-migrate-gruf

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "gritz/core"
+require "optparse"
+
+begin
+  destination = nil
+  parser = OptionParser.new do |options|
+    options.banner = "Usage: gritz-migrate-gruf SOURCE [--output config/gritz.rb]"
+    options.on("--output PATH", "Write a new file; existing files are never overwritten") { |path| destination = path }
+  end
+  parser.parse!
+  raise OptionParser::MissingArgument, "SOURCE" unless ARGV.size == 1
+
+  output = Gritz::Compat::Gruf::ConfigConverter.new.convert(File.read(ARGV.first))
+  if destination
+    File.open(destination, File::WRONLY | File::CREAT | File::EXCL) { |file| file.write(output) }
+  else
+    $stdout.write(output)
+  end
+rescue Gritz::ConfigurationError, OptionParser::ParseError, SystemCallError => e
+  warn "gritz-migrate-gruf: #{e.message}"
+  exit 1
+end

data/lib/gritz/channel_registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Shares transport connections within a process, never across a fork.
+  # @api private
+  class ChannelRegistry
+    module ForkHook
+      def _fork(...)
+        result = super
+        Gritz::ChannelRegistry.reset! if result.zero?
+        result
+      end
+    end
+
+    class << self
+      def fetch(target:, credentials:, args: {}, pool: nil)
+        reset! unless @pid == Process.pid
+        key = [Process.pid, pool, snapshot(target), credentials, snapshot(args)].freeze
+        @lock.synchronize { @channels.fetch(key) { @channels[key] = yield } }
+      end
+
+      # In a child, discard references without calling native close methods.
+      def reset!
+        @lock = Mutex.new
+        @channels = {}
+        @pid = Process.pid
+      end
+
+      def snapshot(value)
+        case value
+        when String then value.dup.freeze
+        when Array then value.map { |entry| snapshot(entry) }.freeze
+        when Hash then value.to_h { |key, entry| [snapshot(key), snapshot(entry)] }.freeze
+        else value
+        end
+      end
+    end
+
+    reset!
+    Process.singleton_class.prepend(ForkHook) unless Process.singleton_class.ancestors.include?(ForkHook)
+  end
+end

data/lib/gritz/client/call_context.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Gritz
+  class Client
+    # Middleware state for an outgoing RPC, independent of its transport.
+    # @api public
+    class CallContext
+      attr_reader :method, :kind, :options, :parent, :store, :logger
+      attr_accessor :request, :operation, :trace_context, :response_block
+
+      def initialize(method:, kind:, request:, options:, parent:, terminal:)
+        service, name = method.delete_prefix("/").split("/", 2)
+        @method = MethodDescriptor.new(service:, name:, input_type: nil, output_type: nil,
+                                       client_streaming: %i[client_streaming bidi].include?(kind),
+                                       server_streaming: %i[server_streaming bidi].include?(kind))
+        @kind = kind
+        @request = request
+        @options = options
+        @parent = parent
+        @terminal = terminal
+        @store = {}
+        @logger = parent&.logger || Logger.new($stderr)
+        @trace_context = parent&.trace_context
+      end
+
+      def metadata = options[:metadata]
+      def deadline = options[:deadline]
+      def remaining = deadline && [deadline - Time.now, 0.0].max
+      def request_id = metadata["x-request-id"]
+      def cancelled? = !!(store[:gritz_cancelled] || parent&.cancelled? || operation&.cancelled?)
+
+      def check_deadline!
+        raise Errors::DeadlineExceeded, "deadline exceeded" if deadline && remaining.zero?
+      end
+
+      def check_cancelled!
+        raise Errors::Cancelled, "request cancelled" if cancelled?
+      end
+
+      # Input streams stay lazy and retain the parent even on native writer threads.
+      # @api private
+      def each_request
+        Enumerator.new do |output|
+          Context.with(parent) do
+            request.each do |message|
+              check_deadline!
+              check_cancelled!
+              output << message
+            end
+          end
+        end
+      end
+
+      # @api private
+      def execute = @terminal.call(self, &response_block)
+    end
+  end
+end

data/lib/gritz/client/invocation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Gritz
+  class Client
+    # Captures the deadline, parent context, and middleware for one outgoing RPC.
+    # @api private
+    class Invocation
+      attr_reader :options
+
+      def initialize(deadline: nil, safety_margin: 0.01, options: {}, parent: nil, middleware: nil)
+        validate_duration!(deadline, :deadline, positive: true) unless deadline.nil?
+        validate_duration!(safety_margin, :safety_margin, positive: false)
+        raise ArgumentError, "return_op is not supported by Gritz::Client" if options[:return_op]
+
+        @parent = parent
+        @options = options.dup
+        explicit = options[:deadline]
+        raise ArgumentError, "deadline must be an absolute Time" unless explicit.nil? || explicit.is_a?(Time)
+
+        now = Time.now
+        candidates = [explicit, deadline && (now + deadline), parent&.deadline && (parent.deadline - safety_margin)].compact
+        @options[:deadline] = candidates.min
+        @options[:metadata] = prepare_metadata(options.fetch(:metadata, {}))
+        check_parent!
+        raise Errors::DeadlineExceeded, "deadline exceeded" if @options[:deadline] && @options[:deadline] <= now
+
+        stack = Client.middleware.dup
+        stack.entries.concat(middleware.entries) if middleware
+        @app = stack.build(lambda(&:execute))
+      end
+
+      def call(terminal, method:, kind:, request:, options:, &block)
+        context = CallContext.new(method:, kind:, request:, options:, parent: @parent, terminal:)
+        if context.method.server_streaming? && !block
+          Enumerator.new { |output| run(context) { |reply| output << reply } }
+        else
+          run(context, &block)
+        end
+      end
+
+      private
+
+      def run(context, &block)
+        Context.with(@parent) do
+          context.check_deadline!
+          context.check_cancelled!
+          context.response_block = block
+          @app.call(context)
+        end
+      end
+
+      def check_parent!
+        raise Errors::Cancelled, "request cancelled" if @parent&.cancelled?
+      end
+
+      def prepare_metadata(metadata)
+        raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
+        copied = metadata.to_h { |key, value| [key.to_s, copy_metadata_value(value)] }
+        copied["x-request-id"] ||= copy_metadata_value(@parent&.request_id) || SecureRandom.uuid
+        %w[traceparent tracestate].each do |key|
+          value = @parent&.metadata&.[](key)
+          copied[key] ||= copy_metadata_value(value) if value
+        end
+        copied
+      end
+
+      def copy_metadata_value(value)
+        case value
+        when Array then value.map { |item| item.is_a?(String) ? item.dup : item }
+        when String then value.dup
+        else value
+        end
+      end
+
+      def validate_duration!(value, name, positive:)
+        valid = value.is_a?(Numeric) && value.real? && value.finite? && (positive ? value.positive? : value >= 0)
+        raise ArgumentError, "#{name} must be a finite #{positive ? 'positive' : 'nonnegative'} number" unless valid
+      end
+    end
+  end
+end

data/lib/gritz/client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gritz
+  # Defines fork-safe singleton clients without constructing a native transport.
+  # @api public
+  class Client
+    class << self
+      attr_accessor :adapter
+
+      def middleware = @middleware ||= Middleware::Stack.new
+
+      def middleware=(stack)
+        raise ArgumentError, "middleware must be a Gritz::Middleware::Stack" unless stack.is_a?(Middleware::Stack)
+
+        @middleware = stack
+      end
+
+      def define(stub_class, target:, credentials: :insecure, channel_args: {}, deadline: nil,
+                 safety_margin: 0.01, service_config: nil, middleware: nil, adapter: nil)
+        unless stub_class.is_a?(Class) && !stub_class.public_instance_methods(false).empty?
+          raise ArgumentError, "stub_class must define RPC methods"
+        end
+        raise ArgumentError, "target must be a nonempty String" unless target.is_a?(String) && !target.strip.empty? && !target.include?("\0")
+        raise ArgumentError, "channel_args must be a Hash" unless channel_args.is_a?(Hash)
+
+        validate_time!(:deadline, deadline) unless deadline.nil?
+        validate_time!(:safety_margin, safety_margin)
+        if middleware && !middleware.is_a?(Middleware::Stack)
+          raise ArgumentError, "middleware must be a Gritz::Middleware::Stack"
+        end
+
+        args = channel_args.dup
+        unless service_config.nil?
+          raise ArgumentError, "service_config must be a JSON object" unless service_config.is_a?(Hash)
+
+          args["grpc.service_config"] = JSON.generate(service_config)
+          validate_json!(service_config)
+        end
+        definition = Definition.new(stub_class:, target: target.dup.freeze, credentials:,
+                                    args: ChannelRegistry.snapshot(args), deadline:, safety_margin:, middleware:, adapter:)
+        Module.new do
+          stub_class.public_instance_methods(false).each do |method|
+            define_singleton_method(method) do |request, options = {}, **keywords, &block|
+              raise ArgumentError, "RPC options must be a Hash" unless options.is_a?(Hash)
+
+              definition.call(method, request, options.merge(keywords), &block)
+            end
+          end
+        end
+      rescue JSON::GeneratorError, JSON::NestingError => e
+        raise ArgumentError, "invalid service_config: #{e.message}"
+      end
+
+      private
+
+      def validate_time!(name, value)
+        unless value.is_a?(Numeric) && value.real? && value.finite? && (name == :deadline ? value.positive? : value >= 0)
+          raise ArgumentError, "#{name} must be a finite #{name == :deadline ? 'positive' : 'nonnegative'} number"
+        end
+      end
+
+      def validate_json!(value)
+        case value
+        when Hash
+          value.each do |key, entry|
+            raise ArgumentError, "service_config object keys must be Strings or Symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+
+            validate_json!(entry)
+          end
+        when Array then value.each { |entry| validate_json!(entry) }
+        when Float
+          raise ArgumentError, "service_config numbers must be finite" unless value.finite?
+        when String, Integer, Symbol, TrueClass, FalseClass, NilClass then nil
+        else raise ArgumentError, "service_config must contain only JSON values"
+        end
+      end
+    end
+
+    # @api private
+    class Definition
+      def initialize(stub_class:, target:, credentials:, args:, deadline:, safety_margin:, middleware:, adapter:)
+        @stub_class = stub_class
+        @target = target
+        @credentials = credentials
+        @args = args
+        @deadline = deadline
+        @safety_margin = safety_margin
+        @middleware = middleware
+        @adapter = adapter
+      end
+
+      def call(method, request, options, &)
+        ForkGuard.check!(@stub_class)
+        invocation = Invocation.new(deadline: @deadline, safety_margin: @safety_margin, options:,
+                                    parent: Context.current, middleware: @middleware)
+        adapter = @adapter || Client.adapter
+        raise ArgumentError, "require gritz/native or provide a client adapter" unless adapter
+
+        connection = ChannelRegistry.fetch(target: @target, credentials: @credentials, args: @args, pool: adapter) do
+          adapter.connect(target: @target, credentials: @credentials, args: @args)
+        end
+        adapter.invoke(stub_class: @stub_class, connection:, method:, request:, options: invocation.options,
+                       around: invocation.method(:call), &)
+      end
+    end
+  end
+end

data/lib/gritz/compat/gruf/config_converter.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "ripper"
+
+module Gritz
+  module Compat
+    module Gruf
+      # Converts a deliberately small, literal-only subset of Gruf.configure.
+      # @api public
+      class ConfigConverter
+        ARGUMENTS = {
+          "grpc.max_receive_message_length" => [:max_receive_message_size, 1],
+          "grpc.max_send_message_length" => [:max_send_message_size, 1],
+          "grpc.max_metadata_size" => [:max_metadata_size, 1],
+          "grpc.max_connection_age_ms" => [:max_connection_age, 1000.0],
+          "grpc.max_connection_age_grace_ms" => [:max_connection_age_grace, 1000.0],
+          "grpc.keepalive_time_ms" => [:keepalive_time, 1000.0]
+        }.freeze
+
+        # @param source [String] Ruby source containing one static Gruf.configure block
+        # @return [String] Gritz configuration requiring manual review before use
+        # @raise [Gritz::ConfigurationError] when a setting or expression cannot be converted
+        # @api public
+        def convert(source)
+          settings = assignments(source)
+          output = { workers: 0 }
+          settings.each do |name, value|
+            case name
+            when "server_binding_url" then output[:bind] = value
+            when "rpc_server_options" then server_options(value, output)
+            when "use_ssl", "ssl_crt_file", "ssl_key_file" then next
+            when "default_client_host", "default_channel_credentials"
+              unsupported("#{name}: configure Gritz::Client.define manually")
+            else unsupported("#{name}: manual migration required; see migrating-from-gruf.md")
+            end
+          end
+          config = Gritz::Configuration.new
+          output.each { |name, value| config.public_send("#{name}=", value) }
+          config.validate!
+          tls = tls_options(settings)
+          output[:tls] = tls unless tls.empty?
+          ["# Review controller registration, interceptors and fork safety before starting.",
+           'require "gritz/compat/gruf"', "", *output.map { |name, value| "#{name}(#{value.inspect})" }, "",
+           "# register_controller YourMigratedController", ""].join("\n")
+        end
+
+        private
+
+        def assignments(source)
+          tree = Ripper.sexp(source)
+          unsupported("invalid Ruby syntax; manual correction required") unless tree
+          statements = tree[1].reject { |node| node[0] == :void_stmt }
+          unsupported("expected one Gruf.configure block; other executable code needs manual migration") unless statements.size == 1
+          node = statements.first
+          call = node[1]
+          block = node[2]
+          unless node[0] == :method_add_block && call&.dig(0) == :call && call.dig(3, 1) == "configure" &&
+                 %i[var_ref top_const_ref].include?(call.dig(1, 0)) && call.dig(1, 1, 1) == "Gruf"
+            unsupported("expected Gruf.configure; manual migration required")
+          end
+          params = block&.dig(1, 1)
+          unless %i[do_block brace_block].include?(block&.dig(0)) && params&.dig(0) == :params &&
+                 params[1]&.size == 1 && params[2..].all?(&:nil?) && block.dig(1, 2) == false
+            unsupported("configure needs one block variable; manual migration required")
+          end
+          variable = params[1][0][1]
+          body = block[2]
+          if block[0] == :do_block
+            unsupported("rescue/ensure needs manual migration") unless body[2..].all?(&:nil?)
+            body = body[1]
+          end
+          body.each_with_object({}) do |statement, values|
+            next if statement[0] == :void_stmt
+
+            field = statement[1]
+            unless statement[0] == :assign && field&.dig(0) == :field && field.dig(1, 0) == :var_ref && field.dig(1, 1, 1) == variable
+              unsupported("only literal assignments are supported; interceptors and other code require manual migration")
+            end
+            name = field[3][1]
+            unsupported("duplicate setting #{name}; manual migration required") if values.key?(name)
+            values[name] = literal(statement[2])
+          end
+        end
+
+        def literal(node)
+          case node[0]
+          when :@int then Integer(node[1].delete("_"), 0)
+          when :@float then Float(node[1].delete("_"))
+          when :string_literal
+            parts = node[1][1..]
+            unsupported("strings must be literals without interpolation or escapes") unless parts.all? { |part|
+              part[0] == :@tstring_content && !part[1].include?("\\")
+            }
+            parts.map { |part| part[1] }.join
+          when :symbol_literal
+            token = node.dig(1, 1)
+            unsupported("symbol must be a static literal") unless %i[@ident @op @const].include?(token&.dig(0))
+            token[1].to_sym
+          when :@label then node[1].delete_suffix(":").to_sym
+          when :var_ref
+            return { "true" => true, "false" => false, "nil" => nil }.fetch(node[1][1]) if node[1][0] == :@kw
+
+            unsupported("dynamic values need manual migration; use static literals")
+          when :unary
+            unsupported("only negative numeric literals are supported") unless node[1] == :-@ && %i[@int @float].include?(node.dig(2, 0))
+            -literal(node[2])
+          when :hash
+            pairs = node.dig(1, 1) || []
+            pairs.each_with_object({}) do |pair, values|
+              unsupported("hash splats need manual migration; use literal entries") unless pair[0] == :assoc_new
+              key = literal(pair[1])
+              unsupported("duplicate hash key #{key}; manual migration required") if values.key?(key)
+              values[key] = literal(pair[2])
+            end
+          else unsupported("dynamic values need manual migration; only static literals are supported")
+          end
+        rescue ArgumentError, KeyError
+          unsupported("invalid literal; manual migration required")
+        end
+
+        def server_options(options, output)
+          unsupported("rpc_server_options must be a literal Hash") unless options.is_a?(Hash)
+          options.each do |name, value|
+            case name
+            when :pool_size then output[:threads] = value
+            when :max_waiting_requests then output[:max_waiting_requests] = value
+            when :server_args
+              unsupported("server_args must be a literal Hash") unless value.is_a?(Hash)
+              value.each do |key, argument|
+                conversion = ARGUMENTS[key]
+                unsupported("#{key}: manual C-core argument migration required") unless conversion
+                unsupported("#{key} must be a numeric literal") unless argument.is_a?(Numeric)
+                setting, divisor = conversion
+                output[setting] = argument / divisor
+              end
+            else unsupported("#{name}: manual rpc_server_options migration required")
+            end
+          end
+        end
+
+        def tls_options(settings)
+          enabled = settings.fetch("use_ssl", false)
+          unsupported("use_ssl must be a boolean literal") unless [true, false].include?(enabled)
+          paths = %w[ssl_crt_file ssl_key_file]
+          unless enabled
+            paths.each { |key| unsupported("#{key} requires use_ssl=true; manual review required") if settings.key?(key) }
+            return {}
+          end
+          unless paths.all? { |key| settings[key].is_a?(String) && !settings[key].empty? }
+            unsupported("use_ssl=true requires ssl_crt_file and ssl_key_file; manual review required")
+          end
+          { cert: settings.fetch("ssl_crt_file"), key: settings.fetch("ssl_key_file") }
+        end
+
+        def unsupported(message) = raise Gritz::ConfigurationError, message
+      end
+    end
+  end
+end

data/lib/gritz/compat/gruf.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "gritz/core"
+require "json"
+
+module Gritz
+  module Compat
+    # Selected Gruf 2.22 controller/interceptor APIs, without loading Gruf or grpc.
+    # @api public
+    module Gruf
+      REQUEST_KEY = Object.new.freeze
+
+      # @api private
+      def self.request_for(context)
+        context.store[REQUEST_KEY] ||= Request.new(context)
+      end
+
+      # Wraps a Gruf-style interceptor as a Gritz server middleware.
+      # @param klass [Class] interceptor implementing #call and yielding to the action
+      # @return [Class] middleware accepted by Middleware::Stack#use
+      # @api public
+      def self.interceptor(klass)
+        Class.new(InterceptorAdapter) do
+          define_method(:initialize) { |app, **options| super(app, klass, options) }
+        end
+      end
+
+      class RequestContext < Hash
+        def [](key) = super(convert_key(key))
+
+        def []=(key, value)
+          super(convert_key(key), value)
+        end
+
+        def fetch(key, ...) = super(convert_key(key), ...)
+        def key?(key) = super(convert_key(key))
+        def merge!(other, &) = super(other.transform_keys { |key| convert_key(key) }, &)
+        alias update merge!
+
+        private
+
+        def convert_key(key) = key.is_a?(Symbol) ? key.to_s : key
+      end
+
+      class ActiveCall
+        def initialize(context) = @context = context
+        def metadata = @context.metadata
+        def deadline = @context.deadline
+        def peer = @context.peer
+        def cancelled? = @context.cancelled?
+        def output_metadata = @context.call.trailing_metadata
+      end
+
+      class Request
+        attr_reader :context, :active_call, :error
+
+        def initialize(context)
+          @rpc_context = context
+          @original = Gritz::Controller::Request.for(context)
+          @context = RequestContext.new
+          @active_call = ActiveCall.new(context)
+          @error = Error.new
+        end
+
+        def service = @rpc_context.method.service_class
+        def method_key = @rpc_context.method.action
+        def request_class = @rpc_context.method.input_type
+        def response_class = @rpc_context.method.output_type
+        def metadata = @rpc_context.metadata
+        def type = self
+        def client_streamer? = @rpc_context.method.kind == :client_streaming
+        def server_streamer? = @rpc_context.method.kind == :server_streaming
+        def bidi_streamer? = @rpc_context.method.kind == :bidi
+        def request_response? = @rpc_context.method.kind == :unary
+
+        def service_key
+          name = service.name || @rpc_context.method.service
+          name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .gsub("::", ".").downcase.delete_suffix(".service")
+        end
+
+        def method_name = "#{service_key}.#{method_key}"
+
+        def message
+          return @original.message unless @rpc_context.method.client_streaming?
+
+          @message ||= client_streamer? ? proc { |&block| @original.each_message(&block) } : @original.each_message
+        end
+
+        def messages(&block)
+          return [message] unless @rpc_context.method.client_streaming?
+
+          block ? @original.each_message(&block) : @original.each_message
+        end
+      end
+
+      class Error
+        Field = Struct.new(:field_name, :error_code, :message)
+        DebugInfo = Struct.new(:detail, :stack_trace)
+        attr_accessor :code, :app_code, :message
+        attr_reader :field_errors, :debug_info, :metadata
+
+        def initialize
+          @field_errors = []
+          @metadata = {}
+        end
+
+        def add_field_error(field, code, message = "") = @field_errors << Field.new(field, code, message)
+        def has_field_errors? = !@field_errors.empty? # rubocop:disable Naming/PredicatePrefix -- Preserve the upstream Gruf method name.
+
+        def set_debug_info(detail, stack_trace = [])
+          @debug_info = DebugInfo.new(detail, stack_trace.is_a?(String) ? stack_trace.split("\n") : Array(stack_trace))
+        end
+
+        def metadata=(value)
+          @metadata = value.transform_values(&:to_s)
+        end
+
+        def to_h
+          { code:, app_code:, message:, field_errors: field_errors.map(&:to_h), debug_info: debug_info.to_h }
+        end
+
+        def fail!(_active_call = nil)
+          canonical = { bad_request: :invalid_argument, unauthorized: :permission_denied }.fetch(code, code)
+          trailers = metadata.merge("error-internal-bin" => JSON.generate(to_h))
+          raise Gritz::Errors.for_code(canonical).new(message, metadata: trailers)
+        end
+      end
+
+      module ErrorHelpers
+        def add_field_error(...) = error.add_field_error(...)
+        def has_field_errors? = error.has_field_errors? # rubocop:disable Naming/PredicatePrefix -- Preserve the upstream Gruf method name.
+        def set_debug_info(...) = error.set_debug_info(...)
+
+        def fail!(code, app_code = nil, message = "", metadata = {})
+          error.code = code.to_sym
+          error.app_code = app_code ? app_code.to_sym : error.code
+          error.message = message.to_s
+          error.metadata = metadata
+          error.fail!(request.active_call)
+        end
+      end
+
+      # Controller base retaining selected Gruf request, error and streaming APIs.
+      # @api public
+      class Controller < Gritz::Controller
+        include ErrorHelpers
+
+        def self.bound_service = service_class
+
+        def self.action_defined?(action)
+          super && ![Controller, ErrorHelpers].include?(instance_method(action).owner)
+        end
+
+        def initialize(context:)
+          super
+          @request = Gruf.request_for(context)
+        end
+
+        def error = request.error
+
+        def process(action)
+          result = super
+          return result unless context.method.server_streaming?
+
+          result.each { |message| stream.write(message) } if result.respond_to?(:each)
+          nil
+        end
+      end
+
+      Base = Controller
+
+      # Base for migrated interceptors whose #call yields to the next handler.
+      # @api public
+      class ServerInterceptor
+        include ErrorHelpers
+
+        attr_reader :request, :error, :options
+
+        def initialize(request, error, options = {})
+          @request = request
+          @error = error
+          @options = options
+        end
+      end
+
+      class InterceptorAdapter
+        def initialize(app, klass, options)
+          @app = app
+          @klass = klass
+          @options = options
+        end
+
+        def call(context)
+          request = Gruf.request_for(context)
+          @klass.new(request, request.error, @options.dup).call { @app.call(context) }
+        end
+      end
+    end
+  end
+end

data/lib/gritz/configuration.rb

@@ -10,7 +10,7 @@ module Gritz
       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,
+      fork_mode: :clean, fork_guard: :raise, strict_routes: false, reflection: 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,
@@ -28,7 +28,7 @@ module Gritz
     }.freeze
     HOOKS = %i[before_fork on_worker_boot on_worker_shutdown].freeze
 
-    attr_accessor(*DEFAULTS.keys, :controllers, :middleware, :preload_app)
+    attr_accessor(*DEFAULTS.keys, :controllers, :middleware, :preload_app, :metrics_recorder_factory)
     attr_reader :health_checks
 
     def initialize
@@ -98,6 +98,9 @@ module Gritz
       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)
+      if metrics_recorder_factory && !metrics_recorder_factory.respond_to?(:call)
+        raise ConfigurationError, "metrics recorder factory must be callable"
+      end
       raise ConfigurationError, "preload_app must be boolean" unless [true, false].include?(preload_app)
       unless log_redact.all? { |name| name.is_a?(String) || name.is_a?(Symbol) }
         raise ConfigurationError, "log_redact must contain metadata names"
@@ -116,7 +119,9 @@ module Gritz
       validate!
       raise ConfigurationError, "This release supports transport :native" unless transport == :native
       raise ConfigurationError, "This release supports listener_strategy :reuseport" unless listener_strategy == :reuseport
-      raise ConfigurationError, "This release supports metrics_backend :pipe" unless metrics_backend == :pipe
+      unless metrics_backend == :pipe || (metrics_backend == :otlp && metrics_recorder_factory)
+        raise ConfigurationError, "metrics_backend requires an installed recorder (:pipe is built in)"
+      end
       raise ConfigurationError, "This release supports phased_restart_surge 1" unless phased_restart_surge == 1
 
       unless worker_recycle.empty?
@@ -143,6 +148,7 @@ module Gritz
 
     def preload!
       @preloaders.each(&:call)
+      Core::LOADER.eager_load
     end
 
     def add_hook(name, &block)

data/lib/gritz/controller.rb

@@ -42,7 +42,7 @@ module Gritz
 
     def initialize(context:)
       @context = context
-      @request = Request.new(context.call, context)
+      @request = Request.for(context)
       @stream = Stream.new(context.call, context)
     end
 
@@ -93,6 +93,13 @@ module Gritz
 
     # @api public
     class Request
+      STORE_KEY = Object.new.freeze
+
+      # @api private
+      def self.for(context)
+        context.store[STORE_KEY] ||= new(context.call, context)
+      end
+
       def initialize(call, context)
         @call = call
         @context = context

data/lib/gritz/core/version.rb

@@ -2,6 +2,6 @@
 
 module Gritz
   module Core
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/gritz/errors.rb

@@ -6,14 +6,16 @@ module Gritz
   class Error < StandardError
     attr_reader :details, :metadata
 
-    def initialize(message = nil, details: [], metadata: {})
+    def initialize(message = nil, details: [], metadata: {}, remote: false)
       super(message || code.to_s.tr("_", " "))
       @details = details
       @metadata = metadata
+      @remote = remote
     end
 
     def code = self.class::CODE
     def grpc_code = self.class::GRPC_CODE
+    def remote? = @remote
 
     CODE = :unknown
     GRPC_CODE = 2

data/lib/gritz/metrics/recorder.rb

@@ -56,6 +56,10 @@ module Gritz
         end
       end
 
+      # Optional process observations and shutdown for installed worker backends.
+      def observe_worker(_status); end
+      def close(timeout: nil); end
+
       # The caller retains this detached delta until its status channel accepts the row.
       def take_delta(max_bytes: Supervisor::StatusChannel::MAX_LINE_BYTES - 4096)
         raise ArgumentError, "Metric packet budget must be positive" unless max_bytes.is_a?(Integer) && max_bytes.positive?

data/lib/gritz/middleware/exception_mapper.rb

@@ -7,16 +7,19 @@ module Gritz
     # Converts application exceptions to safe RPC errors.
     # @api public
     class ExceptionMapper
-      def initialize(app, mappings: {}, expose_errors: false)
+      def initialize(app, mappings: {}, expose_errors: false, passthrough_remote_errors: false)
         @app = app
         @mappings = mappings
         @expose_errors = expose_errors
+        @passthrough_remote_errors = passthrough_remote_errors
       end
 
       def call(context)
         @app.call(context)
-      rescue Gritz::Error
-        raise
+      rescue Gritz::Error => e
+        raise unless e.remote? && !@passthrough_remote_errors
+
+        raise_internal(context, e)
       rescue StandardError => e
         mapping = @mappings.find { |klass, _| e.is_a?(klass) }&.last
         if mapping
@@ -30,9 +33,15 @@ module Gritz
           raise Errors::InvalidArgument, "invalid record"
         end
 
+        raise_internal(context, e)
+      end
+
+      private
+
+      def raise_internal(context, error)
         error_id = SecureRandom.uuid
-        context.store[:gritz_error] = { error_id: error_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 })
+        context.store[:gritz_error] = { error_id: error_id, error: error.class.name, message: error.message, backtrace: error.backtrace }
+        raise Errors::Internal.new(@expose_errors ? error.message : "internal error (#{error_id})", metadata: { "error-id" => error_id })
       end
     end
   end

data/lib/gritz/supervisor/admin_server.rb

@@ -23,6 +23,7 @@ module Gritz
         @metrics = metrics
         @logger = logger
         @clients = {}
+        @read_buffer = +""
       end
 
       def ios = [@io, *@clients.keys]
@@ -68,7 +69,7 @@ module Gritz
       end
 
       def read_request(socket, client)
-        chunk = socket.read_nonblock(4096, exception: false)
+        chunk = socket.read_nonblock(4096, @read_buffer, exception: false)
         return if chunk == :wait_readable
         return drop(socket) if chunk.nil?
 

data/lib/gritz/supervisor/launcher.rb

@@ -49,7 +49,7 @@ module Gritz
           end
           update_lifecycle
           @admin&.poll
-          @observer&.write(status)
+          @observer&.write { status }
           @observer&.flush
           break if @stopping && @generations.empty?
 

data/lib/gritz/supervisor/master.rb

@@ -50,7 +50,10 @@ module Gritz
           advance_replacement
           maintain_worker_count unless @shutdown_at
           flush_forwarded
-          @reports&.write(@owner_channel ? status.merge(type: "status") : status) if @forwarded.empty?
+          if @reports && @forwarded.empty? && (!@next_report_at || now >= @next_report_at || @shutdown_at) &&
+             @reports.write { @owner_channel ? status.merge(type: "status") : status }
+            @next_report_at = now + @config.status_interval
+          end
           @admin&.poll
           if @owner_channel&.closed?
             @exit_status = 1
@@ -132,6 +135,7 @@ module Gritz
         handle = WorkerHandle.new(pid: pid, index: index, status_io: reader)
         handle.recycle_factor = 1.0 + (rand * @config.worker_recycle.fetch(:jitter, 0.0))
         @workers[pid] = handle
+        @next_report_at = nil
         @logger.info("Worker #{index} spawned pid=#{pid}")
         handle
       rescue StandardError
@@ -159,7 +163,9 @@ module Gritz
             end
             next
           end
+          changed = handle.state != message[:state] || (message.key?(:healthy) && handle.stats[:healthy] != message[:healthy])
           handle.update(message, now: now)
+          @next_report_at = nil if changed
           if message[:state] == "failed" && !@ever_ready
             @exit_status = 1
             begin_shutdown
@@ -207,6 +213,7 @@ module Gritz
             break if handle.channel.closed?
           end
           @workers.delete(pid)
+          @next_report_at = nil
           @metrics.forget(handle)
           handle.close
           child_status = result.last
@@ -223,10 +230,12 @@ module Gritz
           break unless @forwarded.empty?
         rescue Errno::ECHILD
           @workers.delete(pid)&.close
+          @next_report_at = nil
         end
       end
 
       def handle_signal(signal)
+        @next_report_at = nil
         case signal
         when "TERM", "INT" then begin_shutdown
         when "QUIT" then begin_shutdown(immediate: true)
@@ -301,6 +310,7 @@ module Gritz
             kill(fresh) if fresh
             @logger.warn("Replacement failed; keeping previous workers")
             @replacement = nil
+            @next_report_at = nil
             @replacement_queue.clear
             @recycle_retry_at = now + @config.worker_boot_timeout
             return true
@@ -314,6 +324,7 @@ module Gritz
           return if old || !@replacement[:retired]
 
           @replacement = nil
+          @next_report_at = nil
         end
         while (entry = @replacement_queue.shift)
           old_pid, reason = entry

data/lib/gritz/supervisor/signal_queue.rb

@@ -10,6 +10,7 @@ module Gritz
       def initialize(signals:)
         @io, @writer = IO.pipe
         @pending = []
+        @read_buffer = +""
         @previous = {}
         signals.each do |name|
           @previous[name] = Signal.trap(name) do
@@ -26,7 +27,7 @@ module Gritz
 
       def drain
         loop do
-          break unless @io.read_nonblock(4096, exception: false).is_a?(String)
+          break unless @io.read_nonblock(4096, @read_buffer, exception: false).is_a?(String)
         end
         # Swap instead of clearing: a signal arriving here belongs to the next drain.
         pending = @pending

data/lib/gritz/supervisor/status_channel.rb

@@ -16,14 +16,16 @@ module Gritz
       def initialize(io)
         @io = io
         @buffer = +""
+        @read_buffer = +""
         @pending = +""
         @discarding = false
         @closed = io.closed?
       end
 
-      def write(status)
+      def write(status = nil)
         return false if closed? || flush_pending.positive?
 
+        status = yield if block_given?
         line = "#{JSON.generate(status)}\n"
         return false if line.bytesize > MAX_LINE_BYTES
 
@@ -54,7 +56,7 @@ module Gritz
 
         remaining = max_bytes
         while remaining.positive?
-          chunk = @io.read_nonblock([4096, remaining].min, exception: false)
+          chunk = @io.read_nonblock([4096, remaining].min, @read_buffer, exception: false)
           break if chunk == :wait_readable
 
           if chunk.nil?

data/lib/gritz/worker/runner.rb

@@ -28,6 +28,7 @@ module Gritz
           @boot_started = true
           @config.preload! unless @config.preload_app?
           @config.run_hooks(:on_worker_boot, @index)
+          @recorder = @config.metrics_recorder_factory.call(worker: @index) if @config.metrics_recorder_factory
           router = Router.new(controllers: @config.controllers, strict: @config.strict_routes, logger: @logger)
           dispatcher = Dispatcher.new(router:, middleware: @config.middleware, logger: @logger, metrics: @recorder,
                                       worker: @index, log_format: @config.log_format, log_redact: @config.log_redact)
@@ -94,7 +95,7 @@ module Gritz
           if @pending_reexec && @owner_channel.write(type: "reexec", pid: Process.pid)
             @pending_reexec = false
           end
-          publish_metrics
+          publish_metrics if @pending_delta || now >= next_status
           @admin&.poll
           if now >= next_status
             report(@draining ? "draining" : "ready")
@@ -114,6 +115,7 @@ module Gritz
                    busy_threads: stats.fetch(:busy_threads, stats.fetch(:busy, 0)), healthy: state == "ready" && @healthy,
                    checks: @checks || {}, worker_started_at: @born_at)
         @last_status = row.merge(extra)
+        @recorder.observe_worker(@last_status)
         @status&.write(@owner_channel ? snapshot : @last_status)
       end
 
@@ -184,6 +186,7 @@ module Gritz
         @status.io.wait_writable((deadline - monotonic).clamp(0, 0.01)) until !@status || @status.flush || @status.closed? || monotonic >= deadline
       ensure
         begin
+          cleanup { @recorder.close(timeout: [(deadline || monotonic) - monotonic, 0].max) }
           @signals&.close
           @admin&.close
         ensure

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: gritz-core
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Yudai Takada
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -113,15 +113,23 @@ description: Transport-independent controllers, routing, middleware, configurati
   and testing for Gritz.
 email:
 - t.yudai92@gmail.com
-executables: []
+executables:
+- gritz-migrate-gruf
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- exe/gritz-migrate-gruf
 - lib/gritz/call.rb
+- lib/gritz/channel_registry.rb
 - lib/gritz/cli.rb
+- lib/gritz/client.rb
+- lib/gritz/client/call_context.rb
+- lib/gritz/client/invocation.rb
+- lib/gritz/compat/gruf.rb
+- lib/gritz/compat/gruf/config_converter.rb
 - lib/gritz/configuration.rb
 - lib/gritz/configuration_error.rb
 - lib/gritz/context.rb