apigenie-generator client elixir (Protobuf)
Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate an Elixir gRPC client on elixir-grpc from a .proto file and
the files it imports.
Usage
apigenie-generator client elixir [...OPTIONS] INPUT_FILE.proto
Description
client elixir generates a gRPC client when its input is a .proto file (an OpenAPI document
gives a Req client, see client elixir). The input is the file
declaring the services; the files it imports are looked up in the directories of --proto-path,
then next to it, and google/protobuf, google/api and google/rpc imports need no files. Only
proto3 files are read.
The generator writes a Mix project (Elixir 1.18 or later) depending on grpc 1.0 with Mint, and
protobuf 0.17. Its code passes mix format --check-formatted, mix compile --warnings-as-errors, mix credo --strict and mix dialyzer. No protoc is needed: the modules of
the messages, services and stubs are those protoc-gen-elixir would write, named the same way (see
server elixir-grpc).
| File | Contents |
|---|---|
lib/proto/<path>.pb.ex |
per .proto file, a module per message, map entry and enum, and the <Service>.Service and <Service>.Stub modules of each service |
lib/<app>.ex |
the root module: connect/2, the types of options and results |
lib/<app>/<service>.ex |
a module per service, with a function per method |
lib/<app>/validation.ex |
<Root>.Validation, the checks of the required fields, when a request has some (since 0.12.0) |
mix.exs, .formatter.exs, .gitignore, README.md |
the project |
{:ok, channel} = CarpetExpressClient.connect("localhost:50051")
{:ok, shipment} =
CarpetExpressClient.ShipmentService.get_shipment(
channel,
%Carpetexpress.V1.GetShipmentRequest{id: "sh_1"},
timeout: 5_000,
metadata: %{"x-tenant" => "acme"}
)
Functions
A method is a function named as GRPC.Stub names it (GetShipment is get_shipment/3):
| Method | Arguments | Returns |
|---|---|---|
| unary | channel, request, options | {:ok, response} or {:error, %GRPC.RPCError{}} |
| server streaming | channel, request, options | {:ok, stream}: an Enumerable of {:ok, message} and {:error, %GRPC.RPCError{}} items; {:error, %GRPC.RPCError{}} for a request without a required field |
| client streaming | channel, Enumerable of requests, options |
{:ok, response} or {:error, %GRPC.RPCError{}}; raises GRPC.RPCError for a request without a required field |
| bidirectional streaming | channel, Enumerable of requests, options |
like server streaming; the requests are sent from a task while the responses arrive, and the responses end early after a request without a required field |
The options are those of GRPC.Stub: :timeout (milliseconds; 10 seconds for unary calls) or
:deadline (a DateTime), :metadata (a map of headers) and :compressor. connect/2 passes
its options to GRPC.Stub.connect/2 with the Mint adapter unless :adapter names another one.
The Stub modules remain available for calls the functions don’t cover, e.g. interleaving the
requests and responses of a bidirectional stream. Deprecated methods are @deprecated.
Required fields
Since 0.12.0, the client checks a request before it sends it. A request without a field marked
(google.api.field_behavior) = REQUIRED isn’t sent: the function returns
{:error, %GRPC.RPCError{}} with the INVALID_ARGUMENT status and a message naming the path of the
first missing field, e.g. shipment.sender is required. The rules of a missing field are those of
server elixir-grpc.
The requests of a client or bidirectional stream are checked one by one as they are sent, so the requests before a failing one have already been sent. The call is then cancelled:
- a client stream raises the
GRPC.RPCErrorin the calling process; - the responses of a bidirectional stream end early, and the sending task logs the error.
The checks are in <Root>.Validation: validate/1 returns :ok or {:error, reason}, check/1
returns :ok or {:error, %GRPC.RPCError{}}, and validate!/1 returns the message or raises the
error. A message without required fields is valid. A service named Validation becomes
<Root>.Validation2 when the module is generated.
Limitations
extendblocks aren’t generated; a warning names the file.
Options
-I, –proto-path DIR
Directory searched for the imported files, like protoc’s --proto_path. Can be repeated. Given
with an OpenAPI input, it is an error.
-c, –config
Path to the configuration file to use. See the “Configuration” section for more information.
–check
Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.
-o, –output
Directory where the project is generated.
–package-name
Name of the Mix application, converted to snake_case (carpet-express-client gives
carpet_express_client and the root module CarpetExpressClient). Defaults to the name of the
output directory.
–package-version
Version of the Mix project; 0.1.0 by default.
-p, –property NAME=VALUE
Sets a generator option (see below), e.g. -p package_prefix=acme.proto. Options given on the
command line take precedence over the configuration file.
Configuration
The options are in the protobuf section of client_elixir; the others concern OpenAPI input.
version: '1.0'
commands:
generate:
client_elixir:
protobuf:
app: carpet_express_client
dev_deps: false
| Option | Type | Default | Description |
|---|---|---|---|
app |
string | name of the output directory | Name of the Mix application (snake_case, the directory under lib/); also set by --package-name. |
namespace |
string | the application in PascalCase | Root module of the client’s modules, e.g. CarpetExpressClient. |
package_prefix |
string | Prepended to the package in the names of the modules of messages, enums and services, like protoc-gen-elixir’s package_prefix. |
|
dev_deps |
boolean | true |
Lists credo and dialyxir as dependencies of mix.exs (only: :dev). |
Verification
The codegen conformance suite runs this target on the Carpet Express Protobuf fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.
This target's support tier is Tier 2. It goes through all three levels before every release, like Tier 1. It doesn't aim to support every feature: a feature of the fixture can stay unsupported, with the reason its manifest gives.
| Results | Level 1 | Level 2 | Level 3 |
|---|---|---|---|
| Release 0.12.0 | ✓ snapshots of proto3; 42 supported, 0 not yet | ✓ pass (Erlang/OTP 29 [erts-17.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]; Mix 1.20.4 (compiled with Erlang/OTP 29)) | ✓ 24 of 24 operations pass (elixir) |
| Development version | ✓ snapshots of proto3; 42 supported, 0 not yet | runs before a release | runs before a release |