@lakutata/netif 0.0.0-stage → 3.1.5

package/dist/cjs/exceptions/NetIfException.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetIfException = void 0;
+/**
+ * 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.
+ */
+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;
+    }
+}
+exports.NetIfException = NetIfException;

package/dist/cjs/exceptions/NetIfNotEnforcedException.d.ts

@@ -0,0 +1,12 @@
+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 declare class NetIfNotEnforcedException extends NetIfException {
+    /**
+     * `'E_NETIF_NOT_ENFORCED'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/exceptions/NetIfNotEnforcedException.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetIfNotEnforcedException = void 0;
+const NetIfException_js_1 = require("./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'`.
+ */
+class NetIfNotEnforcedException extends NetIfException_js_1.NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_NOT_ENFORCED'`.
+         */
+        this.errno = 'E_NETIF_NOT_ENFORCED';
+    }
+}
+exports.NetIfNotEnforcedException = NetIfNotEnforcedException;

package/dist/cjs/exceptions/NetIfNotFoundException.d.ts

@@ -0,0 +1,12 @@
+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 declare class NetIfNotFoundException extends NetIfException {
+    /**
+     * `'E_NETIF_NOT_FOUND'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/exceptions/NetIfNotFoundException.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetIfNotFoundException = void 0;
+const NetIfException_js_1 = require("./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'`.
+ */
+class NetIfNotFoundException extends NetIfException_js_1.NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_NOT_FOUND'`.
+         */
+        this.errno = 'E_NETIF_NOT_FOUND';
+    }
+}
+exports.NetIfNotFoundException = NetIfNotFoundException;

package/dist/cjs/exceptions/NetIfNotSupportedException.d.ts

@@ -0,0 +1,12 @@
+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 declare class NetIfNotSupportedException extends NetIfException {
+    /**
+     * `'E_NETIF_NOT_SUPPORTED'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/exceptions/NetIfNotSupportedException.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetIfNotSupportedException = void 0;
+const NetIfException_js_1 = require("./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'`.
+ */
+class NetIfNotSupportedException extends NetIfException_js_1.NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_NOT_SUPPORTED'`.
+         */
+        this.errno = 'E_NETIF_NOT_SUPPORTED';
+    }
+}
+exports.NetIfNotSupportedException = NetIfNotSupportedException;

package/dist/cjs/exceptions/NetIfTimeoutException.d.ts

@@ -0,0 +1,11 @@
+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 declare class NetIfTimeoutException extends NetIfException {
+    /**
+     * `'E_NETIF_TIMEOUT'`.
+     */
+    errno: string | number;
+}

package/dist/cjs/exceptions/NetIfTimeoutException.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetIfTimeoutException = void 0;
+const NetIfException_js_1 = require("./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'`.
+ */
+class NetIfTimeoutException extends NetIfException_js_1.NetIfException {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_NETIF_TIMEOUT'`.
+         */
+        this.errno = 'E_NETIF_TIMEOUT';
+    }
+}
+exports.NetIfTimeoutException = NetIfTimeoutException;

package/dist/cjs/exports/Netif.d.ts

@@ -0,0 +1,11 @@
+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 { type InterfaceAddress, type NetworkInterfaceInfo } from '../lib/Types.js';
+export { listenOn, listenOnAll, listInterfaces } from '../lib/Functions.js';
+export { type ListeningAddress } from '../lib/Attachment.js';
+export { InterfaceListener, type InterfaceListenerEvents, type ListenOptions } from '../lib/InterfaceListener.js';
+export { type AddressChange, type BindSocketOptions, type BoundSocket, type InterfaceSelector, NetworkInterface, type NetworkInterfaceEvents, type WaitForAddressOptions } from '../lib/NetworkInterface.js';
+export { InterfaceUDPSocket, type InterfaceUDPSocketEvents, type UDPSocketOptions } from '../lib/InterfaceUDPSocket.js';

package/dist/cjs/exports/Netif.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InterfaceUDPSocket = exports.NetworkInterface = exports.InterfaceListener = exports.listInterfaces = exports.listenOnAll = exports.listenOn = exports.NetIfNotSupportedException = exports.NetIfNotEnforcedException = exports.NetIfTimeoutException = exports.NetIfNotFoundException = exports.NetIfException = void 0;
+var NetIfException_js_1 = require("../exceptions/NetIfException.js");
+Object.defineProperty(exports, "NetIfException", { enumerable: true, get: function () { return NetIfException_js_1.NetIfException; } });
+var NetIfNotFoundException_js_1 = require("../exceptions/NetIfNotFoundException.js");
+Object.defineProperty(exports, "NetIfNotFoundException", { enumerable: true, get: function () { return NetIfNotFoundException_js_1.NetIfNotFoundException; } });
+var NetIfTimeoutException_js_1 = require("../exceptions/NetIfTimeoutException.js");
+Object.defineProperty(exports, "NetIfTimeoutException", { enumerable: true, get: function () { return NetIfTimeoutException_js_1.NetIfTimeoutException; } });
+var NetIfNotEnforcedException_js_1 = require("../exceptions/NetIfNotEnforcedException.js");
+Object.defineProperty(exports, "NetIfNotEnforcedException", { enumerable: true, get: function () { return NetIfNotEnforcedException_js_1.NetIfNotEnforcedException; } });
+var NetIfNotSupportedException_js_1 = require("../exceptions/NetIfNotSupportedException.js");
+Object.defineProperty(exports, "NetIfNotSupportedException", { enumerable: true, get: function () { return NetIfNotSupportedException_js_1.NetIfNotSupportedException; } });
+var Functions_js_1 = require("../lib/Functions.js");
+Object.defineProperty(exports, "listenOn", { enumerable: true, get: function () { return Functions_js_1.listenOn; } });
+Object.defineProperty(exports, "listenOnAll", { enumerable: true, get: function () { return Functions_js_1.listenOnAll; } });
+Object.defineProperty(exports, "listInterfaces", { enumerable: true, get: function () { return Functions_js_1.listInterfaces; } });
+var InterfaceListener_js_1 = require("../lib/InterfaceListener.js");
+Object.defineProperty(exports, "InterfaceListener", { enumerable: true, get: function () { return InterfaceListener_js_1.InterfaceListener; } });
+var NetworkInterface_js_1 = require("../lib/NetworkInterface.js");
+Object.defineProperty(exports, "NetworkInterface", { enumerable: true, get: function () { return NetworkInterface_js_1.NetworkInterface; } });
+var InterfaceUDPSocket_js_1 = require("../lib/InterfaceUDPSocket.js");
+Object.defineProperty(exports, "InterfaceUDPSocket", { enumerable: true, get: function () { return InterfaceUDPSocket_js_1.InterfaceUDPSocket; } });
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

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

