Practical examples of using ZenWebsocket, all written and tested in-tree under
lib/zen_websocket/examples/. Examples and their test suites live in the library
repository; a separate examples/<name>/ mix project structure was evaluated and
reverted in favor of in-tree examples to ensure they stay synchronized with the
library. This page is a navigable index; each entry points at the module source
and test, which are the single source of truth rather than pasting code blocks
that can drift.
Module Index
lib/zen_websocket/examples/
| Module | File | Demonstrates | Tests |
|---|---|---|---|
ZenWebsocket.Examples.AdapterSupervisor | adapter_supervisor.ex | Supervising adapter GenServers alongside ClientSupervisor | none |
ZenWebsocket.Examples.BatchSubscriptionManager | batch_subscription_manager.ex | Batching subscription requests with configurable batch size/delay | batch_subscription_manager_test.exs |
ZenWebsocket.Examples.DeribitAdapter | deribit_adapter.ex | Simplified Deribit adapter built on DeribitRpc | deribit_adapter_auth_test.exs, deribit_adapter_nil_client_test.exs |
ZenWebsocket.Examples.DeribitGenServerAdapter | deribit_genserver_adapter.ex | Production-ready supervised Deribit adapter: monitored client, auto-reconnect, auth/subscription restore | deribit_genserver_adapter_test.exs |
ZenWebsocket.Examples.DeribitRpc | deribit_rpc.ex | Shared Deribit JSON-RPC method/request builders used by both Deribit adapters | none dedicated — exercised indirectly through the DeribitAdapter/DeribitGenServerAdapter test suites |
ZenWebsocket.Examples.JsonRpcTransport | json_rpc_transport.ex | Shared JSON-RPC send helper (Client.send_message/2 result normalization) used by both Deribit adapters | none dedicated — exercised indirectly via deribit_adapter_nil_client_test.exs |
ZenWebsocket.Examples.PlatformAdapterTemplate | platform_adapter_template.ex | Minimal template (connect/2, authenticate/2, extension points) for a new platform adapter | platform_adapter_template_test.exs |
ZenWebsocket.Examples.SupervisedClient | supervised_client.ex | Minimal ClientSupervisor-based connection supervision | supervised_client_test.exs |
ZenWebsocket.Examples.UsagePatterns | usage_patterns.ex | Three usage patterns: direct connection, ClientSupervisor, direct supervision in your own tree | none |
ClientSupervisor itself (not an example module, but exercised by this
directory's supervision examples) has end-to-end coverage in
supervised_connection_test.exs.
lib/zen_websocket/examples/docs/
A second set of examples, written to accompany this guide's code snippets:
| Module | File | Demonstrates | Tests |
|---|---|---|---|
ZenWebsocket.Examples.Docs.BasicUsage | basic_usage.ex | Basic connect + request/response against Deribit testnet | basic_usage_test.exs |
ZenWebsocket.Examples.Docs.ErrorHandling | error_handling.ex | A GenServer wrapping a connection with retry-on-failure | error_handling_test.exs |
ZenWebsocket.Examples.Docs.JsonRpcClient | json_rpc_client.ex | Declaring JSON-RPC methods with ZenWebsocket.JsonRpc's defrpc macro | none |
ZenWebsocket.Examples.Docs.SubscriptionManagement | subscription_management.ex | Multi-channel subscription patterns | subscription_management_test.exs |
Running the Examples
# Run a single example's test
mix test test/zen_websocket/examples/basic_usage_test.exs
# Run every example test
mix test test/zen_websocket/examples/
# Run with coverage
mix test --cover test/zen_websocket/examples/
# Or explore interactively
iex -S mix
# In IEx, try the basic usage example
alias ZenWebsocket.Examples.Docs.BasicUsage
{:ok, client} = BasicUsage.deribit_testnet_example()Deribit Integration
ZenWebsocket.Examples.DeribitAdapter and ZenWebsocket.Examples.DeribitGenServerAdapter
are the in-tree Deribit integration examples — authentication, subscription
management, and (for the GenServer adapter) monitored auto-reconnect with
auth/subscription restore. Both share request-building through DeribitRpc and
transport through JsonRpcTransport. Study
deribit_genserver_adapter.ex
for the production-supervised pattern. Its test suite
(deribit_genserver_adapter_test.exs)
runs against real Deribit testnet endpoints — all integration tests in this library
use live API endpoints rather than mocks to ensure correctness against real
provider behavior.
Extending for Your Platform
To create an adapter for your own platform:
- Study platform_adapter_template.ex
- Follow the adapter building guide
- Implement platform-specific authentication, message formatting, subscription management, and error handling
- Add tests against real API endpoints — see the Deribit adapters' test suites for the pattern
- Document platform-specific features