@synnaxlabs/freighter 0.2.0 → 0.4.1

package/src/errors.ts

@@ -0,0 +1,205 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { URL } from "@synnaxlabs/x";
+import { z } from "zod";
+
+export interface TypedError extends Error {
+  discriminator: "FreighterError";
+  /**
+   * @description Returns a unique type identifier for the error. Freighter uses this to
+   * determine the correct decoder to use on the other end of the freighter.
+   */
+  type: string;
+}
+
+export class BaseTypedError extends Error implements TypedError {
+  discriminator: "FreighterError" = "FreighterError";
+  type: string;
+
+  constructor(message: string, type: string) {
+    super(message);
+    this.type = type;
+  }
+}
+
+type ErrorDecoder = (encoded: ErrorPayload) => Error | null;
+type ErrorEncoder = (error: TypedError) => ErrorPayload | null;
+
+export const isTypedError = (error: unknown): error is TypedError => {
+  if (error == null || typeof error !== "object") return false;
+  const typedError = error as TypedError;
+  if (typedError.discriminator !== "FreighterError") return false;
+  if (!("type" in typedError))
+    throw new Error(
+      `Freighter error is missing its type property: ${JSON.stringify(typedError)}`,
+    );
+  return true;
+};
+
+export const assertErrorType = <T>(type: string, error?: Error | null): T => {
+  if (error == null)
+    throw new Error(`Expected error of type ${type} but got nothing instead`);
+  if (!isTypedError(error))
+    throw new Error(`Expected a typed error, got: ${error.message}`);
+  if (error.type !== type)
+    throw new Error(
+      `Expected error of type ${type}, got ${error.type}: ${error.message}`,
+    );
+  return error as unknown as T;
+};
+
+export const UNKNOWN = "unknown";
+export const NONE = "nil";
+export const FREIGHTER = "freighter";
+
+export const errorZ = z.object({ type: z.string(), data: z.string() });
+
+export type ErrorPayload = z.infer<typeof errorZ>;
+
+interface errorProvider {
+  encode: ErrorEncoder;
+  decode: ErrorDecoder;
+}
+
+class Registry {
+  private readonly providers: errorProvider[] = [];
+
+  register(provider: errorProvider): void {
+    this.providers.push(provider);
+  }
+
+  encode(error: unknown): ErrorPayload {
+    if (error == null) return { type: NONE, data: "" };
+    if (isTypedError(error)) {
+      for (const provider of this.providers) {
+        const payload = provider.encode(error);
+        if (payload != null) return payload;
+      }
+    }
+    return { type: UNKNOWN, data: JSON.stringify(error) };
+  }
+
+  decode(payload?: ErrorPayload | null): Error | null {
+    if (payload == null || payload.type === NONE) return null;
+    if (payload.type === UNKNOWN) return new UnknownError(payload.data);
+    for (const provider of this.providers) {
+      const error = provider.decode(payload);
+      if (error != null) return error;
+    }
+    return new UnknownError(payload.data);
+  }
+}
+
+const REGISTRY = new Registry();
+
+/**
+ * Registers a custom error type with the error registry, which allows it to be
+ * encoded/decoded and sent over the network.
+ *
+ * @param type - A unique string identifier for the error type.
+ * @param encode - A function that encodes the error into a string.
+ * @param decode - A function that decodes the error from a string.
+ */
+export const registerError = ({
+  encode,
+  decode,
+}: {
+  encode: ErrorEncoder;
+  decode: ErrorDecoder;
+}): void => REGISTRY.register({ encode, decode });
+
+/**
+ * Encodes an error into a payload that can be sent between a freighter server
+ * and client.
+ * @param error - The error to encode.
+ * @returns The encoded error.
+ */
+export const encodeError = (error: unknown): ErrorPayload => {
+  return REGISTRY.encode(error);
+};
+
+/**
+ * Decodes an error payload into an exception. If a custom decoder can be found
+ * for the error type, it will be used. Otherwise, a generic Error containing
+ * the error data is returned.
+ *
+ * @param payload - The encoded error payload.
+ * @returns The decoded error.
+ */
+export const decodeError = (payload: ErrorPayload): Error | null => {
+  return REGISTRY.decode(payload);
+};
+
+export class UnknownError extends BaseTypedError implements TypedError {
+  constructor(message: string) {
+    super(message, UNKNOWN);
+  }
+}
+
+/** Thrown/returned when a stream closed normally. */
+export class EOF extends BaseTypedError implements TypedError {
+  constructor() {
+    super("EOF", FREIGHTER);
+  }
+}
+
+/** Thrown/returned when a stream is closed abnormally. */
+export class StreamClosed extends BaseTypedError implements TypedError {
+  constructor() {
+    super("StreamClosed", FREIGHTER);
+  }
+}
+
+export interface UnreachableArgs {
+  message?: string;
+  url?: URL;
+}
+
+/** Thrown when a target is unreachable. */
+export class Unreachable extends BaseTypedError implements TypedError {
+  url: URL;
+
+  constructor(args: UnreachableArgs = {}) {
+    const { message = "Unreachable", url = URL.UNKNOWN } = args;
+    super(message, FREIGHTER);
+    this.url = url;
+  }
+}
+
+const FREIGHTER_ERROR_TYPE = "freighter";
+
+const freighterErrorEncoder: ErrorEncoder = (error: TypedError) => {
+  if (error.type !== FREIGHTER) return null;
+  if (error instanceof EOF) return { type: FREIGHTER_ERROR_TYPE, data: "EOF" };
+  if (error instanceof StreamClosed)
+    return { type: FREIGHTER_ERROR_TYPE, data: "StreamClosed" };
+  if (error instanceof Unreachable)
+    return { type: FREIGHTER_ERROR_TYPE, data: "Unreachable" };
+  throw new Error(`Unknown error type: ${error.type}: ${error.message}`);
+};
+
+const freighterErrorDecoder: ErrorDecoder = (encoded: ErrorPayload) => {
+  if (encoded.type !== FREIGHTER_ERROR_TYPE) return null;
+  switch (encoded.data) {
+    case "EOF":
+      return new EOF();
+    case "StreamClosed":
+      return new StreamClosed();
+    case "Unreachable":
+      return new Unreachable();
+    default:
+      throw new Error(`Unknown error type: ${encoded.data}`);
+  }
+};
+
+registerError({
+  encode: freighterErrorEncoder,
+  decode: freighterErrorDecoder,
+});

