Skip to content

Commit e30e4d7

Browse files
committed
docs: draw the load-balancer case as two replicas with separate buses
Replace the sequence diagram on the Subscriptions page with a small flowchart: each replica is a box holding its own bus, the listen stream is subscribed to one, the tool call publishes to the other, and a dashed outline marks the shared bus that is missing between them.
1 parent a245b52 commit e30e4d7

1 file changed

Lines changed: 17 additions & 16 deletions

File tree

‎docs/handlers/subscriptions.md‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -74,26 +74,27 @@ Entering `client.listen(...)` sends the request and waits for your acknowledgmen
7474

7575
Publishes travel from your handler to the open streams over a `SubscriptionBus`. The default is in-memory: one process, every stream in it. That is the right answer until you run replicas behind a load balancer, because then a client's stream is pinned to one replica, and a publish on another replica has to reach it.
7676

77-
With the default bus, it doesn't:
77+
With the default bus it can't, because every replica has its own:
7878

7979
```mermaid
80-
sequenceDiagram
81-
participant C as Client
82-
participant LB as Load balancer
83-
participant A as Replica A
84-
participant B as Replica B
85-
Note over LB: any request,<br/>any replica
86-
C->>A: subscriptions/listen
87-
activate A
88-
A-->>C: acknowledged, stream stays open
89-
C->>B: tools/call
90-
Note over B: ctx.notify_* publishes<br/>to B's own bus
91-
B-->>C: result
92-
Note over A: hears nothing,<br/>so neither does the client
93-
deactivate A
80+
flowchart LR
81+
client[Client] --> lb[Load balancer]
82+
lb --> stream
83+
lb ~~~~ gap
84+
lb --> tool
85+
subgraph B [Replica B]
86+
tool[tools/call] -- publishes --> busB[(bus B)]
87+
end
88+
gap[(no shared bus)]
89+
subgraph A [Replica A]
90+
stream[listen stream] -- subscribed --> busA[(bus A)]
91+
end
92+
style A fill:none
93+
style B fill:none
94+
style gap fill:none,stroke-dasharray:4 4
9495
```
9596

96-
Nothing fails. The tool call succeeds and the stream stays silent. So behind a load balancer, pick one:
97+
Nothing fails: the call succeeds, and the stream stays silent. So behind a load balancer, pick one:
9798

9899
* **You need change notifications.** Give every replica the same bus, below.
99100
* **You don't.** [Turn them off](#turning-it-off), so no client is promised events it will miss or holds a stream open for them.

0 commit comments

Comments
 (0)