simplexmq/rfcs/protocol_overview.md

# Overview of SMP agent protocol commands

## Connections

### Commands and messages

A initiates connection, B accepts

- command `C:idB? NEW` - create connection
- message `C:idB INV cInv`
- command `C:idA? JOIN cInv replyMode` - join connection (response `OK`, followed by `CON`)
- *message* `C:idB REQ prv:invId infoB` - request from B joining sent to A (not implemented)
- *command* `C:idB ACPT prv:invId` - A confirms B joining (not implemented)
- message `C:id CON` - connection is established
- command `C:id SUB` - subscribe to connection
- message `C:id END` - unsubscribed from connection
- command `C:idB SEND msg` - send message
- message `C:idA SENT msgId` - confirmation that the message is sent
- message `C:id MSG msgId msgMeta msgIntegrity msgBody` - received message
- *command* `C:idB ACK msgId` - acknowledge message reception (not implemented)
- *message* `C:idA RCVD msgId msgIntegrity` - confirmation of message reception and integrity (not implemented)
- command `C:id OFF` - suspend connection
- command `C:id DEL` - delete connection
- message `C:id? OK` - command confirmation
- message `C:id? ERR e` - error

### Envelopes

- `MSG `
- `HELLO verificationKey ackMode`
- `REPLY replyInv`

## Broadcasts

### Commands & messages

- command `B:id? NEW` - create broadcast (response is `B:id OK`)
- command `B:id SEND msg` - broadcast message (response is multiple `C:id SENT msgId` or ERR, separately for each connection, followed by `B:id SENT msgId` once sent to all)
- message `B:id SENT msgId` - notification that the message is sent and its internal ID, same as SENT
- command `B:id ADD cId` - add existing connection to a broadcast (response is `B:id OK` or `ERR`, e.g. if bId is used)
- command `B:id REM cId` - remove connection from the broadcast (response is `REMD`)
- message `B:id REMD cId` - connection removed from the broadcast
- message `B:id EMPTY` - all connections were removed from the broadcast
- command `B:id DEL` - delete broadcast (response is `B:id OK`)
- command `B:id LS` - list connections in broadcast, response is `B:id MEM space_separated_connections`
- message `B:id MEM space_separated_connections`

## Open/public connection

### Commands

- command `O:id? NEW` - create open connection
- message `O:id INV oInv` - open invitation
- command `C:id? JOIN oInv replyMode` - join connection (response `OK`, followed by `CON`)
- message `O:id REQ open:invId infoB` - confirmation from B joining sent to A
- command `C:idC? ACPT open:invId` - note, that it creates new connection, keeping OPEN connection
- command `O:id SUB` - subscribe to open connection
- message `O:id END` - unsubscribed from open connection
- command `O:id OFF` - suspend open connection
- command `O:id DEL` - delete open connection
- message `O:id? OK` - command confirmation
- message `O:id? ERR e` - error

## Introductions

### Commands

- command `C:idAB INTRO C:idAM infoM` - introduce connection cIdB to connection cIdM (response is `OK`)
- message `C:idBA REQ C:invId infoM` - notification to confirm introduction
- command `C:idBM? ACPT C:invId` - accept offer to be introduced (response is `cIdBM OK`, followed by `ICON`)
- message `C:idBM CON` - confirmation that connection is established to both introduced parties
- message `C:idAB CON C:idAM` - confirmation that connection is established to the introducer

### Envelopes

- `INTRO C:extIntroIdM infoM` - new introduction offered by introducer
- `INV C:extIntroIdB prv:invBM infoB` - invitation to join connection from B to M sent via A (can be pub:)
- `REQ C:extIntroIdB prv:invBM infoB` - new introduction forwarded by introducer
- `CON C:extIntroIdM` - confirmation that the connection is established sent by both introduced parties to the introducer

## Groups

## Agent commands and messages syntax

