[ZEPPELIN-6456] Share websocket operation contract

.github/workflows/frontend.yml

@@ -92,6 +92,10 @@ jobs:
           channel-priority: strict
       - name: Install application
         run: ./mvnw clean install -DskipTests -am -pl python,zeppelin-jupyter-interpreter,zeppelin-web,zeppelin-web-angular -Pweb-classic ${MAVEN_ARGS}
+      - name: Check websocket operation contract
+        if: matrix.mode == 'anonymous'
+        working-directory: zeppelin-web-angular
+        run: ./node/npm run check:websocket-contract
       # Keeps the Karma coverage previously run by the removed zeppelin-web e2e job
       - name: Run zeppelin-web unit tests
         if: matrix.mode == 'anonymous'

zeppelin-common/src/main/java/org/apache/zeppelin/common/Message.java

@@ -28,8 +28,12 @@
 import java.util.Set;
 
 /**
- * Copied from zeppelin-server (TODO, zjffdu). Should resume the same piece of code instead of copying.
- * Zeppelin websocket message template class.
+ * Shared websocket message contract used by Zeppelin server and Java clients.
+ *
+ * <p>Operation names are part of the public wire protocol and must remain backward compatible. CI
+ * verifies that the Angular websocket operation enum remains synchronized with this enum.
+ * When adding a wire operation, add the same name and value to the Angular enum. Frontend-only
+ * events belong only in the Angular enum and must be marked {@code @frontendOnly}.
  */
 public class Message implements JsonSerializable {
   /**
@@ -174,7 +178,7 @@ public enum OP {
     APP_STATUS_CHANGE,            // [s-c] on app status change
 
     LIST_NOTE_JOBS,               // [c-s] get note job management information
-    LIST_UPDATE_NOTE_JOBS,        // [c-s] get job management information for until unixtime
+    LIST_UPDATE_NOTE_JOBS,        // [s-c] update job management information
     UNSUBSCRIBE_UPDATE_NOTE_JOBS, // [c-s] unsubscribe job information for job management
     JOB_MANAGER_DISABLED,         // [s-c] send when job manager is disabled
     // @param unixTime
@@ -186,7 +190,7 @@ public enum OP {
     INTERPRETER_SETTINGS,         // [s-c] interpreter settings
     ERROR_INFO,                   // [s-c] error information to be sent
     SESSION_LOGOUT,               // [s-c] error information to be sent
-    WATCHER,                      // [s-c] Change websocket to watcher mode.
+    WATCHER,                      // [c-s] Change websocket to watcher mode.
     PARAGRAPH_ADDED,              // [s-c] paragraph is added
     PARAGRAPH_REMOVED,            // [s-c] paragraph deleted
     PARAGRAPH_MOVED,              // [s-c] paragraph moved

zeppelin-common/src/test/java/org/apache/zeppelin/common/MessageContractTest.java

@@ -0,0 +1,59 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.zeppelin.common;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import org.apache.zeppelin.common.Message.OP;
+import org.junit.jupiter.api.Test;
+
+class MessageContractTest {
+  @Test
+  void operationNamesRoundTripWithoutChangingWireValues() {
+    for (OP operation : OP.values()) {
+      Message message = new Message(operation);
+      JsonObject json = JsonParser.parseString(message.toJson()).getAsJsonObject();
+      assertEquals(operation.name(), json.get("op").getAsString());
+      assertEquals(operation, Message.fromJson(json.toString()).op);
+    }
+  }
+
+  @Test
+  void messageDefaultsRemainBackwardCompatible() {
+    Message message = new Message(OP.GET_NOTE);
+
+    assertTrue(message.data.isEmpty());
+    assertEquals("anonymous", message.ticket);
+    assertEquals("anonymous", message.principal);
+    assertEquals("", message.roles);
+    assertNull(message.msgId);
+
+    JsonObject json = JsonParser.parseString(message.toJson()).getAsJsonObject();
+    assertEquals("GET_NOTE", json.get("op").getAsString());
+    assertTrue(json.getAsJsonObject("data").entrySet().isEmpty());
+    assertEquals("anonymous", json.get("ticket").getAsString());
+    assertEquals("anonymous", json.get("principal").getAsString());
+    assertEquals("", json.get("roles").getAsString());
+    assertFalse(json.has("msgId"));
+  }
+}

zeppelin-web-angular/package.json

@@ -13,6 +13,7 @@
     "build:react": "cd projects/zeppelin-react && npm run build",
     "build:projects": "npm run build-project:sdk && npm run build-project:vis",
     "build-project:sdk": "ng build --project zeppelin-sdk",
+    "check:websocket-contract": "node --test scripts/check-websocket-contract.test.js && node scripts/check-websocket-contract.js",
     "build-project:vis": "ng build --project zeppelin-visualization",
     "lint": "cross-env NODE_OPTIONS='--max-old-space-size=8192' ng lint && npm run lint:react && prettier --check \"**/*.{ts,tsx,js,json,css,html}\"",
     "lint:fix": "cross-env NODE_OPTIONS='--max-old-space-size=8192' ng lint --fix && npm run lint:fix:react && prettier --write \"**/*.{ts,tsx,js,json,css,html}\"",

zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-data-type-map.interface.ts

@@ -169,7 +169,6 @@ export interface MessageSendDataTypeMap {
   [OP.EDITOR_SETTING]: EditorSettingSend;
   [OP.LIST_NOTE_JOBS]: undefined;
   [OP.UNSUBSCRIBE_UPDATE_NOTE_JOBS]: undefined;
-  [OP.LIST_UPDATE_NOTE_JOBS]: undefined;
   [OP.GET_INTERPRETER_BINDINGS]: GetInterpreterBindings;
   [OP.SAVE_INTERPRETER_BINDINGS]: SaveInterpreterBindings;
   [OP.GET_INTERPRETER_SETTINGS]: undefined;

zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-operator.interface.ts

@@ -12,6 +12,9 @@
 
 /**
  * Representation of event type.
+ *
+ * Wire operations must match org.apache.zeppelin.common.Message.OP. Add SDK-local events only here
+ * and mark them with @frontendOnly.
  */
 export enum OP {
   /**
@@ -54,6 +57,7 @@ export enum OP {
    * paragraph status update
    *  @param id paragraph id
    *  @param progress percentage progress
+   * @frontendOnly Emitted locally by the SDK without using the websocket.
    */
   PARAGRAPH_STATUS = 'PARAGRAPH_STATUS',
 
@@ -91,6 +95,19 @@ export enum OP {
    * @param object notebook
    */
   IMPORT_NOTE = 'IMPORT_NOTE',
+
+  /**
+   * [c-s]
+   * convert a note to nbformat
+   */
+  CONVERT_NOTE_NBFORMAT = 'CONVERT_NOTE_NBFORMAT',
+
+  /**
+   * [s-c]
+   * converted nbformat note
+   */
+  CONVERTED_NOTE_NBFORMAT = 'CONVERTED_NOTE_NBFORMAT',
+
   NOTE_UPDATE = 'NOTE_UPDATE',
   NOTE_RENAME = 'NOTE_RENAME',
 
@@ -347,8 +364,8 @@ export enum OP {
   LIST_NOTE_JOBS = 'LIST_NOTE_JOBS',
 
   /**
-   * [c-s]
-   * get job management information for until unixtime
+   * [s-c]
+   * update job management information
    */
   LIST_UPDATE_NOTE_JOBS = 'LIST_UPDATE_NOTE_JOBS',