From a35d3cbeb91d2104cd65d1d9f1f85936b4c2b6bc Mon Sep 17 00:00:00 2001 From: akwizgran Date: Thu, 22 Mar 2018 13:41:47 +0000 Subject: [PATCH] Update ForumSharingClient --- Forum-Sharing-Client.md | 45 ++++++++++++++++++++++++++++ ForumSharingClient.md | 66 ----------------------------------------- 2 files changed, 45 insertions(+), 66 deletions(-) create mode 100644 Forum-Sharing-Client.md delete mode 100644 ForumSharingClient.md diff --git a/Forum-Sharing-Client.md b/Forum-Sharing-Client.md new file mode 100644 index 0000000..a4e4a0c --- /dev/null +++ b/Forum-Sharing-Client.md @@ -0,0 +1,45 @@ +The forum sharing client is a [BSP client](BSP) that allows users to share forums with their contacts, who may accept or decline the invitations. + +### Group identifiers + +The client's identifier is `org.briarproject.briar.forum.sharing`. + +The client uses a separate group for each pair of contacts. The [group descriptor](BSP#group-identifiers) is a [BDF list](BDF) containing the unique IDs of the contacts' identities, sorted in ascending order as byte strings. + +### Message types + +The sharing protocol uses five message types. All communication happens solely between the inviter and the invitee. The messages referring to each forum constitute a session. + +**0: INVITE** - Sent by the inviter to the invitee. The message body is a BDF list with four elements: `messageType` (int), `previousMessageId` (unique ID or null), `descriptor` (list), and `message` (string or null). + +`previousMessageId` is the ID of the previous message in this session, if any. `descriptor` is the [descriptor of the forum](Forum-Client#group-identifiers) being shared. `message` is an optional message from the inviter to the invitee. The forum ID must be calculated from the descriptor, as it is used by subsequent messages in the session. + +The inviter sets the forum's visibility to VISIBLE when sending an invite message. + +**1: ACCEPT** - Sent by the invitee to the inviter in response to an invite. The message body is a BDF list with three elements: `messageType` (int), `forumId` (unique ID), and `previousMessageId` (unique ID). + +The invitee sets the forum's visibility to SHARED when sending an accept message. The inviter sets the forum's visibility to SHARED when receiving an accept message. + +**2: DECLINE** - Sent by the invitee to the inviter in response to an invite. The message body is a BDF list with three elements: `messageType` (int), `forumId` (unique ID), and `previousMessageId` (unique ID). + +The inviter sets the forum's visibility to INVISIBLE when receiving a decline message. + +**3: LEAVE** - Sent by either party when unsubscribing from the forum, if the forum's visibility is VISIBLE or SHARED. The message body is a BDF list with three elements: `messageType` (int), `forumId` (unique ID), and `previousMessageId` (unique ID). + +The sender sets the forum's visibility to INVISIBLE when sending a leave message. The recipient sets the forum's visibility to INVISIBLE when receiving a leave message. + +**4: ABORT** - Sent by either party when recieving a message that is valid but unexpected in the current state. The message body is a BDF list with three elements: `messageType` (int), `forumId` (unique ID), and `previousMessageId` (unique ID). + +The sender sets the forum's visibility to INVISIBLE when sending an abort message. The recipient sets the forum's visibility to INVISIBLE when receiving an abort message. + +### Validity policy + +* A message is valid if it is well-formed. + +### Storage policy + +* All messages are stored. + +### Sharing policy + +* All local messages are shared. diff --git a/ForumSharingClient.md b/ForumSharingClient.md deleted file mode 100644 index f9d31bf..0000000 --- a/ForumSharingClient.md +++ /dev/null @@ -1,66 +0,0 @@ -The Forum Sharing Client is a [BSP client](BSP) that allows to share forums with other contacts. These have the option to accept or decline the invitation to the forum. - -### Group identifiers - -The Forum Sharing Client uses the following client identifier: -`cd11 a5d0 4dcc d9e2 931d 6fc3 df45 6313 63bb 3e9d 9d0e 9405 fccd b051 f41f 5449` - -The client uses a separate group for each pair of contacts. The [group descriptor](BSP#group-identifiers) is a [BDF list](BDF) containing the unique IDs of the contacts' identities, sorted in ascending order as byte strings. - -### Message types - -The sharing protocol uses five message types. It should be noted that all communication happens solely between the sharer and the contacts she invites. - -1: **INVITATION** - This is send by the sharer to one of her contacts. The content is a BDF list. -* (int) The type of the message, here 1 -* (raw) SessionId chosen by the sharer -* (string) name of the forum -* (raw) salt to uniquely identify this forum -* (string) optional invitation message - -2: **ACCEPT RESPONSE** - This should be sent by contacts that received a sharing invitation. The content is a BDF list with these elements: -* (int) The type of the message, here 2 -* (raw) SessionId must match the SessionId of an unanswered invitation. - -3: **DECLINE RESPONSE** - This should be sent by contacts that received a sharing invitation and do not want to add the forum. The content is a BDF list with these elements: -* (int) The type of the message, here 3 -* (raw) SessionId must match the SessionId of an unanswered invitation. - -4: **LEAVE** - This should be send by a contact that is unsubscribing from the forum. The content is a BDF list with two elements: -* (int) The type of the message, here 4 -* (raw) SessionId must match the SessionId of a previous (un)answered invitation. - -5: **ABORT** - This should be send by a contact that encountered an error, so that it can not complete the protocol. The content is a BDF list with two elements: -* (int) The type of the message, here 5 -* (raw) SessionId must match the SessionId of an unanswered invitation. - -A successful run of the protocol would look like this: - -![forum-sharing](/uploads/8f53758e8ed55146f498181b2708a9b1/forum-sharing.png) - -**Sharer** - -![sharer-state-machine](/uploads/5ca0924c21eef0601e5cfdf4060577ad/sharer-state-machine.png) - -[sharer-state-machine.odg](/uploads/24354e5ef7779d36ed7a815eccb8f35e/sharer-state-machine.odg) - -**Invitee** - -![invitee-state-machine](/uploads/b57dc42ebe5873530543ce7ab36af8f4/invitee-state-machine.png) - -[invitee-state-machine.odg](/uploads/2099baeb7948980819022fda5f402aed/invitee-state-machine.odg) - -Arrows that have no label stand for 'all other actions'. - -### Validity policy - -* A message is valid if it is well-formed. - -### Storage policy - -Since the messages represent the current state of the introduction protocol, all participants need to hold on to their messages as long as the protocol did not complete or fail permanently. - -### Sharing policy - -* All local messages are shared. -* All remote messages are shared. \ No newline at end of file