(core) Converting server-side Comm.js to typescript

Summary:
- Add app/common/CommTypes.ts to define types shared by client and server.
- Include @types/ws npm package

Test Plan: Intended to have no changes in behavior

Reviewers: paulfitz

Reviewed By: paulfitz

Differential Revision: https://phab.getgrist.com/D3467

app/common/CommTypes.ts

@@ -0,0 +1,146 @@
+import {ActionGroup} from 'app/common/ActionGroup';
+import {DocAction} from 'app/common/DocActions';
+import {FilteredDocUsageSummary} from 'app/common/DocUsage';
+import {Product} from 'app/common/Features';
+import {StringUnion} from 'app/common/StringUnion';
+import {UserProfile} from 'app/common/LoginSessionAPI';
+
+export const ValidEvent = StringUnion('docListAction', 'docUserAction', 'docShutdown', 'docError',
+                               'docUsage', 'clientConnect');
+export type ValidEvent = typeof ValidEvent.type;
+
+
+/**
+ * A request in the appropriate form for sending to the server.
+ */
+export interface CommRequest {
+  reqId: number;
+  method: string;
+  args: any[];
+}
+
+/**
+ * A regular, successful response from the server.
+ */
+export interface CommResponse {
+  reqId: number;
+  data: any;
+  error?: null;  // TODO: keep until sure server never sets this on regular responses.
+}
+
+/**
+ * An exceptional response from the server when there is an error.
+ */
+export interface CommResponseError {
+  reqId: number;
+  error: string;
+  errorCode?: string;
+  shouldFork?: boolean;  // if set, the server suggests forking the document.
+  details?: any;  // if set, error has extra details available. TODO - the treatment of
+                  // details could do with some harmonisation between rest API and ws API,
+                  // and between front-end and back-end types.
+}
+
+/**
+ * A message pushed from the server, not in response to a request.
+ */
+export interface CommMessageBase {
+  type: ValidEvent;
+  docFD?: number;
+  data?: unknown;
+}
+
+export type CommDocMessage = CommDocUserAction | CommDocUsage | CommDocShutdown | CommDocError;
+export type CommMessage = CommDocMessage | CommDocListAction | CommClientConnect;
+
+export type CommDocEventType = CommDocMessage['type']
+
+/**
+ * Event for a change to the document list.
+ * These are sent to all connected clients, regardless of which documents they have open.
+ * TODO: This is entirely unused at the moment.
+ */
+export interface CommDocListAction extends CommMessageBase {
+  type: 'docListAction';
+  addDocs?: string[];        //  names of documents to add to the docList.
+  removeDocs?: string[];     //  names of documents that got removed.
+  renameDocs?: string[];     //  [oldName, newName] pairs for renamed docs.
+  addInvites?: string[];     //  document invite names to add.
+  removeInvites?: string[];  //  documents invite names to remove.
+}
+
+/**
+ * Event for a user action on a document, or part of one. Sent to all clients that have this
+ * document open.
+ */
+export interface CommDocUserAction extends CommMessageBase {
+  type: 'docUserAction';
+  docFD: number;           // The file descriptor of the open document, specific to each client.
+  fromSelf?: boolean;      // Flag to indicate whether the action originated from this client.
+
+  // ActionGroup object containing user action, and doc actions.
+  data: {
+    docActions: DocAction[];
+    actionGroup: ActionGroup;
+    docUsage: FilteredDocUsageSummary;
+    error?: string;
+  };
+}
+
+/**
+ * Event for a change to document usage. Sent to all clients that have this document open.
+ */
+export interface CommDocUsage extends CommMessageBase {
+  type: 'docUsage';
+  docFD: number;           // The file descriptor of the open document, specific to each client.
+  data: {
+    docUsage: FilteredDocUsageSummary;  // Document usage summary.
+    product?: Product;                  //Product that was used to compute `data.docUsage`
+  };
+}
+
+/**
+ * Event for when a document is forcibly shutdown, and requires the client to re-open it.
+ */
+export interface CommDocShutdown extends CommMessageBase {
+  type: 'docShutdown';
+  docFD: number;
+  data: null;
+}
+
+/**
+ * Event that signals an error while opening a doc.
+ */
+export interface CommDocError extends CommMessageBase {
+  type: 'docError';
+  docFD: number;
+  data: {
+    when: string;
+    message: string;
+  }
+}
+
+/**
+ * Event sent by server received when a client first connects.
+ */
+export interface CommClientConnect extends CommMessageBase {
+  type: 'clientConnect';
+
+  // ID for the client, which may be reused if a client reconnects to reattach to its state on
+  // the server.
+  clientId: string;
+
+  // Array of serialized messages missed from the server while disconnected.
+  missedMessages: string[];
+
+  // Which version the server reports for itself.
+  serverVersion?: string;
+
+  // Object containing server settings and features which should be used to initialize the client.
+  settings?: {[key: string]: unknown};
+
+  // Object containing session profile information if the user is signed in, or null otherwise.
+  profile: UserProfile|null;
+
+  dup?: boolean;  // Flag that's set to true when it's a duplicate clientConnect message.
+}