### Initialize and Run smp-server

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Provides commands for initializing and starting the smp-server. Initialization can be done using FQDN or IP address. The server can be started directly or configured as a service. It also mentions optional Tor setup for onion addresses.

```bash
# Initialize SMP server with smp-server init [-l] -n <fqdn> or smp-server init [-l] --ip <ip>
# Run smp-server start to start SMP server
# For Tor setup: smp://<fingerprint>@<public_hostname>,<onion_hostname>
# For help: smp-server -h and smp-server init -h
```

--------------------------------

### Install SimpleX Chat for Terminal

Source: https://github.com/simplex-chat/simplexmq/blob/stable/apps/smp-server/static/i/index.html

Installs the SimpleX Chat application for the terminal using a curl command to download and execute an installation script from GitHub.

```bash
curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/master/install.sh | bash
```

--------------------------------

### Install SimpleX Chat for Terminal

Source: https://github.com/simplex-chat/simplexmq/blob/stable/apps/smp-server/static/a/index.html

Installs the SimpleX Chat application for the terminal using a curl command to download and execute an installation script from GitHub.

```bash
curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/master/install.sh | bash
```

--------------------------------

### Install SimplexMQ Server using Script

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Downloads and executes a shell script to automatically install and set up SimplexMQ servers. Includes a SHA-256 checksum verification for the script.

```Shell
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/simplex-chat/simplexmq/stable/install.sh -o simplex-server-install.sh &&\
if echo '53fcdb4ceab324316e2c4cda7e84dbbb344f32550a65975a7895425e5a1be757 simplex-server-install.sh' | sha256sum -c; then
  chmod +x ./simplex-server-install.sh
  ./simplex-server-install.sh
  rm ./simplex-server-install.sh
else
  echo "SHA-256 checksum is incorrect!"
  rm ./simplex-server-install.sh
fi
```

--------------------------------

### Install SimpleX Chat for Terminal

Source: https://github.com/simplex-chat/simplexmq/blob/stable/apps/smp-server/static/link.html

Installs the SimpleX Chat application for the terminal using a curl command to download and execute an installation script from GitHub.

```bash
curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/master/install.sh | bash
```

--------------------------------

### Install Packer on macOS

Source: https://github.com/simplex-chat/simplexmq/blob/stable/scripts/smp-server-digitalocean-droplet/README.md

Installs the Packer tool on macOS using Homebrew, including tapping the HashiCorp repository.

```shell
brew tap hashicorp/tap
brew install hashicorp/tap/packer
```

--------------------------------

### Install SimpleX Chat for Terminal

Source: https://github.com/simplex-chat/simplexmq/blob/stable/apps/smp-server/static/c/index.html

Installs the SimpleX Chat application for the terminal using a curl command to download and execute an installation script from GitHub.

```bash
curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/master/install.sh | bash
```

--------------------------------

### SimplexMQ Short Link Examples

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2024-06-21-short-links.md

Provides examples of short invitation links for SimplexMQ, demonstrating different configurations and their approximate lengths. These examples illustrate the impact of including onion addresses and server domains.

```APIDOC
https://simplex.chat/contact/#0YuTwO05YJWS8rkjn9eLJDjQhFKvIYd8d4xG8X1blIU=@smp8.simplex.im/abcdefghij0123456789abcdefghij0123456789abc=

https://smp8.simplex.im/contact/#0YuTwO05YJWS8rkjn9eLJDjQhFKvIYd8d4xG8X1blIU@/abcdefghij0123456789abcdefghij0123456789abc

https://smp8.simplex.im/contact/#0YuTwO05YJWS8rkjn9eLJDjQhFKvIYd8d4xG8X1blIU@beccx4yfxxbvyhqypaavemqurytl6hozr47wfc7uuecacjqdvwpw2xid.onion/abcdefghij0123456789abcdefghij0123456789abc
```

--------------------------------

### Install SimpleX Chat for Terminal

Source: https://github.com/simplex-chat/simplexmq/blob/stable/apps/smp-server/static/contact/index.html

