@lakutata/netif 0.0.0-stage → 3.1.4

package/dist/cjs/lib/Native.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeList = nativeList;
+exports.nativeWatch = nativeWatch;
+exports.nativeUnwatch = nativeUnwatch;
+exports.nativeBindSocket = nativeBindSocket;
+exports.nativeMembership = nativeMembership;
+exports.nativeWeakReception = nativeWeakReception;
+const node_util_1 = require("node:util");
+const Addon_js_1 = require("./Addon.js");
+const NetIfException_js_1 = require("../exceptions/NetIfException.js");
+/**
+ * The error of a call of the addon as an exception of the package: the code of the error of the system as its `errno`
+ * (the name of the POSIX error, the number of the Windows one)
+ */
+function exception(error) {
+    if (!(error instanceof Error))
+        return new NetIfException_js_1.NetIfException(String(error));
+    const thrown = new NetIfException_js_1.NetIfException(error.message, { cause: error });
+    const number = error.errno;
+    if (typeof number === 'number') {
+        if (process.platform === 'win32') {
+            thrown.errno = number;
+        }
+        else {
+            try {
+                thrown.errno = (0, node_util_1.getSystemErrorName)(-number);
+            }
+            catch {
+                thrown.errno = number;
+            }
+        }
+    }
+    return thrown;
+}
+/**
+ * Calls a function of the addon, its errors turned into exceptions of the package
+ */
+function call(run) {
+    try {
+        return run(Addon_js_1.addon);
+    }
+    catch (error) {
+        throw exception(error);
+    }
+}
+/**
+ * The interfaces of the machine as the addon reads them
+ */
+function nativeList() {
+    return call((functions) => functions.list());
+}
+/**
+ * Starts the notifications of the changes of the interfaces: changed() called at each one (once by thread)
+ */
+function nativeWatch(changed) {
+    call((functions) => functions.watch(changed));
+}
+/**
+ * Stops the notifications
+ */
+function nativeUnwatch() {
+    call((functions) => functions.unwatch());
+}
+/**
+ * A socket bound to the interface of the name (Linux): its descriptor and port
+ */
+function nativeBindSocket(name, family, stream, port, backlog) {
+    return call((functions) => functions.bindSocket(name, family, stream, port, backlog));
+}
+/**
+ * The socket of the descriptor joins or leaves the multicast group on the interface of the index (Linux)
+ */
+function nativeMembership(fd, group, index, join) {
+    call((functions) => functions.membership(fd, group, index, join));
+}
+/**
+ * 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)
+ */
+function nativeWeakReception(index, family) {
+    return call((functions) => functions.weakReception(index, family));
+}

package/dist/cjs/lib/NetworkInterface.d.ts

@@ -0,0 +1,313 @@
+import { EventEmitter } from 'node:events';
+import { type Server } from 'node:net';
+import { InterfaceListener, type ListenOptions } from './InterfaceListener.js';
+import { InterfaceUDPSocket, type UDPSocketOptions } from './InterfaceUDPSocket.js';
+import { OBSERVE, type Observer } from './Internal.js';
+import { type InterfaceAddress, type NetworkInterfaceInfo } from './Types.js';
+/**
+ * How an interface is given: its name (`'eth1'`, `'en0'`, `'以太网 2'`), its hardware address (`{mac: '52:54:00:12:34:56'}`,
+ * the same on every system, the one to give a management port by) or its index (`{index: 3}`, which changes when the
+ * interface is unplugged and plugged again).
+ */
+export type InterfaceSelector = string | {
+    /**
+     * The hardware address: `'52:54:00:12:34:56'`, `'52-54-00-12-34-56'`, in either case.
+     */
+    mac: string;
+} | {
+    /**
+     * The index of the interface.
+     */
+    index: number;
+};
+/**
+ * A change of the addresses of an interface: the `change` event.
+ */
+export interface AddressChange {
+    /**
+     * Every usable address of the interface now.
+     */
+    addresses: InterfaceAddress[];
+    /**
+     * The addresses that came: added, or usable since (an IPv6 address once its duplicate address detection is over).
+     */
+    added: InterfaceAddress[];
+    /**
+     * The addresses that went.
+     */
+    removed: InterfaceAddress[];
+}
+/**
+ * The options of `waitForAddress()`.
+ */
+export interface WaitForAddressOptions {
+    /**
+     * The family of the address to wait for, any by default.
+     */
+    family?: 'IPv4' | 'IPv6';
+    /**
+     * The milliseconds to wait at most, without limit by default: then a `NetIfTimeoutException`.
+     */
+    timeout?: number;
+}
+/**
+ * The options of `bindSocket()`.
+ */
+export interface BindSocketOptions {
+    /**
+     * The port, 0 by default: one the system chooses (`port` of the result).
+     */
+    port?: number;
+    /**
+     * The family of the socket, `'IPv4'` by default. An IPv6 socket is IPv6 only.
+     */
+    family?: 'IPv4' | 'IPv6';
+    /**
+     * `'tcp'` (a listening socket, by default) or `'udp'`.
+     */
+    type?: 'tcp' | 'udp';
+    /**
+     * The length of the queue of the connections not accepted yet of a TCP socket, 511 by default.
+     */
+    backlog?: number;
+}
+/**
+ * A socket bound to an interface: `bindSocket()`.
+ */
+export interface BoundSocket {
+    /**
+     * Its file descriptor, to give to `server.listen({fd})` (a `net.Server`) or `socket.bind({fd})` (a `dgram` socket),
+     * which then own it; closed by `fs.closeSync(fd)` when it is not given.
+     */
+    fd: number;
+    /**
+     * Its port.
+     */
+    port: number;
+    /**
+     * Its family.
+     */
+    family: 'IPv4' | 'IPv6';
+    /**
+     * Its type.
+     */
+    type: 'tcp' | 'udp';
+}
+/**
+ * The events of a `NetworkInterface` and their arguments.
+ */
+export interface NetworkInterfaceEvents {
+    /**
+     * The addresses changed (some added, some removed).
+     */
+    change: [change: AddressChange];
+    /**
+     * The link came up: a cable plugged in, an association made.
+     */
+    up: [];
+    /**
+     * The link went down.
+     */
+    down: [];
+    /**
+     * The interface appeared: plugged, created, enabled (on Windows).
+     */
+    added: [];
+    /**
+     * The interface disappeared.
+     */
+    removed: [];
+}
+/**
+ * What changed between two states of an interface: whether it appeared or disappeared, its link came up or went down,
+ * and its addresses added and removed
+ */
+export declare function changesOf(previous: NetworkInterfaceInfo | undefined, next: NetworkInterfaceInfo | undefined): {
+    appeared: boolean;
+    disappeared: boolean;
+    up: boolean;
+    down: boolean;
+    added: InterfaceAddress[];
+    removed: InterfaceAddress[];
+};
+/**
+ * A network interface of the machine, followed: its state and addresses now, events when they change, and the servers
+ * listening on it. The interface may not exist yet (a USB adapter not plugged in, a system starting): the object follows
+ * it once it appears, and again when it is unplugged and plugged back.
+ * @example
+ * ```typescript
+ * import {type InterfaceAddress, NetworkInterface} from '@lakutata/netif'
+ *
+ * const management: NetworkInterface = new NetworkInterface('eth1')
+ * console.log(management.present, management.running, management.addresses.map(address => address.address))
+ * management.on('change', ({added, removed}) => console.log('added', added, 'removed', removed))
+ * management.on('down', () => console.log('the cable of eth1 is unplugged'))
+ * const address: InterfaceAddress = await management.waitForAddress({family: 'IPv4', timeout: 30000})
+ * console.log(`http://${address.address}:8080`)
+ * management.close()
+ * ```
+ */
+export declare class NetworkInterface extends EventEmitter<NetworkInterfaceEvents> {
+    #private;
+    /**
+     * How the interface was given.
+     */
+    readonly selector: InterfaceSelector;
+    /**
+     * Follows an interface.
+     * @param selector Its name, `{mac}` or `{index}`.
+     * @throws NetIfNotFoundException An index that no interface has (an index is never given again once its interface is
+     * gone), or a hardware address that several interfaces have now (a bridge and its ports: give the name then).
+     */
+    constructor(selector: InterfaceSelector);
+    /**
+     * The network interfaces of the machine, as `listInterfaces()` gives them.
+     * @returns The interfaces, in the order of the system.
+     * @example
+     * ```typescript
+     * import {NetworkInterface} from '@lakutata/netif'
+     *
+     * const names: string[] = NetworkInterface.list().map(entry => entry.name)
+     * ```
+     */
+    static list(): NetworkInterfaceInfo[];
+    /**
+     * Whether the interface exists now.
+     */
+    get present(): boolean;
+    /**
+     * Its name, `undefined` while it does not exist.
+     */
+    get name(): string | undefined;
+    /**
+     * Its index, `undefined` while it does not exist. It changes when the interface is unplugged and plugged again.
+     */
+    get index(): number | undefined;
+    /**
+     * Its hardware address, `undefined` while it does not exist or when it has none (and on the macOS versions that hide
+     * it).
+     */
+    get mac(): string | undefined;
+    /**
+     * Whether it is enabled (its administrative state); `false` while it does not exist.
+     */
+    get up(): boolean;
+    /**
+     * Whether its link is up (a cable plugged in, an association made); `false` while it does not exist.
+     */
+    get running(): boolean;
+    /**
+     * Whether it is the loopback interface.
+     */
+    get loopback(): boolean;
+    /**
+     * Its usable addresses now, an empty array when it has none or does not exist.
+     */
+    get addresses(): InterfaceAddress[];
+    /**
+     * Its state now as `listInterfaces()` gives it, `undefined` while it does not exist.
+     */
+    get info(): NetworkInterfaceInfo | undefined;
+    /**
+     * Whether the object was closed.
+     */
+    get closed(): boolean;
+    /**
+     * An address of the interface: one it has now, or the first one it gets.
+     * @param options The family of the address and the milliseconds to wait at most.
+     * @returns The address.
+     * @throws NetIfTimeoutException No address came in time.
+     * @throws NetIfException The object was closed while waiting.
+     * @example
+     * ```typescript
+     * import {type InterfaceAddress, NetworkInterface} from '@lakutata/netif'
+     *
+     * const wan: NetworkInterface = new NetworkInterface('eth0')
+     * const address: InterfaceAddress = await wan.waitForAddress({family: 'IPv4', timeout: 60000})
+     * wan.close()
+     * ```
+     */
+    waitForAddress(options?: WaitForAddressOptions): Promise<InterfaceAddress>;
+    /**
+     * Listens on the interface for the server: its connections are accepted by the listener returned and given to the
+     * server, which handles them as its own. On Linux the sockets are bound to the interface (whatever its addresses, the
+     * system refuses the connections coming through another interface); on Windows and macOS each address of the
+     * interface is listened on, and listened on again when they change (`enforced` tells whether the system refuses the
+     * connections coming through another interface). The interface may not exist yet, nor have an address: it is listened
+     * on once it can be, and again when it is unplugged and plugged back.
+     * @param server A `net.Server` or a server built on one: `http`, `https`, `http2`, `tls`; for Express
+     * `createServer(app)`, for Fastify `fastify.server`. The server itself must not listen.
+     * @param options The port, the families, `strict` and the backlog.
+     * @returns The listener, once the interface is listened on (or waited for).
+     * @throws NetIfNotEnforcedException With `strict`, where the system cannot refuse the connections coming through
+     * another interface.
+     * @throws NetIfException The system refused the first listening, its code as `errno` (`'EADDRINUSE'`, `'EACCES'`…).
+     * Later refusals are `error` events of the listener, and retried.
+     * @example
+     * ```typescript
+     * import {createServer} from 'node:http'
+     * import express from 'express'
+     * import {type InterfaceListener, NetworkInterface} from '@lakutata/netif'
+     *
+     * const app = express()
+     * app.get('/', (request, response) => response.send('ok'))
+     * const management: NetworkInterface = new NetworkInterface({mac: '52:54:00:12:34:56'})
+     * const listener: InterfaceListener = await management.listen(createServer(app), {port: 8080})
+     * listener.on('error', error => console.error(error))
+     * ```
+     */
+    listen(server: Server, options: ListenOptions): Promise<InterfaceListener>;
+    /**
+     * A UDP socket of the interface, with the methods and the events of a `dgram` socket. On Linux it is bound to the
+     * interface: it receives what comes through it, broadcasts and the multicast of the groups joined there included,
+     * whatever its addresses. On Windows and macOS a socket is bound to each address of the interface (on macOS it
+     * receives no broadcast nor multicast then). It is bound again when the addresses change and when the interface is
+     * plugged back.
+     * @param options The port, the families and `strict`.
+     * @returns The socket, once it is bound (or the interface waited for).
+     * @throws NetIfNotEnforcedException With `strict`, where the system cannot refuse the datagrams coming through
+     * another interface.
+     * @throws NetIfException The system refused the first binding, its code as `errno`.
+     * @example
+     * ```typescript
+     * import {type InterfaceUDPSocket, NetworkInterface} from '@lakutata/netif'
+     *
+     * const socket: InterfaceUDPSocket = await new NetworkInterface('eth1').createUDPSocket({port: 9999, family: 'IPv4'})
+     * socket.setBroadcast(true)
+     * socket.on('message', (message, remote) => socket.send(message, remote.port, remote.address))
+     * ```
+     */
+    createUDPSocket(options: UDPSocketOptions): Promise<InterfaceUDPSocket>;
+    /**
+     * A socket bound to the interface (Linux, `SO_BINDTODEVICE`), on the port of every address of its family: it gets the
+     * connections and the datagrams that come through the interface, whatever the address they were sent to, and the
+     * system refuses the other ones. For the users that need the server itself listening (its `address()` and `close()`
+     * as usual): the socket is not made again when the interface is unplugged and plugged back, which `listen()` does.
+     * In Bun, give the descriptor to a `net.Server` or a `dgram` socket (Bun's `http.Server` does not listen on one).
+     * @param options The port, the family, the type and the backlog.
+     * @returns The descriptor of the socket and its port.
+     * @throws NetIfNotSupportedException Outside Linux: macOS and Windows have no socket bound to an interface.
+     * @throws NetIfNotFoundException The interface does not exist now.
+     * @throws NetIfNotEnforcedException The process may not bind a socket to an interface (CAP_NET_RAW before Linux 5.7).
+     * @throws NetIfException Another refusal of the system, its code as `errno` (`'EADDRINUSE'`…).
+     * @example
+     * ```typescript
+     * import {createServer} from 'node:http'
+     * import {type BoundSocket, NetworkInterface} from '@lakutata/netif'
+     *
+     * const management: NetworkInterface = new NetworkInterface('eth1')
+     * const socket: BoundSocket = management.bindSocket({port: 8080, family: 'IPv4', type: 'tcp'})
+     * createServer((request, response) => response.end('ok')).listen({fd: socket.fd})
+     * ```
+     */
+    bindSocket(options?: BindSocketOptions): BoundSocket;
+    /**
+     * Stops following the interface: no event any more; its listeners are closed, the waits of `waitForAddress()`
+     * rejected.
+     */
+    close(): void;
+    /**
+     * Internal: follows the readings of the interfaces (the listeners of the interface)
+     */
+    [OBSERVE](observer: Observer): () => void;
+}