Module: GRPC::GenericService::Dsl

Defined in:
src/ruby/lib/grpc/generic/service.rb

Overview

Provides a simple DSL to describe RPC services.

E.g, a Maths service that uses the serializable messages DivArgs, DivReply and Num might define its endpoint uses the following way:

rpc :div DivArgs, DivReply # single request, single response rpc :sum stream(Num), Num # streamed input, single response rpc :fib FibArgs, stream(Num) # single request, streamed response rpc :div_many stream(DivArgs), stream(DivReply)

# streamed req and resp

Each ‘rpc’ adds an RpcDesc to classes including this module, and #assert_rpc_descs_have_methods is used to ensure the including class provides methods with signatures that support all the descriptors.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#marshal_class_method ⇒ Object

the name of the instance method used to marshal events to a byte stream.



113
114
115
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 113

def marshal_class_method
  @marshal_class_method ||= :marshal
end

#service_name ⇒ Object

This allows configuration of the service name.



77
78
79
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 77

def service_name
  @service_name
end

#unmarshal_class_method ⇒ Object

the name of the class method used to unmarshal from a byte stream.



118
119
120
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 118

def unmarshal_class_method
  @unmarshal_class_method ||= :unmarshal
end

Instance Method Details

#assert_can_marshal(cls) ⇒ Object 



122
123
124
125
126
127
128
129
130
131
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 122

def assert_can_marshal(cls)
  cls = cls.type if cls.is_a? RpcDesc::Stream
  mth = unmarshal_class_method
  unless cls.methods.include? mth
    fail(ArgumentError, "#{cls} needs #{cls}.#{mth}")
  end
  mth = marshal_class_method
  return if cls.methods.include? mth
  fail(ArgumentError, "#{cls} needs #{cls}.#{mth}")
end

#inherited(subclass) ⇒ Object 



104
105
106
107
108
109
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 104

def inherited(subclass)
  # Each subclass should have a distinct class variable with its own
  # rpc_descs
  subclass.rpc_descs.merge!(rpc_descs)
  subclass.service_name = service_name
end

#rpc(name, input, output) ⇒ Object

Adds an RPC spec.

Takes the RPC name and the classes representing the types to be serialized, and adds them to the including classes rpc_desc hash.

input and output should both have the methods #marshal and #unmarshal that are responsible for writing and reading an object instance from a byte buffer respectively.

Parameters:

  • name (String) —

    the name of the rpc

  • input (Object) —

    the input parameter’s class

  • output (Object) —

    the output parameter’s class



91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 91

def rpc(name, input, output)
  fail(DuplicateRpcName, name) if rpc_descs.key? name
  assert_can_marshal(input)
  assert_can_marshal(output)
  rpc_descs[name] = RpcDesc.new(name, input, output,
                                marshal_class_method,
                                unmarshal_class_method)
  define_method(GenericService.underscore(name.to_s).to_sym) do |_, _|
    fail GRPC::BadStatus.new_status_exception(
      GRPC::Core::StatusCodes::UNIMPLEMENTED)
  end
end

#rpc_descs ⇒ Object

the RpcDescs defined for this GenericService, keyed by name.



141
142
143
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 141

def rpc_descs
  @rpc_descs ||= {}
end

#rpc_stub_class ⇒ Object

Creates a rpc client class with methods for accessing the methods currently in rpc_descs.



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 147

def rpc_stub_class
  descs = rpc_descs
  route_prefix = service_name
  Class.new(ClientStub) do
    # @param host [String] the host the stub connects to
    # @param creds [Core::ChannelCredentials|Symbol] The channel
    #     credentials to use, or :this_channel_is_insecure otherwise
    # @param kw [KeywordArgs] the channel arguments, plus any optional
    #                         args for configuring the client's channel
    def initialize(host, creds, **kw)
      super(host, creds, **kw)
    end

    # Used define_method to add a method for each rpc_desc.  Each method
    # calls the base class method for the given descriptor.
    descs.each_pair do |name, desc|
      mth_name = GenericService.underscore(name.to_s).to_sym
      marshal = desc.marshal_proc
      unmarshal = desc.unmarshal_proc(:output)
      route = "/#{route_prefix}/#{name}"
      if desc.request_response?
        define_method(mth_name) do |req, metadata = {}|
          GRPC.logger.debug("calling #{@host}:#{route}")
          request_response(route, req, marshal, unmarshal, metadata)
        end
      elsif desc.client_streamer?
        define_method(mth_name) do |reqs, metadata = {}|
          GRPC.logger.debug("calling #{@host}:#{route}")
          client_streamer(route, reqs, marshal, unmarshal, metadata)
        end
      elsif desc.server_streamer?
        define_method(mth_name) do |req, metadata = {}, &blk|
          GRPC.logger.debug("calling #{@host}:#{route}")
          server_streamer(route, req, marshal, unmarshal, metadata, &blk)
        end
      else  # is a bidi_stream
        define_method(mth_name) do |reqs, metadata = {}, &blk|
          GRPC.logger.debug("calling #{@host}:#{route}")
          bidi_streamer(route, reqs, marshal, unmarshal, metadata, &blk)
        end
      end
    end
  end
end

#stream(cls) ⇒ Object

Returns cls wrapped in a RpcDesc::Stream.

Parameters:

  • cls (Class) —

    the class of a serializable type

Returns:

  • cls wrapped in a RpcDesc::Stream



135
136
137
138
 
# File 'src/ruby/lib/grpc/generic/service.rb', line 135

def stream(cls)
  assert_can_marshal(cls)
  RpcDesc::Stream.new(cls)
end