@@ -0,0 +1,5 @@
+/**
+ * The addon of the package (build/Release/netif.node), written by the build (scripts/addon.mjs) in place of this one: a
+ * require of its file by a path from the module, which the builder of lakutata follows when it packs an application
+ */
+export declare const addon: unknown;

package/dist/cjs/lib/Addon.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addon = void 0;
+try {
+    exports.addon = require(require("node:path").join(__dirname, "..", "..", "..", "build", "Release", "netif.node"));
+} 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;
+}

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

@@ -0,0 +1,152 @@
+import { EventEmitter } from 'node:events';
+import { type Family } from './Enforcement.js';
+import { type NetworkInterface } from './NetworkInterface.js';
+import { type InterfaceAddress } from './Types.js';
+/**
+ * An address a listener or a UDP socket of an interface can be reached at.
+ */
+export interface ListeningAddress {
+    /**
+     * The address (an IPv6 address without its scope).
+     */
+    address: string;
+    /**
+     * `'IPv4'` or `'IPv6'`.
+     */
+    family: 'IPv4' | 'IPv6';
+    /**
+     * The port.
+     */
+    port: number;
+    /**
+     * IPv6 only: the scope of the address (the index of the interface for a link-local one), 0 for a global one.
+     */
+    scopeid?: number;
+}
+/**
+ * The options common to the listeners and the UDP sockets of an interface
+ */
+export interface AttachmentOptions {
+    port: number;
+    family?: 'IPv4' | 'IPv6' | 'both';
+    strict?: boolean;
+}
+/**
+ * What a socket of an attachment is made on: a socket bound to the interface (Linux, its descriptor), or an address of
+ * the interface (the host with its scope, and the port)
+ */
+export type Target = {
+    fd: number;
+} | {
+    host: string;
+    port: number;
+};
+/**
+ * A socket of an attachment: bound to the interface, or to one of its addresses
+ */
+export interface Endpoint<Handle> {
+    key: string;
+    family: Family;
+    handle: Handle;
+    address?: InterfaceAddress;
+}
+/**
+ * The code of the error of the system an error carries
+ */
+export declare function codeOf(error: unknown): unknown;
+/**
+ * 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 declare abstract class Attachment<Events extends Record<keyof Events, unknown[]>, Handle> extends EventEmitter<Events> {
+    #private;
+    /**
+     * The interface.
+     */
+    readonly networkInterface: NetworkInterface;
+    protected readonly families: Family[];
+    protected readonly strict: boolean;
+    /**
+     * 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.
+     */
+    protected constructor(networkInterface: NetworkInterface, options: AttachmentOptions, ownsInterface: boolean);
+    /**
+     * Whether a TCP (true) or a UDP socket is bound to the interface
+     */
+    protected abstract readonly stream: boolean;
+    /**
+     * Makes a socket of a family on the target: its handle once it listens (or is bound)
+     */
+    protected abstract openHandle(target: Target, family: Family): Promise<Handle>;
+    /**
+     * The port of a socket made
+     */
+    protected abstract portOf(handle: Handle): number | undefined;
+    /**
+     * Closes a socket
+     */
+    protected abstract closeHandle(handle: Handle): void;
+    /**
+     * 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(): boolean;
+    /**
+     * Why what comes through another interface is not refused, `undefined` while it is.
+     */
+    get reason(): string | undefined;
+    /**
+     * The port, `undefined` until a port 0 was given one by the system.
+     */
+    get port(): number | undefined;
+    /**
+     * Whether the interface is listened on now (it exists, and has an address where its addresses are listened on).
+     */
+    get listening(): boolean;
+    /**
+     * 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(): ListeningAddress[];
+    /**
+     * Whether it was closed.
+     */
+    get closed(): boolean;
+    /**
+     * Whether the sockets are bound to the interface (Linux), not to its addresses
+     */
+    protected get boundToInterface(): boolean;
+    /**
+     * The sockets now
+     */
+    protected endpoints(): Endpoint<Handle>[];
+    /**
+     * A socket made, before it is counted (its settings applied: the broadcasts, the multicast groups)
+     */
+    protected prepare(_endpoint: Endpoint<Handle>): void;
+    /**
+     * A socket closed, no longer counted
+     */
+    protected released(_endpoint: Endpoint<Handle>): void;
+    /**
+     * Internal: the first binding, which the method that made it waits for.
+     * @returns It.
+     */
+    start(): Promise<this>;
+    /**
+     * Stops: the sockets closed (the listener does not wait for the connections established, which are left to the
+     * server).
+     */
+    close(): Promise<void>;
+    /**
+     * An error of a binding again, or of a socket: the error event, the binding retried a little later
+     */
+    protected failed(error: unknown): void;
+}