@fuman/net 0.0.4 → 0.0.8

package/errors.d.cts

@@ -0,0 +1,6 @@
+export declare class ConnectionClosedError extends Error {
+    constructor(message?: string);
+}
+export declare class ListenerClosedError extends Error {
+    constructor();
+}

package/fake.d.cts

@@ -0,0 +1,16 @@
+import { IConnection } from './types.js';
+export declare class FakeConnection<Address = string> implements IConnection<Address, Address> {
+    readonly address: Address;
+    constructor(address: Address);
+    private rx;
+    private tx;
+    private closed;
+    private cv;
+    get localAddress(): Address;
+    get remoteAddress(): Address;
+    close(): void;
+    read(into: Uint8Array): Promise<number>;
+    write(bytes: Uint8Array): Promise<void>;
+    writeIntoRx(bytes: Uint8Array): void;
+    getTx(): Uint8Array;
+}

package/index.d.cts

@@ -0,0 +1,7 @@
+export * from './errors.js';
+export * from './fake.js';
+export * from './ip/index.js';
+export * from './proxy/index.js';
+export * from './reconnection.js';
+export * from './types.js';
+export * from './websocket.js';

package/ip/bundle.d.cts

@@ -0,0 +1,3 @@
+export * from './parse.js';
+export * from './v4.js';
+export * from './v6.js';

package/ip/index.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Utilities for parsing and manipulating IP addresses.
+ *
+ * @module
+ */
+import * as ip from './bundle.js';
+export * from './types.js';
+export { ip };

package/ip/parse.d.cts

@@ -0,0 +1,5 @@
+import { Ipv4Address, Ipv6Address } from './types.js';
+export declare function parse(ip: string): Ipv4Address | Ipv6Address;
+export declare function parseWithPort(ip: string): [Ipv4Address | Ipv6Address, number];
+export declare function stringify(parsed: Ipv4Address | Ipv6Address): string;
+export declare function stringifyWithPort(parsed: Ipv4Address | Ipv6Address, port: number): string;

package/ip/types.d.cts

@@ -0,0 +1,10 @@
+export interface Ipv4Address {
+    type: 'ipv4';
+    parts: Uint8Array;
+}
+export interface Ipv6Address {
+    type: 'ipv6';
+    parts: Uint16Array;
+    zoneId?: string;
+}
+export type IpAddress = Ipv4Address | Ipv6Address;

package/ip/v4.bench.d.cts

@@ -0,0 +1 @@
+export {};

package/ip/v4.d.cts

@@ -0,0 +1,4 @@
+import { Ipv4Address } from './types.js';
+export declare function parseV4(input: string): Ipv4Address;
+export declare function stringifyV4(ip: Ipv4Address): string;
+export declare function normalizeV4(input: string): string;

package/ip/v6.bench.d.cts

@@ -0,0 +1 @@
+export {};

package/ip/v6.d.cts

@@ -0,0 +1,18 @@
+import { ISyncReadable, ISyncWritable } from '@fuman/io';
+import { Ipv6Address } from './types.js';
+export declare function parseV6(string: string): Ipv6Address;
+export interface StringifyV6Options {
+    /**
+     * Whether to compress consecutive zeroes
+     * (according to [RFC 5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4))
+     */
+    zeroCompression?: boolean;
+    /** Whether to pad each part to 4 characters */
+    fixedLength?: boolean;
+}
+export declare function stringifyV6(parsed: Ipv6Address, options?: StringifyV6Options): string;
+export declare function expandV6(string: string): string;
+export declare function fromBytesV6(bytes: Uint8Array): Ipv6Address;
+export declare function readV6(reader: ISyncReadable): Ipv6Address;
+export declare function toBytesV6(parsed: Ipv6Address): Uint8Array;
+export declare function writeV6(parsed: Ipv6Address, writer: ISyncWritable): void;

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@fuman/net",
     "type": "module",
