# apigenie-generator server elixir-grpc

Source: https://apigenie.pl/docs/reference/generator/server-elixir-grpc
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), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.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 server on [elixir-grpc](https://hexdocs.pm/grpc_server) from a `.proto`
file and the files it imports.

## Usage

```sh
apigenie-generator server elixir-grpc [...OPTIONS] INPUT_FILE
```

## Description

The input is the `.proto` file declaring the services. The files it imports are looked up in the
directories of `--proto-path`, then next to it; `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_server` 1.0 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 are those protoc-gen-elixir would write.

| File | Contents |
| ---- | -------- |
| `lib/proto/<path>.pb.ex` | per `.proto` file, a module per message, map entry and enum (`use Protobuf`), and a `<Service>.Service` module per service (`use GRPC.Service`) |
| `lib/<app>/<service>.ex` | a behaviour per service, with a callback per method |
| `lib/<app>/<service>/server.ex` | the `GRPC.Server` of the service, calling the configured implementation |
| `lib/<app>/validation.ex` | `<Root>.Validation`, the checks of the required fields, when a request has some (since 0.12.0) |
| `lib/<app>/endpoint.ex`, `application.ex` | the endpoint running the servers, and the application starting it |
| `config/config.exs`, `config/runtime.exs` | the port (50051, or `PORT`) |
| `mix.exs`, `.formatter.exs`, `.gitignore`, `README.md` | the project |

```sh
mix deps.get
mix run --no-halt
```

### Messages

Modules are named as protoc-gen-elixir names them: the package camelized segment by segment, then
the message (`carpetexpress.v1.Shipment.Parcel` is `Carpetexpress.V1.Shipment.Parcel`). The
`(elixirpb.file).module_prefix` option of a file, or the `package_prefix` option of the generator,
change the prefix. Fields are declared with `field` and the options protoc-gen-elixir writes
(`repeated`, `proto3_optional`, `json_name`, `map`, `enum`, `oneof`, `packed`, `deprecated`), oneofs
with `oneof`. Comments become `@moduledoc` and `#` comments.

Well-known types are the modules of the `protobuf` package (`Google.Protobuf.Timestamp`, ...), the
types of `google/api`, `google/rpc` and `google/type` those of `googleapis`.

### Services

A service is a behaviour, `<Root>.<Service>`, with a callback per method named as GRPC.Server names
it (`GetShipment` is `get_shipment/2`). Implement it and configure the implementation:

```elixir
config :carpet_express, CarpetExpress.ShipmentService, impl: MyApp.ShipmentService
```

```elixir
defmodule MyApp.ShipmentService do
  @behaviour CarpetExpress.ShipmentService

  @impl true
  def get_shipment(request, _stream), do: MyApp.Shipments.fetch!(request.id)

  @impl true
  def import_shipments(requests, _stream) do
    imported = requests |> Enum.map(&MyApp.Shipments.book/1) |> length()
    %Carpetexpress.V1.ImportShipmentsResponse{imported: imported}
  end

  # ...
end
```

A callback receives the request, or an `Enumerable` of the requests of a client or bidirectional
stream, and the `GRPC.Server.Stream` of the call. It returns the response, or an `Enumerable` of
the responses of a server or bidirectional stream, which the server sends one by one. Raising
`GRPC.RPCError` answers with its status. Methods without an implementation answer UNIMPLEMENTED.

### Required fields

Since 0.12.0, the server checks the fields marked `(google.api.field_behavior) = REQUIRED`, which
protobuf-elixir doesn't know. A request without a required field is answered with
INVALID_ARGUMENT, the status [AIP-203](https://google.aip.dev/203) asks for, and a message naming
the path of the first missing field, e.g. `shipment.sender is required`. The implementation isn't
called.

A field is missing when it holds its default value, because protobuf-elixir can't tell an unset
field from one set to its default:

- a string or bytes field: `nil` or `""`;
- a number: `nil` or `0` (`0.0` for `float` and `double`);
- a bool: anything but `true`;
- an enum: `nil`, `0` or its zero value;
- a message field or a proto3 `optional` field: `nil` (so an `optional` field set to `""` or `0`
  counts as set);
- a repeated field: `[]`, and a map: `%{}`;
- a member of a `oneof`: when the `oneof` holds another member, or none.

The required fields of the messages in a request's fields are checked too, in lists and map values
as well. A message with a `google.protobuf.FieldMask` field is a partial update
([AIP-134](https://google.aip.dev/134)): only its own required fields are checked, not those of
the messages in its fields.

The requests of a client or bidirectional stream are checked one by one as the implementation reads
them, so it may already have handled the earlier ones when a missing field ends the call.

`<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 `GRPC.RPCError`.
A message without required fields is valid. They are there for the implementation's own use too,
e.g. on the messages it builds. A service named `Validation` becomes `<Root>.Validation2` when the
module is generated.

### Limitations

- `extend` blocks (custom options, proto2-style extensions) aren't generated; a warning names the
  file.
- HTTP/JSON transcoding (`google.api.http`) isn't turned on.

## Options

### -I, --proto-path DIR

Directory searched for the imported files, like protoc's `--proto_path`. Can be repeated.

### -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` gives `carpet_express`
and the root module `CarpetExpress`). 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 dev_deps=false`. Options given on the command line
take precedence over the configuration file.

## Configuration

```yaml
version: '1.0'
commands:
  generate:
    server_elixir_grpc:
      app: carpet_express
      package_prefix: carpet_express.proto
```

| 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 modules of the application (behaviours, servers, endpoint), e.g. `CarpetExpress`. |
| `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)) | ✓ 31 of 31 operations pass (elixir) |
| Development version | ✓ snapshots of proto3; 42 supported, 0 not yet | runs before a release | runs before a release |
