EdmondFrank / grpc

An Elixir implementation of gRPC

gRPC Elixir

WARNING: Be careful to use it in production! Test and benchmark in advance.

An Elixir implementation of gRPC. This is the forked version of https://github.com/elixir-grpc/grpc. Aim goals:

• Make dependencies up-to-date.
• Rely on https://github.com/elixir-protobuf/protobuf v0.10 and so on.
• No override dependencies. (cowlib and grpc_gun for example).

Installation

Currently, this package doesn't publish on hex.pm yet. You can install it by using github repo syntax:

def deps do
  [
    {:grpc, github: "wingyplus/grpc"},
  ]
end

Usage

1. Generate Elixir code from proto file as protobuf-elixir shows (especially the gRPC Support section).
2. Implement the server side code like below and remember to return the expected message types.

defmodule Helloworld.Greeter.Server do
  use GRPC.Server, service: Helloworld.Greeter.Service

  @spec say_hello(Helloworld.HelloRequest.t, GRPC.Server.Stream.t) :: Helloworld.HelloReply.t
  def say_hello(request, _stream) do
    Helloworld.HelloReply.new(message: "Hello #{request.name}")
  end
end

3. Start the server

You can start the gRPC server as a supervised process. First, add GRPC.Server.Supervisor to your supervision tree.

# Define your endpoint
defmodule Helloworld.Endpoint do
  use GRPC.Endpoint

  intercept GRPC.Logger.Server
  run Helloworld.Greeter.Server
end

# In the start function of your Application
defmodule HelloworldApp do
  use Application
  def start(_type, _args) do
    children = [
      # ...
      supervisor(GRPC.Server.Supervisor, [{Helloworld.Endpoint, 50051}])
    ]

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

Then start it when starting your application:

# config.exs
config :grpc, start_server: true

# test.exs
config :grpc, start_server: false

$ iex -S mix

or run grpc.server using a mix task

$ mix grpc.server

4. Call rpc:

iex> {:ok, channel} = GRPC.Stub.connect("localhost:50051")
iex> request = Helloworld.HelloRequest.new(name: "grpc-elixir")
iex> {:ok, reply} = channel |> Helloworld.Greeter.Stub.say_hello(request)

# With interceptors
iex> {:ok, channel} = GRPC.Stub.connect("localhost:50051", interceptors: [GRPC.Logger.Client])
...

Check examples and interop(Interoperability Test) for some examples.

TODO

• Unary RPC
• Server streaming RPC
• Client streaming RPC
• Bidirectional streaming RPC
• Helloworld and RouteGuide examples
• Doc and more tests
• Authentication with TLS
• Improve code generation from protos (protobuf-elixir #8)
• Timeout for unary calls
• Errors handling
• Benchmarking
• Logging
• Interceptors(See GRPC.Endpoint)
• Connection Backoff
• Data compression
• Support other encoding(other than protobuf)

Benchmark

1. Simple benchmark by using ghz

2. Benchmark followed by official spec

OTP Support

This library support only latest 3 versions. For example, if current OTP version is 25, this library will support only versions 23, 24 and 25.

Sponsors

This project is being sponsored by Tubi. Thank you!

Contributing

You contributions are welcome!

Please open issues if you have questions, problems and ideas. You can create pull requests directly if you want to fix little bugs, add small features and so on. But you'd better use issues first if you want to add a big feature or change a lot of code.