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.RPCError in 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

  • extend blocks 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.

ResultsLevel 1Level 2Level 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 yetruns before a releaseruns before a release
Was this helpful?