Diagrams: sequence and state-machine

docs/Makefile

@@ -12,7 +12,12 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile diagrams
+
+diagrams:
+	plantuml -Tpng happy-plant.seq
+	seqdiag --no-transparency --antialias -T png happy.seq
+	dot -Tpng states.dot > states.png
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/close-phase.seq

@@ -0,0 +1,79 @@
+seqdiag {
+  default_fontsize = 16;
+  edge_length = 320;
+
+  alice <- mailbox [label = "welcome"]
+  alice -> mailbox [label = "bind appid, side"]
+  alice -> mailbox [label = "allocate", note = "side assigned"]
+  alice <- mailbox [label = "allocated: nameplate_id"]
+  alice -> mailbox [label = "claim nameplate_id"]
+  alice <- mailbox [label = "claimed: mailbox_id"]
+  alice -> mailbox [label = "open mailbox_id"]
+
+  alice -> mailbox [label = "add phase=pake body"]
+  alice <- mailbox [label = "message phase=pake side=a body"]
+
+  bob <- mailbox [label = "welcome"]
+  bob -> mailbox [label = "bind appid, side"]
+// note: no allocate / allocated
+  bob -> mailbox [label = "claim nameplate_id"]
+  bob <- mailbox [label = "claimed: mailbox_id"]
+  bob -> mailbox [label = "open mailbox_id"]
+  bob <- mailbox [label = "message phase=pake side=a body"]
+  bob -> mailbox [label = "add phase=pake body"]
+  bob <- mailbox [label = "mesage phase=pake side=b body"]
+
+  alice <- mailbox [label = "mesage phase=pake side=b body"]
+  alice -> mailbox [label = "release nameplate_id"]
+  alice <- mailbox [label = "released"]
+  alice -> mailbox [label = "add phase=version side=a body"]
+
+  bob <- mailbox [label = "message phase=version side=a body"]
+  alice <- mailbox [label = "message phase=version side=a body"]
+
+  bob -> mailbox [label = "add phase=version side=b body"]
+  bob <- mailbox [label = "message phase=version side=b body"]
+  alice <- mailbox [label = "message phase=version side=b body"]
+
+=== application messages ===
+
+  alice -> mailbox [label = "add phase=0 side=a body"]
+  alice <- mailbox [label = "message phase=0 side=a body"]
+  bob   <- mailbox [label = "message phase=0 side=a body"]
+
+  alice -> mailbox [label = "add phase=1 side=a body"]
+  alice <- mailbox [label = "message phase=1 side=a body"]
+  bob   <- mailbox [label = "message phase=1 side=a body"]
+
+  bob -> mailbox [label = "add phase=0 side=b body"]
+  bob   <- mailbox [label = "message phase=0 side=b body"]
+  alice <- mailbox [label = "message phase=0 side=b body"]
+
+=== closing ===
+
+  bob -> mailbox [label = "add phase=closing side=b body"]
+  bob <- mailbox [label = "message phase=closing side=b body"]
+  alice <- mailbox [label = "message phase=closing side=b body"]
+
+... bob sends no more messages ...
+... however, alice can still ...
+
+  alice -> mailbox [label = "add phase=2 side=a body"]
+  bob <- mailbox [label = "message phase=2 side=a body"]
+  alice <- mailbox [label = "message phase=2 side=a body"]
+
+... alice sends no more messages ...
+
+  alice -> mailbox [label = "add phase=closing side=a body"]
+  bob <- mailbox [label = "message phase=closing side=a body"]
+  alice <- mailbox [label = "message phase=closing side=a body"]
+
+... both sides know both sides done ...
+
+  alice -> mailbox [label = "close mailbox_id mood"]
+  alice <- mailbox [label = "closed"]
+
+  bob -> mailbox [label = "close mailbox_id mood"]
+  bob <- mailbox [label = "closed"]
+
+}

docs/happy-plant.seq

