@seriousme/opifex 2.1.0 → 2.3.0

package/node/socket-node-stream.test.ts

@@ -1,322 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { PassThrough } from "node:stream";
-import { Conn, type SockConn } from "./socket-node-stream.ts";
-
-// Helper to create a mock SockConn using a PassThrough duplex stream
-function createMockConn(): {
-  conn: Conn;
-  stream: PassThrough;
-  closeCalled: { count: number };
-} {
-  const stream = new PassThrough();
-  const closeCalled = { count: 0 };
-
-  const sockConn: SockConn = {
-    stream,
-    close: () => {
-      closeCalled.count++;
-    },
-    remoteAddr: {
-      transport: "tcp",
-      hostname: "127.0.0.1",
-      port: 1883,
-    },
-  };
-
-  const conn = new Conn(sockConn);
-  return { conn, stream, closeCalled };
-}
-
-test("Conn.write - successfully writes data", async () => {
-  const { conn, stream } = createMockConn();
-  const data = new Uint8Array([0x01, 0x02, 0x03]);
-
-  const bytesWritten = await conn.write(data);
-  assert.equal(bytesWritten, data.length, "Number of written bytes matches");
-
-  const chunk = stream.read();
-  assert.deepStrictEqual(
-    new Uint8Array(chunk),
-    data,
-    "The stream received the correct data",
-  );
-
-  conn.close();
-});
-
-test("Conn.write - respects backpressure and waits for drain event", async () => {
-  const { conn, stream } = createMockConn();
-  const data = new Uint8Array([0x01, 0x02, 0x03]);
-
-  // Force stream.write to return false to simulate a full internal buffer (backpressure)
-  stream.write = () => false;
-
-  let writeResolved = false;
-  const writePromise = conn.write(data).then((bytes) => {
-    writeResolved = true;
-    return bytes;
-  });
-
-  // Yield execution shortly to ensure the promise hasn't resolved prematurely
-  await new Promise((resolve) => setImmediate(resolve));
-  assert.equal(
-    writeResolved,
-    false,
-    "Write promise should pend while backpressure is active",
-  );
-
-  // Emit the drain event to signal the buffer has cleared
-  stream.emit("drain");
-
-  const bytesWritten = await writePromise;
-  assert.equal(bytesWritten, data.length, "Resolves after drain event fires");
-  assert.equal(writeResolved, true);
-
-  conn.close();
-});
-
-test("Conn.read - reads exact number of bytes", async () => {
-  const { conn, stream } = createMockConn();
-  const data = new Uint8Array([10, 20, 30, 40, 50]);
-
-  stream.write(data);
-
-  const result = await conn.read(3);
-  assert.deepStrictEqual(
-    result,
-    new Uint8Array([10, 20, 30]),
-    "First 3 bytes match",
-  );
-
-  const restResult = await conn.read(2);
-  assert.deepStrictEqual(
-    restResult,
-    new Uint8Array([40, 50]),
-    "Remaining bytes match via the leftover buffer",
-  );
-
-  conn.close();
-});
-
-test("Conn.read - waits for async data (readable event)", async () => {
-  const { conn, stream } = createMockConn();
-
-  const readPromise = conn.read(2);
-
-  // Simulate network latency using setImmediate or setTimeout
-  await new Promise((resolve) => setTimeout(resolve, 10));
-  stream.write(new Uint8Array([0xAA, 0xBB]));
-
-  const result = await readPromise;
-  assert.deepStrictEqual(
-    result,
-    new Uint8Array([0xAA, 0xBB]),
-    "Data correctly received after async wait",
-  );
-
-  conn.close();
-});
-
-test("Conn.close - gracefully closes the connection and streams", async () => {
-  const { conn, stream, closeCalled } = createMockConn();
-
-  assert.equal(closeCalled.count, 0, "Closer has not been called yet");
-
-  conn.close();
-
-  assert.equal(closeCalled.count, 1, "Closer is called exactly once");
-  assert.equal(stream.destroyed, true, "The underlying stream is destroyed");
-
-  await assert.rejects(
-    conn.write(new Uint8Array([1])),
-    /Stream is closed or not writable/,
-    "Writing to a closed connection throws an error",
-  );
-
-  const readResult = await conn.read(1);
-  assert.equal(
-    readResult,
-    null,
-    "Reading from a closed connection returns null",
-  );
-});
-
-test("Conn.read - length less than 0 returns null", async () => {
-  const { conn } = createMockConn();
-
-  const result = await conn.read(-5);
-  assert.equal(result, null, "Reading with a negative length returns null");
-
-  conn.close();
-});
-
-test("Conn.read - length equal to 0 returns empty Uint8Array", async () => {
-  const { conn } = createMockConn();
-
-  const result = await conn.read(0);
-  assert.deepStrictEqual(
-    result,
-    new Uint8Array(0),
-    "Reading 0 bytes returns an empty Uint8Array",
-  );
-
-  conn.close();
-});
-
-test("Conn.read - stream errors while waiting for data (returns null)", async () => {
-  const { conn, stream } = createMockConn();
-
-  // Prevent Node.js from crashing due to an unhandled stream error during test execution
-  stream.on("error", () => {});
-
-  const readPromise = conn.read(5);
-
-  // Emit error event to invoke internal error tracking state
-  stream.emit("error", new Error("Network failure"));
-
-  const result = await readPromise;
-  assert.equal(
-    result,
-    null,
-    "Returns null when the stream errors out during an active read",
-  );
-
-  conn.close();
-});
-
-test("Conn.read - chunk is larger than requested (populates leftover)", async () => {
-  const { conn, stream } = createMockConn();
-  const largeChunk = new Uint8Array([1, 2, 3, 4, 5]);
-
-  stream.write(largeChunk);
-
-  const result1 = await conn.read(2);
-  assert.deepStrictEqual(
-    result1,
-    new Uint8Array([1, 2]),
-    "Returns the exact requested chunk size",
-  );
-
-  const result2 = await conn.read(2);
-  assert.deepStrictEqual(
-    result2,
-    new Uint8Array([3, 4]),
-    "Returns the next bytes from the leftover buffer",
-  );
-
-  const result3 = await conn.read(1);
-  assert.deepStrictEqual(
-    result3,
-    new Uint8Array([5]),
-    "Returns the last remaining byte from leftover",
-  );
-
-  conn.close();
-});
-
-test("Conn.read - partial leftover is not enough (combines leftover and new stream chunk)", async () => {
-  const { conn, stream } = createMockConn();
-
-  // 1. Write 3 bytes and read 2 (leaving 1 byte [0x03] in leftover)
-  stream.write(new Uint8Array([0x01, 0x02, 0x03]));
-  await conn.read(2);
-
-  // 2. Write new data to the stream
-  stream.write(new Uint8Array([0x04, 0x05]));
-
-  // 3. Request 3 bytes (needs 1 from leftover + 2 from stream)
-  const result = await conn.read(3);
-  assert.deepStrictEqual(
-    result,
-    new Uint8Array([0x03, 0x04, 0x05]),
-    "Combines leftover data with newly arrived stream data",
-  );
-
-  conn.close();
-});
-
-test("Conn.write - rejects immediately if stream.writable is false", async () => {
-  const { conn, stream } = createMockConn();
-
-  Object.defineProperty(stream, "writable", { value: false });
-
-  await assert.rejects(
-    conn.write(new Uint8Array([1, 2, 3])),
-    /Stream is closed or not writable/,
-    "Rejects immediately when stream.writable is false",
-  );
-
-  conn.close();
-});
-
-test("Conn.read - fulfilled entirely from leftover buffer (skips while loop)", async () => {
-  const { conn, stream } = createMockConn();
-  const data = new Uint8Array([10, 20, 30, 40, 50]);
-
-  // 1. Populate the leftover buffer by reading less than what was written
-  stream.write(data);
-  await conn.read(2); // Leaves [30, 40, 50] in leftover
-
-  // 2. Request an amount that can be fully satisfied by the leftover buffer
-  const result = await conn.read(2);
-  assert.deepStrictEqual(
-    result,
-    new Uint8Array([30, 40]),
-    "Successfully fulfilled entirely from the leftover buffer",
-  );
-
-  // 3. Verify the remaining byte is still preserved
-  const finalResult = await conn.read(1);
-  assert.deepStrictEqual(
-    finalResult,
-    new Uint8Array([50]),
-    "The remaining byte in leftover is still accessible",
-  );
-
-  conn.close();
-});
-
-test("Conn - handles unexpected stream close event from underlying resource", () => {
-  const { conn, stream } = createMockConn();
-
-  // Initially, the connection should not be marked as closed
-  assert.equal(conn["closed"], false, "Connection is open initially");
-
-  // Simulate the underlying socket/stream closing unexpectedly from the remote side
-  stream.emit("close");
-
-  // Verify that the permanent 'close' listener was triggered and updated the internal state
-  assert.equal(
-    conn["closed"],
-    true,
-    "Connection internally updates to closed when stream emits close",
-  );
-
-  // Clean up to ensure resources are disposed
-  conn.close();
-});
-
-test("Conn.write - rejects the promise if stream.write invokes the callback with an error", async () => {
-  const { conn, stream } = createMockConn();
-  const data = new Uint8Array([1, 2, 3]);
-
-  // Simulate a write error by overriding stream.write
-  // It forces the callback to be invoked with an Error object
-  stream.write = (_chunk, callback) => {
-    if (typeof callback === "function") {
-      // Execute the callback with an error asynchronously, mimicking Node.js behavior
-      setImmediate(() => callback(new Error("Write pipeline failure")));
-    }
-    return false;
-  };
-
-  // Verify that the conn.write Promise rejects with the exact error
-  await assert.rejects(
-    conn.write(data),
-    /Write pipeline failure/,
-    "The write promise should reject when the stream callback receives an error",
-  );
-
-  conn.close();
-});