Installs the SimpleX Chat application for the terminal using a curl command to download and execute an installation script from GitHub.

```bash
curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/master/install.sh | bash
```

--------------------------------

### Install SimpleX Chat for Terminal

Source: https://github.com/simplex-chat/simplexmq/blob/stable/apps/smp-server/static/invitation/index.html

Installs the SimpleX Chat application for the terminal using a curl command to download and execute an installation script from GitHub.

```bash
curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/master/install.sh | bash
```

--------------------------------

### SimplexMQ Protocol - Setup Phase

Source: https://github.com/simplex-chat/simplexmq/blob/stable/notes-flow.txt

Describes the initial handshake process between the proxy (p) and the remote server (r), and the reply from the remote server back to the client (s). This phase establishes secure communication channels.

```APIDOC
Setup Phase:

1. Client (s) initiates connection to proxy (p):
   s->p: "proxy", uri, auth?
   # This occurs unless already connected.

2. Proxy (p) handshakes with remote server (r):
   p->r: "p_handshake"
   p<-r: "r_key", tls-signed dh pub
   # The reply contains the entityId with tlsUniq.

3. Remote server (r) replies to client (s):
   s<-r: "r_key", tls-signed dh pub
   # This reply includes the entityId which contains tlsUniq.
```

--------------------------------

### SimplexMQ Queue Initialization Logic

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2024-09-01-smp-message-storage.md

Illustrates the C-like pseudocode for initializing a queue when it's first requested by the server. It covers scenarios where the queue folder exists or needs to be created, including initial file setup and state logging.

```c
if queue folder exists:
    read queue state from last line of queue.log
    if queue.log contained more than one line: // compaction
        copy queue.log to queue.timestamp.log
        write one line queue state to queue.log
else:
    create queue folder
    create messages.abcd.log (abcd is some random string)
    read_msg = 0
    read_byte = 0
    create queue.log with one line: "read_file=abcd read_msg=0 read_byte=0 write_files=abcd write_msg=0"
open read_file in ReadMode and seek to read_byte position
nextReadByte = read_byte
nextReadMsg = read_msg
open write_file in AppendMode
```

--------------------------------

### SimplexMQ Example Contact Link (Preset Server)

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2025-03-16-smp-queues.md

An example of a contact connection link for a preset SimplexMQ server, showing the structure with a link key.

```URL
https://smp12.simplex.im/c#abcdefghij0123456789abcdefghij0123456789abc
```

--------------------------------

### SimplexMQ Example One-Time Link

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2025-03-16-smp-queues.md

An example of a one-time connection link for a preset SimplexMQ server, demonstrating the structure with a link ID and key.

```URL
https://smp12.simplex.im/i#abcdefghij0123456789abcdefghij0123456789abcdefghij01234
```

--------------------------------

### Install OpenSSL on Ubuntu

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Installs the OpenSSL package on Ubuntu systems, which is a runtime dependency for smp-server and xftp-server.

```Shell
# For Ubuntu
apt update && apt install openssl
```

--------------------------------

### SimplexMQ Example Contact Link (User-Defined Server)

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2025-03-16-smp-queues.md

An example of a contact connection link for a user-defined SimplexMQ server, including a certificate fingerprint parameter.

```URL
https://smp1.example.com/c#abcdefghij0123456789abcdefghij0123456789abc?c=0YuTwO05YJWS8rkjn9eLJDjQhFKvIYd8d4xG8X1blIU
```

--------------------------------

### Install Haskell Dependencies and Build Tools

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Installs necessary dependencies and build tools for Haskell development on Ubuntu, including GHC and cabal, using ghcup for version management.

