@lakutata/netif 0.0.0-stage → 3.1.4

package/dist/esm/lib/InterfaceListener.js

@@ -0,0 +1,95 @@
+import { Server as HTTPServer } from 'node:http';
+import { createServer } from 'node:net';
+import { NetIfNotSupportedException } from '../exceptions/NetIfNotSupportedException.js';
+import { Attachment } from './Attachment.js';
+/**
+ * Bun 1.4: whether its http server is an https one (Bun's https.Server is its http.Server, which answers a connection
+ * given to it in plain HTTP even when it was made with keys: the connections of an https server cannot be given to it).
+ * An internal symbol tells: its TLS options, null for a plain server; undefined when Bun has no such symbol.
+ */
+function bunTLS(server) {
+    const symbol = Object.getOwnPropertySymbols(server).find((candidate) => candidate.description === 'tls');
+    if (!symbol)
+        return undefined;
+    return !!server[symbol];
+}
+/**
+ * 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 class InterfaceListener extends Attachment {
+    #backlog;
+    /**
+     * 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, server, options, ownsInterface = false) {
+        if (!server || typeof server.emit !== 'function')
+            throw new TypeError('listen() takes a net.Server (http, https, http2, tls…)');
+        if (process.versions.bun && server instanceof HTTPServer && bunTLS(server) !== false) {
+            throw new NetIfNotSupportedException(bunTLS(server)
+                ? 'The https server of Bun answers the connections given to it without TLS: in Bun, listen with http2.createSecureServer({key, cert, allowHTTP1: true}) or a tls.Server instead'
+                : 'Whether this server of Bun uses TLS cannot be told, and the https server of Bun answers the connections given to it without TLS: in Bun, listen with an http server of a known version, http2.createSecureServer() or a tls.Server');
+        }
+        super(networkInterface, options, ownsInterface);
+        this.stream = true;
+        this.server = server;
+        this.#backlog = options.backlog ?? 511;
+    }
+    /**
+     * Listens on the target: a server of the listener, the connections it accepts given to the server of the user
+     */
+    openHandle(target, _family) {
+        const settings = this.server;
+        const inner = createServer({ allowHalfOpen: !!settings.allowHalfOpen, pauseOnConnect: !!settings.pauseOnConnect, noDelay: true }, (socket) => {
+            this.server.emit('connection', socket);
+        });
+        if (typeof this.server.maxConnections === 'number')
+            inner.maxConnections = this.server.maxConnections;
+        return new Promise((resolve, reject) => {
+            const failed = (error) => {
+                inner.off('listening', listened);
+                inner.close();
+                reject(error);
+            };
+            const listened = () => {
+                inner.off('error', failed);
+                //Later errors of the socket: the ones of the listener
+                inner.on('error', (error) => this.failed(error));
+                resolve(inner);
+            };
+            inner.once('error', failed);
+            inner.once('listening', listened);
+            if ('fd' in target) {
+                inner.listen({ fd: target.fd, backlog: this.#backlog });
+            }
+            else {
+                inner.listen({ host: target.host, port: target.port, backlog: this.#backlog, exclusive: true });
+            }
+        });
+    }
+    portOf(handle) {
+        const address = handle.address();
+        return address && typeof address === 'object' ? address.port : undefined;
+    }
+    closeHandle(handle) {
+        handle.close();
+    }
+}

package/dist/esm/lib/InterfaceUDPSocket.js

@@ -0,0 +1,241 @@
+import { createSocket } from 'node:dgram';
+import { isIP } from 'node:net';
+import { NetIfException } from '../exceptions/NetIfException.js';
+import { NetIfNotSupportedException } from '../exceptions/NetIfNotSupportedException.js';
+import { Attachment } from './Attachment.js';
+import { nativeMembership } from './Native.js';
+/**
+ * Whether an IPv4 address is in the network of an address of the interface
+ */
+function sameNetwork(destination, address) {
+    const toNumber = (text) => text.split('.').reduce((value, part) => value * 256 + Number(part), 0);
+    const mask = toNumber(address.netmask);
+    return (toNumber(destination) & mask) >>> 0 === (toNumber(address.address) & mask) >>> 0 || destination === '255.255.255.255';
+}
+/**
+ * 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 class InterfaceUDPSocket extends Attachment {
+    #broadcast;
+    #groups;
+    #descriptors;
+    //By address: the socket of each family that joined the groups (on every socket, a datagram of a group would be
+    //received once by each of them)
+    #members;
+    /**
+     * 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, options, ownsInterface = false) {
+        super(networkInterface, options, ownsInterface);
+        this.stream = false;
+        this.#broadcast = false;
+        this.#groups = new Set();
+        this.#descriptors = new WeakMap();
+        //By address: the socket of each family that joined the groups (on every socket, a datagram of a group would be
+        //received once by each of them)
+        this.#members = new Map();
+    }
+    openHandle(target, family) {
+        const socket = createSocket({ type: family === 'IPv4' ? 'udp4' : 'udp6' });
+        return new Promise((resolve, reject) => {
+            const failed = (error) => {
+                try {
+                    socket.close();
+                }
+                catch {
+                    //Not bound
+                }
+                reject(error);
+            };
+            const bound = () => {
+                socket.off('error', failed);
+                socket.on('error', (error) => this.failed(error));
+                socket.on('message', (message, remote) => {
+                    this.emit('message', message, remote);
+                });
+                resolve(socket);
+            };
+            socket.once('error', failed);
+            if ('fd' in target) {
+                this.#descriptors.set(socket, target.fd);
+                socket.bind({ fd: target.fd }, bound);
+            }
+            else {
+                socket.bind({ address: target.host, port: target.port, exclusive: true }, bound);
+            }
+        });
+    }
+    portOf(handle) {
+        return handle.address().port;
+    }
+    closeHandle(handle) {
+        try {
+            handle.close();
+        }
+        catch {
+            //Closed already
+        }
+    }
+    /**
+     * A socket made: the broadcasts and the groups of the socket applied to it
+     */
+    prepare(endpoint) {
+        if (endpoint.family === 'IPv4' && this.#broadcast)
+            endpoint.handle.setBroadcast(true);
+        this.#join(endpoint);
+    }
+    /**
+     * A socket closed: the groups it joined for its family joined by another one
+     */
+    released(endpoint) {
+        if (this.#members.get(endpoint.family) !== endpoint)
+            return;
+        this.#members.delete(endpoint.family);
+        const next = this.endpoints().find((candidate) => candidate.family === endpoint.family);
+        if (next)
+            this.#join(next);
+    }
+    /**
+     * The groups of the family of a socket joined on it, unless another socket of the family has them already
+     */
+    #join(endpoint) {
+        if (this.#members.has(endpoint.family))
+            return;
+        this.#members.set(endpoint.family, endpoint);
+        for (const group of this.#groups) {
+            if ((isIP(group) === 4 ? 'IPv4' : 'IPv6') !== endpoint.family)
+                continue;
+            try {
+                this.#membership(endpoint, group, true);
+            }
+            catch (error) {
+                this.failed(error);
+            }
+        }
+    }
+    #membership(endpoint, group, join) {
+        if (this.boundToInterface) {
+            nativeMembership(this.#descriptors.get(endpoint.handle), group, this.networkInterface.index ?? 0, join);
+            return;
+        }
+        //Windows: the group on the interface of the address of the socket (IPv6: by the index of the interface)
+        const via = endpoint.family === 'IPv4' ? endpoint.address.address : `::%${this.networkInterface.index ?? 0}`;
+        if (join) {
+            endpoint.handle.addMembership(group, via);
+        }
+        else {
+            endpoint.handle.dropMembership(group, via);
+        }
+    }
+    /**
+     * 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, port, address, callback) {
+        const family = isIP(address.split('%')[0]) === 6 ? 'IPv6' : 'IPv4';
+        const endpoints = this.endpoints().filter((endpoint) => endpoint.family === family);
+        let chosen = endpoints[0];
+        if (!this.boundToInterface && endpoints.length > 1) {
+            if (family === 'IPv4') {
+                chosen = endpoints.find((endpoint) => sameNetwork(address, endpoint.address)) ?? chosen;
+            }
+            else {
+                const linkLocal = address.toLowerCase().startsWith('fe80:');
+                chosen = endpoints.find((endpoint) => endpoint.address.address.startsWith('fe80:') === linkLocal) ?? chosen;
+            }
+        }
+        if (!chosen) {
+            const error = new NetIfException(`No ${family} socket is bound to the interface now: it does not exist${this.boundToInterface ? '' : ` or has no ${family} address`}`);
+            if (callback) {
+                queueMicrotask(() => callback(error));
+            }
+            else {
+                queueMicrotask(() => {
+                    this.emit('error', error);
+                });
+            }
+            return;
+        }
+        chosen.handle.send(message, port, address, (error, bytes) => {
+            if (callback) {
+                callback(error, bytes);
+            }
+            else if (error) {
+                this.emit('error', error);
+            }
+        });
+    }
+    /**
+     * 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) {
+        this.#broadcast = flag;
+        for (const endpoint of this.endpoints()) {
+            if (endpoint.family === 'IPv4')
+                endpoint.handle.setBroadcast(flag);
+        }
+    }
+    /**
+     * 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) {
+        if (!isIP(group))
+            throw new TypeError(`${group} is not the address of a multicast group`);
+        if (!this.boundToInterface && process.platform !== 'win32') {
+            throw new NetIfNotSupportedException(`A UDP socket bound to the addresses of an interface receives no multicast on ${process.platform === 'darwin' ? 'macOS' : process.platform}: only Linux binds a socket to the interface itself`);
+        }
+        if (this.#groups.has(group))
+            return;
+        this.#groups.add(group);
+        const family = isIP(group) === 4 ? 'IPv4' : 'IPv6';
+        const member = this.#members.get(family);
+        if (member)
+            this.#membership(member, group, true);
+    }
+    /**
+     * Leaves a multicast group joined.
+     * @param group The address of the group.
+     */
+    dropMembership(group) {
+        if (!this.#groups.delete(group))
+            return;
+        const member = this.#members.get(isIP(group) === 4 ? 'IPv4' : 'IPv6');
+        if (!member)
+            return;
+        try {
+            this.#membership(member, group, false);
+        }
+        catch {
+            //Left already (the socket made again since)
+        }
+    }
+}

package/dist/esm/lib/Internal.js

@@ -0,0 +1,6 @@
+/**
+ * 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 const OBSERVE = Symbol('lakutata.netif.observe');

package/dist/esm/lib/Native.js

@@ -0,0 +1,75 @@
+import { getSystemErrorName } from 'node:util';
+import { addon } from './Addon.js';
+import { NetIfException } from '../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(String(error));
+    const thrown = new NetIfException(error.message, { cause: error });
+    const number = error.errno;
+    if (typeof number === 'number') {
+        if (process.platform === 'win32') {
+            thrown.errno = number;
+        }
+        else {
+            try {
+                thrown.errno = 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);
+    }
+    catch (error) {
+        throw exception(error);
+    }
+}
+/**
+ * The interfaces of the machine as the addon reads them
+ */
+export function nativeList() {
+    return call((functions) => functions.list());
+}
+/**
+ * Starts the notifications of the changes of the interfaces: changed() called at each one (once by thread)
+ */
+export function nativeWatch(changed) {
+    call((functions) => functions.watch(changed));
+}
+/**
+ * Stops the notifications
+ */
+export function nativeUnwatch() {
+    call((functions) => functions.unwatch());
+}
+/**
+ * A socket bound to the interface of the name (Linux): its descriptor and port
+ */
+export 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)
+ */
+export 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)
+ */
+export function nativeWeakReception(index, family) {
+    return call((functions) => functions.weakReception(index, family));
+}