@fuman/net 0.0.1

package/reconnection.d.ts

@@ -0,0 +1,82 @@
+import { MaybePromise } from '@fuman/utils';
+import { ConnectFunction, IConnection } from './types.js';
+interface ReconnectionState {
+    readonly previousWait: number | null;
+    readonly consequentFails: number;
+    readonly lastError: Error | null;
+}
+/**
+ * Declares a strategy to handle reconnection.
+ * When a number is returned, that number of MS will be waited before trying to reconnect.
+ * When `false` is returned, connection is not reconnected
+ */
+export type ReconnectionStrategy = (state: ReconnectionState) => number | false;
+/**
+ * Declares an action to take when an error occurs.
+ *
+ * - `reconnect` - reconnect using the current strategy
+ * - `reconnect-now` - reconnect immediately, ignoring the current strategy
+ * - `close` - close the connection
+ */
+export type OnErrorAction = 'reconnect' | 'reconnect-now' | 'close';
+/**
+ * default reconnection strategy: first - immediate reconnection,
+ * then 1s with linear increase up to 5s (with 1s step)
+ */
+export declare const defaultReconnectionStrategy: ReconnectionStrategy;
+export declare class PersistentConnection<ConnectAddress, Connection extends IConnection<unknown>> {
+    #private;
+    readonly params: {
+        connect: ConnectFunction<ConnectAddress, Connection>;
+        strategy?: ReconnectionStrategy;
+        /**
+         * Function to call once the connection is open
+         *
+         * As soon as the promise is resolved the connection will be closed (and will *not*
+         * be re-opened automatically), so this is the best place to put your recv loop
+         */
+        onOpen: (connection: Connection) => Promise<void>;
+        onClose?: () => MaybePromise<void>;
+        onWait?: (wait: number) => void;
+        /**
+         * Function that will be called whenever an error happens while connecting
+         * (in which case `connection` will be null) or inside `onOpen`.
+         *
+         * @default  `(err) => err instanceof ConnectionClosedError ? 'reconnect' : 'close'`
+         */
+        onError?: (error: Error, connection: Connection | null, state: ReconnectionState) => MaybePromise<OnErrorAction>;
+    };
+    constructor(params: {
+        connect: ConnectFunction<ConnectAddress, Connection>;
+        strategy?: ReconnectionStrategy;
+        /**
+         * Function to call once the connection is open
+         *
+         * As soon as the promise is resolved the connection will be closed (and will *not*
+         * be re-opened automatically), so this is the best place to put your recv loop
+         */
+        onOpen: (connection: Connection) => Promise<void>;
+        onClose?: () => MaybePromise<void>;
+        onWait?: (wait: number) => void;
+        /**
+         * Function that will be called whenever an error happens while connecting
+         * (in which case `connection` will be null) or inside `onOpen`.
+         *
+         * @default  `(err) => err instanceof ConnectionClosedError ? 'reconnect' : 'close'`
+         */
+        onError?: (error: Error, connection: Connection | null, state: ReconnectionState) => MaybePromise<OnErrorAction>;
+    });
+    get isConnected(): boolean;
+    get isConnecting(): boolean;
+    get isWaiting(): boolean;
+    get connection(): Connection | null;
+    get state(): ReconnectionState;
+    connect(address: ConnectAddress): void;
+    /**
+     * @param force  Whether to close the existing connection if there is one
+     */
+    reconnect(force: boolean): void;
+    close(): Promise<void>;
+    changeTransport(connect: ConnectFunction<ConnectAddress, Connection>): Promise<void>;
+}
+export {};

package/reconnection.js