```bash
# On Ubuntu. Depending on your distribution, use your package manager to determine package names.
sudo apt-get update && apt-get install -y build-essential curl libffi-dev libffi7 libgmp3-dev libgmp10 libncurses-dev libncurses5 libtinfo5 pkg-config zlib1g-dev libnuma-dev libssl-dev
export BOOTSTRAP_HASKELL_GHC_VERSION=9.6.3
export BOOTSTRAP_HASKELL_CABAL_VERSION=3.10.3.0
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | BOOTSTRAP_HASKELL_NONINTERACTIVE=1 sh
ghcup set ghc "${BOOTSTRAP_HASKELL_GHC_VERSION}"
ghcup set cabal "${BOOTSTRAP_HASKELL_CABAL_VERSION}"
source ~/.ghcup/env
```

--------------------------------

### SimplexMQ Example Contact Link (User-Defined Server with Onion)

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2025-03-16-smp-queues.md

An example of a contact connection link for a user-defined SimplexMQ server, including both a certificate fingerprint and an onion hostname parameter.

```URL
https://smp1.example.com/c#abcdefghij0123456789abcdefghij0123456789abc?c=0YuTwO05YJWS8rkjn9eLJDjQhFKvIYd8d4xG8X1blIU&h=beccx4yfxxbvyhqypaavemqurytl6hozr47wfc7uuecacjqdvwpw2xid.onion
```

--------------------------------

### SimpleX Messaging Protocol Initialization

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/overview-tjr.md

Describes the initial setup of SMP, involving an introduction message with server details, queue ID, and public keys for end-to-end encryption. It highlights the uni-directional nature of queues and the server's role in managing sender/recipient queues and DH exchanges for message re-encryption.

```APIDOC
SMP Initialization:
  - Alice provides Bob with server details (IP/hostname, port, certificate hash), queue ID, and public keys.
  - Establishes end-to-end encryption.
  - Queues are uni-directional.
  - Server creates separate sender and recipient queue IDs.
  - Alice performs DH exchange with the server for shared secret to re-encrypt Bob's incoming messages.
```

--------------------------------

### macOS OpenSSL Check and Install

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Verifies the OpenSSL version on macOS and provides instructions to install the original OpenSSL if LibreSSL is detected, which is required for SMP server initialization.

```Shell
openssl version
brew update
brew install openssl
echo 'PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"' >> ~/.zprofile
. ~/.zprofile
```

--------------------------------

### SimplexMQ Key Agreement Pseudocode

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/done/2023-10-25-remote-control.md

Illustrates the key agreement process for session establishment in SimplexMQ using DH and KEM keys, including initial setup and subsequent sessions. It shows how shared secrets are derived for encryption.

```pseudocode
// session 1
hostHelloSecret(1) = dhSecret(1)
sessionSecret(1) = sha256(dhSecret(1) || kemSecret(1)) // to encrypt session 1 data, incl. controller hello
dhSecret(1) = dh(hostHelloDhKey(1), controllerInvitationDhKey(1))
kemCiphertext(1) = enc(kemSecret(1), kemEncKey(1))
// kemEncKey is included in host HELLO, kemCiphertext - in controller HELLO
kemSecret(1) = dec(kemCiphertext(1), kemDecKey(1))

// multicast announcement for session n
announcementSecret(n) = sha256(dhSecret(n'))
dhSecret(n') = dh(hostHelloDhKey(n - 1), controllerDhKey(n))

// session n
hostHelloSecret(n) = dhSecret(n)
sessionSecret(n) = sha256(dhSecret(n) || kemSecret(n)) // to encrypt session n data, incl. controller hello
dhSecret(n) = dh(hostHelloDhKey(n), controllerDhKey(n))
// controllerDhKey(n) is either from invitation or from multicast announcement
kemCiphertext(n) = enc(kemSecret(n), kemEncKey(n))
kemSecret(n) = dec(kemCiphertext(n), kemDecKey(n))
```

--------------------------------

### INI Configuration for SimplexMQ Transport and Web Server

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2024-09-15-shared-port.md

Provides INI file examples for configuring the SimplexMQ transport port and web server settings, including paths to TLS certificates and keys. Demonstrates alternative configurations for shared ports and explicit transport setup.

