[Libreoffice-commits] online.git: loolwsd/README

[Ashod Nakashian]

 loolwsd/README |   94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 93 insertions(+), 1 deletion(-)

New commits:
commit 4a4583e7119ee871982ff19a3dcc0175ad7229d4
Author: Ashod Nakashian <ashod.nakashian at collabora.co.uk>
Date:   Thu Jan 7 00:41:32 2016 -0500

    loolwsd: documentation updated with architecture, filesystem, and workflow
    
    Change-Id: If5268cd87794493d63d8175b9da10e6242d6e3f0
    Reviewed-on: https://gerrit.libreoffice.org/21186
    Reviewed-by: Ashod Nakashian <ashnakash at gmail.com>
    Tested-by: Ashod Nakashian <ashnakash at gmail.com>

diff --git a/loolwsd/README b/loolwsd/README
index 39550cc..cd6e8d8 100644
--- a/loolwsd/README
+++ b/loolwsd/README
@@ -147,6 +147,98 @@ Protocol description
 See protocol.txt for a description of the protocol to be used over the
 websocket.
 
+Architecture
+------------
+
+There are three processes: LoolWSD, LoolBroker, and LoolKit.
+
+WSD is the top-level server and is intended to run as a service.
+It is responsible for spawning Broker and listening on public
+port for Client connections.
+
+The Broker is only responsible for spawning (or forking) Kit
+instances. There is only one Broker per WSD instance and
+there is one Kit instance per document.
+
+WSD listens on a public port and using internal pipes requests
+the Broker to fire a child (Kit) instance to host documents.
+The Broker then has to find an existing Kit that hosts that
+document, based on the public URI as unique key, and forward
+the request to this existing Kit, which then loads a new
+view to the document.
+
+Whether a document is loaded for the first time, or this is
+a new view on an existing one, the Kit connects via a socket
+to WSD on an internal port. WSD acts as a bridge between
+the Client and Kit by tunnelling the traffic between the two
+sockets (that which is between the Client and WSD and the one
+between WSD and Kit).
+
+File System
+-----------
+
+WSD is given childroot argument on the command line. This is
+the root directory of jailed FS. This path can be anywhere, but
+here we'll designate it as:
+
+/childroot
+
+Before spawning a Broker instance, WSD needs to generate a random
+Jail-ID to use as the jail directory name. This JailID is then
+passed to Broker as argument jailid.
+
+Note: for security reasons, this directory name is randomly generated
+and should not be given out to the Client. Since there is only one
+Broker per WSD instance, there is also one JailID between them.
+
+The Broker creates a chroot in this directory (the jail directory):
+
+/childroot/jailid/
+
+Broker copies the LO instdir (essentially installs LO in the chroot),
+then copies the Kit binary into the jail directory upon startup.
+Once done, it chroot-s and drops caps.
+
+Broker then waits on a read pipe to which WSD writes when a new
+request from a Client is received. Broker is responsible for spawning
+(or forking) Kit instances. For our purposes, it doesn't matter
+whether Kit is spawned or forked.
+
+Every document is hosted by a Kit instance. Each document is stored
+in a dedicated directory within the jail directory. The document
+root within the jail is /user/docs. The absolute path on the system
+(which isn't accessible to the Kit process as it's jailed) is:
+
+/childroot/jailid/user/docs
+
+Within this path, each document gets its own sub-directory based on
+another random Child-ID (which could be the Process ID of the Kit).
+This ChildId will be given out to Clients to facilitate the insertion
+and downloading of documents. (Although strictly speaking the Client
+can use the main document URI as key, this is the current design.)
+
+/childroot/jailid/user/docs/childid
+
+
+A request from a Client to load a document will trigger the following
+chain of events.
+
+- WSD public socket will receive the connection request followed
+  by a "load" command.
+- WSD creates MasterProcessSession (ToClient) to handle the client traffic.
+- MasterProcessSession requests Broker to find or spawn Kit for
+  the given URI.
+- Broker sends Kit request to host URI via pipe.
+- Kit connects to WSD on an internal port.
+- WSD creates another MasterProcessSession (ToPrisoner) to service Kit.
+- MasterProcessSession (ToClient) is linked to the ToPrisoner instance,
+  copies the document into jail (first load only) and sends
+  (via ToPrisoner) the load request to Kit.
+- Kit loads the document and sets up callbacks with LOKit.
+- MasterProcessSession (ToClient) and MasterProcessSession (ToPrisoner)
+  tunnel the traffic between Client and Kit both ways.
+
+
 Coding style
 ------------
 
@@ -178,7 +270,7 @@ The style is roughly as follows, in rough order of importance:
 
 - Use std:: prefix for all std API, i.e. don't ever do "using
   std;". But it's OK to use "using Poco::Foo;" all over. Maybe that is
-  not a good idea?
+  not a good idea? But please no "using" in headers.
 
 - Be as portable as possible, i.e. don't intentionally write Unix-only
   code if there is a choice. Obviously some parts of the code