WebsockexNova
View SourceA robust, highly extensible WebSocket client library for Elixir with elegant abstractions for building specialized WebSocket clients.
This library is based on the excellent Websockex library by Azolo and has been heavily extended with additional capabilities including behavior-based extensibility, adapter patterns, Gun transport integration, automatic reconnection, subscription management, rate limiting, and more.
Features
- Behavior-Based Architecture: Easily extendable through behavior interfaces
- Adapter Pattern: Customize specific aspects of WebSocket communication
- Default Implementations: Sensible defaults provided for all behaviors
- Gun Integration: Uses the battle-tested Gun library as the transport layer
- Client Macro: Simplify creation of service-specific WebSocket clients
- Adapter Macro: Build service-specific adapters with minimal boilerplate
- Rate Limiting: Built-in rate limiting capabilities
- Observability: Rich telemetry and logging support
Installation
Add websockex_nova
to your list of dependencies in mix.exs
:
def deps do
[
{:websockex_nova, "~> 0.1.0"}
]
end
Usage
Basic Usage
# Connect to a WebSocket server
{:ok, conn} = WebsockexNova.Client.connect(WebsockexNova.Defaults.DefaultAdapter, %{
host: "echo.websocket.org",
port: 443,
path: "/",
transport: :tls
})
# Send a message
{:ok, response} = WebsockexNova.Client.send_text(conn, "Hello, WebSocket!")
# Close the connection
WebsockexNova.Client.close(conn)
Using ClientMacro
Create service-specific clients with minimal boilerplate using WebsockexNova.ClientMacro
:
defmodule MyApp.DeribitClient do
use WebsockexNova.ClientMacro, adapter: MyApp.DeribitAdapter
# Add domain-specific methods:
def subscribe_to_trades(conn, instrument, opts \\ nil) do
channel = "trades.#{instrument}.raw"
subscribe(conn, channel, opts)
end
def subscribe_to_ticker(conn, instrument, opts \\ nil) do
channel = "ticker.#{instrument}.raw"
subscribe(conn, channel, opts)
end
end
# Usage
{:ok, conn} = MyApp.DeribitClient.connect()
{:ok, _} = MyApp.DeribitClient.subscribe_to_trades(conn, "BTC-PERPETUAL")
Using AdapterMacro
Create service-specific adapters with minimal boilerplate using WebsockexNova.Adapter
:
defmodule MyApp.DeribitAdapter do
use WebsockexNova.Adapter
# Override only what you need:
@impl WebsockexNova.Behaviors.ConnectionHandler
def connection_info(opts) do
defaults = %{
host: "www.deribit.com",
port: 443,
path: "/ws/api/v2",
transport: :tls
}
{:ok, Map.merge(defaults, opts)}
end
@impl WebsockexNova.Behaviors.MessageHandler
def handle_message(message, state) do
# Custom message handling...
{:ok, decoded_message, updated_state}
end
end
Documentation
Comprehensive documentation is available in the docs/
directory:
- Architecture Overview:
docs/architecture.md
- Client Macro Guide:
docs/client_macro.md
- Implementation Plan:
docs/plan.md
License
This project is licensed under the MIT License - see the LICENSE file for details.