gritz-native 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1acc3257753cf7f6cb65db29e2c77692136a2050044b225b2cc73880fe67e9d3
-  data.tar.gz: 665dcaae2cc563da543b1305337cce4634d6094bfd39863ed09762765bae35c3
+  metadata.gz: 11284795837121fb007d3158c2fa704281946741d262e2101cf0ab3b134183e5
+  data.tar.gz: b1c1a7c414f1b3f435af88183f8da23dd7aaabcff4591355dbfdd138deeffcb0
 SHA512:
-  metadata.gz: 0ee1d520c991ea1b015215651b60a94071e73ccdf130b3e1bbf2982b4b72be90c448d3a2d89db82b37132f170bd6428455428f54d20be68c11f57a8b329be368
-  data.tar.gz: b1f58698b7e9cd52e1c94bf170ecdee3bf2ebec81a0a9ed2e954b81d7369f1dd880104306c2067e3b9fccf8d96b4c7ad48a4e45b1e1429bdafef861c465b5c45
+  metadata.gz: 832837820eb0ecb86bef7fe3cf84514f52a22b92933fb08bf9fd8d3cb48fee690585ba42c853bee984bdd801fb93c7fdaa96e5a873ffee93b976b417f99f08b0
+  data.tar.gz: f7b4a6ba6ba8ad367db6d6d486fc041471f73a7fa72663ed90ee71ed1445122d287c92c2ceaef986b9b7572445f3c03960e4a65f01af4588be904b2c67d251a8

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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.
+- Support experimental Linux grpc fork callbacks for parent-side clients.
+
 ## 0.1.0
 
 Initial release.

data/README.md

@@ -17,7 +17,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 server currently supports a single process and 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/fork_guard.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Constructor instrumentation installed without activating a master guard.
+# @api private
+module Gritz::Native::ForkGuard
+  [GRPC::Core::Channel, GRPC::Core::Server, GRPC::Core::ChannelCredentials,
+   GRPC::Core::ServerCredentials, GRPC::Core::CallCredentials, GRPC::ClientStub, GRPC::RpcServer].each do |klass|
+    Gritz::ForkGuard.install(klass)
+  end
+end

data/lib/gritz/native/version.rb

@@ -2,6 +2,6 @@
 
 module Gritz
   module Native
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/gritz/native.rb

@@ -6,8 +6,10 @@ require "google/rpc/status_pb"
 require "google/protobuf/any_pb"
 require "google/protobuf/well_known_types"
 require_relative "native/version"
+require_relative "native/fork_guard"
 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 "testing/server"

data/lib/gritz/testing/server.rb

@@ -46,6 +46,12 @@ module Gritz
           @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
@@ -58,6 +64,10 @@ module Gritz
 
         @stopped = true
         begin
+          @health_stop&.push(true)
+          if @health_thread && !@health_thread.join(@config.shutdown_timeout)
+            @health_thread.kill.join
+          end
           transport&.stop(deadline: Time.now + @config.shutdown_timeout)
         ensure
           @config.run_hooks(:on_worker_shutdown, 0) if @lifecycle_started

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,16 @@ 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
+      rescue RuntimeError => e
+        raise "#{e.message}. fork_mode :grpc_fork_support requires GRPC_ENABLE_FORK_SUPPORT=1 before requiring grpc."
+      end
+
+      def self.postfork_parent = GRPC.postfork_parent
+      def self.postfork_child = GRPC.postfork_child
 
       def initialize(config:, dispatcher:, logger:)
         @config = config
@@ -23,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.
@@ -38,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
@@ -53,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
@@ -67,6 +81,7 @@ module Gritz
       def running? = @thread&.alive? && @server.running?
 
       def stop(deadline:)
+        drain!
         unless @thread
           @server&.close_unstarted
           @server = nil
@@ -79,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
           }
@@ -105,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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: grpc
   requirement: !ruby/object:Gem::Requirement
@@ -75,11 +75,13 @@ files:
 - LICENSE.txt
 - README.md
 - lib/gritz/native.rb
+- lib/gritz/native/fork_guard.rb
 - lib/gritz/native/version.rb
 - lib/gritz/testing/server.rb
 - lib/gritz/transport/native.rb
 - lib/gritz/transport/native/bridge.rb
 - lib/gritz/transport/native/call.rb
+- lib/gritz/transport/native/health.rb
 - lib/gritz/transport/native/server.rb
 homepage: https://github.com/gritzrpc/gritz-native
 licenses:
@@ -103,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: gRPC C-core transport for Gritz
 test_files: []