# apigenie-generator client elixir (Protobuf)

Source: https://apigenie.pl/docs/reference/generator/client-elixir-protobuf
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 2](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · [Verification](#verification)

Generate an Elixir gRPC client on [elixir-grpc](https://hexdocs.pm/grpc) from a `.proto` file and
the files it imports.

## Usage

```sh
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](/docs/reference/generator/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](/docs/reference/generator/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 |

```elixir
{: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](/docs/reference/generator/server-elixir-grpc#required-fields).

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](/docs/reference/generator#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.

```yaml
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](/docs/reference/generator#conformance-checks) 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](/docs/reference/generator/conformance#protobuf).

This target's support tier is [Tier 2](/docs/reference/generator/conformance#tiers). 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 |
