📝 documentation: describing editing_session_key in more detail (#525)

Documentation/docs/plugins.md

@@ -145,6 +145,15 @@ ended with and without a new version.
 
 See operations `beginEditing` and `updateEditing` in `tdrive/backend/node/src/services/documents/services/index.ts` for operations available on that key.
 
+Basic flow is:
+  - Call `beginEditing`
+    - If a key previously was set for that file, uses the `/check` endpoint of the plugin to update the key status first
+    - Twake Drive generates an editing session key and returns it (or returns the existing one).
+  - Optionally call `updateEditing?keepEditing=true` with a file stream to generate intermediary versions
+  - End the session by calling `updateEditing` (without `keepEditing=true`). If a file is provided, a new (and final) FileVersion
+    is created with that content. Otherwise, the editing session is cleared without creating a new version.
+
+
 #### API to expose by the application
 
 Authentication from the Twake Drive backend is a JWT with the property `type` being
@@ -161,7 +170,81 @@ multiple parallel requests for the same key gracefully.
   - `{ status: 'unknown' }`: the key isn't known and maybe used for a new session
   - `{ status: 'updated' }`: the key needed updating but is now invalid
   - `{ status: 'expired' }`: the key was already used in a finished session and can't be used again
-  - `{ status: 'live' }`:    the key is valid and current and should be used again for the same file
+  - `{ status: 'live' }`:    the key is valid and current and should be used again for the same file (if multiple writers are allowed)
+
+#### Example flow of editing session
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor User as User/Browser
+  participant Front as Frontend
+  box Server side
+    participant Back as Backend
+    participant Conn as onlyoffice<br>connector
+    participant OO as Only Office<br>Edition Server
+  end
+
+  User->>Front: Open in<br>editor
+  Front->>Back: Get plugin config
+  Front->>User: Open plugin config<br>editor.edition_url
+
+  User->>Conn: Open editor_url<br>(proxied by backend)
+  Conn->>Back: beginEditing
+  alt existing key
+  Back->>Conn: checkSessionStatus
+  Conn->>OO: getForgotten
+  note over Conn, OO: recover forgotten<br>process, and new key
+  Conn->>OO: info command
+  note right of Conn: decide status of key<br>live or stale
+  note over Conn, OO: detect ended but<br>not changed keys
+  note over Conn, OO: normal callback processing with<br>update if required
+  OO->>Conn: callback with key status
+  Conn->>Back: key status<br>(live/expired/updated/etc)
+  end
+  activate Back
+  Back->>Conn: editing_session_key
+  Conn->>User: HTML host for Editor with<br>special callback URL
+  User->>OO: Load JS Editor directly from OO server
+  activate User
+  loop User editing
+  User->>User: Furious Document<br>Editing
+  User-->>OO: Periodic saving
+  end
+  deactivate User
+  note left of User: Closes editor
+  note over User,OO: 10 seconds after last user closes their editor
+  OO->>Conn: callback to save the new version<br>or close without changes
+  Conn->>Back: updateEditing?keepEditing=false<br>with URL to new version from OO
+  deactivate Back
+```
+
+#### Batch processing of unknown keys
+
+Periodically, the plugin, and twake drive, should run batch cleanup operations on editing session keys
+to ensure they are live, or removed, as they may block other operations until then.
+
+Here is an example initiated by the plugin:
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor User as User/Browser
+  participant Front as Frontend
+  box Server side
+    participant Back as Backend
+    participant Conn as onlyoffice<br>connector
+    participant OO as Only Office<br>Edition Server
+  end
+
+  alt Periodic scheduled task
+  Conn->>OO: getForgottenList
+    loop Each forgotten file
+      Conn->>Back: Save new version<br>end editing session
+      Conn->>OO: Delete forgotten file
+    end
+  end
+```
 
 ### Example: OnlyOffice plugin