package/node/wrapNodeSocket.ts

@@ -1,44 +0,0 @@
-/**
- * Utility functions for wrapping Node.js sockets into standard web streams.
- */
-import type { Socket } from "node:net";
-import { Readable, Writable } from "node:stream";
-import type { NetAddr, SockConn } from "../socket/socket.ts";
-
-/**
- * Closes a Node.js socket if it is not already closed
- * @param sock - The Node.js socket to close
- */
-function closer(sock: Socket): void {
-  // deno-coverage-ignore-start
-  if (!sock.closed) {
-    sock.end();
-  }
-  // deno-coverage-ignore-stop
-}
-
-/**
- * Wraps a Node.js socket into a standard web streams-based socket connection
- * @param socket - The Node.js socket to wrap
- * @returns A socket connection object with readable/writable streams and close method
- */
-export function wrapNodeSocket(socket: Socket): SockConn {
-  const readable = Readable.toWeb(socket);
-  const writable = Writable.toWeb(socket);
-
-  // deno-coverage-ignore-start
-  const remoteAddr: NetAddr = {
-    hostname: socket.remoteAddress || "",
-    port: socket.remotePort || 0,
-    transport: "tcp",
-  };
-  // deno-coverage-ignore-stop
-
-  const conn: SockConn = {
-    readable: readable as ReadableStream<Uint8Array>,
-    writable: writable as WritableStream<Uint8Array>,
-    close: () => closer(socket),
-    remoteAddr,
-  };
-  return conn;
-}

