Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/CrowdHailer/Ace

HTTP web server and client, supports http1 and http2
https://github.com/CrowdHailer/Ace

elixir elixir-lang erlang h2spec http http2 https tls web

Last synced: 7 days ago
JSON representation

HTTP web server and client, supports http1 and http2

Awesome Lists containing this project

README 

        
# Ace



**HTTP web server and client, supports http1 and http2**



[![Hex pm](http://img.shields.io/hexpm/v/ace.svg?style=flat)](https://hex.pm/packages/ace)

[![Build Status](https://secure.travis-ci.org/CrowdHailer/Ace.svg?branch=master

"Build Status")](https://travis-ci.org/CrowdHailer/Ace)

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)



- [Install from Hex](https://hex.pm/packages/ace)

- [Documentation available on hexdoc](https://hexdocs.pm/ace)

- [Discuss on slack](https://elixir-lang.slack.com/messages/C56H3TBH8/)



See [Raxx.Kit](https://github.com/CrowdHailer/raxx_kit) for a project generator that helps you set up

a web project based on [Raxx](https://github.com/CrowdHailer/raxx)/[Ace](https://github.com/CrowdHailer/Ace).



## Get started



#### Hello, World!

```elixir

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



```elixir

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](https://hexdocs.pm/raxx/readme.html) 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.



```elixir

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.



```sh

mix new my_app --sup

```



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



```elixir

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](http://localhost:8080).



## Testing



```

mix test --include ci:true

```



Will run [h2spec](https://github.com/summerwind/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](https://github.com/ninenines/cowboy) and [Elli](https://github.com/elli-lib/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](http://www.devstopfix.com/posts/2019/elixir-http-benchmark/)