@lakutata/netif 0.0.0-stage → 3.1.5

package/dist/cjs/lib/Types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/exceptions/NetIfException.js

@@ -0,0 +1,20 @@
+/**
+ * The base of the exceptions of the package: catch it for any of them. Its `errno` is the code of the error of the
+ * system (`'EADDRINUSE'`, `'EACCES'`…) when the system refused something, `'E_NETIF'` for an error of the package, the
+ * one of the subclass otherwise; its `name` is the name of its class.
+ */
+export class NetIfException extends Error {
+    /**
+     * An exception of a message.
+     * @param message The message.
+     * @param options The error that caused it (`cause`).
+     */
+    constructor(message, options) {
+        super(message, options);
+        /**
+         * `'E_NETIF'`, the code of the error of the system, or the one of the subclass.
+         */
+        this.errno = 'E_NETIF';
+        this.name = new.target.name;
+    }
+}

package/dist/esm/exceptions/NetIfNotEnforcedException.js

@@ -0,0 +1,15 @@
+import { NetIfException } from './NetIfException.js';
+/**
+ * A listening with `strict: true` that the system cannot guarantee: the connections and the datagrams reaching the
+ * addresses of the interface through another interface would not be refused. Its message tells why (the system, the
+ * interface and its setting, the permission missing) and what to do. Its `errno` is `'E_NETIF_NOT_ENFORCED'`.
+ */
+export class NetIfNotEnforcedException extends NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_NOT_ENFORCED'`.
+         */
+        this.errno = 'E_NETIF_NOT_ENFORCED';
+    }
+}

package/dist/esm/exceptions/NetIfNotFoundException.js

@@ -0,0 +1,15 @@
+import { NetIfException } from './NetIfException.js';
+/**
+ * A network interface that cannot be found: an interface given by an index that does not exist (an index is never
+ * given again once its interface is gone), or a hardware address that several interfaces have (a bridge and its ports).
+ * Its `errno` is `'E_NETIF_NOT_FOUND'`.
+ */
+export class NetIfNotFoundException extends NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_NOT_FOUND'`.
+         */
+        this.errno = 'E_NETIF_NOT_FOUND';
+    }
+}

package/dist/esm/exceptions/NetIfNotSupportedException.js

@@ -0,0 +1,15 @@
+import { NetIfException } from './NetIfException.js';
+/**
+ * An operation the system, or the way the interface is listened on, cannot do: `bindSocket()` outside Linux, the
+ * broadcasts and the multicast of a UDP socket bound to the addresses of an interface on Linux and macOS. Its `errno` is
+ * `'E_NETIF_NOT_SUPPORTED'`.
+ */
+export class NetIfNotSupportedException extends NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_NOT_SUPPORTED'`.
+         */
+        this.errno = 'E_NETIF_NOT_SUPPORTED';
+    }
+}

package/dist/esm/exceptions/NetIfTimeoutException.js

@@ -0,0 +1,14 @@
+import { NetIfException } from './NetIfException.js';
+/**
+ * A wait that ended before what it waited for happened: `waitForAddress()` whose interface got no address in time.
+ * Its `errno` is `'E_NETIF_TIMEOUT'`.
+ */
+export class NetIfTimeoutException extends NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_TIMEOUT'`.
+         */
+        this.errno = 'E_NETIF_TIMEOUT';
+    }
+}

package/dist/esm/exports/Netif.js

@@ -0,0 +1,9 @@
+export { NetIfException } from '../exceptions/NetIfException.js';
+export { NetIfNotFoundException } from '../exceptions/NetIfNotFoundException.js';
+export { NetIfTimeoutException } from '../exceptions/NetIfTimeoutException.js';
+export { NetIfNotEnforcedException } from '../exceptions/NetIfNotEnforcedException.js';
+export { NetIfNotSupportedException } from '../exceptions/NetIfNotSupportedException.js';
+export { listenOn, listenOnAll, listInterfaces } from '../lib/Functions.js';
+export { InterfaceListener } from '../lib/InterfaceListener.js';
+export { NetworkInterface } from '../lib/NetworkInterface.js';
+export { InterfaceUDPSocket } from '../lib/InterfaceUDPSocket.js';

package/dist/esm/lib/Addon.js

