livery_grpc (livery_grpc v0.1.0)

View Source

Public facade: run a gRPC server on a dedicated livery HTTP/2 listener.

A gRPC server is its own listener, serving only gRPC. The dispatcher owns every stream, routing POST /package.Service/Method to the Erlang callback module bound to that service. One listener per server keeps gRPC framing and routing separate from any REST surface.

{ok, Server} = livery_grpc:start_server(#{
    port     => 50051,
    services => [
        #{proto => helloworld_pb, service => 'Greeter', handler => my_greeter}
    ]
}),
%% my_greeter implements one Erlang function per RPC, named in snake_case:
%%   say_hello(#{name := Name}, _Ctx) -> {ok, #{message => <<"hi ", Name/binary>>}}.
ok = livery_grpc:stop_server(Server).

The transport defaults to tcp (h2c); pass transport => ssl with cert and key to serve over TLS with ALPN-negotiated h2. Each service binds a handler module; its callbacks receive the decoded request message and a context (see livery_grpc_server:ctx/0).

Summary

Types

server()
server_opts()
service_spec()

Functions

server_port(Server)

The TCP port a running server is bound to.

start_server(Opts)

Start a gRPC server on its own h2 listener.

stop_server(Server)

Stop a gRPC server.

Types

server()

-type server() :: pid().

server_opts()

-type server_opts() ::
          #{services := [service_spec()],
            port => inet:port_number(),
            transport => tcp | ssl,
            cert => binary() | string(),
            key => binary() | string(),
            cacerts => [binary()],
            ssl_opts => [ssl:tls_server_option()],
            acceptors => pos_integer(),
            compression => livery_grpc_compression:algorithm(),
            reflection => boolean(),
            middleware => livery_middleware:stack(),
            config => term()}.

service_spec()

-type service_spec() :: #{proto := module(), service := atom(), handler := module()}.

Functions

server_port(Server)

-spec server_port(server()) -> inet:port_number().

The TCP port a running server is bound to.

start_server(Opts)

-spec start_server(server_opts()) -> {ok, server()} | {error, term()}.

Start a gRPC server on its own h2 listener.

services is required: a list of #{proto, service, handler} bindings. Returns the listener handle for stop_server/1 and server_port/1.

stop_server(Server)

-spec stop_server(server()) -> ok.

Stop a gRPC server.