tonic-rails 0.2.0 → 0.4.0

data/lib/tonic/rails/server.rb

@@ -22,6 +22,7 @@ module Tonic
         @state = :stopped
         @stop_signal = nil
         @stop_requested = false
+        @health = Health.new(configuration, @router)
         @lock = Mutex.new
       end
 
@@ -58,6 +59,7 @@ module Tonic
           @native = build_native_server
           @native.start_server
           log_pump = spawn_log_pump
+          @health.attach(@native)
           @state = :running
 
           request_log = subscribe_request_logger
@@ -67,10 +69,12 @@ module Tonic
           yield self if block_given?
 
           wait_for_stop(workers)
+          @health.detach
           shutdown(workers)
         ensure
           ActiveSupport::Notifications.unsubscribe(request_log) if request_log
           previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
+          @health.detach
           @native&.stop_server
           stop_log_pump(log_pump)
           @native = nil
@@ -91,6 +95,25 @@ module Tonic
         @state == :running
       end
 
+      # Mark the whole server, or the given services (fully-qualified
+      # names), SERVING in grpc.health.v1.  Takes effect immediately when
+      # running, otherwise when the server starts.
+      #
+      # With `config.health_check`, a service reports SERVING only while the
+      # check passes *and* it's marked serving here.
+      def serving!(*services)
+        @health.mark(services, true)
+        self
+      end
+
+      # Mark the whole server, or the given services, NOT_SERVING (e.g. for
+      # maintenance), so load balancers and readiness probes route around
+      # this instance.  Calls are still served.
+      def not_serving!(*services)
+        @health.mark(services, false)
+        self
+      end
+
       # @return [Hash{Symbol=>Integer}] request and connection counters
       def stats
         native = @native
@@ -107,19 +130,30 @@ module Tonic
         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
+        apply_connection_settings(native, config)
+        apply_features(native, config)
+        native
+      end
+
+      def apply_connection_settings(native, config)
         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)
+      end
+
+      def apply_features(native, config)
+        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_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
+        return unless config.grpc_web
+
+        native.set_grpc_web(config.grpc_web_origins, config.grpc_web_allowed_headers, config.grpc_web_exposed_headers)
       end
 
       # The proc the transport calls for every RPC:
@@ -250,6 +284,16 @@ module Tonic
         logger&.info("tonic-rails: stopped")
       end
 
