@lakutata/netif 0.0.0-stage → 3.1.4

package/dist/cjs/lib/Attachment.js

@@ -0,0 +1,415 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Attachment = void 0;
+exports.codeOf = codeOf;
+const node_events_1 = require("node:events");
+const node_fs_1 = require("node:fs");
+const NetIfNotEnforcedException_js_1 = require("../exceptions/NetIfNotEnforcedException.js");
+const Enforcement_js_1 = require("./Enforcement.js");
+const Internal_js_1 = require("./Internal.js");
+const Native_js_1 = require("./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
+ */
+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.
+ */
+class Attachment extends node_events_1.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_js_1.NetIfNotEnforcedException(`The interface cannot be listened on strictly: ${this.#enforcement.reason}`);
+        }
+        this.#stopObserving = this.networkInterface[Internal_js_1.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_js_1.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 (0, Enforcement_js_1.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_js_1.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 = (0, Native_js_1.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_js_1.NetIfNotEnforcedException(`The process may not bind a socket to ${state.name}. ${Enforcement_js_1.LINUX_PERMISSION}`, { cause: error });
+                    this.#bound = false;
+                    this.#closeAll();
+                    this.#enforcement = { enforced: false, reason: Enforcement_js_1.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 {
+                    (0, node_fs_1.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';
+    }
+}
+exports.Attachment = Attachment;

package/dist/cjs/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/cjs/lib/Enforcement.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINUX_PERMISSION = void 0;
+exports.addressEnforcement = addressEnforcement;
+const Native_js_1 = require("./Native.js");
+/**
+ * Why a socket of Linux could not be bound to the interface
+ */
+exports.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
+ */
+function addressEnforcement(index, families) {
+    if (process.platform !== 'win32' && process.platform !== 'darwin') {
+        if (process.platform === 'linux')
+            return { enforced: false, reason: exports.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 = (0, Native_js_1.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/cjs/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/cjs/lib/Functions.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listInterfaces = listInterfaces;
+exports.listenOn = listenOn;
+exports.listenOnAll = listenOnAll;
+const InterfaceListener_js_1 = require("./InterfaceListener.js");
+const NetworkInterface_js_1 = require("./NetworkInterface.js");
+const Snapshot_js_1 = require("./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)
+ * ```
+ */
+function listInterfaces() {
+    return (0, Snapshot_js_1.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)
+ * ```
+ */
+async function listenOn(selector, server, options) {
+    const networkInterface = new NetworkInterface_js_1.NetworkInterface(selector);
+    try {
+        return await new InterfaceListener_js_1.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))
+ * ```
+ */
+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;
+}