@synnaxlabs/freighter 0.2.0 → 0.6.0

package/dist/http.d.ts

@@ -0,0 +1,20 @@
+import { type URL, type binary } from "@synnaxlabs/x";
+import { type z } from "zod";
+import { MiddlewareCollector } from './middleware';
+import { type UnaryClient } from './unary';
+export declare const CONTENT_TYPE_HEADER_KEY = "Content-Type";
+/**
+ * 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 declare class HTTPClient extends MiddlewareCollector implements UnaryClient {
+    endpoint: URL;
+    encoder: binary.EncoderDecoder;
+    fetch: typeof fetch;
+    constructor(endpoint: URL, encoder: binary.EncoderDecoder, secure?: boolean);
+    get headers(): Record<string, string>;
+    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]>;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { BaseTypedError, decodeError, encodeError, EOF, errorZ, registerError, StreamClosed, Unreachable, } 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/{build/module/lib → dist}/middleware.d.ts

@@ -1,28 +1,31 @@
 /**
- * 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 declare type MetaData = {
+export interface Context {
     target: string;
+    role: Role;
     protocol: string;
     params: Record<string, string>;
-};
+}
+export declare const ROLES: readonly ["client", "server"];
+export type Role = (typeof ROLES)[number];
 /** Next executes the next middleware in the chain. */
-export declare 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 declare 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.
  */
-declare 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
  * middleware in order to implement the Transport interface.
@@ -36,10 +39,10 @@ export declare 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>;
+    executeMiddleware(ctx: Context, finalizer: Finalizer): Promise<[Context, Error | null]>;
 }
 export {};

package/{build/main/lib → dist}/stream.d.ts

@@ -1,9 +1,9 @@
-import { ZodSchema } from 'zod';
-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.
@@ -13,16 +13,16 @@ 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.
@@ -34,13 +34,13 @@ 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
@@ -50,12 +50,12 @@ 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> extends StreamSenderCloser<RQ>, StreamReceiver<RS> {
+export interface Stream<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ> extends StreamSenderCloser<RQ>, StreamReceiver<RS> {
 }
 /**
  * Interface for a bidirectional stream between a client and a server.
@@ -72,5 +72,5 @@ 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>(target: string, reqSchema: ZodSchema<RQ>, resSchema: ZodSchema<RS>): Promise<Stream<RQ, RS>>;
+    stream: <RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(target: string, reqSchema: RQ, resSchema: RS) => Promise<Stream<RQ, RS>>;
 }

package/{build/main/lib → dist}/transport.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from './middleware';
+import { type Middleware } from './middleware';
 /**
  * Transport is a based interface that represents a general transport for
  * exchanging messages between a client and a server.
@@ -9,5 +9,5 @@ export interface Transport {
      *
      * @param mw - The middleware to register.
      */
-    use(...mw: Middleware[]): void;
+    use: (...mw: Middleware[]) => void;
 }

package/dist/unary.d.ts

@@ -0,0 +1,16 @@
+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 declare const sendRequired: <RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(client: UnaryClient, target: string, req: z.input<RQ> | z.output<RQ>, resSchema: RS | null) => Promise<z.output<RS>>;

package/dist/websocket.d.ts

@@ -0,0 +1,24 @@
+import { type URL, type binary } from "@synnaxlabs/x";
+import { z } from "zod";
+import { MiddlewareCollector } from './middleware';
+import type { Stream, StreamClient } from './stream';
+export declare const FREIGHTER_METADATA_PREFIX = "freighterctx";
+/**
+ * WebSocketClient is an implementation of StreamClient that is backed by
+ * websockets.
+ */
+export declare class WebSocketClient extends MiddlewareCollector implements StreamClient {
+    baseUrl: URL;
+    encoder: binary.EncoderDecoder;
+    static readonly MESSAGE_TYPE = "arraybuffer";
+    /**
+     * @param encoder - The encoder to use for encoding messages and decoding
+     *   responses.
+     * @param baseEndpoint - A base url to use as a prefix for all requests.
+     */
+    constructor(baseEndpoint: URL, encoder: binary.EncoderDecoder, secure?: boolean);
+    /** Implements the StreamClient interface. */
+    stream<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny = RQ>(target: string, reqSchema: RQ, resSchema: RS): Promise<Stream<RQ, RS>>;
+    private buildURL;
+    private wrapSocket;
+}

package/package.json