```INI
[TRANSPORT]
port: 443

[WEB]
https: 443
cert: /etc/opt/simplex/web.cert
key: /etc/opt/simplex/web.key

# Alternatively, with a proper access configuration, the paths can point to the LE creds directly:
# cert: /etc/letsencrypt/live/smp.hostname.tld/fullchain.pem
# key: /etc/letsencrypt/live/smp.hostname.tld/privkey.pem
```

```INI
[TRANSPORT]
port: 5223 ; pure protocol transport
# control_port: 5224
shared_port: 443 ; variant 1: register in TRANSPORT

[WEB]
https: 443
cert: /etc/opt/simplex/web.cert
key: /etc/opt/simplex/web.key
# transport: on ; variant 2:
```

--------------------------------

### SMP Agent Introduction Commands

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/rejected/2021-05-23-introduction.md

Defines the commands used by an agent client to introduce one connection to another. These commands facilitate the out-of-band channel establishment.

```APIDOC
C:idAB INTRO C:idAM infoM
  Initiates the introduction of connection cIdB to connection cIdM.
  Parameters:
    - C:idAB: The ID of the agent initiating the introduction.
    - INTRO: The command keyword for introduction.
    - C:idAM: The ID of the target connection to be introduced to.
    - infoM: Information about the target connection.
  Response:
    - C:idAB OK: Confirmation of the introduction initiation.

C:idBA REQ C:invId infoM
  Notification to confirm an introduction.
  Parameters:
    - C:idBA: The ID of the agent sending the request.
    - REQ: The command keyword for request.
    - C:invId: The invitation ID.
    - infoM: Information about the target connection.

C:idBM? ACPT C:invId
  Accepts an offer to be introduced.
  Parameters:
    - C:idBM: The ID of the agent accepting the introduction.
    - ACPT: The command keyword for accept.
    - C:invId: The invitation ID.
  Response:
    - C:idBM OK: Confirmation of acceptance.
    - C:idBM CON: Confirmation that the connection is established.

C:idBM CON
  Confirms that the connection is established to both introduced parties.
  Parameters:
    - C:idBM: The ID of the agent confirming the connection.
    - CON: The command keyword for confirmation.

C:idAB CON C:idAM
  Confirms that the connection is established to the introducer.
  Parameters:
    - C:idAB: The ID of the introducer agent.
    - CON: The command keyword for confirmation.
    - C:idAM: The ID of the established connection.
```

--------------------------------

### SimplexMQ Introduction Commands

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/rejected/protocol_overview.md

Facilitates introductions between connections. Includes commands for initiating introductions, requesting confirmation, accepting offers, and establishing connections between introduced parties.

```APIDOC
C:idAB INTRO C:idAM infoM
  - Introduces connection cIdB to connection cIdM.
  - Response: OK.

C:idBA REQ C:invId infoM
  - Notification to confirm an introduction.

C:idBM? ACPT C:invId
  - Accepts an offer to be introduced.
  - Response: cIdBM OK, followed by ICON.

C:idBM CON
  - Confirmation that a connection is established to both introduced parties.

C:idAB CON C:idAM
  - Confirmation that a connection is established to the introducer.
```

--------------------------------

### Deploy SMP Server on DigitalOcean

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Instructions for deploying an SMP server on DigitalOcean using their 1-click app. This involves creating a DigitalOcean account, launching the SimpleX Server droplet, and obtaining the server fingerprint.

