Home
The interface for grpc_client.
This module contains the functions use a gRPC service from Erlang.
See the Readme in the root folder of the repository for a reference to a more general (tutorial-style) introduction.
client_stream() = pid()
compression_method() = none | gzip
connection() = grpc_client_connection:connection()
connection_option() = verify_server_opt() | server_host_override_opt() | http2_client_opt() | {http2_options, [http2_option()]}
error_response(Type) = {error, #{error_type := error_type(), http_status => integer(), grpc_status => integer(), status_message => binary(), headers => metadata(), result => Type, trailers => grpc:metadata()}}
error_type() = client | timeout | http | grpc
get_response() = rcv_response() | empty
http2_client_opt() = {http2_client, module()}
A module that implements an HTPP/2 client (with a specific API). By default 'http2_client' will be used. As an alternative 'grpc_client_chatterbox_adapter' can be used, which provides an interface to the chatterbox http/2 client, or any other HTTP/2 client implementation with the right API.
http2_option() = term()
Passed on to the HTTP/2 client. See the documentation of 'http2_client' for the options that can be specified for the default HTTP2/2 client.
metadata() = #{metadata_key() => metadata_value()}
metadata_key() = binary()
metadata_value() = binary()
ok_response(Type) = {ok, #{result := Type, status_message := binary(), http_status := 200, grpc_status := 0, headers := metadata(), trailers := metadata()}}
rcv_response() = {data, #{}} | {headers, metadata()} | eof | {error, term()}
server_host_override_opt() = {server_host_override, string()}
If the 'verify_server_identity' option is set, check the subject of the server certificate against this name (rather than against the host name).
stream_option() = {metadata, metadata()} | {compression, compression_method()} | {http2_options, [term()]}
unary_response(Type) = ok_response(Type) | error_response(Type)
verify_server_opt() = {verify_server_identity, boolean()}
If true (and if the transport is ssl), the client will verify that the subject of the server certificate matches with the domain of the server (use the 'server_host_override' to check against another name).
| compile/1 | Equivalent to compile(FileName, []). |
| compile/2 | Compile a .proto file to generate client stubs and a module to encode and decode the protobuf messages. |
| connect/3 | Equivalent to connect(Transport, Host, Port, []). |
| connect/4 | Start a connection to a gRPC server. |
| get/1 | Get a message from the stream, if there is one in the queue. |
| new_stream/4 | Equivalent to new_stream(Connection, Service, Rpc, DecoderModule, []). |
| new_stream/5 | Create a new stream to start a new RPC. |
| ping/2 | Send a PING request. |
| rcv/1 | Equivalent to rcv(Stream, infinity). |
| rcv/2 | Receive a message from the server. |
| send/2 | Send a message from the client to the server. |
| send_last/2 | Send a message to server and mark it as the last message on the stream. |
| stop_connection/1 | Stop a connection and clean up. |
| stop_stream/1 | Equivalent to stop_stream(Stream, 0). |
| stop_stream/2 | Stops a stream. |
| unary/6 | Call a unary rpc in one go. |
compile(FileName::string()) -> ok
Equivalent to compile(FileName, []).
compile(FileName::string(), Options::gpb_compile:opts()) -> ok
Compile a .proto file to generate client stubs and a module to encode and decode the protobuf messages.
Refer to gpb for the options. grpc_client will always use the option 'maps' (so that the protobuf messages are translated to and from maps) and the option '{i, "."}' (so that .proto files in the current working directory will be found).
connect(Transport::tcp | ssl, Host::string(), Port::integer()) -> {ok, connection()} | {error, term()}
Equivalent to connect(Transport, Host, Port, []).
connect(Transport::tcp | ssl, Host::string(), Port::integer(), Options::[connection_option()]) -> {ok, connection()}
Start a connection to a gRPC server.
If 'verify_server_identity' is true (and Transport == ssl), the client will check that the subject of the certificate received from the server is identical to Host.
If it is known that the server returns a certificate with another subject than the host name, the 'server_host_override' option can be used to specify that other subject.
The transport options will be passed to the selected Transport when establishing the connection.
The option {'http2_client', module()} enables the selection of an http2 client. The default is http2_client, as an alternative it is possible to select 'grpc_client_chatterbox_adapter', which implements an adapter for the chatterbox http/2 client.
get(Stream::client_stream()) -> get_response()
Get a message from the stream, if there is one in the queue. If not return 'empty'. This is a non-blocking call.
Returns 'eof' after the last message from the server has been read.
new_stream(Connection::connection(), Service::atom(), Rpc::atom(), DecoderModule::module()) -> {ok, client_stream()}
Equivalent to new_stream(Connection, Service, Rpc, DecoderModule, []).
new_stream(Connection::connection(), Service::atom(), Rpc::atom(), DecoderModule::module(), Options::[stream_option()]) -> {ok, client_stream()}
Create a new stream to start a new RPC.
ping(Connection::connection(), Timeout::timeout()) -> {ok, RoundTripTime::integer()} | {error, term()}
Send a PING request.
rcv(Stream::client_stream()) -> rcv_response()
Equivalent to rcv(Stream, infinity).
rcv(Stream::client_stream(), Timeout::timeout()) -> rcv_response()
Receive a message from the server. This is a blocking call, it returns when a message has been received or after Timeout. Timeout is in milliseconds.
Returns 'eof' after the last message from the server has been read.
send(Stream::client_stream(), Msg::#{}) -> ok
Send a message from the client to the server.
send_last(Stream::client_stream(), Msg::#{}) -> ok
Send a message to server and mark it as the last message on the stream. For simple RPC and client-streaming RPCs that will trigger the response from the server.
stop_connection(Connection::connection()) -> ok
Stop a connection and clean up.
stop_stream(Stream::client_stream()) -> ok
Equivalent to stop_stream(Stream, 0).
stop_stream(Stream::client_stream(), ErrorCode::integer()) -> ok
Stops a stream. Depending on the state of the connection a 'RST_STREAM' frame may be sent to the server with the provided Errorcode (it should be a HTTP/2 error code, see RFC7540).
unary(Connection::connection(), Message::#{}, Service::atom(), Rpc::atom(), Decoder::module(), Options::[stream_option() | {timeout, timeout()}]) -> unary_response(#{})
Call a unary rpc in one go.
Set up a stream, receive headers, message and trailers, stop the stream and assemble a response. This is a blocking function.
Generated by EDoc, Aug 21 2017, 16:32:59.