feat: Add customizable sync error messages for session desync scenarios (#23267)

When client and server message IDs get out of sync (e.g., after abrupt
pod termination), a specific MessageIdSyncException is now thrown
instead of UnsupportedOperationException.

Developers can customize the error notification via SystemMessages:
- setSyncErrorCaption/Message/URL for custom content
- setSyncErrorNotificationEnabled(false) for silent page refresh

Fixes vaadin/kubernetes-kit#267

Author: mcollovati

flow-server/src/main/java/com/vaadin/flow/server/CustomizedSystemMessages.java

@@ -41,6 +41,8 @@
  * <li>Cookies disabled: the cookie support is disabled in the browser.
  * <li>Internal error: unhandled critical server error (e.g out of memory,
  * database crash)
+ * <li>Synchronization error: client and server are out of sync due to abrupt
+ * server termination (e.g., OOMKilled, SIGKILL) before UI state was saved
  * </ul>
  *
  * @since 1.0
@@ -207,4 +209,61 @@ public void setCookiesDisabledMessage(String cookiesDisabledMessage) {
         this.cookiesDisabledMessage = cookiesDisabledMessage;
     }
 
+    /**
+     * Sets the URL the user will be redirected to after dismissing a
+     * "synchronization error" message.
+     *
+     * Default value is {@literal null}.
+     *
+     * @param syncErrorURL
+     *            the URL to redirect to, or null to refresh the page
+     * @since 25.1
+     */
+    public void setSyncErrorURL(String syncErrorURL) {
+        this.syncErrorURL = syncErrorURL;
+    }
+
+    /**
+     * Sets whether a "synchronization error" notification should be shown to
+     * the end user. If the notification is disabled the user will be
+     * immediately redirected to the URL returned by {@link #getSyncErrorURL()}.
+     * <p>
+     * Synchronization errors occur when the client and server become out of
+     * sync, typically due to an abrupt server restart (e.g., OOMKilled,
+     * SIGKILL) before the UI state could be serialized.
+     *
+     * By default, the "synchronization error" notification is enabled.
+     *
+     * @param syncErrorNotificationEnabled
+     *            {@code true} to show the notification to the end user,
+     *            {@code false} to redirect directly
+     * @since 25.1
+     */
+    public void setSyncErrorNotificationEnabled(
+            boolean syncErrorNotificationEnabled) {
+        this.syncErrorNotificationEnabled = syncErrorNotificationEnabled;
+    }
+
+    /**
+     * Sets the caption to show in a "synchronization error" notification.
+     *
+     * @param syncErrorCaption
+     *            The caption to show or {@code null} to show no caption.
+     * @since 25.1
+     */
+    public void setSyncErrorCaption(String syncErrorCaption) {
+        this.syncErrorCaption = syncErrorCaption;
+    }
+
+    /**
+     * Sets the message to show in a "synchronization error" notification.
+     *
+     * @param syncErrorMessage
+     *            The message to show or {@code null} to show no message.
+     * @since 25.1
+     */
+    public void setSyncErrorMessage(String syncErrorMessage) {
+        this.syncErrorMessage = syncErrorMessage;
+    }
+
 }

flow-server/src/main/java/com/vaadin/flow/server/SystemMessages.java

@@ -42,6 +42,11 @@
  * <li><b>cookiesDisabledMessage</b> = "This application requires cookies to
  * function. Please enable cookies in your browser and click here or press ESC
  * to try again.</li>
+ * <li><b>syncErrorURL</b> = null</li>
+ * <li><b>syncErrorNotificationEnabled</b> = true</li>
+ * <li><b>syncErrorCaption</b> = "Synchronization Error"</li>
+ * <li><b>syncErrorMessage</b> = "Your session needs to be refreshed. Click here
+ * or press ESC to reload and restore your last saved state."</li>
  * </ul>
  *
  * @since 1.0
@@ -62,6 +67,11 @@ public class SystemMessages implements Serializable {
     protected String cookiesDisabledCaption = "Cookies disabled";
     protected String cookiesDisabledMessage = "This application requires cookies to function. Please enable cookies in your browser and click here or press ESC to try again.";
 
+    protected String syncErrorURL = null;
+    protected boolean syncErrorNotificationEnabled = true;
+    protected String syncErrorCaption = "Synchronization Error";
+    protected String syncErrorMessage = "Your session needs to be refreshed. Click here or press ESC to reload and restore your last saved state.";
+
     /**
      * Private constructor
      */
@@ -221,4 +231,62 @@ public String getCookiesDisabledMessage() {
                 : null);
     }
 