package/socket/socket.test.ts

@@ -1,91 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { Conn } from "./socket.ts";
-import { createMockSockConn } from "../dev_utils/mod.ts";
-
-test("Conn.read peaks and buffers partial data correctly", async () => {
-  const chunk1 = new Uint8Array([1, 2, 3]);
-  const chunk2 = new Uint8Array([4, 5, 6, 7]);
-  const chunk3 = new Uint8Array([8, 9]);
-
-  const mockTarget = new Uint8Array();
-  const sockConn = createMockSockConn([chunk1, chunk2, chunk3], mockTarget);
-  const conn = new Conn(sockConn);
-
-  const res1 = await conn.read(2);
-  assert.deepStrictEqual(res1, new Uint8Array([1, 2]));
-
-  const res2 = await conn.read(3);
-  assert.deepStrictEqual(res2, new Uint8Array([3, 4, 5]));
-
-  const res3 = await conn.read(4);
-  assert.deepStrictEqual(res3, new Uint8Array([6, 7, 8, 9]));
-});
-
-test("Conn.read returns null when stream ends before length is met", async () => {
-  const chunk = new Uint8Array([1, 2, 3]);
-  const mockTarget = new Uint8Array(0);
-  const sockConn = createMockSockConn([chunk], mockTarget);
-  const conn = new Conn(sockConn);
-
-  // asking for5 bytes, but only 3 are available in the stream
-  const res = await conn.read(5);
-  assert.deepStrictEqual(res, null);
-});
-
-test("Conn.read returns null when length <= 0", async () => {
-  const chunk = new Uint8Array([1, 2, 3]);
-  const mockTarget = new Uint8Array(0);
-  const sockConn = createMockSockConn([chunk], mockTarget);
-  const conn = new Conn(sockConn);
-
-  const res = await conn.read(-1);
-  assert.deepStrictEqual(res, null);
-});
-
-test("Conn.read returns empty array when length = 0", async () => {
-  const chunk = new Uint8Array([1, 2, 3]);
-  const mockTarget = new Uint8Array(0);
-  const sockConn = createMockSockConn([chunk], mockTarget);
-  const conn = new Conn(sockConn);
-
-  const res = await conn.read(0);
-  assert.deepStrictEqual(res?.length, 0);
-});
-
-test("Conn.write successfully forwards data to writable stream", async () => {
-  const dataToWrite = new Uint8Array([10, 20, 30, 40]);
-  const mockTarget = new Uint8Array(4);
-  const sockConn = createMockSockConn([], mockTarget);
-  const conn = new Conn(sockConn);
-
-  const bytesWritten = await conn.write(dataToWrite);
-
-  assert.deepStrictEqual(bytesWritten, 4);
-  assert.deepStrictEqual(mockTarget, dataToWrite);
-});
-
-test("Conn.write rejects when connection is closed", async () => {
-  const mockTarget = new Uint8Array(4);
-  const sockConn = createMockSockConn([], mockTarget);
-  const conn = new Conn(sockConn);
-
-  conn.close();
-
-  await assert.rejects(
-    conn.write(new Uint8Array([1, 2])),
-    /Connection closed/,
-  );
-});
-
-test("Conn.close closes writer, releases reader lock and sets closed flag", () => {
-  const mockTarget = new Uint8Array(0);
-  const sockConn = createMockSockConn([], mockTarget);
-  const conn = new Conn(sockConn);
-
-  assert.deepStrictEqual(conn.closed, false);
-
-  conn.close();
-
-  assert.deepStrictEqual(conn.closed, true);
-});

