WebsockexAdapter Examples
View SourceThis guide provides practical examples of using WebsockexAdapter in various scenarios. All examples are fully tested and available in the lib/websockex_adapter/examples/
directory.
Working Examples
All examples have comprehensive test coverage and demonstrate real-world usage patterns:
Core Examples (in examples/docs/
)
- Basic Usage - Basic connection and messaging patterns (tests)
- Error Handling - Robust error recovery patterns (tests)
- JSON-RPC Client - JSON-RPC 2.0 protocol usage
- Subscription Management - Channel subscription patterns (tests)
Platform Adapters
- Platform Adapter Template - Template for creating platform-specific adapters (see platform_adapter_template.ex)
- Deribit Integration - Complete examples moved to market_maker project for better separation of concerns
Architecture Examples
- Adapter Supervisor - Fault-tolerant supervision patterns
- Supervised Client - Client supervision with restart strategies
- Usage Patterns - Common WebSocket patterns and best practices
Running the Examples
Basic Connection Example
# Run the basic usage example test
mix test test/websockex_adapter/examples/basic_usage_test.exs
# Or run it in IEx
iex -S mix
# In IEx, try the basic usage example
alias WebsockexAdapter.Examples.Docs.BasicUsage
# Echo server example
{:ok, result} = BasicUsage.echo_example()
# Custom headers example
{:ok, client} = BasicUsage.connect_with_headers("wss://echo.websocket.org", "Bearer token123")
Platform Integration Example
For comprehensive platform integration examples (including Deribit), see the market_maker
project which demonstrates:
- Authentication flows
- Supervised adapters with automatic recovery
- Market data subscriptions
- Trading operations
- Error handling and reconnection
The WebsockexAdapter library provides the infrastructure, while platform-specific business logic resides in dedicated projects.
Example Patterns
Error Recovery Pattern
See error_handling.ex for a complete implementation:
alias WebsockexAdapter.Examples.Docs.ErrorHandling
# Start a resilient client
{:ok, client} = ErrorHandling.start_link("wss://echo.websocket.org")
# The client automatically handles:
# - Connection failures with exponential backoff
# - Message send failures with retries
# - WebSocket errors with appropriate recovery
Subscription Management Pattern
See subscription_management.ex for implementation:
alias WebsockexAdapter.Examples.Docs.SubscriptionManagement
# Start a client with managed subscriptions
{:ok, manager} = SubscriptionManagement.start_link("wss://test.deribit.com/ws/api/v2")
# Add subscriptions (automatically restored on reconnection)
:ok = SubscriptionManagement.add_subscription(manager, "ticker.BTC-PERPETUAL.raw")
:ok = SubscriptionManagement.add_subscription(manager, "book.ETH-PERPETUAL.100ms")
# List active subscriptions
subscriptions = SubscriptionManagement.list_subscriptions(manager)
JSON-RPC Pattern
See json_rpc_client.ex for implementation:
alias WebsockexAdapter.Examples.Docs.JsonRpcClient
# Start a JSON-RPC client
{:ok, client} = JsonRpcClient.start_link("wss://api.example.com/jsonrpc")
# Make RPC calls with automatic correlation
{:ok, result} = JsonRpcClient.call(client, "get_account_info", %{account_id: "123"})
{:ok, balance} = JsonRpcClient.call(client, "get_balance", %{currency: "USD"})
Testing Your Implementation
All examples come with comprehensive tests. To run them:
# Run all example tests
mix test test/websockex_adapter/examples/
# Run specific example test
mix test test/websockex_adapter/examples/basic_usage_test.exs
# Run with coverage
mix test --cover test/websockex_adapter/examples/
Best Practices
- Use GenServers for Stateful Connections: See
DeribitGenServerAdapter
for a production-ready pattern - Handle Errors at the Appropriate Level: Let the framework handle reconnection, focus on business logic
- Test Against Real APIs: All examples use real WebSocket endpoints for testing
- Monitor Connection Health: Use telemetry events and health checks
- Batch Operations: For high-frequency data, batch updates before processing
Extending for Your Platform
To create an adapter for your platform:
- Study the platform adapter template in
examples/platform_adapter_template.ex
- Follow the adapter building guide
- Implement platform-specific:
- Authentication flow
- Message formatting
- Subscription management
- Error handling
- Add comprehensive tests using real API endpoints
- Document platform-specific features