+    /**
+     * Gets the URL the user will be redirected to after dismissing a
+     * "synchronization error" message.
+     *
+     * Default value is {@literal null}.
+     *
+     * @return the URL to redirect to, or null to refresh the page
+     * @since 25.1
+     */
+    public String getSyncErrorURL() {
+        return syncErrorURL;
+    }
+
+    /**
+     * Checks if "synchronization error" notifications should be shown to the
+     * end user. If the notification is disabled the user will be immediately
+     * redirected to the URL returned by {@link #getSyncErrorURL()}.
+     * <p>
+     * Synchronization errors occur when the client and server become out of
+     * sync, typically due to an abrupt server restart (e.g., OOMKilled,
+     * SIGKILL) before the UI state could be serialized.
+     *
+     * By default, the "synchronization error" notification is enabled.
+     *
+     * @return {@code true} to show the notification to the end user,
+     *         {@code false} to redirect directly
+     * @since 25.1
+     */
+    public boolean isSyncErrorNotificationEnabled() {
+        return syncErrorNotificationEnabled;
+    }
+
+    /**
+     * Gets the caption to show in a "synchronization error" notification.
+     *
+     * Returns {@literal null} if the "synchronization error" notification is
+     * disabled.
+     *
+     * @return The caption to show or {@code null} to show no caption.
+     * @since 25.1
+     */
+    public String getSyncErrorCaption() {
+        return (syncErrorNotificationEnabled ? syncErrorCaption : null);
+    }
+
+    /**
+     * Gets the message to show in a "synchronization error" notification.
+     *
+     * Returns {@literal null} if the "synchronization error" notification is
+     * disabled.
+     *
+     * @return The message to show or {@code null} to show no message.
+     * @since 25.1
+     */
+    public String getSyncErrorMessage() {
+        return (syncErrorNotificationEnabled ? syncErrorMessage : null);
+    }
+
 }

flow-server/src/main/java/com/vaadin/flow/server/communication/PushHandler.java

@@ -51,6 +51,7 @@
 import com.vaadin.flow.server.VaadinServletService;
 import com.vaadin.flow.server.VaadinSession;
 import com.vaadin.flow.server.communication.ServerRpcHandler.InvalidUIDLSecurityKeyException;
+import com.vaadin.flow.server.communication.ServerRpcHandler.MessageIdSyncException;
 import com.vaadin.flow.server.dau.DAUUtils;
 import com.vaadin.flow.server.dau.DauEnforcementException;
 import com.vaadin.flow.server.startup.ApplicationConfiguration;
