@@ -10,11 +10,11 @@ BSP synchronises data among dynamic sets of **devices**. Each device has a dynam
Data is organised into **groups**. Each group is an independent synchronisation scope containing a **message graph** made up of immutable **messages**.
If a device takes part in synchronising a group's messages, we say the device is a **member** of the group. If two peers synchronise a group's messages with each other, we say they **share** the group with each other. Group membership and sharing are dynamic. Peers that are members of a group do not necessarily share it with each other.
If a device takes part in synchronising a group's messages, we say the device is a **member** of the group. If two peers synchronise a group's messages with each other, we say they **share** the group with each other. Group membership and sharing are dynamic. Devices that are members of a group are not necessarily each other's peers, and peers that are members of a group do not necessarily share it with each other.
Each member of a group stores a partial copy of the message graph. Each message in the partial copy of the graph may be **shared** or **deleted**. If a message is shared, the device will synchronise the message to any peers with which it shares the group. If a message is deleted, the device will delete its copy of the message but retain some information about the message's position in the graph.
Each member of a group stores a copy of the message graph, which may be incomplete. Each message in the member's copy of the graph may be **shared** or **deleted**. If a message is shared, the device will synchronise the message to any peers with which it shares the group. If a message is deleted, the device will delete its copy of the message but retain some information about the message's position in the graph.
Each group belongs to a **client**, which is an application component that uses BSP to synchronise data. The client is responsible for deciding which peers the group should be shared with, what constitutes a valid message, which messages should be shared, and which messages should be deleted. BSP implements these decisions on behalf of the client.
Each group belongs to a **client**, which is an application component that uses BSP to synchronise data. The client is responsible for deciding which peers the group should be shared with, what constitutes a valid message, which messages should be shared, and which messages should be deleted. BSP carries out these decisions on behalf of the client.
### 1.2 Transport Layer Security
...
...
@@ -49,7 +49,7 @@ Each client is identified by a namespaced string. The namespace is based on doma
BSP uses a major/minor numbering scheme to distinguish between versions of each client.
The client identifier and major version are included in the calculation of group identifiers, so different major versions of a given client use distinct groups, whereas different minor versions use the same groups.
The client identifier and major version are included when calculating group identifiers, so different major versions of a given client use distinct groups, whereas different minor versions use the same groups.
The major version is used to indicate backward-incompatible changes. A client may send a message that another client with the same identifier but a different major version would not be able to handle. The use of distinct groups for each major version makes this safe.
...
...
@@ -63,13 +63,13 @@ Each group has a unique identifier HASH\_LEN bytes long. The identifier is calcu
The group format version is 1 for the current version of BSP.
The group descriptor is supplied by the client and is not interpreted by BSP. The maximum length of a group descriptor is 16 KiB.
The group descriptor is supplied by the client. BSP treats it as an opaque byte string without interpreting its contents. The maximum length of a group descriptor is 16 KiB.
### 2.4 Messages
A message consists of a byte string called the **message body** and a timestamp indicating the time at which the message was created, represented in milliseconds since the Unix epoch.
The message body is supplied by the client and is not interpreted by BSP. The maximum length of a message body is 32 KiB.
The message body is supplied by the client. BSP treats it as an opaque byte string without interpreting its contents. The maximum length of a message body is 32 KiB.
Each message has a unique identifier HASH\_LEN bytes long. The identifier is calculated by hashing the group identifier, timestamp and message body:
...
...
@@ -128,11 +128,15 @@ The device may also store a list of message identifiers that have been offered b
### 4.2 Synchronisation Modes
Each time a device has an opportunity to send records to a peer, it decides whether to use ***interactive mode*** or***batch mode***.
Each time a device has an opportunity to send records to a peer, it decides whether to use ***interactive mode***,***batch mode*** or ***eager mode***.
Interactive mode uses less bandwidth than batch mode, but needs two round-trips for synchronisation, whereas batch mode needs one.
Interactive mode uses less bandwidth than the other modes, but needs two round-trips for synchronisation, whereas the other modes need one round-trip. Interactive mode is generally suitable for transports with relatively short round-trip times, such as TCP.
The device may choose a mode based on prior knowledge or measurements of the underlying transport, such as the round-trip time, or it may use any other method. Devices may use different methods from their peers.
Batch mode uses more bandwidth than interactive mode, but less than eager mode. It is generally suitable for transports with relatively long round-trip times and low risk of data loss, where it is better to wait for an acknowledgement before resending a message.
Eager mode uses more bandwidth than the other modes. It is generally suitable for transports with relatively long round-trip times and high risk of data loss, where it is better to resend a message at the next opportunity than to wait for an acknowledgement.
The device may choose a mode based on prior knowledge or measurements of the underlying transport, such as the round-trip time, or it may use any other method. Devices may use different methods of choosing modes than their peers.
##### 4.2.1 Interactive Mode
...
...
@@ -156,11 +160,17 @@ In batch mode, messages are sent without being offered. The device does the foll
-**Acknowledge** any messages **offered** by the peer that the device has seen and has not yet acknowledged
-**Request** any messages **offered** by the peer that the device has not seen and has not yet requested
-**Send** any messages that the device is **sharing** with the peer, and does not know whether the peer has seen, and that are ready to send
-**Send** any messages that the device is **sharing** with the peer, that have been **requested** by the peer, and that are ready to send
#### 4.2.3 Eager Mode
-**Send** any messages that the device is **sharing** with the peer, and does not know whether the peer has seen, and that are ready to send
In eager mode, messages are sent without being offered, and may be resent immediately. The device does the following, in any order:
-**Acknowledge** any messages **sent** by the peer that the device has not yet acknowledged
-**Acknowledge** any messages **offered** by the peer that the device has seen and has not yet acknowledged
-**Send** any messages that the device is **sharing** with the peer, and does not know whether the peer has seen, regardless of whether they are ready to send
### 4.3 Retransmission
...
...
@@ -174,12 +184,12 @@ A message is considered **ready to send** if either its send time has been reach
## 5 The Message Graph
Each group belongs to a client that is responsible for deciding which peers the group should be shared with, what constitutes a valid message, which messages should be shared, and which messages should be deleted.
Each group belongs to a client that is responsible for deciding which peers the group should be shared with, what constitutes a valid message, which messages should be shared, and which messages should be deleted. The messages in the group form a message graph.
The message graph is a directed graph where each message points to its **dependencies**. The list of dependencies is encoded in the message body in a format determined by the client. Since messages are immutable, dependency relationships are also immutable and the graph is acyclic. The graph may have more than one component.
When a device receives a message for the first time, the client responsible for the corresponding group parses the message body and extracts a list of dependencies. BSP uses the list of dependencies to determine the message's position in the message graph. If the client cannot parse the message, BSP marks it as invalid and deletes it. Any messages that transitively depend on it are also marked as invalid and deleted.
A message is eligible to be **delivered** to the client when all its dependencies have been delivered. This provides**causal consistency**. When a message is delivered, the client validates the message in the context of its dependencies. If the client decides the message is invalid, BSP marks it as invalid and deletes it. Any messages that transitively depend on it are also marked as invalid and deleted.
A message is eligible to be **delivered** to the client when all its dependencies have been delivered. Thus on every device in the group, messages are delivered to the client in a consistent order, even if the messages arrive at different devices in different orders. This can be used to implement**causal consistency**. When a message is delivered, the client validates the message in the context of its dependencies. If the client decides the message is invalid, BSP marks it as invalid and deletes it. Any messages that transitively depend on it are also marked as invalid and deleted.
The client may share any message that has been delivered, in which case the message's transitive dependencies are also shared. The client may delete any message that it no longer needs to store. This does not affect the message's dependencies or dependents.