package/socket/socket.ts

@@ -1,124 +0,0 @@
-/** Net adresses */
-export type NetAddr = {
-  transport: "tcp" | "udp";
-  hostname: string;
-  port: number;
-};
-/** Unix adresses */
-export type UnixAddr = { transport: "unix" | "unixpacket"; path: string };
-/** vSock adresses */
-export type VsockAddr = { transport: "vsock"; cid: number; port: number };
-/** Socket adresses */
-export type SockAddr = NetAddr | UnixAddr | VsockAddr;
-/** Socket connection descriptor. */
-export type SockConn = {
-  readable: ReadableStream<Uint8Array>;
-  writable: WritableStream<Uint8Array>;
-  close: () => void;
-  localAddr?: SockAddr;
-  remoteAddr?: SockAddr;
-};
-
-export class Conn {
-  reader: ReadableStreamDefaultReader<Uint8Array>;
-  writer: WritableStreamDefaultWriter<Uint8Array>;
-  closed: boolean;
-  remoteAddr: SockAddr | undefined;
-  closer: () => void;
-
-  private leftover: Uint8Array = new Uint8Array(0);
-
-  constructor(sockConn: SockConn) {
-    this.closed = false;
-    this.reader = sockConn.readable.getReader();
-    this.writer = sockConn.writable.getWriter();
-    this.closer = sockConn.close.bind(sockConn);
-    this.reader.closed.catch(() => {});
-    this.writer.closed.catch(() => {});
-    this.remoteAddr = sockConn.remoteAddr;
-  }
-
-  async read(length: number): Promise<Uint8Array | null> {
-    if (this.closed || length < 0) {
-      return null;
-    }
-
-    if (length === 0) {
-      return new Uint8Array(0);
-    }
-
-    const result = new Uint8Array(length);
-    let bytesAccumulated = 0;
-
-    // Do we have data from the previous read()
-    if (this.leftover.length > 0) {
-      const take = Math.min(this.leftover.length, length);
-      result.set(this.leftover.subarray(0, take), bytesAccumulated);
-      bytesAccumulated += take;
-      this.leftover = this.leftover.subarray(take);
-    }
-
-    // Keep readin until we have enough data
-    while (bytesAccumulated < length) {
-      const { value, done } = await this.reader.read();
-
-      if (value) {
-        const needed = length - bytesAccumulated;
-
-        if (value.length <= needed) {
-          // We need the whole chunk
-          result.set(value, bytesAccumulated);
-          bytesAccumulated += value.length;
-        } else {
-          // Chunk is bigger than what we need
-          result.set(value.subarray(0, needed), bytesAccumulated);
-          bytesAccumulated += needed;
-          // Save the rest for the next read() call
-          this.leftover = value.subarray(needed);
-        }
-      }
-      if (done) {
-        // if the stream closed and not enough data was returned, return null
-        return null;
-      }
-    }
-    return result;
-  }
-
-  async write(data: Uint8Array): Promise<number> {
-    if (this.closed) {
-      return Promise.reject(new Error("Connection closed"));
-    }
-    try {
-      await this.writer.write(data);
-      return data.length;
-    } catch (err) {
-      this.closed = true;
-      throw err;
-    }
-  }
-
-  close() {
-    if (!this.closed) {
-      this.closed = true;
-
-      // deno-coverage-ignore-start
-      void this.writer.close().catch(() => {
-        // ignore duplicate/late close attempts; the stream may already be closed
-      });
-      // deno-coverage-ignore-stop
-
-      try {
-        void this.reader.cancel().catch(() => {
-          // ignore duplicate/late cancel attempts; the stream may already be closed
-        });
-        this.reader?.releaseLock();
-        // deno-coverage-ignore
-      } catch (_err) { /* swallow */ }
-
-      try {
-        this.closer();
-      } catch (_err) { /* swallow */ }
-    }
-  }
-}

