ZenWebsocket

A robust WebSocket client library for Elixir, built on Gun transport for production-grade reliability. Designed for financial APIs with automatic reconnection, comprehensive error handling, and real-world testing.

Features

Gun Transport - Battle-tested HTTP/2 and WebSocket client
Automatic Reconnection - Exponential backoff with state preservation
Financial-Grade Reliability - Built for high-frequency trading systems
Platform Adapters - Ready-to-use Deribit integration, extensible for others
Real API Testing - No mocks, tested against live systems
Simple API - Only 5 public functions to learn
Comprehensive Error Handling - Categorized errors with recovery strategies
Rate Limiting - Configurable token bucket algorithm
JSON-RPC 2.0 - Full protocol support with correlation tracking

Installation

Add zen_websocket to your dependencies in mix.exs:

def deps do
  [
    {:zen_websocket, "~> 0.1"}
  ]
end

Quick Start

Basic Connection

# Connect to a WebSocket endpoint
{:ok, client} = ZenWebsocket.Client.connect("wss://echo.websocket.org", [
  timeout: 5000,
  heartbeat_interval: 30000
])

# Send a message
{:ok, _} = ZenWebsocket.Client.send_message(client, "Hello, WebSocket!")

# Receive messages in your process
receive do
  {:websocket_message, message} -> IO.inspect(message)
end

# Close the connection
:ok = ZenWebsocket.Client.close(client)

For more detailed examples, see our working examples with fully tested implementations:

Basic Usage - Connection management and messaging
Error Handling - Robust error recovery patterns
JSON-RPC Client - JSON-RPC 2.0 protocol usage
Subscription Management - Channel subscription patterns

See the Examples Guide for complete code samples and usage patterns.

Deribit Integration

# Configure Deribit credentials
config = %{
  client_id: System.get_env("DERIBIT_CLIENT_ID"),
  client_secret: System.get_env("DERIBIT_CLIENT_SECRET"),
  test_mode: true
}

# Start the supervised adapter
{:ok, adapter} = ZenWebsocket.Examples.DeribitGenServerAdapter.start_link(config)

# Subscribe to market data
{:ok, _} = ZenWebsocket.Examples.DeribitGenServerAdapter.subscribe(
  adapter,
  ["book.BTC-PERPETUAL.raw", "trades.BTC-PERPETUAL.raw"]
)

# Send a custom JSON-RPC request (e.g., place an order)
{:ok, response} = ZenWebsocket.Examples.DeribitGenServerAdapter.send_request(
  adapter,
  "private/buy",
  %{
    instrument_name: "BTC-PERPETUAL",
    amount: 10,
    type: "limit",
    price: 50000
  }
)

Architecture

ZenWebsocket follows a modular architecture with clear separation of concerns:

ZenWebsocket.Client         # Main client interface
ZenWebsocket.Config         # Configuration management
ZenWebsocket.Frame          # WebSocket frame handling
ZenWebsocket.Reconnection   # Automatic reconnection logic
ZenWebsocket.MessageHandler # Message parsing and routing
ZenWebsocket.ErrorHandler   # Error categorization
ZenWebsocket.RateLimiter   # API rate limiting
ZenWebsocket.JsonRpc       # JSON-RPC 2.0 protocol

Platform Integration

The library includes a complete Deribit adapter as a reference implementation. To integrate with other platforms:

Create an adapter module following the Deribit pattern
Implement platform-specific authentication
Handle platform message formats
Add comprehensive tests against the real API

See lib/zen_websocket/examples/deribit_adapter.ex for a complete example.

Configuration Options

Option	Description	Default
`url`	WebSocket endpoint URL	required
`headers`	Custom headers for connection	`[]`
`timeout`	Connection timeout in milliseconds	`5000`
`retry_count`	Maximum reconnection attempts	`3`
`retry_delay`	Initial retry delay in milliseconds	`1000`
`heartbeat_interval`	Ping interval in milliseconds	`30000`
`reconnect_on_error`	Enable automatic reconnection	`true`
`debug`	Enable verbose debug logging	`false`

Debug Logging

Debug logging is disabled by default to keep library output quiet. Enable it for troubleshooting connection issues:

# Enable debug logging for troubleshooting
{:ok, client} = ZenWebsocket.Client.connect("wss://example.com", debug: true)

When enabled, you'll see detailed logs for connection establishment, WebSocket upgrades, frame handling, heartbeats, and reconnection attempts.

Testing Philosophy

This library uses real API testing exclusively. No mocks or stubs - every test runs against actual WebSocket endpoints or local test servers. This ensures the library handles real-world conditions including network latency, connection drops, and API quirks.

# Run all tests
mix test

# Run with coverage
mix test --cover

# Run quality checks
mix check

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Write tests using real APIs (no mocks)
Ensure all quality checks pass (mix check)
Commit your changes
Push to the branch
Open a Pull Request

Development Commands

mix compile           # Compile the project
mix test             # Run test suite
mix lint             # Run Credo analysis
mix typecheck        # Run Dialyzer
mix docs             # Generate documentation
mix check            # Run all quality checks

License

This project is licensed under the MIT License.

Acknowledgments

Built for the Elixir community by ZenHive.