@@ -1,119 +1,51 @@
 {
   "name": "@synnaxlabs/freighter",
-  "version": "0.2.0",
+  "private": false,
+  "version": "0.6.0",
+  "type": "module",
   "description": "a modular transport abstraction",
-  "main": "build/main/index.js",
-  "typings": "build/main/index.d.ts",
-  "module": "build/module/index.js",
-  "repository": "https://github.com/synnaxlabs/synnax",
-  "license": "MIT",
+  "repository": "https://github.com/synnaxlabs/synnax/tree/main/freighter/ts",
+  "licens": "MIT",
   "keywords": [
     "synnax",
     "grpc",
     "transport",
-    "client",
     "data acquisition",
     "big data",
     "telemetry",
     "control systems"
   ],
-  "scripts": {
-    "build": "run-p build:*",
-    "build:main": "tsc -p tsconfig.json",
-    "build:module": "tsc -p tsconfig.module.json",
-    "fix": "run-s fix:*",
-    "fix:prettier": "prettier \"src/**/*.ts\" --write",
-    "fix:lint": "eslint src --ext .ts --fix",
-    "test": "run-s build test:*",
-    "test:lint": "eslint src --ext .ts",
-    "test:prettier": "prettier \"src/**/*.ts\" --list-different",
-    "test:unit": "nyc --silent ava",
-    "check-cli": "run-s test diff-integration-tests check-integration-tests",
-    "check-integration-tests": "run-s check-integration-test:*",
-    "diff-integration-tests": "mkdir -p diff && rm -rf diff/test && cp -r test diff/test && rm -rf diff/test/test-*/.git && cd diff && git init --quiet && git add -A && git commit --quiet --no-verify --allow-empty -m 'WIP' && echo '\\n\\nCommitted most recent integration test output in the \"diff\" directory. Review the changes with \"cd diff && git diff HEAD\" or your preferred git diff viewer.'",
-    "watch:build": "tsc -p tsconfig.json -w",
-    "watch:test": "nyc --silent ava --watch",
-    "cov": "run-s build test:unit cov:html cov:lcov",
-    "cov:html": "nyc report --reporter=html",
-    "cov:lcov": "nyc report --reporter=lcov",
-    "cov:send": "run-s cov:lcov && codecov",
-    "cov:check": "nyc report && nyc check-coverage --lines 100 --functions 100 --branches 100",
-    "doc": "run-s doc:html && open-cli build/docs/index.html",
-    "doc:html": "typedoc src/ --exclude **/*.spec.ts --target ES6 --mode file --out build/docs",
-    "doc:json": "typedoc src/ --exclude **/*.spec.ts --target ES6 --mode file --json build/docs/typedoc.json",
-    "doc:publish": "gh-pages -m \"[ci skip] Updates\" -d build/docs",
-    "version": "standard-version",
-    "reset-hard": "git clean -dfx && git reset --hard && yarn",
-    "prepare-release": "run-s reset-hard test cov:check doc:html version doc:publish"
-  },
   "engines": {
-    "node": ">=10"
+    "node": ">=18"
   },
   "dependencies": {
-    "@bitauth/libauth": "^1.17.1",
-    "axios": "^0.27.2",
     "js-convert-case": "^4.2.0",
-    "msgpackr": "^1.7.0",
-    "prettier-plugin-jsdoc": "^0.4.2",
-    "ws": "^8.8.1",
-    "zod": "^3.19.1"
+    "msgpackr": "^1.10.0",
+    "node-fetch": "2.6.11",
+    "ws": "^8.15.1",
+    "zod": "3.22.4",
+    "@synnaxlabs/alamos": "0.1.0",
+    "@synnaxlabs/x": "0.9.0"
   },
   "devDependencies": {
-    "@ava/typescript": "^1.1.1",
-    "@istanbuljs/nyc-config-typescript": "^1.0.1",
-    "@typescript-eslint/eslint-plugin": "^4.0.1",
-    "@typescript-eslint/parser": "^4.0.1",
-    "ava": "^3.12.1",
-    "codecov": "^3.5.0",
-    "cspell": "^4.1.0",
-    "cz-conventional-changelog": "^3.3.0",
-    "eslint": "^7.8.0",
-    "eslint-config-prettier": "^6.11.0",
-    "eslint-plugin-eslint-comments": "^3.2.0",
-    "eslint-plugin-import": "^2.22.0",
-    "gh-pages": "^3.1.0",
-    "npm-run-all": "^4.1.5",
-    "nyc": "^15.1.0",
-    "open-cli": "^6.0.1",
-    "prettier": "^2.7.1",
-    "standard-version": "^9.0.0",
-    "ts-node": "^9.0.0",
-    "typedoc": "^0.19.0",
-    "typescript": "^4.0.2"
-  },
-  "files": [
-    "build/main",
-    "build/module",
-    "!**/*.spec.*",
-    "!**/*.json",
-    "CHANGELOG.md",
-    "LICENSE",
-    "README.md"
-  ],
-  "ava": {
-    "failFast": true,
-    "timeout": "60s",
-    "typescript": {
-      "rewritePaths": {
-        "src/": "build/main/"
-      }
-    },
-    "files": [
-      "!build/module/**"
-    ]
+    "@types/node": "^20.10.5",
+    "@vitest/coverage-v8": "^1.2.2",
+    "typescript": "^5.3.3",
+    "vite": "^5.1.2",
+    "vitest": "^1.2.2",
+    "@synnaxlabs/vite-plugin": "0.0.1",
+    "@synnaxlabs/tsconfig": "0.0.1",
+    "eslint-config-synnaxlabs": "0.0.1"
   },
-  "config": {
-    "commitizen": {
-      "path": "cz-conventional-changelog"
-    }
-  },
-  "prettier": {
-    "singleQuote": true
-  },
-  "nyc": {
-    "extends": "@istanbuljs/nyc-config-typescript",
-    "exclude": [
-      "**/*.spec.js"
-    ]
+  "main": "dist/freighter.cjs.js",
+  "module": "dist/freighter.es.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --noEmit && vite build",
+    "watch": "tsc --noEmit && vite build --watch",
+    "test": "vitest",
+    "cov": "vitest --coverage",
+    "lint": "eslint \"src/**/*.ts*\"",
+    "fix": "eslint \"src/**/*.ts*\" --fix"
   }
-}
+}

