@lakutata/netif 0.0.0-stage → 3.1.5

package/dist/types/lib/Attachment.d.ts

@@ -0,0 +1,152 @@
+import { EventEmitter } from 'node:events';
+import { type Family } from './Enforcement.js';
+import { type NetworkInterface } from './NetworkInterface.js';
+import { type InterfaceAddress } from './Types.js';
+/**
+ * An address a listener or a UDP socket of an interface can be reached at.
+ */
+export interface ListeningAddress {
+    /**
+     * The address (an IPv6 address without its scope).
+     */
+    address: string;
+    /**
+     * `'IPv4'` or `'IPv6'`.
+     */
+    family: 'IPv4' | 'IPv6';
+    /**
+     * The port.
+     */
+    port: number;
+    /**
+     * IPv6 only: the scope of the address (the index of the interface for a link-local one), 0 for a global one.
+     */
+    scopeid?: number;
+}
+/**
+ * The options common to the listeners and the UDP sockets of an interface
+ */
+export interface AttachmentOptions {
+    port: number;
+    family?: 'IPv4' | 'IPv6' | 'both';
+    strict?: boolean;
+}
+/**
+ * What a socket of an attachment is made on: a socket bound to the interface (Linux, its descriptor), or an address of
+ * the interface (the host with its scope, and the port)
+ */
+export type Target = {
+    fd: number;
+} | {
+    host: string;
+    port: number;
+};
+/**
+ * A socket of an attachment: bound to the interface, or to one of its addresses
+ */
+export interface Endpoint<Handle> {
+    key: string;
+    family: Family;
+    handle: Handle;
+    address?: InterfaceAddress;
+}
+/**
+ * The code of the error of the system an error carries
+ */
+export declare function codeOf(error: unknown): unknown;
+/**
+ * The sockets of an interface kept matching it (the base of the listeners and the UDP sockets): on Linux sockets bound
+ * to the interface, one by family, made again when the interface is plugged back (a new index); elsewhere (and on Linux
+ * without the permission to bind) a socket by address of the interface, made and closed as its addresses change. The
+ * guarantee that the system refuses what comes through another interface (`enforced`), followed; with `strict` the
+ * sockets are closed while it is lost. The changes of the interface are followed one at a time.
+ */
+export declare abstract class Attachment<Events extends Record<keyof Events, unknown[]>, Handle> extends EventEmitter<Events> {
+    #private;
+    /**
+     * The interface.
+     */
+    readonly networkInterface: NetworkInterface;
+    protected readonly families: Family[];
+    protected readonly strict: boolean;
+    /**
+     * Internal: the options checked.
+     * @param networkInterface The interface.
+     * @param options The port, the families and `strict`.
+     * @param ownsInterface Whether the interface is closed with it.
+     */
+    protected constructor(networkInterface: NetworkInterface, options: AttachmentOptions, ownsInterface: boolean);
+    /**
+     * Whether a TCP (true) or a UDP socket is bound to the interface
+     */
+    protected abstract readonly stream: boolean;
+    /**
+     * Makes a socket of a family on the target: its handle once it listens (or is bound)
+     */
+    protected abstract openHandle(target: Target, family: Family): Promise<Handle>;
+    /**
+     * The port of a socket made
+     */
+    protected abstract portOf(handle: Handle): number | undefined;
+    /**
+     * Closes a socket
+     */
+    protected abstract closeHandle(handle: Handle): void;
+    /**
+     * Whether the system refuses, through another interface, what is sent to the addresses of the interface: always on
+     * Linux (the sockets are bound to the interface), on Windows while every other interface receives with the strong
+     * host model and does not forward, on macOS when it is set to (`net.inet.ip.check_interface` 2, forwarding off).
+     */
+    get enforced(): boolean;
+    /**
+     * Why what comes through another interface is not refused, `undefined` while it is.
+     */
+    get reason(): string | undefined;
+    /**
+     * The port, `undefined` until a port 0 was given one by the system.
+     */
+    get port(): number | undefined;
+    /**
+     * Whether the interface is listened on now (it exists, and has an address where its addresses are listened on).
+     */
+    get listening(): boolean;
+    /**
+     * The addresses it can be reached at now. On Linux the sockets bound to the interface also get what is sent to
+     * another address of the machine through the interface.
+     */
+    get addresses(): ListeningAddress[];
+    /**
+     * Whether it was closed.
+     */
+    get closed(): boolean;
+    /**
+     * Whether the sockets are bound to the interface (Linux), not to its addresses
+     */
+    protected get boundToInterface(): boolean;
+    /**
+     * The sockets now
+     */
+    protected endpoints(): Endpoint<Handle>[];
+    /**
+     * A socket made, before it is counted (its settings applied: the broadcasts, the multicast groups)
+     */
+    protected prepare(_endpoint: Endpoint<Handle>): void;
+    /**
+     * A socket closed, no longer counted
+     */
+    protected released(_endpoint: Endpoint<Handle>): void;
+    /**
+     * Internal: the first binding, which the method that made it waits for.
+     * @returns It.
+     */
+    start(): Promise<this>;
+    /**
+     * Stops: the sockets closed (the listener does not wait for the connections established, which are left to the
+     * server).
+     */
+    close(): Promise<void>;
+    /**
+     * An error of a binding again, or of a socket: the error event, the binding retried a little later
+     */
+    protected failed(error: unknown): void;
+}

