WebSocket subscription pattern dispatcher.
Parallel of Bourse.WS.Auth: a function-head dispatcher that routes a
pattern atom to the matching per-pattern module. Each pattern module
implements the Bourse.WS.Subscription.Behaviour callbacks.
Supported Patterns
| Pattern atom | Exchanges | Frame shape |
|---|---|---|
:op_subscribe | bybit, bitmex | %{"op"=>"subscribe","args"=>[strings]} |
:op_subscribe_objects | okx | %{"op"=>"subscribe","args"=>[objects]} |
:method_subscribe | binance, xt, aster | %{"method"=>"SUBSCRIBE","params"=>[strings]} |
:method_params_subscribe | kraken, cryptocom, derive | %{"method"=>"subscribe","params"=>%{"channel"=>[strings]}} |
:method_subscription | hyperliquid | %{"method"=>"subscribe","subscription"=>%{"type"=>…}} |
:jsonrpc_subscribe | deribit | JSON-RPC 2.0 envelope with correlation id |
:event_subscribe | gate, bitfinex, woo, bitrue | %{"event"=>"subscribe","channel"=>…} variants |
:type_subscribe | kucoin, coinbaseexchange | %{"type"=>"subscribe","topic"=>…} variants |
:sub_subscribe | htx, huobi | %{"sub"=>…} — one frame per channel, no id (see SubBased moduledoc) |
:custom | bithumb, upbit, deepcoin, … (escape hatch) | dispatches on config[:custom_type] |
Patterns for venues without a WS.SpecConfig hand base (e.g. method_topics /
method_as_topic / reqtype_sub / action_subscribe) are not registered here —
re-adding a venue re-vendors the shape deliberately from git history or
ccxt_client_bak.
Return shape
build_subscribe/3 returns {:ok, frame_or_frames} where
frame_or_frames is map() | [map()]. Single-frame exchanges return a
map; multi-frame exchanges (HTX, Upbit-custom) return a list.
Pattern modules may also surface input-shape rejections as
{:error, term()} (e.g. :multiple_maps_not_supported /
:mixed_channel_types from :event_subscribe and
:method_params_subscribe when callers mix shapes). The dispatcher
passes those tuples through verbatim — it never wraps them in {:ok, _}.
Unknown patterns return {:error, {:unknown_pattern, atom}} — matches
Bourse.WS.Auth's dispatcher-head behavior.
Summary
Functions
Builds the subscribe frame(s) for the pattern and channel list.
Builds the unsubscribe frame(s) — same return shape as build_subscribe/3.
Returns the implementing module for a pattern, or nil if unknown.
Lists every supported subscription pattern atom.
Types
Functions
@spec build_subscribe(pattern(), [channel()], config()) :: build_result()
Builds the subscribe frame(s) for the pattern and channel list.
Returns {:ok, map()} for the common single-frame case, or
{:ok, [map()]} for multi-frame exchanges (HTX, Upbit-custom).
Callers should handle both shapes.
@spec build_unsubscribe(pattern(), [channel()], config()) :: build_result()
Builds the unsubscribe frame(s) — same return shape as build_subscribe/3.
Returns the implementing module for a pattern, or nil if unknown.
@spec patterns() :: [pattern()]
Lists every supported subscription pattern atom.