package/src/http.spec.ts

@@ -0,0 +1,67 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { URL, binary } from "@synnaxlabs/x";
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+
+import { HTTPClient } from "@/http";
+
+const ENDPOINT = new URL({
+  host: "127.0.0.1",
+  protocol: "http",
+  port: 8080,
+  pathPrefix: "unary",
+});
+
+const client = new HTTPClient(ENDPOINT, new binary.JSONEncoderDecoder());
+
+const messageZ = z.object({
+  id: z.number().optional(),
+  message: z.string().optional(),
+});
+
+describe("http", () => {
+  test("echo", async () => {
+    const [response, error] = await client.send<typeof messageZ>(
+      "/echo",
+      {
+        id: 1,
+        message: "hello",
+      },
+      messageZ,
+    );
+    expect(error).toBeNull();
+    expect(response).toEqual({ id: 2, message: "hello" });
+  });
+
+  test("not found", async () => {
+    const [response, error] = await client.send<typeof messageZ>(
+      "/not-found",
+      {},
+      messageZ,
+    );
+    expect(error?.message).toEqual("Not Found");
+    expect(response).toBeNull();
+  });
+
+  test("middleware", async () => {
+    client.use(async (md, next) => {
+      md.params.Test = "test";
+      return await next(md);
+    });
+    const [response, error] = await client.send<typeof messageZ>(
+      "/middlewareCheck",
+      {},
+      messageZ,
+    );
+    expect(error).toBeNull();
+    expect(response?.message).toEqual("");
+  });
+});

package/src/http.ts

