tonic-rails 0.1.0 → 0.3.0

data/lib/tonic/rails/health.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # What grpc.health.v1 reports, per service ("" = the whole server).
+    #
+    # A service reports SERVING only while the app hasn't marked it
+    # NOT_SERVING (Server#not_serving!) *and* the optional
+    # `config.health_check` passes.  Neither overrides the other.
+    # @api private
+    class Health
+      def initialize(configuration, router)
+        @configuration = configuration
+        @router = router
+        @marks = {}
+        @check_passing = true
+        @native = nil
+        @checker = nil
+      end
+
+      def mark(services, serving)
+        names = services.empty? ? names_to_report : services.map(&:to_s)
+        names.each { |name| @marks[name] = serving }
+        publish(names)
+      end
+
+      # Start reporting through a running native server.
+      def attach(native)
+        @native = native
+        @check_passing = true
+        publish(names_to_report)
+        start_checker
+      end
+
+      # Stop the checker before shutdown flips everything NOT_SERVING, so
+      # a passing check can't flip it back.
+      def detach
+        stop_checker
+        @native = nil
+      end
+
+      private
+
+      def names_to_report
+        ["", *@router.service_names, *@marks.keys].uniq
+      end
+
+      def publish(names)
+        native = @native
+        return unless native
+
+        names.each { |name| native.set_health(name, @check_passing && @marks.fetch(name, true)) }
+      end
+
+      def start_checker
+        check = @configuration.health_check
+        return unless check
+
+        @wakeup = Thread::Queue.new
+        @checker = Thread.new do
+          Thread.current.name = "tonic-rails-health"
+          loop do
+            passing = run_check(check)
+            changed(passing) if passing != @check_passing
+            break if @wakeup.pop(timeout: @configuration.health_check_interval)
+          end
+        end
+      end
+
+      def stop_checker
+        return unless @checker
+
+        @wakeup << :stop
+        @checker.join(@configuration.drain_timeout.to_f + 5)
+        @checker = nil
+      end
+
+      def changed(passing)
+        @check_passing = passing
+        publish(names_to_report)
+        logger = @configuration.logger
+        return unless logger
+
+        if passing
+          logger.info("tonic-rails: health check passing; SERVING")
+        else
+          logger.warn("tonic-rails: health check failing; NOT_SERVING")
+        end
+      end
+
+      # Runs inside the Rails executor so database connections are returned.
+      def run_check(check)
+        result = if defined?(::Rails.application) && ::Rails.application
+          ::Rails.application.executor.wrap { check.call }
+        else
+          check.call
+        end
+        result ? true : false
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "health check")
+        false
+      end
+    end
+  end
+end

