tonic-rails 0.1.0

data/lib/tonic/rails/base.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/string/inflections"
+
+module Tonic
+  module Rails
+    # Include in a class to define a gRPC service handler.
+    #
+    #   class ProductService
+    #     include Tonic::Rails::Base
+    #     rpc_service "shop.ProductService"   # every RPC from the descriptor
+    #
+    #     def get_product(request)
+    #       Shop::Product.new(id: request.id, title: "Widget")
+    #     end
+    #   end
+    #
+    # Handler methods are the snake_case RPC names.  A new instance is
+    # created for every call, so instance variables never leak between
+    # requests.
+    #
+    # Requests are decoded protobuf messages when `request_format :message`
+    # 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.
+    module Base
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.class_attribute :grpc_service_name, instance_writer: false
+        base.class_attribute :grpc_rpcs, instance_writer: false, default: {}
+        base.class_attribute :grpc_request_format, instance_writer: false, default: :hash
+      end
+
+      module ClassMethods
+        # @param name [String] fully-qualified service name, e.g. "shop.ProductService"
+        def service(name)
+          self.grpc_service_name = name.to_s
+        end
+
+        # How requests are passed to handlers.
+        # @param format [Symbol] :hash (string-keyed Hash, the default) or
+        #   :message (the decoded protobuf message — avoids a conversion)
+        def request_format(format)
+          unless %i[hash message].include?(format)
+            raise ArgumentError, "request_format must be :hash or :message, got #{format.inspect}"
+          end
+
+          self.grpc_request_format = format
+        end
+
+        # Declare one RPC.
+        # @param method_name [Symbol, String] RPC name as in the .proto, e.g. :GetProduct
+        # @param request_class [Class] protobuf request message class
+        # @param response_class [Class] protobuf response message class
+        # @param stream [Symbol, nil] :server, :client, :bidi, or nil for unary
+        def rpc(method_name, request_class, response_class, stream: nil)
+          unless [nil, :server, :client, :bidi].include?(stream)
+            raise ArgumentError, "stream must be :server, :client, :bidi, or nil, got #{stream.inspect}"
+          end
+
+          name = method_name.to_s
+          self.grpc_rpcs = grpc_rpcs.merge(
+            name => {
+              request: request_class,
+              response: response_class,
+              request_stream: %i[client bidi].include?(stream),
+              response_stream: %i[server bidi].include?(stream),
+              handler: name.underscore.to_sym,
+            }.freeze,
+          )
+        end
+
+        # Declare the service and every RPC in it from the protobuf
+        # descriptor pool.  Load the generated `_pb.rb` file first.
+        #
+        # @param full_name [String] fully-qualified service name
+        def rpc_service(full_name)
+          descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(full_name.to_s)
+          unless descriptor.is_a?(Google::Protobuf::ServiceDescriptor)
+            raise NotConfiguredError,
+                  "rpc_service: #{full_name} is not a known protobuf service. " \
+                  "Require its generated _pb.rb file (protoc --ruby_out) before declaring the handler."
+          end
+
+          service(full_name)
+          descriptor.each do |method|
+            stream = if method.client_streaming && method.server_streaming
+              :bidi
+            elsif method.client_streaming
+              :client
+            elsif method.server_streaming
+              :server
+            end
+            rpc(method.name, method.input_type.msgclass, method.output_type.msgclass, stream: stream)
+          end
+        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
+          raise NotConfiguredError, "#{self} declares no RPCs" if grpc_rpcs.empty?
+
+          router.add(self)
+        end
+      end
+
+      # 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
+
+      # Milliseconds left before the client's deadline, or nil if the
+      # client did not set one.
+      # @return [Integer, nil]
+      def deadline_ms
+        return unless @grpc_deadline_at
+
+        remaining = ((@grpc_deadline_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)) * 1000).to_i
+        remaining.negative? ? 0 : remaining
+      end
+
+      # True when the deadline has passed.
+      def deadline_exceeded?
+        !deadline_ms.nil? && deadline_ms.zero?
+      end
+
+      # True when the server is shutting down.
+      def cancelled?
+        Tonic::Rails.cancelled?
+      end
+
+      # @api private
+      # Run one RPC.  `reader` yields raw request messages (`#next`, then
+      # `#error` once exhausted); `sender` accepts raw response messages
+      # (`#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)
+        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])
+
+        @grpc_metadata = metadata
+        @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
+        else
+          read_request(reader, spec) || raise(RpcError.new("missing request message", code: :invalid_argument))
+        end
+
+        result = public_send(spec[:handler], request)
+
+        if spec[:response_stream]
+          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
+        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
+
+      def read_request(reader, spec)
+        bytes = reader.next
+        if bytes.nil?
+          code, message = reader.error
+          raise RpcError.new(message, code: code) if code
+
+          return
+        end
+
+        message = begin
+          spec[:request].decode(bytes)
+        rescue Google::Protobuf::ParseError, ArgumentError
+          raise RpcError.new("invalid protobuf request", code: :invalid_argument)
+        end
+        self.class.grpc_request_format == :message ? message : message.to_h.deep_stringify_keys
+      end
+
+      def encode_response(item, spec)
+        klass = spec[:response]
+        message = case item
+        when klass then item
+        when Hash then klass.new(item)
+        else
+          raise TypeError, "#{self.class}##{spec[:handler]} must return a #{klass} or Hash, got #{item.class}"
+        end
+        klass.encode(message)
+      end
+
+      def push_response(sender, bytes)
+        sender.push(bytes)
+      rescue IOError
+        # The client went away; nothing left to deliver to.
+        raise RpcError.new("client cancelled the stream", code: :cancelled)
+      end
+    end
+  end
+end