@@ -0,0 +1,92 @@
+@startuml
+
+skinparam defaultFontName "Source Sans Pro"
+skinparam defaultFontSize 18
+skinparam participantFontSize 22
+skinparam arrowFontSize 18
+skinparam noteFontSize 22
+
+title Magic Folder Server
+
+  alice <- mailbox: welcome
+  alice -> mailbox: bind appid, side
+
+  alice -> mailbox: allocate
+  alice <- mailbox: allocated: nameplate_id
+
+activate alice #aaddff
+
+  alice -> mailbox: claim nameplate_id
+  alice <- mailbox: claimed: mailbox_id
+  alice -> mailbox: open mailbox_id
+
+  alice -> mailbox: add phase=pake body
+  alice <- mailbox: message phase=pake side=a body
+
+... code communicated out-of-band ...
+
+  bob <- mailbox: welcome
+  bob -> mailbox: bind appid, side
+  bob -> mailbox: claim nameplate_id
+  bob <- mailbox: claimed: mailbox_id
+  bob -> mailbox: open mailbox_id
+  bob <- mailbox: message phase=pake side=a body
+  bob -> mailbox: add phase=pake body
+  bob <- mailbox: mesage phase=pake side=b body
+
+  alice <- mailbox: mesage phase=pake side=b body
+  alice -> mailbox: release nameplate_id
+  alice <- mailbox: released
+
+deactivate alice
+
+note over mailbox #eeeeee: Key-Verification messages double as version exchange
+
+  alice -> mailbox: add phase=version side=a body
+
+  bob <- mailbox: message phase=version side=a body
+  alice <- mailbox: message phase=version side=a body
+
+  bob -> mailbox: add phase=version side=b body
+  bob <- mailbox: message phase=version side=b body
+activate bob #lightgreen
+  alice <- mailbox: message phase=version side=b body
+
+activate alice #lightgreen
+
+  alice -> mailbox: add phase=0 side=a body
+  alice <- mailbox: message phase=0 side=a body
+  bob   <- mailbox: message phase=0 side=a body
+
+' XXX does this help or hinter understanding?
+  alice -->> bob: (effectively msg 0 from alice->bob)
+
+  alice -> mailbox: add phase=1 side=a body
+  alice <- mailbox: message phase=1 side=a body
+  bob   <- mailbox: message phase=1 side=a body
+
+' XXX does this help or hinter understanding?
+  alice -->> bob: (effectively msg 1 from alice->bob)
+
+  bob -> mailbox: add phase=0 side=b body
+  bob   <- mailbox: message phase=0 side=b body
+  alice <- mailbox: message phase=0 side=b body
+
+' XXX does this help or hinter understanding?
+  alice <<-- bob: (effectively msg 0 from bob->alice)
+
+deactivate alice
+deactivate bob
+
+' group #Pink Closing
+group Closing
+
+  bob -> mailbox: close mailbox_id mood
+  bob <- mailbox: closed
+
+  alice -> mailbox: close mailbox_id mood
+  alice <- mailbox: closed
+
+end
+
+@enduml

docs/happy.seq

@@ -0,0 +1,57 @@
+seqdiag {
+  alice <- mailbox [label = "welcome"]
+  alice -> mailbox [label = "bind appid, side"]
+  alice -> mailbox [label = "allocate", note = "side assigned"]
+  alice <- mailbox [label = "allocated: nameplate_id"]
+  alice -> mailbox [label = "claim nameplate_id"]
+  alice <- mailbox [label = "claimed: mailbox_id"]
+  alice -> mailbox [label = "open mailbox_id"]
+
+  alice -> mailbox [label = "add phase=pake body"]
+  alice <- mailbox [label = "message phase=pake side=a body"]
+
+  bob <- mailbox [label = "welcome"]
+  bob -> mailbox [label = "bind appid, side"]
+// note: no allocate / allocated
+  bob -> mailbox [label = "claim nameplate_id"]
+  bob <- mailbox [label = "claimed: mailbox_id"]
+  bob -> mailbox [label = "open mailbox_id"]
+  bob <- mailbox [label = "message phase=pake side=a body"]
+  bob -> mailbox [label = "add phase=pake body"]
+  bob <- mailbox [label = "mesage phase=pake side=b body"]
+
+  alice <- mailbox [label = "mesage phase=pake side=b body"]
+  alice -> mailbox [label = "release nameplate_id"]
+  alice <- mailbox [label = "released"]
+  alice -> mailbox [label = "add phase=version side=a body"]
+
+  bob <- mailbox [label = "message phase=version side=a body"]
+  alice <- mailbox [label = "message phase=version side=a body"]
+
+  bob -> mailbox [label = "add phase=version side=b body"]
+  bob <- mailbox [label = "message phase=version side=b body"]
+  alice <- mailbox [label = "message phase=version side=b body"]
+
+=== application messages ===
+
+  alice -> mailbox [label = "add phase=0 side=a body"]
+  alice <- mailbox [label = "message phase=0 side=a body"]
+  bob   <- mailbox [label = "message phase=0 side=a body"]
+
+  alice -> mailbox [label = "add phase=1 side=a body"]
+  alice <- mailbox [label = "message phase=1 side=a body"]
+  bob   <- mailbox [label = "message phase=1 side=a body"]
+
+  bob -> mailbox [label = "add phase=0 side=b body"]
+  bob   <- mailbox [label = "message phase=0 side=b body"]
+  alice <- mailbox [label = "message phase=0 side=b body"]
+
+=== closing ===
+
+  bob -> mailbox [label = "close mailbox_id mood"]
+  bob <- mailbox [label = "closed"]
+
+  alice -> mailbox [label = "close mailbox_id mood"]
+  alice <- mailbox [label = "closed"]
+
+}

