tonic-rails 0.5.0 → 0.6.0

data/ext/tonic_rails_native/src/gvl.rs

@@ -20,7 +20,7 @@ use magnus::{
     Error, RHash, RString, Ruby, Value, prelude::*, r_hash::ForEach, typed_data::DataTypeFunctions,
     value::Opaque,
 };
-use parking_lot::Mutex;
+use parking_lot::{Condvar, Mutex};
 use rb_sys::{RB_NOGVL_INTR_FAIL, rb_nogvl, rb_thread_call_with_gvl};
 use tokio::sync::{Notify, mpsc};
 
@@ -100,25 +100,40 @@ where
 
 /// Minimal single-future executor that parks the current (non-tokio)
 /// thread.  tokio's channel and `Notify` futures are runtime-agnostic.
+///
+/// It parks on a pthread condition variable rather than
+/// `std::thread::park`, which on macOS uses libdispatch: libdispatch
+/// traps in the child of a multi-threaded process, and the client blocks
+/// here in processes forked after it made calls.
 pub fn block_on<F: Future>(fut: F) -> F::Output {
-    struct ThreadWaker(std::thread::Thread);
-    impl Wake for ThreadWaker {
+    #[derive(Default)]
+    struct Signal {
+        woken: Mutex<bool>,
+        condvar: Condvar,
+    }
+    impl Wake for Signal {
         fn wake(self: Arc<Self>) {
-            self.0.unpark();
+            self.wake_by_ref();
         }
         fn wake_by_ref(self: &Arc<Self>) {
-            self.0.unpark();
+            *self.woken.lock() = true;
+            self.condvar.notify_one();
         }
     }
 
-    let waker = Waker::from(Arc::new(ThreadWaker(std::thread::current())));
+    let signal = Arc::new(Signal::default());
+    let waker = Waker::from(signal.clone());
     let mut cx = Context::from_waker(&waker);
     let mut fut = std::pin::pin!(fut);
     loop {
         if let Poll::Ready(value) = fut.as_mut().poll(&mut cx) {
             return value;
         }
-        std::thread::park();
+        let mut woken = signal.woken.lock();
+        while !*woken {
+            signal.condvar.wait(&mut woken);
+        }
+        *woken = false;
     }
 }
 

data/ext/tonic_rails_native/src/lib.rs

@@ -20,6 +20,7 @@
 //! Modules:
 //! - [`framing`]  — gRPC wire format (frames, gzip, timeouts, trailers)
 //! - [`body`]     — response bodies and request stats
+//! - [`client`]   — `TonicRails::Native::Channel` and `ResponseStream`, for outgoing calls
 //! - [`dispatch`] — the fallback tower service that queues RPCs for Ruby
 //! - [`gvl`]      — GVL release/acquire and the Ruby stream objects
 //! - [`log`]      — transport log events for Ruby's logger
@@ -27,6 +28,7 @@
 //! - [`server`]   — `TonicRails::Native::Server`
 
 mod body;
+mod client;
 mod dispatch;
 mod framing;
 mod gvl;
@@ -36,6 +38,7 @@ mod server;
 
 use magnus::{Error, Ruby, function, method, prelude::*};
 
+use client::{NativeChannel, ResponseStream};
 use gvl::{RequestReader, StreamSender};
 use server::NativeServer;
 
@@ -95,5 +98,16 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     reader.define_method("next", method!(RequestReader::next, 0))?;
     reader.define_method("error", method!(RequestReader::error, 0))?;
 
+    let channel = native.define_class("Channel", ruby.class_object())?;
+    channel.define_singleton_method("new", function!(NativeChannel::new, 4))?;
+    channel.define_method("unary", method!(NativeChannel::unary, 4))?;
+    channel.define_method("server_streaming", method!(NativeChannel::server_streaming, 4))?;
+
+    let stream = native.define_class("ResponseStream", ruby.class_object())?;
+    stream.undef_default_alloc_func();
+    stream.define_method("next", method!(ResponseStream::next, 0))?;
+    stream.define_method("result", method!(ResponseStream::result, 0))?;
+    stream.define_method("close", method!(ResponseStream::close, 0))?;
+
     Ok(())
 }

