derp: add sequence diagrams to READMEpercy/derp_sequence_diagram

Updates tailscale/corp#24073

Signed-off-by: Percy Wegmann <percy@tailscale.com>

1 files changed, 101 insertions, 1 deletions

diff --git a/derp/README.md b/derp/README.md
index 16877020d..ac7be3ed9 100644
--- a/derp/README.md
+++ b/derp/README.md
@@ -58,4 +58,104 @@ We generally run a minimum of three nodes in a region not for quorum reasons
 (there's no voting) but just because two is too uncomfortably few for cascading
 failure reasons: if you're running two nodes at 51% load (CPU, memory, etc) and
 then one fails, that makes the second one fail. With three or more nodes, you
-can run each node a bit hotter.
\ No newline at end of file
+can run each node a bit hotter.
+
+## Sequence Diagrams
+
+The below sequence diagrams show some of the main DERP-related interactions.
+
+### Connection Establishment
+
+Tailscale clients connect to the control server and to their respective DERP homes. The control server distributes knowledge about chosen DERP homes to other clients.
+
+At the end of this flow, both client A and client B are connected to their respective home DERPs 1x and 2x, and both know of each other's chosen DERP home region.
+
+```mermaid
+sequenceDiagram
+	participant a as Client A
+  participant 1x as DERP 1x
+  participant control as Control
+  participant 2x as DERP 2x
+	participant b as Client B
+  
+  par A
+  a->>control: connect
+  and B
+  b->>control: connect
+  end
+  par A
+  control->>a: DERP map
+  a->>a: choose home region by latency
+  a->>a: choose DERP in home region based on priority order in DERP map
+  a->>1x: connect to home DERP
+  a->>control: report home region 1
+  control->>b: notify Client A's home region is 1
+  and B
+  control->>b: DERP map
+  b->>b: choose home region by latency
+  b->>b: choose DERP in home region based on priority order in DERP map
+  b->>2x: connect to home DERP
+  b->>control: report home region 2
+  control->>a: notify Client B's home region is 2
+  end
+```
+
+### Packet Sending, Same Home Region, Same Home DERP
+
+This is the simplest case, in which both clients are already connected to the same DERP server.
+
+```mermaid
+sequenceDiagram
+	participant a as Client A
+  participant 1x as DERP 1x
+  participant b as Client B
+  
+  b->>1x: send packet to Client A
+  1x->>a: forward packet to Client A
+```
+
+### Packet Sending, Same Home Region, Different Home DERP (Mesh)
+
+In this case, both clients are using the same home region, but they are connected to different DERP servers within this region.
+
+```mermaid
+sequenceDiagram
+	participant a as Client A
+  participant 1x as DERP 1x
+  participant 1y as DERP 1y
+  participant b as Client B
+  
+  a->>1x: connect to home DERP
+  1x->>1y: notify that Client A is connected to 1x
+  b->>1y: send packet to Client A
+  1y->>1x: forward packet for Client A
+  1x->>a: forward packet to Client A
+```
+
+### Packet Sending, Different Home Regions
+
+In this case, both clients are using different home regions. The sending Client B connects to the recipients's home region.
+Note that the Client B remains connected to its own home DERP even as it sends traffic to Client A via its home DERP region.
+
+```mermaid
+sequenceDiagram
+	participant a as Client A
+  participant 1x as DERP 1x
+  participant control as Control
+  participant 2x as DERP 2x
+  participant b as Client B
+  
+  par A
+  a->>1x: connect to home DERP
+  a->>control: report home region 1
+  control->>b: notify Client A's home region is 1
+  and B
+  b->>2x: connect to home DERP
+  b->>control: report home region 2
+  control->>a: notify Client B's home region is 2
+  end
+  b->>1x: connect to Client A's home DERP
+  b->>1x: send packet to Client A
+  1x->>a: forward packet to Client A
+```
+