diff options
Diffstat (limited to 'protocol.txt')
| -rw-r--r-- | protocol.txt | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/protocol.txt b/protocol.txt new file mode 100644 index 0000000..223f58a --- /dev/null +++ b/protocol.txt @@ -0,0 +1,39 @@ +The debug-me protocol is a series of JSON objects, exchanged between +the two participants, known as the user and the developer. + +The exact composition of the JSON objects is not described here; see +Types.hs for the data types that JSON serialization instances are derived +from. + +A debug-me session starts with the user sending an Activity Seen +containing some introductory message. This first Activity Seen has +Nothing as its prevActivity. All subsequent Activity sent by either the +user or developer has a prevActivity that points to the Hash of +the previous activity, so a chain of Activity is built up. + +The exact details about how these objects are hashed is not described here; +see Hash.hs for the implementation. Note that the JSON strings are *not* +directly hashed (to avoid tying hashing to JSON serialization details), +instead the values in the data types are hashed. + +The user and developer have different points of view; the debug-me protocol +makes sure that both sides agree on what is happening, to avoid +disagreements. For example, the developer could send an Activity Entered +at the same time the user is sending an Activity Seen. In this case, +the developer didn't see something that happened while they were entering +a command. So, when the user receives their Activity Entered, and sees that +its prevActivity does not point to the just sent Activity Seen, the user +will reject that input, sending back a Rejected message to let the +developer know. + +This requirement that the developer always send Activity Entered that points +to the last Activity that the user has sent/accepted is known as the +synchronicity requirement. + +The synchronicity requirement can be problematic when the developer is +entering a command, because each letter they type gets echoed back, and +that echo happens asynchronously. To avoid needing to wait for the letter +to be echoed back before the next letter can be entered, the debug-me +protocol allows the developer to include echoDatta in an Activity Entered. + + |