grpc v0.5.0-beta.1 GRPC.Stub View Source

A module acting as the interface for gRPC client.

You can do everything in the client side via GRPC.Stub, including connecting, sending/receiving steaming or non-steaming requests, canceling calls and so on.

A service is needed to define a stub:

defmodule Greeter.Service do
  use GRPC.Service, name: "ping"

  rpc :SayHello, Request, Reply
  rpc :SayGoodbye, stream(Request), stream(Reply)
end

defmodule Greeter.Stub do
  use GRPC.Stub, service: Greeter.Service
end

so that functions say_hello/2 and say_goodbye/1 will be generated for you:

# Unary call
{:ok, reply} = Greeter.Stub.say_hello(channel, request)

# Streaming call
stream = Greeter.Stub.say_goodbye(channel)
GRPC.Stub.send_request(stream, request, end_stream: true)
{:ok, reply_enum} = GRPC.Stub.recv(stream)
replies = Enum.map(reply_enum, fn({:ok, reply}) -> reply end)

Note that streaming calls are very different with unary calls. If request is streaming, the RPC function only accepts channel as argument and returns a GRPC.Client.Stream. You can send streaming requests one by one via send_request/3, then use recv/1 to receive the reply. And if the reply is streaming, recv/1 returns a Stream.

You can refer to call/6 for doc of your RPC functions.

Link to this section Summary

Types

rpc_return()

Functions

call(service_mod, rpc, stream, request, opts)

The actual function invoked when invoking a rpc function.

cancel(stream)

Cancel a stream in a streaming client.

connect(addr, opts \\ [])

Establish a connection with gRPC server and return GRPC.Channel needed for sending requests.

connect(host, port, opts)

disconnect(channel)

Disconnects the adapter and frees any resources the adapter is consuming

end_stream(stream)

Send END_STREAM frame to end the stream.

recv(stream, opts \\ [])

Receive replies when requests are streaming.

retry_timeout(curr)

send_request(stream, request, opts \\ [])

Send streaming requests.

stream_send(stream, request, opts \\ []) deprecated

DEPRECATED. Use send_request/3 instead

Link to this section Types

rpc_return()

rpc_return() ::
  {:ok, struct()}
  | {:ok, struct(), map()}
  | GRPC.Client.Stream.t()
  | {:ok, Enumerable.t()}
  | {:ok, Enumerable.t(), map()}
  | {:error, GRPC.RPCError.t()}

Link to this section Functions

call(service_mod, rpc, stream, request, opts)

call(atom(), tuple(), GRPC.Client.Stream.t(), struct() | nil, keyword()) ::
  rpc_return()

The actual function invoked when invoking a rpc function.

Returns

Unary calls. {:ok, reply} | {:ok, headers_map} | {:error, error}
Client streaming. A GRPC.Client.Stream
Server streaming. {:ok, Enumerable.t} | {:ok, Enumerable.t, trailers_map} | {:error, error}

Options

:timeout - request timeout. Default is 10s for unary calls and :infinity for client or server streaming calls
:deadline - when the request is timeout, will override timeout
:metadata - a map, your custom metadata
:return_headers - default is false. When it's true, a three elem tuple will be returned with the last elem being a map of headers %{headers: headers, trailers: trailers}(unary) or %{headers: headers}(server streaming)

cancel(stream)

Cancel a stream in a streaming client.

After that, callings to recv/2 will return a CANCEL error.

connect(addr, opts \\ [])

connect(String.t(), Keyword.t()) :: {:ok, GRPC.Channel.t()} | {:error, any()}

Establish a connection with gRPC server and return GRPC.Channel needed for sending requests.

Examples

iex> GRPC.Stub.connect("localhost:50051")
{:ok, channel}

iex> GRPC.Stub.connect("localhost:50051", accepted_compressors: [GRPC.Compressor.Gzip])
{:ok, channel}

iex> GRPC.Stub.connect("/paht/to/unix.sock")
{:ok, channel}

Options

:cred - a GRPC.Credential used to indicate it's a secure connection. An insecure connection will be created without this option.
:adapter - custom client adapter
:interceptors - client interceptors
:codec - client will use this to encode and decode binary message
:compressor - the client will use this to compress requests and decompress responses. If this is set, accepted_compressors will be appended also, so this can be used safely without :accesspted_compressors.
:accepted_compressors - tell servers accepted compressors, this can be used without :compressor
:headers - headers to attach to each request

connect(host, port, opts)

connect(String.t(), binary() | non_neg_integer(), keyword()) ::
  {:ok, GRPC.Channel.t()} | {:error, any()}

disconnect(channel)

disconnect(GRPC.Channel.t()) :: {:ok, GRPC.Channel.t()} | {:error, any()}

Disconnects the adapter and frees any resources the adapter is consuming

end_stream(stream)

end_stream(GRPC.Client.Stream.t()) :: GRPC.Client.Stream.t()

Send END_STREAM frame to end the stream.

The stream will be in half_closed state after this is called.

Examples

iex> stream = GRPC.Stub.send_request(stream, request)
iex> GRPC.Stub.end_stream(stream)

recv(stream, opts \\ [])

recv(GRPC.Client.Stream.t(), keyword() | map()) ::
  {:ok, struct()}
  | {:ok, struct(), map()}
  | {:ok, Enumerable.t()}
  | {:ok, Enumerable.t(), map()}
  | {:error, any()}

Receive replies when requests are streaming.

If the reply is not streaming, a normal reply struct will be returned
If the reply is streaming, a enumerable Stream will be returned. You can use Enum to fetch further replies or Stream to manipulate it. Each item in the Enumerable is a tuple {:ok, reply} or {:error, error}. When :return_headers is true, the last item in the Enumerable will be {:trailers, map}

Examples

# Reply is not streaming
{:ok, reply} = GRPC.Stub.recv(stream)

# Reply is streaming
{:ok, enum} = GRPC.Stub.recv(stream)
replies = Enum.map(enum, fn({:ok, reply}) -> reply end)

Options

:timeout - request timeout
:deadline - when the request is timeout, will override timeout
:return_headers - when true, headers will be returned.

retry_timeout(curr)

send_request(stream, request, opts \\ [])

send_request(GRPC.Client.Stream.t(), struct(), Keyword.t()) ::
  GRPC.Client.Stream.t()

Send streaming requests.

The last request can be sent with :end_stream option, or you can call end_stream/1 to send a frame with END_STREAM flag to end the stream.

Options

:end_stream - indicates it's the last one request, then the stream will be in half_closed state. Default is false.

stream_send(stream, request, opts \\ [])

This function is deprecated. Use send_request/3 instead.

DEPRECATED. Use send_request/3 instead