tonic-rails 0.1.0 → 0.3.0

data/lib/generators/tonic_rails/service/service_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TonicRails
+  module Generators
+    # rails generate tonic_rails:service Item GetItem ListItems:server ImportItems:client Sync:bidi
+    #
+    # Creates a .proto with the service and its messages, a handler with a
+    # method per RPC, the handler's registration, and a test.
+    class ServiceGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      STREAM_KINDS = %w[unary server client bidi].freeze
+
+      argument :rpcs, type: :array, default: [], banner: "Rpc[:server|:client|:bidi] ..."
+
+      class_option :package, type: :string,
+                             desc: "Protobuf package (default: <app name>.v1)"
+
+      def check_rpcs
+        rpc_specs.each do |rpc|
+          next if rpc[:name].match?(/\A[A-Z][A-Za-z0-9]*\z/) && STREAM_KINDS.include?(rpc[:kind])
+
+          raise Thor::Error, "Invalid RPC #{rpc[:raw].inspect}: use CamelCase names, optionally :server, :client or :bidi"
+        end
+      end
+
+      def create_proto
+        template "service.proto.tt", "app/protos/#{package_path}/#{service_file}_service.proto"
+      end
+
+      def create_handler
+        template "handler.rb.tt", "app/grpc/#{service_file}_service.rb"
+      end
+
+      def register_handler
+        initializer = "config/initializers/tonic_rails.rb"
+        invoke "tonic_rails:install", [], skip_next_steps: true unless File.exist?(File.join(destination_root, initializer))
+        inject_into_file initializer, "  Tonic::Rails.server.register(#{service_class})\n",
+                         after: "Rails.application.config.to_prepare do\n"
+      end
+
+      def create_test
+        if File.directory?(File.join(destination_root, "spec"))
+          template "service_spec.rb.tt", "spec/grpc/#{service_file}_service_spec.rb"
+        else
+          template "service_test.rb.tt", "test/grpc/#{service_file}_service_test.rb"
+        end
+      end
+
+      def show_next_steps
+        say "\nNext: bin/rails tonic_rails:compile_protos, then fill in app/grpc/#{service_file}_service.rb", :green
+      end
+
+      private
+
+      # "Item" and "ItemService" both mean the service ItemService.
+      def service_base
+        class_name.delete_suffix("Service")
+      end
+
+      def service_file
+        service_base.underscore
+      end
+
+      def service_class
+        "#{service_base}Service"
+      end
+
+      def package
+        options[:package] || "#{app_name}.v1"
+      end
+
+      def app_name
+        app = defined?(::Rails.application) && ::Rails.application
+        name = app ? app.class.module_parent_name : File.basename(destination_root)
+        name.to_s.underscore.tr("-", "_").presence || "app"
+      end
+
+      def package_path
+        package.tr(".", "/")
+      end
+
+      def ruby_module
+        package.split(".").map(&:camelize).join("::")
+      end
+
+      def full_service_name
+        "#{package}.#{service_class}"
+      end
+
+      def rpc_specs
+        list = rpcs.empty? ? ["Get#{service_base}"] : rpcs
+        list.map do |raw|
+          name, kind = raw.split(":", 2)
+          { raw: raw, name: name.to_s, kind: kind || "unary", method: name.to_s.underscore }
+        end
+      end
+
+      def proto_rpc_line(rpc)
+        request = "#{rpc[:name]}Request"
+        response = "#{rpc[:name]}Response"
+        request = "stream #{request}" if %w[client bidi].include?(rpc[:kind])
+        response = "stream #{response}" if %w[server bidi].include?(rpc[:kind])
+        "rpc #{rpc[:name]}(#{request}) returns (#{response});"
+      end
+    end
+  end
+end

data/lib/generators/tonic_rails/service/templates/handler.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "<%= package_path %>/<%= service_file %>_service_pb"
+
+class <%= service_class %>
+  include Tonic::Rails::Base
+
+  rpc_service "<%= full_service_name %>"
+  request_format :message
+<% rpc_specs.each do |rpc| %>
+<% case rpc[:kind] -%>
+<% when "unary" -%>
+  # @param request [<%= ruby_module %>::<%= rpc[:name] %>Request]
+  # @return [<%= ruby_module %>::<%= rpc[:name] %>Response]
+  def <%= rpc[:method] %>(request)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% when "server" -%>
+  # @param request [<%= ruby_module %>::<%= rpc[:name] %>Request]
+  # @return [Enumerable<<%= ruby_module %>::<%= rpc[:name] %>Response>] each element is streamed as it's produced
+  def <%= rpc[:method] %>(request)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% when "client" -%>
+  # @param requests [Enumerator<<%= ruby_module %>::<%= rpc[:name] %>Request>] yields messages as they arrive
+  # @return [<%= ruby_module %>::<%= rpc[:name] %>Response]
+  def <%= rpc[:method] %>(requests)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% else -%>
+  # @param requests [Enumerator<<%= ruby_module %>::<%= rpc[:name] %>Request>] yields messages as they arrive
+  # @return [Enumerable<<%= ruby_module %>::<%= rpc[:name] %>Response>]
+  def <%= rpc[:method] %>(requests)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% end -%>
+<% end -%>
+end

data/lib/generators/tonic_rails/service/templates/service.proto.tt

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package <%= package %>;
+
+service <%= service_class %> {
+<% rpc_specs.each do |rpc| -%>
+  <%= proto_rpc_line(rpc) %>
+<% end -%>
+}
+<% rpc_specs.each do |rpc| %>
+message <%= rpc[:name] %>Request {
+}
+
+message <%= rpc[:name] %>Response {
+}
+<% end -%>

data/lib/generators/tonic_rails/service/templates/service_spec.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "tonic/rails/testing/rspec"
+
+RSpec.describe <%= service_class %> do
+<% rpc_specs.each_with_index do |rpc, i| -%>
+<% if i.positive? %>
+<% end -%>
+  describe "<%= rpc[:name] %>" do
+    it "is not implemented yet" do
+      request = <%= %w[client bidi].include?(rpc[:kind]) ? "[#{ruby_module}::#{rpc[:name]}Request.new]" : "#{ruby_module}::#{rpc[:name]}Request.new" %>
+      expect { Tonic::Rails::Testing.call(described_class, :<%= rpc[:name] %>, request) }.to raise_grpc_error(:unimplemented)
+    end
+  end
+<% end -%>
+end

data/lib/generators/tonic_rails/service/templates/service_test.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "tonic/rails/testing/minitest"
+
+class <%= service_class %>Test < ActiveSupport::TestCase
+  include Tonic::Rails::Testing::Assertions
+<% rpc_specs.each do |rpc| %>
+  test "<%= rpc[:name] %> is not implemented yet" do
+    request = <%= %w[client bidi].include?(rpc[:kind]) ? "[#{ruby_module}::#{rpc[:name]}Request.new]" : "#{ruby_module}::#{rpc[:name]}Request.new" %>
+    assert_grpc_error(:unimplemented) { Tonic::Rails::Testing.call(<%= service_class %>, :<%= rpc[:name] %>, request) }
+  end
+<% end -%>
+end

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?