package/dist/types/lib/Enforcement.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A family of addresses
+ */
+export type Family = 'IPv4' | 'IPv6';
+/**
+ * Whether the system refuses the connections and the datagrams reaching the addresses of an interface through another
+ * interface, and why not
+ */
+export interface Enforcement {
+    enforced: boolean;
+    reason?: string;
+}
+/**
+ * Why a socket of Linux could not be bound to the interface
+ */
+export declare const LINUX_PERMISSION: string;
+/**
+ * Whether the system refuses, through the other interfaces, the packets for the addresses of the interface of the index
+ * when they are listened on by address: the strong host model of Windows (every other interface receiving with it and
+ * not forwarding) and of macOS (net.inet.ip.check_interface set to 2, forwarding off); never on Linux
+ */
+export declare function addressEnforcement(index: number, families: Family[]): Enforcement;

package/dist/types/lib/Functions.d.ts

@@ -0,0 +1,66 @@
+import { type Server } from 'node:net';
+import { InterfaceListener, type ListenOptions } from './InterfaceListener.js';
+import { type InterfaceSelector } from './NetworkInterface.js';
+import { type NetworkInterfaceInfo } from './Types.js';
+/**
+ * The network interfaces of the machine, the ones without an address too, with their state: their name, index,
+ * hardware address, whether they are enabled and connected, their usable addresses. More than `os.networkInterfaces()`,
+ * which lists only the interfaces with an address and no state.
+ * @returns The interfaces, in the order of the system.
+ * @example
+ * ```typescript
+ * import {listInterfaces, type NetworkInterfaceInfo} from '@lakutata/netif'
+ *
+ * for (const entry of listInterfaces()) {
+ *     console.log(entry.name, entry.running ? 'connected' : 'not connected', entry.addresses.map(address => address.cidr))
+ * }
+ * const connected: NetworkInterfaceInfo[] = listInterfaces().filter(entry => entry.running && !entry.loopback)
+ * ```
+ */
+export declare function listInterfaces(): NetworkInterfaceInfo[];
+/**
+ * Listens on an interface for a server: `new NetworkInterface(selector).listen(server, options)` in one call, the
+ * interface followed until the listener is closed.
+ * @param selector The interface: its name, `{mac}` or `{index}`.
+ * @param server A `net.Server` or a server built on one (`http`, `https`, `http2`, `tls`), which must not listen itself.
+ * @param options The port, the families, `strict` and the backlog.
+ * @returns The listener.
+ * @throws NetIfNotEnforcedException With `strict`, where the system cannot refuse the connections coming through another
+ * interface.
+ * @throws NetIfNotFoundException An index or a hardware address that cannot be found.
+ * @throws NetIfException The system refused the first listening, its code as `errno`.
+ * @example
+ * ```typescript
+ * import {createServer} from 'node:http'
+ * import {type InterfaceListener, listenOn} from '@lakutata/netif'
+ *
+ * const listener: InterfaceListener = await listenOn('eth1', createServer((request, response) => response.end('ok')), {port: 8080})
+ * console.log(listener.addresses)
+ * ```
+ */
+export declare function listenOn(selector: InterfaceSelector, server: Server, options: ListenOptions): Promise<InterfaceListener>;
+/**
+ * Listens on several interfaces for a server: `listenOn()` for each of them, one listener by interface, the interfaces
+ * followed until their listeners are closed. When one of them cannot be listened on, the ones listened on already are
+ * closed and the error is thrown. Several interfaces need a port: 0 lets the system choose one for the first
+ * interface, which may not exist yet. With it, the package implements `IInterfaceListening` of `@lakutata/core`: the
+ * entrypoints of lakutata listen on interfaces through it.
+ * @param selectors An interface (its name, `{mac}` or `{index}`), or several.
+ * @param server A `net.Server` or a server built on one (`http`, `https`, `http2`, `tls`), which must not listen itself.
+ * @param options The port, the families, `strict` and the backlog, the same for every interface.
+ * @returns The listeners, in the order of the interfaces.
+ * @throws TypeError No interface, or a port 0 with several of them.
+ * @throws NetIfNotEnforcedException With `strict`, where the system cannot refuse the connections coming through another
+ * interface.
+ * @throws NetIfException The system refused a first listening, its code as `errno`.
+ * @example
+ * ```typescript
+ * import {createServer} from 'node:http'
+ * import {type InterfaceListener, listenOnAll} from '@lakutata/netif'
+ *
+ * const server = createServer((request, response) => response.end('ok'))
+ * const listeners: InterfaceListener[] = await listenOnAll(['eth1', {mac: '52:54:00:12:34:56'}], server, {port: 8080})
+ * for (const listener of listeners) listener.on('error', error => console.error(error))
+ * ```
+ */
+export declare function listenOnAll(selectors: InterfaceSelector | InterfaceSelector[], server: Server, options: ListenOptions): Promise<InterfaceListener[]>;