-    "version": "0.0.4",
+    "version": "0.0.8",
     "description": "experimental network abstractions",
     "license": "MIT",
     "scripts": {},
     "dependencies": {
-        "@fuman/io": "^0.0.4",
+        "@fuman/io": "^0.0.8",
         "@fuman/utils": "^0.0.4"
     },
     "exports": {

package/proxy/http/_protocol.d.cts

@@ -0,0 +1,3 @@
+import { TcpEndpoint } from '../../types.js';
+import { HttpProxySettings } from './types.js';
+export declare function buildConnectRequest(options: HttpProxySettings, dest: TcpEndpoint): Uint8Array;

package/proxy/http/connect.d.cts

@@ -0,0 +1,4 @@
+import { TcpEndpoint } from '../../types.js';
+import { IReadable, IWritable } from '@fuman/io';
+import { HttpProxySettings } from './types.js';
+export declare function performHttpProxyHandshake(reader: IReadable, writer: IWritable, proxy: HttpProxySettings, destination: TcpEndpoint): Promise<void>;

package/proxy/http/index.d.cts

@@ -0,0 +1,5 @@
+import { ConnectFunction, ITcpConnection, TcpEndpoint } from '../../types.js';
+import { HttpProxySettings } from './types.js';
+export * from './connect.js';
+export * from './types.js';
+export declare function withHttpProxy<Connection extends ITcpConnection, Connect extends ConnectFunction<TcpEndpoint, Connection>>(connect: Connect, proxy: HttpProxySettings): Connect;

package/proxy/http/types.d.cts

@@ -0,0 +1,32 @@
+/**
+ * An error has occurred while connecting to an HTTP(s) proxy
+ */
+export declare class HttpProxyConnectionError extends Error {
+    readonly proxy: HttpProxySettings;
+    constructor(proxy: HttpProxySettings, message: string);
+}
+/**
+ * HTTP(s) proxy settings
+ */
+export interface HttpProxySettings {
+    /**
+     * Host or IP of the proxy (e.g. `proxy.example.com`, `1.2.3.4`)
+     */
+    host: string;
+    /**
+     * Port of the proxy (e.g. `8888`)
+     */
+    port: number;
+    /**
+     * Proxy authorization username, if needed
+     */
+    user?: string;
+    /**
+     * Proxy authorization password, if needed
+     */
+    password?: string;
+    /**
+     * Proxy connection headers, if needed
+     */
+    headers?: Record<string, string>;
+}

package/proxy/index.d.cts

@@ -0,0 +1,2 @@
+export * from './http/index.js';
+export * from './socks/index.js';

package/proxy/socks/_protocol.d.cts

@@ -0,0 +1,7 @@
+import { TcpEndpoint } from '../../types.js';
+export declare const SOCKS4_ERRORS: Record<number, string>;
+export declare const SOCKS5_ERRORS: Record<number, string>;
+export declare function buildSocks4Connect(dest: TcpEndpoint, username?: string): Uint8Array;
+export declare function buildSocks5Greeting(authAvailable: boolean): Uint8Array;
+export declare function buildSocks5Auth(username: string, password: string): Uint8Array;
+export declare function buildSocks5Connect(dest: TcpEndpoint): Uint8Array;

package/proxy/socks/connect.d.cts

@@ -0,0 +1,4 @@
+import { IReadable, IWritable } from '@fuman/io';
+import { TcpEndpoint } from '../../types.js';
+import { SocksProxySettings } from './types.js';
+export declare function performSocksHandshake(reader: IReadable, writer: IWritable, proxy: SocksProxySettings, destination: TcpEndpoint): Promise<void>;

package/proxy/socks/index.d.cts

@@ -0,0 +1,5 @@
+import { ConnectFunction, ITcpConnection, TcpEndpoint } from '../../types.js';
+import { SocksProxySettings } from './types.js';
+export * from './connect.js';
+export * from './types.js';
+export declare function withSocksProxy<Connection extends ITcpConnection, Connect extends ConnectFunction<TcpEndpoint, Connection>>(connect: Connect, proxy: SocksProxySettings): Connect;

package/proxy/socks/types.d.cts

@@ -0,0 +1,34 @@
+/**
+ * Settings for a SOCKS4/5 proxy
+ */
+export interface SocksProxySettings {
+    /**
+     * Host or IP of the proxy (e.g. `proxy.example.com`, `1.2.3.4`)
+     */
+    host: string;
+    /**
+     * Port of the proxy (e.g. `8888`)
+     */
+    port: number;
+    /**
+     * Proxy authorization username, if needed
+     */
+    user?: string;
+    /**
+     * Proxy authorization password, if needed
+     */
+    password?: string;
+    /**
+     * Version of the SOCKS proxy (4 or 5)
+     *
+     * @default `5`
+     */
+    version?: 4 | 5;
+}
+/**
+ * An error has occurred while connecting to an SOCKS proxy
+ */
+export declare class SocksProxyConnectionError extends Error {
+    readonly proxy: SocksProxySettings;
+    constructor(proxy: SocksProxySettings, message: string);
+}

package/reconnection.d.cts

@@ -0,0 +1,82 @@
+import { IClosable } from '@fuman/io';
+import { MaybePromise } from '@fuman/utils';
+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 IClosable> {
+    #private;
+    readonly params: {
+        connect: (address: ConnectAddress) => Promise<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: (address: ConnectAddress) => Promise<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: (address: ConnectAddress) => Promise<Connection>): Promise<void>;
+}
+export {};

package/types.d.cts

@@ -0,0 +1,57 @@
+import { IClosable, IReadable, IWritable } from '@fuman/io';
+export interface IConnection<Address, LocalAddress = Address> extends IReadable, IWritable, IClosable {
+    /** local address of the connection (if available) */
+    readonly localAddress: LocalAddress | null;
+    /** remote address of the connection (if available) */
+    readonly remoteAddress: Address | null;
+}
+/** a TCP endpoint */
+export interface TcpEndpoint {
+    /** address of the endpoint */
+    readonly address: string;
+    /** port of the endpoint */
+    readonly port: number;
+}
+/** common TLS options */
+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;
+}
+/** TLS options for connecting to an endpoint */
+export interface TlsConnectOptions extends TcpEndpoint, TlsOptions {
+}
+/** TLS options for listening on an endpoint */
+export interface TlsListenOptions extends TcpEndpoint, TlsOptions {
+    readonly key?: string;
+    readonly cert?: string;
+    readonly hosts?: Omit<this, 'hosts' | 'address' | 'port'>[];
+}
+/** a TCP connection */
+export interface ITcpConnection extends IConnection<TcpEndpoint> {
+    /** set no-delay flag on the connection */
+    setNoDelay: (noDelay: boolean) => void;
+    /** set keep-alive flag on the connection */
+    setKeepAlive: (keepAlive: boolean) => void;
+}
+/** a TLS connection */
+export interface ITlsConnection extends ITcpConnection {
+    /** get the ALPN protocol that was negotiated in the handshake */
+    getAlpnProtocol: () => string | null;
+}
+/** a listener for connections */
+export interface IListener<Address, Connection extends IConnection<Address> = IConnection<Address>> extends IClosable {
+    /** address of the listener (if available) */
+    readonly address: Address | null;
+    /** accept a new connection */
+    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.d.cts

@@ -0,0 +1,43 @@
+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;
+    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 {};