996
stars
60
forks
14
watchers
193
prs
37
issues
0
releases
README
!Thousand Island
!Thousand Island
Thousand Island is a modern, pure Elixir socket server, inspired heavily by
ranch. It aims to be easy to understand
and reason about, while also being at least as stable and performant as alternatives.
Informal tests place ranch and Thousand Island at roughly the same level of
performance and overhead; short of synthetic scenarios on the busiest of servers,
they perform equally for all intents and purposes.
Thousand Island is written entirely in Elixir, and is nearly dependency-free (the
only library used is telemetry).
The application strongly embraces OTP design principles, and emphasizes readable,
simple code. The hope is that as much as Thousand Island is capable of backing
the most demanding of services, it is also useful as a simple and approachable
reference for idiomatic OTP design patterns.
Usage
Thousand Island is implemented as a supervision tree which is intended to be hosted
inside a host application, often as a dependency embedded within a higher-level
protocol library such as Bandit. Aside from
supervising the Thousand Island process tree, applications interact with Thousand
Island primarily via the
ThousandIsland.Handler behaviour.
Handlers
The ThousandIsland.Handler behaviour defines the interface that Thousand Island
uses to pass ThousandIsland.Sockets up to the application level; together they
form the primary interface that most applications will have with Thousand Island.
Thousand Island comes with a few simple protocol handlers to serve as examples;
these can be found in the examples
folder of this project. A simple implementation would look like this:
elixir
defmodule Echo do
use ThousandIsland.Handler
@impl ThousandIsland.Handler
def handle_data(data, socket, state) do
ThousandIsland.Socket.send(socket, data)
{:continue, state}
end
end
{:ok, pid} = ThousandIsland.start_link(port: 1234, handler_module: Echo)
For more information, please consult the ThousandIsland.Handler documentation.
Starting a Thousand Island Server
Thousand Island servers exist as a supervision tree, and are started by a call
to
ThousandIsland.start_link/1.
There are a number of options supported; for a complete description, consult the
Thousand Island
docs.
Connection Draining & Shutdown
The ThousandIsland.Server process is just a standard Supervisor, so all the
usual rules regarding shutdown and shutdown timeouts apply. Immediately upon
beginning the shutdown sequence the ThousandIsland.ShutdownListener will cause
the listening socket to shut down, which in turn will cause all of the Acceptor
processes to shut down as well. At this point all that is left in the supervision
tree are several layers of Supervisors and whatever Handler processes were
in progress when shutdown was initiated. At this point, standard Supervisor shutdown
timeout semantics give existing connections a chance to finish things up. Handler
processes trap exit, so they continue running beyond shutdown until th