package/dist/types/lib/InterfaceListener.d.ts

@@ -0,0 +1,92 @@
+import { type Server } from 'node:net';
+import type { IInterfaceListener } from '@lakutata/core';
+import { Attachment, type Target } from './Attachment.js';
+import { type Family } from './Enforcement.js';
+import { type NetworkInterface } from './NetworkInterface.js';
+/**
+ * The options of `listen()`.
+ */
+export interface ListenOptions {
+    /**
+     * The port. 0: one the system chooses, kept when the interface is listened on again.
+     */
+    port: number;
+    /**
+     * The families listened on: `'IPv4'`, `'IPv6'` or `'both'` (by default). With `'both'`, a system without IPv6 is
+     * listened on in IPv4.
+     */
+    family?: 'IPv4' | 'IPv6' | 'both';
+    /**
+     * `true`: the listening is refused (a `NetIfNotEnforcedException`) where the system cannot refuse the connections
+     * reaching the addresses of the interface through another interface, and it stops while that guarantee is lost.
+     * `false` by default: the best the system allows, told by `enforced`.
+     */
+    strict?: boolean;
+    /**
+     * The length of the queue of the connections not accepted yet, 511 by default.
+     */
+    backlog?: number;
+}
+/**
+ * The events of an `InterfaceListener` and their arguments.
+ */
+export interface InterfaceListenerEvents {
+    /**
+     * The interface is listened on, after `listen()` and each time it is listened on again (an address added, the
+     * interface plugged back).
+     */
+    listening: [];
+    /**
+     * An error of a listening again (the port taken meanwhile…), retried a little later; with `strict`, the guarantee
+     * lost (a `NetIfNotEnforcedException`). Without a listener of `error`, the error is thrown, as for a `net.Server`.
+     */
+    error: [error: Error];
+    /**
+     * Whether the connections coming through another interface are refused changed: its new value.
+     */
+    enforced: [enforced: boolean];
+    /**
+     * The listener was closed.
+     */
+    close: [];
+}
+/**
+ * The listening of a server on a network interface: `NetworkInterface.listen()`. The listener accepts the connections
+ * and gives them to the server (`server.emit('connection', socket)`), which handles them as its own: the server itself
+ * does not listen (its `address()` is `null`, its `close()` does not stop the listener; use the ones of the listener).
+ * The interface is listened on again when its addresses change and when it is unplugged and plugged back; the
+ * connections established are left to the server. It implements `IInterfaceListener` of `@lakutata/core`.
+ * @example
+ * ```typescript
+ * import {createServer} from 'node:http'
+ * import {type InterfaceListener, NetworkInterface} from '@lakutata/netif'
+ *
+ * const server = createServer((request, response) => response.end('ok'))
+ * const listener: InterfaceListener = await new NetworkInterface('eth1').listen(server, {port: 8080})
+ * console.log(listener.enforced, listener.addresses)
+ * listener.on('error', error => console.error(error))
+ * await listener.close()
+ * ```
+ */
+export declare class InterfaceListener extends Attachment<InterfaceListenerEvents, Server> implements IInterfaceListener {
+    #private;
+    /**
+     * The server the connections are given to.
+     */
+    readonly server: Server;
+    protected readonly stream: boolean;
+    /**
+     * Internal: made by `NetworkInterface.listen()` and `listenOn()`; `start()` listens.
+     * @param networkInterface The interface.
+     * @param server The server.
+     * @param options The options of `listen()`.
+     * @param ownsInterface Whether the interface is closed with the listener (`listenOn()`).
+     */
+    constructor(networkInterface: NetworkInterface, server: Server, options: ListenOptions, ownsInterface?: boolean);
+    /**
+     * Listens on the target: a server of the listener, the connections it accepts given to the server of the user
+     */
+    protected openHandle(target: Target, _family: Family): Promise<Server>;
+    protected portOf(handle: Server): number | undefined;
+    protected closeHandle(handle: Server): void;
+}

