update protocols (#190)

Co-authored-by: Efim Poberezkin <8711996+efim-poberezkin@users.noreply.github.com>
2026-03-29 20:59:59 +00:00 · 2021-09-07 15:25:04 +01:00
parent e07bedac0e
commit d973c834a5
4 changed files with 84 additions and 29 deletions
--- a/protocol/agent-protocol.md
+++ b/protocol/agent-protocol.md
@@ -16,9 +16,10 @@
  - [Client commands and server responses](#client-commands-and-server-responses)
    - [NEW command and INV response](#new-command-and-inv-response)
    - [JOIN command](#join-command)
-    - [CON notification](#con-notification)
+    - [REQ notification and ACPT command](#req-notification-and-acpt-command)
+    - [INFO and CON notifications](#info-and-con-notifications)
    - [SUB command](#sub-command)
-    - [SEND command and SENT response](#send-command-and-sent-response)
+    - [SEND command and MID, SENT and MERR responses](#send-command-and-mid-sent-and-merr-responses)
    - [MSG notification](#msg-notification)
    - [END notification](#end-notification)
    - [OFF command](#off-command)
@@ -73,18 +74,22 @@ SMP agent protocol has 3 main parts:
 The procedure of establishing a duplex connection is explained on the example of Alice and Bob creating a bi-directional connection comprised of two unidirectional (simplex) queues, using SMP agents (A and B) to facilitate it, and two different SMP servers (which could be the same server). It is shown on the diagram above and has these steps:

 1. Alice requests the new connection from the SMP agent A using `NEW` command.
-2. Agent A creates an SMP queue on the server (using [SMP protocol](./simplex-messaging.md)) and responds to Alice with the invitation that contains queue information and the encryption key Bob's agent B should use. The invitation format is described in [Connection invitation](#connection-invitation).
+2. Agent A creates an SMP connection on the server (using [SMP protocol](./simplex-messaging.md)) and responds to Alice with the invitation that contains queue information and the encryption key Bob's agent B should use. The invitation format is described in [Connection invitation](#connection-invitation).
 3. Alice sends the invitation to Bob via any secure channel they have (out-of-band message).
 4. Bob sends `JOIN` command with the invitation as a parameter to agent B to accept the connection.
-5. Establishing Alice's SMP queue (with SMP protocol commands):
-  - Agent B sends unauthenticated message to SMP queue with ephemeral key that will be used to authenticate commands to the queue, as described in SMP protocol.
-  - Agent A receives the KEY and secures the queue.
+5. Establishing Alice's SMP connection (with SMP protocol commands):
+  - Agent B sends an "SMP confirmation" to the SMP queue specified in the invitation - SMP confirmation is an unauthenticated message with an ephemeral key that will be used to authenticate Bob's commands to the queue, as described in SMP protocol, and Bob's info.
+  - Agent A receives the SMP confirmation containing Bob's key and info.
+  - Agent A notifies Alice sending REQ notification with Bob's info.
+  - Alice accepts connection request with ACPT command.
+  - Agent A secures the queue.
  - Agent B tries sending authenticated SMP SEND command with agent `HELLO` message until it succeeds. Once it succeeds, Bob's agent "knows" the queue is secured.
 6. Agent B creates a new SMP queue on the server.
 7. Establish Bob's SMP queue:
  - Agent B sends `REPLY` message with the invitation to this 2nd queue to Alice's agent (via the 1st queue).
-  - Agent A having received this `REPLY` message sends unauthenticated message to SMP queue with Alice agent's ephemeral key that will be used to authenticate commands to the queue, as described in SMP protocol.
-  - Bob's agent receives the key and secures the queue.
+  - Agent A, having received this `REPLY` message, sends unauthenticated message to SMP queue with Alice agent's ephemeral key that will be used to authenticate Alice's commands to the queue, as described in SMP protocol, and Alice's info.
+  - Bob's agent receives the key and Alice's information and secures the queue.
+  - Bob's agent sends the notification `INFO` with Alice's information to Bob.
  - Alice's agent keeps sending `HELLO` message until it succeeds.
 8. Agents A and B notify Alice and Bob that connection is established.
  - Once sending `HELLO` succeeds, Alice's agent sends to Alice `CON` notification that confirms that now both parties can communicate.
@@ -193,13 +198,25 @@ cId = encoded
 cName = 1*(ALPHA / DIGIT / "_" / "-")

 agentCommand = (userCmd / agentMsg) CRLF
-userCmd = newCmd / joinCmd / subscribeCmd / sendCmd / acknowledgeCmd / suspendCmd / deleteCmd
-agentMsg = invitation / connected / unsubscribed / message / sent / received / ok / error
+userCmd = newCmd / joinCmd / acceptCmd / subscribeCmd / sendCmd / acknowledgeCmd / suspendCmd / deleteCmd
+agentMsg = invitation / connRequest / connInfo / connected / unsubscribed / connDown / connUp / messageId / sent / messageError / message / received / ok / error

 newCmd = %s"NEW" [SP %s"NO_ACK"] ; response is `invitation` or `error`
+; NO_ACK parameter currently not supported

 invitation = %s"INV" SP <queueInfo> ; `queueInfo` is the same as in out-of-band message, see SMP protocol

+connRequest = %s"REQ" SP confirmationId SP msgBody
+; msgBody here is any binary information identifying connection request
+
+confirmationId = 1*DIGIT
+
+acceptCmd = %s"ACPT" SP confirmationId SP msgBody
+; msgBody here is any binary information identifying connecting party
+
+connInfo = %s"INFO" SP msgBody
+; msgBody here is any binary information identifying connecting party
+
 connected = %s"CON"

 subscribeCmd = %s"SUB" ; response is `ok` or `error`
@@ -208,6 +225,12 @@ unsubscribed = %s"END"
 ; when another agent (or another client of the same agent)
 ; subscribes to the same SMP queue on the server

+connDown = %s"DOWN"
+; lost connection (e.g. because of Internet connectivity or server is down)
+
+connUp = %s"UP"
+; restored connection
+
 joinCmd = %s"JOIN" SP <queueInfo> [SP %s"NO_REPLY"] [SP %s"NO_ACK"]
 ; `queueInfo` is the same as in out-of-band message, see SMP protocol
 ; response is `connected` or `error`
@@ -225,18 +248,22 @@ binaryMsg = size CRLF msgBody CRLF ; the last CRLF is in addition to CRLF in the
 size = 1*DIGIT ; size in bytes
 msgBody = *OCTET ; any content of specified size - safe for binary

+messageId = %s"MID" SP agentMsgId
+
 sent = %s"SENT" SP agentMsgId

+messageError = %s"MERR" SP agentMsgId SP <errorType>
+
 message = %s"MSG" SP msgIntegrity SP recipientMeta SP brokerMeta SP senderMeta SP binaryMsg
 recipientMeta = %s"R=" agentMsgId "," agentTimestamp ; receiving agent message metadata 
 brokerMeta = %s"B=" brokerMsgId "," brokerTimestamp ; broker (server) message metadata
 senderMeta = %s"S=" agentMsgId "," agentTimestamp ; sending agent message metadata 
 brokerMsgId = encoded
 brokerTimestamp = <date-time>
-msgIntegrity = ok / messageError
+msgIntegrity = ok / msgIntegrityError

-messageError = %s"ERR" SP messageErrorType
-messageErrorType = skippedMsgErr / badMsgIdErr / badHashErr
+msgIntegrityError = %s"ERR" SP msgIntegrityErrorType
+msgIntegrityErrorType = skippedMsgErr / badMsgIdErr / badHashErr

 skippedMsgErr = %s"NO_ID" SP missingFromMsgId SP missingToMsgId
 badMsgIdErr = %s"ID" SP previousMsgId ; ID is lower than the previous
@@ -247,7 +274,6 @@ missingToMsgId = agentMsgId
 previousMsgId = agentMsgId

 acknowledgeCmd = %s"ACK" SP agentMsgId ; ID assigned by receiving agent (in MSG "R")
-; currently not implemented

 received = %s"RCVD" SP agentMsgId ; ID assigned by sending agent (in SENT response)
 ; currently not implemented
@@ -261,27 +287,41 @@ error = %s"ERR" SP <errorType>

 #### NEW command and INV response

-`NEW` command is used to create a connection and an invitation to be sent out-of-band to another protocol user. It should be used by the client of the agent that initiates creating a duplex connection.
+`NEW` command is used to create a connection and an invitation to be sent out-of-band to another protocol user (the joining party). It should be used by the client of the agent that initiates creating a duplex connection (the initiating party).

-`INV` response is sent by the agent to the client.
+`INV` response is sent by the agent to the client of the initiating party.

 #### JOIN command

-It is used to create a connection and accept the invitation received out-of-band. It should be used by the client of the agent that accepts the connection.
+It is used to create a connection and accept the invitation received out-of-band. It should be used by the client of the agent that accepts the connection (the joining party).

-#### CON notification
+#### REQ notification and ACPT command

-It is sent by both agents managing duplex connection to their clients once the connection is established and ready to accept client messages.
+When the joining party uses `JOIN` command, the initiating party will receive `REQ` notification with some numeric identifier and an additional binary information, that can be used to identify the joining party or for any other purpose.
+
+To continue with the connection the initiating party should use `ACPT` command.
+
+#### INFO and CON notifications
+
+After the initiating party proceeds with the connection using `ACPT` command, the joining party will receive `INFO` notification that can be used to identify the initiating party or for any other purpose.
+
+Once the connection is established and ready to accept client messages, both agents will send `CON` notification to their clients.

 #### SUB command

 This command can be used by the client to resume receiving messages from the connection that was created in another TCP/client session. Agent response to this command can be `OK` or `ERR` in case connection does not exist (or can only be used to send connections - e.g. when the reply queue was not created).

-#### SEND command and SENT response
+#### SEND command and MID, SENT and MERR responses

-`SEND` command is used to the client to send messages
+`SEND` command is used by the client to send messages.

-`SENT` response is sent by the agent to confirm that the message was delivered to the SMP server. Message ID in this response is the sequential message number that includes both sent and received messages in the connection.
+`MID` notification with the message ID (the sequential message number that includes both sent and received messages in the connection) is sent to the client to confirm that the message is accepted by the agent, before it is sent to the SMP server.
+
+`SENT` response is sent by the agent to confirm that the message was delivered to the SMP server. This notification contains the same message ID as `MID` notification. `SENT` notification, depending on network availability, can be sent at any time later, potentially in the next client session.
+
+In case of the failure to send the message for any other reason than network connection or message queue quota - e.g. authentication error (`ERR AUTH`) or syntax error (`ERR CMD error`), the agent will send to the client `MERR` notification with the message ID, and this message delivery will no longer be attempted.
+
+In case of client disconnecting from the agent, the pending messages will not be sent until the client re-connects to the agent and subscribes to the connection that has pending messages.

 #### MSG notification

@@ -294,6 +334,12 @@ It is sent by the agent to the client when agent receives the message from the S

 It is sent by the agent to the client when agent receives SMP protocol `END` notification from SMP server. It indicates that another agent has subscribed to the same SMP queue on the server and the server terminated the subscription of the current agent.

+#### DOWN and UP notifications
+
+These notifications are sent when server or network connection is, respectively, `DOWN` or back `UP`.
+
+All the subscriptions made in the current client session will be automatically resumed when `UP` notification is received.
+
 #### OFF command

 It is used to suspend the receiving SMP queue - sender will no longer be able to send the messages to the connection, but the recipient can retrieve the remaining messages. Agent response to this command can be `OK` or `ERR`. This command is irreversible.
--- a/protocol/diagrams/duplex-messaging/duplex-creating.mmd
+++ b/protocol/diagrams/duplex-messaging/duplex-creating.mmd
@@ -27,11 +27,14 @@ sequenceDiagram
  note over BA: status: NONE/NEW

  note over BA, AA: 5. establish Alice's SMP queue
-  BA ->> AS: SEND: KEY: sender's server key
+  BA ->> AS: SEND: Bob's info and sender server key (SMP confirmation)
  note over BA: status: NONE/CONFIRMED
  activate BA
-  AS ->> AA: MSG: KEY: sender's server key
+  AS ->> AA: MSG: Bob's info and<br>sender server key
  note over AA: status: CONFIRMED/NONE
+  AA ->> AS: ACK: confirm message
+  AA ->> A: REQ: connection request ID<br>and Bob's info
+  A ->> AA: ACPT: accept connection request,<br>send Alice's info
  AA ->> AS: KEY: secure queue
  note over AA: status: SECURED/NONE

@@ -40,6 +43,7 @@ sequenceDiagram
  note over BA: status: NONE/ACTIVE
  AS ->> AA: MSG: HELLO: Alice's agent<br>knows Bob can send
  note over AA: status: ACTIVE/NONE
+  AA ->> AS: ACK: confirm message

  note over BA, BS: 6. create Bob's SMP queue
  BA ->> BS: NEW: create SMP queue
@@ -51,12 +55,15 @@ sequenceDiagram
  note over BA: status: PENDING/ACTIVE
  AS ->> AA: MSG: REPLY: invitation<br>to connect
  note over AA: status: ACTIVE/NEW
+  AA ->> AS: ACK: confirm message

-  AA ->> BS: SEND: KEY: sender's server key
+  AA ->> BS: SEND: Alice's info and sender's server key
  note over AA: status: ACTIVE/CONFIRMED
  activate AA
-  BS ->> BA: MSG: KEY: sender's server key
+  BS ->> BA: MSG: Alice's info and<br>sender's server key
  note over BA: status: CONFIRMED/ACTIVE
+  BA ->> B: INFO: Alice's info
+  BA ->> BS: ACK: confirm message
  BA ->> BS: KEY: secure queue
  note over BA: status: SECURED/ACTIVE

@@ -65,6 +72,7 @@ sequenceDiagram
  note over AA: status: ACTIVE/ACTIVE
  BS ->> BA: MSG: HELLO: Bob's agent<br>knows Alice can send
  note over BA: status: ACTIVE/ACTIVE
+  BA ->> BS: ACK: confirm message

  note over A, B: 8. notify users about connection success
  AA ->> A: CON: connected
--- a/protocol/diagrams/duplex-messaging/duplex-creating.svg
+++ b/protocol/diagrams/duplex-messaging/duplex-creating.svg
--- a/protocol/simplex-messaging.md
+++ b/protocol/simplex-messaging.md
@@ -410,7 +410,7 @@ secure = %s"KEY" SP senderKey
 senderKey = %s"rsa:" x509encoded ; the sender's RSA public key for this queue
 ```

-`senderKey` is received from the sender as part of the first message - see [Send Message Command](#send-message-command).
+`senderKey` is received from the sender as part of the first message - see [Send Message](#send-message) command.

 Once the queue is secured only signed messages can be sent to it.

@@ -535,7 +535,8 @@ No further messages should be delivered to unsubscribed transport connection.
  - transmission has no required signature or queue ID (`NO_AUTH`)
  - transmission has unexpected credentials (`HAS_AUTH`)
  - transmission has no required queue ID (`NO_QUEUE`)
- authentication error (`AUTH`) - incorrect signature, unknown (or suspended) queue, sender's ID is used in place of recipient's and vice versa, and some other cases (see [Send message command](#send-message-command)).
+- authentication error (`AUTH`) - incorrect signature, unknown (or suspended) queue, sender's ID is used in place of recipient's and vice versa, and some other cases (see [Send message](#send-message) command).
+- message queue quota exceeded error (`QUOTA`) - too many messages were sent to the message queue. Further messages can only be sent after the recipient retrieves the messages.
 - incorrect message body size (`SIZE`).
 - internal server error (`INTERNAL`).