grpc v0.3.0-alpha GRPC.Stub

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.

Summary

Functions

The actual function invoked when invoking a rpc function

Cancel a stream in a streaming client

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

Send END_STREAM frame to end the stream

Receive replies when requests are streaming

Functions

call(service_mod, rpc, path, channel, request, opts)
call(atom, tuple, String.t, GRPC.Channel, struct | nil, keyword) ::
  {:ok, struct} |
  {:ok, struct, map} |
  GRPC.Client.Stream.t |
  {:ok, Enumerable.t} |
  {:error, GRPC.RPCError.t}

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
  • :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}

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
connect(host, port, opts)
connect(String.t, binary | non_neg_integer, keyword) ::
  {:ok, GRPC.Channel.t} |
  {:error, any}
end_stream(stream)

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} |
  Enumerable.t |
  {: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 Enumrable is a tuple {:ok, reply} or {:error, error}. When :return_headers is true, the last item in the Enumrable 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.
send_request(stream, request, opts \\ [])

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 \\ [])

DEPRECATED. Use send_request/3 instead