Changes between Version 9 and Version 10 of Infinote/Protocol

Timestamp:

10/02/08 14:46:04 (5 years ago)

Author:

armin (IP: 87.178.239.221)

Comment:

Updated InfText? messages

Infinote/Protocol

@@ -6 +6 @@
 
 TODO: List error domains and codes
+
+TODO: Max-Total-Log-Size
 
 The basic Infinote protocol uses XML and can be used over any transport that can deliver XML messages between hosts, such as XMPP.
@@ -451 +453 @@
 == InfText messages ==
 
+This section describes additional messages that are used for text sessions.
+
 === State vectors ===
 
@@ -461 +465 @@
 Some attributes of the following messages describe such a state vector. The state vector has the form "user_id:processed_requests;user_id:processed_requests;[...]" where user_id is the ID of a user and processed_requests describe the number of requests that this user is guaranteed to have already processed.
 
+==== State Vector Diffs ====
+
+State Vectors can also be sent as a "Diff", which means relative to a state vector sent previously.
+
+For example, if such a diff contains the value "2:3;1:1", this means that the value 3 needs to be added to the processed requests of user 2 of the reference state vector, and 1 to the requests of user 1.
+
+=== Operations ===
+
+Some fields of the InfText messages use operations to describe a change that has been made to the document. This section defines what operations are allowed.
+
+There are two types of operations. Such operations that modify the document and such that do not. For example, inserting a character into the document does modify it, but moving the cursor of a user does not. If the operation of a request does not modify the document, the request is not recorded into the request log (and cannot be undone).
+
+{{{
+<insert pos="pos">text</insert>
+<insert-caret pos="pos">text</insert-caret>
+}}}
+
+ * pos, Integer: The character offset at which to insert text.
+ * text, String: The text to insert.
+
+An operation that inserts new text into the document. The <insert-caret> version additionally places the cursor of the user that made the request behind the inserted text.
+
+{{{
+<delete pos="pos" len="len" />
+<delete-caret pos="pos" len="len" />
+}}}
+
+ * pos, Integer: The character offset at which to start deleting characters
+ * len, Integer: The number of characters to delete.
+
+Deletes text from the buffer. This operation is only used in <request /> messages. Again, <delete-caret /> additionally places the cursor of the user that made the request to the place where characters have been deleted.
+
+{{{
+<delete pos="pos"><segment author="user_id">text</segment>[...]</delete>
+}}}
+
+ * pos, Integer: The character offset at which to start deleting characters.
+ * segments: The text that was deleted, including author information, i.e. which user wrote what text.
+
+Deletes text from the buffer and specifies what text is deleted. This operation is only used in <sync-request /> messages. The synchronization client cannot deduce what text was actually deleted, but must be able to compute the reverse operation in case someone undoes the request. In a normal <request /> message, other users can deduce what text was deleted by having a look at the document and which transformations were required to transform the request to the current state before the operation is actually executed.
+
+{{{
+<no-op />
+}}}
+
+Does nothing, and does especially not modify the document (see above). This is used when a user was inactive for some time to report its current state vector to the other users.
+
+{{{
+<move caret="pos" selection="len" />
+}}}
+
+ * pos, Integer: The character offset to place the cursor to.
+ * len, Integer: The length of the selection area, in characters. Negative values mean selection towards the beginning of the document.
+
+Changes the position of the user's cursor position and selection area. This operation does not modify the document.
+
+{{{
+<undo />
+<undo-caret />
+}}}
+
+Undoes the previous request of the user. The <undo-caret /> version also places the user's cursor to the position where the operation was performed.
+
+{{{
+<redo />
+<redo-caret />
+}}}
+
+Redoes the previous request of the user. The <redo-caret /> version also places the user's cursor to the position where the operation was performed.
+
 === User attributes ===
 
-The following attributes are used in the <sync-user> and <join-user> requests for text sessions:
+The following attributes are used in the <sync-user /> and <join-user /> requests for text sessions:
 
  * time, StateVector: The current state vector of the user
- * caret: The position of the user's cursor, in characters, from the document beginning
- * selection: The number of characters selected, starting at the character caret. Negative means selection towards the beginning of the document.
+ * caret, Integer: The position of the user's cursor, in characters, from the document beginning
+ * selection, Integer: The number of characters selected, starting at the character caret. Negative means selection towards the beginning of the document.
+ * hue, Float: A floating point number between 0.0 (red) and 1.0 (red), specifying the user's color.
 
 TODO: Viewport
@@ -483 +558 @@
  * user, Integer: The ID of the user that made the request.
  * time, State Vector: The state at which the request was made.