package/dist/types/lib/InterfaceUDPSocket.d.ts

@@ -0,0 +1,119 @@
+import { type RemoteInfo, type Socket } from 'node:dgram';
+import { Attachment, type Endpoint, type Target } from './Attachment.js';
+import { type Family } from './Enforcement.js';
+import { type NetworkInterface } from './NetworkInterface.js';
+/**
+ * The options of `createUDPSocket()`.
+ */
+export interface UDPSocketOptions {
+    /**
+     * The port. 0: one the system chooses, kept when the socket is bound again.
+     */
+    port: number;
+    /**
+     * The families: `'IPv4'`, `'IPv6'` or `'both'` (by default, a socket of each family inside). With `'both'`, a system
+     * without IPv6 is bound in IPv4.
+     */
+    family?: 'IPv4' | 'IPv6' | 'both';
+    /**
+     * `true`: refused (a `NetIfNotEnforcedException`) where the system cannot refuse the datagrams reaching the addresses
+     * of the interface through another interface, and stopped while that guarantee is lost. `false` by default.
+     */
+    strict?: boolean;
+}
+/**
+ * The events of an `InterfaceUDPSocket` and their arguments.
+ */
+export interface InterfaceUDPSocketEvents {
+    /**
+     * A datagram received: its content, and where it came from (as `dgram` gives it).
+     */
+    message: [message: Buffer, remote: RemoteInfo];
+    /**
+     * The interface is bound, after `createUDPSocket()` and each time it is bound again (an address added, the interface
+     * plugged back).
+     */
+    listening: [];
+    /**
+     * An error of a binding again, retried a little later, or of a socket; with `strict`, the guarantee lost (a
+     * `NetIfNotEnforcedException`). Without a listener of `error`, the error is thrown, as for a `dgram` socket.
+     */
+    error: [error: Error];
+    /**
+     * Whether the datagrams coming through another interface are refused changed: its new value.
+     */
+    enforced: [enforced: boolean];
+    /**
+     * The socket was closed.
+     */
+    close: [];
+}
+/**
+ * A UDP socket of a network interface: `NetworkInterface.createUDPSocket()`. Its methods and events are the ones of a
+ * `dgram` socket. On Linux its sockets (one by family) are bound to the interface: they receive what comes through it,
+ * its broadcasts and the multicast of the groups joined there, whatever its addresses, and send through it. On Windows
+ * and macOS a socket is bound to each address of the interface, again when they change. The datagrams that arrive while
+ * the socket is bound again are lost (UDP never guarantees their delivery).
+ * @example
+ * ```typescript
+ * import {type InterfaceUDPSocket, NetworkInterface} from '@lakutata/netif'
+ *
+ * const lan: NetworkInterface = new NetworkInterface('eth1')
+ * const socket: InterfaceUDPSocket = await lan.createUDPSocket({port: 5353})
+ * socket.addMembership('224.0.0.251')
+ * socket.on('message', (message, remote) => console.log(`${remote.address}:${remote.port}`, message.length))
+ * socket.send('hello', 5353, '224.0.0.251')
+ * ```
+ */
+export declare class InterfaceUDPSocket extends Attachment<InterfaceUDPSocketEvents, Socket> {
+    #private;
+    protected readonly stream: boolean;
+    /**
+     * Internal: made by `NetworkInterface.createUDPSocket()`; `start()` binds it.
+     * @param networkInterface The interface.
+     * @param options The options of `createUDPSocket()`.
+     * @param ownsInterface Whether the interface is closed with the socket.
+     */
+    constructor(networkInterface: NetworkInterface, options: UDPSocketOptions, ownsInterface?: boolean);
+    protected openHandle(target: Target, family: Family): Promise<Socket>;
+    protected portOf(handle: Socket): number | undefined;
+    protected closeHandle(handle: Socket): void;
+    /**
+     * A socket made: the broadcasts and the groups of the socket applied to it
+     */
+    protected prepare(endpoint: Endpoint<Socket>): void;
+    /**
+     * A socket closed: the groups it joined for its family joined by another one
+     */
+    protected released(endpoint: Endpoint<Socket>): void;
+    /**
+     * Sends a datagram through the interface, from the socket of the family of the address (from the address of the
+     * interface in the network of the destination, where its addresses are bound).
+     * @param message The content.
+     * @param port The port of the destination.
+     * @param address The address of the destination (a broadcast address with `setBroadcast(true)`, a multicast group).
+     * @param callback Called once it is sent, with the error if it could not be; without it, the error is an `error`
+     * event.
+     */
+    send(message: string | Uint8Array, port: number, address: string, callback?: (error: Error | null, bytes?: number) => void): void;
+    /**
+     * Whether the datagrams may be sent to broadcast addresses (`SO_BROADCAST`), kept when the socket is bound again.
+     * Where the addresses are bound (macOS, and Linux without the permission to bind to the interface) the broadcasts can
+     * be sent, not received.
+     * @param flag Whether they may.
+     */
+    setBroadcast(flag: boolean): void;
+    /**
+     * Joins a multicast group on the interface, kept when the socket is bound again: its datagrams are received.
+     * @param group The address of the group: `'224.0.0.251'`, `'ff02::fb'`.
+     * @throws NetIfNotSupportedException Where the addresses are bound on macOS and Linux: a socket bound to an address
+     * receives no multicast.
+     * @throws NetIfException The system refused, its code as `errno`.
+     */
+    addMembership(group: string): void;
+    /**
+     * Leaves a multicast group joined.
+     * @param group The address of the group.
+     */
+    dropMembership(group: string): void;
+}