@@ -0,0 +1,115 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { runtime, type URL, type binary } from "@synnaxlabs/x";
+import { type z } from "zod";
+
+import { errorZ, decodeError, Unreachable } from "@/errors";
+import { type Context, MiddlewareCollector } from "@/middleware";
+import { type UnaryClient } from "@/unary";
+
+export const CONTENT_TYPE_HEADER_KEY = "Content-Type";
+
+const resolveFetchAPI = (protocol: "http" | "https"): typeof fetch => {
+  if (runtime.RUNTIME !== "node") return fetch;
+  const _fetch: typeof fetch = require("node-fetch");
+  if (protocol === "http") return _fetch;
+  const https = require("https");
+  const agent = new https.Agent({ rejectUnauthorized: false });
+  // @ts-expect-error - TS doesn't know about qhis option
+  return async (info, init) => await _fetch(info, { ...init, agent });
+};
+
+/**
+ * HTTPClientFactory provides a POST and GET implementation of the Unary
+ * protocol.
+ *
+ * @param url - The base URL of the API.
+ * @param encoder - The encoder/decoder to use for the request/response.
+ */
+export class HTTPClient extends MiddlewareCollector implements UnaryClient {
+  endpoint: URL;
+  encoder: binary.EncoderDecoder;
+  fetch: typeof fetch;
+
+  constructor(endpoint: URL, encoder: binary.EncoderDecoder, secure: boolean = false) {
+    super();
+    this.endpoint = endpoint.replace({ protocol: secure ? "https" : "http" });
+    this.encoder = encoder;
+    this.fetch = resolveFetchAPI(this.endpoint.protocol as "http" | "https");
+
+    return new Proxy(this, {
+      get: (target, prop, receiver) => {
+        if (prop === "endpoint") return this.endpoint;
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+  }
+
+  get headers(): Record<string, string> {
+    return {
+      [CONTENT_TYPE_HEADER_KEY]: this.encoder.contentType,
+    };
+  }
+
+  async send<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(
+    target: string,
+    req: z.input<RQ> | null,
+    resSchema: RS | null,
+  ): Promise<[z.output<RS> | null, Error | null]> {
+    let rs: RS | null = null;
+    const url = this.endpoint.child(target);
+    const request: RequestInit = {};
+    request.method = "POST";
+    request.body = this.encoder.encode(req ?? {});
+
+    const [, err] = await this.executeMiddleware(
+      { target: url.toString(), protocol: this.endpoint.protocol, params: {}, role: "client" },
+      async (ctx: Context): Promise<[Context, Error | null]> => {
+        const outCtx: Context = { ...ctx, params: {} };
+        request.headers = {
+          ...this.headers,
+          ...ctx.params,
+        };
+        let httpRes: Response;
+        try {
+          const f = resolveFetchAPI(ctx.protocol as "http" | "https");
+          httpRes = await f(ctx.target, request);
+        } catch (err_) {
+          let err = err_ as Error;
+          if (err.message === "Load failed") err = new Unreachable({ url });
+          return [outCtx, err];
+        }
+        const data = await httpRes.arrayBuffer();
+        if (httpRes?.ok) {
+          if (resSchema != null) rs = this.encoder.decode(data, resSchema);
+          return [outCtx, null];
+        }
+        try {
+          if (httpRes.status !== 400) return [outCtx, new Error(httpRes.statusText)];
+          const err = this.encoder.decode(data, errorZ);
+          const decoded = decodeError(err);
+          return [outCtx, decoded];
+        } catch (e) {
+          return [
+            outCtx,
+            new Error(
+              `[freighter] - failed to decode error: ${httpRes.statusText}: ${
+                (e as Error).message
+              }`,
+            ),
+          ];
+        }
+      },
+    );
+
+    return [rs, err];
+  }
+}

package/src/index.ts

@@ -1,25 +1,26 @@
-export { WebSocketClient } from './lib/websocket';
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
 export {
-  MsgpackEncoderDecoder,
-  JSONEncoderDecoder,
-  registerCustomTypeEncoder,
-  ENCODERS,
-} from './lib/encoder';
-export { StreamClient, Stream } from './lib/stream';
-export { UnaryClient } from './lib/unary';
-export { HTTPClientFactory } from './lib/http';
-export { default as URL } from './lib/url';
-export {
-  encodeError,
-  decodeError,
-  registerError,
   BaseTypedError,
-  TypedError,
-  ErrorPayload,
-  ErrorPayloadSchema,
+  decodeError,
+  encodeError,
   EOF,
+  errorZ,
+  registerError,
   StreamClosed,
   Unreachable,
-} from './lib/errors';
-export { Middleware, Next, MetaData } from './lib/middleware';
-export { logMiddleware } from './lib/util/log';
+} from "@/errors";
+export type { ErrorPayload as ErrorPayload, TypedError } from "@/errors";
+export { HTTPClient } from "@/http";
+export type { Context as MetaData, Middleware, Next } from "@/middleware";
+export type { Stream, StreamClient } from "@/stream";
+export type { UnaryClient } from "@/unary";
+export { sendRequired } from "@/unary";
+export { WebSocketClient } from "@/websocket";

package/src/{lib/middleware.ts → middleware.ts}

@@ -1,34 +1,44 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
 /**
- * MetaData is the metadata associated with a freighter transport request.
+ * Context is the metadata associated with a freighter transport request.
  *
  * @property target - The target the request is being issued to.
  * @property protocol - The protocol used to issue the request.
  * @property params - Arbitrary string parameters that can be set by client side
  *   middleware and read by server side middleware.
  */
-export type MetaData = {
+export interface Context {
   target: string;
+  role: Role;
   protocol: string;
   params: Record<string, string>;
-};
+}
+
+export const ROLES = ["client", "server"] as const;
+export type Role = (typeof ROLES)[number];
 
 /** Next executes the next middleware in the chain. */
-export type Next = (md: MetaData) => Promise<Error | undefined>;
+export type Next = (ctx: Context) => Promise<[Context, Error | null]>;
 
 /**
  * Middleware represents a general middleware function that can be used to
  * parse/attach metadata to a request or alter its behavior.
  */
-export type Middleware = (
-  md: MetaData,
-  next: Next
-) => Promise<Error | undefined>;
+export type Middleware = (ctx: Context, next: Next) => Promise<[Context, Error | null]>;
 
 /**
  * Finalizer is a middleware that is executed as the last step in the chain.
  * Finalizer middleware should be used to execute the request.
  */
-type Finalizer = (md: MetaData) => Promise<Error | undefined>;
+type Finalizer = (ctx: Context) => Promise<[Context, Error | null]>;
 
 /**
  * MiddlewareCollector is a class that can be used to collect and execute
@@ -38,7 +48,7 @@ export class MiddlewareCollector {
   middleware: Middleware[] = [];
 
   /** Implements the Transport interface */
-  use(...mw: Middleware[]) {
+  use(...mw: Middleware[]): void {
     this.middleware.push(...mw);
   }
 
@@ -47,21 +57,21 @@ export class MiddlewareCollector {
    * until the end of the chain is reached. It then calls the finalizer with the
    * metadata.
    *
-   * @param md - The metadata to pass to the middleware.
+   * @param ctx - The context to pass to the middleware.
    * @param finalizer - The finalizer to call with the metadata.
    * @returns An error if one was encountered, otherwise undefined.
    */
-  executeMiddleware(
-    md: MetaData,
-    finalizer: Finalizer
-  ): Promise<Error | undefined> {
+  async executeMiddleware(
+    ctx: Context,
+    finalizer: Finalizer,
+  ): Promise<[Context, Error | null]> {
     let i = 0;
-    const next = (md: MetaData): Promise<Error | undefined> => {
-      if (i == this.middleware.length) return finalizer(md);
+    const next = async (md: Context): Promise<[Context, Error | null]> => {
+      if (i === this.middleware.length) return await finalizer(md);
       const _mw = this.middleware[i];
       i++;
-      return _mw(md, next);
+      return await _mw(md, next);
     };
-    return next(md);
+    return await next(ctx);
   }
 }

package/src/{lib/stream.ts → stream.ts}

@@ -1,11 +1,20 @@
-import { ZodSchema } from 'zod';
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
 
-import { Transport } from './transport';
+import { type z } from "zod";
+
+import { type Transport } from "@/transport";
 
 /**
  * Interface for an entity that receives a stream of responses.
  */
-export interface StreamReceiver<RS> {
+export interface StreamReceiver<RS extends z.ZodTypeAny> {
   /**
    * Receives a response from the stream. It's not safe to call receive
    * concurrently.
@@ -15,18 +24,18 @@ export interface StreamReceiver<RS> {
    *  returns the error the server returned.
    *  @raises Error: if the transport fails.
    */
-  receive(): Promise<[RS | undefined, Error | undefined]>;
+  receive: () => Promise<[z.output<RS>, null] | [null, Error]>;
 
   /**
    * @returns true if the stream has received a response
    */
-  received(): boolean;
+  received: () => boolean;
 }
 
 /**
  * Interface for an entity that sends a stream of requests.
  */
-export interface StreamSender<RQ> {
+export interface StreamSender<RQ extends z.ZodTypeAny> {
   /**
   * Sends a request to the stream. It is not safe to call send concurrently
   * with closeSend or send.
@@ -38,14 +47,14 @@ export interface StreamSender<RQ> {
   * @raises freighter.StreamClosed: if the client called close_send()
   * @raises Error: if the transport fails.
   */
-  send(req: RQ): Error | undefined;
+  send: (req: z.input<RQ>) => Error | null;
 }
 
 /**
  * Extension of the StreamSender interface that allows the client to close the sending
  * direction of the stream when finished issuing requrest.
  */
-export interface StreamSenderCloser<RQ> extends StreamSender<RQ> {
+export interface StreamSenderCloser<RQ extends z.ZodTypeAny> extends StreamSender<RQ> {
   /**
   * Lets the server know no more messages will be sent. If the client attempts
   * to call send() after calling closeSend(), a freighter.StreamClosed
@@ -55,13 +64,13 @@ export interface StreamSenderCloser<RQ> extends StreamSender<RQ> {
   * After calling close_send, the client is responsible for calling receive()
   * to successfully receive the server's acknowledgement.
    */
-  closeSend(): void;
+  closeSend: () => void;
 }
 
 /**
  * Interface for a bidirectional stream between a client and a server.
  */
-export interface Stream<RQ, RS>
+export interface Stream<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>
   extends StreamSenderCloser<RQ>,
     StreamReceiver<RS> {}
 
@@ -80,9 +89,9 @@ export interface StreamClient extends Transport {
    * @param resSchema - The schema for the response type. This is used to
    * validate the response before returning it.
    */
-  stream<RQ, RS>(
+  stream: <RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(
     target: string,
-    reqSchema: ZodSchema<RQ>,
-    resSchema: ZodSchema<RS>
-  ): Promise<Stream<RQ, RS>>;
+    reqSchema: RQ,
+    resSchema: RS,
+  ) => Promise<Stream<RQ, RS>>;
 }

package/src/transport.ts

@@ -0,0 +1,23 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type 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/unary.ts

@@ -0,0 +1,44 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type z } from "zod";
+
+import { type 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 extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(
+    target: string,
+    req: z.input<RQ> | null,
+    resSchema: RS | null,
+  ) => Promise<[z.output<RS>, null] | [null, Error]>;
+}
+
+export const sendRequired = async <
+  RQ extends z.ZodTypeAny,
+  RS extends z.ZodTypeAny = RQ,
+>(
+  client: UnaryClient,
+  target: string,
+  req: z.input<RQ>,
+  resSchema: RS | null,
+): Promise<z.output<RS>> => {
+  const [res, err] = await client.send(target, req, resSchema);
+  if (err != null) throw err;
+  return res;
+};