Home

Awesome

Ace

HTTP web server and client, supports http1 and http2

Hex pm Build Status License

See Raxx.Kit for a project generator that helps you set up a web project based on Raxx/Ace.

Get started

Hello, World!

defmodule MyApp do
  use Ace.HTTP.Service, port: 8080, cleartext: true
  use Raxx.SimpleServer

  @impl Raxx.SimpleServer
  def handle_request(%{method: :GET, path: []}, %{greeting: greeting}) do
    response(:ok)
    |> set_header("content-type", "text/plain")
    |> set_body("#{greeting}, World!")
  end
end

The arguments given to use Ace.HTTP.Service are default values when starting the service.

Start the service

config = %{greeting: "Hello"}

MyApp.start_link(config, port: 1234)

Here the default port value has been overridden at startup

Raxx

Ace implements the Raxx HTTP interface. This allows applications to be built with any components from the Raxx ecosystem.

Raxx has tooling for streaming, server-push, routing, api documentation and more. See documentation for details.

The correct version of raxx is included with ace, raxx does not need to be added as a dependency.

TLS/SSL

If a service is started without the cleartext it will start using TLS. This requires a certificate and key.

config = %{greeting: "Hello"}
options = [port: 8443, certfile: "path/to/certificate", keyfile: "path/to/key"]

MyApp.start_link(application, options)

TLS is required to serve content via HTTP/2.

Supervising services

The normal way to run services is as part of a projects supervision tree. When starting a new project use the --sup flag.

mix new my_app --sup

Add the services to be supervised in the application file lib/my_app/application.ex.

defmodule MyApp.Application do
  @moduledoc false

  use Application

  def start(_type, _args) do
    import Supervisor.Spec, warn: false

    children = [
      {MyApp, [%{greeting: "Hello"}]}
    ]

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

Start project using iex -S mix and visit http://localhost:8080.

Testing

mix test --include ci:true

Will run h2spec as one of the tests.

If the h2spec is not specified in the environment variable $H2SPEC_PATH or on the $PATH, it will be downloaded into test/support/h2spec/ and executed.

Alternative HTTP servers

Other servers you can use for Elixir/erlang applications are Cowboy and Elli.

Of the three Cowboy is the most widely used. Both Elli and Cowboy are written in erlang, Ace is written in Elixir.

Elixir HTTP Benchmark - Ace vs Cowboy