github.com/anycable/anycable-go@v1.5.1/docs/broker.md (about)

     1  # Broker deep dive
     2  
     3  Broker is a component of AnyCable-Go responsible for keeping streams and sessions information in a cache-like storage. It drives the [Reliable Streams](./reliable_streams.md) feature.
     4  
     5  Broker implements features that can be characterized as _hot cache utilities_:
     6  
     7  - Handling incoming broadcast messages and storing them in a cache—that could help clients to receive missing broadcasts (triggered while the client was offline, for example).
     8  - Persisting client states—to make it possible to restore on re-connection (by providing a _session id_ of the previous connection).
     9  
    10  ## Client-server communication
    11  
    12  Below you can see the diagram demonstrating how clients can use the broker-backed features to keep up with the stream messages and restore their state:
    13  
    14  ```mermaid
    15  sequenceDiagram
    16      participant Client
    17      participant Server
    18      participant RPC
    19      participant Publisher
    20      Publisher--)Server: '{"stream":"chat_42","data":{"text":"Hi"}}'
    21      Client->>Server: CONNECT /cable
    22      activate Client
    23      Server->>RPC: Connect
    24      RPC->>Server: SUCCESS
    25      Server->>Client: '{"type":"welcome","sid":"a431"}'
    26      Client->>Server: '{"command":"subscribe","identifier":"ChatChannel/42","history":{"since":163213232}}'
    27      Server->>RPC: Subscribe
    28      RPC->>Server: SUCCESS
    29      Server->>Client: '{"type":"confirm_subscription"}}'
    30      Server->>Client: '{"message":{"text":"Hi"},"stream_id":"chat_42",offset: 42, epoch: "y2023"}'
    31      Server->>Client: '{"type":"confirm_history"}'
    32      Publisher--)Server: '{"stream":"chat_42","data":{"text":"What's up?"}}'
    33      Server->>Client: '{"message":{"text":"What's up?"},"stream_id":"chat_42",offset: 43, epoch: "y2023"}'
    34      Client-x Client: DISCONNECT
    35      deactivate Client
    36      Server--)RPC: Disconnect
    37      Publisher--)Server: '{"stream":"chat_42","data":{"text":"Where are you?"}}'
    38      Client->>Server: CONNECT /cable?sid=a431
    39      activate Client
    40      Note over Server,RPC: No RPC calls made here
    41      Server->>Client: '{"type":"welcome", "sid":"h542", "restored":true,"restored_ids":["ChatChannel/42"]}'
    42      Note over Client,Server: No need to re-subscribe, we only request history
    43      Client->>Server: '{"type":"history","identifier":"ChatChannel/42","history":{"streams": {"chat_42": {"offset":43,"epoch":"y2023"}}}}'
    44      Server->>Client: '{"message":{"text":"Where are you?"},"stream_id":"chat_42",offset: 44, epoch: "y2023"}'
    45      Server->>Client: '{"type":"confirm_history"}'
    46      deactivate Client
    47  ```
    48  
    49  To support these features, an [extended Action Cable protocol](/misc/action_cable_protocol.md#action-cable-extended-protocol) is used for communication.
    50  
    51  You can use [AnyCable JS client](https://github.com/anycable/anycable-client) library at the client-side to use the extended protocol.
    52  
    53  ## Broadcasting messages
    54  
    55  Broker is responsible for **registering broadcast messages**. Each message MUST be registered once; thus, we MUST use a broadcasting method which publishes messages to a single node in a cluster (see [broadcasting](./broadcasting.md)). Currently, `http` and `redisx` adapters are supported.
    56  
    57  **NOTE:** When legacy adapters are used, enabling a broker has no effect.
    58  
    59  To re-transmit registered messages within a cluster, we need a pub/sub component. See [Pub/Sub](./pubsub.md) for more information.
    60  
    61  The overall broadcasting message flow looks as follows:
    62  
    63  ```mermaid
    64  graph LR
    65    Publisher[Publisher]
    66  
    67    subgraph node2[Node 2]
    68     PubSub2[Pub/Sub 2]
    69     ClientC[Client C]
    70     ClientD[Client D]
    71    end
    72  
    73    subgraph node1[Node 1]
    74     Broadcaster[Broadcaster]
    75     Broker[Broker]
    76     BrokerBackend[Broker Backend]
    77     PubSub[Pub/Sub]
    78     ClientA[Client A]
    79     ClientB[Client B]
    80    end
    81  
    82    class node1 lightbg
    83    class node2 lightbg
    84    classDef lightbg fill:#ffe,stroke:#333,stroke-width:2px
    85  
    86    Publisher -.->|Message| Broadcaster
    87    Broadcaster -->|Message| Broker
    88    Broker -->|Cache Message| BrokerBackend
    89    BrokerBackend --> Broker
    90    Broker -->|Registered Message| PubSub
    91    PubSub -->|Registered Message| ClientA
    92    PubSub -->|Registered Message| ClientB
    93  
    94    PubSub -.-> PubSub2
    95  
    96    PubSub2 -->|Registered Message| ClientC
    97    PubSub2 -->|Registered Message| ClientD
    98  ```