```text
1. Create a DigitalOcean account or login.
2. Click 'Create SimpleX server Droplet' button.
3. Choose region and plan.
4. Finalize Droplet creation.
5. Open "Console" to get SMP server fingerprint or SSH to the Droplet.
6. Connect using `smp://<fingerprint>@<ip_address>`.
```

--------------------------------

### SimplexMQ Introduction Protocol Sequence Diagram

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/rejected/2021-05-23-introduction.md

Visual representation of the SimplexMQ introduction protocol flow, detailing message exchanges and connection establishment between Alice, Bob, Mark, and their respective agents.

```mermaid
sequenceDiagram
  participant A as Alice (A) - the introducer
  participant AA as Alice's<br>agent (AA)
  participant B as Bob (B) - introduced
  participant BA as Bob's<br>agent (BA)
  participant M as Mark (M) - introduced to
  participant MA as Mark's<br>agent (MA)

  note over A, AA: 1. create introduction
  A --> AA: C:idAB INTRO C:idAM infoM<br>(idAB - conn alias A has for B,<br>idAM - for M)
  AA --> A: C:idAB OK

  note over A, BA: 2. send intro to Bob

  AA --> BA: via idAB: INTRO C:extIntroIdM prv:introBM infoB
  BA --> B: C:idBA REQ C:intIntroIdM infoM
  B --> BA: C:idBM? ACCT C:intIntroIdM
  BA --> B: C:idBM OK

  note over BA: 3. create connection for  M idBM

  BA --> AA: via idBA: INV C:extIntroIdM prv:invBM infoB

  note over AA, M: 4. send intro to Mark

  AA --> MA: via idAM: REQ C:extIntroIdB prv:invBM infoB

  note over MA, B: 5. Mark connects to Bob

  MA --> M: C:idMA REQ C:intIntroIdB infoB
  M --> MA: C:idMB? ACPT C:intIntroIdB
  MA --> M: C:idMB OK

  MA --> BA:  establish connection idBM -> idMA

  note over A, MA: 6. notify all clients

  MA --> M: C:idMB CON
  MA --> AA: via idMA: CON C:extIntroIdB
  BA --> B: C:idBM CON
  BA --> AA: via idBA: CON C:extIntroIdB
  AA --> A: C:idAB CON C:idAM
```

--------------------------------

### Simplexmq Queue Blob Retrieval Protocol (GET Command)

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2024-09-09-smp-blobs.md

Defines the ABNF syntax for the GET command used to retrieve queue blobs from Simplexmq. It also specifies the format of the BLOB response.

```abnf
get = %s"GET"

blobs = %s"BLOB" senderId [ "0" blob0 ] [ "1" blob1 ] [ "2" blob2 ]
```

--------------------------------

### Build DigitalOcean SMP Server Image

Source: https://github.com/simplex-chat/simplexmq/blob/stable/scripts/smp-server-digitalocean-droplet/README.md

Builds the SMP server image for DigitalOcean using Packer. Requires setting the DIGITALOCEAN_TOKEN environment variable.

```shell
cd ./scripts/smp-server-digitalocean-droplet
DIGITALOCEAN_TOKEN=$YOUR_TOKEN packer build -on-error=ask -color=false ./marketplace-image.json
```

--------------------------------

### Message Processing Strategies (GET vs SUB)

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/done/2022-06-13-db-sync.md

Explores different strategies for NSE to process incoming messages, including using SUB, GET, and variations of ACK, along with their respective downsides and potential optimizations.

```APIDOC
Message Processing Options for NSE:

1. SUB:
   - Process messages normally.
   - Downside: Requires app to resubscribe and track state.

2. GET:
   - Process messages by pushing them through the processing function.
   - Downside: Requires rewiring of message processing.
   - Variant: GET with ACK variations (one that never delivers new message, one that does) to handle message processing flow.
   - Batched commands support is considered a valuable addition.

3. GET with Queue Delivery:
   - Agent function returns a flag indicating message receipt instead of the message itself.
   - Message is also sent to the queue.

4. Manual Agent Processing:
   - Process messages in the agent manually and via the queue for chat.
```

--------------------------------

### List Compiled Simplexmq Binaries

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Lists the compiled binary paths for smp-server and xftp-server using the cabal list-bin command.

```bash
cabal list-bin exe:smp-server
cabal list-bin exe:xftp-server
```

--------------------------------

### Concurrency Handling in NSE GET Calls

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/done/2022-06-13-db-sync.md

Addresses the concurrency issue where multiple GET calls for the same queue might occur before the previous one finishes processing, proposing a solution to differentiate calls and ensure unique message delivery.

```APIDOC
NSE Concurrency Handling for GET:

Problem: Multiple notifications from the same queue arriving before the previous one finishes processing.

