ep_configurable_reconnect

Beta / experimental: This plugin is still being evaluated and may not function as expected. Test it thoroughly before relying on it in production.

Keeps Etherpad's existing browser page and local changeset tracker alive through backend restarts and transient outages. It extends Socket.IO reconnection, verifies Etherpad's logical collaboration state after the transport reconnects, and replaces the destructive Force Reconnect page reload with an in-place recovery attempt.

Why

Etherpad 3.3.2 stops after five reconnect attempts. If a backend takes longer to return, Force Reconnect reloads the page and can discard edits that are still only in the browser. This plugin preserves those edits so Etherpad's normal CLIENT_RECONNECT revision reconciliation can submit them when the same backend returns. Socket.IO's connected flag alone is not sufficient: Etherpad enables the editor before missed revisions have necessarily been replayed. This plugin keeps ACE guarded until a server probe confirms that the socket has joined the pad room and the browser revision matches the server head. It then confirms that matched revision with a second reconnect handshake before releasing queued USER_CHANGES; this also synchronizes Etherpad's per-socket server revision, which otherwise remains at the pre-replay value in Etherpad 3.3.2.

Configuration

Add this block to settings.json:

"ep_configurable_reconnect": {
  "enabled": true,
  "reconnectionAttempts": 0,
  "reconnectionDelay": 1000,
  "reconnectionDelayMax": 5000,
  "collaborationProbeInterval": 15000,
  "collaborationRecoveryTimeout": 15000
}

• enabled: Enables the plugin. Default: true.
• reconnectionAttempts: Maximum attempts in one Socket.IO reconnection cycle. 0 means unlimited. Default: 0.
• reconnectionDelay: Initial retry delay in milliseconds, from 100 to 60000. Default: 1000.
• reconnectionDelayMax: Maximum retry delay in milliseconds, from 100 to 60000. Values below reconnectionDelay are raised to match it. Default: 5000.
• collaborationProbeInterval: Interval in milliseconds between lightweight room-membership/server-head probes while connected, from 1000 to 300000. Default: 15000.
• collaborationRecoveryTimeout: Maximum wait in milliseconds for a reconnect replay or probe before the plugin resends CLIENT_READY(reconnect=true) in place, from 1000 to 120000. Default: 15000.

Keep Etherpad's top-level automaticReconnectionTimeout at 0. While enabled, the plugin also disables that timer in the browser because Etherpad's built-in timer follows a reload-oriented recovery path.

With unlimited retries, the editor remains locked while disconnected or logically unreconciled, retains local changes in memory, and resumes only after Etherpad's revision replay and the plugin's server round trip agree. If a connected socket is stale, the plugin resends the reconnect handshake without reloading. Closing or crashing the browser can still lose changes that have not reached the server.

Compatibility

Tested with Etherpad 3.3.2 and Socket.IO client 4.8.3. Force Reconnect uses the runtime Manager.reconnect() method so upgrades should repeat the included unit and live backend-restart tests.

Testing

npm test