data/lib/tonic/rails/instrumentation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/notifications"
+
+module Tonic
+  module Rails
+    # Every RPC is wrapped in an ActiveSupport::Notifications event, so APM
+    # agents, OpenTelemetry and your own subscribers can observe it:
+    #
+    #   ActiveSupport::Notifications.subscribe("process_rpc.tonic_rails") do |event|
+    #     event.payload[:path]      # "/demo.v1.ItemService/GetItem"
+    #     event.payload[:service]   # "demo.v1.ItemService"
+    #     event.payload[:rpc]       # "GetItem"
+    #     event.payload[:metadata]  # request metadata Hash
+    #     event.payload[:code]      # gRPC status code, 0 = OK
+    #     event.payload[:status]    # :ok, :not_found, :internal, ...
+    #     event.duration            # milliseconds
+    #   end
+    #
+    # When a call fails, :exception_object holds the RpcError. If a handler
+    # raised something unexpected, that RpcError's #cause is the original
+    # exception.
+    module Instrumentation
+      EVENT = "process_rpc.tonic_rails"
+
+      module_function
+
+      # @api private
+      def instrument(path, metadata)
+        # Without subscribers, skip building the payload: this runs on
+        # every RPC.
+        return yield unless ActiveSupport::Notifications.notifier.listening?(EVENT)
+
+        service, rpc = path.delete_prefix("/").split("/", 2)
+        payload = { path: path, service: service, rpc: rpc, metadata: metadata, code: nil, status: nil }
+        ActiveSupport::Notifications.instrument(EVENT, payload) do
+          result = yield
+          payload[:code] = 0
+          payload[:status] = :ok
+          result
+        rescue RpcError => e
+          payload[:code] = e.code
+          payload[:status] = e.code_name
+          raise
+        rescue StandardError
+          payload[:code] = RpcError::CODES[:internal]
+          payload[:status] = :internal
+          raise
+        end
+      end
+
+      # Logs one line per RPC through the configured logger, e.g.
+      #   gRPC /demo.v1.ItemService/GetItem OK in 1.4ms
+      #   gRPC /demo.v1.ItemService/GetItem NOT_FOUND in 0.9ms: item 7 not found
+      # Enabled by `config.log_requests = true`.
+      class RequestLogger
+        def initialize(logger)
+          @logger = logger
+        end
+
+        def call(event)
+          payload = event.payload
+          status = (payload[:status] || :unknown).to_s.upcase
+          line = format("gRPC %<path>s %<status>s in %<ms>.1fms", path: payload[:path], status: status, ms: event.duration)
+          error = payload[:exception_object]
+          line = "#{line}: #{error.message}" if error && payload[:code] != 0
+          @logger.info(line)
+        end
+
+        # @return [Object] the subscription, for #unsubscribe
+        def subscribe
+          ActiveSupport::Notifications.subscribe(EVENT, self)
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/metadata.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # Converts handler-supplied gRPC metadata into header pairs.
+    #
+    # Names are lower-cased and must be valid gRPC metadata names; names
+    # ending in "-bin" carry binary values, which are base64-encoded as the
+    # gRPC spec requires.  Other values must be printable ASCII.
+    module Metadata
+      NAME = /\A[0-9a-z_.-]+\z/
+      PRINTABLE = /\A[\x20-\x7e]*\z/
+      RESERVED = %w[content-type te user-agent content-length connection transfer-encoding].freeze
+
+      module_function
+
+      # @param metadata [Hash{String,Symbol=>String,Array<String>}]
+      # @return [Hash{String=>String}]
+      # @raise [ArgumentError] for invalid or reserved names and values
+      def encode(metadata)
+        metadata.each_with_object({}) do |(name, value), out|
+          name = name.to_s.downcase
+          validate_name!(name)
+          out[name] = encode_value(name, value)
+        end
+      end
+
+      def validate_name!(name)
+        raise ArgumentError, "invalid gRPC metadata name #{name.inspect}" unless NAME.match?(name)
+        return unless RESERVED.include?(name) || (name.start_with?("grpc-") && name != "grpc-status-details-bin")
+
+        raise ArgumentError, "gRPC metadata name #{name.inspect} is reserved"
+      end
+
+      def encode_value(name, value)
+        values = Array(value).map(&:to_s)
+        if name.end_with?("-bin")
+          values.map { |v| [v].pack("m0") }.join(",")
+        else
+          values.each do |v|
+            next if PRINTABLE.match?(v)
+
+            raise ArgumentError, "gRPC metadata #{name} must be printable ASCII; use a -bin name for binary"
+          end
+          values.join(",")
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/peer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # The client on the other end of an RPC, available in handlers as
+    # `peer`:
+    #
+    #   peer.address       # => "10.0.4.17:51234"
+    #   peer.ip            # => "10.0.4.17"
+    #   peer.certificate   # => OpenSSL::X509::Certificate, with mutual TLS
+    #   peer.certificate&.subject.to_s  # => "/CN=billing-service"
+    class Peer
+      # @return [String, nil] "ip:port" ("[ipv6]:port" for IPv6)
+      attr_reader :address
+
+      # @param address [String, nil]
+      # @param certificates [Array<String>] DER-encoded chain, leaf first
+      def initialize(address = nil, certificates = [])
+        @address = address
+        @certificate_ders = certificates
+      end
+
+      # @return [String, nil]
+      def ip
+        return unless address
+
+        host = address.rpartition(":").first
+        host.delete_prefix("[").delete_suffix("]")
+      end
+
+      # @return [Integer, nil]
+      def port
+        address && Integer(address.rpartition(":").last, exception: false)
+      end
+
+      # The client certificate presented over mutual TLS, or nil.
+      # @return [OpenSSL::X509::Certificate, nil]
+      def certificate
+        certificate_chain.first
+      end
+
+      # @return [Array<OpenSSL::X509::Certificate>] leaf first
+      def certificate_chain
+        @certificate_chain ||= begin
+          require "openssl"
+          @certificate_ders.map { |der| OpenSSL::X509::Certificate.new(der) }
+        end
+      end
+
+      # True when the client authenticated with a certificate.
+      def authenticated?
+        !@certificate_ders.empty?
+      end
+
+      def inspect
+        "#<#{self.class.name} #{address || 'unknown'}#{' (certificate)' if authenticated?}>"
+      end
+    end
+  end
+end

data/lib/tonic/rails/railtie.rb

