lakutata 3.1.3 → 3.1.5

package/doc/en/Netif.md

@@ -0,0 +1,261 @@
+# Lakutata Netif
+
+The package `@lakutata/netif` lets a server of Node.js listen on a network interface instead of an address. A device
+with several interfaces often serves its management pages on one of them only: the address of that port comes from DHCP
+and changes, or is not there yet when the device starts, and listening on `0.0.0.0` would expose the pages on every
+interface. With the package the server listens on "eth1", whatever its addresses, and keeps listening through their
+changes and through the interface unplugged and plugged back. It is not part of `lakutata`, and it needs no
+application. What it is like:
+
+- **Any server**: `http`, `https`, `http2`, `tls`, Express and Fastify take the connections of the interface as their
+  own; UDP sockets too, for the services that work on one interface (DHCP, mDNS, SSDP).
+- **The entrypoints of lakutata** take an `interface` option, which serves the controllers of an application on one
+  interface (section 5).
+- **The system refuses the other interfaces where it can**: on Linux the sockets are bound to the interface, and a
+  connection that reaches its address through another interface is refused. On Windows and macOS the addresses of the
+  interface are listened on, and `enforced` tells whether the system refuses those connections.
+- **The interfaces and their changes**: every interface of the machine with its state, and events when its addresses,
+  its link or its presence change, from the notifications of the system.
+- **A native addon**, compiled when the package is installed, for Linux, macOS and Windows; it also runs in Bun and in
+  the main process of Electron.
+
+The README of `@lakutata/netif` describes every function and its options; this guide goes through what the package is
+for, with an example of each use.
+
+```bash
+npm install @lakutata/netif
+```
+
+The addon is compiled when the package is installed, so the machine needs Python 3 and a C++17 compiler (on Alpine Linux
+the headers of the kernel too: `apk add python3 make g++ linux-headers`). The package manager has to run the install
+script of the package: npm runs it, and may warn that the script is "not yet covered by allowScripts" (`npm
+install-scripts approve @lakutata/netif` records that you allow it); Bun and pnpm run it only for the packages they are
+told to trust (`trustedDependencies` in the package.json for Bun, `pnpm approve-builds` for pnpm). Its types refer to
+the ones of `@lakutata/core`, a peer dependency that the package managers install with it; it is not loaded when the
+package runs.
+
+## 1. Listening on an interface
+
+`listenOn()` listens on an interface for a server. The interface is given by its name, its hardware address
+(`{mac: '52:54:00:12:34:56'}`, the same whatever the system names it) or its index; on Windows the name is the one of
+the network connection (`'以太网 2'`, `'Ethernet 2'`).
+
+```typescript
+import {createServer} from 'node:http'
+import express from 'express'
+import {type InterfaceListener, listenOn} from '@lakutata/netif'
+
+const app = express()
+app.get('/', (request, response) => response.send(`served on ${request.socket.localAddress}`))
+
+const listener: InterfaceListener = await listenOn('eth1', createServer(app), {port: 8080})
+listener.on('error', error => console.error(error))
+console.log(listener.port, listener.addresses)
+```
+
+- The listener accepts the connections and gives them to the server, which handles them as its own. The server itself
+  does not listen: its `address()` is `null`, and `server.close()` does not stop the listener; use `listener.port`,
+  `listener.addresses` and `listener.close()`.
+- The interface may not exist yet or have no address yet: `listenOn()` returns at once, and the interface is listened
+  on when it can be. When it is unplugged and plugged back, or when its addresses change, it is listened on again by
+  itself; the connections established are left to the server.
+- The first listening throws its errors (the port taken); the later ones are `error` events, retried a little later.
+  Handle the `error` event of the listener, as for a `net.Server`.
+- `family` chooses `'IPv4'`, `'IPv6'` or `'both'` (by default); `port: 0` lets the system choose a port, kept when the
+  interface is listened on again.
+
+## 2. Which connections are refused
+
+A client of another network can send packets for the address of the management port through another interface of the
+device, with a route of its own through it. Whether the system refuses such a connection is what `enforced` tells:
+
+| | `enforced` |
+|---|---|
+| Linux | `true`: the sockets are bound to the interface (`SO_BINDTODEVICE`); before Linux 5.7 this needs the capability `CAP_NET_RAW`, without which the addresses are listened on and `enforced` is `false` |
+| Windows | `true` while every other interface receives with the strong host model and does not forward, which is the default |
+| macOS | `false` unless the system is set to refuse those packets (`net.inet.ip.check_interface` set to 2, and `net.inet6.ip6.check_interface` for IPv6) and does not forward |
+
+By default the interface is listened on in the best way the system allows, never less than `listen(port, host)` on its
+addresses; `reason` tells why there is no guarantee and how to get it. Where the management port is a boundary of
+security, `strict: true` refuses to listen without the guarantee, and stops the listening while it is lost:
+
+```typescript
+import {createServer} from 'node:http'
+import {type InterfaceListener, NetIfNotEnforcedException, NetworkInterface} from '@lakutata/netif'
+
+const management: NetworkInterface = new NetworkInterface({mac: '52:54:00:12:34:56'})
+try {
+    const listener: InterfaceListener = await management.listen(createServer(), {port: 443, strict: true})
+    listener.on('error', error => console.error(error))
+    listener.on('enforced', enforced => console.log(enforced ? 'guaranteed again' : 'stopped: no longer guaranteed'))
+} catch (error) {
+    if (error instanceof NetIfNotEnforcedException) console.error(error.message)
+    throw error
+}
+```
+
+## 3. Following an interface
+
+A `NetworkInterface` gives the state of an interface now (`present`, `running`, `addresses`…) and an event at each
+change. The events come from the notifications of the system, not from polling.
+
+```typescript
+import {type InterfaceAddress, listInterfaces, NetworkInterface} from '@lakutata/netif'
+
+console.log(listInterfaces().map(entry => `${entry.name}: ${entry.running ? 'connected' : 'not connected'}`))
+
+const wan: NetworkInterface = new NetworkInterface('eth0')
+wan.on('change', ({added, removed}) => {
+    for (const address of added) console.log(`new address ${address.cidr}`)
+    for (const address of removed) console.log(`address gone ${address.cidr}`)
+})
+wan.on('down', () => console.log('the cable of eth0 is unplugged'))
+wan.on('up', () => console.log('the cable of eth0 is plugged in'))
+const address: InterfaceAddress = await wan.waitForAddress({family: 'IPv4', timeout: 60000})
+console.log(`reachable at ${address.address}`)
+```
+
+- `listInterfaces()` lists the interfaces without an address too, with their state; `os.networkInterfaces()` lists
+  only the ones with an address.
+- An IPv6 address counts once it is usable: about a second after it is added, when its duplicate address detection is
+  over.
+- `close()` stops following the interface (and closes its listeners).
+
+## 4. UDP on an interface
+
+`createUDPSocket()` gives a UDP socket of the interface, with the methods and the events of a `dgram` socket. A device
+that answers the discovery broadcasts of its management network only:
+
+```typescript
+import {type InterfaceUDPSocket, NetworkInterface} from '@lakutata/netif'
+
+const management: NetworkInterface = new NetworkInterface('eth1')
+const socket: InterfaceUDPSocket = await management.createUDPSocket({port: 30303, family: 'IPv4'})
+socket.setBroadcast(true)
+socket.on('message', (message, remote) => {
+    const answer: string = `device at ${management.addresses[0]?.address}`
+    if (message.toString() === 'who is there') socket.send(answer, remote.port, remote.address)
+})
+socket.on('error', error => console.error(error))
+```
+
+On Linux the socket receives what comes through the interface, its broadcasts and the multicast of the groups joined
+with `addMembership()` included, and nothing of the other interfaces. On Windows and macOS a socket is bound to each
+address of the interface; on macOS such sockets receive no broadcast and no multicast.
+
+## 5. In an application
+
+The entrypoints of lakutata that listen on a port take an `interface` option: `expressHTTPEntrypoint()`,
+`fastifyHTTPEntrypoint()`, `httpServiceEntrypoint()`, `socketIOServiceEntrypoint()`, `jsonRPCServiceEntrypoint()`,
+`grpcServiceEntrypoint()` of `@lakutata/grpc` and `httpMCPEntrypoint()` of `@lakutata/mcp`. The actions of the
+controllers are then served on that interface, whatever its addresses:
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {GET} from 'lakutata/decorator/ctrl'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+class ManagementController extends Controller {
+    @GET('/status')
+    public async status(): Promise<{ ok: boolean }> {
+        return {ok: true}
+    }
+}
+
+Application.run(() => ({
+    id: 'device.app',
+    name: 'Device',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [ManagementController],
+            http: expressHTTPEntrypoint({port: 8080, interface: 'eth1'})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+- `family`, `strict` and `onError` go with `interface`. Without `onError`, the errors of listening again are written to
+  the log of the application. The `listening` callback of the adapter gets the listeners. [HTTP](HTTP.md), section 2,
+  describes these options.
+- The application starts while the interface does not exist yet, and its actions can be reached once it appears.
+- The entrypoints listen through `IInterfaceListening`, a contract of `@lakutata/core` that this package implements
+  and that they load by default. Another implementation is given in their `interfaceListening` option; the
+  `InterfaceListener` of the package is an `IInterfaceListener`.
+
+A server that is not an entrypoint belongs to a component: it listens in `startup()` and stops in `destroy()`. The
+interface and the port are the options of the component.
+
+```typescript
+import {createServer} from 'node:http'
+import express from 'express'
+import {Application, Component, DTO, type ILogger} from 'lakutata'
+import {Configurable, Inject} from 'lakutata/decorator/di'
+import {type InterfaceListener, listenOn} from '@lakutata/netif'
+
+class ManagementPages extends Component {
+    @Inject('log')
+    protected readonly log: ILogger
+
+    @Configurable(DTO.String().required())
+    protected readonly interfaceName: string
+
+    @Configurable(DTO.Number().port().default(8080))
+    protected readonly port: number
+
+    protected listener: InterfaceListener
+
+    protected async startup(): Promise<void> {
+        const app = express()
+        app.get('/', (request, response) => response.send('management'))
+        this.listener = await listenOn(this.interfaceName, createServer(app), {port: this.port})
+        this.listener.on('error', (error: Error): void => this.log.error(error.message))
+        this.listener.on('listening', (): void => this.log.info('listening on %o', this.listener.addresses))
+        this.log.info('enforced: %s', this.listener.enforced)
+    }
+
+    protected async destroy(): Promise<void> {
+        await this.listener?.close()
+    }
+}
+
+Application.run(() => ({
+    id: 'device.app',
+    name: 'Device',
+    components: {
+        management: {class: ManagementPages, interfaceName: 'eth1', port: 8080}
+    },
+    bootstrap: ['management']
+}))
+```
+
+## 6. Systems, runtimes and packaging
+
+- **Linux** binds the sockets to the interface: the system refuses the other interfaces, an address added is served at
+  once, and UDP gets the broadcasts and the multicast of the interface. Before Linux 5.7 give the process `CAP_NET_RAW`
+  (`setcap cap_net_raw+ep`, or `AmbientCapabilities=CAP_NET_RAW` in its systemd unit).
+- **Windows** listens on the addresses of the interface; its strong host model refuses the other interfaces unless an
+  interface is set to the weak host model (`netsh interface ipv4 set interface "<name>" weakhostreceive=enabled`, which
+  some load balancers do) or forwards. `reason` names that interface.
+- **macOS** listens on the addresses of the interface, without the guarantee unless the system is set to it. macOS 27
+  hides the hardware addresses from the processes (it gives `02:00:00:00:00:00`): give an interface by its name there.
+- **Bun**: its `https` server answers the connections given to it without TLS, so `listen()` refuses it in Bun (a
+  Fastify instance created with `https` too); use `http2.createSecureServer({key, cert, allowHTTP1: true})` or
+  `tls.createServer()` there. Its servers do not close the idle keep-alive connections given to them, which the
+  entrypoints close themselves. A connection given to a server cannot be upgraded to a WebSocket (seen with Bun 1.4), so
+  the entrypoints refuse WebSocket on an interface in Bun.
+- **Electron**: in the main process.
+- The bundles, the executables and the installers made by `lakutata package` carry the compiled addon
+  (`build/Release/netif.node`): build them on each target platform, after installing the package there (see
+  [Packaging](Packaging.md) and [NativeAddons](NativeAddons.md)).
+
+## 7. Exceptions
+
+| Exception | When |
+|---|---|
+| `NetIfNotFoundException` | An index no interface has, a hardware address several interfaces have |
+| `NetIfNotEnforcedException` | `strict` where the system cannot refuse the other interfaces, or the guarantee lost (an `error` event) |
+| `NetIfNotSupportedException` | What the system or the runtime cannot do: `bindSocket()` outside Linux, multicast on a socket bound to an address on macOS, an `https` server in Bun |
+| `NetIfTimeoutException` | `waitForAddress()` past its `timeout` |
+| `NetIfException` | The base of all of them; a refusal of the system has its code as `errno` (`'EADDRINUSE'`, `'EACCES'`…) |

package/doc/en/Overview.md

@@ -1,10 +1,10 @@
 # Lakutata Overview
 
 **Lakutata** is an IoC application framework for Node.js and TypeScript. It gives web services, CLI tools, desktop
-(Electron) applications and embedded devices one programming model: an application is a tree of objects (components,
-providers, controllers) that a container creates. DTOs validate their options and inputs, and transports expose
-the controllers: HTTP (Express, Fastify), CLI (Commander), service RPC (HTTP, Socket.IO, JSON-RPC 2.0, gRPC, NATS,
-Electron IPC), schedules and message queues. One controller method can serve all of them at once.
+(Electron, NW.js) applications and embedded devices one programming model: an application is a tree of objects
+(components, providers, controllers) that a container creates. DTOs validate their options and inputs, and transports
+expose the controllers: HTTP (Express, Fastify), CLI (Commander), service RPC (HTTP, Socket.IO, JSON-RPC 2.0, gRPC,
+NATS, Electron IPC, NW.js), schedules and message queues. One controller method can serve all of them at once.
 
 The package `lakutata` re-exports the `@lakutata/*` packages under its subpaths (see the table below) and presets two
 components in every application: `log` (the `Logger`, which writes pino-compatible JSON lines) and `entrypoint` (the
@@ -30,7 +30,7 @@ tool, a web and a desktop application, calls between services, background jobs,
 | `lakutata/decorator/ctrl` | `@HTTPAction`, `@GET`…`@OPTIONS`, `@CLIAction`, `@ServiceAction`, `@Schedule`, `@Prefix`, `@UseMiddlewares` |
 | `lakutata/adapter/express`, `lakutata/adapter/fastify` | The HTTP transports |
 | `lakutata/adapter/commander` | The CLI transport |
-| `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron` | The service transports |
+| `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron`, `lakutata/adapter/nwjs` | The service transports |
 | `lakutata/com/logger` | The `Logger` component, preset as `log` (pino-compatible JSON lines) |
 | `lakutata/orm`, `lakutata/decorator/orm` | TypeORM and its decorators |
 | `lakutata/com/database`, `lakutata/provider/database` | The `Database` component and provider |
@@ -48,8 +48,9 @@ Not part of this package: `@lakutata/cli` (the `lakutata` command for creating p
 applications, see [Command](Command.md)), `@lakutata/grpc` (a gRPC client, server and service transport),
 `@lakutata/nats` (a NATS component and service transport), `@lakutata/dbus` (D-Bus), `@lakutata/mcp` (the Model
 Context Protocol), `@lakutata/webrtc` (WebRTC: the signaling, a TURN server, a media server, peer connections),
-`@lakutata/ffi` (the C functions of native libraries) and `@lakutata/math` (symbolic and numeric mathematics, as
-functions that need no lakutata application).
+`@lakutata/ffi` (the C functions of native libraries), `@lakutata/math` (symbolic and numeric mathematics, as functions
+that need no lakutata application) and `@lakutata/netif` (servers and UDP sockets listening on a network interface
+whatever its addresses, the interfaces of the machine and their changes).
 
 ## The guides
 
@@ -73,7 +74,7 @@ functions that need no lakutata application).
 | [Middlewares](Middlewares.md) | The middlewares and the access control of the actions |
 | [HTTP](HTTP.md) | The HTTP adapters: routes, input, responses, errors, the features of Express and Fastify |
 | [CLI](CLI.md) | Command line tools: commands, options, prompts, output and exit codes |
-| [ServiceCalls](ServiceCalls.md) | The service actions over HTTP, Socket.IO, JSON-RPC 2.0 and Electron: patterns, responses, clients and their events |
+| [ServiceCalls](ServiceCalls.md) | The service actions over HTTP, Socket.IO, JSON-RPC 2.0, Electron and NW.js: patterns, responses, clients and their events |
 | [GRPC](GRPC.md) | The service actions over gRPC (`@lakutata/grpc`), and calling them from other applications and languages |
 | [NATS](NATS.md) | The NATS component, the service actions over NATS (`@lakutata/nats`), the service proxies and their events |
 | [Schedules](Schedules.md) | Scheduled jobs: intervals, cron expressions, jobs run by one instance |
@@ -95,6 +96,7 @@ functions that need no lakutata application).
 | [WebRTC](WebRTC.md) | Peer-to-peer connections and a media server (`@lakutata/webrtc`): the signaling, the TURN server, browsers and applications, the actions of an application called through data channels, WHIP and WHEP |
 | [FFI](FFI.md) | The C functions of native libraries (`@lakutata/ffi`): declarations copied from headers, structs, callbacks, memory, packaging |
 | [Math](Math.md) | Mathematics (`@lakutata/math`): formulas and exact results, equations, decimals of any precision, matrices, statistics, numeric solutions, units |
+| [Netif](Netif.md) | Network interfaces (`@lakutata/netif`): a server listening on an interface whatever its addresses, the connections of the other interfaces refused, the interfaces and their changes, UDP on one interface |
 | [Command](Command.md) | The `lakutata` command: creating projects, migrations, translations, environment variables |
 | [Workspaces](Workspaces.md) | Projects of several packages: running their scripts, giving them a version, adding packages |
 | [NativeAddons](NativeAddons.md) | Native addons in C++ or Rust: creating them, linking libraries, shipping them |

package/doc/en/Packaging.md

@@ -49,6 +49,7 @@ directory, once moved with them.
 | `--outfile <file>` | The bundle, `dist/<name>.cjs` by default |
 | `--no-minify` | Do not minify the bundle (the names of the classes are kept either way) |
 | `--external <modules...>` | Modules left out of the bundle, loaded at run time from a `node_modules` next to it |
+| `--node <version>` | The version of Node.js running the bundle (`18.10` for NW.js 0.70): the bundle is written in the syntax that version reads; the one running the tool by default |
 
 ## 3. Native addons
 
@@ -124,11 +125,12 @@ architecture for Linux (`docker run --platform linux/arm64`); the README of the
 
 | Option | Meaning |
 |---|---|
-| `--runtime node` (default) | The bundle is embedded in a copy of the Node.js running the tool (a single executable application of Node.js): about 110 MB on macOS arm64 |
+| `--runtime node` (default) | The bundle is embedded in a copy of the Node.js running the tool, or of `--node-program` (a single executable application of Node.js): about 110 MB on macOS arm64 |
 | `--runtime bun` | The bundle is compiled by Bun (the `bun` package of the project, else the `bun` of the system): about 70 MB on macOS arm64, and it starts faster; the runtime is then Bun |
 | `--layout file` (default) | One file: the native addons, the files read by path and the resources are embedded, and extracted when it starts |
 | `--layout directory` | `dist/<name>/` holds the executable, `native/` and `resources/`, loaded from there without extraction (the installers use it) |
 | `--outdir <directory>` | Where the executable is written, `dist` by default |
+| `--node-program <path>` | The node embedded instead of the one running the tool: a Node.js 20.12, 21.7 or later (`$(nvm which 22)`), so that an older Node.js can run the tool; the bundle follows its syntax |
 | `--entry`, `--no-minify`, `--external` | As for a bundle |
 
 - **Extraction**: an executable of the file layout extracts what it embeds at its first run, into its cache directory,
@@ -171,6 +173,7 @@ of the project (it may be outside the package, such as `../ui/dist`), `to` its p
 | An executable, file layout | `true` | The directory the resources were extracted to |
 | An executable, directory layout, or an installed application | `true` | `resources` next to the executable |
 | A packaged Electron application | `true` | `main.resources` in the resources of Electron |
+| An NW.js application (run by `lakutata nwjs run`, or packaged) | `true` | `resources` in the directory of the application |
 
 `resourcesPath()` returns the path even when the application declares no resources, so the directory may not exist.
 The application chooses where to read its files from:

package/doc/en/ProjectStructure.md

@@ -53,8 +53,8 @@ templates other than `cli` do.
 ## 2. The workspace templates
 
 The other templates are npm workspaces: the application is the package `packages/app`, and the templates with an
-interface or with installers add `packages/ui` (the web pages, or the renderer of Electron) and `packages/resources`
-(the icon). The `service` template:
+interface or with installers add `packages/ui` (the web pages, the renderer of Electron, or the user interface of
+NW.js) and `packages/resources` (the icon). The `service` template:
 
 ```
 shop/
@@ -93,6 +93,10 @@ The other templates add to this layout:
   it into `dist/` ([Packaging](Packaging.md)).
 - `electron-react` and `electron-vue`: the main process of Electron in `packages/app` (its window and its service
   actions over IPC), the renderer in `packages/ui`, and the scripts that make the installers.
+- `nwjs-react` and `nwjs-vue`: the background script of NW.js in `packages/app` (its window, whose host page in
+  `packages/app/host` holds the user interface in a webview, and its service actions), the user interface in
+  `packages/ui`, the version of NW.js in `packages/app/nwjs.json` (written by `npm run nwjs:use -- <version>`), and the
+  scripts that make the installers.
 
 The packed forms are written to `dist/` at the root of the workspace; `.gitignore` leaves out `build`, `dist` and the
 outputs of the interfaces.
@@ -105,8 +109,9 @@ outputs of the interfaces.
 |---|---|---|
 | `i18n` | all | The messages of the languages in `src/locales` (`en`, `zh-CN`), the `i18n` component, the language middleware, and the scripts `i18n:check` and `i18n:types` ([I18n](I18n.md)) |
 | `installer` | `cli`, `service`, `web-*` | The `lakutata.installer` of the application, the scripts that make the installers (on the machine, and for Linux in Docker), and for the services a system service ([Installers](Installers.md)) |
+| `win7` | `nwjs-*` | NW.js 0.72.0 instead of the release the template was published with: the last release running on Windows 7, 8 and 8.1, and the script `package:ia32` that makes the installers of 32-bit Windows |
 
-The Electron templates make installers without this feature.
+The Electron and NW.js templates make installers without the `installer` feature.
 
 ## 4. Templates of your own
 

package/doc/en/ServiceCalls.md

@@ -2,8 +2,8 @@
 
 A service action (`@ServiceAction`) is called with a message rather than a URL: an object whose keys select the action,
 its **pattern**, and whose other keys are the input. The same actions can be served over several transports at once:
-plain HTTP, Socket.IO, JSON-RPC 2.0 (over HTTP, WebSocket or the standard input and output) and the IPC of Electron, as
-this guide describes, and gRPC, NATS and the data channels of WebRTC, which have their own guides. The controllers and
+plain HTTP, Socket.IO, JSON-RPC 2.0 (over HTTP, WebSocket or the standard input and output), the IPC of Electron and the
+windows of NW.js, as this guide describes, and gRPC, NATS and the data channels of WebRTC, which have their own guides. The controllers and
 their actions are described in [Controllers](Controllers.md), the entrypoint and its adapters in
 [Entrypoint](Entrypoint.md).
 
@@ -136,7 +136,7 @@ class OrderController extends Controller {
 
 ## 3. The response
 
-The HTTP service, Socket.IO and Electron answer with an envelope; JSON-RPC answers with its own responses (section 4).
+The HTTP service, Socket.IO, Electron and NW.js answer with an envelope; JSON-RPC answers with its own responses (section 4).
 
 ```text
 {"success": true, "error": null, "payload": <the result>}
@@ -179,6 +179,7 @@ export async function call<T>(message: Record<string, unknown>): Promise<T> {
 | `socketIOServiceEntrypoint()` | `lakutata/adapter/socket.io` | `socket.io` (`socket.io-client` on the clients) | An emit with an acknowledgement | Socket.IO events |
 | `jsonRPCServiceEntrypoint()` | `lakutata/adapter/jsonrpc` | `ws`, for WebSocket | A JSON-RPC 2.0 request | Notifications (WebSocket, stdio) |
 | `electronIPCServiceEntrypoint()` | `lakutata/adapter/electron` | (Electron) | `ipcRenderer.invoke()` | IPC messages |
+| `nwjsServiceEntrypoint()` | `lakutata/adapter/nwjs` | (NW.js) | A call of its bridge, by the host page of a window | Calls of the function the host page gives |
 | `grpcServiceEntrypoint()` | `@lakutata/grpc/service` | `@lakutata/grpc` | See [GRPC](GRPC.md) | gRPC streams |
 | `natsServiceEntrypoint()` | `@lakutata/nats` | `@lakutata/nats` | See [NATS](NATS.md) | NATS messages |
 | `webrtcServiceEntrypoint()` | `@lakutata/webrtc` | `@lakutata/webrtc` | A JSON-RPC 2.0 request on a data channel, see [WebRTC](WebRTC.md) | Notifications |
@@ -197,7 +198,7 @@ pages of a web UI during its development. The Electron templates add it in devel
 | `host` | all the interfaces | The address to listen on |
 | `path` | `'/'` | The path of the requests; the events are under it, at `<path>/events` |
 | `limit` | `10485760` (10 MiB) | The largest body, in bytes |
-| `listening` | | `(server) => …`, called once the server listens |
+| `listening` | | `(server, listeners) => …`, called once the server listens (`listeners`, with `interface`: see below) |
 
 - A request is a `POST` to `path`, its body the message as JSON. It is answered with 200 and the envelope, whatever the
   result of the action. A body that is not JSON is answered with 400, a body over `limit` with 413, another method or
@@ -284,7 +285,7 @@ connected.
 | `options` | | The options of the Socket.IO server: `cors`, `path`, `maxHttpBufferSize`… |
 | `server` | | An HTTP server to share, or a function returning it (below) |
 | `io` | | An existing Socket.IO server, used as it is |
-| `listening` | | `(io, server) => …`, called once the adapter is ready |
+| `listening` | | `(io, server, listeners) => …`, called once the adapter is ready |
 
 ```typescript
 import {io, type Socket} from 'socket.io-client'
@@ -340,7 +341,7 @@ the tools that speak the protocol, and the parent processes over the standard in
 | `input`, `output` | `process.stdin`, `process.stdout` | The streams of stdio |
 | `end` | `'application'` | When the input of stdio ends: `'application'` exits the application once the requests in progress are answered, `'none'` does nothing, or a function |
 | `heartbeat` | `30000` | The interval of the pings of WebSocket, in milliseconds; `0` sends none |
-| `listening` | | `(server) => …`, called once the server of HTTP or WebSocket listens |
+| `listening` | | `(server, listeners) => …`, called once the server of HTTP or WebSocket listens |
 
 The method and the params of a request make the message: `{"method": "order.get", "params": {"id": 1}}` is the message
 `{method: 'order.get', id: 1}`, so the action declares the method in its pattern:
@@ -417,6 +418,25 @@ $ echo '{"jsonrpc": "2.0", "id": 1, "method": "sum", "params": {"values": [1, 2,
 
 The application exits once its input ends and its requests are answered (`end`).
 
+### On a network interface
+
+`httpServiceEntrypoint()`, `socketIOServiceEntrypoint()` with its own server, and `jsonRPCServiceEntrypoint()` over HTTP
+or WebSocket can listen on a network interface instead of an address, whatever its addresses, with the package
+`@lakutata/netif` installed apart. They take the options `interface`, `family`, `strict`, `onError` and
+`interfaceListening` of the HTTP adapters (see [HTTP](HTTP.md), section 2), and their `listening` callback gets the
+listeners of the interface as its last argument:
+
+```typescript
+import {httpServiceEntrypoint} from 'lakutata/com/entrypoint'
+
+//The service on eth1 only, whatever its address
+export const service = httpServiceEntrypoint({port: 3000, interface: 'eth1'})
+```
+
+In Bun, a connection given to a server cannot be upgraded to a WebSocket (seen with Bun 1.4). There the start fails for
+JSON-RPC over WebSocket, and for Socket.IO unless it uses polling only (`options: {transports: ['polling']}`, and the
+same on the clients).
+
 ### Electron
 
 `electronIPCServiceEntrypoint()` serves the actions to the windows of an Electron application, in its main process.
@@ -449,6 +469,47 @@ contextBridge.exposeInMainWorld('service', {
 - The Electron templates of `lakutata create` contain a preload script of this shape, and a `window.ipc` for the pages,
   whose `invoke()` returns the payload or throws the error.
 
+### NW.js
+
+`nwjsServiceEntrypoint()` serves the actions to the windows of an NW.js application, in its background script (its
+Node.js context). NW.js gives Node.js to the pages of its windows, and an iframe of such a page does not keep Node.js
+from its content (its sandbox is ignored): the user interface runs in a `<webview>`, without Node.js, held by a trusted
+page of the window (its host page). The adapter puts a bridge on the global object that NW.js shares with its windows,
+`global[Symbol.for(key)]`; the host page forwards the requests of the interface to it, and gives it the function that
+pushes the events to the interface.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `key` | `'lakutata:service'` (`NWJS_SERVICE_BRIDGE`) | The key of the bridge on the global object |
+| `global` | the global object of NW.js | The object the bridge is put on, or a stand-in in the tests |
+
+| Method of the bridge | Meaning |
+|---|---|
+| `invoke(message, clientId)` | Invokes an action: resolves to the envelope, never rejects |
+| `subscribe(clientId, push)` | Makes a page a client: the events pushed to it are given to `push(event, args)` |
+| `unsubscribe(clientId)` | Removes a client, when its page is loaded again or its window closed: its requests in progress are aborted |
+
+The host page forwards the messages of the interface, from the page loaded in its `<webview>` only:
+
+```javascript
+const view = document.querySelector('webview')
+const origin = new URL(view.src).origin
+const bridge = global[Symbol.for('lakutata:service')]
+const send = (message) => view.contentWindow.postMessage(message, origin)
+window.addEventListener('message', async (event) => {
+    if (event.source !== view.contentWindow || event.origin !== origin) return
+    const {type, id, message, clientId} = event.data
+    if (type === 'invoke') send({type: 'response', id: id, response: await bridge.invoke(message, clientId)})
+    if (type === 'subscribe') bridge.subscribe(clientId, (name, args) => send({type: 'event', name: name, args: args}))
+})
+```
+
+- The `<webview>` loads the files of the application when its partition is declared in the manifest of NW.js:
+  `"webview": {"partitions": [{"name": "trusted", "accessible_resources": ["<all_urls>"]}]}` (the builder writes it).
+- A page loaded again in the `<webview>` is a new client: the host page unsubscribes the previous one.
+- The NW.js templates of `lakutata create` contain such a host page (`packages/app/host`), and a `window.ipc` for the
+  interface like the one of the Electron templates.
+
 ## 5. Clients and events
 
 The transports that keep their clients connected can push events to them. A client is identified by the id it gives:
@@ -461,6 +522,7 @@ The transports that keep their clients connected can push events to them. A clie
 | JSON-RPC over WebSocket | The `id` header or `id` query parameter of the connection, else a random id |
 | JSON-RPC over stdio | `'stdio'` |
 | Electron | The id the page gives when it subscribes or invokes |
+| NW.js | The id the host page gives to the bridge for its page |
 | WebRTC | The member id of the caller in its room |
 
 An action reads the id of its client in `this.context.clientId`. The `entrypoint` component pushes the events:
@@ -496,6 +558,7 @@ A client receives `notify(clientId, 'progress', 50, 'half')` as:
 | Socket.IO | `socket.on('progress', (percent, label) => …)` |
 | JSON-RPC (WebSocket, stdio) | `{"jsonrpc": "2.0", "method": "progress", "params": [50, "half"]}` |
 | Electron | `('progress', [50, 'half'])`, through the `subscribe` of the preload script above |
+| NW.js | `('progress', [50, 'half'])`, given to the function of the `subscribe` of the bridge |
 | WebRTC | `proxy.on('progress', (percent, label) => …)` of a `PeerServiceProxy` |
 
 ## 6. Stopping and leaving

package/doc/en/UpgradingFrom1.md

@@ -20,7 +20,7 @@ packages obtained elsewhere may have APIs that this page does not cover.
 | Modules | CommonJS: imports without extensions, `__dirname` | ES modules: relative imports ending in `.js` |
 | Service actions | `@Controller({_ctrl: …})` and `@PATTERN({_act: …})` from `@lakutata-module/service` | `@ServiceAction({…})` from `lakutata/decorator/ctrl` |
 | Validation | `Validator` schemas (yup) given to `@Accept` | DTO classes with `@Expect` |
-| Node.js | `>=14.15.1` (`@lakutata/core` 1.0.60) | `^22.13.0 \|\| >=24.11.0` |
+| Node.js | `>=14.15.1` (`@lakutata/core` 1.0.60) | `>=18.10.0` |
 
 **`@lakutata/core` 3 is not a new version of the 1.x library.** It is the core of Lakutata 3, a different API under the
 same name. `npm install @lakutata/core@latest`, or a range such as `*`, in a 1.x project puts it in place of the 1.x
@@ -392,7 +392,7 @@ are built differently, so the entries that 1.x wrote are not found: start with a
 - **The `lakutata` field of `package.json`** told the 1.x tool the kind of the project (`type`), its directories and
   its configuration file. In 3.x the field has another meaning (the `resources` and the `installer` of a packed
   application, [Packaging](Packaging.md)): remove the 1.x one.
-- **Node.js, TypeScript and modules.** Node.js `^22.13.0 || >=24.11.0`, TypeScript 6 as in the templates, ES modules
+- **Node.js, TypeScript and modules.** Node.js `>=18.10.0`, TypeScript 6 as in the templates, ES modules
   (`"type": "module"`, relative imports ending in `.js`), `tsconfig.json` extending `lakutata/tsconfig.json`.
 - **Ports.** The service module listened on a port of its own (6912 by default) and the registry on another (6911).
   The 3.x adapters listen on the ports of their options, and a service on NATS only connects out to the NATS server:

package/doc/en/UpgradingFrom2.md

@@ -17,15 +17,15 @@ It is for the projects that depend on the package `lakutata` at version 2. A pro
 | Exported functions | PascalCase: `BuildEntrypoints`, `BuildDatabaseOptions`, `MD5` | camelCase: `buildEntrypoints`, `buildDatabaseOptions`, `md5` |
 | Transports | Written by hand: `BuildHTTPEntrypoint((module, routeMap, handler, registerDestroy) => …)` | Adapters: `expressHTTPEntrypoint()` from `lakutata/adapter/express`… |
 | Subpaths of 3.x only | | `lakutata/utils`, `lakutata/security`, `lakutata/adapter/*`, `lakutata/com/{containerd,mutex,queue,i18n}` |
-| Node.js | `>=20` | `^22.13.0 \|\| >=24.11.0` |
+| Node.js | `>=20` | `>=18.10.0` |
 
 `npx @lakutata/cli info` prints the versions of the tool, of the framework and of Node.js, and the `lakutata` version
 that the project declares and the one installed. There is no upgrade command: the steps below are done by hand.
 
 ## 2. The steps
 
-- **Node.js** `^22.13.0 || >=24.11.0` (22.13 or a later 22.x, or 24.11 and later; not 23). Update `engines`, the CI
-  matrix and the base images of the Dockerfiles.
+- **Node.js** `>=18.10.0` (3.0 to 3.1 needed `^22.13.0 || >=24.11.0`). The versions 2.x needs (`>=20`) are among them:
+  `engines`, the CI matrix and the Dockerfiles can stay.
 - **A TypeScript that knows `"module": "Node20"`** (the templates use TypeScript 6): `lakutata/tsconfig.json` now sets
   it (2.x: `Node16`), and older compilers reject it.
 - **`package.json`**: `"type": "module"`, `lakutata` `^3.0.0`, the `@lakutata/*` packages at `^3.0.0` too, and
@@ -281,7 +281,7 @@ Application
 ## 6. Checking the upgrade
 
 ```bash
-node --version                      # ^22.13.0 || >=24.11.0
+node --version                      # >=18.10.0
 npm ls lakutata @lakutata/core      # one version of each
 npm run build                       # tsc without errors: no 2.x import left
 grep -rnE "process\.on\('SIG|\|\| ''|(startup|launched|beforeDestroy|acceptsOption)\(|AccessDenyException|=== 500" src

package/doc/en/WebRTC.md

@@ -224,10 +224,10 @@ export class Telemetry extends Component {
 ```
 
 An `http:` or `https:` URL uses Socket.IO (install `socket.io-client`), a `ws:` or `wss:` URL uses JSON-RPC over the
-`WebSocket` of Node.js 22 and Bun. Its options: `url`, `id` (a random UUID by default), `path` (of Socket.IO), `auth`
-(more fields of the Socket.IO handshake, a token), `timeout`, and the options of its connections (`iceTransportPolicy`,
-`icePortRange`, `iceAdditionalHostAddresses`, `codecs`, `threads`). It is `@Transient`: each `getObject()` gives a new
-client, and `close()` leaves its rooms and disconnects.
+global `WebSocket` of Node.js 22 and Bun, else over the `WebSocket` of the package `ws` (install `ws`). Its options: `url`, `id`
+(a random UUID by default), `path` (of Socket.IO), `auth` (more fields of the Socket.IO handshake, a token), `timeout`,
+and the options of its connections (`iceTransportPolicy`, `icePortRange`, `iceAdditionalHostAddresses`, `codecs`,
+`threads`). It is `@Transient`: each `getObject()` gives a new client, and `close()` leaves its rooms and disconnects.
 
 ### Calling the actions of an application
 

package/doc/zh/Application.md

@@ -8,7 +8,7 @@
 
 | 选项 | 含义 |
 |---|---|
-| `id`、`name` | 必填。应用的 ID（同时作为 `process.title`）和名称（`app.appId`、`app.appName`） |
+| `id`、`name` | 必填。应用的 ID（同时作为 `process.title`，NW.js 中除外）和名称（`app.appId`、`app.appName`） |
 | `timezone` | IANA 时区名，或 `'auto'`（默认）表示使用系统时区；写入 `TZ` |
 | `mode` | `'development'` 或 `'production'`，在环境变量未指定时生效（见第 4 节） |
 | `shutdownSignals` | 使应用优雅退出的信号（默认 `['SIGTERM', 'SIGINT']`），或 `false` |

package/doc/zh/Cache.md

@@ -250,7 +250,7 @@ Application.run(() => ({
 
 - `table` 中字母、数字和 `_` 以外的字符会被去掉。
 - 语句同步执行：等待被锁住的数据库时，语句会阻塞事件循环，最长 `busyTimeout`。
-- `better-sqlite3` 是原生插件，针对一种运行时构建：Electron 应用需要使用针对其 Electron 版本构建的 `better-sqlite3`。在 Bun 上，存储改用 `bun:sqlite`。
+- `better-sqlite3` 是原生插件，针对一种运行时构建：Electron 应用需要使用针对其 Electron 版本构建的 `better-sqlite3`；NW.js 应用会用 NW.js 的头文件重新构建它（需要 0.111.3 及以后的版本：更早的版本无法加载它）。在 Bun 上，存储改用 `bun:sqlite`。
 
 ### PostgreSQL