@superblocksteam/sdk 1.8.0 → 1.9.0

package/src/socket/socket.ts

@@ -1,9 +1,13 @@
-import WebSocket from "isomorphic-ws";
+import WebSocket from "ws";
 import {
   ISocketClient,
   MethodHandler,
   MethodHandlers,
-  MiddlewareHandler,
+  RequestContextBase,
+  SocketTimeouts,
+  SocketErrorException,
+  GenericMiddleware,
+  NonEmptyArray,
 } from "../types";
 
 interface SocketRequest<Payload = unknown> {
@@ -19,31 +23,61 @@ interface SocketResponse<Payload = unknown> {
   error: SocketError | null;
 }
 
-interface SocketMessage<RequestPayload = unknown, ResponsePayload = unknown> {
+export interface SocketMessage<
+  RequestPayload = unknown,
+  ResponsePayload = unknown
+> {
   request?: SocketRequest<RequestPayload>;
   response?: SocketResponse<ResponsePayload>;
 }
 
-interface SocketError {
+export interface SocketError {
   message: string;
   code: number;
 }
 
-export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
+/**
+ * ISocket is a class that wraps a WebSocket connection and provides a simple interface for sending and receiving messages.
+ * ISocket is initialized by both server and client and request/response is called symmetrically.
+ *
+ * ISocket handles has two timeout actions:
+ * 1. Connection timeout: If the connection is not closed after a certain time, the connection is closed.
+ *  - This is useful to prevent a connection from being open indefinitely. This is mainly used in the server side since
+ *    the client side manages connection lifecycle manually.
+ * 2. No response timeout: If the response is not received after a certain time, the request is timed out.
+ *  - This is mainly used by CLI to handle the case where the server is not responding.
+ *
+ * It is expected that timeouts should be relatively sorted in the order of connection timeout > request timeout > no response timeout.
+ */
+export class ISocket<
+  ImplementedMethods,
+  CallableMethods,
+  RequestContext extends RequestContextBase
+> {
   private readonly ws: WebSocket;
   private readonly requestHandlers: MethodHandlers<
     ImplementedMethods,
     CallableMethods,
     RequestContext
   >;
-  private readonly responseHandler: {
-    [requestId: number]: {
+  private readonly globalMiddlewares: GenericMiddleware<
+    CallableMethods,
+    RequestContext
+  >[];
+  private readonly responseHandler = new Map<
+    number,
+    {
       resolve: (data: unknown) => void;
       reject: (error: SocketError) => void;
-    };
-  } = {};
+      timeout?: NodeJS.Timeout;
+    }
+  >();
   private peerAuthorization?: string;
-  private nxtRequestId: number;
+  protected nxtRequestId: number;
+  private connectionTimeout?: NodeJS.Timeout;
+  // pino library not available in shared
+  private logger: { error: (message?: string) => void };
+  private timeouts?: SocketTimeouts;
 
   constructor(
     ws: WebSocket,
@@ -51,90 +85,129 @@ export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
       ImplementedMethods,
       CallableMethods,
       RequestContext
-    >
+    >,
+    globalMiddlewares: GenericMiddleware<CallableMethods, RequestContext>[],
+    timeouts?: SocketTimeouts,
+    logger?: { error: (message?: string) => void }
   ) {
     this.ws = ws;
     this.requestHandlers = requestHandlers;
+    this.globalMiddlewares = globalMiddlewares;
     this.nxtRequestId = 0;
+    this.logger = logger ?? { error: console.error };
+    this.timeouts = timeouts;
+    // reset connection timeout in each message received. It means connection still active
+    this.resetConnectionTimeout();
 
-    this.ws.addEventListener("message", (event: WebSocket.MessageEvent) => {
-      const eventData: SocketMessage = JSON.parse(event.data.toString());
-      void this.handleEvent(eventData);
-    });
+    this.ws.addEventListener(
+      "message",
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      async (event: WebSocket.MessageEvent) => {
+        const eventData: SocketMessage = JSON.parse(event.data.toString());
+        return this.handleMessage(eventData);
+      }
+    );
   }
 
-  private async handleEvent(eventData: SocketMessage<unknown, unknown>) {
-    if (eventData.request) {
+  protected async handleMessage(message: SocketMessage): Promise<void> {
+    this.resetConnectionTimeout();
+    if (message.request) {
       // Split the method string into parts
-      const parts = eventData.request.method.split(".");
-      let handlers = this.requestHandlers;
+      const parts = message.request.method.split(".");
+      let handlers = this.requestHandlers as Record<string, unknown>;
       for (const part of parts) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        handlers = handlers[part];
+        handlers = handlers[part] as Record<string, unknown>;
         if (!handlers) {
-          return this.respondError(eventData.request.id, {
+          return this.respondError(message.request.id, {
             code: 2,
-            message: `unknown method ${eventData.request.method}`,
+            message: `unknown method ${message.request.method}`,
           });
         }
       }
 
       if (!Array.isArray(handlers)) {
-        return this.respondError(eventData.request.id, {
+        return this.respondError(message.request.id, {
           code: 2,
           message: "unknown method",
         });
       }
-      if (eventData.request.setAuthorization) {
-        this.peerAuthorization = eventData.request.setAuthorization;
-      }
-      const middlewareHandlers = handlers.slice(0, -1) as MiddlewareHandler<
-        unknown,
-        CallableMethods,
-        RequestContext
-      >[];
-      const handler = handlers[handlers.length - 1] as MethodHandler<
-        unknown,
-        unknown,
+      handlers = [...this.globalMiddlewares, ...handlers] as MethodHandlers<
+        ImplementedMethods,
         CallableMethods,
         RequestContext
       >;
-      const reqCtx = {} as RequestContext;
-      let response: unknown;
-      // TODO(george): maybe we should not create a new client for each request
+      if (message.request.setAuthorization) {
+        this.peerAuthorization = message.request.setAuthorization;
+      }
+      const reqCtx = {
+        peerAuthorization: this.peerAuthorization,
+        method: message.request.method,
+        requestId: message.request.id,
+      } as RequestContext;
       const client = createISocketClient(this);
-      try {
-        for (const middlewareHandler of middlewareHandlers) {
-          await middlewareHandler(
-            eventData.request.payload,
-            this.peerAuthorization,
+      const payload = message.request.payload;
+      let alreadyResponded = false;
+      const generateNextFn = (idx: number): (() => Promise<unknown>) => {
+        let wasCalled = false;
+        return async () => {
+          if (alreadyResponded) {
+            throw new SocketErrorException(
+              4,
+              "next() was called after the response was sent"
+            );
+          }
+          const handler = (
+            handlers as unknown as NonEmptyArray<
+              MethodHandler<unknown, unknown, CallableMethods, RequestContext>
+            >
+          )[idx];
+          if (!handler) {
+            throw new SocketErrorException(
+              5,
+              "cannot call past the last handler in the chain"
+            );
+          }
+          if (wasCalled) {
+            throw new SocketErrorException(
+              6,
+              "next() was called multiple times"
+            );
+          }
+          wasCalled = true;
+          return this.callHandler(
+            handler,
+            payload,
+            reqCtx,
             client,
-            reqCtx
+            generateNextFn(idx + 1)
           );
-        }
-        response = await handler(eventData.request.payload, client, reqCtx);
-      } catch (error: any) {
-        return this.respondError(eventData.request.id, {
-          code: 3,
-          message: error.toString(),
-        });
+        };
+      };
+      let response: unknown;
+      try {
+        // call the first handler in the chain
+        response = await generateNextFn(0)();
+      } catch (error) {
+        const socketError =
+          error instanceof SocketErrorException
+            ? { code: error.code, message: error.message }
+            : { code: 3, message: (error as Error).toString() };
+        return this.respondError(message.request.id, socketError);
       }
-      this.respond(eventData.request.id, response);
-    } else if (eventData.response && eventData.response.id) {
-      if (!this.responseHandler[eventData.response.id]) {
+      this.respond(message.request.id, response);
+      alreadyResponded = true;
+    } else if (message.response && message.response.id) {
+      const responseHandler = this.responseHandler.get(message.response.id);
+      if (!responseHandler) {
         return;
       }
-      if (eventData.response.error) {
-        this.responseHandler[eventData.response.id].reject(
-          eventData.response.error
-        );
+      if (message.response.error) {
+        responseHandler.reject(message.response.error);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      this.responseHandler[eventData.response.id].resolve(
-        eventData.response.payload as any
-      );
-      delete this.responseHandler[eventData.response.id];
+      responseHandler.resolve(message.response.payload as any);
+      clearTimeout(responseHandler.timeout);
+      this.responseHandler.delete(message.response.id);
     } else {
       return this.respondError(-1, {
         code: 3,
@@ -143,6 +216,21 @@ export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
     }
   }
 
+  protected async callHandler<
+    Params,
+    Result,
+    CallableMethods,
+    RequestContext extends RequestContextBase
+  >(
+    handler: MethodHandler<Params, Result, CallableMethods, RequestContext>,
+    params: Params,
+    ctx: RequestContext,
+    client: ISocketClient<CallableMethods>,
+    next: () => Promise<Result>
+  ): Promise<Result> {
+    return handler(params, ctx, client, next);
+  }
+
   public request<Params, Result>(
     method: string,
     params: Params,
@@ -150,10 +238,10 @@ export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
   ): Promise<Result> {
     return new Promise<Result>((resolve, reject) => {
       const requestId = ++this.nxtRequestId;
-      this.responseHandler[requestId] = {
+      this.responseHandler.set(requestId, {
         resolve: (result) => resolve(result as Result),
         reject: (error: SocketError) => reject(error),
-      };
+      });
       const toSend: SocketMessage = {
         request: {
           method,
@@ -163,10 +251,11 @@ export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
         },
       };
       this.ws.send(JSON.stringify(toSend));
+      this.resetNoResponseTimeout(requestId);
     });
   }
 
-  private respond<Result>(requestId: number, result: Result): void {
+  protected respond<Result>(requestId: number, result: Result): void {
     const toSend: SocketMessage = {
       response: {
         payload: result,
@@ -177,7 +266,7 @@ export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
     return this.ws.send(JSON.stringify(toSend));
   }
 
-  private respondError(requestId: number, error: SocketError): void {
+  protected respondError(requestId: number, error: SocketError): void {
     const toSend: SocketMessage = {
       response: {
         payload: null,
@@ -188,7 +277,66 @@ export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
     return this.ws.send(JSON.stringify(toSend));
   }
 
+  private resetConnectionTimeout(): void {
+    if (!this.timeouts?.connectionTimeoutInSeconds) {
+      return;
+    }
+    if (this.connectionTimeout) {
+      clearTimeout(this.connectionTimeout);
+    }
+    // Set a new timeout for the next message
+    this.connectionTimeout = setTimeout(
+      this.handleConnectionTimeout(),
+      this.timeouts?.connectionTimeoutInSeconds * 1000
+    );
+  }
+
+  private handleConnectionTimeout() {
+    return () => {
+      this.logger.error(
+        `Connection timed out after ${this.timeouts?.connectionTimeoutInSeconds} seconds`
+      );
+      this.close();
+    };
+  }
+
+  private resetNoResponseTimeout(requestId: number): void {
+    if (!this.timeouts?.noResponseTimeoutInSeconds) {
+      return;
+    }
+    const responseHandler = this.responseHandler.get(requestId);
+    if (!responseHandler) {
+      return;
+    }
+    const noResponseTimeout = responseHandler.timeout;
+    const reject = responseHandler.reject;
+    if (responseHandler.timeout) {
+      clearTimeout(noResponseTimeout);
+    }
+    // Set a new timeout for the next message
+    responseHandler.timeout = setTimeout(
+      this.handleNoResponseTimeout(reject),
+      this.timeouts?.noResponseTimeoutInSeconds * 1000
+    );
+  }
+
+  private handleNoResponseTimeout(reject: (error: SocketError) => void) {
+    return () => {
+      const message = `Request timed out after ${this.timeouts?.noResponseTimeoutInSeconds} seconds`;
+      this.logger.error(message);
+      reject({ code: 7, message });
+    };
+  }
+
   public close(): void {
+    clearTimeout(this.connectionTimeout);
+    this.responseHandler.forEach((handler, key) => {
+      clearTimeout(handler.timeout);
+      this.logger.error(
+        `Rejecting pending requestId ${key} due to connection close`
+      );
+      handler.reject({ code: 8, message: "Connection closed" });
+    });
     this.ws.close();
   }
 }
@@ -200,7 +348,7 @@ const proxyTarget = Object.freeze(() => {
 function createIsocketProxy<
   ImplementedMethods,
   CallableMethods,
-  RequestContext
+  RequestContext extends RequestContextBase
 >(
   socket: ISocket<ImplementedMethods, CallableMethods, RequestContext>,
   // if path is undefined, it means the current object is the root object
@@ -238,13 +386,13 @@ function createIsocketProxy<
 export function createISocketClient<
   CallableMethods,
   ImplementedMethods,
-  RequestContext
+  RequestContext extends RequestContextBase
 >(
   socket: ISocket<ImplementedMethods, CallableMethods, RequestContext>
 ): ISocketClient<CallableMethods> {
   return {
     close: () => socket.close(),
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any,@typescript-eslint/no-unsafe-assignment
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     call: createIsocketProxy(socket, undefined) as any,
   };
 }

package/src/types/common.ts

@@ -7,7 +7,6 @@ export interface UserMeDto {
 
 export interface FlagBootstrap {
   "ui.enable-resource-signing"?: boolean;
-  "server.multipage.enabled"?: boolean;
 }
 
 export type User = {
@@ -152,3 +151,9 @@ export interface RemoteCommitDto {
   branchName: string;
   repositoryId: string;
 }
+
+export type ViewMode =
+  | "export-deployed"
+  | "export-latest"
+  | "export-live"
+  | "export-commit";

package/src/types/socket.ts

@@ -1,28 +1,32 @@
+export interface RequestContextBase {
+  peerAuthorization?: string;
+  method: string;
+  requestId: number;
+}
+
 export type MethodHandler<Params, Result, PeerMethods, RequestContext> = (
   params: Params,
+  ctx: RequestContext,
   peer: ISocketClient<PeerMethods>,
-  ctx: RequestContext
+  next: () => Promise<Result>
 ) => Promise<Result>;
 
-export type MiddlewareHandler<Params, PeerMethods, RequestContext> = (
-  params: Params,
-  peerAuthorization: string | undefined,
-  peer: ISocketClient<PeerMethods>,
-  ctx: RequestContext
-) => Promise<void>;
+// A  generic middleware is a method handler that can be chained with any other method handler, so it uses `any` for the params and result types
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GenericMiddleware<PeerMethods, RequestContext> = MethodHandler<
+  any,
+  any,
+  PeerMethods,
+  RequestContext
+>;
+
+export type NonEmptyArray<T> = [...T[], T];
 
 export type MethodHandlers<Methods, PeerMethods, RequestContext> = {
   [Key in keyof Methods]: Methods[Key] extends (
     params: infer Params
   ) => Promise<infer Result>
-    ? [
-        ...middlewareHandlers: MiddlewareHandler<
-          Params,
-          PeerMethods,
-          RequestContext
-        >[],
-        handler: MethodHandler<Params, Result, PeerMethods, RequestContext>
-      ]
+    ? NonEmptyArray<MethodHandler<Params, Result, PeerMethods, RequestContext>>
     : Methods[Key] extends Record<string, unknown>
     ? MethodHandlers<Methods[Key], PeerMethods, RequestContext>
     : never;
@@ -46,3 +50,20 @@ export type ISocketClient<Methods> = {
 export type MethodSchema<Params, Response> = (
   params: Params
 ) => Promise<Response>;
+
+/** The exception type can be thrown to cause the default error handler to write a raw error response to the socket */
+export class SocketErrorException extends Error {
+  readonly code: number;
+  readonly message: string;
+
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+    this.message = message;
+  }
+}
+
+export type SocketTimeouts = {
+  noResponseTimeoutInSeconds?: number;
+  connectionTimeoutInSeconds?: number;
+};