@synnaxlabs/freighter 0.55.0 → 0.56.1

package/src/stream.ts

@@ -16,15 +16,14 @@ import { type Transport } from "@/transport";
  */
 export interface StreamReceiver<RS extends z.ZodType> {
   /**
-   * Receives a response from the stream. It's not safe to call receive
-   * concurrently.
+   * Receives a response from the stream. It's not safe to call receive concurrently.
    *
-   *  @returns freighter.EOF: if the server closed the stream nominally.
-   *  @returns Error: if the server closed the stream abnormally,
-   *  returns the error the server returned.
-   *  @raises Error: if the transport fails.
+   *  @returns the next response from the stream.
+   *  @throws freighter.EOF: if the server closed the stream nominally.
+   *  @throws Error: if the server closed the stream abnormally, throws the error the
+   *  server returned, or a transport error if the transport itself failed.
    */
-  receive: () => Promise<[z.infer<RS>, null] | [null, Error]>;
+  receive: () => Promise<z.infer<RS>>;
 
   /**
    * @returns true if the stream has received a response
@@ -37,17 +36,16 @@ export interface StreamReceiver<RS extends z.ZodType> {
  */
 export interface StreamSender<RQ extends z.ZodType> {
   /**
-  * Sends a request to the stream. It is not safe to call send concurrently
-  * with closeSend or send.
+  * Sends a request to the stream. It is not safe to call send concurrently with
+  * closeSend or send.
 
   * @param req -  the request to send.
-  * @returns freighter.EOF: if the server closed the stream. The caller
-  * can discover the error returned by the server by calling receive().
-  * @returns undefined: if the message was sent successfully.
-  * @raises freighter.StreamClosed: if the client called close_send()
-  * @raises Error: if the transport fails.
+  * @throws freighter.EOF: if the server closed the stream. The caller can discover the
+  * error returned by the server by calling receive().
+  * @throws freighter.StreamClosed: if the client called closeSend().
+  * @throws Error: if the transport fails.
   */
-  send: (req: z.input<RQ> | z.infer<RQ>) => Error | null;
+  send: (req: z.input<RQ> | z.infer<RQ>) => void;
 }
 
 /**
@@ -56,13 +54,13 @@ export interface StreamSender<RQ extends z.ZodType> {
  */
 export interface StreamSenderCloser<RQ extends z.ZodType> 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
-  * exception will be raised. close_send is idempotent. If the server has
-  * already closed the stream, close_send will do nothing.
+  * Lets the server know no more messages will be sent. If the client attempts to call
+  * send() after calling closeSend(), a freighter.StreamClosed exception will be raised.
+  * close_send is idempotent. If the server has already closed the stream, close_send
+  * will do nothing.
 
-  * After calling close_send, the client is responsible for calling receive()
-  * to successfully receive the server's acknowledgement.
+  * After calling close_send, the client is responsible for calling receive() to
+  * successfully receive the server's acknowledgement.
    */
   closeSend: () => void;
 }
@@ -78,15 +76,15 @@ export interface Stream<RQ extends z.ZodType, RS extends z.ZodType = RQ>
  */
 export interface StreamClient extends Transport {
   /**
-   * Dials the target and returns a stream that can be used to issue requests
-   * and receive responses
+   * Dials the target and returns a stream that can be used to issue requests and
+   * receive responses
    *
-   * @param target - The target to dial. In some implementations, this may be
-   * an endpoint path, or in others, a complete hostname or URL.
-   * @param reqSchema - The schema for the request type. This is used to
-   * validate the request before sending it.
-   * @param resSchema - The schema for the response type. This is used to
-   * validate the response before returning it.
+   * @param target - The target to dial. In some implementations, this may be an
+   * endpoint path, or in others, a complete hostname or URL.
+   * @param reqSchema - The schema for the request type. This is used to validate the
+   * request before sending it.
+   * @param resSchema - The schema for the response type. This is used to validate the
+   * response before returning it.
    */
   stream: <RQ extends z.ZodType, RS extends z.ZodType = RQ>(
     target: string,

package/src/unary.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { breaker } from "@synnaxlabs/x";
+import { breaker, errors } from "@synnaxlabs/x";
 import { type z } from "zod";
 
 import { Unreachable } from "@/errors";
@@ -15,8 +15,8 @@ import { type Middleware } from "@/middleware";
 import { type Transport } from "@/transport";
 
 /**
- * An interface for an entity that implements a simple request-response
- * transport between two entities.
+ * An interface for an entity that implements a simple request-response transport
+ * between two entities.
  */
 export interface UnaryClient extends Transport {
   /**
@@ -24,13 +24,15 @@ export interface UnaryClient extends Transport {
    * @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.
+   * @returns the decoded response.
+   * @throws Error: if the server returns an error or the transport fails.
    */
   send: <RQ extends z.ZodType, RS extends z.ZodType = RQ>(
     target: string,
     req: z.input<RQ> | z.infer<RQ>,
     reqSchema: RQ,
     resSchema: RS,
-  ) => Promise<[z.infer<RS>, null] | [null, Error]>;
+  ) => Promise<z.infer<RS>>;
 }
 
 export const unaryWithBreaker = (
@@ -53,28 +55,19 @@ export const unaryWithBreaker = (
       req: z.input<RQ> | z.infer<RQ>,
       reqSchema: RQ,
       resSchema: RS,
-    ): Promise<[z.infer<RS>, null] | [null, Error]> {
+    ): Promise<z.infer<RS>> {
       const brk = new breaker.Breaker(cfg);
-      do {
-        const [res, err] = await this.wrapped.send(target, req, reqSchema, resSchema);
-        if (err == null) return [res, null];
-        if (!Unreachable.matches(err)) return [null, err];
-        console.warn(`[freighter] ${brk.retryMessage}`, err);
-        if (!(await brk.wait())) return [res, err];
-      } while (true);
+      do
+        try {
+          return await this.wrapped.send(target, req, reqSchema, resSchema);
+        } catch (err) {
+          const e = errors.fromUnknown(err);
+          if (!Unreachable.matches(e)) throw e;
+          console.warn(`[freighter] ${brk.retryMessage}`, e);
+          if (!(await brk.wait())) throw e;
+        }
+      while (true);
     }
   }
   return new WithBreaker(base);
 };
