WebsockexNova.Message.SubscriptionManager (WebsockexNova v0.1.1)
View SourceManages WebSocket subscriptions with support for persistence and automatic resubscription.
The SubscriptionManager provides a higher-level interface for working with subscriptions,
delegating the actual subscription tracking to a SubscriptionHandler
behavior implementation.
It adds features like:
- Centralized subscription management
- Automatic resubscription after reconnection
- Subscription state persistence
- Helper functions for monitoring subscriptions
Usage Example
alias WebsockexNova.Message.SubscriptionManager
alias MyApp.Crypto.DeribitSubscriptionHandler
# Initialize a subscription manager
{:ok, manager} = SubscriptionManager.new(DeribitSubscriptionHandler)
# Subscribe to channels
{:ok, sub_id1, manager} = SubscriptionManager.subscribe(manager, "market.btcusd.trades", %{frequency: "100ms"})
{:ok, sub_id2, manager} = SubscriptionManager.subscribe(manager, "market.btcusd.orderbook", %{depth: 10})
# Handle subscription responses
response = %{"type" => "subscribed", "id" => sub_id1}
{:ok, manager} = SubscriptionManager.handle_response(manager, response)
# When connection is lost, prepare for reconnection
{:ok, manager} = SubscriptionManager.prepare_for_reconnect(manager)
# After reconnection, resubscribe to channels
results = SubscriptionManager.resubscribe_after_reconnect(manager)
# Process results and get the updated manager
[{:ok, new_sub_id1, manager} | _] = results
# Check active subscriptions
active = SubscriptionManager.active_subscriptions(manager)
State Persistence
To persist subscriptions across process restarts:
# Export state before process terminates
state_to_save = SubscriptionManager.export_state(manager)
# Later, when restarting:
{:ok, manager} = SubscriptionManager.new(DeribitSubscriptionHandler)
{:ok, restored_manager} = SubscriptionManager.import_state(manager, state_to_save)
Summary
Functions
Retrieves the active (confirmed) subscriptions.
Exports the subscription state for persistence.
Finds a subscription ID by channel name.
Processes a subscription-related response message.
Imports previously exported subscription state.
Creates a new subscription manager with the specified handler module.
Prepares for reconnection by storing active subscriptions in state.
Resubscribes to all stored subscriptions after a successful reconnect.
Subscribes to a channel using the configured handler.
Unsubscribes from a channel using the configured handler.
Types
Functions
@spec active_subscriptions(t()) :: %{ required(WebsockexNova.Behaviors.SubscriptionHandler.subscription_id()) => term() }
Retrieves the active (confirmed) subscriptions.
Parameters
manager
- The subscription manager
Returns
- A map of subscription IDs to subscription details
Exports the subscription state for persistence.
This is useful for saving the state before a process terminates, so it can be restored later.
Parameters
manager
- The subscription manager
Returns
- A map containing the serializable state
@spec find_subscription_by_channel( t(), WebsockexNova.Behaviors.SubscriptionHandler.channel() ) :: WebsockexNova.Behaviors.SubscriptionHandler.subscription_id() | nil
Finds a subscription ID by channel name.
Parameters
manager
- The subscription managerchannel
- The channel name to look up
Returns
- The subscription ID if found, nil otherwise
@spec handle_response( t(), WebsockexNova.Behaviors.SubscriptionHandler.subscription_response() ) :: {:ok, t()} | {:error, term(), t()}
Processes a subscription-related response message.
Parameters
manager
- The subscription managerresponse
- The response message from the server
Returns
{:ok, updated_manager}
- Response processed successfully{:error, reason, updated_manager}
- Error in response
Imports previously exported subscription state.
This is useful for restoring state after process restart.
Parameters
manager
- The subscription managerexported_state
- The state previously exported withexport_state/1
Returns
{:ok, updated_manager}
- Successfully imported state
Creates a new subscription manager with the specified handler module.
Parameters
handler_module
- Module that implements theSubscriptionHandler
behaviorinitial_state
- Optional initial state for the handler (default:%{}
)
Returns
{:ok, manager}
- A new subscription manager
Prepares for reconnection by storing active subscriptions in state.
This should be called before a reconnection attempt to ensure subscriptions can be restored after reconnection.
Parameters
manager
- The subscription manager
Returns
{:ok, updated_manager}
- Successfully prepared for reconnect
@spec resubscribe_after_reconnect(t()) :: [ {:ok, WebsockexNova.Behaviors.SubscriptionHandler.subscription_id(), t()} | {:error, term(), t()} ]
Resubscribes to all stored subscriptions after a successful reconnect.
This should be called after a successful reconnection to restore previously active subscriptions.
Parameters
manager
- The subscription manager with stored subscriptions
Returns
- A list of subscription results, each being
{:ok, subscription_id, updated_manager}
or{:error, reason, updated_manager}
@spec subscribe( t(), WebsockexNova.Behaviors.SubscriptionHandler.channel(), WebsockexNova.Behaviors.SubscriptionHandler.params() ) :: {:ok, WebsockexNova.Behaviors.SubscriptionHandler.subscription_id(), t()} | {:error, term(), t()}
Subscribes to a channel using the configured handler.
Parameters
manager
- The subscription managerchannel
- The channel to subscribe toparams
- Optional parameters for the subscription
Returns
{:ok, subscription_id, updated_manager}
- Successful subscription with ID{:error, reason, updated_manager}
- Failed to subscribe
@spec unsubscribe(t(), WebsockexNova.Behaviors.SubscriptionHandler.subscription_id()) :: {:ok, t()} | {:error, term(), t()}
Unsubscribes from a channel using the configured handler.
Parameters
manager
- The subscription managersubscription_id
- The ID of the subscription to remove
Returns
{:ok, updated_manager}
- Successfully unsubscribed{:error, reason, updated_manager}
- Failed to unsubscribe