+      def log_grpc_web(logger, config)
+        return unless config.grpc_web
+
+        origins = config.grpc_web_origins
+        logger.info("tonic-rails: gRPC-Web enabled (#{origins.empty? ? 'same-origin only' : "origins: #{origins.join(', ')}"})")
+        return unless origins.include?("*")
+
+        logger.warn("tonic-rails: gRPC-Web allows any origin; any website can call these services from a visitor's browser")
+      end
+
       def log_startup
         config = @configuration
         logger = config.logger
@@ -261,6 +305,7 @@ module Tonic
           logger.warn("tonic-rails: TLS is not configured; gRPC traffic is plaintext")
         end
         logger.info("tonic-rails: reflection enabled") if config.reflection
+        log_grpc_web(logger, config)
         logger.info(
           "tonic-rails: serving #{@router.service_names.join(', ')} on #{config.bind_address} " \
           "(#{config.dispatch_threads} dispatch threads)",

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

@@ -27,7 +27,19 @@ namespace :tonic_rails do
     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)
+    version = begin
+      IO.popen(%w[protoc --version], err: File::NULL, &:read)[/\d+(\.\d+)+/]
+    rescue SystemCallError
+      nil
+    end
+    abort "protoc not found on PATH. Install the Protocol Buffers compiler (22.0 or newer)." unless version
+    # protoc before 22 emits the Ruby DSL that google-protobuf 4 removed
+    # (`undefined method 'build' for DescriptorPool` at load time).
+    major = version.split(".").then { |parts| parts.first == "3" ? parts[1].to_i : parts.first.to_i }
+    if major < 22
+      abort "protoc #{version} is too old for google-protobuf 4: install protoc 22.0 or newer " \
+            "(distribution packages are often older; see https://github.com/protocolbuffers/protobuf/releases)."
+    end
 
     FileUtils.mkdir_p(ruby_out)
     sh "protoc", "--ruby_out=#{ruby_out}", "-I#{proto_dir}", *protos

data/lib/tonic/rails/testing/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    module Testing
+      # Shared helpers for the RSpec matcher and Minitest assertions.
+      # @api private
+      module Errors
+        module_function
+
+        # Exceptions that carry a gRPC status: tonic-rails' own, and the
+        # official grpc gem client's, when it's loaded.
+        def classes
+          [Tonic::Rails::RpcError, (GRPC::BadStatus if defined?(GRPC::BadStatus))].compact
+        end
+
+        def status?(error)
+          classes.any? { |klass| error.is_a?(klass) }
+        end
+
+        # @return [Integer]
+        def code(error)
+          error.code
+        end
+
+        # @return [String] the status message the client sees.  The grpc
+        # gem keeps it in #details (its #message adds the code).
+        def message(error)
+          text = defined?(GRPC::BadStatus) && error.is_a?(GRPC::BadStatus) ? error.details.to_s : error.message
+          text.dup.force_encoding(Encoding::UTF_8)
+        end
+
+        def code_name(code)
+          Tonic::Rails::RpcError::CODE_NAMES.fetch(code, code)
+        end
+
+        def message_matches?(expected, actual)
+          expected.is_a?(Regexp) ? expected.match?(actual) : expected.to_s == actual
+        end
+
+        def describe(error)
+          "#{code_name(code(error)).to_s.upcase} (#{message(error).inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/testing/minitest.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "tonic/rails/testing"
+require "tonic/rails/testing/errors"
+
+module Tonic
+  module Rails
+    module Testing
+      # Minitest assertions for gRPC statuses:
+      #
+      #   class ItemServiceTest < ActiveSupport::TestCase
+      #     include Tonic::Rails::Testing::Assertions
+      #
+      #     test "missing items" do
+      #       error = assert_grpc_error(:not_found) { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+      #       assert_match(/0/, error.message)
+      #     end
+      #   end
+      module Assertions
+        # Asserts the block raises a gRPC status (Tonic::Rails::RpcError or
+        # GRPC::BadStatus) with the given code and, optionally, message
+        # (String or Regexp).  Returns the error.
+        def assert_grpc_error(code = nil, message = nil, &)
+          errors = Testing::Errors
+          error = assert_raises(*errors.classes, &)
+          if code
+            expected = Tonic::Rails::RpcError.normalize_code(code)
+            assert_equal(
+              errors.code_name(expected), errors.code_name(errors.code(error)),
+              "Expected gRPC status #{errors.code_name(expected).to_s.upcase}, got #{errors.describe(error)}"
+            )
+          end
+          if message
+            assert(
+              errors.message_matches?(message, errors.message(error)),
+              "Expected gRPC message #{message.inspect}, got #{errors.message(error).inspect}",
+            )
+          end
+          error
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/testing/rspec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+require "tonic/rails/testing"
+require "tonic/rails/testing/errors"
+
+# Matches a block that ends with a gRPC status, raised as a
+# Tonic::Rails::RpcError (Testing.call) or a GRPC::BadStatus (the official
+# client):
+#
+#   expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+#     .to raise_grpc_error(:not_found)
+#   expect { stub.get_item(request) }.to raise_grpc_error(:invalid_argument).with_message(/name/)
+#   expect { ... }.to raise_grpc_error   # any non-OK status
+RSpec::Matchers.define :raise_grpc_error do |expected_code = nil|
+  errors = Tonic::Rails::Testing::Errors
+
+  supports_block_expectations
+
+  chain(:with_message) { |message| @expected_message = message }
+
+  match do |block|
+    @expected = expected_code && Tonic::Rails::RpcError.normalize_code(expected_code)
+    begin
+      block.call
+      @error = nil
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      raise unless errors.status?(e)
+
+      @error = e
+    end
+    return false unless @error
+
+    (@expected.nil? || errors.code(@error) == @expected) &&
+      (!defined?(@expected_message) || errors.message_matches?(@expected_message, errors.message(@error)))
+  end
+
+  description do
+    text = +"raise a gRPC error"
+    text << " #{errors.code_name(@expected).to_s.upcase}" if @expected
+    text << " with message #{@expected_message.inspect}" if defined?(@expected_message)
+    text
+  end
+
+  failure_message do
+    actual = @error ? "got #{errors.describe(@error)}" : "nothing was raised"
+    "expected block to #{description}, but #{actual}"
+  end
+
+  failure_message_when_negated do
+    "expected block not to #{description}, but got #{errors.describe(@error)}"
+  end
+end

data/lib/tonic/rails/testing.rb

@@ -65,11 +65,12 @@ module Tonic
       #   request; an Array of them for client- and bidi-streaming RPCs
       # @param metadata [Hash{String=>String}]
       # @param timeout_ms [Integer, nil] simulated client deadline
+      # @param peer [Tonic::Rails::Peer, nil] simulated client (address, certificates)
       # @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)
-        invoke(service_class, rpc_name, request, metadata: metadata, timeout_ms: timeout_ms).response
+      def call(service_class, rpc_name, request, metadata: {}, timeout_ms: nil, peer: nil)
+        invoke(service_class, rpc_name, request, metadata: metadata, timeout_ms: timeout_ms, peer: peer).response
       end
 
       # Like #call, but returns a Result with the response metadata too:
@@ -80,7 +81,7 @@ module Tonic
       #   result.trailers["x-cost-ms"]   # => "3"
       #
       # @return [Result]
-      def invoke(service_class, rpc_name, request, metadata: {}, timeout_ms: nil)
+      def invoke(service_class, rpc_name, request, metadata: {}, timeout_ms: nil, peer: nil)
         spec = service_class.grpc_rpcs.fetch(rpc_name.to_s) do
           raise ArgumentError, "#{service_class} has no RPC #{rpc_name}"
         end
@@ -95,6 +96,7 @@ module Tonic
           reader: reader,
           sender: sender,
           timeout_ms: timeout_ms,
+          peer: peer,
         )
 
         response = if spec[:response_stream]

