gritz-native 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e8049bb49561c6146900ca5fdf2f40177d4da3352b488c0c090b834f28a76bd
-  data.tar.gz: f55456efb1b318a0079ebf027b77f41d63413ca2abc723319804fe07ee403165
+  metadata.gz: c84c8135c9f1374962f4dd07181d16d2568498ceb55c4eb03c7d0dce59d475d8
+  data.tar.gz: c4dbff62a8188ea82f4c49eb4a7b470a4fee5cbf9199489f88bbab74b8ee08fb
 SHA512:
-  metadata.gz: 7a98685d7f3d10fefba9d156e0d5f182aed3a497e3886534e082449629e6420422ef614fbe8e0b0b793ae6ada7cdcd03e357ec58db0bf3826d7627615b32cd09
-  data.tar.gz: d5051b7e5a6739eac2d3be2b53316b0def376af8bfbe91c77958c1d554e1e08842d3a6a298f359a735ed736e3310e430e8c842ea00650900af4dd9f3be245173
+  metadata.gz: c61a25e22d150d219828f0a07f9dc39069fb792b3c8b5fefd82b6af6637071d7849df836736bcfe600da23eff7d8f39d604f8b5602966768e92dcc3915f71fb1
+  data.tar.gz: 1d4279464949f4bfacaf45405bc9c670de00b25673d3a5dc6ec941de86c24bd9cb475b6db5790000425fb6c74883042515f65b645b5fefb875e33ebfb739723b

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.0
+
+- Connect `Gritz::Client` to all four native RPC forms with shared worker-local channels and deferred credentials.
+- Cancel unfinished response streams and decode downstream status, trailers and protobuf rich error details into typed Gritz errors.
+- Pass retry and load-balancing service configuration to the native channel.
+- Run installed worker telemetry with real-server test helpers and close it after the final RPC observations.
+
+## 0.3.0
+
+- Serve TLS and mTLS connections and expose authenticated client certificates to handlers.
+- Provide standard gRPC Health Check and Watch methods linked to application health and draining.
+- Finish accepted RPCs during graceful shutdown and phased worker replacement.
+- Report actual native thread-pool usage, including active Health watches.
+
 ## 0.2.0
 
 - Detect native gRPC constructors in the master before fork.

data/README.md

