feat(frontend): XState statecharts

Expressing logic in statecharts for complex stateful behaviours should
improve maintainability

We use @xstate/cli to statically analyze statcharts before typechecking

4 files changed, 430 insertions, 320 deletions

diff --git a/subprojects/frontend/src/xtext/UpdateService.ts b/subprojects/frontend/src/xtext/UpdateService.ts
index f1abce52..d7471cdc 100644
--- a/subprojects/frontend/src/xtext/UpdateService.ts
+++ b/subprojects/frontend/src/xtext/UpdateService.ts
@@ -83,7 +83,7 @@ export default class UpdateService {
   }
 
   private idleUpdate(): void {
-    if (!this.webSocketClient.isOpen || !this.tracker.needsUpdate) {
+    if (!this.webSocketClient.opened || !this.tracker.needsUpdate) {
       return;
     }
     if (!this.tracker.lockedForUpdate) {
diff --git a/subprojects/frontend/src/xtext/XtextWebSocketClient.ts b/subprojects/frontend/src/xtext/XtextWebSocketClient.ts
index 60bf6ba9..eedfa365 100644
--- a/subprojects/frontend/src/xtext/XtextWebSocketClient.ts
+++ b/subprojects/frontend/src/xtext/XtextWebSocketClient.ts
@@ -1,34 +1,22 @@
+import { createAtom, makeAutoObservable, observable } from 'mobx';
 import { nanoid } from 'nanoid';
+import { interpret } from 'xstate';
 
+import CancelledError from '../utils/CancelledError';
 import PendingTask from '../utils/PendingTask';
-import Timer from '../utils/Timer';
 import getLogger from '../utils/getLogger';
 
+import webSocketMachine from './webSocketMachine';
 import {
-  XtextWebErrorResponse,
-  XtextWebRequest,
-  XtextWebOkResponse,
-  XtextWebPushMessage,
-  XtextWebPushService,
+  type XtextWebPushService,
+  XtextResponse,
+  type XtextWebRequest,
 } from './xtextMessages';
 import { PongResult } from './xtextServiceResults';
 
 const XTEXT_SUBPROTOCOL_V1 = 'tools.refinery.language.web.xtext.v1';
 
-const WEBSOCKET_CLOSE_OK = 1000;
-
-const WEBSOCKET_CLOSE_GOING_AWAY = 1001;
-
-const RECONNECT_DELAY_MS = [200, 1000, 5000, 30_000];
-
-const MAX_RECONNECT_DELAY_MS =
-  RECONNECT_DELAY_MS[RECONNECT_DELAY_MS.length - 1];
-
-const BACKGROUND_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
-
-const PING_TIMEOUT_MS = 10 * 1000;
-
-const REQUEST_TIMEOUT_MS = 1000;
+const REQUEST_TIMEOUT = 1000;
 
 const log = getLogger('xtext.XtextWebSocketClient');
 
@@ -41,351 +29,250 @@ export type PushHandler = (
   data: unknown,
 ) => void;
 
-enum State {
-  Initial,
-  Opening,
-  TabVisible,
-  TabHiddenIdle,
-  TabHiddenWaitingToClose,
-  Error,
-  ClosedDueToInactivity,
-}
-
 export default class XtextWebSocketClient {
-  private nextMessageId = 0;
+  private readonly stateAtom = createAtom('state');
 
-  private connection!: WebSocket;
+  private webSocket: WebSocket | undefined;
 
   private readonly pendingRequests = new Map<string, PendingTask<unknown>>();
 
-  private readonly onReconnect: ReconnectHandler;
-
-  private readonly onPush: PushHandler;
-
-  private state = State.Initial;
-
-  private reconnectTryCount = 0;
-
-  private readonly idleTimer = new Timer(() => {
-    this.handleIdleTimeout();
-  }, BACKGROUND_IDLE_TIMEOUT_MS);
-
-  private readonly pingTimer = new Timer(() => {
-    this.sendPing();
-  }, PING_TIMEOUT_MS);
+  private readonly interpreter = interpret(
+    webSocketMachine
+      .withContext({
+        ...webSocketMachine.context,
+        webSocketURL: `${window.location.origin.replace(
+          /^http/,
+          'ws',
+        )}/xtext-service`,
+      })
+      .withConfig({
+        actions: {
+          openWebSocket: ({ webSocketURL }) => this.openWebSocket(webSocketURL),
+          closeWebSocket: () => this.closeWebSocket(),
+          notifyReconnect: () => this.onReconnect(),
+          cancelPendingRequests: () => this.cancelPendingRequests(),
+        },
+        services: {
+          pingService: () => this.sendPing(),
+        },
+      }),
+    {
+      logger: log.log.bind(log),
+    },
+  );
+
+  private readonly openListener = () => {
+    if (this.webSocket === undefined) {
+      throw new Error('Open listener called without a WebSocket');
+    }
+    const {
+      webSocket: { protocol },
+    } = this;
+    if (protocol === XTEXT_SUBPROTOCOL_V1) {
+      this.interpreter.send('OPENED');
+    } else {
+      this.interpreter.send({
+        type: 'ERROR',
+        message: `Unknown subprotocol ${protocol}`,
+      });
+    }
+  };
 
-  private readonly reconnectTimer = new Timer(() => {
-    this.handleReconnect();
-  });
+  private readonly errorListener = (event: Event) => {
+    log.error('WebSocket error', event);
+    this.interpreter.send({ type: 'ERROR', message: 'WebSocket error' });
+  };
 
-  constructor(onReconnect: ReconnectHandler, onPush: PushHandler) {
-    this.onReconnect = onReconnect;
-    this.onPush = onPush;
-    document.addEventListener('visibilitychange', () => {
-      this.handleVisibilityChange();
+  private readonly closeListener = ({ code, reason }: CloseEvent) =>
+    this.interpreter.send({
+      type: 'ERROR',
+      message: `Socket closed unexpectedly: ${code} ${reason}`,
     });
-    this.reconnect();
-  }
 
-  private get isLogicallyClosed(): boolean {
-    return (
-      this.state === State.Error || this.state === State.ClosedDueToInactivity
-    );
-  }
-
-  get isOpen(): boolean {
-    return (
-      this.state === State.TabVisible ||
-      this.state === State.TabHiddenIdle ||
-      this.state === State.TabHiddenWaitingToClose
-    );
-  }
-
-  private reconnect() {
-    if (this.isOpen || this.state === State.Opening) {
-      log.error('Trying to reconnect from', this.state);
+  private readonly messageListener = ({ data }: MessageEvent) => {
+    if (typeof data !== 'string') {
+      this.interpreter.send({
+        type: 'ERROR',
+        message: 'Unexpected message format',
+      });
       return;
     }
-    this.state = State.Opening;
-    const webSocketServer = window.origin.replace(/^http/, 'ws');
-    const webSocketUrl = `${webSocketServer}/xtext-service`;
-    this.connection = new WebSocket(webSocketUrl, XTEXT_SUBPROTOCOL_V1);
-    this.connection.addEventListener('open', () => {
-      if (this.connection.protocol !== XTEXT_SUBPROTOCOL_V1) {
-        log.error(
-          'Unknown subprotocol',
-          this.connection.protocol,
-          'selected by server',
-        );
-        this.forceReconnectOnError();
-      }
-      if (document.visibilityState === 'hidden') {
-        this.handleTabHidden();
-      } else {
-        this.handleTabVisibleConnected();
-      }
-      log.info('Connected to websocket');
-      this.nextMessageId = 0;
-      this.reconnectTryCount = 0;
-      this.pingTimer.schedule();
-      this.onReconnect();
-    });
-    this.connection.addEventListener('error', (event) => {
-      log.error('Unexpected websocket error', event);
-      this.forceReconnectOnError();
-    });
-    this.connection.addEventListener('message', (event) => {
-      this.handleMessage(event.data);
-    });
-    this.connection.addEventListener('close', (event) => {
-      const closedOnRequest =
-        this.isLogicallyClosed &&
-        event.code === WEBSOCKET_CLOSE_OK &&
-        this.pendingRequests.size === 0;
-      const closedOnNavigation = event.code === WEBSOCKET_CLOSE_GOING_AWAY;
-      if (closedOnNavigation) {
-        this.state = State.ClosedDueToInactivity;
-      }
-      if (closedOnRequest || closedOnNavigation) {
-        log.info('Websocket closed');
-        return;
-      }
-      log.error('Websocket closed unexpectedly', event.code, event.reason);
-      this.forceReconnectOnError();
-    });
-  }
-
-  private handleVisibilityChange() {
-    if (document.visibilityState === 'hidden') {
-      if (this.state === State.TabVisible) {
-        this.handleTabHidden();
-      }
+    let json: unknown;
+    try {
+      json = JSON.parse(data);
+    } catch (error) {
+      log.error('JSON parse error', error);
+      this.interpreter.send({ type: 'ERROR', message: 'Malformed message' });
       return;
     }
-    this.idleTimer.cancel();
-    if (
-      this.state === State.TabHiddenIdle ||
-      this.state === State.TabHiddenWaitingToClose
-    ) {
-      this.handleTabVisibleConnected();
+    const responseResult = XtextResponse.safeParse(json);
+    if (!responseResult.success) {
+      log.error('Xtext response', json, 'is malformed:', responseResult.error);
+      this.interpreter.send({ type: 'ERROR', message: 'Malformed message' });
       return;
     }
-    if (this.state === State.ClosedDueToInactivity) {
-      this.reconnect();
+    const { data: response } = responseResult;
+    if ('service' in response) {
+      // `XtextWebPushMessage.push` is optional, but `service` is not.
+      const { resource, stateId, service, push } = response;
+      this.onPush(resource, stateId, service, push);
+      return;
+    }
+    const { id } = response;
+    const task = this.pendingRequests.get(id);
+    if (task === undefined) {
+      log.warn('Task', id, 'has been already resolved');
+      return;
+    }
+    this.removeTask(id);
+    if ('error' in response) {
+      const formattedMessage = `${response.error} error: ${response.message}`;
+      log.error('Task', id, formattedMessage);
+      task.reject(new Error(formattedMessage));
+    } else {
+      task.resolve(response.response);
     }
+  };
+
+  constructor(
+    private readonly onReconnect: ReconnectHandler,
+    private readonly onPush: PushHandler,
+  ) {
+    this.interpreter
+      .onTransition((state, event) => {
+        log.trace('WebSocke state transition', state.value, 'on event', event);
+        this.stateAtom.reportChanged();
+      })
+      .start();
+
+    this.updateVisibility();
+    document.addEventListener('visibilitychange', () =>
+      this.updateVisibility(),
+    );
+
+    this.interpreter.send('CONNECT');
+
+    makeAutoObservable<
+      XtextWebSocketClient,
+      | 'stateAtom'
+      | 'webSocket'
+      | 'interpreter'
+      | 'openListener'
+      | 'errorListener'
+      | 'closeListener'
+      | 'messageListener'
+      | 'sendPing'
+    >(this, {
+      stateAtom: false,
+      webSocket: observable.ref,
+      interpreter: false,
+      openListener: false,
+      errorListener: false,
+      closeListener: false,
+      messageListener: false,
+      sendPing: false,
+    });
   }
 
-  private handleTabHidden() {
-    log.debug('Tab hidden while websocket is connected');
-    this.state = State.TabHiddenIdle;
-    this.idleTimer.schedule();
+  get state() {
+    this.stateAtom.reportObserved();
+    return this.interpreter.state;
   }
 
-  private handleTabVisibleConnected() {
-    log.debug('Tab visible while websocket is connected');
-    this.state = State.TabVisible;
+  get opened(): boolean {
+    return this.state.matches('connection.socketCreated.open.opened');
   }
 
-  private handleIdleTimeout() {
-    log.trace('Waiting for pending tasks before disconnect');
-    if (this.state === State.TabHiddenIdle) {
-      this.state = State.TabHiddenWaitingToClose;
-      this.handleWaitingForDisconnect();
-    }
+  connect(): void {
+    this.interpreter.send('CONNECT');
   }
 
-  private handleWaitingForDisconnect() {
-    if (this.state !== State.TabHiddenWaitingToClose) {
-      return;
-    }
-    const pending = this.pendingRequests.size;
-    if (pending === 0) {
-      log.info('Closing idle websocket');
-      this.state = State.ClosedDueToInactivity;
-      this.closeConnection(1000, 'idle timeout');
-      return;
-    }
-    log.info(
-      'Waiting for',
-      pending,
-      'pending requests before closing websocket',
-    );
+  disconnect(): void {
+    this.interpreter.send('DISCONNECT');
   }
 
-  private sendPing() {
-    if (!this.isOpen) {
-      return;
-    }
-    const ping = nanoid();
-    log.trace('Ping', ping);
-    this.send({ ping })
-      .then((result) => {
-        const parsedPongResult = PongResult.safeParse(result);
-        if (parsedPongResult.success && parsedPongResult.data.pong === ping) {
-          log.trace('Pong', ping);
-          this.pingTimer.schedule();
-        } else {
-          log.error('Invalid pong:', parsedPongResult, 'expected:', ping);
-          this.forceReconnectOnError();
-        }
-      })
-      .catch((error) => {
-        log.error('Error while waiting for ping', error);
-        this.forceReconnectOnError();
-      });
+  forceReconnectOnError(): void {
+    this.interpreter.send({
+      type: 'ERROR',
+      message: 'Client error',
+    });
   }
 
   send(request: unknown): Promise<unknown> {
-    if (!this.isOpen) {
-      throw new Error('Not open');
-    }
-    const messageId = this.nextMessageId.toString(16);
-    if (messageId in this.pendingRequests) {
-      log.error('Message id wraparound still pending', messageId);
-      this.rejectRequest(messageId, new Error('Message id wraparound'));
+    if (!this.opened || this.webSocket === undefined) {
+      throw new Error('Not connected');
     }
-    if (this.nextMessageId >= Number.MAX_SAFE_INTEGER) {
-      this.nextMessageId = 0;
-    } else {
-      this.nextMessageId += 1;
-    }
-    const message = JSON.stringify({
-      id: messageId,
-      request,
-    } as XtextWebRequest);
-    log.trace('Sending message', message);
-    return new Promise((resolve, reject) => {
-      const task = new PendingTask(resolve, reject, REQUEST_TIMEOUT_MS, () => {
-        this.removePendingRequest(messageId);
-      });
-      this.pendingRequests.set(messageId, task);
-      this.connection.send(message);
+
+    const id = nanoid();
+
+    const promise = new Promise((resolve, reject) => {
+      const task = new PendingTask(resolve, reject, REQUEST_TIMEOUT, () =>
+        this.removeTask(id),
+      );
+      this.pendingRequests.set(id, task);
     });
+
+    const webRequest: XtextWebRequest = { id, request };
+    const json = JSON.stringify(webRequest);
+    this.webSocket.send(json);
+
+    return promise;
   }
 
-  private handleMessage(messageStr: unknown) {
-    if (typeof messageStr !== 'string') {
-      log.error('Unexpected binary message', messageStr);
-      this.forceReconnectOnError();
-      return;
-    }
-    log.trace('Incoming websocket message', messageStr);
-    let message: unknown;
-    try {
-      message = JSON.parse(messageStr);
-    } catch (error) {
-      log.error('Json parse error', error);
-      this.forceReconnectOnError();
-      return;
-    }
-    const okResponse = XtextWebOkResponse.safeParse(message);
-    if (okResponse.success) {
-      const { id, response } = okResponse.data;
-      this.resolveRequest(id, response);
-      return;
-    }
-    const errorResponse = XtextWebErrorResponse.safeParse(message);
-    if (errorResponse.success) {
-      const { id, error, message: errorMessage } = errorResponse.data;
-      this.rejectRequest(id, new Error(`${error} error: ${errorMessage}`));
-      if (error === 'server') {
-        log.error('Reconnecting due to server error: ', errorMessage);
-        this.forceReconnectOnError();
-      }
-      return;
-    }
-    const pushMessage = XtextWebPushMessage.safeParse(message);
-    if (pushMessage.success) {
-      const { resource, stateId, service, push } = pushMessage.data;
-      this.onPush(resource, stateId, service, push);
-    } else {
-      log.error(
-        'Unexpected websocket message:',
-        message,
-        'not ok response because:',
-        okResponse.error,
-        'not error response because:',
-        errorResponse.error,
-        'not push message because:',
-        pushMessage.error,
-      );
-      this.forceReconnectOnError();
-    }
+  private updateVisibility(): void {
+    this.interpreter.send(document.hidden ? 'TAB_HIDDEN' : 'TAB_VISIBLE');
   }
 
-  private resolveRequest(messageId: string, value: unknown) {
-    const pendingRequest = this.pendingRequests.get(messageId);
-    if (pendingRequest) {
-      pendingRequest.resolve(value);
-      this.removePendingRequest(messageId);
-      return;
+  private openWebSocket(webSocketURL: string | undefined): void {
+    if (this.webSocket !== undefined) {
+      throw new Error('WebSocket already open');
     }
-    log.error('Trying to resolve unknown request', messageId, 'with', value);
-  }
 
-  private rejectRequest(messageId: string, reason?: unknown) {
-    const pendingRequest = this.pendingRequests.get(messageId);
-    if (pendingRequest) {
-      pendingRequest.reject(reason);
-      this.removePendingRequest(messageId);
-      return;
+    if (webSocketURL === undefined) {
+      throw new Error('URL not configured');
     }
-    log.error('Trying to reject unknown request', messageId, 'with', reason);
-  }
 
-  private removePendingRequest(messageId: string) {
-    this.pendingRequests.delete(messageId);
-    this.handleWaitingForDisconnect();
+    log.debug('Creating WebSocket');
+
+    this.webSocket = new WebSocket(webSocketURL, XTEXT_SUBPROTOCOL_V1);
+    this.webSocket.addEventListener('open', this.openListener);
+    this.webSocket.addEventListener('close', this.closeListener);
+    this.webSocket.addEventListener('error', this.errorListener);
+    this.webSocket.addEventListener('message', this.messageListener);
   }
 
-  forceReconnectOnError(): void {
-    if (this.isLogicallyClosed) {
-      return;
-    }
-    this.pendingRequests.forEach((request) => {
-      request.reject(new Error('Websocket disconnect'));
-    });
-    this.pendingRequests.clear();
-    this.closeConnection(1000, 'reconnecting due to error');
-    if (this.state === State.Error) {
-      // We are already handling this error condition.
-      return;
+  private closeWebSocket() {
+    if (this.webSocket === undefined) {
+      throw new Error('WebSocket already closed');
     }
-    if (
-      this.state === State.TabHiddenIdle ||
-      this.state === State.TabHiddenWaitingToClose
-    ) {
-      log.error('Will reconned due to error once the tab becomes visible');
-      this.idleTimer.cancel();
-      this.state = State.ClosedDueToInactivity;
-      return;
-    }
-    log.error('Reconnecting after delay due to error');
-    this.state = State.Error;
-    this.reconnectTryCount += 1;
-    const delay =
-      RECONNECT_DELAY_MS[this.reconnectTryCount - 1] ?? MAX_RECONNECT_DELAY_MS;
-    log.info('Reconnecting in', delay, 'ms');
-    this.reconnectTimer.schedule(delay);
+
+    log.debug('Closing WebSocket');
+
+    this.webSocket.removeEventListener('open', this.openListener);
+    this.webSocket.removeEventListener('close', this.closeListener);
+    this.webSocket.removeEventListener('error', this.errorListener);
+    this.webSocket.removeEventListener('message', this.messageListener);
+    this.webSocket.close(1000, 'Closing connection');
+    this.webSocket = undefined;
   }
 
-  private closeConnection(code: number, reason: string) {
-    this.pingTimer.cancel();
-    const { readyState } = this.connection;
-    if (readyState !== WebSocket.CLOSING && readyState !== WebSocket.CLOSED) {
-      this.connection.close(code, reason);
-    }
+  private removeTask(id: string): void {
+    this.pendingRequests.delete(id);
   }
 
-  private handleReconnect() {
-    if (this.state !== State.Error) {
-      log.error('Unexpected reconnect in', this.state);
-      return;
-    }
-    if (document.visibilityState === 'hidden') {
-      this.state = State.ClosedDueToInactivity;
-    } else {
-      this.reconnect();
+  private cancelPendingRequests(): void {
+    this.pendingRequests.forEach((task) =>
+      task.reject(new CancelledError('Closing connection')),
+    );
+    this.pendingRequests.clear();
+  }
+
+  private async sendPing(): Promise<void> {
+    const ping = nanoid();
+    const result = await this.send({ ping });
+    const { pong } = PongResult.parse(result);
+    if (ping !== pong) {
+      throw new Error(`Expected pong ${ping} but got ${pong} instead`);
     }
   }
 }
diff --git a/subprojects/frontend/src/xtext/webSocketMachine.ts b/subprojects/frontend/src/xtext/webSocketMachine.ts
new file mode 100644
index 00000000..50eb36a0
--- /dev/null
+++ b/subprojects/frontend/src/xtext/webSocketMachine.ts
@@ -0,0 +1,215 @@
+import { actions, assign, createMachine, RaiseAction } from 'xstate';
+
+const { raise } = actions;
+
+const ERROR_WAIT_TIMES = [200, 1000, 5000, 30_000];
+
+export interface WebSocketContext {
+  webSocketURL: string | undefined;
+  errors: string[];
+  retryCount: number;
+}
+
+export type WebSocketEvent =
+  | { type: 'CONFIGURE'; webSocketURL: string }
+  | { type: 'CONNECT' }
+  | { type: 'DISCONNECT' }
+  | { type: 'OPENED' }
+  | { type: 'TAB_VISIBLE' }
+  | { type: 'TAB_HIDDEN' }
+  | { type: 'ERROR'; message: string };
+
+export default createMachine(
+  {
+    id: 'webSocket',
+    predictableActionArguments: true,
+    schema: {
+      context: {} as WebSocketContext,
+      events: {} as WebSocketEvent,
+    },
+    tsTypes: {} as import('./webSocketMachine.typegen').Typegen0,
+    context: {
+      webSocketURL: undefined,
+      errors: [],
+      retryCount: 0,
+    },
+    type: 'parallel',
+    states: {
+      connection: {
+        initial: 'disconnected',
+        states: {
+          disconnected: {
+            id: 'disconnected',
+            on: {
+              CONFIGURE: { actions: 'configure' },
+            },
+          },
+          timedOut: {
+            id: 'timedOut',
+            on: {
+              TAB_VISIBLE: 'socketCreated',
+            },
+          },
+          errorWait: {
+            id: 'errorWait',
+            after: {
+              ERROR_WAIT_TIME: [
+                { target: 'timedOut', in: '#tabHidden' },
+                { target: 'socketCreated' },
+              ],
+            },
+          },
+          socketCreated: {
+            type: 'parallel',
+            entry: 'openWebSocket',
+            exit: ['cancelPendingRequests', 'closeWebSocket'],
+            states: {
+              open: {
+                initial: 'opening',
+                states: {
+                  opening: {
+                    after: {
+                      OPEN_TIMEOUT: {
+                        actions: 'raiseTimeoutError',
+                      },
+                    },
+                    on: {
+                      OPENED: {
+                        target: 'opened',
+                        actions: ['clearError', 'notifyReconnect'],
+                      },
+                    },
+                  },
+                  opened: {
+                    initial: 'pongReceived',
+                    states: {
+                      pongReceived: {
+                        after: {
+                          PING_PERIOD: 'pingSent',
+                        },
+                      },
+                      pingSent: {
+                        invoke: {
+                          src: 'pingService',
+                          onDone: 'pongReceived',
+                          onError: {
+                            actions: 'raisePromiseRejectionError',
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+              idle: {
+                initial: 'getTabState',
+                states: {
+                  getTabState: {
+                    always: [
+                      { target: 'inactive', in: '#tabHidden' },
+                      'active',
+                    ],
+                  },
+                  active: {
+                    on: {
+                      TAB_HIDDEN: 'inactive',
+                    },
+                  },
+                  inactive: {
+                    after: {
+                      IDLE_TIMEOUT: '#timedOut',
+                    },
+                    on: {
+                      TAB_VISIBLE: 'active',
+                    },
+                  },
+                },
+              },
+            },
+            on: {
+              CONNECT: undefined,
+              ERROR: {
+                target: '#errorWait',
+                actions: 'increaseRetryCount',
+              },
+            },
+          },
+        },
+        on: {
+          CONNECT: { target: '.socketCreated', cond: 'hasWebSocketURL' },
+          DISCONNECT: { target: '.disconnected', actions: 'clearError' },
+        },
+      },
+      tab: {
+        initial: 'visibleOrUnknown',
+        states: {
+          visibleOrUnknown: {
+            on: {
+              TAB_HIDDEN: 'hidden',
+            },
+          },
+          hidden: {
+            id: 'tabHidden',
+            on: {
+              TAB_VISIBLE: 'visibleOrUnknown',
+            },
+          },
+        },
+      },
+      error: {
+        initial: 'init',
+        states: {
+          init: {
+            on: {
+              ERROR: { actions: 'pushError' },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    guards: {
+      hasWebSocketURL: ({ webSocketURL }) => webSocketURL !== undefined,
+    },
+    delays: {
+      IDLE_TIMEOUT: 300_000,
+      OPEN_TIMEOUT: 5000,
+      PING_PERIOD: 10_000,
+      ERROR_WAIT_TIME: ({ retryCount }) => {
+        const { length } = ERROR_WAIT_TIMES;
+        const index = retryCount < length ? retryCount : length - 1;
+        return ERROR_WAIT_TIMES[index];
+      },
+    },
+    actions: {
+      configure: assign((context, { webSocketURL }) => ({
+        ...context,
+        webSocketURL,
+      })),
+      pushError: assign((context, { message }) => ({
+        ...context,
+        errors: [...context.errors, message],
+      })),
+      increaseRetryCount: assign((context) => ({
+        ...context,
+        retryCount: context.retryCount + 1,
+      })),
+      clearError: assign((context) => ({
+        ...context,
+        errors: [],
+        retryCount: 0,
+      })),
+      // Workaround from https://github.com/statelyai/xstate/issues/1414#issuecomment-699972485
+      raiseTimeoutError: raise({
+        type: 'ERROR',
+        message: 'Open timeout',
+      }) as RaiseAction<WebSocketEvent>,
+      raisePromiseRejectionError: (_context, { data }) =>
+        raise({
+          type: 'ERROR',
+          message: data,
+        }) as RaiseAction<WebSocketEvent>,
+    },
+  },
+);
diff --git a/subprojects/frontend/src/xtext/xtextMessages.ts b/subprojects/frontend/src/xtext/xtextMessages.ts
index c4d0c676..ec7a2a31 100644
--- a/subprojects/frontend/src/xtext/xtextMessages.ts
+++ b/subprojects/frontend/src/xtext/xtextMessages.ts
@@ -40,3 +40,11 @@ export const XtextWebPushMessage = z.object({
 });
 
 export type XtextWebPushMessage = z.infer<typeof XtextWebPushMessage>;
+
+export const XtextResponse = z.union([
+  XtextWebOkResponse,
+  XtextWebErrorResponse,
+  XtextWebPushMessage,
+]);
+
+export type XtextResponse = z.infer<typeof XtextResponse>;