data/lib/tonic/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Tonic
   module Rails
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/tonic-rails.rb

@@ -11,11 +11,13 @@ end
 
 require "tonic/rails/version"
 require "tonic/rails/metadata"
+require "tonic/rails/peer"
 require "tonic/rails/rpc_error"
 require "tonic/rails/configuration"
 require "tonic/rails/router"
 require "tonic/rails/instrumentation"
 require "tonic/rails/base"
+require "tonic/rails/health"
 require "tonic/rails/reflection"
 require "tonic/rails/server"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tonic-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Tanous
@@ -80,12 +80,21 @@ files:
 - ext/tonic_rails_native/src/log.rs
 - ext/tonic_rails_native/src/net.rs
 - ext/tonic_rails_native/src/server.rs
+- lib/generators/tonic_rails/install/install_generator.rb
+- lib/generators/tonic_rails/install/templates/tonic_rails.rb.tt
+- lib/generators/tonic_rails/service/service_generator.rb
+- lib/generators/tonic_rails/service/templates/handler.rb.tt
+- lib/generators/tonic_rails/service/templates/service.proto.tt
+- lib/generators/tonic_rails/service/templates/service_spec.rb.tt
+- lib/generators/tonic_rails/service/templates/service_test.rb.tt
 - lib/puma/plugin/tonic_rails.rb
 - lib/tonic-rails.rb
 - lib/tonic/rails/base.rb
 - lib/tonic/rails/configuration.rb
+- lib/tonic/rails/health.rb
 - lib/tonic/rails/instrumentation.rb
 - lib/tonic/rails/metadata.rb
+- lib/tonic/rails/peer.rb
 - lib/tonic/rails/railtie.rb
 - lib/tonic/rails/reflection.rb
 - lib/tonic/rails/router.rb
@@ -93,6 +102,9 @@ files:
 - lib/tonic/rails/server.rb
 - lib/tonic/rails/tasks/tonic-rails.rake
 - lib/tonic/rails/testing.rb
+- lib/tonic/rails/testing/errors.rb
+- lib/tonic/rails/testing/minitest.rb
+- lib/tonic/rails/testing/rspec.rb
 - lib/tonic/rails/version.rb
 homepage: https://github.com/CodingAnarchy/tonic-rails
 licenses: