apigenie-generator server elixir-grpc

Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification

Generate an Elixir gRPC server on elixir-grpc from a .proto file and the files it imports.

Usage

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
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:

config :carpet_express, CarpetExpress.ShipmentService, impl: MyApp.ShipmentService
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 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): 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.

-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

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 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))✓ 31 of 31 operations pass (elixir)
Development version✓ snapshots of proto3; 42 supported, 0 not yetruns before a releaseruns before a release
Was this helpful?