Ace
Easy TCP and TLS(ssl) servers.
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 git@github.com: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!