- * operation: The operation performed by the request, see below.
-
-Tells that at the given time a user made a request. This should be added to the request log and might be necessary to transform incoming operations or to compute Undo operations.
+ * operation, Operation: The operation performed by the request, see below.
+
+Tells that at the given time a user made a request. The request is already included in the document content sent via <sync-segment /> messages. However, the request should be added to the request log and might be necessary to transform incoming operations or to compute Undo operations.
 
 {{{
@@ -494 +569 @@
  * Text: The text that user wrote.
 
-Synchronizes a part of the initial document that was written by a single user. The <sync-segment> messages should be sent in-order so the document can be reconstructed.
-
-=== Independant ===
-
-These messages are sent no matter whether being client or server.
+Synchronizes a continous part of the initial document that was written by a single user. The <sync-segment> messages must be sent in-order so the document can be reconstructed.
+
+=== Group messages ===
+
+These messages can be sent from each group member to other group members.
 
 {{{
@@ -507 +582 @@
 
  * user, Integer: The ID of the user that made the request.
- * time, State Vector diff: Describes the document state at which the request was made.
- * operation: The operation performed by the request, see below.
-
-Whenever a user issues a request the <request> message is sent. The user must have joined via the connection the request message comes from. <request> is sent to the whole subscription group. The time sent with this message is not absolute, but relative to the time from the last request of this user. For, example, if time contains the value "2:3;1:1", this means that since the last request of that user, it processed 3 requests from user 2 and one request from user 1. Note that the  value for the user itself is therefore always zero, because there cannot be any requests inbetween them. This requires the requests from some user to arrive in-order, but it state vector components from inactive (or users that have left the session) need not to be transmitted all the time.
-
-=== Operations ===
-
-There are two types of operations. Such operations that modify the document and such that do not. For example, inserting a character into the document does modify it, but moving the cursor of a user does not. If the operation of a request does not modify the document, the request is not recorded in the request log.
-
-The following operations are defined:
-
-{{{
-<insert pos="pos">text</insert>
-<insert-caret pos="pos">text</insert-caret>
-}}}
-
- * pos, Integer: The character offset at which to insert text.
- * text, String: The text to insert.
-
-An operation that inserts new text into the document. The <insert-caret> version additionally places the cursor of the user that made the request behind the inserted text.
-
-{{{
-<delete pos="pos" len="len" />
-<delete-caret pos="pos" len="len" />
-}}}
-
- * pos, Integer: The character offset at which to start deleting characters
- * len, Integer: The number of characters to delete.
-
-Deletes text from the buffer. This operation is only used in <request> messages. Again, <delete-caret> additionally places the cursor of the user that made the request to the place where characters have been deleted.
-
-{{{
-<delete pos="pos"><segment author="user_id">text</segment>[...]</delete>
-}}}
-
- * pos, Integer: The character offset at which to start deleting characters.
- * segments: The text that was deleted, including author information, i.e. which user wrote what text.
-
-Deletes text from the buffer and specifies what text is deleted. This operation is only used in <sync-request> messages. The synchronization client cannot deduce what text was actually deleted, but must be able to compute the reverse operation in case someone undoes the request. In a normal <request> message, other users can deduce what text was deleted by having a look at the document and which transformations were required to transform the request to the current state before the operation is actually executed.
-
-{{{
-<no-op />
-}}}
-
-Does nothing, and does especially not modify the document (see above). This is used when a user was inactive for some time to report its current state vector to the other users.
-
-{{{
-<move caret="pos" selection="len" />
-}}}
-
- * pos, Integer: The character offset to place the cursor to.
- * len, Integer: The length of the selection area, in characters. Negative values mean selection towards the beginning of the document.
-
-Changes the position of the user's cursor position and selection area. This operation does not modify the document.
-
-{{{
-<undo />
-<undo-caret />
-}}}
-
-Undoes the last request of the user. The <undo-caret> version also places the user's cursor to the position where the operation was performed.
-
-{{{
-<redo />
-<redo-caret />
-}}}
-
-Redoes the last request of the user. The <redo-caret> version also places the user's cursor to the position where the operation was performed.
+ * time, State Vector Diff: Describes the document state at which the request was made.
+ * operation, Operation: The operation performed by the request, see below.
+
+Whenever a user issues a request the <request> message is sent. The user must have joined via the connection the request message comes from. <request> is sent to the whole subscription group. The time is a State Vector Diff, with the previous time sent by that user being the reference state vector. Therefore, it requires the requests from some user to arrive in-order, but state vector components from inactive users (or ones that have left the session) need not to be transmitted all the time. Note that the value for the user itself is therefore always zero, because there cannot be any requests inbetween them.
 
 == Concurrency Control ==
@@ -612 +623 @@
       v := associated_request(r).v;
 }}}
-   r.v() is the state vector at which request r was made. The function associated_request returns request the given request r undoes (which is a DO or REDO request if r is a UNDO request, or an UNDO request if r is a REDO request). In the following diagram DO operations at (0,0), (0,1) and an UNDO operation at (1,1) have been issued. Note that the point (2,0) is reachable by folding from (0,0). The translation path of the blue request from (0,0) to (2,1) shows how it may be used. Although there exists another path in this example where (2,0) does not need to be reachable, the tests described in [svn://svn.0x539.de/infinote/trunk/test/std/test-21.xml test/std/test-21.xml] and [svn://svn.0x539.de/infinote/trunk/test/std/test-46.xml test/std/test-46.xml] fail with the original definition of the Reachable function.
+   r.v() is the state vector at which request r was made. The function associated_request returns request the given request r undoes (which is a DO or REDO request if r is a UNDO request, or an UNDO request if r is a REDO request). In the following diagram DO operations at (0,0), (0,1) and an UNDO operation at (1,1) have been issued. Note that the point (2,0) is reachable by folding from (0,0). The translation path of the blue request from (0,0) to (2,1) shows how it may be used. Although there exists another path in this example where (2,0) does not need to be reachable, the tests described in [http://git.0x539.de/?p=infinote.git;a=blob;f=test/session/test-21.xml;hb=master test/std/test-21.xml] and [http://git.0x539.de/?p=infinote.git;a=blob;f=test/session/test-46.xml;hb=master test/std/test-46.xml] fail with the original definition of the Reachable function.
 
    [[Image(http://infinote.0x539.de/illustrations/extended-reachable.png)]]