Solution:
- Agent should queue GET calls to ensure they return different messages.
- GET calls should include the previous message ID if available.
- GET call should return message flags (including notification flag) to allow UI to send the next GET if needed without waiting.
```

--------------------------------

### Initialize SMP Server

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Initializes the SMP server, generating keys and certificates for TLS transport. Supports IP-based addressing and optional store log for persistence.

```Shell
smp-server init -n <fqdn>
smp-server init --ip <ip>
smp-server -l
smp-server --help
```

--------------------------------

### Restart Tor Service

Source: https://github.com/simplex-chat/simplexmq/blob/stable/scripts/tor/README.md

Command to restart the Tor system service after modifying its configuration.

```sh
sudo systemctl restart tor
```

--------------------------------

### Retrieve SimplexMQ Onion Address

Source: https://github.com/simplex-chat/simplexmq/blob/stable/scripts/tor/README.md

Command to display the SimplexMQ onion address, which is stored in a file after Tor configuration.

```sh
sudo cat /var/lib/tor/simplex-smp/hostname
```

--------------------------------

### Run XFTP Server Docker Container

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Deploys the XFTP server using a Docker container. Requires specifying the server address and maximum storage quota. Mounts local directories for configuration, logs, and file storage.

```Docker
docker run -d \
    -e "ADDR=your_ip_or_domain" \
    -e "QUOTA=maximum_storage" \
    -p 443:443 \
    -v $HOME/simplex/xftp/config:/etc/opt/simplex-xftp:z \
    -v $HOME/simplex/xftp/logs:/var/opt/simplex-xftp:z \
    -v $HOME/simplex/xftp/files:/srv/xftp:z \
    simplexchat/xftp-server:latest
