feat(vscode): implement daemon protocol (#915)

Author: alestiago

extensions/vscode/src/daemon/index.ts

@@ -1 +1,2 @@
+export * from "./protocol";
 export * from "./dart-frog-daemon";

extensions/vscode/src/daemon/protocol.ts

@@ -0,0 +1,59 @@
+/**
+ * Defines the protocol used by the Dart Frog daemon and custom
+ * type guards to check if an object is a valid message.
+ *
+ * @see {@link https://github.com/VeryGoodOpenSource/dart_frog/blob/main/packages/dart_frog_cli/lib/src/daemon/protocol.dart Dart Frog dart's protocol}
+ */
+
+export class DaemonMessage {
+  /**
+   * Decodes messages that follow the protocol.
+   *
+   * @param data The data to decode (usually from stdout of the Dart Frog
+   * daemon and in JSON format).
+   * @returns The decoded messages.
+   */
+  public static decode(data: Buffer): DaemonMessage[] {
+    const stringData = data.toString();
+    const messages = stringData.split("\n").filter((s) => s.trim().length > 0);
+    const parsedMessages = messages.map((message) => JSON.parse(message));
+
+    let daemonMessages: DaemonMessage[] = [];
+    for (const parsedMessage of parsedMessages) {
+      for (const message of parsedMessage) {
+        daemonMessages.push(message as DaemonMessage);
+      }
+    }
+
+    return daemonMessages;
+  }
+}
+
+export abstract class DaemonRequest implements DaemonMessage {
+  abstract method: string;
+  abstract id: string;
+  abstract params: any;
+}
+
+export function isDaemonRequest(object: any): object is DaemonRequest {
+  return typeof object.id === "string" && typeof object.method === "string";
+}
+
+export interface DaemonResponse extends DaemonMessage {
+  id: string;
+  result: any;
+  error: any;
+}
+
+export function isDaemonResponse(object: any): object is DaemonResponse {
+  return typeof object.id === "string" && !("method" in object);
+}
+
+export interface DaemonEvent extends DaemonMessage {
+  event: string;
+  params: any;
+}
+
+export function isDaemonEvent(object: any): object is DaemonEvent {
+  return typeof object.event === "string";
+}

extensions/vscode/src/test/suite/daemon/protocol.test.ts

@@ -0,0 +1,304 @@
+import * as assert from "assert";
+import {
+  DaemonMessage,
+  isDaemonEvent,
+  isDaemonRequest,
+  isDaemonResponse,
+} from "../../../daemon";
+
+suite("DaemonMessage", () => {
+  suite("decode", () => {
+    test("returns an empty array when data is empty", () => {
+      const data = Buffer.from("");
+
+      assert.deepEqual(DaemonMessage.decode(data), []);
+    });
+
+    test("decodes request", () => {
+      const request = `[{"method": "daemon.requestVersion", "id": "12"}]`;
+      const data = Buffer.from(request);
+
+      const requestObject = {
+        method: "daemon.requestVersion",
+        id: "12",
+      };
+      assert.deepEqual(DaemonMessage.decode(data), [requestObject]);
+    });
+
+    test("decodes event", () => {
+      const event = `[{"event":"daemon.ready","params":{"version":"0.0.1","processId":75941}}]`;
+      const data = Buffer.from(event);
+
+      const eventObject = {
+        event: "daemon.ready",
+        params: {
+          version: "0.0.1",
+          processId: 75941,
+        },
+      };
+      assert.deepEqual(DaemonMessage.decode(data), [eventObject]);
+    });
+
+    test("decodes response", () => {
+      const response = `[{"id":"12","result":{"version":"0.0.1"}}]`;
+      const data = Buffer.from(response);
+
+      const responseObject = {
+        id: "12",
+        result: {
+          version: "0.0.1",
+        },
+      };
+      assert.deepEqual(DaemonMessage.decode(data), [responseObject]);
+    });
+
+    test("decodes multiple batched messages", () => {
+      const request = `{"method": "daemon.requestVersion", "id": "12"}`;
+      const event = `{"event":"daemon.ready","params":{"version":"0.0.1","processId":75941}}`;
+      const response = `{"id":"12","result":{"version":"0.0.1"}}`;
+      const data = Buffer.from(`[${request},${event},${response}]`);
+
+      const requestObject = {
+        method: "daemon.requestVersion",
+        id: "12",
+      };
+      const eventObject = {
+        event: "daemon.ready",
+        params: {
+          version: "0.0.1",
+          processId: 75941,
+        },
+      };
+      const responseObject = {
+        id: "12",
+        result: {
+          version: "0.0.1",
+        },
+      };
+      assert.deepEqual(DaemonMessage.decode(data), [
+        requestObject,
+        eventObject,
+        responseObject,
+      ]);
+    });
+
+    test("decodes multiple buffered messages", () => {
+      const request = `[{"method": "daemon.requestVersion", "id": "12"}]`;
+      const event = `[{"event":"daemon.ready","params":{"version":"0.0.1","processId":75941}}]`;
+      const response = `[{"id":"12","result":{"version":"0.0.1"}}]`;
+      const data = Buffer.from(`${request}\n${event}\n${response}`);
+
+      const requestObject = {
+        method: "daemon.requestVersion",
+        id: "12",
+      };
+      const eventObject = {
+        event: "daemon.ready",
+        params: {
+          version: "0.0.1",
+          processId: 75941,
+        },
+      };
+      const responseObject = {
+        id: "12",
+        result: {
+          version: "0.0.1",
+        },
+      };
+      assert.deepEqual(DaemonMessage.decode(data), [
+        requestObject,
+        eventObject,
+        responseObject,
+      ]);
+    });
+  });
+});
+
+suite("isDaemonRequest", () => {
+  suite("returns true when object is a valid DaemonRequest", () => {
+    test("with all fields", () => {
+      const request = {
+        id: "1",
+        method: "method",
+        params: {},
+      };
+
+      assert.equal(isDaemonRequest(request), true);
+    });
+
+    test("when missing params only", () => {
+      const request = {
+        id: "1",
+        method: "method",
+      };
+
+      assert.equal(isDaemonRequest(request), true);
+    });
+  });
+
+  suite("returns false", () => {
+    test("when missing id only", () => {
+      const request = {
+        method: "method",
+        params: {},
+      };
+
+      assert.equal(isDaemonRequest(request), false);
+    });
+
+    test("when missing method only", () => {
+      const request = {
+        id: "1",
+        params: {},
+      };
+
+      assert.equal(isDaemonRequest(request), false);
+    });
+
+    test("when object is a valid DaemonResponse", () => {
+      const response = {
+        id: "1",
+        result: {},
+        error: {},
+      };
+
+      assert.equal(isDaemonResponse(response), true);
+      assert.equal(isDaemonRequest(response), false);
+    });
+
+    test("when object is a valid DaemonEvent", () => {
+      const event = {
+        event: "event",
+        params: {},
+      };
+
+      assert.equal(isDaemonEvent(event), true);
+      assert.equal(isDaemonRequest(event), false);
+    });
+  });
+});
+
+suite("isDaemonResponse", () => {
+  suite("returns true when object is a valid DaemonResponse", () => {
+    test("with all fields", () => {
+      const response = {
+        id: "1",
+        result: {},
+        error: {},
+      };
+
+      assert.equal(isDaemonResponse(response), true);
+    });
+
+    test("when missing error only", () => {
+      const response = {
+        id: "1",
+        result: {},
+      };
+
+      assert.equal(isDaemonResponse(response), true);
+    });
+
+    test("when missing result only", () => {
+      const response = {
+        id: "1",
+        error: {},
+      };
+
+      assert.equal(isDaemonResponse(response), true);
+    });
+
+    test("when missing result and errror only", () => {
+      const response = {
+        id: "1",
+      };
+
+      assert.equal(isDaemonResponse(response), true);
+    });
+  });
+
+  suite("returns false", () => {
+    test("when missing id only", () => {
+      const response = {
+        result: {},
+        error: {},
+      };
+
+      assert.equal(isDaemonResponse(response), false);
+    });
+
+    test("when object is a valid DaemonRequest", () => {
+      const request = {
+        id: "1",
+        method: "method",
+        params: {},
+      };
+
+      assert.equal(isDaemonRequest(request), true);
+      assert.equal(isDaemonResponse(request), false);
+    });
+
+    test("when object is a valid DaemonEvent", () => {
+      const event = {
+        event: "event",
+        params: {},
+      };
+
+      assert.equal(isDaemonEvent(event), true);
+      assert.equal(isDaemonResponse(event), false);
+    });
+  });
+});
+
+suite("isDaemonEvent", () => {
+  suite("returns true when object is a valid DaemonEvent", () => {
+    test("with all fields", () => {
+      const event = {
+        event: "event",
+        params: {},
+      };
+
+      assert.equal(isDaemonEvent(event), true);
+    });
+
+    test("when missing params only", () => {
+      const event = {
+        event: "event",
+      };
+
+      assert.equal(isDaemonEvent(event), true);
+    });
+  });
+
+  suite("returns false", () => {
+    test("when missing event only", () => {
+      const event = {
+        params: {},
+      };
+
+      assert.equal(isDaemonEvent(event), false);
+    });
+
+    test("when object is a valid DaemonRequest", () => {
+      const request = {
+        id: "1",
+        method: "method",
+        params: {},
+      };
+
+      assert.equal(isDaemonRequest(request), true);
+      assert.equal(isDaemonEvent(request), false);
+    });
+
+    test("when object is a valid DaemonResponse", () => {
+      const response = {
+        id: "1",
+        result: {},
+        error: {},
+      };
+
+      assert.equal(isDaemonResponse(response), true);
+      assert.equal(isDaemonEvent(response), false);
+    });
+  });
+});