Class: Gapic::ServiceStub

Inherits:
Object
  • Object
show all
Defined in:
lib/gapic/grpc/service_stub.rb,
lib/gapic/grpc/service_stub/rpc_call.rb

Overview

Gapic gRPC Stub

This class wraps the actual gRPC Stub object and it's RPC methods.

Defined Under Namespace

Classes: RpcCall

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil) ⇒ ServiceStub

Creates a Gapic gRPC stub object.

Parameters:

  • grpc_stub_class (Class) —

    gRPC stub class to create a new instance of.

  • endpoint (String) —

    The endpoint of the API.

  • credentials (Google::Auth::Credentials, Signet::OAuth2::Client, String, Hash, Proc, GRPC::Core::Channel, GRPC::Core::ChannelCredentials) —

    Provides the means for authenticating requests made by the client. This parameter can be many types:

    • A Google::Auth::Credentials uses a the properties of its represented keyfile for authenticating requests made by this client.
    • A Signet::OAuth2::Client object used to apply the OAuth credentials.
    • A GRPC::Core::Channel will be used to make calls through.
    • A GRPC::Core::ChannelCredentials for the setting up the RPC client. The channel credentials should already be composed with a GRPC::Core::CallCredentials object.
    • A Proc will be used as an updater_proc for the Grpc channel. The proc transforms the metadata for requests, generally, to give OAuth credentials.
  • channel_args (Hash) (defaults to: nil) —

    The channel arguments. (This argument is ignored when credentials is provided as a GRPC::Core::Channel.)

  • interceptors (Array<GRPC::ClientInterceptor>) (defaults to: nil) —

    An array of GRPC::ClientInterceptor objects that will be used for intercepting calls before they are executed Interceptors are an EXPERIMENTAL API.

Raises:

  • (ArgumentError) 


53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/gapic/grpc/service_stub.rb', line 53

def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil
  raise ArgumentError, "grpc_stub_class is required" if grpc_stub_class.nil?
  raise ArgumentError, "endpoint is required" if endpoint.nil?
  raise ArgumentError, "credentials is required" if credentials.nil?

  channel_args = Hash channel_args
  interceptors = Array interceptors

  @grpc_stub = case credentials
               when GRPC::Core::Channel
                 grpc_stub_class.new endpoint, nil, channel_override: credentials,
                                                    interceptors:     interceptors
               when GRPC::Core::ChannelCredentials, Symbol
                 grpc_stub_class.new endpoint, credentials, channel_args: channel_args,
                                                            interceptors: interceptors
               else
                 updater_proc = credentials.updater_proc if credentials.respond_to? :updater_proc
                 updater_proc ||= credentials if credentials.is_a? Proc
                 raise ArgumentError, "invalid credentials (#{credentials.class})" if updater_proc.nil?

                 call_creds = GRPC::Core::CallCredentials.new updater_proc
                 chan_creds = GRPC::Core::ChannelCredentials.new.compose call_creds
                 grpc_stub_class.new endpoint, chan_creds, channel_args: channel_args,
                                                           interceptors: interceptors
               end
end

Instance Attribute Details

#grpc_stub ⇒ Object (readonly)

Returns The instance of the gRPC stub class (grpc_stub_class) constructor argument.

Returns:

  • (Object) —

    The instance of the gRPC stub class (grpc_stub_class) constructor argument.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/gapic/grpc/service_stub.rb', line 28

