Twirp v0.4.1 Twirp View Source

Twirp provides an elixir implementation of the twirp rpc framework developed by Twitch. The protocol defines semantics for routing and serialization of RPCs based on protobufs.

Example

The canonical Twirp example is a Haberdasher service. Here's the protobuf description for the service.

syntax = "proto3";

package example;

// Haberdasher service makes hats for clients.
service Haberdasher {
  // MakeHat produces a hat of mysterious, randomly-selected color!
  rpc MakeHat(Size) returns (Hat);
}

// Size of a Hat, in inches.
message Size {
  int32 inches = 1; // must be > 0
}

// A Hat is a piece of headwear made by a Haberdasher.
message Hat {
  int32 inches = 1;
  string color = 2; // anything but "invisible"
  string name = 3; // i.e. "bowler"
}

We'll assume for now that this proto file lives in priv/protos/service.proto

Code generation

We can now use protoc to generate the files we need. You can run this command from the root directory of your project.

$ protoc --proto_path=./priv/protos --elixir_out=./lib/example --twirp_elixir_out=./lib/example ./priv/protos/service.proto

After running this command there should be 2 files located in lib/example.

The message definitions:

defmodule Example.Size do
  @moduledoc false
  use Protobuf, syntax: :proto3

  @type t :: %__MODULE__{
          inches: integer
        }

  defstruct [:inches]

  field :inches, 1, type: :int32
end

defmodule Example.Hat do
  @moduledoc false
  use Protobuf, syntax: :proto3

  @type t :: %__MODULE__{
          inches: integer,
          color: String.t(),
          name: String.t()
        }
  defstruct [:inches, :color, :name]

  field :inches, 1, type: :int32
  field :color, 2, type: :string
  field :name, 3, type: :string
end

The service and client definition:

defmodule Example.HaberdasherService do
  @moduledoc false
  use Twirp.Service

  package "example"
  service "Haberdasher"

  rpc :MakeHat, Example.Size, Example.Hat, :make_hat
end

defmodule Example.HaberdasherClient do
  @moduledoc false
  use Twirp.Client, service: Example.HaberdasherService
end

Implementing the server

Now that we've generated the service definition we can implement a "handler" module that will implement each "method".

defmodule Example.HaberdasherHandler do
  @colors ~w|white black brown red blue|
  @names ["bowler", "baseball cap", "top hat", "derby"]

  def make_hat(_ctx, size) do
    if size <= 0 do
      Twirp.Error.invalid_argument("I can't make a hat that small!")
    else
      %Haberdasher.Hat{
        inches: size.inches,
        color: Enum.random(@colors),
        name: Enum.random(@names)
      }
    end
  end
end

Separating the service and handler like this may seem a little odd but there are good reasons to do this. The most important is that it allows the service to be autogenerated again in the future. The second reason is that it allows us to easily mock service implementations for testing.

Running the server

To serve traffic Twirp provides a Plug. We use this plug to attach our service definition with our handler.

defmodule Example.Router do
  use Plug.Router

  plug Twirp.Plug,
    service: Haberdasher.HatMakerService,
    handler: Haberdasher.HatMakerHandler
end
defmodule Example.Application do
  use Application

  def start(_type, _args) do
    children = [
      Plug.Cowboy.child_spec(scheme: :http, plug: Example.Router, options: [port: 4040]),
    ]

    opts = [strategy: :one_for_one, name: Example.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

If you start your application your plug will now be available on port 4040.

Using the client

Client definitions are generated alongside the service definition. This allows you to generate clients for your services in other applications. You can make RPC calls like so:

defmodule AnotherService.GetHats do
  alias Example.HaberdasherClient, as: Client
  alias Example.{Size, Hat}

  def make_a_hat(inches) do
    case Client.make_hat(Size.new(inches: inches)) do
      {:ok, %Hat{}=hat} ->
        hat

      {:error, %Twirp.Error{msg: msg}} ->
        Logger.error(msg)
    end
  end
end