tonic-rails 0.1.0

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

data/lib/tonic/rails/testing.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # Call handlers in-process, without a network or the native extension.
+    # Requests and responses go through real protobuf encoding, so tests
+    # exercise the same conversion the server does.
+    #
+    #   require "tonic/rails/testing"
+    #
+    #   response = Tonic::Rails::Testing.call(ProductService, :GetProduct, { id: 1 })
+    #   response.title  # => "Widget"
+    #
+    #   expect { Tonic::Rails::Testing.call(ProductService, :GetProduct, { id: 0 }) }
+    #     .to raise_error(Tonic::Rails::RpcError) { |e| expect(e.code_name).to eq(:not_found) }
+    module Testing
+      # Request side of a call: yields pre-encoded messages.
+      class Reader
+        def initialize(messages, error: nil)
+          @messages = messages.dup
+          @error = error
+        end
+
+        def next
+          @messages.shift
+        end
+
+        attr_reader :error
+      end
+
+      # Response side of a call: collects encoded messages.
+      class Sender
+        attr_reader :messages
+
+        def initialize
+          @messages = []
+        end
+
+        def push(bytes)
+          @messages << bytes
+        end
+      end
+
+      module_function
+
+      # @param service_class [Class] handler class
+      # @param rpc_name [Symbol, String] RPC name as in the .proto
+      # @param request [Google::Protobuf::AbstractMessage, Hash, Array] the
+      #   request; an Array of them for client- and bidi-streaming RPCs
+      # @param metadata [Hash{String=>String}]
+      # @param timeout_ms [Integer, nil] simulated client deadline
+      # @return [Google::Protobuf::AbstractMessage, Array] the response, or
+      #   an Array of responses for server- and bidi-streaming RPCs
+      # @raise [RpcError] when the handler ends the call with a status
+      def call(service_class, rpc_name, request, metadata: {}, timeout_ms: nil)
+        spec = service_class.grpc_rpcs.fetch(rpc_name.to_s) do
+          raise ArgumentError, "#{service_class} has no RPC #{rpc_name}"
+        end
+
+        requests = spec[:request_stream] ? Array(request) : [request]
+        reader = Reader.new(requests.map { |r| encode(spec[:request], r) })
+        sender = Sender.new
+
+        result = service_class.new.call_rpc(
+          rpc_name.to_s,
+          metadata: metadata.transform_keys(&:to_s),
+          reader: reader,
+          sender: sender,
+          timeout_ms: timeout_ms,
+        )
+
+        if spec[:response_stream]
+          sender.messages.map { |bytes| spec[:response].decode(bytes) }
+        else
+          spec[:response].decode(result)
+        end
+      end
+
+      def encode(klass, message)
+        message = klass.new(message) if message.is_a?(Hash)
+        klass.encode(message)
+      end
+    end
+  end
+end

data/lib/tonic/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/tonic-rails.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "google/protobuf"
+
+module Tonic
+  module Rails
+    class Error < StandardError; end
+    class NotConfiguredError < Error; end
+  end
+end
+
+require "tonic/rails/version"
+require "tonic/rails/rpc_error"
+require "tonic/rails/configuration"
+require "tonic/rails/router"
+require "tonic/rails/base"
+require "tonic/rails/reflection"
+require "tonic/rails/server"
+
+module Tonic
+  module Rails
+    @configuration = Configuration.new
+    @shutting_down = false
+    @native_load_error = nil
+
+    class << self
+      attr_reader :configuration
+
+      def configure
+        yield @configuration
+      end
+
+      # The process-wide server used by the Railtie and rake tasks.
+      def server
+        @server ||= Server.new
+      end
+
+      # True once shutdown has begun.  Long-running handlers (especially
+      # streams) should check this and finish early.
+      def cancelled?
+        @shutting_down
+      end
+
+      # @api private
+      def _set_shutting_down(value)
+        @shutting_down = value
+      end
+
+      # @api private
+      # Log an unexpected exception (and hand it to the Rails error
+      # reporter, if present) without exposing it to the client.
+      def log_exception(error, context)
+        configuration.logger&.error(
+          "tonic-rails: #{context}: #{error.class}: #{error.message}\n" \
+          "#{Array(error.backtrace).first(20).join("\n")}",
+        )
+        if defined?(::Rails.error) && ::Rails.respond_to?(:error)
+          ::Rails.error.report(error, handled: true, source: "tonic-rails", context: { rpc: context })
+        end
+      rescue StandardError
+        nil
+      end
+
+      # @api private
+      def native_extension!
+        return if defined?(::TonicRails::Native::Server)
+
+        raise Error, "tonic-rails native extension is not available " \
+                     "(#{@native_load_error&.message || 'unknown error'}). " \
+                     "Reinstall the gem, or run `bundle exec rake compile` in a checkout."
+      end
+
+      # @api private
+      def load_native_extension
+        # Precompiled platform gems ship one binary per Ruby minor version.
+        ruby_version = RUBY_VERSION[/\d+\.\d+/]
+        require "tonic/rails/#{ruby_version}/tonic_rails_native"
+      rescue LoadError
+        begin
+          require "tonic/rails/tonic_rails_native"
+        rescue LoadError => e
+          @native_load_error = e
+        end
+      end
+    end
+
+    load_native_extension
+  end
+end
+
+require "tonic/rails/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: tonic-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Tanous
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.27'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.27'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.110
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.110
+description: |
+  Tonic::Rails serves gRPC from Rails applications. The transport layer
+  (HTTP/2 framing, connection management, TLS, health checks, reflection)
+  is handled by tonic in Rust and exposed to Ruby through a native
+  extension built with Magnus. Protobuf (de)serialization and business
+  logic remain in Ruby, giving you Rails-grade handlers, routing,
+  interceptors, and the Rails executor around every RPC.
+email:
+- matt.tanous@hey.com
+executables: []
+extensions:
+- ext/tonic_rails_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE
+- README.md
+- ext/tonic_rails_native/Cargo.toml
+- ext/tonic_rails_native/extconf.rb
+- ext/tonic_rails_native/src/body.rs
+- ext/tonic_rails_native/src/dispatch.rs
+- ext/tonic_rails_native/src/framing.rs
+- ext/tonic_rails_native/src/gvl.rs
+- ext/tonic_rails_native/src/lib.rs
+- ext/tonic_rails_native/src/net.rs
+- ext/tonic_rails_native/src/server.rs
+- lib/tonic-rails.rb
+- lib/tonic/rails/base.rb
+- lib/tonic/rails/configuration.rb
+- lib/tonic/rails/railtie.rb
+- lib/tonic/rails/reflection.rb
+- lib/tonic/rails/router.rb
+- lib/tonic/rails/rpc_error.rb
+- lib/tonic/rails/server.rb
+- lib/tonic/rails/tasks/tonic-rails.rake
+- lib/tonic/rails/testing.rb
+- lib/tonic/rails/version.rb
+homepage: https://github.com/CodingAnarchy/tonic-rails
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/CodingAnarchy/tonic-rails
+  source_code_uri: https://github.com/CodingAnarchy/tonic-rails
+  bug_tracker_uri: https://github.com/CodingAnarchy/tonic-rails/issues
+  changelog_uri: https://github.com/CodingAnarchy/tonic-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: High-performance gRPC endpoints for Rails, powered by tonic via a Rust native
+  extension
+test_files: []