@lakutata/netif 0.0.0-stage → 3.1.4

package/dist/types/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;
+}

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

@@ -0,0 +1,26 @@
+import { type NetworkInterfaceInfo } from './Types.js';
+/**
+ * A subscriber of the changes: called with the interfaces read after each change
+ */
+export type Subscriber = (interfaces: NetworkInterfaceInfo[]) => void;
+/**
+ * The interfaces of the machine as the package follows them: the notifications of the system shared by every
+ * subscriber of the thread, started with the first one and stopped with the last one. The timers do not keep the event
+ * loop alive.
+ */
+declare class Registry {
+    #private;
+    /**
+     * The interfaces read last while followed, read now otherwise
+     */
+    current(): NetworkInterfaceInfo[];
+    /**
+     * Follows the interfaces: the subscriber is called after each change; the function returned unsubscribes it
+     */
+    subscribe(subscriber: Subscriber): () => void;
+}
+/**
+ * The registry of the thread
+ */
+export declare const registry: Registry;
+export {};

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

@@ -0,0 +1,17 @@
+import { type NativeInterface } from './Native.js';
+import { type NetworkInterfaceInfo } from './Types.js';
+/**
+ * The mask of a prefix length: `'255.255.255.0'` for 24 in IPv4, `'ffff:ffff:ffff:ffff::'` for 64 in IPv6
+ */
+export declare function netmaskOf(family: 'IPv4' | 'IPv6', prefixLength: number): string;
+/**
+ * An interface read by the addon as an interface of the package: its usable addresses only
+ */
+export declare function interfaceOf(entry: NativeInterface): NetworkInterfaceInfo;
+/**
+ * The interfaces of the machine now, and whether some address is still tentative (to be read again soon)
+ */
+export declare function readInterfaces(): {
+    interfaces: NetworkInterfaceInfo[];
+    tentative: boolean;
+};

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

@@ -0,0 +1,63 @@
+/**
+ * An address of a network interface, written as `os.networkInterfaces()` writes it
+ */
+export interface InterfaceAddress {
+    /**
+     * The address: `'192.168.10.2'`, `'fd00::2'`, `'fe80::1c82:430f:35a3:800a'` (an IPv6 address without its scope).
+     */
+    address: string;
+    /**
+     * `'IPv4'` or `'IPv6'`.
+     */
+    family: 'IPv4' | 'IPv6';
+    /**
+     * The mask of the network of the address: `'255.255.255.0'`, `'ffff:ffff:ffff:ffff::'`.
+     */
+    netmask: string;
+    /**
+     * The address and the length of its prefix: `'192.168.10.2/24'`.
+     */
+    cidr: string;
+    /**
+     * IPv6 only: the scope of the address, as `os.networkInterfaces()` gives it: the index of the interface for a
+     * link-local address (`fe80::…`, written `fe80::…%<scopeid>` to be connected to), `0` for a global one (Windows gives
+     * a site-local address, `fec0::…`, the number of its site).
+     */
+    scopeid?: number;
+}
+/**
+ * A network interface of the machine and its state when it was read
+ */
+export interface NetworkInterfaceInfo {
+    /**
+     * The name of the interface: `'eth1'`, `'en0'`, on Windows the name of its network connection (`'以太网 2'`,
+     * `'Ethernet 2'`, in the language of the system).
+     */
+    name: string;
+    /**
+     * The index the system gives the interface. It changes when the interface is unplugged and plugged again.
+     */
+    index: number;
+    /**
+     * The hardware address (`'52:54:00:12:34:56'`), `undefined` for an interface without one (loopback, tunnels) and on
+     * the macOS versions that hide it from the processes (macOS 27 gives `02:00:00:00:00:00` for every interface).
+     */
+    mac?: string;
+    /**
+     * Whether the interface is enabled (its administrative state). On Windows a disabled adapter is not listed at all.
+     */
+    up: boolean;
+    /**
+     * Whether its link is up: a cable plugged in, an association made.
+     */
+    running: boolean;
+    /**
+     * Whether it is the loopback interface.
+     */
+    loopback: boolean;
+    /**
+     * Its usable addresses, an empty array when it has none. An IPv6 address still in its duplicate address detection
+     * (about one second after it is added) is not usable yet and not listed.
+     */
+    addresses: InterfaceAddress[];
+}

package/native/Interfaces.cpp

