@synnaxlabs/freighter 0.1.0 → 0.2.0

package/src/lib/websocket.ts

@@ -0,0 +1,225 @@
+import { z, ZodSchema } from 'zod';
+
+import { EncoderDecoder } from './encoder';
+import { decodeError, EOF, ErrorPayloadSchema, StreamClosed } from './errors';
+import { buildQueryString } from './http';
+import { CONTENT_TYPE_HEADER_KEY } from './http';
+import { MetaData, MiddlewareCollector } from './middleware';
+import { Runtime, RUNTIME } from './runtime';
+import { Stream, StreamClient } from './stream';
+import URL from './url';
+
+const resolveWebSocketConstructor = (): typeof WebSocket => {
+  if (RUNTIME == Runtime.Node) return require('ws');
+  return WebSocket;
+};
+
+enum MessageType {
+  Data = 'data',
+  Close = 'close',
+}
+
+const MessageSchema = z.object({
+  type: z.nativeEnum(MessageType),
+  payload: z.unknown().optional(),
+  error: z.optional(ErrorPayloadSchema),
+});
+
+type Message = z.infer<typeof MessageSchema>;
+
+enum CloseCode {
+  Normal = 1000,
+  GoingAway = 1001,
+}
+
+/** WebSocketStream is an implementation of Stream that is backed by a websocket. */
+class WebSocketStream<RQ, RS> implements Stream<RQ, RS> {
+  private encoder: EncoderDecoder;
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  private reqSchema: z.ZodSchema<RQ>;
+  private resSchema: z.ZodSchema<RS>;
+
+  private ws: WebSocket;
+  private server_closed?: Error;
+  private send_closed: boolean;
+  private receiveDataQueue: Message[] = [];
+  private receiveCallbacksQueue: {
+    resolve: (msg: Message) => void;
+    reject: (reason: unknown) => void;
+  }[] = [];
+
+  constructor(
+    ws: WebSocket,
+    encoder: EncoderDecoder,
+    reqSchema: z.ZodSchema<RQ>,
+    resSchema: z.ZodSchema<RS>
+  ) {
+    this.encoder = encoder;
+    this.reqSchema = reqSchema;
+    this.resSchema = resSchema;
+    this.ws = ws;
+    this.send_closed = false;
+    this.listenForMessages();
+  }
+
+  /** Implements the Stream protocol */
+  send(req: RQ): Error | undefined {
+    if (this.server_closed) return new EOF();
+    if (this.send_closed) throw new StreamClosed();
+
+    this.ws.send(
+      this.encoder.encode({
+        type: MessageType.Data,
+        payload: req,
+        error: undefined,
+      })
+    );
+
+    return undefined;
+  }
+
+  /** Implements the Stream protocol */
+  async receive(): Promise<[RS | undefined, Error | undefined]> {
+    if (this.server_closed) return [undefined, this.server_closed];
+
+    const msg = await this.receiveMsg();
+
+    if (msg.type == MessageType.Close) {
+      if (!msg.error) throw new Error('Message error must be defined');
+      this.server_closed = decodeError(msg.error);
+      return [undefined, this.server_closed];
+    }
+
+    return [this.resSchema.parse(msg.payload), undefined];
+  }
+
+  /** Implements the Stream protocol */
+  received(): boolean {
+    return this.receiveDataQueue.length !== 0;
+  }
+
+  /** Implements the Stream protocol */
+  closeSend(): void {
+    if (this.send_closed || this.server_closed) {
+      return undefined;
+    }
+    const msg: Message = { type: MessageType.Close };
+    try {
+      this.ws.send(this.encoder.encode(msg));
+    } finally {
+      this.send_closed = true;
+    }
+    return undefined;
+  }
+
+  private async receiveMsg(): Promise<Message> {
+    if (this.receiveDataQueue.length !== 0) {
+      const msg = this.receiveDataQueue.shift();
+      if (msg) return msg;
+      throw new Error('unexpected undefined message');
+    }
+
+    return new Promise((resolve, reject) => {
+      this.receiveCallbacksQueue.push({ resolve, reject });
+    });
+  }
+
+  private listenForMessages(): void {
+    this.ws.onmessage = (ev: MessageEvent) => {
+      const msg = this.encoder.decode(ev.data, MessageSchema);
+
+      if (this.receiveCallbacksQueue.length > 0) {
+        const callback = this.receiveCallbacksQueue.shift();
+        if (callback) callback.resolve(msg);
+        else throw new Error('Unexpected empty callback queue');
+      } else {
+        this.receiveDataQueue.push(msg);
+      }
+    };
+
+    this.ws.onclose = (ev: CloseEvent) => {
+      if ([CloseCode.Normal, CloseCode.GoingAway].includes(ev.code)) {
+        this.server_closed = new EOF();
+      } else {
+        this.server_closed = new StreamClosed();
+      }
+    };
+  }
+}
+
+export const FREIGHTER_METADATA_PREFIX = 'freightermd';
+
+/**
+ * WebSocketClient is an implementation of StreamClient that is backed by
+ * websockets.
+ */
+export class WebSocketClient
+  extends MiddlewareCollector
+  implements StreamClient
+{
+  baseUrl: URL;
+  encoder: EncoderDecoder;
+
+  static readonly MESSAGE_TYPE = 'arraybuffer';
+
+  /**
+   * @param encoder - The encoder to use for encoding messages and decoding
+   *   responses.
+   * @param baseURL - A base url to use as a prefix for all requests.
+   */
+  constructor(encoder: EncoderDecoder, baseURL: URL) {
+    super();
+    this.baseUrl = baseURL.replace({ protocol: 'ws' });
+    this.encoder = encoder;
+  }
+
+  /** Implements the StreamClient interface. */
+  async stream<RQ, RS>(
+    target: string,
+    reqSchema: ZodSchema<RQ>,
+    resSchema: ZodSchema<RS>
+  ): Promise<Stream<RQ, RS>> {
+    const socketConstructor = resolveWebSocketConstructor();
+    let stream: Stream<RQ, RS> | undefined;
+    const error = await this.executeMiddleware(
+      { target, protocol: 'websocket', params: {} },
+      async (md: MetaData): Promise<Error | undefined> => {
+        const ws = new socketConstructor(this.buildURL(target, md));
+        ws.binaryType = WebSocketClient.MESSAGE_TYPE;
+        const streamOrErr = await this.wrapSocket(ws, reqSchema, resSchema);
+        if (streamOrErr instanceof Error) return streamOrErr;
+        stream = streamOrErr;
+        return undefined;
+      }
+    );
+    if (error) throw error;
+    return stream as Stream<RQ, RS>;
+  }
+
+  private buildURL(target: string, md: MetaData): string {
+    const qs = buildQueryString({
+      request: {
+        [CONTENT_TYPE_HEADER_KEY]: this.encoder.contentType,
+        ...md.params,
+      },
+      prefix: FREIGHTER_METADATA_PREFIX,
+    });
+    return this.baseUrl.child(target).stringify() + qs;
+  }
+
+  private async wrapSocket<RQ, RS>(
+    ws: WebSocket,
+    reqSchema: ZodSchema<RQ>,
+    resSchema: ZodSchema<RS>
+  ): Promise<WebSocketStream<RQ, RS> | Error> {
+    return await new Promise((resolve, reject) => {
+      ws.onopen = () => {
+        resolve(
+          new WebSocketStream<RQ, RS>(ws, this.encoder, reqSchema, resSchema)
+        );
+      };
+      ws.onerror = (ev: Event) => reject(new Error(ev.toString()));
+    });
+  }
+}