data/lib/tonic/rails/base.rb

@@ -248,7 +248,10 @@ module Tonic
 
         @request = build_request(reader, spec)
         response = nil
-        run_callbacks(:rpc) { response = respond(public_send(spec[:handler], @request), spec, sender) }
+        # Calls this handler makes with Tonic::Rails::Client default to its deadline.
+        Client.with_deadline(@grpc_deadline_at) do
+          run_callbacks(:rpc) { response = respond(public_send(spec[:handler], @request), spec, sender) }
+        end
         response
       rescue RpcError
         raise

data/lib/tonic/rails/client.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+require "active_support/inflector"
+
+module Tonic
+  module Rails
+    # Calls other gRPC services, without the grpc gem.
+    #
+    #   ITEMS = Tonic::Rails::Client.new("items.internal:50051", deadline: 2)
+    #
+    #   items = ITEMS.stub("demo.v1.ItemService")
+    #   item = items.get_item(Demo::V1::GetItemRequest.new(id: 1))
+    #   item = items.get_item(id: 1)
+    #   item = items.get_item({ id: 1 }, deadline: 0.5, metadata: { "x-request-id" => request_id })
+    #   items.list_items(category: "books").each { |item| ... }
+    #
+    # Stubs are built from the protobuf descriptors that
+    # `tonic_rails:compile_protos` (protoc --ruby_out) generates; no
+    # `_services_pb.rb` is needed.  A failed call raises
+    # Tonic::Rails::RpcError.
+    #
+    # A client holds one HTTP/2 connection and is safe to share between
+    # threads, so create it once (a constant or an initializer).  It keeps
+    # working across `fork`: each process connects on its own, with no
+    # hooks to call.
+    class Client
+      # A response with its headers and trailers; see `return_call:`.
+      Call = Data.define(:response, :headers, :trailers)
+
+      DEFAULT_MAX_MESSAGE_SIZE = 4 * 1024 * 1024
+
+      # @return [String] "host:port"
+      attr_reader :address
+
+      # @return [Numeric, nil] default deadline in seconds
+      attr_reader :deadline
+
+      # @param address [String] "host:port"
+      # @param tls [Boolean] false for plaintext, which must be explicit
+      # @param tls_ca_path [String, nil] CA certificates (PEM) to trust instead
+      #   of the system's root certificates
+      # @param tls_cert_path [String, nil] client certificate (PEM), for mutual TLS
+      # @param tls_key_path [String, nil] client private key (PEM), for mutual TLS
+      # @param tls_server_name [String, nil] name to verify the server's
+      #   certificate against, if not the host in `address`
+      # @param deadline [Numeric, nil] seconds each call may take, unless the
+      #   call sets its own
+      # @param metadata [Hash] sent with every call (see Tonic::Rails::Metadata)
+      # @param max_message_size [Integer] largest message sent or received, in bytes
+      # @param connect_timeout [Numeric] seconds to wait for a connection
+      def initialize(address, tls: true, tls_ca_path: nil, tls_cert_path: nil, tls_key_path: nil,
+                     tls_server_name: nil, deadline: nil, metadata: {}, max_message_size: DEFAULT_MAX_MESSAGE_SIZE,
+                     connect_timeout: 5)
+        Tonic::Rails.native_extension!
+        validate_address!(address)
+        validate_tls!(tls, tls_cert_path, tls_key_path)
+        positive!(:deadline, deadline) unless deadline.nil?
+        positive!(:connect_timeout, connect_timeout)
+        unless max_message_size.is_a?(Integer) && max_message_size.positive?
+          raise ArgumentError, "max_message_size must be a positive Integer"
+        end
+
+        @address = address
+        @deadline = deadline
+        @metadata = Metadata.encode(metadata)
+        @stubs = {}
+        tls_options = [read_pem(tls_ca_path, "CA"), read_pem(tls_cert_path, "certificate"),
+                       read_pem(tls_key_path, "key"), tls_server_name]
+        @native = TonicRails::Native::Channel.new(
+          "#{tls ? 'https' : 'http'}://#{address}", max_message_size, (connect_timeout * 1000).ceil,
+          (tls_options if tls)
+        )
+      end
+
+      # A stub with one method per RPC of the service, named in snake_case
+      # (`GetItem` becomes `get_item`).
+      #
+      # @param service [String, Google::Protobuf::ServiceDescriptor, #service_name]
+      #   the fully-qualified service name, its descriptor, or a grpc gem
+      #   service class (`Demo::V1::ItemService::Service`)
+      # @return [Tonic::Rails::Client::Stub]
+      def stub(service)
+        descriptor = service_descriptor(service)
+        @stubs[descriptor.name] ||= Stub.for(descriptor).new(self)
+      end
+
+      def inspect
+        "#<#{self.class.name} #{address}>"
+      end
+
+      # The deadline of the RPC this thread is handling, as a monotonic
+      # clock time; outgoing calls default to it.
+      # @api private
+      def self.current_deadline
+        Thread.current[:tonic_rails_deadline]
+      end
+
+      # @api private
+      def self.with_deadline(deadline)
+        previous = Thread.current[:tonic_rails_deadline]
+        Thread.current[:tonic_rails_deadline] = deadline
+        yield
+      ensure
+        Thread.current[:tonic_rails_deadline] = previous
+      end
+
+      # Make a unary call.  Stubs call this; use them instead.
+      # @api private
+      def unary(path, input, output, request, deadline: nil, metadata: {}, return_call: false)
+        message = request_message(path, input, request)
+        metadata = call_metadata(metadata)
+        timeout_ms = remaining_ms(deadline_at(deadline))
+
+        Instrumentation.instrument_request(path, address, metadata) do
+          code, error_message, response, headers, trailers, details =
+            @native.unary(path, input.encode(message), metadata, timeout_ms)
+          headers = decode_metadata(headers)
+          trailers = decode_metadata(trailers)
+          check_status!(code, error_message, trailers, details)
+
+          response = decode_response(output, response, path)
+          return_call ? Call.new(response: response, headers: headers, trailers: trailers) : response
+        end
+      end
+
+      # Start a server-streaming call.  Stubs call this; use them instead.
+      # @api private
+      def server_streaming(path, input, output, request, deadline: nil, metadata: {})
+        message = request_message(path, input, request)
+        metadata = call_metadata(metadata)
+        # Fixed now, so the stream keeps the deadline of the RPC this
+        # thread is handling even if it's read later.
+        deadline_at = deadline_at(deadline)
+
+        ServerStream.new(path) do |stream, block|
+          timeout_ms = remaining_ms(deadline_at)
+          Instrumentation.instrument_request(path, address, metadata) do
+            native = @native.server_streaming(path, input.encode(message), metadata, timeout_ms)
+            begin
+              while (bytes = native.next)
+                block.call(decode_response(output, bytes, path))
+              end
+              code, error_message, _, headers, trailers, details = native.result
+              trailers = decode_metadata(trailers)
+              stream.finish(decode_metadata(headers), trailers)
+              check_status!(code, error_message, trailers, details)
+            ensure
+              native.close
+            end
+          end
+        end
+      end
+
+      private
+
+      def validate_address!(address)
+        return if address.is_a?(String) && address.match?(%r{\A[^\s/]+:\d+\z})
+
+        raise ArgumentError, "address must be \"host:port\", got #{address.inspect}"
+      end
+
+      def validate_tls!(tls, cert_path, key_path)
+        raise ArgumentError, "tls must be true or false" unless [true, false].include?(tls)
+        raise ArgumentError, "tls_cert_path and tls_key_path must be set together" if cert_path.nil? != key_path.nil?
+        raise ArgumentError, "tls_cert_path and tls_key_path need tls: true" if cert_path && !tls
+      end
+
+      def positive!(name, value)
+        raise ArgumentError, "#{name} must be a positive number of seconds" unless value.is_a?(Numeric) && value.positive?
+      end
+
+      def read_pem(path, what)
+        return unless path
+        raise ArgumentError, "TLS #{what} file not found: #{path}" unless File.file?(path)
+
+        File.read(path)
+      end
+
+      def service_descriptor(service)
+        return service if service.is_a?(Google::Protobuf::ServiceDescriptor)
+
+        name = service.respond_to?(:service_name) ? service.service_name : service.to_s
+        descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(name)
+        return descriptor if descriptor.is_a?(Google::Protobuf::ServiceDescriptor)
+
+        raise NotConfiguredError,
+              "#{name} is not a known protobuf service. Require its generated _pb.rb file (protoc --ruby_out) first."
+      end
+
+      def request_message(path, input, request)
+        case request
+        when input then request
+        when Hash then input.new(request)
+        else raise TypeError, "#{path} expects a #{input} or Hash, got #{request.class}"
+        end
+      end
+
+      def call_metadata(metadata)
+        metadata.empty? ? @metadata : @metadata.merge(Metadata.encode(metadata))
+      end
+
+      # When the call must end, as a monotonic clock time: the call's own
+      # deadline, or else the earlier of the client's default and the
+      # deadline of the RPC being handled.
+      def deadline_at(deadline)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        case deadline
+        when nil then [(now + @deadline if @deadline), self.class.current_deadline].compact.min
+        when Numeric then now + deadline
+        when Time then now + (deadline - Time.now)
+        else raise ArgumentError, "deadline must be seconds (Numeric) or a Time, got #{deadline.class}"
+        end
+      end
+
+      # Milliseconds left until `deadline_at`, or nil for no deadline.
+      def remaining_ms(deadline_at)
+        return unless deadline_at
+
+        remaining = deadline_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise RpcError.new("deadline exceeded", code: :deadline_exceeded) unless remaining.positive?
+
+        (remaining * 1000).ceil
+      end
+
+      def check_status!(code, message, trailers, details)
+        return if code.zero?
+
+        raise RpcError.new(message.empty? ? nil : message, code: code, metadata: trailers,
+                                                           details: RpcError.decode_details(details))
+      end
+
+      # Wire-form [name, value] pairs to a Hash: `-bin` values decoded,
+      # repeated names collected into an Array, and transport headers
+      # (content-type, grpc-*) dropped.
+      def decode_metadata(pairs)
+        pairs.each_with_object({}) do |(name, value), metadata|
+          next if name.start_with?("grpc-") || Metadata::RESERVED.include?(name)
+
+          value = value.unpack1("m") if name.end_with?("-bin")
+          metadata[name] = metadata.key?(name) ? [*metadata[name], value] : value
+        end
+      end
+
+      def decode_response(output, bytes, path)
+        output.decode(bytes)
+      rescue Google::Protobuf::ParseError
+        raise RpcError.new("invalid protobuf response from #{path}", code: :internal)
+      end
+
+      # Calls an RPC's methods.  Built per service from its descriptor; get
+      # one with Client#stub.
+      class Stub
+        class << self
+          # @api private
+          attr_reader :service_name
+
+          # @api private
+          def for(descriptor)
+            Class.new(self) do
+              @service_name = descriptor.name
+              descriptor.each { |method| define_rpc(method) }
+            end
+          end
+
+          def inspect
+            service_name ? "#{Stub.name}(#{service_name})" : super
+          end
+
+          private
+
+          def define_rpc(method)
+            path = "/#{service_name}/#{method.name}"
+            name = ActiveSupport::Inflector.underscore(method.name)
+            if method.client_streaming
+              define_method(name) do |*, **|
+                raise NotImplementedError,
+                      "#{path} is a client-streaming RPC; the tonic-rails client makes unary and server-streaming calls"
+              end
+              return
+            end
+
+            input = method.input_type.msgclass
+            output = method.output_type.msgclass
+            if method.server_streaming
+              define_method(name) do |request = nil, deadline: nil, metadata: {}, **fields|
+                request = rpc_request(name, request, fields)
+                @client.server_streaming(path, input, output, request, deadline: deadline, metadata: metadata)
+              end
+            else
+              # `get_item(id: 1)` works as well as `get_item({ id: 1 })`.
+              define_method(name) do |request = nil, deadline: nil, metadata: {}, return_call: false, **fields|
+                request = rpc_request(name, request, fields)
+                @client.unary(path, input, output, request, deadline: deadline, metadata: metadata,
+                                                            return_call: return_call)
+              end
+            end
+          end
+        end
+
+        # @return [Tonic::Rails::Client]
+        attr_reader :client
+
+        def initialize(client)
+          @client = client
+        end
+
+        def inspect
+          "#<#{self.class.inspect} #{client.address}>"
+        end
+
+        private
+
+        def rpc_request(name, request, fields)
+          unless request.nil? || fields.empty?
+            raise ArgumentError, "#{name}: pass the request or its fields, not both (#{fields.keys.join(', ')})"
+          end
+
+          request || fields
+        end
+      end
+
+      # The responses of a server-streaming call.  Nothing is sent until
+      # it's read; then messages are yielded as they arrive, a few at most
+      # buffered ahead of the reader.
+      #
+      #   items.list_items(category: "books").each { |item| ... }
+      #   items.list_items(category: "books").first(10)
+      #
+      # Stopping early (`break`, `first(n)`, an exception) cancels the call.
+      # An error from the server raises Tonic::Rails::RpcError after the
+      # messages that came before it.  A stream can be read once.
+      class ServerStream
+        include Enumerable
+
+        # @return [Hash, nil] response headers, once the stream has ended
+        attr_reader :headers
+
+        # @return [Hash, nil] trailing metadata, once the stream has ended
+        attr_reader :trailers
+
+        # @api private
+        def initialize(path, &read)
+          @path = path
+          @read = read
+        end
+
+        # @yieldparam response [Google::Protobuf::AbstractMessage]
+        # @return [self, Enumerator] an Enumerator without a block
+        def each(&block)
+          return enum_for(:each) unless block
+          raise Error, "the #{@path} stream has already been read" unless @read
+
+          read = @read
+          @read = nil
+          read.call(self, block)
+          self
+        end
+
+        # @api private
+        def finish(headers, trailers)
+          @headers = headers
+          @trailers = trailers
+        end
+
+        def inspect
+          "#<#{self.class.name} #{@path}>"
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/instrumentation.rb

