gritz-core 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03bd5114b9267c0bc0b5daa80d14433d4941c753321338fc5b83b2281f4d6bf1
-  data.tar.gz: 67fabc1d94c5cca35149679a2e582c983a88122a5299638d05c639387ea48fa4
+  metadata.gz: 600c0b33c1d7f7008866ee20d789504559715612886cd3f8dc33413e5192cb36
+  data.tar.gz: c3797690d572a4d29f5275946b16f84b5717fb19e4f31fd6a20217ece840eb92
 SHA512:
-  metadata.gz: 22ba419be6cd7bf1754eaccc7af3bde09ac0ca9dcac494f5d1932306aa73d595e0861b1c9ff1af9e694195f86d6c19e3103161a721ccd8e3f4c88ae72c93c56d
-  data.tar.gz: 1986b1cc2c4a32d0baf218b8268b1ced8399931c1a48379f46071f891c09d4c89cfe489fb707683dcf0d4ed239c708b3bfdd36a156efb0696f14d1764a10eeb6
+  metadata.gz: f2858b3d8e39c28d309a3acce2255fcc42ec4aba071b2b79735025a840973ffe0016183204eb7e87c67b1a14f11fef48ffa9e6560234cfd5da0866ccd195f68f
+  data.tar.gz: 149a97e113197dc7691152d5aa0f7e246adb55cc0bb90a699b122078ea3272cd32787461808b78d7379804c83a487866f503d8eea7f135a5c356c011e40a2209

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,8 @@ 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.
+
 ## Development
 
 ```sh

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/configuration.rb

@@ -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?

data/lib/gritz/core/version.rb

@@ -2,6 +2,6 @@
 
 module Gritz
   module Core
-    VERSION = "0.3.0"
+    VERSION = "0.4.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/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)
@@ -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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gritz-core
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -121,7 +121,11 @@ files:
 - LICENSE.txt
 - README.md
 - 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/configuration.rb
 - lib/gritz/configuration_error.rb
 - lib/gritz/context.rb