@@ -0,0 +1,34 @@
+//The parts of the reading of the interfaces common to every system
+#include "Interfaces.h"
+
+#ifdef _WIN32
+#include <winsock2.h>
+#include <ws2tcpip.h>
+#else
+#include <arpa/inet.h>
+#include <sys/socket.h>
+#endif
+
+#include <cstdio>
+
+namespace netif {
+
+std::string addressText(int family, const void *bytes)
+{
+    char text[64] = {0};
+    if (!inet_ntop(family, const_cast<void *>(bytes), text, sizeof text)) return std::string();
+    return std::string(text);
+}
+
+std::string macText(const unsigned char *bytes, size_t length)
+{
+    if (length != 6) return std::string();
+    bool zero = true;
+    for (size_t index = 0; index < length; index++) zero = zero && bytes[index] == 0;
+    if (zero) return std::string();
+    char text[18];
+    std::snprintf(text, sizeof text, "%02x:%02x:%02x:%02x:%02x:%02x", bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5]);
+    return std::string(text);
+}
+
+}

package/native/Interfaces.h

@@ -0,0 +1,47 @@
+//The network interfaces of the machine, read from the system: every interface, the ones without an address too, with
+//its state and its unicast addresses. Each system has its own source file (linux/, darwin/, windows/).
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace netif {
+
+//A unicast address of an interface
+struct Address {
+    //The address as text (an IPv6 address without its scope)
+    std::string address;
+    //4 or 6
+    int family = 4;
+    unsigned prefixLength = 0;
+    //Not usable yet: an IPv6 address in its duplicate address detection, or one that failed it
+    bool tentative = false;
+    //IPv6: the scope of the address, the index of its interface for a link-local one, 0 for a global one (Windows also
+    //gives the site of a site-local one)
+    uint32_t scopeId = 0;
+};
+
+struct Interface {
+    std::string name;
+    uint32_t index = 0;
+    //The hardware address (aa:bb:cc:dd:ee:ff), empty when the interface has none
+    std::string mac;
+    //Enabled (its administrative state)
+    bool up = false;
+    //Connected: its link is up
+    bool running = false;
+    bool loopback = false;
+    std::vector<Address> addresses;
+};
+
+//Every interface of the machine; a std::system_error when the system cannot be read
+std::vector<Interface> listInterfaces();
+
+//The text of an address of the given family (AF_INET or AF_INET6) from its bytes
+std::string addressText(int family, const void *bytes);
+
+//The text of a hardware address of 6 bytes, empty for none (any other length, or all zeros)
+std::string macText(const unsigned char *bytes, size_t length);
+
+}

package/native/Sockets.h

@@ -0,0 +1,36 @@
+//The sockets bound to an interface (Linux: SO_BINDTODEVICE) and their multicast groups, and whether the system refuses
+//the packets reaching the addresses of an interface through another one (the strong host model: Windows, macOS).
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+
+namespace netif {
+
+struct BoundSocket {
+    int fd = -1;
+    uint16_t port = 0;
+};
+
+//A socket of the family (4, 6) bound to the interface of the name, on the port of every address of the family (0: one
+//the system chooses); a TCP socket listening already. IPv6 only for 6 (IPV6_V6ONLY). A std::system_error when the system
+//refuses (EPERM: binding to an interface needs CAP_NET_RAW before Linux 5.7; ENODEV: no such interface; EADDRINUSE…).
+BoundSocket bindToInterface(const std::string &name, int family, bool stream, uint16_t port, int backlog);
+
+//The socket joins (or leaves) the multicast group on the interface of the index (MCAST_JOIN_GROUP: by its index, the
+//interface may have no address)
+void membership(int fd, const std::string &group, uint32_t index, bool join);
+
+//A setting that makes the system accept, through another interface, packets for the addresses of the interface of the
+//index: the interface and the setting
+struct WeakReception {
+    std::string interfaceName;
+    std::string setting;
+};
+
+//The first setting of the family (4, 6) that makes the system accept, through another interface, the packets for the
+//addresses of the interface of the index; none when it refuses them
+std::optional<WeakReception> weakReception(uint32_t index, int family);
+
+}

package/native/Watcher.h

@@ -0,0 +1,27 @@
+//The notifications of the changes of the interfaces (links, addresses, their settings), from a thread of the addon or
+//of the system: each one calls the function given, which only signals that something changed (JavaScript reads the
+//interfaces again). Stopped when destroyed: no call once the destructor has returned. Each system has its own source
+//file (linux/, darwin/, windows/).
+#pragma once
+
+#include <functional>
+#include <memory>
+
+namespace netif {
+
+class Watcher {
+public:
+    explicit Watcher(std::function<void()> changed);
+
+    ~Watcher();
+
+    Watcher(const Watcher &) = delete;
+
+    Watcher &operator=(const Watcher &) = delete;
+
+private:
+    struct State;
+    std::unique_ptr<State> state;
+};
+
+}