tonic-rails 0.1.0-aarch64-linux-gnu

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

data/lib/tonic/rails/server.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # Runs the gRPC server: a tonic transport in Rust plus a pool of Ruby
+    # dispatch threads.
+    #
+    #   server = Tonic::Rails::Server.new
+    #   server.register(ProductService)
+    #   server.start   # blocks until SIGTERM / SIGINT or #stop
+    #
+    # Shutdown is graceful: health checks flip to NOT_SERVING, new
+    # connections are refused, in-flight RPCs get `drain_timeout` seconds
+    # to finish, then everything is torn down.
+    class Server
+      attr_reader :router, :configuration
+
+      def initialize(configuration: Tonic::Rails.configuration)
+        @configuration = configuration
+        @router = Router.new
+        @native = nil
+        @state = :stopped
+        @stop_reader = nil
+        @stop_writer = nil
+        @stop_requested = false
+        @lock = Mutex.new
+      end
+
+      # @param service_class [Class, String] handler class (or its name)
+      def register(service_class)
+        service_class = Object.const_get(service_class) if service_class.is_a?(String)
+        service_class.register_on(@router)
+        self
+      end
+
+      # Start serving and block until stopped.
+      # @param install_signal_handlers [Boolean] trap TERM and INT to stop.
+      #   Pass false when embedding in a process that owns its signals.
+      # @yield once the server is accepting connections
+      def start(install_signal_handlers: true)
+        @lock.synchronize do
+          raise Error, "server is already running" unless @state == :stopped
+
+          @state = :starting
+          @stop_requested = false
+        end
+
+        begin
+          raise Error, "no services registered" if @router.empty?
+
+          @configuration.validate!
+          Tonic::Rails.native_extension!
+          Tonic::Rails._set_shutting_down(false)
+          @stop_reader, @stop_writer = IO.pipe
+          stop if @stop_requested # requested while we were starting up
+          @native = build_native_server
+          @native.start_server
+          @state = :running
+
+          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)
+          shutdown(workers)
+        ensure
+          previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
+          @native&.stop_server
+          @native = nil
+          [@stop_reader, @stop_writer].each { |io| io.close if io && !io.closed? }
+          @stop_reader = @stop_writer = nil
+          Tonic::Rails._set_shutting_down(false)
+          @state = :stopped
+        end
+      end
+
+      # Request a graceful stop.  Safe to call from signal handlers and
+      # other threads; returns immediately.
+      def stop
+        @stop_requested = true
+        @stop_writer&.write_nonblock(".", exception: false)
+      rescue IOError
+        # Already stopped.
+      end
+
+      def running?
+        @state == :running
+      end
+
+      # @return [Hash{Symbol=>Integer}] request and connection counters
+      def stats
+        native = @native
+        return native.stats if native
+
+        { total: 0, successful: 0, errors: 0, cancelled: 0, deadline_exceeded: 0,
+          resource_exhausted: 0, unimplemented: 0, active_connections: 0, queued: 0 }
+      end
+
+      private
+
+      def build_native_server
+        config = @configuration
+        native = TonicRails::Native::Server.new(config.bind_address, config.max_message_size)
+        native.on_request(build_callback)
+        native.set_routes(@router.paths)
+        if config.tls?
+          native.set_tls(config.tls_cert_path, config.tls_key_path)
+          native.set_tls_client_ca(config.tls_client_ca_path) if config.tls_client_ca_path
+        end
+        native.set_max_connections(config.max_connections)
+        native.set_concurrency_limit_per_connection(config.concurrency_limit_per_connection)
+        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
+        native
+      end
+
+      # The proc the transport calls for every RPC:
+      #   (path, metadata, call) → encoded response String, or nil if streamed
+      def build_callback
+        router = @router
+        call = ->(path, metadata, transport) { router.dispatch(path, metadata, transport) }
+
+        call = @configuration.interceptors.reverse.reduce(call) do |inner, interceptor|
+          lambda do |path, metadata, transport|
+            interceptor.call(path, metadata, -> { inner.call(path, metadata, transport) })
+          end
+        end
+
+        guarded = lambda do |path, metadata, transport|
+          call.call(path, metadata, transport)
+        rescue RpcError
+          raise
+        rescue StandardError => e
+          Tonic::Rails.log_exception(e, path)
+          raise RpcError.new("internal error", code: :internal)
+        end
+
+        wrap_with_rails_executor(guarded)
+      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
+      # requests and Active Job get.
+      def wrap_with_rails_executor(callback)
+        return callback unless defined?(::Rails.application) && ::Rails.application
+
+        app = ::Rails.application
+        wrapper = @configuration.reload_handlers ? app.reloader : app.executor
+        ->(path, metadata, transport) { wrapper.wrap { callback.call(path, metadata, transport) } }
+      end
+
+      def spawn_worker(index)
+        native = @native
+        Thread.new do
+          Thread.current.name = "tonic-rails-dispatch-#{index}"
+          native.serve_worker
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          Tonic::Rails.log_exception(e, "dispatch thread #{index}")
+          stop
+          raise
+        end
+      end
+
+      def trap_signals
+        %w[TERM INT].to_h { |signal| [signal, Signal.trap(signal) { stop }] }
+      end
+
+      def wait_for_stop(workers)
+        loop do
+          break if @stop_reader.wait_readable(1)
+
+          dead = workers.reject(&:alive?)
+          unless dead.empty?
+            @configuration.logger&.error("tonic-rails: #{dead.size} dispatch thread(s) died; shutting down")
+            break
+          end
+        end
+      end
+
+      def shutdown(workers)
+        logger = @configuration.logger
+        @state = :stopping
+        Tonic::Rails._set_shutting_down(true)
+        logger&.info("tonic-rails: shutting down, draining for up to #{@configuration.drain_timeout}s")
+
+        @native.begin_shutdown
+        unless @native.wait_for_drain(@configuration.drain_timeout.to_f)
+          logger&.warn("tonic-rails: drain timeout expired; closing remaining connections")
+        end
+        @native.stop_workers
+        workers.each do |worker|
+          worker.join
+        rescue Exception # rubocop:disable Lint/RescueException
+          # Already logged by the worker.
+        end
+        logger&.info("tonic-rails: stopped")
+      end
+
+      def log_startup
+        config = @configuration
+        logger = config.logger
+        return unless logger
+
+        if config.tls?
+          logger.info("tonic-rails: TLS enabled#{' (mutual TLS)' if config.tls_client_ca_path}")
+        else
+          logger.warn("tonic-rails: TLS is not configured; gRPC traffic is plaintext")
+        end
+        logger.info("tonic-rails: reflection enabled") if config.reflection
+        logger.info(
+          "tonic-rails: serving #{@router.service_names.join(', ')} on #{config.bind_address} " \
+          "(#{config.dispatch_threads} dispatch threads)",
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+namespace :tonic_rails do
+  desc "Start the gRPC server (boots the Rails app with its registered services)"
+  task serve: :environment do
+    # Eager-load so handlers registered via config.to_prepare and
+    # autoloaded constants are in place, as they would be in production.
+    Rails.application.eager_load! unless Rails.application.config.eager_load
+    Tonic::Rails.server.start
+  end
+
+  desc "List registered gRPC methods"
+  task routes: :environment do
+    router = Tonic::Rails.server.router
+    if router.empty?
+      puts "No gRPC services registered."
+    else
+      router.paths.sort.each { |path| puts path }
+    end
+  end
+
+  desc "Generate Ruby protobuf classes (PROTO_DIR=app/protos RUBY_OUT=lib/grpc; requires protoc)"
+  task :compile_protos do
+    proto_dir = ENV.fetch("PROTO_DIR", "app/protos")
+    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)
+
+    FileUtils.mkdir_p(ruby_out)
+    sh "protoc", "--ruby_out=#{ruby_out}", "-I#{proto_dir}", *protos
+    puts "Compiled #{protos.size} proto file(s) to #{ruby_out}/"
+  end
+end