@@ -24,17 +24,32 @@ module Tonic
     module Instrumentation
       EVENT = "process_rpc.tonic_rails"
 
+      # Outgoing calls made with Tonic::Rails::Client publish
+      # "request_rpc.tonic_rails", with the same payload plus :address,
+      # the server called.
+      REQUEST_EVENT = "request_rpc.tonic_rails"
+
       module_function
 
       # @api private
-      def instrument(path, metadata)
+      def instrument(path, metadata, &)
+        publish(EVENT, path, metadata, &)
+      end
+
+      # @api private
+      def instrument_request(path, address, metadata, &)
+        publish(REQUEST_EVENT, path, metadata, address: address, &)
+      end
+
+      # @api private
+      def publish(event, path, metadata, **extra)
         # Without subscribers, skip building the payload: this runs on
         # every RPC.
-        return yield unless ActiveSupport::Notifications.notifier.listening?(EVENT)
+        return yield unless ActiveSupport::Notifications.notifier.listening?(event)
 
         service, rpc = path.delete_prefix("/").split("/", 2)
-        payload = { path: path, service: service, rpc: rpc, metadata: metadata, code: nil, status: nil }
-        ActiveSupport::Notifications.instrument(EVENT, payload) do
+        payload = { path: path, service: service, rpc: rpc, metadata: metadata, code: nil, status: nil, **extra }
+        ActiveSupport::Notifications.instrument(event, payload) do
           result = yield
           payload[:code] = 0
           payload[:status] = :ok

