$ show mtrudel/thousand_island
Thousand Island is a pure Elixir, OTP-based socket server library inspired by Ranch. It provides a supervision tree (Server → Listener + AcceptorPoolSupervisor → AcceptorSupervisor → Acceptor/DynamicSupervisor → Handler) that handles TCP and SSL connections with configurable concurrency, connection draining, and shutdown semantics. The library exposes a clean `ThousandIsland.Handler` behaviour for application-level protocol logic, and a `ThousandIsland.Socket` abstraction that decorates underlying transport sockets with automatic telemetry instrumentation. It emits rich telemetry spans for listeners, acceptors, and individual connections, supports suspend/resume of connection acceptance, and handles transient network errors and file descriptor exhaustion without crashing the acceptor tree. The code is thoroughly tested and free of external dependencies beyond telemetry, making it both a production-ready server and an exemplar of idiomatic Elixir/OTP patterns.
The LLM identified 3 files worth highlighting for reuse:
Provides a complete span-based telemetry helper that can be extracted and reused in any Elixir project needing structured observability. Supports parent-child span hierarchies, automatic duration measurement, exception capture, and typed event emission—all without external dependencies beyond the telemetry library. The design demonstrates careful attention to avoiding duplicate events and preserving caller-supplied timestamps.
Implements a robust accept/2 loop that gracefully handles transient network errors (host unreachable, protocol errors, etc.), file descriptor exhaustion (emfile/enfile with backoff), and connection-spawn failures without crashing the acceptor process. The loop emits telemetry events for each error class, enabling observability while maintaining availability. This pattern is directly applicable to any socket-based server that needs resilience against OS-level resource limits and transient network conditions.
Defines a complete transport behaviour with comprehensive type specifications and a reusable `resolve_options/1` helper that merges required options, defaults, and user-provided options correctly (including handling bare Erlang atoms and Unix domain socket nodelay exclusion). The pattern provides a clean abstraction for swapping TCP, SSL, or custom transports in a socket server—extractable to any project needing transport layer polymorphism.