Provide a notification when client is deactivated due to housekeeping

[chacha912]

Description:

When a client leaves a document without properly deactivating(detaching), it remains as a zombie client, leading to inefficiencies in garbage collection. To address this issue, server deactivates clients that have been inactive for a certain period through a housekeeping process.

The default Client Deactivate Threshold is set to 24 hours, meaning that if a client has not edited the document for 24 hours, it will be deactivated and no longer considered to be participating in document editing.

However, there are cases where a user leaves a document open for a long time without actively editing it, causing housekeeping to occur and disconnecting the user from document editing. In such cases, users should be notified that the document has been disconnected and instructed to re-attach in order to continue editing.

Considerations:

• Check for any unpushed local changes before deactivating the client
• Ensure proper handling of the deactivated client in garbage collection

[chacha912]

Here is additional information regarding this issue and potential solutions we are considering:

A. Notifying SDK Users About Housekeeping:

When the ErrClientNotActivated error occurs, it indicates that housekeeping has taken place.

A1. If the Stream is Disconnected:

• Housekeeping can occur on the server when the client loses network connection, such as when entering sleep mode. The SDK client requests watchDocument to re-establish the watch stream and tries to sync. The server responds with ErrClientNotActivated.

  • In sleep mode, the watch stream stays connected. When waking up, the stream may disconnect due to a network error and try to reconnect. If a local change happens before the stream disconnects, the pushPullChanges request will receive the ErrClientNotActivated error.
  • Since sleep mode behavior varies by browser and OS, periodic network health checks might be necessary. Chrome, for example, throws the following errors:
    
    
    

• When the client gets the ErrClientNotActivated error in watchDocument or pushPullChanges, it considers itself deactivated due to housekeeping, detaches the document, and triggers the detached event in Document.Subscribe.

A2. If the Stream is Still Connected:

• Currently, during housekeeping, the server detaches the document and deactivates the client. If the watch stream is still connected, the SubscriptionMap should also be cleaned up. (The server deactivating the client should remove the SubscriptionMap on the Peer server.)
• The rest is the same as A1.

A3. If Not Maintaining a Stream (Offline Editing):

• The pushPullChanges request will get the ErrClientNotActivated response (same as A1).

B. How Users Can Recover the Document When Receiving a Detached Event in doc.subscribe():

B1. Reactivate the Client and Reattach the Document:

• All unsynced local changes will be lost.

B2. Implement Offline Storage Mode to Keep Unsynced Local Changes:

• This requires additional development for offline storage.

Initially, we plan to test using methods A1 and B1, and then move on to A2 and B2.

[hackerwins]

Flow for Deactivation of Outdated Clients by housekeeping:

A. Initial Setup

• Subscribe to Document.Subscribe('status') event: Add doc.subscribe('status', callback) function yorkie-js-sdk#828

B. Server-side Housekeeping Processing

• Client Deactivation triggered by Housekeeping
• Detach Attachment(Fix missing document detachments when client is deactivated #907)

C. Client Re-access

• Request initiated by SyncLoop or WatchLoop
• Server replies ErrClientDeactivated to the client: Provide error codes for enhancing error handling from clients #927

D. Client-side Handling

• Receive ErrClientDeactivated error
• Pass Detached event to Document.Subscribe

E. Required User Actions

• E1. Reconnection
  • Create new Client and Document
  • Reestablish attachment using newly created objects (similar to page reload)
• E2. Data Preservation
  • Potential loss of unsent Local Changes
  • Recommended providing Copy & Paste UI(similar to Copy & Paste UI of Google Docs, Support time travel #52 (comment))