class ServiceStub
  attr_reader :grpc_stub

  ##
  # Creates a Gapic gRPC stub object.
  #
  # @param grpc_stub_class [Class] gRPC stub class to create a new instance of.
  # @param endpoint [String] The endpoint of the API.
  # @param credentials [Google::Auth::Credentials, Signet::OAuth2::Client, String, Hash, Proc,
  #   GRPC::Core::Channel, GRPC::Core::ChannelCredentials] Provides the means for authenticating requests made by
  #   the client. This parameter can be many types:
  #
  #   * A `Google::Auth::Credentials` uses a the properties of its represented keyfile for authenticating requests
  #     made by this client.
  #   * A `Signet::OAuth2::Client` object used to apply the OAuth credentials.
  #   * A `GRPC::Core::Channel` will be used to make calls through.
  #   * A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials should
  #     already be composed with a `GRPC::Core::CallCredentials` object.
  #   * A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the metadata for
  #     requests, generally, to give OAuth credentials.
  # @param channel_args [Hash] The channel arguments. (This argument is ignored when `credentials` is
  #     provided as a `GRPC::Core::Channel`.)
  # @param interceptors [Array<GRPC::ClientInterceptor>] An array of {GRPC::ClientInterceptor} objects that will
  #   be used for intercepting calls before they are executed Interceptors are an EXPERIMENTAL API.
  #
  def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil
    raise ArgumentError, "grpc_stub_class is required" if grpc_stub_class.nil?
    raise ArgumentError, "endpoint is required" if endpoint.nil?
    raise ArgumentError, "credentials is required" if credentials.nil?

    channel_args = Hash channel_args
    interceptors = Array interceptors

    @grpc_stub = case credentials
                 when GRPC::Core::Channel
                   grpc_stub_class.new endpoint, nil, channel_override: credentials,
                                                      interceptors:     interceptors
                 when GRPC::Core::ChannelCredentials, Symbol
                   grpc_stub_class.new endpoint, credentials, channel_args: channel_args,
                                                              interceptors: interceptors
                 else
                   updater_proc = credentials.updater_proc if credentials.respond_to? :updater_proc
                   updater_proc ||= credentials if credentials.is_a? Proc
                   raise ArgumentError, "invalid credentials (#{credentials.class})" if updater_proc.nil?

                   call_creds = GRPC::Core::CallCredentials.new updater_proc
                   chan_creds = GRPC::Core::ChannelCredentials.new.compose call_creds
                   grpc_stub_class.new endpoint, chan_creds, channel_args: channel_args,
                                                             interceptors: interceptors
                 end
  end

  ##
  # Invoke the specified RPC call.
  #
  # @param method_name [Symbol] The RPC method name.
  # @param request [Object] The request object.
  # @param options [Gapic::CallOptions, Hash] The options for making the RPC call. A Hash can be provided to
  #   customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}. This object
  #   should only be used once.
  #
  # @yield [response, operation] Access the response along with the RPC operation.
  # @yieldparam response [Object] The response object.
  # @yieldparam operation [GRPC::ActiveCall::Operation] The RPC operation for the response.
  #
  # @return [Object] The response object.
  #
  # @example
  #   require "google/showcase/v1beta1/echo_pb"
  #   require "google/showcase/v1beta1/echo_services_pb"
  #   require "gapic"
  #   require "gapic/grpc"
  #
  #   echo_channel = GRPC::Core::Channel.new(
  #     "localhost:7469", nil, :this_channel_is_insecure
  #   )
  #   echo_stub = Gapic::ServiceStub.new(
  #     Google::Showcase::V1beta1::Echo::Stub,
  #     endpoint: "localhost:7469", credentials: echo_channel
  #   )
  #
  #   request = Google::Showcase::V1beta1::EchoRequest.new
  #   response = echo_stub.call_rpc :echo, request
  #
  # @example Using custom call options:
  #   require "google/showcase/v1beta1/echo_pb"
  #   require "google/showcase/v1beta1/echo_services_pb"
  #   require "gapic"
  #   require "gapic/grpc"
  #
  #   echo_channel = GRPC::Core::Channel.new(
  #     "localhost:7469", nil, :this_channel_is_insecure
  #   )
  #   echo_stub = Gapic::ServiceStub.new(
  #     Google::Showcase::V1beta1::Echo::Stub,
  #     endpoint: "localhost:7469", credentials: echo_channel
  #   )
  #
  #   request = Google::Showcase::V1beta1::EchoRequest.new
  #   options = Gapic::CallOptions.new(
  #     retry_policy = {
  #       retry_codes: [GRPC::Core::StatusCodes::UNAVAILABLE]
  #     }
  #   )
  #   response = echo_stub.call_rpc :echo, request
  #                                 options: options
  #
  # @example Accessing the response and RPC operation using a block:
  #   require "google/showcase/v1beta1/echo_pb"
  #   require "google/showcase/v1beta1/echo_services_pb"
  #   require "gapic"
  #   require "gapic/grpc"
  #
  #   echo_channel = GRPC::Core::Channel.new(
  #     "localhost:7469", nil, :this_channel_is_insecure
  #   )
  #   echo_stub = Gapic::ServiceStub.new(
  #     Google::Showcase::V1beta1::Echo::Stub,
  #     endpoint: "localhost:7469", credentials: echo_channel
  #   )
  #
  #   request = Google::Showcase::V1beta1::EchoRequest.new
  #   echo_stub.call_rpc :echo, request do |response, operation|
  #     operation.trailing_metadata
  #   end
  #
  def call_rpc method_name, request, options: nil, &block
    rpc_call = RpcCall.new @grpc_stub.method method_name
    rpc_call.call request, options: options, &block
  end
