many changes

HACKING.org

@@ -6,7 +6,7 @@ This packages implements the Logoot split algorithm
 ~André, Luc, et al. "Supporting adaptable granularity of changes for massive-scale collaborative editing." 9th IEEE International Conference on Collaborative Computing: Networking, Applications and Worksharing. IEEE, 2013.~
     
 The CRDT-ID blocks are implemented by text property ='crdt-id=. 
-A continous range of text with the same ='crdt-id'= property represent a CRDT-ID block. 
+A continous range of text with the same ='crdt-id= property represent a CRDT-ID block. 
 The ='crdt-id= is a a cons of =(ID-STRING . END-OF-BLOCK-P)=, 
 where =ID-STRING= represent the CRDT-ID of the leftmost character in the block.
 If =END-OF-BLOCK-P= is =NIL=, the block is a non-rightmost segment splitted from a larger block,
@@ -14,20 +14,36 @@ so insertion at the right of this block shouldn't be merged into the block by sh
 
 =ID-STRING= is a unibyte string representing a CRDT-ID (for efficient comparison).
 Every two bytes represent a big endian encoded integer.
-For base IDs, last two bytes are always representing site ID.
+For base IDs, last two bytes are always representing Site ID.
 Stored strings are BASE-ID:OFFSETs. So the last two bytes represent offset,
-and second last two bytes represent site ID.
+and second last two bytes represent Site ID.
+
+* Access Control
+  
+~crdt.el~ implements a capability based access control system.
+
+Each capability is a list of the form =(type transferable-p nonce . body)=
+
+  - read :: body takes the form =(buffer-name)=
+  - write :: body takes the form =(buffer-name)=
+  - command :: body takes the form =(buffer-name command-symbol)=
+    + =buffer-name= can be =t=, which means that =command-symbol= is not 
+      bound to be invoked in any specific buffer.
+  - process :: body takes the form =(buffer-name)=
 
 * Protocol
 
-  Text-based version
-  (it should be easy to migrate to a binary version.  Using text for better debugging for now)
+Text-based version
+(it should be easy to migrate to a binary version.  Using text for better debugging for now)
+
+Note: Starting from =v0.3.0=, we separate /User IDs/ and /Site IDs/. 
+Site IDs are /buffer local/ and temporarily assigned to users with writable access.
 
-  Every message takes the form =(type . body)=
+Every message takes the form =(type . body)=
 
   - Text Editing
     + insert ::
-      body takes the form =(buffer-name crdt-id position-hint content)=
+      body takes the form =(buffer-name user-id crdt-id position-hint content)=
       - =position-hint= is the buffer position where the operation happens at the site
         which generates the operation.  Then we can play the trick that start search
         near this position at other sites to speedup CRDT ID search
@@ -40,18 +56,18 @@ and second last two bytes represent site ID.
   - Peer State
     + cursor ::
       body takes the form
-           =(buffer-name site-id point-position-hint point-crdt-id mark-position-hint mark-crdt-id)=
+           =(buffer-name user-id point-position-hint point-crdt-id mark-position-hint mark-crdt-id)=
       =*-crdt-id= can be either a CRDT ID, or
         - =nil=, which means clear the point/mark
         - =""=, which means =(point-max)=
 
     + contact ::
       body takes the form
-           =(site-id name address port)=
-      when name is =nil=, clear the contact for this =site-id=
+           =(user-id name address port)=
+      when name is =nil=, clear the contact for this =user-id=
 
     + focus ::
-      body takes the form =(site-id buffer-name)=
+      body takes the form =(user-id buffer-name)=
 
   - Login
     + hello ::
@@ -68,8 +84,8 @@ and second last two bytes represent site ID.
 
     + login ::
       It's always sent after server receives a hello message.
-      Assigns an ID to the client
-      body takes the form =(site-id session-name)=.
+      Assigns a User ID to the client
+      body takes the form =(user-id session-name)=.
 
   - Initial Synchronization
     + sync ::
@@ -115,7 +131,7 @@ and second last two bytes represent site ID.
     + overlay-add ::
       body takes the form 
       #+BEGIN_SRC
-      (buffer-name site-id logical-clock species
+      (buffer-name user-id logical-clock species
         front-advance rear-advance
         start-position-hint start-crdt-id
         end-position-hint end-crdt-id)
@@ -124,27 +140,27 @@ and second last two bytes represent site ID.
     + overlay-move ::
       body takes the form
       #+BEGIN_SRC
-      (buffer-name site-id logical-clock
+      (buffer-name user-id logical-clock
         start-position-hint start-crdt-id
         end-position-hint end-crdt-id)
       #+END_SRC
 
     + overlay-put ::
-      body takes the form =(buffer-name site-id logical-clock prop value)=
+      body takes the form =(buffer-name user-id logical-clock prop value)=
 
     + overlay-remove ::
-      body takes the form =(buffer-name site-id logical-clock)=
+      body takes the form =(buffer-name user-id logical-clock)=
 
   - Remote Command
     + command ::
       body takes the form
       #+BEGIN_SRC
-      (buffer-name spawn-site-id
-       site-id logical-clock state-list
+      (buffer-name spawn-user-id
+       user-id logical-clock state-list
        command-symbol . args)
       #+END_SRC
-       - =spawn-site-id= represents the site where the interactive command is originally invoked
-         + It can be different from =site-id= because a remote command can call a remote command!
+       - =spawn-user-id= represents the site where the interactive command is originally invoked
+         + It can be different from =user-id= because a remote command can call a remote command!
            This is especially useful when client makes a remote call, 
            but the call on the server request some interactive input,
            and such interactive call are remote-called back into the client.
@@ -153,11 +169,11 @@ and second last two bytes represent site ID.
         (CDRs can also be 2 element list of the form =(crdt-id pos-hint)=)
         Allowed symbols are 
         #+BEGIN_SRC
-        point mark mark-active transient-mark-mode last-command-event
+        buffer point mark mark-active transient-mark-mode last-command-event
         #+END_SRC
 
     + return ::
-      body takes the form =(site-id logical-clock state-list success-p . return-values)=
+      body takes the form =(user-id logical-clock state-list success-p . return-values)=
 
   - Buffer local variables
     + var :: body takes the form =(buffer-name variable-symbol . args)=
@@ -310,7 +326,7 @@ Q: What if Emacs GCs?
     + delete :: body takes the form =(buffer-name position length)=
 
   - Peer State
-    + cursor :: body takes the form =(buffer-name site-id point-position mark-position)=
+    + cursor :: body takes the form =(buffer-name user-id point-position mark-position)=
       =*-position= can be either an integer, or
         - =nil=, which means clear the point/mark