@@ -28,8 +28,8 @@ module Tonic
       config.after_initialize do
         configuration = Tonic::Rails.configuration
         # Only inside an actual web server process — not consoles, rake
-        # tasks, or test runs.  Forking servers (Puma cluster mode) must
-        # instead start the server per worker, e.g. in `on_worker_boot`.
+        # tasks, or test runs.  With Puma, prefer `plugin :tonic_rails`
+        # (lib/puma/plugin/tonic_rails.rb), which also covers cluster mode.
         if configuration.auto_start && defined?(::Rails::Server)
           server = Tonic::Rails.server
           thread = Thread.new do

data/lib/tonic/rails/router.rb

@@ -38,6 +38,7 @@ module Tonic
           reader: call[:reader],
           sender: call[:sender],
           timeout_ms: call[:timeout_ms],
+          peer: Peer.new(call[:peer_address], call[:peer_certificates] || []),
         )
       end
 

data/lib/tonic/rails/rpc_error.rb

@@ -2,13 +2,23 @@
 
 module Tonic
   module Rails
-    # Raise from a handler to end the RPC with a gRPC status.
+    # Raise from a handler (or interceptor) to end the RPC with a gRPC status.
     #
-    #   raise Tonic::Rails::RpcError.new("product not found", code: :not_found)
+    #   raise Tonic::Rails::RpcError.new("item not found", code: :not_found)
     #