@@ -0,0 +1,151 @@
+import { Deferred, timers } from "@fuman/utils";
+import { ConnectionClosedError } from "./errors.js";
+const defaultReconnectionStrategy = ({ previousWait }) => {
+  if (previousWait === null) return 0;
+  if (previousWait === 0) return 1e3;
+  if (previousWait >= 5e3) return 5e3;
+  return Math.min(5e3, previousWait + 1e3);
+};
+function defaultOnError(err) {
+  return err instanceof ConnectionClosedError ? "reconnect" : "close";
+}
+class PersistentConnection {
+  constructor(params) {
+    this.params = params;
+    this.#strategy = params.strategy ?? defaultReconnectionStrategy;
+    this.#connect = params.connect;
+    this.#onError = params.onError ?? defaultOnError;
+  }
+  #state = {
+    previousWait: null,
+    lastError: null,
+    consequentFails: 0
+  };
+  #connect;
+  #lastAddress;
+  #connection;
+  #connecting = false;
+  #strategy;
+  #onError;
+  // boolean represents whether the timer is clean
+  // true - resolved because timer is up
+  // false - resolved because .close()/.reconnect() was called
+  #sleep;
+  #closed;
+  get isConnected() {
+    return this.#connection !== void 0;
+  }
+  get isConnecting() {
+    return this.#connection === void 0 && this.#connecting;
+  }
+  get isWaiting() {
+    return this.#connection === void 0 && this.#lastAddress !== void 0 && !this.#connecting;
+  }
+  get connection() {
+    return this.#connection ?? null;
+  }
+  get state() {
+    return this.#state;
+  }
+  #resetState() {
+    this.#state.previousWait = null;
+    this.#state.lastError = null;
+    this.#state.consequentFails = 0;
+    this.#connecting = false;
+  }
+  async #loop() {
+    while (true) {
+      try {
+        this.#connecting = true;
+        this.#connection = await this.#connect(this.#lastAddress);
+        if (this.#closed) {
+          this.#closed.resolve();
+          break;
+        }
+        this.#resetState();
+        await this.params.onOpen?.(this.#connection);
+        this.#connection.close();
+        this.#connection = void 0;
+        break;
+      } catch (err) {
+        const oldConnection = this.#connection;
+        this.#connection = void 0;
+        await this.params.onClose?.();
+        if (this.#closed) {
+          this.#closed.resolve();
+          break;
+        }
+        const action = await this.#onError(err, oldConnection ?? null, this.#state);
+        if (action === "close") {
+          break;
+        }
+        const wait = action === "reconnect-now" ? 0 : this.#strategy(this.#state);
+        if (wait === false) {
+          break;
+        }
+        this.params.onWait?.(wait);
+        if (wait !== 0) {
+          this.#sleep = new Deferred();
+          const timer = timers.setTimeout(this.#sleep.resolve, wait, true);
+          const sleepResult = await this.#sleep.promise;
+          this.#sleep = void 0;
+          if (!sleepResult) {
+            timers.clearTimeout(timer);
+            if (this.#closed != null) {
+              this.#closed.resolve();
+              break;
+            } else {
+              continue;
+            }
+          }
+        }
+        this.#state.previousWait = wait;
+        this.#state.consequentFails = 1;
+        continue;
+      }
+    }
+    this.#lastAddress = void 0;
+    this.#resetState();
+  }
+  connect(address) {
+    if (this.#lastAddress !== void 0 && this.#lastAddress !== address) {
+      throw new Error("Connection is already open to another address");
+    }
+    this.#closed = void 0;
+    this.#lastAddress = address;
+    void this.#loop();
+  }
+  /**
+   * @param force  Whether to close the existing connection if there is one
+   */
+  reconnect(force) {
+    if (this.#sleep) {
+      this.#sleep.resolve(false);
+    } else if (this.#connection && force) {
+      this.#connection.close();
+    }
+  }
+  async close() {
+    if (this.#closed) return this.#closed.promise;
+    if (this.#lastAddress == null) return;
+    this.#closed = new Deferred();
+    if (this.#sleep) {
+      this.#sleep.resolve(false);
+    } else if (this.#connection) {
+      this.#connection.close();
+    } else if (this.#connecting) ;
+    return this.#closed.promise;
+  }
+  async changeTransport(connect) {
+    this.#connect = connect;
+    const addr = this.#lastAddress;
+    await this.close();
+    if (addr != null) {
+      this.connect(addr);
+    }
+  }
+}
+export {
+  PersistentConnection,
+  defaultReconnectionStrategy
+};

package/types.d.ts

@@ -0,0 +1,41 @@
+import { IClosable, IReadable, IWritable } from '@fuman/io';
+export interface IConnection<Address, LocalAddress = Address> extends IReadable, IWritable, IClosable {
+    readonly localAddress: LocalAddress | null;
+    readonly remoteAddress: Address | null;
+}
+export interface TcpEndpoint {
+    readonly address: string;
+    readonly port: number;
+}
+export interface TlsOptions {
+    /**
+     * List of CA certificates to use.
+     * Will replace whatever is in the default platform CA store.
+     */
+    readonly caCerts?: string[];
+    /** List of ALPN protocols to accept/offer */
+    readonly alpnProtocols?: string[];
+    /** Hostname to use for SNI */
+    readonly sni?: string;
+}
+export interface TlsConnectOptions extends TcpEndpoint, TlsOptions {
+}
+export interface TlsListenOptions extends TcpEndpoint, TlsOptions {
+    readonly key?: string;
+    readonly cert?: string;
+    readonly hosts?: Omit<this, 'hosts' | 'address' | 'port'>[];
+}
+export interface ITcpConnection extends IConnection<TcpEndpoint> {
+    setNoDelay: (noDelay: boolean) => void;
+    setKeepAlive: (keepAlive: boolean) => void;
+}
+export interface ITlsConnection extends ITcpConnection {
+    getAlpnProtocol: () => string | null;
+}
+export interface IListener<Address, Connection extends IConnection<Address> = IConnection<Address>> extends IClosable {
+    readonly address: Address | null;
+    accept: () => Promise<Connection>;
+}
+export type ListenFunction<Options, Listener extends IListener<unknown>> = (options: Options) => Promise<Listener>;
+export type ConnectFunction<Options, Connection extends IConnection<unknown>> = (options: Options) => Promise<Connection>;
+export type TlsUpgradeFunction<Options, TcpConnection extends ITcpConnection, TlsConnection extends ITlsConnection> = (tcpConn: TcpConnection, options: Options) => Promise<TlsConnection>;

package/websocket.cjs

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const io = require("@fuman/io");
+const utils = require("@fuman/utils");
+const errors = require("./errors.cjs");
+class WebSocketConnectionClosedError extends errors.ConnectionClosedError {
+  constructor(code, reason) {
+    super(`code ${code} (${reason})`);
+    this.code = code;
+    this.reason = reason;
+  }
+}
+function eventToError(event) {
+  if (event instanceof Error) {
+    return event;
+  }
+  return "error" in event ? event.error : new Error("unknown WebSocket error", { cause: event });
+}
+class WebSocketConnectionBase {
+  constructor(socket) {
+    this.socket = socket;
+    this._cv = new utils.ConditionVariable();
+    socket.addEventListener("message", (event) => {
+      this.onMessage(event);
+      this._cv.notify();
+    });
+    socket.addEventListener("close", (event) => {
+      this._error = new WebSocketConnectionClosedError(event.code, event.reason);
+      this._cv.notify();
+    });
+    socket.addEventListener("error", (event) => {
+      this._error = eventToError(event);
+      this._cv.notify();
+    });
+  }
+  _error = null;
+  _cv;
+  get remoteAddress() {
+    return this.socket.url;
+  }
+  get localAddress() {
+    throw new Error(".localAddress is not available for WebSockets");
+  }
+  close() {
+    this.socket?.close();
+    this._error = new errors.ConnectionClosedError();
+  }
+  closeWithCode(code, reason) {
+    this.socket.close(code, reason);
+    this._error = new errors.ConnectionClosedError();
+  }
+}
+class WebSocketConnection extends WebSocketConnectionBase {
+  #buffer;
+  constructor(socket) {
+    super(socket);
+    this.#buffer = io.Bytes.alloc(0);
+  }
+  onMessage(event) {
+    if (typeof event.data === "string") {
+      const buf = this.#buffer.writeSync(utils.utf8.encodedLength(event.data));
+      utils.utf8.encoder.encodeInto(event.data, buf);
+    } else {
+      const u8 = new Uint8Array(event.data);
+      this.#buffer.writeSync(u8.length).set(u8);
+    }
+    this.#buffer.disposeWriteSync();
+  }
+  async read(into) {
+    if (this.#buffer.available > 0) {
+      const size2 = Math.min(this.#buffer.available, into.length);
+      into.set(this.#buffer.readSync(size2));
+      this.#buffer.reclaim();
+      return size2;
+    }
+    if (this._error !== null) throw this._error;
+    await this._cv.wait();
+    if (this._error !== null) throw this._error;
+    const size = Math.min(this.#buffer.available, into.length);
+    into.set(this.#buffer.readSync(size));
+    this.#buffer.reclaim();
+    return size;
+  }
+  async write(bytes) {
+    if (this._error) throw this._error;
+    if (!bytes.length) return;
+    this.socket.send(bytes);
+  }
+}
+class WebSocketConnectionFramed extends WebSocketConnectionBase {
+  #buffer = new utils.Deque();
+  onMessage(event) {
+    if (typeof event.data === "string") {
+      this.#buffer.pushBack(event.data);
+    } else {
+      this.#buffer.pushBack(new Uint8Array(event.data));
+    }
+  }
+  async readFrame() {
+    if (!this.#buffer.isEmpty()) {
+      return this.#buffer.popFront();
+    }
+    if (this._error !== null) throw this._error;
+    await this._cv.wait();
+    if (this._error !== null) throw this._error;
+    return this.#buffer.popFront();
+  }
+  async writeFrame(data) {
+    if (this._error) throw this._error;
+    this.socket.send(data);
+  }
+}
+const connectWs = (endpoint) => {
+  const {
+    url,
+    implementation: WebSocketImpl = WebSocket,
+    protocols
+  } = endpoint;
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocketImpl(url, protocols);
+    socket.binaryType = "arraybuffer";
+    const onError = (event) => {
+      socket.removeEventListener("error", onError);
+      reject(eventToError(event));
+    };
+    socket.addEventListener("error", onError);
+    socket.addEventListener("open", () => {
+      socket.removeEventListener("error", onError);
+      resolve(new WebSocketConnection(socket));
+    });
+  });
+};
+async function connectWsFramed(endpoint) {
+  const {
+    url,
+    implementation: WebSocketImpl = WebSocket,
+    protocols
+  } = endpoint;
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocketImpl(url, protocols);
+    socket.binaryType = "arraybuffer";
+    const onError = (event) => {
+      socket.removeEventListener("error", onError);
+      reject(eventToError(event));
+    };
+    socket.addEventListener("error", onError);
+    socket.addEventListener("open", () => {
+      socket.removeEventListener("error", onError);
+      resolve(new WebSocketConnectionFramed(socket));
+    });
+  });
+}
+exports.WebSocketConnection = WebSocketConnection;
+exports.WebSocketConnectionClosedError = WebSocketConnectionClosedError;
+exports.WebSocketConnectionFramed = WebSocketConnectionFramed;
+exports.connectWs = connectWs;
+exports.connectWsFramed = connectWsFramed;

package/websocket.d.ts

@@ -0,0 +1,44 @@
+import { IClosable } from '@fuman/io';
+import { ConnectFunction, IConnection } from './types.js';
+import { ConditionVariable } from '@fuman/utils';
+import { ConnectionClosedError } from './errors.js';
+export declare class WebSocketConnectionClosedError extends ConnectionClosedError {
+    readonly code: number;
+    readonly reason: string;
+    constructor(code: number, reason: string);
+}
+declare abstract class WebSocketConnectionBase implements IClosable {
+    readonly socket: WebSocket;
+    protected _error: Error | null;
+    protected _cv: ConditionVariable;
+    constructor(socket: WebSocket);
+    get remoteAddress(): string | null;
+    get localAddress(): never;
+    close(): void;
+    closeWithCode(code: number, reason?: string): void;
+    abstract onMessage(event: MessageEvent): void;
+}
+export declare class WebSocketConnection extends WebSocketConnectionBase implements IConnection<string, never> {
+    #private;
+    constructor(socket: WebSocket);
+    onMessage(event: MessageEvent): void;
+    read(into: Uint8Array): Promise<number>;
+    write(bytes: Uint8Array): Promise<void>;
+}
+export declare class WebSocketConnectionFramed extends WebSocketConnectionBase {
+    #private;
+    onMessage(event: MessageEvent): void;
+    readFrame(): Promise<Uint8Array | string>;
+    writeFrame(data: Uint8Array | string): Promise<void>;
+}
+export interface WebSocketConstructor {
+    new (url: string | URL, protocols?: string | string[]): WebSocket;
+}
+export interface WebSocketEndpoint {
+    readonly url: string | URL;
+    readonly implementation?: WebSocketConstructor;
+    readonly protocols?: string | string[];
+}
+export declare const connectWs: ConnectFunction<WebSocketEndpoint, WebSocketConnection>;
+export declare function connectWsFramed(endpoint: WebSocketEndpoint): Promise<WebSocketConnectionFramed>;
+export {};

package/websocket.js

@@ -0,0 +1,157 @@
+import { Bytes } from "@fuman/io";
+import { utf8, Deque, ConditionVariable } from "@fuman/utils";
+import { ConnectionClosedError } from "./errors.js";
+class WebSocketConnectionClosedError extends ConnectionClosedError {
+  constructor(code, reason) {
+    super(`code ${code} (${reason})`);
+    this.code = code;
+    this.reason = reason;
+  }
+}
+function eventToError(event) {
+  if (event instanceof Error) {
+    return event;
+  }
+  return "error" in event ? event.error : new Error("unknown WebSocket error", { cause: event });
+}
+class WebSocketConnectionBase {
+  constructor(socket) {
+    this.socket = socket;
+    this._cv = new ConditionVariable();
+    socket.addEventListener("message", (event) => {
+      this.onMessage(event);
+      this._cv.notify();
+    });
+    socket.addEventListener("close", (event) => {
+      this._error = new WebSocketConnectionClosedError(event.code, event.reason);
+      this._cv.notify();
+    });
+    socket.addEventListener("error", (event) => {
+      this._error = eventToError(event);
+      this._cv.notify();
+    });
+  }
+  _error = null;
+  _cv;
+  get remoteAddress() {
+    return this.socket.url;
+  }
+  get localAddress() {
+    throw new Error(".localAddress is not available for WebSockets");
+  }
+  close() {
+    this.socket?.close();
+    this._error = new ConnectionClosedError();
+  }
+  closeWithCode(code, reason) {
+    this.socket.close(code, reason);
+    this._error = new ConnectionClosedError();
+  }
+}
+class WebSocketConnection extends WebSocketConnectionBase {
+  #buffer;
+  constructor(socket) {
+    super(socket);
+    this.#buffer = Bytes.alloc(0);
+  }
+  onMessage(event) {
+    if (typeof event.data === "string") {
+      const buf = this.#buffer.writeSync(utf8.encodedLength(event.data));
+      utf8.encoder.encodeInto(event.data, buf);
+    } else {
+      const u8 = new Uint8Array(event.data);
+      this.#buffer.writeSync(u8.length).set(u8);
+    }
+    this.#buffer.disposeWriteSync();
+  }
+  async read(into) {
+    if (this.#buffer.available > 0) {
+      const size2 = Math.min(this.#buffer.available, into.length);
+      into.set(this.#buffer.readSync(size2));
+      this.#buffer.reclaim();
+      return size2;
+    }
+    if (this._error !== null) throw this._error;
+    await this._cv.wait();
+    if (this._error !== null) throw this._error;
+    const size = Math.min(this.#buffer.available, into.length);
+    into.set(this.#buffer.readSync(size));
+    this.#buffer.reclaim();
+    return size;
+  }
+  async write(bytes) {
+    if (this._error) throw this._error;
+    if (!bytes.length) return;
+    this.socket.send(bytes);
+  }
+}
+class WebSocketConnectionFramed extends WebSocketConnectionBase {
+  #buffer = new Deque();
+  onMessage(event) {
+    if (typeof event.data === "string") {
+      this.#buffer.pushBack(event.data);
+    } else {
+      this.#buffer.pushBack(new Uint8Array(event.data));
+    }
+  }
+  async readFrame() {
+    if (!this.#buffer.isEmpty()) {
+      return this.#buffer.popFront();
+    }
+    if (this._error !== null) throw this._error;
+    await this._cv.wait();
+    if (this._error !== null) throw this._error;
+    return this.#buffer.popFront();
+  }
+  async writeFrame(data) {
+    if (this._error) throw this._error;
+    this.socket.send(data);
+  }
+}
+const connectWs = (endpoint) => {
+  const {
+    url,
+    implementation: WebSocketImpl = WebSocket,
+    protocols
+  } = endpoint;
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocketImpl(url, protocols);
+    socket.binaryType = "arraybuffer";
+    const onError = (event) => {
+      socket.removeEventListener("error", onError);
+      reject(eventToError(event));
+    };
+    socket.addEventListener("error", onError);
+    socket.addEventListener("open", () => {
+      socket.removeEventListener("error", onError);
+      resolve(new WebSocketConnection(socket));
+    });
+  });
+};
+async function connectWsFramed(endpoint) {
+  const {
+    url,
+    implementation: WebSocketImpl = WebSocket,
+    protocols
+  } = endpoint;
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocketImpl(url, protocols);
+    socket.binaryType = "arraybuffer";
+    const onError = (event) => {
+      socket.removeEventListener("error", onError);
+      reject(eventToError(event));
+    };
+    socket.addEventListener("error", onError);
+    socket.addEventListener("open", () => {
+      socket.removeEventListener("error", onError);
+      resolve(new WebSocketConnectionFramed(socket));
+    });
+  });
+}
+export {
+  WebSocketConnection,
+  WebSocketConnectionClosedError,
+  WebSocketConnectionFramed,
+  connectWs,
+  connectWsFramed
+};