-
-export const sendRequired = async <RQ extends z.ZodType, RS extends z.ZodType = RQ>(
-  client: UnaryClient,
-  target: string,
-  req: z.input<RQ> | z.infer<RQ>,
-  reqSchema: RQ,
-  resSchema: RS,
-): Promise<z.infer<RS>> => {
-  const [res, err] = await client.send(target, req, reqSchema, resSchema);
-  if (err != null) throw err;
-  return res;
-};

package/src/websocket.spec.ts

@@ -15,12 +15,9 @@ import { EOF } from "@/errors";
 import { type Context } from "@/middleware";
 import { WebSocketClient } from "@/websocket";
 
-const url = new URL({
-  host: "127.0.0.1",
-  port: 8080,
-});
+const url = new URL({ host: "127.0.0.1", port: 8080 });
 
-const MessageSchema = z.object({
+const messageSchema = z.object({
   id: z.number().optional(),
   message: z.string().optional(),
 });
@@ -47,73 +44,63 @@ const decodeTestError = (encoded: errors.Payload): errors.Typed | null => {
   return new MyCustomError(message, parseInt(code, 10));
 };
 
-errors.register({
-  encode: encodeTestError,
-  decode: decodeTestError,
-});
+errors.register({ encode: encodeTestError, decode: decodeTestError });
 
 describe("websocket", () => {
   test("basic exchange", async () => {
-    const stream = await client.stream("stream/echo", MessageSchema, MessageSchema);
+    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();
-      expect(error).toBeNull();
-      expect(response?.id).toEqual(i + 1);
-      expect(response?.message).toEqual("hello");
+      const response = await stream.receive();
+      expect(response.id).toEqual(i + 1);
+      expect(response.message).toEqual("hello");
     }
     stream.closeSend();
-    const [response, error] = await stream.receive();
-    expect(EOF.matches(error)).toBeTruthy();
-    expect(response).toBeNull();
+    await expect(stream.receive()).rejects.toThrow(EOF);
   });
 
   test("receive message after close", async () => {
     const stream = await client.stream(
       "stream/sendMessageAfterClientClose",
-      MessageSchema,
-      MessageSchema,
+      messageSchema,
+      messageSchema,
     );
     stream.closeSend();
-    const [response, error] = await stream.receive();
-    expect(error).toBeNull();
-    expect(response?.id).toEqual(0);
-    expect(response?.message).toEqual("Close Acknowledged");
-    const [, recvError] = await stream.receive();
-    expect(EOF.matches(recvError)).toBeTruthy();
+    const response = await stream.receive();
+    expect(response.id).toEqual(0);
+    expect(response.message).toEqual("Close Acknowledged");
+    await expect(stream.receive()).rejects.toThrow(EOF);
   });
 
   test("receive error", async () => {
     const stream = await client.stream(
       "stream/receiveAndExitWithErr",
-      MessageSchema,
-      MessageSchema,
+      messageSchema,
+      messageSchema,
     );
     stream.send({ id: 0, message: "hello" });
-    const [response, error] = await stream.receive();
-    expect(MyCustomError.matches(error)).toBeTruthy();
-    expect(response).toBeNull();
+    await expect(stream.receive()).rejects.toThrow(MyCustomError);
   });
 
   describe("middleware", () => {
     test("receive middleware", async () => {
       const myClient = new WebSocketClient(url, new binary.JSONCodec());
       let c = 0;
-      myClient.use(async (md, next): Promise<[Context, Error | null]> => {
+      myClient.use(async (md, next): Promise<Context> => {
         if (md.params !== undefined) {
           c++;
           md.params.Test = "test";
         }
         return await next(md);
       });
-      await myClient.stream("stream/middlewareCheck", MessageSchema, MessageSchema);
+      await myClient.stream("stream/middlewareCheck", messageSchema, messageSchema);
       expect(c).toEqual(1);
     });
 
     test("middleware error on server", async () => {
       const myClient = new WebSocketClient(url, new binary.JSONCodec());
       await expect(
-        myClient.stream("stream/middlewareCheck", MessageSchema, MessageSchema),
+        myClient.stream("stream/middlewareCheck", messageSchema, messageSchema),
       ).rejects.toThrow("test param not found");
     });
   });

package/src/websocket.ts

@@ -56,34 +56,32 @@ class WebSocketStream<
     this.listenForMessages();
   }
 
-  async receiveOpenAck(): Promise<Error | null> {
+  async receiveOpenAck(): Promise<void> {
     const msg = await this.receiveMsg();
-    if (msg.type !== "open") {
-      if (msg.error == null) throw new Error("Message error must be defined");
-      return errors.decode(msg.error);
-    }
-    return null;
+    if (msg.type === "open") return;
+    if (msg.error == null) throw new Error("Message error must be defined");
+    const err = errors.decode(msg.error);
+    throw err ?? new Error(`Unexpected open-ack message type: ${msg.type}`);
   }
 
   /** Implements the Stream protocol */
-  send(req: z.input<RQ> | z.infer<RQ>): Error | null {
-    if (this.serverClosed != null) return new EOF();
+  send(req: z.input<RQ> | z.infer<RQ>): void {
+    if (this.serverClosed != null) throw new EOF();
     if (this.sendClosed) throw new StreamClosed();
     this.ws.send(this.codec.encode({ type: "data", payload: req }));
-    return null;
   }
 
   /** Implements the Stream protocol */
-  async receive(): Promise<[z.infer<RS>, null] | [null, Error]> {
-    if (this.serverClosed != null) return [null, this.serverClosed];
+  async receive(): Promise<z.infer<RS>> {
+    if (this.serverClosed != null) throw this.serverClosed;
     const msg = await this.receiveMsg();
     if (msg.type === "close") {
       if (msg.error == null) throw new Error("Message error must be defined");
       this.serverClosed = errors.decode(msg.error);
       if (this.serverClosed == null) throw new Error("Message error must be defined");
-      return [null, this.serverClosed];
+      throw this.serverClosed;
     }
-    return [this.resSchema.parse(msg.payload), null];
+    return this.resSchema.parse(msg.payload);
   }
 
   /** Implements the Stream protocol */
@@ -177,19 +175,16 @@ export class WebSocketClient extends MiddlewareCollector implements StreamClient
     resSchema: RS,
   ): Promise<Stream<RQ, RS>> {
     let stream: Stream<RQ, RS> | undefined;
-    const [, error] = await this.executeMiddleware(
+    await this.executeMiddleware(
       { target, protocol: "websocket", params: {}, role: "client" },
-      async (ctx: Context): Promise<[Context, Error | null]> => {
+      async (ctx: Context): Promise<Context> => {
         const ws = new WebSocket(this.buildURL(target, ctx));
         const outCtx: Context = { ...ctx, params: {} };
         ws.binaryType = WebSocketClient.MESSAGE_TYPE;
-        const streamOrErr = await this.wrapSocket(ws, reqSchema, resSchema);
-        if (streamOrErr instanceof Error) return [outCtx, streamOrErr];
-        stream = streamOrErr;
-        return [outCtx, null];
+        stream = await this.wrapSocket(ws, reqSchema, resSchema);
+        return outCtx;
       },
     );
-    if (error != null) throw error;
     return stream as Stream<RQ, RS>;
   }
 
@@ -208,21 +203,18 @@ export class WebSocketClient extends MiddlewareCollector implements StreamClient
     ws: WebSocket,
     reqSchema: RQ,
     resSchema: RS,
-  ): Promise<WebSocketStream<RQ, RS> | Error> {
-    return await new Promise((resolve) => {
+  ): Promise<WebSocketStream<RQ, RS>> {
+    return await new Promise((resolve, reject) => {
       ws.onopen = () => {
         const oWs = new WebSocketStream<RQ, RS>(ws, this.encoder, reqSchema, resSchema);
         oWs
           .receiveOpenAck()
-          .then((err) => {
-            if (err != null) resolve(err);
-            else resolve(oWs);
-          })
-          .catch((err: Error) => resolve(err));
+          .then(() => resolve(oWs))
+          .catch((err: unknown) => reject(errors.fromUnknown(err)));
       };
       ws.onerror = (ev: Event) => {
         const ev_ = ev as ErrorEvent;
-        resolve(new Error(ev_.message));
+        reject(new Error(ev_.message ?? "websocket error", { cause: ev_.error ?? ev }));
       };
     });
   }