@@ -10,6 +10,10 @@ require "gritz/native"
 
 The entry point loads `gritz-core` and registers `Gritz::Transport::Native`. The configuration value is `transport :native`. Use [gritz](https://github.com/gritzrpc/gritz) for the default combination and executable. The Fiber adapter `gritz-async` is planned separately.
 
+The adapter also connects `Gritz::Client.define` to all four RPC forms, sharing channels within each worker and creating fresh connections after fork. It cancels unfinished streams, decodes rich downstream errors, and passes retry/load-balancing configuration to C-core. See the [client guide](https://github.com/gritzrpc/gritz-core/blob/main/docs/guides/clients.md).
+
+The [three-service integration report](https://github.com/gritzrpc/gritz-otel/blob/main/docs/reports/T4-08-client-chain.md) records worker-local channels, propagated deadlines, connected server/client spans and real OTLP/HTTP metrics.
+
 ```ruby
 Gritz::Testing::Server.start(controllers: [GreeterController]) do |server|
   stub = Helloworld::Greeter::Stub.new(server.address, :this_channel_is_insecure)
@@ -17,7 +21,7 @@ Gritz::Testing::Server.start(controllers: [GreeterController]) do |server|
 end
 ```
 
-The helper opens an ephemeral port and stops the server when the block exits. The helper runs a single process. Supervised native servers also support forked workers on Linux. This release uses insecure sockets; use a trusted network or a TLS-terminating proxy. See the [framework documentation](https://github.com/gritzrpc/gritz) for configuration and limitations.
+The helper opens an ephemeral port and stops the server when the block exits. The helper runs a single process. Supervised native servers support forked workers on Linux. TLS and required client certificate verification are configured with `tls cert:, key:, client_ca:`. Standard gRPC Health Check/Watch tracks application checks and draining. See the [Kubernetes guide](docs/guides/kubernetes.md) and [framework configuration](https://github.com/gritzrpc/gritz-core/blob/main/docs/guides/configuration.md).
 
 ## Development
 

data/lib/gritz/native/version.rb

@@ -2,6 +2,6 @@
 
 module Gritz
   module Native
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/gritz/native.rb

@@ -11,4 +11,8 @@ require_relative "transport/native"
 require_relative "transport/native/call"
 require_relative "transport/native/bridge"
 require_relative "transport/native/server"
+require_relative "transport/native/health"
+require_relative "transport/native/client"
 require_relative "testing/server"
+
+Gritz::Client.adapter = Gritz::Transport::Native::Client

data/lib/gritz/testing/server.rb

@@ -39,13 +39,20 @@ module Gritz
         begin
           @config.preload! if @config.preload_app?
           router = Router.new(controllers: @config.controllers, strict: @config.strict_routes, logger: @logger)
-          dispatcher = Dispatcher.new(router:, middleware: @config.middleware, logger: @logger)
-          @transport = Transport::Native.new(config: @config, dispatcher:, logger: @logger)
           @lifecycle_started = true
           @config.run_hooks(:on_worker_boot, 0)
+          @recorder = @config.metrics_recorder_factory&.call(worker: 0)
+          dispatcher = Dispatcher.new(router:, middleware: @config.middleware, logger: @logger, metrics: @recorder)
+          @transport = Transport::Native.new(config: @config, dispatcher:, logger: @logger)
           @port = transport.bind
           @address = @config.bind.sub(/:\d+\z/, ":#{port}")
           transport.start
+          unless @config.health_checks.empty?
+            @health_stop = Queue.new
+            @health_thread = Thread.new do
+              transport.refresh_health until @health_stop.pop(timeout: @config.status_interval)
+            end
+          end
           self
         rescue StandardError
           stop
@@ -57,12 +64,30 @@ module Gritz
         return if @stopped
 
         @stopped = true
+        deadline = monotonic + @config.shutdown_timeout
         begin
-          transport&.stop(deadline: Time.now + @config.shutdown_timeout)
+          @health_stop&.push(true)
+          if @health_thread && !@health_thread.join([deadline - monotonic, 0].max)
+            @health_thread.kill.join
+          end
+          transport&.stop(deadline: Time.now + [deadline - monotonic, 0].max)
         ensure
-          @config.run_hooks(:on_worker_shutdown, 0) if @lifecycle_started
+          begin
+            @config.run_hooks(:on_worker_shutdown, 0) if @lifecycle_started
+          ensure
+            begin
+              @recorder&.observe_rejected(transport.stats.fetch(:rejected_total, 0)) if transport
+              @recorder&.observe_worker({ pid: Process.pid, index: 0, state: "stopped" })
+            ensure
+              @recorder&.close(timeout: [deadline - monotonic, 0].max)
+            end
+          end
         end
       end
+
+      private
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
   end
 end

data/lib/gritz/transport/native/client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "client_invocation"
+
+module Gritz
+  module Transport
+    class Native
+      # Builds official gRPC connections only on the first process-local client call.
+      # @api private
+      class Client
+        Connection = Struct.new(:target, :credentials, :args, :channel, keyword_init: true)
+
+        def self.connect(target:, credentials:, args:)
+          resolved = credentials.respond_to?(:call) ? credentials.call : credentials
+          resolved = :this_channel_is_insecure if resolved == :insecure
+          channel_credentials = resolved.is_a?(GRPC::Core::CallCredentials) ? GRPC::Core::ChannelCredentials.new : resolved
+          channel = GRPC::ClientStub.setup_channel(nil, target, channel_credentials, args.dup)
+          Connection.new(target:, credentials: resolved, args:, channel:)
+        end
+
+        def self.invoke(stub_class:, connection:, method:, request:, options:, around:, &)
+          stub = stub_class.new(connection.target, connection.credentials,
+                                channel_override: connection.channel, channel_args: connection.args.dup)
+          stub.extend(ClientInvocation)
+          stub.instance_variable_set(:@gritz_around, around)
+          stub.public_send(method, request, options, &)
+        end
+      end
+    end
+  end
+end

data/lib/gritz/transport/native/client_invocation.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Transport
+    class Native
+      # Captures the generated stub's route and keeps middleware around native completion.
+      # @api private
+      module ClientInvocation
+        { request_response: :unary, client_streamer: :client_streaming,
+          server_streamer: :server_streaming, bidi_streamer: :bidi }.each do |native_method, kind|
+          define_method(native_method) do |method, request, marshal, unmarshal, **options, &block|
+            terminal = lambda do |context, &_reply|
+              execute_gritz_client(context) do |response|
+                input = context.method.client_streaming? ? context.each_request : context.request
+                super(method, input, marshal, unmarshal, **context.options.merge(return_op: true), &response)
+              end
+            end
+            @gritz_around.call(terminal, method:, kind:, request:, options:, &block)
+          end
+        end
+
+        private
+
+        def execute_gritz_client(context)
+          context.check_deadline!
+          context.check_cancelled!
+          response = if context.method.server_streaming?
+                       lambda do |message|
+                         context.check_deadline!
+                         context.check_cancelled!
+                         context.response_block.call(message)
+                       end
+                     end
+          operation = yield(response)
+          context.operation = operation
+          result = operation.execute
+          completed = true
+          result
+        rescue GRPC::BadStatus => e
+          raise decode_gritz_error(e)
+        ensure
+          if operation && !completed
+            context.store[:gritz_cancelled] = true
+            cancel_gritz_operation(operation)
+          end
+        end
+
+        def cancel_gritz_operation(operation)
+          operation.cancel
+        rescue GRPC::Core::CallError
+          # A received non-OK status may already have closed the native call.
+          nil
+        end
+
+        def decode_gritz_error(error)
+          status = begin
+            error.to_rpc_status
+          rescue Google::Protobuf::ParseError, TypeError, ArgumentError
+            nil
+          end
+          details = if status && status.code == error.code
+                      status.details.map { |any| decode_gritz_detail(any) }
+                    else
+                      []
+                    end
+          code = error.code.is_a?(Integer) && (1...Errors::CODES.length).cover?(error.code) ? error.code : 2
+          klass = Errors.for_code(code)
+          klass.new(error.details, details:, metadata: error.metadata.dup, remote: true)
+        end
+
+        def decode_gritz_detail(any)
+          descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(any.type_name)
+          descriptor.respond_to?(:msgclass) ? any.unpack(descriptor.msgclass) : any
+        rescue Google::Protobuf::ParseError, TypeError, ArgumentError
+          any
+        end
+      end
+    end
+  end
+end

data/lib/gritz/transport/native/health.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "grpc/health/v1/health_services_pb"
+
+module Gritz
+  module Transport
+    class Native
+      # Standard health RPCs share the server pool; each open Watch uses one pool thread.
+      # @api private
+      class Health < Grpc::Health::V1::Health::Service
+        # Ruby's server call view cannot observe cancellation until the call ends.
+        # Watch needs a dedicated close observer, with at most one per occupied pool thread.
+        class WatchDescriptor < GRPC::RpcDesc
+          def handle_server_streamer(active_call, method, interception)
+            request = active_call.read_unary_request
+            call = active_call.single_req_view
+            raw = active_call.instance_variable_get(:@call)
+            closed = false
+            observer = Thread.new do
+              raw.run_batch(GRPC::Core::CallOps::RECV_CLOSE_ON_SERVER => nil)
+            rescue GRPC::Core::CallError
+              nil
+            ensure
+              closed = true
+              method.receiver.wake
+            end
+            call.define_singleton_method(:cancelled?) { closed }
+            status = begin
+              interception.intercept!(:server_streamer, method:, call:, request:) do
+                method.call(request, call).each { |reply| active_call.remote_send(reply) }
+              end
+              ::Struct::Status.new(GRPC::Core::StatusCodes::OK, "OK", active_call.output_metadata)
+            rescue GRPC::BadStatus => e
+              ::Struct::Status.new(e.code, e.details, e.metadata)
+            rescue GRPC::Core::OutOfTime
+              ::Struct::Status.new(GRPC::Core::StatusCodes::DEADLINE_EXCEEDED, "late", {})
+            rescue StandardError, NotImplementedError
+              ::Struct::Status.new(GRPC::Core::StatusCodes::UNKNOWN, "Health handler failed", {})
+            end
+            active_call.send_initial_metadata
+            raw.run_batch(GRPC::Core::CallOps::SEND_STATUS_FROM_SERVER => status)
+            observer.join
+          rescue GRPC::Core::CallError
+            nil
+          ensure
+            if observer
+              raw.cancel if observer.alive?
+              observer.join
+              # Finish only after the native close operation has released its call resources.
+              active_call.__send__(:set_output_stream_done)
+            end
+          end
+        end
+
+        rpc_descs[:Watch] = WatchDescriptor.new(*rpc_descs.fetch(:Watch).to_a)
+
+        def initialize(services)
+          super()
+          @services = ["", *services].to_set
+          @mutex = Mutex.new
+          @changed = ConditionVariable.new
+          @serving = @closed = false
+        end
+
+        def update(ready)
+          @mutex.synchronize do
+            serving = ready && !@closed
+            @changed.broadcast if serving != @serving
+            @serving = serving
+          end
+        end
+
+        def drain!
+          @mutex.synchronize do
+            @serving = false
+            @closed = true
+            @changed.broadcast
+          end
+        end
+
+        def wake = @mutex.synchronize { @changed.broadcast }
+
+        def check(request, _call)
+          raise GRPC::NotFound, "unknown service" unless @services.include?(request.service)
+
+          @mutex.synchronize { Grpc::Health::V1::HealthCheckResponse.new(status: status_for(request.service)) }
+        end
+
+        def watch(request, call)
+          Enumerator.new do |replies|
+            previous = nil
+            loop do
+              status, closed = @mutex.synchronize do
+                @changed.wait(@mutex, 0.05) while !@closed && !call.cancelled? && status_for(request.service) == previous
+                [status_for(request.service), @closed]
+              end
+              break if call.cancelled?
+
+              if status != previous
+                replies << Grpc::Health::V1::HealthCheckResponse.new(status:)
+                previous = status
+              end
+              break if closed
+            end
+          end
+        end
+
+        private
+
+        def status_for(service)
+          return :SERVICE_UNKNOWN unless @services.include?(service)
+
+          @serving ? :SERVING : :NOT_SERVING
+        end
+      end
+    end
+  end
+end

data/lib/gritz/transport/native/server.rb

@@ -17,6 +17,14 @@ module Gritz
           result
         end
 
+        def busy_threads
+          # grpc 1.83 has no public busy count; its idle queues cover decode and
+          # response writes as well as handlers. Live threads also handle pre-start/stop.
+          workers = @pool.instance_variable_get(:@workers)
+          ready = @pool.instance_variable_get(:@ready_workers)
+          [workers.count(&:alive?) - ready.size, 0].max
+        end
+
         def stop(deadline:)
           # grpc 1.83's stop takes no deadline and reads @poll_period instead.
           # Set its relative grace from the caller's absolute shutdown deadline.
@@ -24,6 +32,37 @@ module Gritz
           super()
         end
 
+        # RpcServer's loop checks running_state before every RequestCall. Its stop
+        # holds that mutex during shutdown_and_notify, so an accepted RPC can leave
+        # the loop blocked while C-core still has unmatched calls. Keep consuming
+        # until C-core closes RequestCall instead of stopping on the Ruby state.
+        def loop_handle_server_calls
+          raise "not started" if running_state == :not_started
+
+          loop do
+            rpc = @server.request_call
+            break if rpc && rpc.call.nil?
+
+            active_call = new_active_server_call(rpc)
+            next unless active_call
+
+            @pool.schedule(active_call) do |pair|
+              call, method = pair
+              rpc_descs[method].run_server_method(call, rpc_handlers[method], @interceptors.build_context)
+            rescue StandardError
+              call.send_status(GRPC::Core::StatusCodes::INTERNAL, "Server handler failed")
+            end
+          rescue GRPC::Core::CallError, RuntimeError => e
+            break unless running_state == :running
+
+            GRPC.logger.warn("server call failed: #{e}")
+          end
+          @run_mutex.synchronize do
+            transition_running_state(:stopped)
+            @server.close
+          end
+        end
+
         def close_unstarted
           return unless running_state == :not_started
 

data/lib/gritz/transport/native.rb

@@ -8,7 +8,7 @@ module Gritz
     # Runs generated services through Gritz's transport-independent dispatcher.
     # @api public
     class Native
-      def self.capabilities = Set[:unary, :client_streaming, :server_streaming, :bidi, :reuseport].freeze
+      def self.capabilities = Set[:unary, :client_streaming, :server_streaming, :bidi, :reuseport, :health, :tls, :mtls].freeze
 
       def self.prefork
         GRPC.prefork
@@ -32,9 +32,9 @@ module Gritz
       # @return [Integer] the port selected by C-core
       def bind(listener_spec = @config.bind)
         raise ArgumentError, "transport is already bound" if @server
-        raise ArgumentError, "TLS is not available in this version" unless @config.tls.empty?
         raise ArgumentError, "at least one controller must be registered" if @dispatcher.router.routes.empty?
 
+        credentials = server_credentials
         created_server = @server = Server.new(
           pool_size: @config.threads,
           # grpc 1.83 accepts but ignores this value: busy pools reject immediately.
@@ -47,7 +47,9 @@ module Gritz
         @dispatcher.router.routes.values.group_by(&:service_class).each do |service_class, descriptors|
           @server.handle(Bridge.build(service_class, descriptors, self))
         end
-        @port = @server.add_http2_port(listener_spec, :this_port_is_insecure)
+        @health = Health.new(@dispatcher.router.routes.values.map(&:service).uniq)
+        @server.handle(@health)
+        @port = @server.add_http2_port(listener_spec, credentials)
         raise ArgumentError, "could not bind #{listener_spec}" unless @port.positive?
 
         @port
@@ -62,7 +64,10 @@ module Gritz
         raise ArgumentError, "transport is already started" if @thread
 
         @thread = Thread.new { @server.run }
-        return self if @server.wait_till_running(5)
+        if @server.wait_till_running(5)
+          refresh_health
+          return self
+        end
 
         @thread.value unless @thread.alive?
         kill
@@ -76,6 +81,7 @@ module Gritz
       def running? = @thread&.alive? && @server.running?
 
       def stop(deadline:)
+        drain!
         unless @thread
           @server&.close_unstarted
           @server = nil
@@ -88,11 +94,35 @@ module Gritz
 
       def kill = stop(deadline: Time.now)
 
+      def update_health(ready:, checks: {})
+        healthy = ready && checks.values.all? && !@draining
+        @health&.update(healthy)
+        healthy
+      end
+
+      def drain!
+        @draining = true
+        @health&.drain!
+        self
+      end
+
+      # @api private
+      def refresh_health
+        checks = @config.health_checks.transform_values do |check|
+          check.call ? true : false
+        rescue StandardError => e
+          @logger.warn("Health check failed (#{e.class})")
+          false
+        end
+        update_health(ready: running?, checks:)
+      end
+
       def stats
+        busy = @server&.busy_threads || 0
         @lock.synchronize do
           oldest = @inflight.values.min
           {
-            inflight: @inflight.size, busy: @inflight.size, capacity: @config.threads,
+            inflight: @inflight.size, busy: busy, capacity: @config.threads,
             rejected_total: @rejected_total, requests_total: @requests_total,
             oldest_inflight_age: oldest ? Process.clock_gettime(Process::CLOCK_MONOTONIC) - oldest : 0
           }
@@ -114,6 +144,14 @@ module Gritz
 
       private
 
+      def server_credentials
+        return :this_port_is_insecure if @config.tls.empty?
+
+        ca = @config.tls[:client_ca] && File.read(@config.tls[:client_ca])
+        GRPC::Core::ServerCredentials.new(ca, [{ private_key: File.read(@config.tls.fetch(:key)),
+                                                 cert_chain: File.read(@config.tls.fetch(:cert)) }], !ca.nil?)
+      end
+
       def status_exception(call, error)
         metadata = call.trailing_metadata.merge(error.metadata)
         unless error.details.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gritz-native
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: grpc
   requirement: !ruby/object:Gem::Requirement
@@ -81,6 +81,9 @@ files:
 - lib/gritz/transport/native.rb
 - lib/gritz/transport/native/bridge.rb
 - lib/gritz/transport/native/call.rb
+- lib/gritz/transport/native/client.rb
+- lib/gritz/transport/native/client_invocation.rb
+- lib/gritz/transport/native/health.rb
 - lib/gritz/transport/native/server.rb
 homepage: https://github.com/gritzrpc/gritz-native
 licenses: