tonic-rails 0.1.0-x86_64-linux-gnu → 0.3.0-x86_64-linux-gnu

data/lib/puma/plugin/tonic_rails.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "puma/plugin"
+
+# Runs the tonic-rails gRPC server alongside Puma:
+#
+#   # config/puma.rb
+#   plugin :tonic_rails
+#
+# The gRPC server runs as one child process of the Puma master, in single
+# and cluster mode alike, so it has its own GVL and never competes with web
+# workers.  It starts once Puma has booted, drains gracefully when Puma
+# stops or restarts, stops itself if Puma goes away, and if it dies
+# unexpectedly Puma shuts down too, so a supervisor can restart both.
+Puma::Plugin.create do
+  def start(launcher)
+    @launcher = launcher
+    unless Process.respond_to?(:fork)
+      log "tonic-rails: the Puma plugin needs fork(), which this platform lacks; " \
+          "run `bin/rails tonic_rails:serve` as a separate process instead"
+      return
+    end
+
+    @puma_pid = Process.pid
+    @grpc_pid = nil
+
+    events = launcher.events
+    if events.respond_to?(:after_booted) # Puma 7+
+      events.after_booted { start_grpc }
+      events.after_stopped { stop_grpc }
+      events.before_restart { stop_grpc }
+    else
+      events.on_booted { start_grpc }
+      events.on_stopped { stop_grpc }
+      events.on_restart { stop_grpc }
+    end
+
+    in_background { monitor_grpc }
+  end
+
+  private
+
+  def start_grpc
+    @grpc_pid = fork { run_grpc_server }
+    log "tonic-rails: gRPC server started (pid #{@grpc_pid})"
+  end
+
+  def run_grpc_server
+    # The web listeners belong to Puma; don't hold them open in this process.
+    @launcher.binder.ios.each { |io| io.close rescue nil } # rubocop:disable Style/RescueModifier
+    load_rails_app
+    Thread.new { stop_when_puma_exits }
+    Tonic::Rails.server.start
+  end
+
+  # `rails server` and preload_app! boot the app before forking; plain
+  # `puma` in cluster mode does not, so boot it here.
+  def load_rails_app
+    return if defined?(Rails.application) && Rails.application&.initialized?
+
+    require File.expand_path("config/environment", Dir.pwd)
+  end
+
+  # Puma fires its stop hooks from its TERM trap handler, so this must
+  # not block indefinitely: allow the server's drain timeout plus a margin,
+  # then kill it.
+  def stop_grpc
+    pid = @grpc_pid
+    return unless pid
+
+    @grpc_pid = nil
+    log "tonic-rails: stopping gRPC server (pid #{pid})"
+    Process.kill(:TERM, pid)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + stop_timeout
+    until Process.waitpid(pid, Process::WNOHANG)
+      if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        log "tonic-rails: gRPC server (pid #{pid}) did not stop in #{stop_timeout}s; killing it"
+        Process.kill(:KILL, pid)
+        Process.wait(pid)
+        break
+      end
+      sleep 0.05
+    end
+  rescue Errno::ESRCH, Errno::ECHILD
+    nil
+  end
+
+  def stop_timeout
+    drain = defined?(Tonic::Rails) ? Tonic::Rails.configuration.drain_timeout.to_f : 10.0
+    drain + 5
+  end
+
+  def monitor_grpc
+    loop do
+      sleep 1
+      pid = @grpc_pid
+      next unless pid && Process.waitpid(pid, Process::WNOHANG)
+
+      @grpc_pid = nil
+      log "tonic-rails: gRPC server (pid #{pid}) exited unexpectedly; stopping Puma"
+      Process.kill(:TERM, @puma_pid)
+      break
+    rescue Errno::ECHILD
+      nil
+    end
+  end
+
+  def stop_when_puma_exits
+    sleep 1 while Process.ppid == @puma_pid
+    Tonic::Rails.server.stop
+  end
+
+  def log(message)
+    @launcher.log_writer.log(message)
+  end
+end

data/lib/tonic/rails/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/callbacks"
+require "active_support/rescuable"
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/hash/keys"
 require "active_support/core_ext/string/inflections"
@@ -25,8 +27,17 @@ module Tonic
     # is set (fastest), or string-keyed Hashes by default.  Handlers may
     # return either a protobuf message or a Hash; streaming handlers
     # return any Enumerable of them.
+    #
+    # Like controllers, handlers get callbacks and exception mapping:
+    #
+    #   before_rpc :authenticate, except: :Health
+    #   rescue_from ActiveRecord::RecordNotFound, code: :not_found
+    #   rescue_from Pundit::NotAuthorizedError, with: :forbidden
     module Base
       def self.included(base)
+        base.include(ActiveSupport::Callbacks)
+        base.include(ActiveSupport::Rescuable)
+        base.define_callbacks(:rpc)
         base.extend(ClassMethods)
         base.class_attribute :grpc_service_name, instance_writer: false
         base.class_attribute :grpc_rpcs, instance_writer: false, default: {}
@@ -34,6 +45,20 @@ module Tonic
       end
 
       module ClassMethods
+        private
+
+        def add_rpc_callback(kind, methods, only, except, block)
+          only &&= rpc_name_matcher(only)
+          except &&= rpc_name_matcher(except)
+          condition = lambda do |handler|
+            name = handler.current_rpc.underscore
+            (only.nil? || only.include?(name)) && (except.nil? || !except.include?(name))
+          end
+          (methods + [block].compact).each { |callback| set_callback(:rpc, kind, callback, if: condition) }
+        end
+
+        public
+
         # @param name [String] fully-qualified service name, e.g. "shop.ProductService"
         def service(name)
           self.grpc_service_name = name.to_s
@@ -97,6 +122,51 @@ module Tonic
           end
         end
 
+        # Run a method or block before each RPC.  Raising (e.g. an RpcError)
+        # stops the call.  The decoded `request` is available.
+        # @param only [Symbol, String, Array] RPC names to apply to
+        # @param except [Symbol, String, Array] RPC names to skip
+        def before_rpc(*methods, only: nil, except: nil, &block)
+          add_rpc_callback(:before, methods, only, except, block)
+        end
+
+        # Run after each RPC that completes without raising (for streaming
+        # responses, after the last message is sent).
+        def after_rpc(*methods, only: nil, except: nil, &block)
+          add_rpc_callback(:after, methods, only, except, block)
+        end
+
+        # Wrap each RPC; the method or block must yield to run it.
+        def around_rpc(*methods, only: nil, except: nil, &block)
+          add_rpc_callback(:around, methods, only, except, block)
+        end
+
+        # Map exceptions raised during an RPC (including callbacks) to a
+        # gRPC status.  Same as ActiveSupport::Rescuable, plus a `code:`
+        # shorthand:
+        #
+        #   rescue_from ActiveRecord::RecordNotFound, code: :not_found
+        #   rescue_from Stale, code: :aborted, message: "please retry"
+        #   rescue_from Denied, with: :deny            # def deny(e) = raise RpcError...
+        #
+        # With `code:`, the client receives `message` (a String, or a Proc
+        # given the exception), defaulting to the exception's own message.
+        # Handlers given via `with:` or a block must raise an RpcError.
+        def rescue_from(*klasses, with: nil, code: nil, message: nil, &)
+          return super(*klasses, with: with, &) unless code
+
+          RpcError.normalize_code(code) # fail at definition time on typos
+          super(*klasses) do |exception|
+            text = message.respond_to?(:call) ? message.call(exception) : (message || exception.message)
+            raise RpcError.new(text, code: code)
+          end
+        end
+
+        # @api private
+        def rpc_name_matcher(names)
+          Array(names).map { |name| name.to_s.underscore }
+        end
+
         # @api private  Called by Server#register.
         def register_on(router)
           raise NotConfiguredError, "#{self} has no service name; call `service` or `rpc_service`" unless grpc_service_name
@@ -106,11 +176,38 @@ module Tonic
         end
       end
 
+      # The RPC being handled, as named in the .proto (e.g. "GetItem").
+      # @return [String]
+      attr_reader :current_rpc
+
+      # The client: address, and certificate with mutual TLS.
+      # @return [Tonic::Rails::Peer]
+      attr_reader :peer
+
+      # The decoded request: a message (or Hash), or for client-streaming
+      # RPCs an Enumerator of them.  Also passed to the handler method.
+      attr_reader :request
+
       # gRPC request metadata (lower-case header names).  Binary (`-bin`)
       # values are base64-encoded, as sent on the wire.
       # @return [Hash{String=>String}]
       attr_reader :grpc_metadata
 
+      # Response headers (initial metadata) for this call.  For streaming
+      # responses, set them before the first message; for unary RPCs,
+      # anywhere in the handler.  `-bin` names take binary values.
+      # @return [Hash]
+      def response_metadata
+        @response_metadata ||= {}
+      end
+
+      # Trailing metadata, sent with the final status, whether the call
+      # succeeds or fails.
+      # @return [Hash]
+      def trailing_metadata
+        @trailing_metadata ||= {}
+      end
+
       # Milliseconds left before the client's deadline, or nil if the
       # client did not set one.
       # @return [Integer, nil]
@@ -137,44 +234,74 @@ module Tonic
       # (`#push`) for server-streaming RPCs.
       # @return [String, nil] the encoded unary response, or nil when
       #   messages were streamed through `sender`
-      def call_rpc(rpc_name, metadata:, reader:, sender: nil, timeout_ms: nil)
+      def call_rpc(rpc_name, metadata:, reader:, sender: nil, timeout_ms: nil, peer: nil)
         spec = self.class.grpc_rpcs[rpc_name.to_s]
         raise RpcError.new("method not implemented", code: :unimplemented) unless spec
         raise RpcError.new("method #{rpc_name} not implemented", code: :unimplemented) unless respond_to?(spec[:handler])
 
+        @current_rpc = rpc_name.to_s
+        @peer = peer || Peer.new
         @grpc_metadata = metadata
+        @grpc_sender = sender
+        @grpc_headers_sent = false
         @grpc_deadline_at = timeout_ms && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + (timeout_ms / 1000.0))
 
-        request = if spec[:request_stream]
-          Enumerator.new do |y|
-            while (message = read_request(reader, spec))
-              y << message
-            end
-          end
+        @request = build_request(reader, spec)
+        response = nil
+        run_callbacks(:rpc) { response = respond(public_send(spec[:handler], @request), spec, sender) }
+        response
+      rescue RpcError
+        raise
+      rescue StandardError => e
+        rescue_exception(e)
+      ensure
+        attach_trailing_metadata
+      end
+
+      private
+
+      # rescue_from handlers must raise; anything they don't handle (or a
+      # handler that returns normally) becomes a logged INTERNAL error.
+      def rescue_exception(exception)
+        if rescue_with_handler(exception)
+          Tonic::Rails.log_exception(
+            TypeError.new("rescue_from handler for #{exception.class} returned instead of raising an RpcError"),
+            "#{self.class}##{current_rpc}",
+          )
         else
-          read_request(reader, spec) || raise(RpcError.new("missing request message", code: :invalid_argument))
+          Tonic::Rails.log_exception(exception, "#{self.class}##{current_rpc}")
         end
+        raise RpcError.new("internal error", code: :internal)
+      end
 
-        result = public_send(spec[:handler], request)
+      def build_request(reader, spec)
+        unless spec[:request_stream]
+          return read_request(reader, spec) || raise(RpcError.new("missing request message", code: :invalid_argument))
+        end
 
-        if spec[:response_stream]
-          unless result.respond_to?(:each)
-            raise TypeError, "streaming handler #{self.class}##{spec[:handler]} must return an Enumerable, got #{result.class}"
+        Enumerator.new do |y|
+          while (message = read_request(reader, spec))
+            y << message
           end
-
-          result.each { |item| push_response(sender, encode_response(item, spec)) }
-          nil
-        else
-          encode_response(result, spec)
         end
-      rescue RpcError
-        raise
-      rescue StandardError => e
-        Tonic::Rails.log_exception(e, "#{self.class}##{rpc_name}")
-        raise RpcError.new("internal error", code: :internal)
       end
 