data/lib/tonic/rails/configuration.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Tonic
+  module Rails
+    class Configuration
+      # Address the gRPC server binds to ("host:port").  Default "0.0.0.0:50051".
+      attr_accessor :bind_address
+
+      # Maximum request and response message size in bytes (also caps
+      # decompressed payloads).  Default 4 MiB.
+      attr_accessor :max_message_size
+
+      # Start the gRPC server in a background thread when `rails server`
+      # boots.  Prefer a dedicated process (`bin/rails tonic_rails:serve`)
+      # in production.  Default false.
+      attr_accessor :auto_start
+
+      attr_accessor :logger
+
+      # Tokio worker threads for the transport.  nil = number of CPUs.
+      attr_accessor :worker_threads
+
+      # Ruby threads running handlers.  Match your ActiveRecord pool size
+      # (RAILS_MAX_THREADS).  Default 4.
+      attr_accessor :dispatch_threads
+
+      # RPCs that may wait for a free dispatch thread.  Beyond this the
+      # server answers RESOURCE_EXHAUSTED immediately.  Default 128.
+      attr_accessor :dispatch_queue_size
+
+      # PEM certificate and private key.  Set both to enable TLS.
+      attr_accessor :tls_cert_path, :tls_key_path
+
+      # PEM CA bundle.  When set, clients must present a certificate
+      # signed by it (mutual TLS).
+      attr_accessor :tls_client_ca_path
+
+      # Seconds to wait for in-flight RPCs during shutdown.  Default 10.
+      attr_accessor :drain_timeout
+
+      # Concurrent TCP connections; extra connections are refused.
+      # 0 = unlimited.  Default 64.
+      attr_accessor :max_connections
+
+      # 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.
+      attr_accessor :log_requests
+
+      # Callables wrapping every RPC, outermost first:
+      #
+      #   ->(path, metadata, next_call) { next_call.call }
+      #
+      # Raise RpcError to reject the call.
+      attr_accessor :interceptors
+
+      # gzip responses larger than 1 KiB for clients that accept it.
+      # Compressed requests are always accepted.  Default false.
+      attr_accessor :compression
+
+      # Serve grpc.reflection.v1 (for grpcurl and friends).  Exposes your
+      # API schema; keep it off in production.  Default false.
+      attr_accessor :reflection
+
+      # HTTP/2 PING interval and ack timeout, in seconds.  Defaults 15 / 5.
+      attr_accessor :keepalive_interval, :keepalive_timeout
+
+      # 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
+
+      def initialize
+        @bind_address = "0.0.0.0:50051"
+        @max_message_size = 4 * 1024 * 1024
+        @auto_start = false
+        @logger = Logger.new($stdout)
+        @worker_threads = nil
+        @dispatch_threads = 4
+        @dispatch_queue_size = 128
+        @tls_cert_path = nil
+        @tls_key_path = nil
+        @tls_client_ca_path = nil
+        @drain_timeout = 10
+        @max_connections = 64
+        @concurrency_limit_per_connection = 32
+        @log_requests = false
+        @interceptors = []
+        @compression = false
+        @reflection = false
+        @keepalive_interval = 15
+        @keepalive_timeout = 5
+        @reload_handlers = false
+      end
+
+      def tls?
+        !tls_cert_path.nil? && !tls_key_path.nil?
+      end
+
+      # @raise [ArgumentError] describing the first invalid setting
+      def validate!
+        positive_integer!(:dispatch_threads)
+        positive_integer!(:dispatch_queue_size)
+        positive_integer!(:max_message_size)
+        non_negative_integer!(:max_connections)
+        non_negative_integer!(:concurrency_limit_per_connection)
+        positive_integer!(:worker_threads) unless worker_threads.nil?
+        %i[drain_timeout keepalive_interval keepalive_timeout].each { |name| non_negative_number!(name) }
+
+        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
+
+        self
+      end
+
+      private
+
+      def positive_integer!(name)
+        value = public_send(name)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError,
+              "#{name} must be a positive Integer, got #{value.inspect}"
+      end
+
+      def non_negative_integer!(name)
+        value = public_send(name)
+        return if value.is_a?(Integer) && !value.negative?
+
+        raise ArgumentError,
+              "#{name} must be a non-negative Integer, got #{value.inspect}"
+      end
+
+      def non_negative_number!(name)
+        value = public_send(name)
+        return if value.is_a?(Numeric) && !value.negative?
+
+        raise ArgumentError,
+              "#{name} must be a non-negative number, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/tonic/rails/railtie.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # Rails integration:
+    # - `config.tonic_rails.*` settings are copied onto Tonic::Rails.configuration
+    #   (an initializer calling Tonic::Rails.configure can still override them)
+    # - the Rails logger is used by default
+    # - handler classes are looked up per request when code reloading is on
+    # - `auto_start` runs the server inside `rails server`
+    # - rake tasks: tonic_rails:serve, tonic_rails:routes, tonic_rails:compile_protos
+    class Railtie < ::Rails::Railtie
+      config.tonic_rails = ::ActiveSupport::OrderedOptions.new
+
+      initializer "tonic_rails.configuration" do |app|
+        configuration = Tonic::Rails.configuration
+        configuration.logger = ::Rails.logger if ::Rails.logger
+        configuration.reload_handlers = Railtie.reloading_enabled?(app)
+
+        app.config.tonic_rails.each do |key, value|
+          setter = "#{key}="
+          raise ArgumentError, "unknown tonic-rails setting config.tonic_rails.#{key}" unless configuration.respond_to?(setter)
+
+          configuration.public_send(setter, value)
+        end
+      end
+
+      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`.
+        if configuration.auto_start && defined?(::Rails::Server)
+          server = Tonic::Rails.server
+          thread = Thread.new do
+            Thread.current.name = "tonic-rails"
+            server.start(install_signal_handlers: false)
+          end
+          thread.report_on_exception = true
+          at_exit do
+            server.stop
+            thread.join(configuration.drain_timeout.to_f + 5)
+          end
+        end
+      end
+
+      def self.reloading_enabled?(app)
+        app.config.respond_to?(:enable_reloading) ? app.config.enable_reloading : !app.config.cache_classes
+      end
+
+      rake_tasks do
+        load File.expand_path("tasks/tonic-rails.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/tonic/rails/reflection.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "google/protobuf/descriptor_pb"
+
+module Tonic
+  module Rails
+    # Builds the protobuf file descriptors served by gRPC reflection from
+    # the descriptors already loaded in Ruby (the generated `_pb.rb` files).
+    module Reflection
+      module_function
+
+      # @param service_names [Array<String>] fully-qualified service names
+      # @return [Array<String>] serialized google.protobuf.FileDescriptorProto,
+      #   covering each service's file and every file its messages reference
+      def file_descriptors(service_names)
+        pool = Google::Protobuf::DescriptorPool.generated_pool
+        files = {}
+        seen = Set.new
+        pending = []
+
+        service_names.each do |name|
+          service = pool.lookup(name)
+          next unless service.is_a?(Google::Protobuf::ServiceDescriptor)
+
+          add_file(files, service.file_descriptor)
+          service.each { |method| pending << method.input_type << method.output_type }
+        end
+
+        until pending.empty?
+          descriptor = pending.pop
+          next unless seen.add?(descriptor.name)
+
+          add_file(files, descriptor.file_descriptor)
+          next unless descriptor.is_a?(Google::Protobuf::Descriptor)
+
+          descriptor.each do |field|
+            subtype = field.subtype
+            pending << subtype if subtype
+          end
+        end
+
+        files.values.map { |fd| Google::Protobuf::FileDescriptorProto.encode(fd.to_proto) }
+      end
+
+      def add_file(files, file_descriptor)
+        files[file_descriptor.name] ||= file_descriptor
+      end
+    end
+  end
+end

data/lib/tonic/rails/router.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # Maps gRPC method paths ("/package.Service/Method") to handler classes.
+    class Router
+      Route = Struct.new(:service_class, :rpc_name)
+
+      def initialize
+        @routes = {}
+        @services = {}
+      end
+
+      # Register (or re-register, e.g. after a code reload) every RPC of
+      # a handler class.
+      # @param service_class [Class] a class including Tonic::Rails::Base
+      def add(service_class)
+        name = service_class.grpc_service_name
+        @routes.delete_if { |_, route| route.service_class.grpc_service_name == name }
+        @services[name] = service_class
+        service_class.grpc_rpcs.each_key do |rpc_name|
+          @routes["/#{name}/#{rpc_name}"] = Route.new(service_class, rpc_name)
+        end
+        self
+      end
+
+      # @param path [String] gRPC method path
+      # @param metadata [Hash{String=>String}]
+      # @param call [Hash] :reader, :sender and optional :timeout_ms from the transport
+      # @return [String, nil] encoded unary response, or nil for streamed responses
+      def dispatch(path, metadata, call)
+        route = @routes[path]
+        raise RpcError.new("unknown method #{path}", code: :unimplemented) unless route
+
+        resolve(route.service_class).new.call_rpc(
+          route.rpc_name,
+          metadata: metadata,
+          reader: call[:reader],
+          sender: call[:sender],
+          timeout_ms: call[:timeout_ms],
+        )
+      end
+
+      # @return [Array<String>] registered gRPC method paths
+      def paths
+        @routes.keys
+      end
+
+      # @return [Array<String>] registered fully-qualified service names
+      def service_names
+        @services.keys
+      end
+
+      def empty?
+        @routes.empty?
+      end
+
+      private
+
+      # With code reloading on, look the class up again so edits to
+      # handler bodies take effect without a restart.
+      def resolve(service_class)
+        return service_class unless Tonic::Rails.configuration.reload_handlers
+
+        Object.const_get(service_class.name)
+      rescue NameError
+        service_class
+      end
+    end
+  end
+end

data/lib/tonic/rails/rpc_error.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # Raise from a handler to end the RPC with a gRPC status.
+    #
+    #   raise Tonic::Rails::RpcError.new("product 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.
+    class RpcError < Error
+      CODES = {
+        ok: 0,
+        cancelled: 1,
+        unknown: 2,
+        invalid_argument: 3,
+        deadline_exceeded: 4,
+        not_found: 5,
+        already_exists: 6,
+        permission_denied: 7,
+        resource_exhausted: 8,
+        failed_precondition: 9,
+        aborted: 10,
+        out_of_range: 11,
+        unimplemented: 12,
+        internal: 13,
+        unavailable: 14,
+        data_loss: 15,
+        unauthenticated: 16,
+      }.freeze
+
+      CODE_NAMES = CODES.invert.freeze
+
+      # @return [Integer] numeric gRPC status code
+      attr_reader :code
+
+      # @param message [String] status message sent to the client
+      # @param code [Symbol, Integer] gRPC status code (see CODES)
+      def initialize(message = nil, code: :unknown)
+        @code = self.class.normalize_code(code)
+        super(message || code_name.to_s)
+      end
+
+      # @return [Symbol] e.g. :not_found
+      def code_name
+        CODE_NAMES.fetch(@code)
+      end
+
+      # @api private
+      def self.normalize_code(code)
+        case code
+        when Symbol, String
+          CODES.fetch(code.to_sym) { raise ArgumentError, "unknown gRPC status code: #{code.inspect}" }
+        when Integer
+          raise ArgumentError, "unknown gRPC status code: #{code}" unless CODE_NAMES.key?(code)
+
+          code
+        else
+          raise ArgumentError, "gRPC status code must be a Symbol or Integer, got #{code.class}"
+        end
+      end
+    end
+  end
+end