@@ -78,6 +79,8 @@ public class PushHandler {
      */
     private final Map<String, Long> disconnectedUuidBuffer = new ConcurrentHashMap<>();
 
+    private VaadinServletService service;
+
     /**
      * Callback interface used internally to process an event with the
      * corresponding UI properly locked.
@@ -176,6 +179,18 @@ interface PushEventCallback {
                     resource.getRequest().getRemoteHost());
             // Refresh on client side
             sendRefreshAndDisconnect(resource);
+        } catch (MessageIdSyncException e) {
+            getLogger().warn(
+                    "Message ID sync error. Expected: {}, received: {}",
+                    e.getExpectedId(), e.getReceivedId());
+            SystemMessages msgs = service.getSystemMessages(
+                    HandlerHelper.findLocale(null, vaadinRequest),
+                    vaadinRequest);
+            sendNotificationAndDisconnect(resource,
+                    VaadinService.createCriticalNotificationJSON(
+                            msgs.getSyncErrorCaption(),
+                            msgs.getSyncErrorMessage(), null,
+                            msgs.getSyncErrorURL()));
         } catch (DauEnforcementException e) {
             getLogger().warn(
                     "Daily Active User limit reached. Blocking new user request");
@@ -185,8 +200,6 @@ interface PushEventCallback {
 
     };
 
-    private VaadinServletService service;
-
     /**
      * Creates an instance connected to the given service.
      *

flow-server/src/main/java/com/vaadin/flow/server/communication/ServerRpcHandler.java

@@ -252,6 +252,57 @@ public ClientResentPayloadException() {
         }
     }
 
+    /**
+     * Exception thrown when the client sends a message with an unexpected
+     * message ID, indicating that the client and server are out of sync.
+     * <p>
+     * This typically occurs when a server pod terminates abruptly (e.g.,
+     * OOMKilled, SIGKILL) before UI state can be serialized to distributed
+     * session storage. When clients reconnect to a healthy pod, their message
+     * ID exceeds what the server expects.
+     *
+     * @since 25.1
+     */
+    public static class MessageIdSyncException extends Exception {
+
+        private final int expectedId;
+        private final int receivedId;
+
+        /**
+         * Creates a new MessageIdSyncException with the expected and received
+         * message IDs.
+         *
+         * @param expectedId
+         *            the message ID the server expected
+         * @param receivedId
+         *            the message ID received from the client
+         */
+        public MessageIdSyncException(int expectedId, int receivedId) {
+            super("Unexpected message id from the client. Expected: "
+                    + expectedId + ", got: " + receivedId);
+            this.expectedId = expectedId;
+            this.receivedId = receivedId;
+        }
+
+        /**
+         * Gets the message ID the server expected.
+         *
+         * @return the expected message ID
+         */
+        public int getExpectedId() {
+            return expectedId;
+        }
+
+        /**
+         * Gets the message ID received from the client.
+         *
+         * @return the received message ID
+         */
+        public int getReceivedId() {
+            return receivedId;
+        }
+    }
+
     /**
      * Reads JSON containing zero or more serialized RPC calls (including legacy
      * variable changes) and executes the calls.
@@ -269,7 +320,8 @@ public ClientResentPayloadException() {
      *             the session.
      */
     public void handleRpc(UI ui, Reader reader, VaadinRequest request)
-            throws IOException, InvalidUIDLSecurityKeyException {
+            throws IOException, InvalidUIDLSecurityKeyException,
+            MessageIdSyncException {
         handleRpc(ui, SynchronizedRequestHandler.getRequestBody(reader),
                 request);
     }
@@ -289,7 +341,7 @@ public void handleRpc(UI ui, Reader reader, VaadinRequest request)
      *             the session.
      */
     public void handleRpc(UI ui, String message, VaadinRequest request)
-            throws InvalidUIDLSecurityKeyException {
+            throws InvalidUIDLSecurityKeyException, MessageIdSyncException {
         ui.getSession().setLastRequestTimestamp(System.currentTimeMillis());
 
         if (message == null || message.isEmpty()) {
@@ -362,11 +414,7 @@ public void handleRpc(UI ui, String message, VaadinRequest request)
                 getLogger().debug("Unexpected message id from the client."
                         + " Expected client id: " + expectedId + ", got "
                         + requestId + ". Message start: " + messageDetails);
-                throw new UnsupportedOperationException(
-                        "Unexpected message id from the client."
-                                + " Expected client id: " + expectedId
-                                + ", got " + requestId
-                                + ". more details logged on DEBUG level.");
+                throw new MessageIdSyncException(expectedId, requestId);
             }
         } else {
             // Message id ok, process RPCs

flow-server/src/main/java/com/vaadin/flow/server/communication/UidlRequestHandler.java

@@ -38,12 +38,14 @@
 import com.vaadin.flow.server.HttpStatusCode;
 import com.vaadin.flow.server.SessionExpiredHandler;
 import com.vaadin.flow.server.SynchronizedRequestHandler;
+import com.vaadin.flow.server.SystemMessages;
 import com.vaadin.flow.server.VaadinRequest;
 import com.vaadin.flow.server.VaadinResponse;
 import com.vaadin.flow.server.VaadinService;
 import com.vaadin.flow.server.VaadinSession;
 import com.vaadin.flow.server.communication.ServerRpcHandler.ClientResentPayloadException;
 import com.vaadin.flow.server.communication.ServerRpcHandler.InvalidUIDLSecurityKeyException;
+import com.vaadin.flow.server.communication.ServerRpcHandler.MessageIdSyncException;
 import com.vaadin.flow.server.communication.ServerRpcHandler.ResynchronizationRequiredException;
 import com.vaadin.flow.server.dau.DAUUtils;
 import com.vaadin.flow.server.dau.DauEnforcementException;
@@ -145,6 +147,14 @@ public Optional<ResponseWriter> synchronizedHandleRequest(
                     request.getRemoteHost());
             // Refresh on client side
             return Optional.of(() -> writeRefresh(response));
+        } catch (MessageIdSyncException e) {
+            getLogger().warn(
+                    "Message ID sync error. Expected: {}, received: {}",
+                    e.getExpectedId(), e.getReceivedId());
+            SystemMessages systemMessages = session.getService()
+                    .getSystemMessages(HandlerHelper.findLocale(null, request),
+                            request);
+            return Optional.of(() -> writeSyncError(systemMessages, response));
         } catch (DauEnforcementException e) {
             getLogger().warn(
                     "Daily Active User limit reached. Blocking new user request");
@@ -169,6 +179,15 @@ private void writeRefresh(VaadinResponse response) throws IOException {
         commitJsonResponse(response, json);
     }
 
+    private void writeSyncError(SystemMessages systemMessages,
+            VaadinResponse response) throws IOException {
+        String json = VaadinService.createCriticalNotificationJSON(
+                systemMessages.getSyncErrorCaption(),
+                systemMessages.getSyncErrorMessage(), null,
+                systemMessages.getSyncErrorURL());
+        commitJsonResponse(response, json);
+    }
+
     void writeUidl(UI ui, Writer writer, boolean resync) throws IOException {
         ObjectNode uidl = createUidl(ui, resync);