loolwsd/README | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 93 insertions(+), 1 deletion(-)
New commits: commit 4a4583e7119ee871982ff19a3dcc0175ad7229d4 Author: Ashod Nakashian <[email protected]> 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 <[email protected]> Tested-by: Ashod Nakashian <[email protected]> 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 _______________________________________________ Libreoffice-commits mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/libreoffice-commits
