mirror of
https://github.com/simplex-chat/simplexmq.git
synced 2026-03-30 14:16:00 +00:00
106 lines
4.9 KiB
Markdown
106 lines
4.9 KiB
Markdown
# SimpleXMQ repository
|
|
|
|
This file provides guidance on the project structure to help working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
SimpleXMQ is a Haskell message broker implementing unidirectional (simplex) queues for privacy-preserving messaging.
|
|
|
|
Key components:
|
|
|
|
- **SimpleX Messaging Protocol**: SMP protocol definition and encodings ([code](../src/Simplex/Messaging/Protocol.hs), [transport code](../src/Simplex/Messaging/Transport.hs), [spec](../protocol/simplex-messaging.md)).
|
|
- **SMP Server**: Message broker with TLS, in-memory queues, optional persistence ([main code](../src/Simplex/Messaging/Server.hs), [all code files](../src/Simplex/Messaging/Server/), [executable](../apps/smp-server/)). For proxying SMP commands the server uses [lightweight SMP client](../src/Simplex/Messaging/Client/Agent.hs).
|
|
- **SMP Client**: Functional API with STM-based message delivery ([code](../src/Simplex/Messaging/Client.hs)).
|
|
- **SMP Agent**: High-level duplex connections via multiple simplex queues with E2E encryption ([code](../src/Simplex/Messaging/Agent.hs)). Implements Agent-to-agent protocol ([code](../src/Simplex/Messaging/Agent/Protocol.hs), [spec](../protocol/agent-protocol.md)) via intermediary agent client ([code](../src/Simplex/Messaging/Agent/Client.hs)).
|
|
- **XFTP**: SimpleX File Transfer Protocol, server and CLI client ([code](../src/Simplex/FileTransfer/), [spec](../protocol/xftp.md)).
|
|
- **XRCP**: SimpleX Remote Control Protocol ([code](../src/Simplex/RemoteControl/), [spec](../protocol/xrcp.md)).
|
|
- **Notifications**: Push notifications server requires PostgreSQL ([code](../src/Simplex/Messaging/Notifications), [executable](../apps/ntf-server/)). Client protocol is used for clients to communicate with the server ([code](../src/Simplex/Messaging/Notifications/Protocol.hs), [spec](../protocol/push-notifications.md)). For subscribing to SMP notifications the server uses [lightweight SMP client](../src/Simplex/Messaging/Client/Agent.hs).
|
|
|
|
## Architecture
|
|
|
|
For general overview see `../protocol/overview-tjr.md`.
|
|
|
|
SMP Protocol Layers:
|
|
|
|
```
|
|
TLS Transport → SMP Protocol → Agent Protocol → Application protocol
|
|
```
|
|
|
|
XFTP Protocol Layers:
|
|
|
|
```
|
|
TLS Transport (HTTP2 encoding) → XFTP Protocol → Out-of-band file descriptions
|
|
```
|
|
|
|
## Key Patterns
|
|
|
|
1. **Persistence**: All queue state managed via Software Transactional Memory or via PostgreSQL
|
|
- `Simplex.Messaging.Server.MsgStore.STM` - in-memory messages
|
|
- `Simplex.Messaging.Server.QueueStore.STM` - in-memory queue state
|
|
- `Simplex.Messaging.Server.MsgStore.Postgres` - message storage
|
|
- `Simplex.Messaging.Server.QueueStore.Postgres` - queue storage
|
|
|
|
2. **Append-Only Store Log**: Optional persistence via journal for in-memory storage
|
|
- `Simplex.Messaging.Server.StoreLog` - queue creation log
|
|
- Compacted on restart
|
|
|
|
3. **Agent Storage**:
|
|
- SQLite (default) or PostgreSQL
|
|
- Migrations in `src/Simplex/Messaging/Agent/Store/{SQLite,Postgres}/Migrations/`
|
|
|
|
4. **Protocol Versioning**: All layers support version negotiation
|
|
- `Simplex.Messaging.Version` - version range utilities
|
|
|
|
5. **Double Ratchet E2E**: Per-connection encryption
|
|
- `Simplex.Messaging.Crypto.Ratchet`
|
|
- SNTRUP761 post-quantum KEM (`src/Simplex/Messaging/Crypto/SNTRUP761/`)
|
|
|
|
## Source Layout
|
|
|
|
```
|
|
src/Simplex/
|
|
├── Messaging/
|
|
│ ├── Agent.hs # Main agent (~210KB)
|
|
│ ├── Server.hs # SMP server (~130KB)
|
|
│ ├── Client.hs # Client API (~65KB)
|
|
│ ├── Protocol.hs # Protocol types (~77KB)
|
|
│ ├── Crypto.hs # E2E encryption (~52KB)
|
|
│ ├── Transport.hs # Transport encoding over TLS
|
|
│ ├── Agent/Store/ # SQLite/Postgres persistence
|
|
│ ├── Server/ # Server internals (QueueStore, MsgStore, Control)
|
|
│ └── Notifications/ # Push notification system
|
|
├── FileTransfer/ # XFTP implementation for file transfers
|
|
└── RemoteControl/ # XRCP implementation for device discovery & control
|
|
```
|
|
|
|
## Protocol Documentation
|
|
|
|
- `protocol/overview-tjr.md`: SMP protocols stack overview
|
|
- `protocol/simplex-messaging.md`: SMP protocol spec (v19)
|
|
- `protocol/agent-protocol.md`: Agent protocol spec (v7)
|
|
- `protocol/xftp.md`: File transfer protocol
|
|
- `protocol/xrcp.md`: Remote control protocol
|
|
- `rfcs/`: Design RFCs for features
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
cabal test --test-show-details=streaming
|
|
|
|
# Run specific test group (uses HSpec)
|
|
cabal test --test-option=--match="/Core tests/Encryption tests/"
|
|
|
|
# Run single test
|
|
cabal test --test-option=--match="/SMP client agent/functional API/"
|
|
```
|
|
|
|
Tests require PostgreSQL running on `localhost:5432` when using `-fserver_postgres` or `-fclient_postgres`.
|
|
|
|
Test files are in `tests/` with structure:
|
|
- `Test.hs`: Main runner
|
|
- `AgentTests/`: Agent protocol and connection tests
|
|
- `CoreTests/`: Crypto, encoding, storage tests
|
|
- `ServerTests.hs`: SMP server tests
|
|
- `XFTPServerTests.hs`: File transfer tests
|