package/src/types/example.d.ts

@@ -0,0 +1,24 @@
+/**
+ * If you import a dependency which does not include its own type definitions,
+ * TypeScript will try to find a definition for it by following the `typeRoots`
+ * compiler option in tsconfig.json. For this project, we've configured it to
+ * fall back to this folder if nothing is found in node_modules/@types.
+ *
+ * Often, you can install the DefinitelyTyped
+ * (https://github.com/DefinitelyTyped/DefinitelyTyped) type definition for the
+ * dependency in question. However, if no one has yet contributed definitions
+ * for the package, you may want to declare your own. (If you're using the
+ * `noImplicitAny` compiler options, you'll be required to declare it.)
+ *
+ * This is an example type definition which allows import from `module-name`,
+ * e.g.:
+ * ```ts
+ * import something from 'module-name';
+ * something();
+ * ```
+ */
+declare module 'module-name' {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const whatever: any;
+  export = whatever;
+}

package/tsconfig.json

@@ -0,0 +1,47 @@
+{
+  "compilerOptions": {
+    "incremental": true,
+    "target": "es2017",
+    "outDir": "build/main",
+    "rootDir": "src",
+    "moduleResolution": "node",
+    "module": "commonjs",
+    "declaration": true,
+    "inlineSourceMap": true,
+    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+    "resolveJsonModule": true /* Include modules imported with .json extension. */,
+
+    "strict": true /* Enable all strict type-checking options. */,
+
+    /* Strict Type-Checking Options */
+    // "noImplicitAny": true /* Raise error on expressions and declarations with an implied 'any' type. */,
+    // "strictNullChecks": true /* Enable strict null checks. */,
+    // "strictFunctionTypes": true /* Enable strict checking of function types. */,
+    // "strictPropertyInitialization": true /* Enable strict checking of property initialization in classes. */,
+    // "noImplicitThis": true /* Raise error on 'this' expressions with an implied 'any' type. */,
+    // "alwaysStrict": true /* Parse in strict mode and emit "use strict" for each source file. */,
+
+    /* Additional Checks */
+    "noUnusedLocals": true /* Report errors on unused locals. */,
+    "noUnusedParameters": true /* Report errors on unused parameters. */,
+    "noImplicitReturns": true /* Report error when not all code paths in function return a value. */,
+    "noFallthroughCasesInSwitch": true /* Report errors for fallthrough cases in switch statement. */,
+
+    /* Debugging Options */
+    "traceResolution": false /* Report module resolution log messages. */,
+    "listEmittedFiles": false /* Print names of generated files part of the compilation. */,
+    "listFiles": false /* Print names of files part of the compilation. */,
+    "pretty": true /* Stylize errors and messages using color and context. */,
+
+    /* Experimental Options */
+    // "experimentalDecorators": true /* Enables experimental support for ES7 decorators. */,
+    // "emitDecoratorMetadata": true /* Enables experimental support for emitting type metadata for decorators. */,
+
+    "lib": ["es2017", "dom"],
+    "types": ["node"],
+    "typeRoots": ["node_modules/@types", "src/types"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules/**"],
+  "compileOnSave": false
+}

package/tsconfig.module.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig",
+  "compilerOptions": {
+    "target": "esnext",
+    "outDir": "build/module",
+    "module": "esnext"
+  },
+  "exclude": ["node_modules/**"]
+}