-      private
+      # Unary: the encoded response.  Streaming: nil, after pushing each
+      # message through the sender.
+      def respond(result, spec, sender)
+        unless spec[:response_stream]
+          encoded = encode_response(result, spec)
+          send_response_headers
+          return encoded
+        end
+
+        unless result.respond_to?(:each)
+          raise TypeError, "streaming handler #{self.class}##{spec[:handler]} must return an Enumerable, got #{result.class}"
+        end
+
+        result.each { |item| push_response(sender, encode_response(item, spec)) }
+        nil
+      end
 
       def read_request(reader, spec)
         bytes = reader.next
@@ -205,11 +332,30 @@ module Tonic
       end
 
       def push_response(sender, bytes)
+        send_response_headers
         sender.push(bytes)
       rescue IOError
         # The client went away; nothing left to deliver to.
         raise RpcError.new("client cancelled the stream", code: :cancelled)
       end
+
+      def send_response_headers
+        return if @grpc_headers_sent
+
+        @grpc_headers_sent = true
+        return if @response_metadata.nil? || @response_metadata.empty? || @grpc_sender.nil?
+
+        @grpc_sender.send_headers(Metadata.encode(@response_metadata))
+      end
+
+      # Runs in `ensure`, so it must never raise over the call's outcome.
+      def attach_trailing_metadata
+        return if @trailing_metadata.nil? || @trailing_metadata.empty? || @grpc_sender.nil?
+
+        @grpc_sender.add_trailers(Metadata.encode(@trailing_metadata))
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "#{self.class} trailing metadata")
+      end
     end
   end
 end

data/lib/tonic/rails/configuration.rb

@@ -47,7 +47,8 @@ module Tonic
       # Concurrent HTTP/2 streams per connection.  0 = unlimited.  Default 32.
       attr_accessor :concurrency_limit_per_connection
 
-      # Log every request, not just errors, to stderr.  Default false.
+      # Log one line per RPC (path, status, duration) through `logger`.
+      # Unexpected exceptions are always logged.  Default false.
       attr_accessor :log_requests
 
       # Callables wrapping every RPC, outermost first:
@@ -68,6 +69,17 @@ module Tonic
       # HTTP/2 PING interval and ack timeout, in seconds.  Defaults 15 / 5.
       attr_accessor :keepalive_interval, :keepalive_timeout
 
+      # Callable checked every `health_check_interval` seconds (inside the
+      # Rails executor).  While it returns false or raises, grpc.health.v1
+      # reports NOT_SERVING so readiness probes and load balancers route
+      # around this instance.  Default nil (always SERVING while up).
+      #
+      #   config.health_check = -> { ActiveRecord::Base.connection.active? }
+      attr_accessor :health_check
+
+      # Seconds between health checks.  Default 5.
+      attr_accessor :health_check_interval
+
       # Look handler classes up again on each request so code reloading
       # works.  The Railtie enables this when Rails reloading is on.
       attr_accessor :reload_handlers
@@ -93,6 +105,8 @@ module Tonic
         @keepalive_interval = 15
         @keepalive_timeout = 5
         @reload_handlers = false
+        @health_check = nil
+        @health_check_interval = 5
       end
 
       def tls?
@@ -112,15 +126,24 @@ module Tonic
         raise ArgumentError, "max_message_size must be at most 4 GiB" if max_message_size > 0xFFFF_FFFF
         raise ArgumentError, "tls_cert_path and tls_key_path must be set together" if tls_cert_path.nil? != tls_key_path.nil?
         raise ArgumentError, "tls_client_ca_path requires tls_cert_path and tls_key_path" if tls_client_ca_path && !tls?
-        unless interceptors.respond_to?(:each) && interceptors.all? { |i| i.respond_to?(:call) }
-          raise ArgumentError, "interceptors must be an Array of callables"
-        end
+
+        validate_callables!
 
         self
       end
 
       private
 
+      def validate_callables!
+        raise ArgumentError, "health_check must respond to #call" if health_check && !health_check.respond_to?(:call)
+        unless health_check_interval.is_a?(Numeric) && health_check_interval.positive?
+          raise ArgumentError, "health_check_interval must be a positive number, got #{health_check_interval.inspect}"
+        end
+        return if interceptors.respond_to?(:each) && interceptors.all? { |i| i.respond_to?(:call) }
+
+        raise ArgumentError, "interceptors must be an Array of callables"
+      end
+
       def positive_integer!(name)
         value = public_send(name)
         return if value.is_a?(Integer) && value.positive?

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