docs/states.dot

@@ -0,0 +1,74 @@
+/*digraph {
+    title [label="Mailbox\lServer Machine" style="dotted"]
+
+    start -> opened [label="open(side)"];
+
+    opened -> opened [label="open(side)"];
+    opened -> opened [label="add_message(sided_message)"];
+    opened -> closing [label="close(side, mood)"];
+
+    closing -> closing [label="close(side, mood)"];
+}
+*/
+
+
+// note: all messages have an "id" and a "type"
+// and the server sends back an "ack" for every one
+// but that ack etc isn't covered in these diagrams
+
+digraph {
+    node [fontname = "Source Sans Pro" fontsize = 22];
+    edge [fontname = "Source Code Pro" fontsize = 18 fontcolor=blue];
+    graph [fontname = "Source Sans Pro" fontsize = 22];
+
+    title [label="Mailbox Server" style="dotted" fontsize=32];
+
+    ranksep = 1;
+
+    start [label="START\n(perm=none)"];
+    start_permissions [label="START\n(perm=hashcash)"];
+    start_reconn [label="RECONNECT\n(mailbox, perm=none)"];
+    start_reconn_perm [label="RECONNECT\n(mailbox, perm=hashcash)"];
+    done [label="DONE\nmood=" shape=box style=filled];
+
+    {rank=same; start start_permissions start_reconn start_reconn_perm}
+    start [shape=box, style=bold];
+    start -> bound [label="bind(appid, side)"];
+
+    # blue, to match seqdiag section on "nameplate allocated"
+    bound [fillcolor=cadetblue1, style=filled];
+    have_nameplate [fillcolor=cadetblue1, style=filled];
+    claimed [fillcolor=cadetblue1, style=filled];
+
+    start_permissions [shape=box, style=bold];
+    start_permissions -> granted [label="submit_permissions()" fontcolor=red];
+    granted -> bound [label="bind(appid, side)"];
+
+    start_reconn [shape=box, style=bold];
+    start_reconn -> open [label="open(mailbox_id)\l-> messages: send(side, phase, body)\l"];
+
+    start_reconn_perm [shape=box, style=bold];
+    start_reconn_perm -> reconn_granted [label="submit_permissions()" fontcolor=red];
+    open [fillcolor=green style=filled];
+    reconn_granted -> open [label="open(mailbox_id)\l-> messages: send(side, phase, body)\l"];
+
+    bound -> have_nameplate [label="allocate()\l-> nameplate_id\l"]
+    # allocate() really does do a claim() .. but you have to call it explicitly too
+    have_nameplate -> claimed [label="claim(nameplate, side)\l-> mailbox_id\l" fontcolor=darkgreen]
+    have_nameplate -> done [label="release(nameplate)" fontcolor=red]
+
+    # ths is on the "join" side; they are told the nameplate number
+    bound -> claimed [label="claim(nameplate, side)\l-> mailbox_id\l" fontcolor=darkgreen]
+    claimed -> unclaimed [label="release(nameplate)" fontcolor=red]
+
+    # note: allowing two different paths to 'unclaimed' is I think
+    # _allowed_ currently by the server, but better to define it with
+    # juts one way probably.
+
+    unclaimed -> open [label="open(mailbox_id)\l-> messages: send(side, phase, body)\l"]
+    #claimed -> open [label="open(mailbox_id)\l-> send(all_messages)\l"]
+    #open -> open [label="release(nameplate)"]
+    open -> open [label="add_message(msg)\l-> send(side, phase, body)\l"]
+    open ->      done [label="close(mailbox_id)" fontcolor=red]
+    # XXX will get all message already in the box, how to represent?
+}