@synnaxlabs/freighter 0.2.0 → 0.6.0

package/src/lib/transport.ts

@@ -1,14 +0,0 @@
-import { Middleware } from './middleware';
-
-/**
- * Transport is a based interface that represents a general transport for
- * exchanging messages between a client and a server.
- */
-export interface Transport {
-  /**
-   * Use registers middleware that will be executed in order when the transport
-   *
-   * @param mw - The middleware to register.
-   */
-  use(...mw: Middleware[]): void;
-}

package/src/lib/unary.ts

@@ -1,21 +0,0 @@
-import { ZodSchema } from 'zod';
-
-import { Transport } from './transport';
-
-/**
- * An interface for an entity that implements a simple request-response
- * transport between two entities.
- */
-export interface UnaryClient extends Transport {
-  /**
-   * Sends a request to the target server and waits until a response is received.
-   * @param target - The target server to send the request to.
-   * @param req - The request to send.
-   * @param resSchema - The schema to validate the response against.
-   */
-  send<RQ, RS>(
-    target: string,
-    req: RQ,
-    resSchema: ZodSchema<RS>
-  ): Promise<[RS | undefined, Error | undefined]>;
-}

package/src/lib/url.spec.ts

@@ -1,37 +0,0 @@
-import test from 'ava';
-
-import URL from './url';
-
-test('URL - child', (t) => {
-  const endpoint = new URL({
-    host: 'localhost',
-    port: 8080,
-    protocol: 'http',
-    pathPrefix: 'api',
-  });
-  t.is(endpoint.child('test').stringify(), 'http://localhost:8080/api/test');
-});
-
-test('URL - child with trailing slash', (t) => {
-  const endpoint = new URL({
-    host: 'localhost',
-    port: 8080,
-    protocol: 'http',
-    pathPrefix: 'api',
-  });
-  const child = endpoint.child('test/');
-  t.is(child.stringify(), 'http://localhost:8080/api/test');
-});
-
-test('URL - replacing protocol', (t) => {
-  const endpoint = new URL({
-    host: 'localhost',
-    port: 8080,
-    protocol: 'http',
-    pathPrefix: 'api',
-  });
-  t.is(
-    endpoint.child('test').replace({ protocol: 'https' }).stringify(),
-    'https://localhost:8080/api/test'
-  );
-});

package/src/lib/url.ts

@@ -1,79 +0,0 @@
-type URLProps = {
-  host: string;
-  port: number;
-  protocol?: string;
-  pathPrefix?: string;
-  params?: string;
-};
-
-/**
- * URL is a simple class for building and extending URLs.
- */
-export default class URL {
-  protocol: string;
-  host: string;
-  port: number;
-  path: string;
-
-  /**
-   * @param host - The hostname or IP address of the server.
-   * @param port - The port number of the server.
-   * @param protocol - The protocol to use for all requests. Defaults to "".
-   * @param pathPrefix - A path prefix to use for all requests. Defaults to "".
-   */
-  constructor({ host, port, protocol = '', pathPrefix = '' }: URLProps) {
-    this.protocol = protocol;
-    this.host = host;
-    this.port = port;
-    this.path = formatPath(pathPrefix);
-  }
-
-  /**
-   * Replaces creates a new URL with the specified properties replaced.
-   * @param props - The properties to replace.
-   * @returns a new URL.
-   */
-  replace(props: Partial<URLProps>): URL {
-    return new URL({
-      host: props.host || this.host,
-      port: props.port || this.port,
-      protocol: props.protocol || this.protocol,
-      pathPrefix: props.pathPrefix || this.path,
-    });
-  }
-
-  /**
-   * Creates a new url with the given path appended to the current path.
-   * @param path - the path to append to the URL.
-   * @returns a new URL.
-   */
-  child(path: string): URL {
-    return new URL({
-      ...this,
-      pathPrefix: joinPaths(this.path, path),
-    });
-  }
-
-  /** @returns a string representation of the url */
-  stringify(): string {
-    return removeTrailingSlash(
-      `${this.protocol}://${this.host}:${this.port}/${this.path}`
-    );
-  }
-}
-
-// joinPath joins the two paths, ensuring there is a single slash between them.
-const joinPaths = (...paths: string[]): string => {
-  return paths.map(formatPath).join('');
-};
-
-const formatPath = (path: string): string => {
-  if (!path.endsWith('/')) path += '/';
-  if (path.startsWith('/')) path = path.slice(1);
-  return path;
-};
-
-const removeTrailingSlash = (path: string): string => {
-  if (path.endsWith('/')) path = path.slice(0, -1);
-  return path;
-};