@@ -0,0 +1,10 @@
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+let loaded;
+try {
+    loaded = createRequire(import.meta.url)(fileURLToPath(new URL('../../../build/Release/netif.node', import.meta.url)));
+} catch (error) {
+    if (error?.code === 'MODULE_NOT_FOUND') throw new Error("The addon of @lakutata/netif (build/Release/netif.node) is not built: the install script of the package did not run. Bun and pnpm run it only for the dependencies they trust (trustedDependencies in the package.json for Bun, pnpm approve-builds for pnpm): allow it, then install again or run npm rebuild @lakutata/netif.", {cause: error});
+    throw error;
+}
+export const addon = loaded;

package/dist/esm/lib/Attachment.js

@@ -0,0 +1,410 @@
+import { EventEmitter } from 'node:events';
+import { closeSync } from 'node:fs';
+import { NetIfNotEnforcedException } from '../exceptions/NetIfNotEnforcedException.js';
+import { addressEnforcement, LINUX_PERMISSION } from './Enforcement.js';
+import { OBSERVE } from './Internal.js';
+import { nativeBindSocket } from './Native.js';
+const RETRY_FIRST = 1000;
+const RETRY_LAST = 30000;
+//A port 0 shared by the sockets of the families: chosen by the first one, taken by another program for the next one
+const PORT_ATTEMPTS = 3;
+/**
+ * The code of the error of the system an error carries
+ */
+export function codeOf(error) {
+    return error?.code ?? error?.errno;
+}
+/**
+ * Whether an error is the one of an address gone or not usable yet: the next reading of the interfaces settles it
+ */
+function vanished(error) {
+    const code = codeOf(error);
+    return code === 'EADDRNOTAVAIL' || code === 'ENODEV' || code === 'ENXIO';
+}
+/**
+ * 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 class Attachment extends EventEmitter {
+    #requestedPort;
+    #endpoints = new Map();
+    #ownsInterface;
+    #port;
+    //Linux: the sockets bound to the interface until the process may not (then by address)
+    #bound = process.platform === 'linux';
+    #enforcement;
+    #paused = false;
+    #closed = false;
+    #stopObserving;
+    #syncing = Promise.resolve();
+    #again = false;
+    #retry;
+    #retryDelay = RETRY_FIRST;
+    #alive;
+    /**
+     * 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.
+     */
+    constructor(networkInterface, options, ownsInterface) {
+        super();
+        if (!Number.isInteger(options?.port) || options.port < 0 || options.port > 65535)
+            throw new TypeError(`${String(options?.port)} is not a port`);
+        const family = options.family ?? 'both';
+        if (!['IPv4', 'IPv6', 'both'].includes(family))
+            throw new TypeError(`${String(family)} is not a family ('IPv4', 'IPv6' or 'both')`);
+        this.networkInterface = networkInterface;
+        this.families = family === 'both' ? ['IPv4', 'IPv6'] : [family];
+        this.strict = options.strict ?? false;
+        this.#requestedPort = options.port;
+        this.#port = options.port || undefined;
+        this.#ownsInterface = ownsInterface;
+        this.#enforcement = this.#enforcementNow();
+    }
+    /**
+     * 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() {
+        return this.#enforcement.enforced;
+    }
+    /**
+     * Why what comes through another interface is not refused, `undefined` while it is.
+     */
+    get reason() {
+        return this.#enforcement.reason;
+    }
+    /**
+     * The port, `undefined` until a port 0 was given one by the system.
+     */
+    get port() {
+        return this.#port;
+    }
+    /**
+     * Whether the interface is listened on now (it exists, and has an address where its addresses are listened on).
+     */
+    get listening() {
+        return this.#endpoints.size > 0;
+    }
+    /**
+     * 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() {
+        if (this.#port === undefined || !this.#endpoints.size)
+            return [];
+        const families = new Set([...this.#endpoints.values()].map((endpoint) => endpoint.family));
+        const addresses = this.#bound
+            ? this.networkInterface.addresses.filter((address) => families.has(address.family))
+            : [...this.#endpoints.values()].map((endpoint) => endpoint.address);
+        return addresses.map((address) => {
+            const listening = { address: address.address, family: address.family, port: this.#port };
+            if (address.family === 'IPv6')
+                listening.scopeid = address.scopeid ?? 0;
+            return listening;
+        });
+    }
+    /**
+     * Whether it was closed.
+     */
+    get closed() {
+        return this.#closed;
+    }
+    /**
+     * Whether the sockets are bound to the interface (Linux), not to its addresses
+     */
+    get boundToInterface() {
+        return this.#bound;
+    }
+    /**
+     * The sockets now
+     */
+    endpoints() {
+        return [...this.#endpoints.values()];
+    }
+    /**
+     * A socket made, before it is counted (its settings applied: the broadcasts, the multicast groups)
+     */
+    prepare(_endpoint) {
+        //Nothing by default
+    }
+    /**
+     * A socket closed, no longer counted
+     */
+    released(_endpoint) {
+        //Nothing by default
+    }
+    /**
+     * Internal: the first binding, which the method that made it waits for.
+     * @returns It.
+     */
+    async start() {
+        if (this.strict && !this.#enforcement.enforced) {
+            this.#finish();
+            throw new NetIfNotEnforcedException(`The interface cannot be listened on strictly: ${this.#enforcement.reason}`);
+        }
+        this.#stopObserving = this.networkInterface[OBSERVE]((event) => {
+            if (event === 'close') {
+                void this.close();
+                return;
+            }
+            this.#sync();
+        });
+        try {
+            await this.#enqueue(() => this.#reconcile(true));
+        }
+        catch (error) {
+            this.#finish();
+            throw error;
+        }
+        if (this.strict && !this.#enforcement.enforced) {
+            this.#finish();
+            throw new NetIfNotEnforcedException(`The interface cannot be listened on strictly: ${this.#enforcement.reason}`);
+        }
+        this.#keepAlive();
+        return this;
+    }
+    /**
+     * Stops: the sockets closed (the listener does not wait for the connections established, which are left to the
+     * server).
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#finish();
+        if (this.#ownsInterface)
+            this.networkInterface.close();
+        this.#emit('close');
+    }
+    #emit(event, ...args) {
+        this.emit(event, ...args);
+    }
+    #finish() {
+        this.#closed = true;
+        this.#stopObserving?.();
+        this.#stopObserving = undefined;
+        clearTimeout(this.#retry);
+        clearInterval(this.#alive);
+        this.#retry = undefined;
+        this.#alive = undefined;
+        this.#closeAll();
+    }
+    #closeAll() {
+        const endpoints = [...this.#endpoints.values()];
+        this.#endpoints.clear();
+        for (const endpoint of endpoints) {
+            this.closeHandle(endpoint.handle);
+            this.released(endpoint);
+        }
+    }
+    /**
+     * The interfaces were read again: the sockets made or closed to match them
+     */
+    #sync() {
+        if (this.#closed || this.#again)
+            return;
+        this.#again = true;
+        void this.#enqueue(async () => {
+            this.#again = false;
+            if (this.#closed)
+                return;
+            try {
+                await this.#reconcile(false);
+            }
+            catch (error) {
+                this.failed(error);
+            }
+            this.#keepAlive();
+        });
+    }
+    /**
+     * A reconciliation run after the ones queued: its promise (the queue goes on whatever its result)
+     */
+    #enqueue(task) {
+        const run = this.#syncing.then(task);
+        this.#syncing = run.catch(() => undefined);
+        return run;
+    }
+    /**
+     * While nothing is bound (the interface missing, no address, a retry pending), it keeps the process alive as a
+     * listening server does
+     */
+    #keepAlive() {
+        if (this.#closed || this.#endpoints.size) {
+            clearInterval(this.#alive);
+            this.#alive = undefined;
+        }
+        else if (!this.#alive) {
+            this.#alive = setInterval(() => undefined, 0x7fffffff);
+        }
+    }
+    /**
+     * An error of a binding again, or of a socket: the error event, the binding retried a little later
+     */
+    failed(error) {
+        if (this.#closed)
+            return;
+        this.#emit('error', error);
+        if (this.#retry)
+            return;
+        this.#retry = setTimeout(() => {
+            this.#retry = undefined;
+            this.#sync();
+        }, this.#retryDelay);
+        this.#retryDelay = Math.min(this.#retryDelay * 2, RETRY_LAST);
+    }
+    #enforcementNow() {
+        if (this.#bound)
+            return { enforced: true };
+        return addressEnforcement(this.networkInterface.index ?? 0, this.families);
+    }
+    /**
+     * The guarantee read again: its event when it changed; with strict, the sockets closed while it is lost
+     */
+    #checkEnforcement() {
+        const now = this.#enforcementNow();
+        const changed = now.enforced !== this.#enforcement.enforced;
+        this.#enforcement = now;
+        if (!changed)
+            return;
+        this.#emit('enforced', now.enforced);
+        if (!this.strict)
+            return;
+        if (!now.enforced) {
+            this.#paused = true;
+            this.#closeAll();
+            this.#emit('error', new NetIfNotEnforcedException(`The listening stopped: ${now.reason}`));
+        }
+        else {
+            this.#paused = false;
+        }
+    }
+    #wanted(state) {
+        if (!state || this.#paused)
+            return [];
+        if (this.#bound)
+            return this.families.map((family) => ({ key: `bound|${family}|${state.index}`, family: family }));
+        return state.addresses
+            .filter((address) => this.families.includes(address.family))
+            .map((address) => ({ key: `address|${address.family}|${address.address}|${address.scopeid ?? ''}`, family: address.family, address: address }));
+    }
+    /**
+     * The sockets made and closed to match the interface; on the first time an error is thrown, later it is retried
+     */
+    async #reconcile(first) {
+        this.#checkEnforcement();
+        for (let attempt = 1;; attempt++) {
+            const state = this.networkInterface.info;
+            const wanted = this.#wanted(state);
+            const keys = new Set(wanted.map((entry) => entry.key));
+            for (const [key, endpoint] of [...this.#endpoints]) {
+                if (keys.has(key))
+                    continue;
+                this.closeHandle(endpoint.handle);
+                this.#endpoints.delete(key);
+                this.released(endpoint);
+            }
+            let opened = false;
+            let byAddress = false;
+            try {
+                for (const entry of wanted) {
+                    if (this.#closed)
+                        return;
+                    if (this.#endpoints.has(entry.key))
+                        continue;
+                    const result = await this.#open(entry, state);
+                    if (result === 'opened')
+                        opened = true;
+                    if (result === 'by address') {
+                        byAddress = true;
+                        break;
+                    }
+                }
+            }
+            catch (error) {
+                //A port 0 the system gave the first socket, taken for the next one: all of them again on another port
+                if (codeOf(error) === 'EADDRINUSE' && !this.#requestedPort && this.#endpoints.size && attempt < PORT_ATTEMPTS && first) {
+                    this.#closeAll();
+                    this.#port = undefined;
+                    continue;
+                }
+                throw error;
+            }
+            //Linux without the permission to bind to the interface: the addresses bound instead, at once
+            if (byAddress)
+                continue;
+            this.#retryDelay = RETRY_FIRST;
+            if (opened)
+                this.#emit('listening');
+            return;
+        }
+    }
+    async #open(entry, state) {
+        let handle;
+        if (this.#bound) {
+            let bound;
+            try {
+                bound = nativeBindSocket(state.name, entry.family === 'IPv4' ? 4 : 6, this.stream, this.#port ?? 0, 511);
+            }
+            catch (error) {
+                const code = codeOf(error);
+                if (code === 'EPERM' || code === 'EACCES') {
+                    //Linux before 5.7 without CAP_NET_RAW: by address, without the guarantee
+                    if (this.strict)
+                        throw new NetIfNotEnforcedException(`The process may not bind a socket to ${state.name}. ${LINUX_PERMISSION}`, { cause: error });
+                    this.#bound = false;
+                    this.#closeAll();
+                    this.#enforcement = { enforced: false, reason: LINUX_PERMISSION };
+                    this.#emit('enforced', false);
+                    return 'by address';
+                }
+                //IPv6 off in the system: IPv4 only for 'both'
+                if (code === 'EAFNOSUPPORT' && this.families.length > 1)
+                    return 'skipped';
+                if (vanished(error))
+                    return 'skipped';
+                throw error;
+            }
+            try {
+                handle = await this.openHandle({ fd: bound.fd }, entry.family);
+            }
+            catch (error) {
+                try {
+                    closeSync(bound.fd);
+                }
+                catch {
+                    //Owned by the socket already
+                }
+                throw error;
+            }
+        }
+        else {
+            const address = entry.address;
+            //An IPv6 address with its scope: the index on Windows, the name of the interface elsewhere (libuv)
+            const scope = address.family === 'IPv6' && address.scopeid ? `%${process.platform === 'win32' ? address.scopeid : state.name}` : '';
+            try {
+                handle = await this.openHandle({ host: `${address.address}${scope}`, port: this.#port ?? 0 }, entry.family);
+            }
+            catch (error) {
+                if (vanished(error))
+                    return 'skipped';
+                throw error;
+            }
+        }
+        if (this.#closed) {
+            this.closeHandle(handle);
+            return 'skipped';
+        }
+        if (this.#port === undefined)
+            this.#port = this.portOf(handle);
+        const endpoint = { key: entry.key, family: entry.family, handle: handle, address: entry.address };
+        this.prepare(endpoint);
+        this.#endpoints.set(entry.key, endpoint);
+        return 'opened';
+    }
+}

package/dist/esm/lib/Enforcement.js

@@ -0,0 +1,41 @@
+import { nativeWeakReception } from './Native.js';
+/**
+ * Why a socket of Linux could not be bound to the interface
+ */
+export const LINUX_PERMISSION = 'Linux accepts the packets of an address through any interface, and binding a socket to an interface (SO_BINDTODEVICE) needs the capability CAP_NET_RAW before Linux 5.7: give it to the process (setcap cap_net_raw+ep on its executable, AmbientCapabilities=CAP_NET_RAW in its systemd unit) or run a newer kernel';
+/**
+ * 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 function addressEnforcement(index, families) {
+    if (process.platform !== 'win32' && process.platform !== 'darwin') {
+        if (process.platform === 'linux')
+            return { enforced: false, reason: LINUX_PERMISSION };
+        return { enforced: false, reason: `The interfaces of ${process.platform} are listened on by address, with no guarantee about the other interfaces` };
+    }
+    for (const family of families) {
+        const weak = nativeWeakReception(index, family === 'IPv4' ? 4 : 6);
+        if (!weak)
+            continue;
+        const version = family === 'IPv4' ? 'ipv4' : 'ipv6';
+        if (process.platform === 'win32') {
+            const setting = weak.setting === 'WeakHostReceive' ? 'weakhostreceive' : 'forwarding';
+            return {
+                enforced: false,
+                reason: `Windows accepts ${family} packets for the addresses of the interface through the interface "${weak.interface}": its ${weak.setting} is enabled. Disable it as an administrator: netsh interface ${version} set interface "${weak.interface}" ${setting}=disabled`
+            };
+        }
+        if (weak.setting.endsWith('forwarding')) {
+            return {
+                enforced: false,
+                reason: `macOS forwards ${family} (${weak.setting} is 1, as while a virtual machine or a container shares the network), and does not check the interface packets come through then`
+            };
+        }
+        return {
+            enforced: false,
+            reason: `macOS accepts the ${family} packets of an address through any interface (${weak.setting} is not 2). Make it refuse them: sudo sysctl -w ${weak.setting}=2, with forwarding off`
+        };
+    }
+    return { enforced: true };
+}

package/dist/esm/lib/Functions.js

@@ -0,0 +1,92 @@
+import { InterfaceListener } from './InterfaceListener.js';
+import { NetworkInterface } from './NetworkInterface.js';
+import { readInterfaces } from './Snapshot.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 function listInterfaces() {
+    return readInterfaces().interfaces;
+}
+/**
+ * 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 async function listenOn(selector, server, options) {
+    const networkInterface = new NetworkInterface(selector);
+    try {
+        return await new InterfaceListener(networkInterface, server, options, true).start();
+    }
+    catch (error) {
+        networkInterface.close();
+        throw error;
+    }
+}
+/**
+ * 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 async function listenOnAll(selectors, server, options) {
+    const list = Array.isArray(selectors) ? selectors : [selectors];
+    if (!list.length)
+        throw new TypeError('listenOnAll() takes an interface at least');
+    if (list.length > 1 && options?.port === 0)
+        throw new TypeError('Several interfaces need a port: 0 lets the system choose one for the first interface, which may not exist yet');
+    const listeners = [];
+    try {
+        for (const selector of list)
+            listeners.push(await listenOn(selector, server, options));
+    }
+    catch (error) {
+        await Promise.all(listeners.map((listener) => listener.close()));
+        throw error;
+    }
+    return listeners;
+}