data/lib/tonic/rails/rpc_error.rb

@@ -19,6 +19,8 @@ module Tonic
     # The message, metadata and details go to the client, so keep internal
     # details out of them.  Any other exception becomes INTERNAL with a
     # generic message and is logged server-side.
+    #
+    # Tonic::Rails::Client raises it too, for calls that fail.
     class RpcError < Error
       CODES = {
         ok: 0,
@@ -114,6 +116,65 @@ module Tonic
         CODE_NAMES.fetch(@code)
       end
 
+      # Unpacks the details of an encoded google.rpc.Status (from the
+      # grpc-status-details-bin trailer).  Details whose message type is
+      # loaded come back as that message; others stay Google::Protobuf::Any.
+      # @api private
+      # @return [Array<Google::Protobuf::AbstractMessage>]
+      def self.decode_details(bytes)
+        return [] if bytes.nil? || bytes.empty?
+
+        require "google/protobuf/well_known_types"
+        details = []
+        each_length_delimited_field(bytes.b) do |field, value|
+          details << unpack_detail(Google::Protobuf::Any.decode(value)) if field == 3
+        end
+        details
+      rescue Google::Protobuf::ParseError, ArgumentError
+        []
+      end
+
+      # Yields (field number, bytes) for each length-delimited field,
+      # skipping varints; raises ArgumentError on anything malformed.
+      def self.each_length_delimited_field(buf)
+        pos = 0
+        while pos < buf.bytesize
+          key, pos = read_varint(buf, pos)
+          case key & 7
+          when 0 then _, pos = read_varint(buf, pos)
+          when 2
+            length, pos = read_varint(buf, pos)
+            raise ArgumentError, "truncated google.rpc.Status" if pos + length > buf.bytesize
+
+            yield key >> 3, buf.byteslice(pos, length)
+            pos += length
+          else raise ArgumentError, "unexpected wire type in google.rpc.Status"
+          end
+        end
+      end
+      private_class_method :each_length_delimited_field
+
+      def self.read_varint(buf, pos)
+        value = 0
+        shift = 0
+        loop do
+          byte = buf.getbyte(pos) or raise ArgumentError, "truncated varint"
+          pos += 1
+          value |= (byte & 0x7f) << shift
+          return [value, pos] if byte < 0x80
+
+          shift += 7
+          raise ArgumentError, "varint too long" if shift > 63
+        end
+      end
+      private_class_method :read_varint
+
+      def self.unpack_detail(any)
+        type = Google::Protobuf::DescriptorPool.generated_pool.lookup(any.type_name)
+        type.is_a?(Google::Protobuf::Descriptor) ? any.unpack(type.msgclass) : any
+      end
+      private_class_method :unpack_detail
+
       # @api private
       def self.normalize_code(code)
         case code

data/lib/tonic/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Tonic
   module Rails
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/tonic-rails.rb

@@ -21,6 +21,7 @@ require "tonic/rails/health"
 require "tonic/rails/reflection"
 require "tonic/rails/cluster"
 require "tonic/rails/server"
+require "tonic/rails/client"
 
 module Tonic
   module Rails

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tonic-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Matt Tanous
@@ -73,6 +73,7 @@ files:
 - ext/tonic_rails_native/Cargo.toml
 - ext/tonic_rails_native/extconf.rb
 - ext/tonic_rails_native/src/body.rs
+- ext/tonic_rails_native/src/client.rs
 - ext/tonic_rails_native/src/dispatch.rs
 - ext/tonic_rails_native/src/framing.rs
 - ext/tonic_rails_native/src/gvl.rs
@@ -90,6 +91,7 @@ files:
 - lib/puma/plugin/tonic_rails.rb
 - lib/tonic-rails.rb
 - lib/tonic/rails/base.rb
+- lib/tonic/rails/client.rb
 - lib/tonic/rails/cluster.rb
 - lib/tonic/rails/configuration.rb
 - lib/tonic/rails/health.rb