package/dist/types/lib/Internal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The key of the internal method of a NetworkInterface its listeners follow it by: the observer given is called with
+ * 'update' after each reading of the interfaces, with 'close' when the NetworkInterface is closed; the function returned
+ * removes it
+ */
+export declare const OBSERVE: unique symbol;
+/**
+ * An observer of a NetworkInterface
+ */
+export type Observer = (event: 'update' | 'close') => void;

package/dist/types/lib/Native.d.ts

@@ -0,0 +1,54 @@
+/**
+ * An address of an interface as the addon reads it: `tentative` while an IPv6 address is in its duplicate address
+ * detection (not usable yet)
+ */
+export interface NativeAddress {
+    address: string;
+    family: 'IPv4' | 'IPv6';
+    prefixLength: number;
+    tentative: boolean;
+    scopeid?: number;
+}
+/**
+ * An interface as the addon reads it
+ */
+export interface NativeInterface {
+    name: string;
+    index: number;
+    mac?: string;
+    up: boolean;
+    running: boolean;
+    loopback: boolean;
+    addresses: NativeAddress[];
+}
+/**
+ * The interfaces of the machine as the addon reads them
+ */
+export declare function nativeList(): NativeInterface[];
+/**
+ * Starts the notifications of the changes of the interfaces: changed() called at each one (once by thread)
+ */
+export declare function nativeWatch(changed: () => void): void;
+/**
+ * Stops the notifications
+ */
+export declare function nativeUnwatch(): void;
+/**
+ * A socket bound to the interface of the name (Linux): its descriptor and port
+ */
+export declare function nativeBindSocket(name: string, family: 4 | 6, stream: boolean, port: number, backlog: number): {
+    fd: number;
+    port: number;
+};
+/**
+ * The socket of the descriptor joins or leaves the multicast group on the interface of the index (Linux)
+ */
+export declare function nativeMembership(fd: number, group: string, index: number, join: boolean): void;
+/**
+ * The setting that makes the system accept, through another interface, the packets for the addresses of the interface of
+ * the index; null when it refuses them (the strong host model of Windows and macOS)
+ */
+export declare function nativeWeakReception(index: number, family: 4 | 6): {
+    interface: string;
+    setting: string;
+} | null;