-    # The message is sent to the client, so keep internal details out of
-    # it.  Any other exception becomes INTERNAL with a generic message
-    # and is logged server-side.
+    # Optionally attach trailing metadata and rich error details (protobuf
+    # messages such as google.rpc.BadRequest, sent in the standard
+    # grpc-status-details-bin trailer as a google.rpc.Status):
+    #
+    #   raise Tonic::Rails::RpcError.new(
+    #     "invalid item", code: :invalid_argument,
+    #     metadata: { "x-request-id" => request_id },
+    #     details: [Google::Rpc::BadRequest.new(field_violations: [...])],
+    #   )
+    #
+    # The message, metadata and details go to the client, so keep internal
+    # details out of them.  Any other exception becomes INTERNAL with a
+    # generic message and is logged server-side.
     class RpcError < Error
       CODES = {
         ok: 0,
@@ -35,13 +45,70 @@ module Tonic
       # @return [Integer] numeric gRPC status code
       attr_reader :code
 
+      # @return [Hash] trailing metadata sent with the status
+      attr_reader :metadata
+
+      # @return [Array<Google::Protobuf::AbstractMessage>] rich error details
+      attr_reader :details
+
       # @param message [String] status message sent to the client
       # @param code [Symbol, Integer] gRPC status code (see CODES)
-      def initialize(message = nil, code: :unknown)
+      # @param metadata [Hash] trailing metadata (see Tonic::Rails::Metadata)
+      # @param details [Array<Google::Protobuf::AbstractMessage>] messages
+      #   packed into google.rpc.Status.details
+      def initialize(message = nil, code: :unknown, metadata: {}, details: [])
         @code = self.class.normalize_code(code)
+        @metadata = metadata
+        @details = Array(details)
         super(message || code_name.to_s)
       end
 
+      # @api private
+      # @return [Hash{String=>String}] trailers to send with this status
+      def trailers
+        trailers = Metadata.encode(metadata)
+        trailers["grpc-status-details-bin"] = [status_proto].pack("m0") unless details.empty?
+        trailers
+      end
+
+      # The encoded google.rpc.Status (code = 1, message = 2, details = 3 as
+      # google.protobuf.Any), built directly so googleapis protos aren't a
+      # dependency.
+      def status_proto
+        require "google/protobuf/well_known_types"
+        buf = (+"").b
+        buf << field_key(1, 0) << varint(code)
+        buf << length_delimited(2, message.b)
+        details.each do |detail|
+          any = detail.is_a?(Google::Protobuf::Any) ? detail : Google::Protobuf::Any.pack(detail)
+          buf << length_delimited(3, Google::Protobuf::Any.encode(any))
+        end
+        buf
+      end
+
+      private
+
+      def field_key(field, wire_type)
+        varint((field << 3) | wire_type)
+      end
+
+      def length_delimited(field, bytes)
+        field_key(field, 2) + varint(bytes.bytesize) + bytes
+      end
+
+      def varint(value)
+        bytes = []
+        loop do
+          byte = value & 0x7f
+          value >>= 7
+          bytes << (value.zero? ? byte : byte | 0x80)
+          break if value.zero?
+        end
+        bytes.pack("C*")
+      end
+
+      public
+
       # @return [Symbol] e.g. :not_found
       def code_name
         CODE_NAMES.fetch(@code)

data/lib/tonic/rails/server.rb

@@ -20,9 +20,9 @@ module Tonic
         @router = Router.new
         @native = nil
         @state = :stopped
-        @stop_reader = nil
-        @stop_writer = nil
+        @stop_signal = nil
         @stop_requested = false
+        @health = Health.new(configuration, @router)
         @lock = Mutex.new
       end
 
@@ -51,25 +51,34 @@ module Tonic
           @configuration.validate!
           Tonic::Rails.native_extension!
           Tonic::Rails._set_shutting_down(false)
-          @stop_reader, @stop_writer = IO.pipe
+          # A Queue rather than a self-pipe: pushing to it is safe from trap
+          # handlers, and unlike pipes it can be waited on with a timeout
+          # on every platform (Windows select() only handles sockets).
+          @stop_signal = Thread::Queue.new
           stop if @stop_requested # requested while we were starting up
           @native = build_native_server
           @native.start_server
+          log_pump = spawn_log_pump
+          @health.attach(@native)
           @state = :running
 
+          request_log = subscribe_request_logger
           previous_handlers = install_signal_handlers ? trap_signals : {}
           workers = Array.new(@configuration.dispatch_threads) { |i| spawn_worker(i) }
           log_startup
           yield self if block_given?
 
           wait_for_stop(workers)
+          @health.detach
           shutdown(workers)
         ensure
+          ActiveSupport::Notifications.unsubscribe(request_log) if request_log
           previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
+          @health.detach
           @native&.stop_server
+          stop_log_pump(log_pump)
           @native = nil
-          [@stop_reader, @stop_writer].each { |io| io.close if io && !io.closed? }
-          @stop_reader = @stop_writer = nil
+          @stop_signal = nil
           Tonic::Rails._set_shutting_down(false)
           @state = :stopped
         end
@@ -79,15 +88,32 @@ module Tonic
       # other threads; returns immediately.
       def stop
         @stop_requested = true
-        @stop_writer&.write_nonblock(".", exception: false)
-      rescue IOError
-        # Already stopped.
+        @stop_signal&.push(:stop)
       end
 
       def running?
         @state == :running
       end
 
+      # Mark the whole server, or the given services (fully-qualified
+      # names), SERVING in grpc.health.v1.  Takes effect immediately when
+      # running, otherwise when the server starts.
+      #
+      # With `config.health_check`, a service reports SERVING only while the
+      # check passes *and* it's marked serving here.
+      def serving!(*services)
+        @health.mark(services, true)
+        self
+      end
+
+      # Mark the whole server, or the given services, NOT_SERVING (e.g. for
+      # maintenance), so load balancers and readiness probes route around
+      # this instance.  Calls are still served.
+      def not_serving!(*services)
+        @health.mark(services, false)
+        self
+      end
+
       # @return [Hash{Symbol=>Integer}] request and connection counters
       def stats
         native = @native
@@ -113,7 +139,6 @@ module Tonic
         native.set_worker_threads(config.worker_threads || 0)
         native.set_keepalive(config.keepalive_interval.to_f, config.keepalive_timeout.to_f)
         native.set_dispatch_queue_size(config.dispatch_queue_size)
-        native.set_log_requests(config.log_requests ? true : false)
         native.set_compression(config.compression ? true : false)
         native.set_reflection(config.reflection ? true : false)
         native.set_reflection_descriptors(Reflection.file_descriptors(@router.service_names)) if config.reflection
@@ -133,8 +158,9 @@ module Tonic
         end
 
         guarded = lambda do |path, metadata, transport|
-          call.call(path, metadata, transport)
-        rescue RpcError
+          Instrumentation.instrument(path, metadata) { call.call(path, metadata, transport) }
+        rescue RpcError => e
+          attach_error_trailers(transport, e)
           raise
         rescue StandardError => e
           Tonic::Rails.log_exception(e, path)
@@ -144,6 +170,15 @@ module Tonic
         wrap_with_rails_executor(guarded)
       end
 
+      # An RpcError's own metadata and rich details travel as trailers.
+      def attach_error_trailers(transport, error)
+        return if error.metadata.empty? && error.details.empty?
+
+        transport[:sender]&.add_trailers(error.trailers)
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "RpcError trailers")
+      end
+
       # Each RPC runs inside the Rails executor (or reloader, when code
       # reloading is on): ActiveRecord connections are returned, query
       # caches and CurrentAttributes are reset — the same isolation Rack