```

--------------------------------

### Get Queue State Information

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/simplex-messaging.md

Retrieves debugging information about the current state of a queue. The response is 'INFO' followed by JSON-encoded queue information.

```ABNF
getQueueInfo = %s"QUE"
queueInfo = %s"INFO " info
info = <json encoded queue information>
```

```JSON
{
  "properties": {
    "qiSnd": {"type": "boolean"},
    "qiNtf": {"type": "boolean"},
    "qiSize": {"type": "uint16"}
  },
  "optionalProperties": {
    "qiSub": {
      "properties": {
        "qSubThread": {"enum": ["noSub", "subPending", "subThread", "prohibitSub"]}
      },
      "optionalProperties": {
        "qDelivered": {"type": "string", "metadata": {"description": "message ID"}}
      }
    },
    "qiMsg": {
      "properties": {
        "msgId": {"type": "string"},
        "msgTs": {"type": "timestamp"},
        "msgType": {"enum": ["message", "quota"]}
      }
    }
  }
}
```

--------------------------------

### Get Message Command

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/simplex-messaging.md

Retrieves a single message from the queue without subscribing. This command is intended for processing push notifications. It cannot be used on the same queue and transport connection as the SUB command.

```ABNF
getMessage = %s"GET"
```

--------------------------------

### Deploy SMP Server on Linode

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Steps to deploy an SMP server on Linode using their StackScripts. This includes creating a Linode account, using the SMP server StackScript, configuring optional parameters like API tokens and domain names, and connecting to the deployed server.

```text
1. Create a Linode account or login with an already existing one.
2. Open [SMP server StackScript](https://cloud.linode.com/stackscripts/748014) and click "Deploy New Linode".
3. Optionally configure parameters: SMP Server store log flag, Linode API token, Domain name.
4. Choose region and plan (1Gb Nanode is sufficient).
5. Provide SSH key.
6. Deploy your Linode and wait for the SMP server to start.
7. Get 'address' and 'fingerprint' from Linode tags or via SSH.
8. Connect using `smp://<fingerprint>@<fqdn>` or `smp://<fingerprint>@<ip_address>`.
```

--------------------------------

### XFTP Client Initialization and ALPN Negotiation

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/done/2024-03-28-xftp-version.md

Configures the transport client with the XFTP ALPN marker and initiates the HTTP/2 client handshake. It negotiates the XFTP protocol version based on the server's ALPN response.

```haskell
let tcConfig = (transportClientConfig xftpNetworkConfig) {alpn = Just ["xftp/1"]}
-- ...
http2Client <- liftEitherError xftpClientError $ getVerifiedHTTP2Client -- ...
thVersion <- case sessionALPN http2Client of
  Nothing -> pure $ VersionXFTP 1
  Just proto -> negotiate http2Client proto
```

--------------------------------

### Tor Configuration for SimplexMQ

Source: https://github.com/simplex-chat/simplexmq/blob/stable/scripts/tor/README.md

This snippet shows the necessary modifications to the `/etc/tor/torrc` file to configure Tor for SimplexMQ. It includes disabling anonymous mode, setting the HiddenService directory, and mapping the SimplexMQ port (5223) to the Tor service.

```sh
SOCKSPort 0
HiddenServiceNonAnonymousMode 1
HiddenServiceSingleHopMode 1

# Specify folder for smp-tor
## Folder for keys, address, etc.
HiddenServiceDir /var/lib/tor/simplex-smp/
## Map smp port (5223) to tor
HiddenServicePort 5223 localhost:5223
```

--------------------------------

### Build Simplexmq Project with Cabal

Source: https://github.com/simplex-chat/simplexmq/blob/stable/README.md

Builds the smp-server and xftp-server executables for the Simplexmq project using cabal after cloning the repository and checking out the stable branch.

```bash
git clone https://github.com/simplex-chat/simplexmq
cd simplexmq
git checkout stable
cabal update
cabal build exe:smp-server exe:xftp-server
```

--------------------------------

### SimpleXMQ Error Response Format

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/push-notifications.md

Defines the ABNF syntax for error responses in SimpleXMQ commands. Error responses start with 'ERR' followed by a space and an error type, which follows the syntax defined in the SimpleX Messaging Protocol.

```APIDOC
errorResp = %s"ERR" SP errorType
```

--------------------------------

### SMP Commands Overview

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/simplex-messaging.md

This section outlines the various commands used in the Simplex Messaging Protocol (SMP) for client-server communication. It covers command verification, keep-alive mechanisms, and different categories of commands for recipients, senders, proxies, and notifiers.

```APIDOC
SMP Commands:

Correlating responses with commands:
  - Mechanism for matching server responses to client commands.

Command verification:
  - Ensures the integrity and authenticity of commands.

Keep-alive command:
  - Used to maintain active connections and detect disconnections.

Recipient Commands:
  - Create queue command: Creates a new simplex queue.
  - Subscribe to queue: Allows a client to subscribe to messages on a queue.
  - Secure queue by recipient: Secures a queue for a specific recipient.
  - Enable notifications command: Enables message delivery notifications.
  - Disable notifications command: Disables message delivery notifications.
  - Get message command: Retrieves a message from a queue.
  - Acknowledge message delivery: Confirms successful message receipt.
  - Suspend queue: Temporarily pauses message delivery to a queue.
  - Delete queue: Removes a queue and its contents.
  - Get queue state: Retrieves the current status of a queue.

Sender Commands:
  - Secure queue by sender: Secures a queue for a specific sender.
  - Send message: Transmits a message to a queue.

Proxying sender commands:
  - Request proxied session: Initiates a session for proxying commands.
  - Send command via proxy: Sends a command through a proxy.
  - Forward command to destination server: Relays a command to the intended destination server.

Notifier Commands:
  - Subscribe to queue notifications: Subscribes to notifications for queue events.

Server Messages:
  - Deliver queue message: Server sends a message to a subscribed client.
  - Deliver message notification: Server sends a notification about message delivery.
  - Subscription END notification: Server indicates the end of a subscription.
  - Error responses: Server returns error information.
  - OK response: Server acknowledges a successful command execution.
```

--------------------------------

### SimplexMQ Queue Folder Path Example

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/2024-09-01-smp-message-storage.md

Illustrates a proposed folder path structure for SimplexMQ messages, where the recipient queue ID is split into multiple path fragments. This approach aims to optimize file system performance by limiting the depth of directory trees.

```Shell
/var/opt/simplex/messages/abcd/efgh/ijkl/mnop/qrst/uvwx/yz01/2345
```

```Shell
/var/opt/simplex/messages/ab/cd/ef/ghijklmnopqrstuvwxyz012345
```

```Shell
/var/opt/simplex/messages/ab/cd/ef/gh/ijklmnopqrstuvwxyz012345
```

--------------------------------

### SMP Protocol Commands for Duplex Connection

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/agent-protocol.md

Illustrates the core SMP (Simplex Messaging Protocol) commands used by the agents to interact with the SMP servers during the duplex connection establishment.

```APIDOC
NEW
  - Command used by SMP agents to create a new SMP queue on the server.
  - Used by Agent A and Agent B during connection setup.

SEND
  - Command used to send messages via an SMP queue.
  - Used for sending confirmations, keys, and HELLO messages between agents.

MSG
  - Represents receiving a message from an SMP queue.
  - Agent A receives Bob's confirmation via MSG.

KEY
  - Command used to secure an SMP queue with encryption keys.
  - Used by Agent A and Agent B to secure their respective queues.

CONF
  - Notification sent to Alice by Agent A, containing Bob's information.

HELLO
  - Message exchanged between agents to confirm that queues are secured and the connection is validated.

CON
  - Notification sent to both Alice and Bob indicating that the duplex connection is established.
```

--------------------------------

### SimplexMQ PQDR Encryption Scenarios

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/agent-protocol.md

Illustrates possible connection stages and PQ key agreement states in SimplexMQ, indicating feasibility with '+' and impossibility with '-'. Covers invitation, confirmation, and message exchange stages.

```APIDOC
Connection stage                                       | No PQ key        | PQ key sent      | PQ key + PQ ct sent
-------------------------------------------------------|------------------|------------------|-------------------
invitation                                             |         +        |         +        |          -
confirmation, in reply to: <br>no-pq inv <br>pq inv    | &nbsp;<br>+<br>+ | &nbsp;<br>+<br>- | &nbsp;<br>-<br>+
1st msg, in reply to: <br>no-pq conf <br>pq/pq+ct conf | &nbsp;<br>+<br>+ | &nbsp;<br>+<br>- | &nbsp;<br>-<br>+
Nth msg, in reply to: <br>no-pq msg <br>pq/pq+ct msg   | &nbsp;<br>+<br>+ | &nbsp;<br>+<br>- | &nbsp;<br>-<br>+
```

--------------------------------

### Fast SMP Procedure for Queue Creation

Source: https://github.com/simplex-chat/simplexmq/blob/stable/protocol/simplex-messaging.md

Details the 'Fast SMP' procedure which allows the sender to create and send messages to a queue without waiting for the recipient to be online.

```APIDOC
APIDOC:
  Fast SMP Procedure:
    - In step 1.5 of the SMP procedure, set sndSecure parameter to 'T' (true) to allow sender securing the queue.
    - In step 2, the SMP queue URI must include a parameter indicating the sender can secure the queue.
    - In step 3.2, Bob secures the queue using the SKEY command before sending the confirmation message.
    - The confirmation message is sent with sender authorization, enabling Bob to send messages without Alice being online.
```

--------------------------------

### SMP Protocol Commands for Push Notifications

Source: https://github.com/simplex-chat/simplexmq/blob/stable/rfcs/done/2022-06-05-smp-notifications.md

Defines new SMP commands for handling push notifications on iOS. GET retrieves a single message, while ACK/GACK acknowledges message processing. These commands aim to streamline message delivery to notification service extensions without causing resubscriptions.

```APIDOC
GET
  - Retrieves one message from the connection.
  - Response: MSG (similar to regular MSG, with correlation id) or GMSG (simplified processing).
  - If message is not available: ERR NO_MSG

ACK or GACK
  - Acknowledges that the message was processed by the client and can be removed.
  - Response: OK or ERR NO_MSG (if nothing to acknowledge).
  - Choice between ACK and GACK to be determined during implementation.
```