paulcockrell/ace

Serve internet applications from TCP or TLS(ssl) endpoints.

Ace

Easy TCP and TLS(ssl) servers.

• Install from hex
• Documentation on hexdoc

For a HTTP webserver see Ace.HTTP.

Application

An Ace.Application module defines a servers behaviour.

defmodule MyApp do
  # MyApp is a server application.
  use Ace.Application

  # Handle client opening a new connection.
  def handle_connect(_connection, state = {:greeting, greeting}) do
    {:send, greeting, state}
  end

  # React to a message that was sent from the client.
  def handle_packet(inbound, state) do
    {:send, "ECHO: #{String.strip(inbound)}\n", state}
  end

  # React to a message recieved from the application.
  def handle_info({:notify, notification}, state) do
    {:send, "#{notification}\n", state}
  end

  # Response to the client closing the connection.
  def handle_disconnect(_reason, _state) do
    IO.puts("Socket connection closed")
  end

  # Define start_link to `MyApp` can be added to supervision tree.
  def start_link(greeting, options \\ []) do
    config = {:greeting, greeting}
    app = {__MODULE__, config}
    Ace.TCP.start_link(app, options)
  end
end

Quick start

From the console, start mix.

iex -S mix

In the iex console, start a TCP endpoint.

{:ok, pid} = MyApp.start_link("WELCOME", port: 8080)

Connect

Use telnet to communicate with the server.

telnet localhost 8080

Wihin the telnet terminal.

# once connected
WELCOME
hi
ECHO: hi

In the iex session.

send(server, {:notify, "BOO!"})

back in telnet terminal.

BOO!

Embedded endpoints

It is not a good idea to start unsupervised processes. Ace endpoints should be added to you application supervision tree.

@tcp_options [
  port: 8080
]

@tls_options [
  port: 8443,
  certificate: "path/to/cert.pm",
  certificate_key: "path/to/key.pm"
]

children = [
  worker(Ace.TCP, [{MyApp, {:greeting, "WELCOME"}}, @tcp_options])
  worker(Ace.TLS, [{MyApp, {:greeting, "WELCOME"}}, @tls_options])
]
Supervisor.start_link(children, opts)

See "01 Quote of the Day" for an example setup.

Ace 0.1 (TCP echo)

The simplest TCP echo server that works. Checkout the source of version 0.1.0. The change log documents all enhancements to this prototype server.

Contributing

Before opening a pull request, please open an issue first.

Once we've decided how to move forward with a pull request:

$ git clone [email protected]:CrowdHailer/Ace.git
$ cd Ace
$ mix deps.get
$ mix test
$ mix dialyzer.plt
$ mix dialyzer

Once you've made your additions, mix test passes and mix dialyzer reports no warnings, go ahead and open a PR!