package/src/alamos.ts

@@ -0,0 +1,40 @@
+// 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 Instrumentation } from "@synnaxlabs/alamos";
+
+import { type Middleware, type Context } from "@/middleware";
+
+export const middleware =
+  (instrumentation: Instrumentation): Middleware =>
+  async (context, next) => {
+    if (context.role === "client") instrumentation.T.propagate(context.params);
+    const [res, exc] = await instrumentation.T.trace(
+      context.target,
+      "debug",
+      async (span): Promise<[Context, Error | null]> => {
+        const [ctx, err] = await next(context);
+        if (err != null) span.recordError(err);
+        return [ctx, err];
+      },
+    );
+    log(context, instrumentation, exc);
+    return [res, exc];
+  };
+
+const log = (
+  context: Context,
+  instrumentation: Instrumentation,
+  err: Error | null,
+): void =>
+  err != null
+    ? instrumentation.L.error(
+        `${context.target} ${context.protocol} failed: ${err.message}`,
+      )
+    : instrumentation.L.debug(`${context.target} ${context.protocol}`);

package/src/errors.spec.ts

@@ -0,0 +1,94 @@
+// 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 { describe, expect, test } from "vitest";
+
+import {
+  BaseTypedError,
+  EOF,
+  FREIGHTER,
+  NONE,
+  StreamClosed,
+  type TypedError,
+  UNKNOWN,
+  UnknownError,
+  Unreachable,
+  assertErrorType,
+  decodeError,
+  encodeError,
+  isTypedError,
+  registerError,
+  type ErrorPayload,
+} from "@/errors";
+
+class MyCustomError extends BaseTypedError {
+  constructor(message: string) {
+    super(message, "MyCustomError");
+  }
+}
+
+const myCustomErrorEncoder = (error: MyCustomError): ErrorPayload => {
+  return { type: "MyCustomError", data: error.message };
+};
+
+const myCustomErrorDecoder = (encoded: ErrorPayload): TypedError => {
+  return new MyCustomError(encoded.data);
+};
+
+describe("errors", () => {
+  test("isTypedError", () => {
+    const error = new MyCustomError("test");
+    const fError = isTypedError(error);
+    expect(fError).toBeTruthy();
+    expect(error.type).toEqual("MyCustomError");
+  });
+
+  test("encoding and decoding a custom error through registry", () => {
+    registerError({
+      encode: myCustomErrorEncoder,
+      decode: myCustomErrorDecoder,
+    });
+    const error = new MyCustomError("test");
+    const encoded = encodeError(error);
+    expect(encoded.type).toEqual("MyCustomError");
+    expect(encoded.data).toEqual("test");
+    const decoded = assertErrorType<MyCustomError>(
+      "MyCustomError",
+      decodeError(encoded),
+    );
+    expect(decoded.message).toEqual("test");
+  });
+
+  test("encoding and decoding a null error", () => {
+    const encoded = encodeError(null);
+    expect(encoded.type).toEqual(NONE);
+    expect(encoded.data).toEqual("");
+    const decoded = decodeError(encoded);
+    expect(decoded).toBeNull();
+  });
+
+  test("encoding and decoding an unrecognized error", () => {
+    const error = new Error("test");
+    const encoded = encodeError(error);
+    expect(encoded.type).toEqual(UNKNOWN);
+    expect(encoded.data).toEqual("{}");
+    const decoded = decodeError(encoded);
+    expect(decoded).toEqual(new UnknownError("{}"));
+  });
+
+  test("encoding and decoding freighter errors", () => {
+    [new EOF(), new StreamClosed(), new Unreachable()].forEach((error) => {
+      const encoded = encodeError(error);
+      expect(encoded.type).toEqual(FREIGHTER);
+      expect(encoded.data).toEqual(error.message);
+      const decoded = decodeError(encoded);
+      expect(decoded).toEqual(error);
+    });
+  });
+});