- command `G:gId? NEW` - create group (response is `G:gId OK`)
- command `C:cId INTRO G:gId gInfo` - add existing connection to a group
- message `C:cId REQ g:invID gInfo` - invitation to join the group
- command `G:gId? ACPT g:invId` - accept invitation (response is `G gId OK`)
- message `G:gId CON C:cId` - 2 connections created with some group member (both for group and direct messages)
- message `G:gId MEM [C:cId]` - connection created with all group members for a given member or current client
- command `G:gId SEND msg` - send message to group
- message `G:gId SENT msgId` - notification that the message is sent and its internal ID, same as SENT
- message `G:gId MSG C:cId msgId msgdata` - received group message from cId, msgdata is the same set of parameters as in `MSG`
- command `G:gId ACK msgId` - acknowledge message reception by the client
- message `G:gId RCVD t:cId msgId status` - message delivery notification
- command `G:gId LEAVE` - leave the group
- message `G:gId LEFT [C:cId]` - connection cId left the group
- command `G:gId REM C:cId` - remove group member (response is `gId OK`, followed by `GREMD` notification)
- message `G:gId REMD C:cId [C:cId]` - member removed
- message `G:gId OUT C:cId` - you are removed (see question below - should it be just a sequence of GLEFT?)
- message `G:gId EMPTY` - all members left the group and it is now empty
- command `G:gId DEL` - delete the group (response is `gId OK`)
- message `G:gId DELD [C:cId]` - group deleted

## Agent message envelopes syntax

- `GROUP C:mid G:inv gInfo` - invitation to join the group
- `MEM C:mid` - confirmation that member connected to all members
- `LEFT` - notification that member left the group
- `OUT` - you are removed from the group
- `REM C:mid` - remove member mid from the group
- `REMD C:mid` - confirmation that member is removed
- `DEL` - group is deleted
- `DELD` - confirmation that group is deleted

## Commands and objects

| Dir     | Command / message    | (C)onnection | (O)pen connection | (B)roadcast | (G)roup |
|:---------:|:--------------------:|:------------:|:-----------------:|:-----------:|:-------:|
| command | `t:id? NEW`           | ✓ | ✓ | ✓ | ✓ |
| command | `C:id INTRO t:id info` | ✓ | - | - | ✓ |
| message | `t:id INV inv`        | ✓ | ✓ | - | - |
| command | `C:id? JOIN inv replyMode info` | ✓ | - | - | - |
| message | `t:id REQ invId info` | ✓ | ✓ | - | ✓ |
| command | `t:id? ACPT invId`    | ✓ | - | - | ✓ |
| message | `t:id CON [C:id]`     | ✓ | - | - | ✓ |
| message | `t:id MEM [C:id]`     | - | - | - | ✓ |
| command | `t:id SUB`            | ✓ | ✓ | - | ✓ |
| message | `t:id END`            | ✓ | ✓ | - | ✓ |
| command | `t:id OFF`            | ✓ | ✓ | - | - |
| command | `t:id DEL`            | ✓ | ✓ | ✓ | ✓ |
| message | `t:id DELD [C:Id]`    | ✓ | ✓ | ✓ | ✓ |
| command | `t:id SEND msg`       | ✓ | - | ✓ | ✓ |
| message | `t:id SENT [t':id] msgId` | ✓ | - | ✓ | ✓ |
| message | `t:id MSG [C:id] msgId msgdata` | ✓ | - | - | ✓ |
| command | `t:id ACK msgId`      | ✓ | - | - | ✓ |
| message | `t:id RCVD [t':id] msgId status` | ✓ | - | - | ✓ |
| command | `t:id ADD C:id`       | - | - | - | ✓ |
| command | `t:id REM C:id`       | - | - | ✓ | ✓ |
| command | `t:id REMD C:id`      | - | - | ✓ | ✓ |
| message | `t:id EMPTY`          | - | - | ✓ | ✓ |
| message | `G:id OUT C:id`       | - | - | - | ✓ |
| command | `t:id LS`             | - | - | ✓ | ✓ |
| message | `t:id MS cIds`        | - | - | ✓ | ✓ |
| command | `G:id LEAVE`          | - | - | - | ✓ |
| message | `G:id LEFT [C:id]`    | - | - | - | ✓ |