@@ -156,6 +191,41 @@ module Tonic
         ->(path, metadata, transport) { wrapper.wrap { callback.call(path, metadata, transport) } }
       end
 
+      def subscribe_request_logger
+        return unless @configuration.log_requests && @configuration.logger
+
+        Instrumentation::RequestLogger.new(@configuration.logger).subscribe
+      end
+
+      # Transport events from the Rust side (rejected calls, expired
+      # deadlines, refused connections, faults) can't call Ruby directly;
+      # this thread drains them into the configured logger.
+      def spawn_log_pump
+        native = @native
+        logger = @configuration.logger
+        @log_pump_running = true
+        Thread.new do
+          Thread.current.name = "tonic-rails-log"
+          write_transport_logs(logger, native.next_log_events(0.25)) while @log_pump_running
+          write_transport_logs(logger, native.next_log_events(0)) # whatever shutdown produced
+        rescue StandardError => e
+          warn("tonic-rails: log thread stopped: #{e.class}: #{e.message}")
+        end
+      end
+
+      def stop_log_pump(thread)
+        return unless thread
+
+        @log_pump_running = false
+        thread.join(2)
+      end
+
+      def write_transport_logs(logger, events)
+        return unless logger
+
+        events.each { |level, message| logger.public_send(level, "tonic-rails: #{message}") }
+      end
+
       def spawn_worker(index)
         native = @native
         Thread.new do
@@ -174,7 +244,7 @@ module Tonic
 
       def wait_for_stop(workers)
         loop do
-          break if @stop_reader.wait_readable(1)
+          break if @stop_signal.pop(timeout: 1)
 
           dead = workers.reject(&:alive?)
           unless dead.empty?

data/lib/tonic/rails/tasks/tonic-rails.rake

@@ -27,7 +27,19 @@ namespace :tonic_rails do
     ruby_out = ENV.fetch("RUBY_OUT", "lib/grpc")
     protos = Dir.glob(File.join(proto_dir, "**", "*.proto"))
     abort "No .proto files found in #{proto_dir}/" if protos.empty?
-    abort "protoc not found on PATH. Install the Protocol Buffers compiler." unless system("protoc", "--version", out: File::NULL)
+    version = begin
+      IO.popen(%w[protoc --version], err: File::NULL, &:read)[/\d+(\.\d+)+/]
+    rescue SystemCallError
+      nil
+    end
+    abort "protoc not found on PATH. Install the Protocol Buffers compiler (22.0 or newer)." unless version
+    # protoc before 22 emits the Ruby DSL that google-protobuf 4 removed
+    # (`undefined method 'build' for DescriptorPool` at load time).
+    major = version.split(".").then { |parts| parts.first == "3" ? parts[1].to_i : parts.first.to_i }
+    if major < 22
+      abort "protoc #{version} is too old for google-protobuf 4: install protoc 22.0 or newer " \
+            "(distribution packages are often older; see https://github.com/protocolbuffers/protobuf/releases)."
+    end
 
     FileUtils.mkdir_p(ruby_out)
     sh "protoc", "--ruby_out=#{ruby_out}", "-I#{proto_dir}", *protos

data/lib/tonic/rails/testing/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    module Testing
+      # Shared helpers for the RSpec matcher and Minitest assertions.
+      # @api private
+      module Errors
+        module_function
+
+        # Exceptions that carry a gRPC status: tonic-rails' own, and the
+        # official grpc gem client's, when it's loaded.
+        def classes
+          [Tonic::Rails::RpcError, (GRPC::BadStatus if defined?(GRPC::BadStatus))].compact
+        end
+
+        def status?(error)
+          classes.any? { |klass| error.is_a?(klass) }
+        end
+
+        # @return [Integer]
+        def code(error)
+          error.code
+        end
+
+        # @return [String] the status message the client sees.  The grpc
+        # gem keeps it in #details (its #message adds the code).
+        def message(error)
+          text = defined?(GRPC::BadStatus) && error.is_a?(GRPC::BadStatus) ? error.details.to_s : error.message
+          text.dup.force_encoding(Encoding::UTF_8)
+        end
+
+        def code_name(code)
+          Tonic::Rails::RpcError::CODE_NAMES.fetch(code, code)
+        end
+
+        def message_matches?(expected, actual)
+          expected.is_a?(Regexp) ? expected.match?(actual) : expected.to_s == actual
+        end
+
+        def describe(error)
+          "#{code_name(code(error)).to_s.upcase} (#{message(error).inspect})"
+        end
+      end
+    end
+  end
+end