[Libreoffice-commits] online.git: wsd/reference.txt

[Jan Holesovsky]

 wsd/reference.txt |   45 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

New commits:
commit b76b6a98615b82ec88ac52f0c2eeda50fed1e3c9
Author: Jan Holesovsky <kendy at collabora.com>
Date:   Thu Feb 1 14:02:49 2018 +0100

    Document the conflict handling.
    
    Change-Id: I2291e4b085fcb6cac3280fdd2139afb909ada748

diff --git a/wsd/reference.txt b/wsd/reference.txt
index cea5fbf2..b75690b7 100644
--- a/wsd/reference.txt
+++ b/wsd/reference.txt
@@ -110,14 +110,55 @@ PutFile additionally indicates whether the user has modified the document
 before the save, or if they just pressed the Save button without any
 modification.  The following header:
 
-   X-LOOL-WOPI-IsModifiedByUser
+    X-LOOL-WOPI-IsModifiedByUser
 
 will have the value 'true' or 'false' accordingly.
 
 To distinguish autosave vs. explicit user requests to save, the following
 header:
 
-   X-LOOL-WOPI-IsAutosave
+    X-LOOL-WOPI-IsAutosave
 
 will have the value 'true' when the PutFile is triggered by autosave, and
 'false' when triggered by explicit user operation (Save button or menu entry).
+
+Detecting external document change
+----------------------------------
+
+The locking part of the WOPI protocol is left out, because it goes against how
+the files are being used in many EFSS solutions.  Instead, LibreOffice Online
+uses timestamps to detect document changes.
+
+When the document is updated in your storage while being edited in LibreOffice
+Online and there are unsaved changes, we detect it as soon as possible and ask
+the user if he/she would like to overwrite the changes or reload the new
+document from the storage.
+
+In case there are no unsaved changes, we reload the new document without
+asking the user.
+
+To support this feature, wopi host implementation has to specify
+LastModifiedTime field in both CheckFileInfo and PutFile calls.
+
+Additionally, WOPI hosts must check for a header in PutFile response:
+
+    X-LOOL-WOPI-Timestamp
+
+This header contains the ISO8601 round-trip formatted time of file’s last
+modified time in storage, as known by LibreOffice Online. In case this header
+is present and its value does not match the file’s modified time in storage,
+it indicates that document being edited is not the one that is present in the
+storage.
+
+WOPI hosts should not save the file to storage in such cases and respond with
+HTTP 409 along with LibreOffice Online specific status code:
+
+    HTTP 409 with JSON:
+    {
+        “LOOLStatusCode”: 1010
+    }
+
+When the user chooses "overwrite" when asked how to resolve the conflict,
+LibreOffice will attempt one more save operation, but this time it will lack
+the X-LOOL-WOPI-Timestamp header, which means "save regardless of state of the
+file".