Thousand Island

Thousand Island does not perform inline logging. Instead, it uses telemetry to emit events for servers, acceptor processes, and individual client connections.

To aid in tracing, you can use the ThousandIsland.Logger module, which provides functions to enable or disable logging for an already running server. This logging is internally backed by telemetry events.

Thousand Island uses a hierarchical supervision tree to manage connections efficiently and reduce contention:

1. Server: The top-level supervisor that coordinates the Listener (which binds to the port) and the AcceptorPoolSupervisor.
2. AcceptorPoolSupervisor: A dynamic supervisor managing a pool of AcceptorSupervisor processes (defaulting to 100).
3. AcceptorSupervisor: Manages an Acceptor (a long-lived process that accepts connections) and a DynamicSupervisor.
4. DynamicSupervisor: Manages the individual Handler processes tied to specific client connections.

This design ensures that Acceptor processes are long-lived and that connection acceptance is decoupled from the creation of handler processes, improving scalability and crash resiliency.

Add thousand_island to your mix.exs dependencies to use it in your Elixir project.

def deps do
  [
    {:thousand_island, "~> 1.0"}
  ]
end

A Thousand Island server is a supervision tree started using ThousandIsland.start_link/1. You must provide a handler_module (which implements ThousandIsland.Handler) and a port in the options list.

{:ok, pid} = ThousandIsland.start_link(port: 1234, handler_module: Echo)

To handle incoming connections, you must implement the ThousandIsland.Handler behaviour in a module. This module defines how the server reacts to data, connection events, and other socket interactions. The server passes ThousandIsland.Socket instances to your handler.

Example of a simple Echo handler:

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

Thousand Island handles shutdown by following standard Elixir Supervisor semantics:

1. Shutdown Initiation: The ThousandIsland.ShutdownListener shuts down the listening socket.
2. Acceptor Shutdown: All ThousandIsland.Acceptor processes shut down immediately.
3. Handler Grace Period: Existing Handler processes continue running. Because Handler processes trap exits, they will continue until they complete or are :brutal_killed after the shutdown_timeout expires.

To ensure connections have enough time to finish, configure the shutdown_timeout option when starting the server.

The ThousandIsland.Socket struct encapsulates a client connection's underlying socket. It provides a high-level interface to read, write, and manipulate connections.

Note for Handler Implementers: If you are building a custom handler based on ThousandIsland.Handler, you typically do not need to call new/3, handshake/1, or upgrade/3 manually, as the handler manages these lifecycle steps for you.

Thousand Island does not perform inline logging. Instead, it uses Telemetry to emit events for servers, acceptor processes, and individual client connections.

• Tracing: Use the ThousandIsland.Logger module to aid in tracing connections at various log levels. Logging can be dynamically enabled/disabled on a running server.
• Telemetry Events: Detailed events (including spans) are available via the ThousandIsland.Telemetry module. This allows for high-performance monitoring without the overhead of constant string formatting and logging.

Thousand Island handles shutdown by shutting down the listening socket and Acceptor processes first. Existing Handler processes (client connections) are allowed to finish within the configured shutdown timeout.

Handler processes trap exit, allowing them to continue running until they complete or are :brutal_killed after the timeout expires. Use the shutdown_timeout option to control this duration (defaults to 15000 ms).