package/web/webSocketStream.ts

@@ -1,97 +0,0 @@
-/**
- * Utility functions for wrapping standard WebSockets into standard web streams.
- */
-
-export interface WebSocketConnection<
-  T extends Uint8Array | string = Uint8Array | string,
-> {
-  readable: ReadableStream<T>;
-  writable: WritableStream<T>;
-  protocol: string;
-  extensions: string;
-}
-
-export interface WebSocketCloseInfo {
-  closeCode?: number;
-  reason?: string;
-}
-
-export interface WebSocketStreamOptions {
-  protocols?: string[];
-  signal?: AbortSignal;
-}
-
-/**
- * [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) with [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)
- *
- * @see https://web.dev/websocketstream/
- */
-export class WebSocketStream<
-  T extends Uint8Array | string = Uint8Array | string,
-> {
-  readonly opened: Promise<WebSocketConnection<T>>;
-
-  readonly closed: Promise<WebSocketCloseInfo>;
-
-  readonly close: (closeInfo?: WebSocketCloseInfo) => void;
-
-  constructor(ws: WebSocket, options: WebSocketStreamOptions = {}) {
-    if (options.signal?.aborted) {
-      throw new DOMException("This operation was aborted", "AbortError");
-    }
-    const closeWithInfo = (
-      { closeCode: code, reason }: WebSocketCloseInfo = {},
-    ) => ws.close(code, reason);
-
-    this.opened = new Promise((resolve, reject) => {
-      ws.onopen = () => {
-        resolve({
-          readable: new ReadableStream<T>({
-            start(controller) {
-              ws.onmessage = ({ data }) => {
-                if (data instanceof ArrayBuffer) {
-                  controller.enqueue(new Uint8Array(data) as T);
-                } else {
-                  controller.enqueue(data as T);
-                }
-              };
-              ws.onerror = (e) => controller.error(e);
-            },
-            cancel: closeWithInfo,
-          }),
-          writable: new WritableStream<T>({
-            write(chunk) {
-              if (chunk instanceof Uint8Array) {
-                ws.send(chunk.buffer as ArrayBuffer);
-              } else {
-                ws.send(chunk);
-              }
-            },
-            abort() {
-              ws.close();
-            },
-            close: closeWithInfo,
-          }),
-          protocol: ws.protocol,
-          extensions: ws.extensions,
-        });
-        ws.removeEventListener("error", reject);
-      };
-      ws.addEventListener("error", reject);
-    });
-
-    this.closed = new Promise<WebSocketCloseInfo>((resolve, reject) => {
-      ws.onclose = ({ code, reason }) => {
-        resolve({ closeCode: code, reason });
-        ws.removeEventListener("error", reject);
-      };
-      ws.addEventListener("error", reject);
-    });
-
-    if (options.signal) {
-      options.signal.onabort = () => ws.close();
-    }
-
-    this.close = closeWithInfo;
-  }
-}