package/src/lib/util/log.ts

@@ -1,12 +0,0 @@
-import { Middleware } from '../middleware';
-
-export const logMiddleware = (): Middleware => {
-  return async (md, next) => {
-    console.log(JSON.stringify(md, undefined, 2));
-    const err = await next(md);
-    if (err) {
-      console.log(err);
-    }
-    return err;
-  };
-};

package/src/lib/websocket.spec.ts

@@ -1,106 +0,0 @@
-import test from 'ava';
-import { z } from 'zod';
-
-import { JSONEncoderDecoder } from './encoder';
-import { BaseTypedError, EOF, registerError, TypedError } from './errors';
-import URL from './url';
-import { WebSocketClient } from './websocket';
-
-const url = new URL({
-  host: '127.0.0.1',
-  port: 8080,
-});
-
-const MessageSchema = z.object({
-  id: z.number().optional(),
-  message: z.string().optional(),
-});
-
-const client = new WebSocketClient(new JSONEncoderDecoder(), url);
-
-class MyCustomError extends BaseTypedError {
-  code: number;
-
-  constructor(message: string, code: number) {
-    super(message, 'integration.error');
-    this.code = code;
-  }
-}
-
-const encodeTestError = (err: TypedError): string => {
-  if (!(err instanceof MyCustomError)) {
-    throw new Error('Unexpected error type');
-  }
-  return `${err.code},${err.message}`;
-};
-
-const decodeTestError = (encoded: string): TypedError => {
-  const [code, message] = encoded.split(',');
-  return new MyCustomError(message, parseInt(code, 10));
-};
-
-registerError({
-  type: 'integration.error',
-  encode: encodeTestError,
-  decode: decodeTestError,
-});
-
-test('basic exchange', async (t) => {
-  const stream = await client.stream(
-    'stream/echo',
-    MessageSchema,
-    MessageSchema
-  );
-  for (let i = 0; i < 10; i++) {
-    stream.send({ id: i, message: 'hello' });
-    const [response, error] = await stream.receive();
-    t.is(error, undefined);
-    t.is(response?.id, i + 1);
-    t.is(response?.message, 'hello');
-  }
-  stream.closeSend();
-  const [response, error] = await stream.receive();
-  t.deepEqual(error, new EOF());
-  t.is(response, undefined);
-});
-
-test('receive message after close', async (t) => {
-  const stream = await client.stream(
-    'stream/sendMessageAfterClientClose',
-    MessageSchema,
-    MessageSchema
-  );
-  await stream.closeSend();
-  let [response, error] = await stream.receive();
-  t.is(error, undefined);
-  t.is(response?.id, 0);
-  t.is(response?.message, 'Close Acknowledged');
-  [response, error] = await stream.receive();
-  t.deepEqual(error, new EOF());
-});
-
-test('receive error', async (t) => {
-  const stream = await client.stream(
-    'stream/receiveAndExitWithErr',
-    MessageSchema,
-    MessageSchema
-  );
-  stream.send({ id: 0, message: 'hello' });
-  const [response, error] = await stream.receive();
-  t.deepEqual(error, new MyCustomError('unexpected error', 1));
-  t.is(response, undefined);
-});
-
-test('middleware', async (t) => {
-  const myClient = new WebSocketClient(new JSONEncoderDecoder(), url);
-  let c = 0;
-  myClient.use(async (md, next): Promise<Error | undefined> => {
-    if (md.params) {
-      c++;
-      md.params['Test'] = 'test';
-    }
-    return await next(md);
-  });
-  await myClient.stream('stream/middlewareCheck', MessageSchema, MessageSchema);
-  t.is(c, 1);
-});

package/src/lib/websocket.ts

@@ -1,225 +0,0 @@
-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

@@ -1,24 +0,0 @@
-/**
- * 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.module.json

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