From 1db93b936d616ad49bd7978ebd7f4f6da8af4df2 Mon Sep 17 00:00:00 2001 From: "Evgeny @ SimpleX Chat" <259188159+evgeny-simplex@users.noreply.github.com> Date: Sat, 14 Mar 2026 13:54:41 +0000 Subject: [PATCH] corrections --- docs/AGENT.md | 40 +++--- docs/CLIENT.md | 37 ++++-- docs/ROUTERS.md | 22 ++-- spec/clients.md | 22 ++-- spec/diagrams/ntf-router.svg | 3 - spec/diagrams/smp-client-agent.svg | 167 ++++++++++++------------ spec/diagrams/smp-client.svg | 195 ++++++++++++++++------------- spec/diagrams/smp-router.svg | 5 +- spec/diagrams/xftp-client.svg | 3 - spec/diagrams/xftp-router.svg | 3 - spec/routers.md | 6 +- 11 files changed, 263 insertions(+), 240 deletions(-) diff --git a/docs/AGENT.md b/docs/AGENT.md index e6fe32b08..83050013f 100644 --- a/docs/AGENT.md +++ b/docs/AGENT.md @@ -4,16 +4,16 @@ The SimpleX Agent builds duplex encrypted connections on top of [SimpleX client This is **Layer 3** of the [SimpleX Network architecture](../protocol/overview-tjr.md). Layer 1 is the routers; Layer 2 is the [client libraries](CLIENT.md) that speak the wire protocols. The Agent adds the connection semantics that applications need. -**Source**: [`Simplex.Messaging.Agent`](../src/Simplex/Messaging/Agent.hs) — **Module spec**: [`spec/modules/Simplex/Messaging/Agent.md`](../spec/modules/Simplex/Messaging/Agent.md) +**Source**: [`Simplex.Messaging.Agent`](../src/Simplex/Messaging/Agent.hs). **Module spec**: [`spec/modules/Simplex/Messaging/Agent.md`](../spec/modules/Simplex/Messaging/Agent.md) ## Connections The Agent turns simplex (unidirectional) SMP queues into duplex connections, implementing the [Agent protocol](../protocol/agent-protocol.md): -- **Duplex connections**: each connection uses a pair of SMP queues — one for each direction. The queues can be on different routers chosen independently by each party. See the [duplex connection procedure](../protocol/agent-protocol.md) for the full handshake. +- **Duplex connections**: each connection uses a pair of SMP queues - one for each direction. The queues can be on different routers chosen independently by each party. See the [duplex connection procedure](../protocol/agent-protocol.md) for the full handshake. - **Connection establishment**: one party creates a connection and generates an invitation (containing router address, queue ID, and public keys). The invitation is passed out-of-band (QR code, link, etc.). The other party joins by creating a reverse queue and completing the handshake. - **Connection links**: the Agent supports connection links (long and short) for sharing connection invitations via URLs. Short links use a separate SMP queue to store the full invitation, allowing compact QR codes. -- **Queue rotation**: the Agent periodically rotates the underlying SMP queues, limiting the window for metadata correlation. Rotation is transparent to the application — the connection identity is stable while the underlying queues change. +- **Queue rotation**: the Agent periodically rotates the underlying SMP queues, limiting the window for metadata correlation. Rotation is transparent to the application - the connection identity is stable while the underlying queues change. - **Redundant queues**: connections can use multiple queues for reliability. If one router becomes unreachable, messages flow through the remaining queues. ## Encryption @@ -46,7 +46,7 @@ The Agent manages push notification subscriptions for mobile devices, using the The Agent is designed to be embedded as a Haskell library: -- **STM queues**: the application communicates with the Agent via STM queues. Commands go in (`ACommand`), events come out (`AEvent`). No serialization or parsing — direct Haskell values. The command/event types are defined in the [Agent Protocol module](../spec/modules/Simplex/Messaging/Agent/Protocol.md). +- **STM queues**: the application communicates with the Agent via STM queues. Commands go in (`ACommand`), events come out (`AEvent`). No serialization or parsing - direct Haskell values. The command/event types are defined in the [Agent Protocol module](../spec/modules/Simplex/Messaging/Agent/Protocol.md). - **Async operation**: all network operations are asynchronous. The Agent manages internal worker threads for each router connection, message processing, and background tasks (cleanup, statistics, notification supervision). See the [Agent Client module spec](../spec/modules/Simplex/Messaging/Agent/Client.md) for worker architecture. - **Background mode**: on mobile platforms, the Agent can run in a reduced mode with only the message receiver active, minimizing resource usage when the app is backgrounded. - **Dual database backends**: the Agent supports both SQLite (for mobile/desktop) and PostgreSQL (for server deployments) as persistence backends, selected at compile time. See [Agent Store Interface](../spec/modules/Simplex/Messaging/Agent/Store/Interface.md) and [Agent Store Postgres](../spec/modules/Simplex/Messaging/Agent/Store/Postgres.md). @@ -70,24 +70,24 @@ The Agent is designed to be embedded as a Haskell library: ## Protocol references -- [Agent Protocol](../protocol/agent-protocol.md) — duplex connection procedure, message format -- [SimpleX Network overview](../protocol/overview-tjr.md) — architecture, trust model -- [PQDR](../protocol/pqdr.md) — post-quantum double ratchet specification -- [SimpleX Messaging Protocol](../protocol/simplex-messaging.md) — SMP queue operations used by the Agent -- [XFTP Protocol](../protocol/xftp.md) — data packet operations for file transfer -- [Push Notifications Protocol](../protocol/push-notifications.md) — NTF token and subscription management +- [Agent Protocol](../protocol/agent-protocol.md) - duplex connection procedure, message format +- [SimpleX Network overview](../protocol/overview-tjr.md) - architecture, trust model +- [PQDR](../protocol/pqdr.md) - post-quantum double ratchet specification +- [SimpleX Messaging Protocol](../protocol/simplex-messaging.md) - SMP queue operations used by the Agent +- [XFTP Protocol](../protocol/xftp.md) - data packet operations for file transfer +- [Push Notifications Protocol](../protocol/push-notifications.md) - NTF token and subscription management ## Peer library: Remote Control -The Agent exposes the [XRCP protocol](../protocol/xrcp.md) API for cross-device remote control (e.g., controlling a mobile app from a desktop). The actual logic is in the standalone [`Simplex.RemoteControl.Client`](../src/Simplex/RemoteControl/Client.hs) library — the Agent provides thin wrappers that pass through its random and multicast state. XRCP is not a managed Agent capability (no workers, persistence, or background supervision). See the [RemoteControl module specs](../spec/modules/Simplex/RemoteControl/Types.md). +The Agent exposes the [XRCP protocol](../protocol/xrcp.md) API for cross-device remote control (e.g., controlling a mobile app from a desktop). The actual logic is in the standalone [`Simplex.RemoteControl.Client`](../src/Simplex/RemoteControl/Client.hs) library - the Agent provides thin wrappers that pass through its random and multicast state. XRCP is not a managed Agent capability (no workers, persistence, or background supervision). See the [RemoteControl module specs](../spec/modules/Simplex/RemoteControl/Types.md). ## Module specs -- [Agent](../spec/modules/Simplex/Messaging/Agent.md) — main Agent module, connection lifecycle, message processing -- [Agent Client](../spec/modules/Simplex/Messaging/Agent/Client.md) — worker threads, router connections, subscription management -- [Agent Protocol](../spec/modules/Simplex/Messaging/Agent/Protocol.md) — ACommand/AEvent types, connection invitations -- [Agent Store Interface](../spec/modules/Simplex/Messaging/Agent/Store/Interface.md) — database abstraction for SQLite/Postgres -- [Agent Store (AgentStore)](../spec/modules/Simplex/Messaging/Agent/Store/AgentStore.md) — connection, queue, and message persistence -- [NtfSubSupervisor](../spec/modules/Simplex/Messaging/Agent/NtfSubSupervisor.md) — notification subscription management -- [XFTP Agent](../spec/modules/Simplex/FileTransfer/Agent.md) — file transfer orchestration -- [Ratchet](../spec/modules/Simplex/Messaging/Crypto/Ratchet.md) — double ratchet implementation -- [SNTRUP761](../spec/modules/Simplex/Messaging/Crypto/SNTRUP761.md) — post-quantum KEM +- [Agent](../spec/modules/Simplex/Messaging/Agent.md) - main Agent module, connection lifecycle, message processing +- [Agent Client](../spec/modules/Simplex/Messaging/Agent/Client.md) - worker threads, router connections, subscription management +- [Agent Protocol](../spec/modules/Simplex/Messaging/Agent/Protocol.md) - ACommand/AEvent types, connection invitations +- [Agent Store Interface](../spec/modules/Simplex/Messaging/Agent/Store/Interface.md) - database abstraction for SQLite/Postgres +- [Agent Store (AgentStore)](../spec/modules/Simplex/Messaging/Agent/Store/AgentStore.md) - connection, queue, and message persistence +- [NtfSubSupervisor](../spec/modules/Simplex/Messaging/Agent/NtfSubSupervisor.md) - notification subscription management +- [XFTP Agent](../spec/modules/Simplex/FileTransfer/Agent.md) - file transfer orchestration +- [Ratchet](../spec/modules/Simplex/Messaging/Crypto/Ratchet.md) - double ratchet implementation +- [SNTRUP761](../spec/modules/Simplex/Messaging/Crypto/SNTRUP761.md) - post-quantum KEM diff --git a/docs/CLIENT.md b/docs/CLIENT.md index 6cd4f2321..4f71dab89 100644 --- a/docs/CLIENT.md +++ b/docs/CLIENT.md @@ -8,7 +8,7 @@ This is **Layer 2** of the [SimpleX Network architecture](../protocol/overview-t **Source**: [`Simplex.Messaging.Client`](../src/Simplex/Messaging/Client.hs). For architecture and module specs, see [SMP Client](../spec/clients.md#smp-client-protocolclient). -The SMP client connects to SMP routers and manages simplex messaging queues — the fundamental addressing primitive of the SimpleX Network. Each simplex queue is a unidirectional, ordered sequence of fixed-size packets (16,384 bytes) with separate cryptographic credentials for sending and receiving. The queue model and command set are defined in the [SMP protocol](../protocol/simplex-messaging.md). +The SMP client connects to SMP routers and manages simplex messaging queues, the fundamental addressing primitive of the SimpleX Network. Each simplex queue is a unidirectional, ordered sequence of fixed-size packets (16,384 bytes) with separate cryptographic credentials for sending and receiving. The queue model and command set are defined in the [SMP protocol](../protocol/simplex-messaging.md). ### Capabilities @@ -31,17 +31,30 @@ The client uses a functional Haskell API with STM queues for asynchronous event Routers are identified by the SHA-256 hash of their CA certificate fingerprint, not by hostname. The client validates the full X.509 certificate chain on every TLS connection and compares the CA fingerprint against the expected hash from the queue address. This means a DNS or IP-level attacker who cannot produce the correct certificate is detected at connection time. +## SMPClientAgent + +**Source**: [`Simplex.Messaging.Client.Agent`](../src/Simplex/Messaging/Client/Agent.hs). For architecture and module specs, see [SMPClientAgent](../spec/clients.md#smpclientagent). + +Connection manager that multiplexes multiple SMP client connections. Maintains one ProtocolClient per SMP router, tracks queue and service subscriptions, and handles reconnection with exponential backoff. Used by the SMP router (for proxy forwarding) and the NTF router (for message subscriptions). + +### Capabilities + +- **Connection pooling**: maintains a pool of ProtocolClient connections keyed by SMP router, creating connections on demand and reusing existing ones +- **Subscription tracking**: tracks active and pending subscriptions (both queue-based and service-based) with automatic state transitions on connect/disconnect +- **Automatic reconnection**: on connection loss, moves subscriptions from active to pending, then spawns a background worker that retries with backoff and resubscribes +- **Session-scoped disconnect handling**: uses session IDs to ensure only subscriptions belonging to the disconnected session are affected, preventing races with newly established connections + ## XFTP Client **Source**: [`Simplex.FileTransfer.Client`](../src/Simplex/FileTransfer/Client.hs). For architecture and module specs, see [XFTP Client](../spec/clients.md#xftp-client). -The XFTP client connects to XFTP routers and manages data packets — individually addressed blocks used for larger payload delivery. Data packets come in fixed sizes (64KB, 256KB, 1MB, 4MB), hiding the actual payload size. The XFTP protocol runs over HTTP/2, simplifying browser integration. The data packet lifecycle and command set are defined in the [XFTP protocol](../protocol/xftp.md). +The XFTP client connects to XFTP routers and manages data packets, individually addressed blocks used for larger payload delivery. Data packets come in fixed sizes (64KB, 256KB, 1MB, 4MB), hiding the actual payload size. The XFTP protocol runs over HTTP/2, simplifying browser integration. The data packet lifecycle and command set are defined in the [XFTP protocol](../protocol/xftp.md). ### Capabilities - **Data packet creation**: create data packets on routers with sender, recipient, and optional additional recipient credentials. See the [XFTP protocol](../protocol/xftp.md) for credential roles and packet lifecycle. - **Send** (FPUT): send encrypted data to the router in a single HTTP/2 streaming request (command + body) -- **Receive** (FGET): receive data packets with per-request ephemeral Diffie-Hellman key exchange, providing forward secrecy — compromising one DH key does not reveal other received data packets +- **Receive** (FGET): receive data packets with per-request ephemeral Diffie-Hellman key exchange, providing forward secrecy: compromising one DH key does not reveal other received data packets - **Acknowledgment and deletion**: recipients acknowledge receipt; senders delete data packets after delivery ## NTF Client @@ -69,15 +82,15 @@ These libraries are appropriate when the application manages its own encryption The following capabilities require the [Agent](AGENT.md) (Layer 3): -- **Duplex connections** — the Agent pairs two simplex queues into a duplex connection -- **End-to-end encryption** — the Agent manages double ratchet with post-quantum extensions -- **File transfer** — the Agent handles chunking, encryption, padding, multi-router distribution, and reassembly -- **Queue rotation** — the Agent transparently rotates queues to limit metadata correlation -- **Connection discovery** — connection links, short links, and contact addresses are Agent-level abstractions -- **Push notifications** — notification token management and subscription is Agent-level +- **Duplex connections** - the Agent pairs two simplex queues into a duplex connection +- **End-to-end encryption** - the Agent manages double ratchet with post-quantum extensions +- **File transfer** - the Agent handles chunking, encryption, padding, multi-router distribution, and reassembly +- **Queue rotation** - the Agent transparently rotates queues to limit metadata correlation +- **Connection discovery** - connection links, short links, and contact addresses are Agent-level abstractions +- **Push notifications** - notification token management and subscription is Agent-level ## Protocol references -- [SimpleX Messaging Protocol](../protocol/simplex-messaging.md) — SMP wire format, commands, and security properties -- [XFTP Protocol](../protocol/xftp.md) — XFTP wire format, data packet lifecycle -- [SimpleX Network overview](../protocol/overview-tjr.md) — architecture, trust model, and design rationale +- [SimpleX Messaging Protocol](../protocol/simplex-messaging.md) - SMP wire format, commands, and security properties +- [XFTP Protocol](../protocol/xftp.md) - XFTP wire format, data packet lifecycle +- [SimpleX Network overview](../protocol/overview-tjr.md) - architecture, trust model, and design rationale diff --git a/docs/ROUTERS.md b/docs/ROUTERS.md index 29d518d65..d938dc40f 100644 --- a/docs/ROUTERS.md +++ b/docs/ROUTERS.md @@ -1,4 +1,4 @@ -# SimpleX Routers — Deployment and Configuration +# SimpleX Routers: Deployment and Configuration SimpleX routers are the network infrastructure of the [SimpleX Network](../protocol/overview-tjr.md). They accept, buffer, and deliver data packets between endpoints. Each router operates independently and can be run by any party on standard computing hardware. @@ -6,7 +6,7 @@ This document covers deployment and advanced configuration. For an overview of t ## SMP Router -The SMP router provides messaging queues — unidirectional, ordered sequences of fixed-size packets (16,384 bytes each). It implements the [SimpleX Messaging Protocol](../protocol/simplex-messaging.md). For architecture and module specs, see [SMP Router](../spec/routers.md#smp-router). +The SMP router provides messaging queues - unidirectional, ordered sequences of fixed-size packets (16,384 bytes each). It implements the [SimpleX Messaging Protocol](../protocol/simplex-messaging.md). For architecture and module specs, see [SMP Router](../spec/routers.md#smp-router). ### Advanced configuration @@ -35,7 +35,7 @@ echo 'PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"' >> ~/.zprofile ## XFTP Router -The XFTP router accepts and delivers data packets over HTTP/2 — individually addressed blocks in fixed sizes (64KB, 256KB, 1MB, 4MB). It implements the [XFTP protocol](../protocol/xftp.md). Data packets are used for larger payload delivery (files, media) where SMP queue packet sizes would be inefficient. The use of HTTP/2 simplifies browser integration. For architecture and module specs, see [XFTP Router](../spec/routers.md#xftp-router). +The XFTP router accepts and delivers data packets over HTTP/2 - individually addressed blocks in fixed sizes (64KB, 256KB, 1MB, 4MB). It implements the [XFTP protocol](../protocol/xftp.md). Data packets are used for larger payload delivery (files, media) where SMP queue packet sizes would be inefficient. The use of HTTP/2 simplifies browser integration. For architecture and module specs, see [XFTP Router](../spec/routers.md#xftp-router). Initialize with `xftp-server init` and configure storage quota in `xftp-server.ini`. @@ -66,7 +66,7 @@ Prebuilt images are available from [Docker Hub](https://hub.docker.com/r/simplex 2. Run: - **SMP router** — change `your_ip_or_domain`; `-e "PASS=password"` is optional: + **SMP router** - change `your_ip_or_domain`; `-e "PASS=password"` is optional: ```sh docker run -d \ -e "ADDR=your_ip_or_domain" \ @@ -77,7 +77,7 @@ Prebuilt images are available from [Docker Hub](https://hub.docker.com/r/simplex simplexchat/smp-server:latest ``` - **XFTP router** — change `your_ip_or_domain` and `maximum_storage`: + **XFTP router** - change `your_ip_or_domain` and `maximum_storage`: ```sh docker run -d \ -e "ADDR=your_ip_or_domain" \ @@ -160,12 +160,12 @@ Then run with the same Docker commands as above, replacing `simplexchat/smp-serv ### Linode StackScript -[Deploy via Linode StackScript](https://cloud.linode.com/stackscripts/748014) — Shared CPU Nanode with 1GB is sufficient. +[Deploy via Linode StackScript](https://cloud.linode.com/stackscripts/748014). Shared CPU Nanode with 1GB is sufficient. Configuration options: - SMP Server store log flag for queue persistence (recommended) - [Linode API token](https://www.linode.com/docs/guides/getting-started-with-the-linode-api#get-an-access-token) for automatic DNS and tagging (scopes: read/write for "linodes" and "domains") -- Domain name (e.g., `smp1.example.com`) — the [domain must exist](https://cloud.linode.com/domains/create) in your Linode account +- Domain name (e.g., `smp1.example.com`) - the [domain must exist](https://cloud.linode.com/domains/create) in your Linode account After deployment (up to 5 minutes), get the server address from Linode tags or SSH: `smp://@`. @@ -188,7 +188,7 @@ SMP and XFTP routers expose Prometheus metrics via a control port. The control p ## Protocol references -- [SimpleX Messaging Protocol](../protocol/simplex-messaging.md) — SMP wire format and security properties -- [XFTP Protocol](../protocol/xftp.md) — data packet protocol -- [Push Notifications Protocol](../protocol/push-notifications.md) — NTF protocol -- [SimpleX Network overview](../protocol/overview-tjr.md) — architecture and trust model +- [SimpleX Messaging Protocol](../protocol/simplex-messaging.md) - SMP wire format and security properties +- [XFTP Protocol](../protocol/xftp.md) - data packet protocol +- [Push Notifications Protocol](../protocol/push-notifications.md) - NTF protocol +- [SimpleX Network overview](../protocol/overview-tjr.md) - architecture and trust model diff --git a/spec/clients.md b/spec/clients.md index 871d1b4fd..a99686ab0 100644 --- a/spec/clients.md +++ b/spec/clients.md @@ -14,9 +14,9 @@ Generic protocol client used for both SMP and NTF connections. Manages a single ### Component topology -![SMP Client — Component Topology](diagrams/smp-client.svg) +![SMP Client - Component Topology](diagrams/smp-client.svg) -### Command/response flow +### Command/result flow ```mermaid sequenceDiagram @@ -33,7 +33,7 @@ sequenceDiagram participant Router as SMP Router - C->>SC: mkTransmission (generate CorrId, create Request with empty responseVar) + C->>SC: mkTransmission
(generate CorrId, create Request
with empty responseVar) C->>SQ: write (Request, encoded command) S->>SQ: read S-->>S: check pending flag (drop if timed out) @@ -65,15 +65,19 @@ Connection manager that multiplexes multiple ProtocolClient connections. Tracks ### Component topology -![SMPClientAgent — Component Topology](diagrams/smp-client-agent.svg) +![SMPClientAgent - Component Topology](diagrams/smp-client-agent.svg) ### Connection lifecycle ```mermaid sequenceDiagram participant C as Consumer
(router / app) - participant A as SMPClientAgent - participant PC as ProtocolClient + + box + participant A as SMPClientAgent + participant PC as ProtocolClient + end + participant Router as SMP Router C->>A: getSMPServerClient'' (server) @@ -112,11 +116,11 @@ sequenceDiagram **Module specs**: [Client](modules/Simplex/FileTransfer/Client.md) · [Protocol](modules/Simplex/FileTransfer/Protocol.md) · [HTTP/2 Client](modules/Simplex/Messaging/Transport/HTTP2/Client.md) -Stateless wrapper around HTTP2Client. XFTPClient adds no threads of its own — each operation is a synchronous HTTP/2 request/response. Serialization and multiplexing happen inside HTTP2Client's internal request queue and process thread. +Stateless wrapper around HTTP2Client. XFTPClient adds no threads of its own; each operation is a synchronous HTTP/2 request/response. Serialization and multiplexing happen inside HTTP2Client's internal request queue and process thread. ### Component topology -![XFTP Client — Component Topology](diagrams/xftp-client.svg) +![XFTP Client - Component Topology](diagrams/xftp-client.svg) ### Upload/download flow @@ -156,7 +160,7 @@ sequenceDiagram **Module specs**: [Client](modules/Simplex/Messaging/Notifications/Client.md) · [Protocol](modules/Simplex/Messaging/Notifications/Protocol.md) -Type alias for ProtocolClient — same architecture as SMP Client: +Type alias for ProtocolClient - same architecture as SMP Client: ```haskell type NtfClient = ProtocolClient NTFVersion ErrorType NtfResponse diff --git a/spec/diagrams/ntf-router.svg b/spec/diagrams/ntf-router.svg index b42429459..c6c9c2431 100644 --- a/spec/diagrams/ntf-router.svg +++ b/spec/diagrams/ntf-router.svg @@ -10,9 +10,6 @@ - - NTF Router -- Component Topology - diff --git a/spec/diagrams/smp-client-agent.svg b/spec/diagrams/smp-client-agent.svg index 4257726ec..be76d2233 100644 --- a/spec/diagrams/smp-client-agent.svg +++ b/spec/diagrams/smp-client-agent.svg @@ -1,4 +1,4 @@ - + @@ -10,137 +10,134 @@ - - SMPClientAgent -- Component Topology + + consumer + (NTF router / + SMP proxy / + application) - - consumer - (NTF router / - SMP proxy / - application) - - - + - msgQ - (TBQueue, server messages) - - - - - - - agentQ - (TBQueue SMPClientAgentEvent) + agentQ + (TBQueue SMPClientAgentEvent) - - CAConnected - CADisconnected - CASubscribed / CASubError - CAServiceDisconnected - CAServiceSubscribed / SubError + CAConnected / Disconnected + CASubscribed / SubError + CAServiceDisconnected + CAServiceSubscribed / SubError + CAServiceUnavailable + + + + msgQ + (TBQueue, server messages) + + + - - SMPClientAgent (connection manager) + SMPClientAgent (connection manager) - - smpClients - (TMap SMPServer SMPClientVar) - - - - activeQueueSubs / pendingQueueSubs - (TMap SMPServer (TMap QueueId ...)) - activeServiceSubs / pendingServiceSubs - (TMap SMPServer (TVar (Maybe ...))) + smpClients + (TMap SMPServer SMPClientVar) - + + + smpSubWorkers + (one per server) + + + + reconnect + + + + activeQueueSubs / pendingQueueSubs + (TMap SMPServer (TMap QueueId ...)) + activeServiceSubs / pendingServiceSubs + (TMap SMPServer (TVar (Maybe ...))) + - - - - smpSubWorkers - (one per server) - - - - reconnect + resubscribe - - - getSMPServerClient'': get or create client - connectClient: create ProtocolClient, register disconnect handler - on disconnect: filter by SessionId, move active → pending, notify agentQ, spawn worker - worker: retry connect with backoff, resubscribe pending subs - subscribeQueuesNtfs / subscribeServiceNtfs: subscribe + track state - - - ProtocolClient connections (one per SMP Router) + ProtocolClient connections (one per SMP Router) - - ProtocolClient - → SMP Router A + ProtocolClient + → SMP Router A - - ProtocolClient - → SMP Router B + ProtocolClient + → SMP Router B - - ProtocolClient - → SMP Router N + ProtocolClient + → SMP Router N - ... + ... - - + + getSMPServerClient'': get or create client + connectClient: create ProtocolClient, register disconnect handler + on disconnect: filter by SessionId, move active to pending, notify agentQ, spawn worker + worker: retry connect with backoff, resubscribe pending subs + subscribeQueuesNtfs / subscribeServiceNtfs: subscribe + track state + - - - ProtocolClient + ProtocolClient - - state / queue + state / queue - - background worker + background worker - - Solid arrows: TBQueue flow. Dashed: reconnection / resubscription. + + Solid arrows: TBQueue flow. Dashed: reconnection. diff --git a/spec/diagrams/smp-client.svg b/spec/diagrams/smp-client.svg index d537ec8d0..754c41c89 100644 --- a/spec/diagrams/smp-client.svg +++ b/spec/diagrams/smp-client.svg @@ -1,4 +1,4 @@ - + @@ -10,139 +10,160 @@ - - SMP Client (ProtocolClient) -- Component Topology - - - per connection (raceAny_ -- any thread exit tears down connection) + per connection (raceAny_: any exit tears down all threads) - - caller - (Agent/ - router) + + + monitor + optional - - API (PING via sendProtocolCommand) --> + + PING + + + + + caller + (Agent / + router) + + + - commands + + + + sendProtocolCommand + mkTransmission + + + - - sndQ - (TBQueue, 64) + sndQ + (TBQueue, 64) - - - send + send - - Router (exits per-connection box) --> + + + + SMP + Router + (TLS) + + + + + + insert + + + + sentCommands + (TMap CorrId Request) + + + + responseVar + (TMVar) + + + - - receive - - - - - - SMP - Router - (TLS) + receive - - - rcvQ - (TBQueue, 64) + rcvQ + (TBQueue, 64) + + - + + + match + - - process + process - - - sentCommands - (TMap CorrId Request) + - - - match - - - - responseVar - (TMVar) - - - - monitor - - - - PING - - - optional - - - - msgQ (optional) - (TBQueue, server events) - - - msgQ --> + - events (empty CorrId) + events + + + + msgQ (optional) + (TBQueue, server events) - - to Agent / SMPClientAgent + to Agent / SMPClientAgent - - - thread + thread - - queue / state + queue / state - + API entry point + + - optional + optional - + Solid arrows: TBQueue flow. Dashed: STM lookups / TMVar responses. diff --git a/spec/diagrams/smp-router.svg b/spec/diagrams/smp-router.svg index 09a198bc9..819da8a36 100644 --- a/spec/diagrams/smp-router.svg +++ b/spec/diagrams/smp-router.svg @@ -10,13 +10,10 @@ - - SMP Router -- Component Topology - - per client connection (raceAny_ -- any thread exit tears down connection) + per client connection (raceAny_: any exit tears down connection) - - XFTP Client -- Component Topology - diff --git a/spec/diagrams/xftp-router.svg b/spec/diagrams/xftp-router.svg index 6f13221f9..5a5146275 100644 --- a/spec/diagrams/xftp-router.svg +++ b/spec/diagrams/xftp-router.svg @@ -10,9 +10,6 @@ - - XFTP Router -- Component Topology - diff --git a/spec/routers.md b/spec/routers.md index b66c52ce4..6e8be5e8b 100644 --- a/spec/routers.md +++ b/spec/routers.md @@ -12,7 +12,7 @@ For deployment and configuration, see [docs/ROUTERS.md](../docs/ROUTERS.md). For ### Component topology -![SMP Router — Component Topology](diagrams/smp-router.svg) +![SMP Router - Component Topology](diagrams/smp-router.svg) ### Packet delivery flow @@ -74,7 +74,7 @@ sequenceDiagram ### Component topology -![XFTP Router — Component Topology](diagrams/xftp-router.svg) +![XFTP Router - Component Topology](diagrams/xftp-router.svg) ### Data packet delivery flow @@ -124,7 +124,7 @@ sequenceDiagram ### Component topology -![NTF Router — Component Topology](diagrams/ntf-router.svg) +![NTF Router - Component Topology](diagrams/ntf-router.svg) ### Token registration and notification delivery