diff --git a/src/pages/en/specs/format-repo.md b/src/pages/en/specs/format-repo.md index 8c5073e..e7644f9 100644 --- a/src/pages/en/specs/format-repo.md +++ b/src/pages/en/specs/format-repo.md @@ -762,7 +762,7 @@ type InternalNode = Vec ## Event -An event is a commit with some additional meta-data needed for sending it into the pub/dub topic. +An event is a commit with some additional meta-data needed for sending it into the pub/sub topic. It can also contain additional blocks that are sent together with the commit (additional_blocks). diff --git a/src/pages/en/specs/protocol-client.md b/src/pages/en/specs/protocol-client.md index e9e925a..c43a993 100644 --- a/src/pages/en/specs/protocol-client.md +++ b/src/pages/en/specs/protocol-client.md @@ -8,21 +8,21 @@ layout: ../../../layouts/MainLayout.astro The Client Protocol is used by the Verifier in order to contact the Broker of the User. -It maintain this connection throughout the session that was opened by the User (by opening the wallet in the app, by example). +It maintains this connection throughout the session that was opened by the User (by opening the wallet in the app, by example). From this connection, the Verifier gets all the pushed updates (called Events), after it subscribed to some topics. The verifier also sends the updates that it wants to publish, in the form of an Event to the Pub/Sub Topic, and the Broker deals with forwarding this Event to all the other devices and users that have subscribed to this topic. -The communication on the Client Protocol are using a WebSocket, encrypted from within with the Noise Protocol. +The communication on the Client Protocol is using a WebSocket, encrypted from within with the Noise Protocol. -In addition, all the Events, that are send and received with this protocol, are also encrypted end-to-end. +In addition, all the Events, that are sent and received with this protocol, are also encrypted end-to-end. For now, the Verifier only connects to one Broker, but for redundancy and failsafe purposes, it will be possible in the future that it tries to connect to several Brokers. But one rule should always be followed: for any given Overlay, a User can only participate in this Overlay from one and only one Broker at the same time. -Let's dive into the format of the messages and actions/commands that can be exchange on the Client Protocol +Let's dive into the format of the messages and actions/commands that can be exchanged on the Client Protocol. The initiation of the connection is common to all protocols, and involves some Noise handshake. It isn't detailed here, please refer to the code for now. We will provide more documentation on that part later on. @@ -30,7 +30,7 @@ For a reference of the common types, please refer to the [Repo format documentat ### ClientMessage -All the subsequent message sent and receive on this protocol, are encapsulated inside a `ClientMessage`. +All the subsequent messages sent and receive on this protocol, are encapsulated inside a `ClientMessage`. The `ClientRequestV0.id` is set by the requester in an incremental way. Request IDs must be unique by session. They should start from 1 after every start of a new session. This ID is present in the response, in order to match requests and responses. @@ -167,12 +167,10 @@ Request a Commit by ID Replied with a stream of `Block`s. -`commit_header_key` of the replied blocks is always set to None when request is made on OuterOverlay of protected or Group overlays. +`commit_header_key` of the replied blocks is always set to None when request is made on OuterOverlay of Protected or Group overlays. -The difference with BlocksGet is that the Broker will try to return all the commit blocks as they were sent in the Pub/Sub Event, if it has it. -This will help in having all the blocks (including the header and body blocks) in one ClientProtocol message, while a BlocksGet would inevitably return only the blocks of the ObjectContent, -and not the header nor the body. And the load() would fail with CommitLoadError::MissingBlocks. That's what happens when the Commit is not present in the pubsub, -and we need to default to using BlocksGet instead. +The difference with BlocksGet is that the Broker will try to return all the commit blocks as they were sent in the Pub/Sub Event, if it has the event. +This will help in receiving all the blocks (including the header and body blocks) in one ClientProtocol message, while a BlocksGet would inevitably return only the blocks of the ObjectContent, and not the header nor the body. And the load() would fail with CommitLoadError::MissingBlocks. That's what happens when the Commit is not present in the pubsub, and then we need to default to using BlocksGet instead. #### Request @@ -194,11 +192,11 @@ struct CommitGetV0 { ### RepoPinStatus -Request the status of pinning for a repo on the broker (for the current user's session). +Request the pinning status for a repo on the broker (for the current user's session). Returns an error code if not pinned, otherwise returns a RepoPinStatusV0. The overlay entered in ClientMessage is important. if it is the outer, only outer pinning will be checked. -/// if it is the inner overlay, only the inner pinning will be checked. +If it is the inner overlay, only the inner pinning will be checked. #### Request