end

Instance Method Details

#call_rpc(method_name, request, options: nil) {|response, operation| ... } ⇒ Object

Invoke the specified RPC call.

Examples:

require "google/showcase/v1beta1/echo_pb"
require "google/showcase/v1beta1/echo_services_pb"
require "gapic"
require "gapic/grpc"

echo_channel = GRPC::Core::Channel.new(
  "localhost:7469", nil, :this_channel_is_insecure
)
echo_stub = Gapic::ServiceStub.new(
  Google::Showcase::V1beta1::Echo::Stub,
  endpoint: "localhost:7469", credentials: echo_channel
)

request = Google::Showcase::V1beta1::EchoRequest.new
response = echo_stub.call_rpc :echo, request

Using custom call options:

require "google/showcase/v1beta1/echo_pb"
require "google/showcase/v1beta1/echo_services_pb"
require "gapic"
require "gapic/grpc"

echo_channel = GRPC::Core::Channel.new(
  "localhost:7469", nil, :this_channel_is_insecure
)
echo_stub = Gapic::ServiceStub.new(
  Google::Showcase::V1beta1::Echo::Stub,
  endpoint: "localhost:7469", credentials: echo_channel
)

request = Google::Showcase::V1beta1::EchoRequest.new
options = Gapic::CallOptions.new(
  retry_policy = {
    retry_codes: [GRPC::Core::StatusCodes::UNAVAILABLE]
  }
)
response = echo_stub.call_rpc :echo, request
                              options: options

Accessing the response and RPC operation using a block:

require "google/showcase/v1beta1/echo_pb"
require "google/showcase/v1beta1/echo_services_pb"
require "gapic"
require "gapic/grpc"

echo_channel = GRPC::Core::Channel.new(
  "localhost:7469", nil, :this_channel_is_insecure
)
echo_stub = Gapic::ServiceStub.new(
  Google::Showcase::V1beta1::Echo::Stub,
  endpoint: "localhost:7469", credentials: echo_channel
)

request = Google::Showcase::V1beta1::EchoRequest.new
echo_stub.call_rpc :echo, request do |response, operation|
  operation.trailing_metadata
end

Parameters:

  • method_name (Symbol) —

    The RPC method name.

  • request (Object) —

    The request object.

  • options (Gapic::CallOptions, Hash) (defaults to: nil) —

    The options for making the RPC call. A Hash can be provided to customize the options object, using keys that match the arguments for CallOptions.new. This object should only be used once.

Yields:

  • (response, operation) —

    Access the response along with the RPC operation.

Yield Parameters:

  • response (Object) —

    The response object.

  • operation (GRPC::ActiveCall::Operation) —

    The RPC operation for the response.

Returns:

  • (Object) —

    The response object.



154
155
156
157
 
# File 'lib/gapic/grpc/service_stub.rb', line 154

def call_rpc method_name, request, options: nil, &block
  rpc_call = RpcCall.new @grpc_stub.method method_name
  rpc_call.call request, options: options, &block
end