lakutata 3.1.3 → 3.1.4

package/README.md

@@ -144,9 +144,9 @@ on. Each package's README lists its exceptions.
   `Entrypoint.md`, `Middlewares.md`, `HTTP.md`, `CLI.md`, `ServiceCalls.md`, `GRPC.md`, `NATS.md`, `Schedules.md`,
   `Queue.md`, `Database.md`, `DatabaseDrivers.md`, `MongoEmbedded.md`, `Entities.md`, `Migrations.md`, `Cache.md`,
   `Mutex.md`, `I18n.md`, `DockerIntegration.md`, `ContainerdIntegration.md`, `Monitor.md`, `Security.md`, `DBus.md`,
-  `MCP.md`, `WebRTC.md`, `FFI.md`, `Math.md`, `Command.md`, `Workspaces.md`, `NativeAddons.md`, `Packaging.md`,
-  `Installers.md`; and the examples, in `doc/en/examples` and `doc/zh/examples`: whole applications built from the
-  templates.
+  `MCP.md`, `WebRTC.md`, `FFI.md`, `Math.md`, `Netif.md`, `Command.md`, `Workspaces.md`, `NativeAddons.md`,
+  `Packaging.md`, `Installers.md`; and the examples, in `doc/en/examples` and `doc/zh/examples`: whole applications
+  built from the templates.
 - `@lakutata/cli`: creating, building and packaging applications.
 - The official Agent Skill for AI coding assistants that work on lakutata projects:
   [lakutata.com/skill](https://lakutata.com/skill/).

package/README.zh-CN.md

@@ -121,7 +121,7 @@ Application
 ## 另见
 
 - 网站 <https://lakutata.com/zh/>：指南、示例和 API 参考，中英文都有。
-- 指南在这个包的 `doc/zh`（中文）和 `doc/en`（英文）中：`Overview.md`、`GettingStarted.md`、`ProjectStructure.md`、`UpgradingFrom2.md`、`UpgradingFrom1.md`、`Application.md`、`Objects.md`、`Injection.md`、`DTOValidation.md`、`Exceptions.md`、`Logger.md`、`Decorator.md`、`Time.md`、`HelperFunctions.md`、`Controllers.md`、`Entrypoint.md`、`Middlewares.md`、`HTTP.md`、`CLI.md`、`ServiceCalls.md`、`GRPC.md`、`NATS.md`、`Schedules.md`、`Queue.md`、`Database.md`、`DatabaseDrivers.md`、`MongoEmbedded.md`、`Entities.md`、`Migrations.md`、`Cache.md`、`Mutex.md`、`I18n.md`、`DockerIntegration.md`、`ContainerdIntegration.md`、`Monitor.md`、`Security.md`、`DBus.md`、`MCP.md`、`WebRTC.md`、`FFI.md`、`Math.md`、`Command.md`、`Workspaces.md`、`NativeAddons.md`、`Packaging.md`、`Installers.md`；示例在 `doc/zh/examples` 和 `doc/en/examples` 中：从模板构建的完整应用。
+- 指南在这个包的 `doc/zh`（中文）和 `doc/en`（英文）中：`Overview.md`、`GettingStarted.md`、`ProjectStructure.md`、`UpgradingFrom2.md`、`UpgradingFrom1.md`、`Application.md`、`Objects.md`、`Injection.md`、`DTOValidation.md`、`Exceptions.md`、`Logger.md`、`Decorator.md`、`Time.md`、`HelperFunctions.md`、`Controllers.md`、`Entrypoint.md`、`Middlewares.md`、`HTTP.md`、`CLI.md`、`ServiceCalls.md`、`GRPC.md`、`NATS.md`、`Schedules.md`、`Queue.md`、`Database.md`、`DatabaseDrivers.md`、`MongoEmbedded.md`、`Entities.md`、`Migrations.md`、`Cache.md`、`Mutex.md`、`I18n.md`、`DockerIntegration.md`、`ContainerdIntegration.md`、`Monitor.md`、`Security.md`、`DBus.md`、`MCP.md`、`WebRTC.md`、`FFI.md`、`Math.md`、`Netif.md`、`Command.md`、`Workspaces.md`、`NativeAddons.md`、`Packaging.md`、`Installers.md`；示例在 `doc/zh/examples` 和 `doc/en/examples` 中：从模板构建的完整应用。
 - `@lakutata/cli`：创建、构建和打包应用。
 - 官方 Agent Skill（智能体技能），供 AI 编程助手在 lakutata 项目中使用：<https://lakutata.com/zh/skill/>。
 

package/doc/en/GRPC.md

@@ -56,10 +56,15 @@ The options of `grpcServiceEntrypoint`:
 | `tls` | None (plain HTTP/2) | `{cert, key}` for TLS; with `ca` too, the clients must present a certificate signed by it (mutual TLS) |
 | `maxMessageSize` | 4 MiB | The largest request, before and after decompression; a larger one fails with `RESOURCE_EXHAUSTED` |
 | `compression` | `'identity'` | `'gzip'` or `'deflate'` to compress the responses for the clients that accept it. Compressed requests are always accepted |
-| `listening` | | `(address) => void`, called once the server listens; the start waits for it |
+| `listening` | | `(address, listeners) => void`, called once the server listens; the start waits for it |
+| `interface`, `family`, `strict`, `onError` | | Listen on a network interface instead of an address, as the HTTP adapters do (see [HTTP](HTTP.md), section 2); not with `host` or `socketPath` |
 | `middlewares` | | The middlewares of the actions called over gRPC, run after the ones of the entrypoint |
 | `name` | | The name of the adapter, to tell several apart |
 
+With `interface`, the package `@lakutata/netif` has to be installed. The `address` given to `listening` is then the
+first one listened on, or `null` while the interface does not exist or has no address yet, and `listeners` are the
+listeners of the interface.
+
 The server has no reflection service and no health service.
 
 ## 2. Calling them from another application
@@ -248,4 +253,5 @@ seconds by default) to complete. Then the event streams end and the server close
 
 The package also has the layers the service is built on, usable without lakutata: `GRPCConnection`, a client for any
 gRPC server (unary, server streaming and bidirectional calls, metadata, TLS); `GRPCServer`; and `encode`/`decode`, a
-protobuf codec driven by schemas. The README of `@lakutata/grpc` describes them.
+protobuf codec driven by schemas. The README of `@lakutata/grpc` describes them. `GRPCServer.listenWith()` listens
+through the listeners of network interfaces (`listenOnAll()` of `@lakutata/netif`), as the adapter does.

package/doc/en/HTTP.md

@@ -123,6 +123,8 @@ The options of `expressHTTPEntrypoint()`:
 | `fallback` | | Answers the requests outside the paths of the actions, such as the pages of a web UI (section 7) |
 | `stop` | | Called when the adapter stops, once its server is closed |
 | `heartbeat` | `15000` | How often a comment keeps the event streams alive, in milliseconds (section 5) |
+| `listening` | | `(server, listeners) => …`: called once the server listens, or once the listeners of the interface are made (see below) |
+| `interface` | | The network interface to listen on instead of an address, with `family`, `strict` and `onError` (see below) |
 
 `fastifyHTTPEntrypoint()` takes the same options, except `server` and `app`, replaced by `fastify`: a Fastify instance,
 or the options of the instance to create (`bodyLimit`, 1 MiB by default; `trustProxy`; `connectionTimeout`,
@@ -146,6 +148,38 @@ the event streams; Fastify also answers 503 to the requests that still arrive on
 progress get the `shutdownTimeout` of the entrypoint (after it, they are answered with 503), then up to one second to
 send their responses, before the remaining connections are closed, the WebSockets included.
 
+### On a network interface
+
+A device with several network interfaces often serves its pages on one of them only, and the address of that interface
+comes from DHCP and changes. With `interface`, the adapter listens on the interface instead of an address, whatever its
+addresses, and goes on listening when they change and when the interface is unplugged and plugged back. By default it
+uses the package `@lakutata/netif`, installed apart, which compiles a native addon (see [Netif](Netif.md)).
+
+```typescript
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+//The pages on eth1 only, whatever its address
+export const http = expressHTTPEntrypoint({
+    port: 8080,
+    interface: 'eth1',
+    listening: (_server, listeners): void => console.log(listeners?.map(listener => listener.addresses))
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `interface` | | The name of the interface (`'eth1'`; on Windows the name of the network connection), `{mac: '52:54:00:12:34:56'}` or `{index: 3}`; several in an array, and then `port` cannot be `0`. It cannot be given with `host` |
+| `family` | `'both'` | `'IPv4'`, `'IPv6'` or both |
+| `strict` | `false` | Fails the start where the system cannot refuse the connections that reach the addresses of the interface through another interface, and stops listening while it cannot (see [Netif](Netif.md), section 2) |
+| `onError` | the log of the application | Receives the errors of listening again while the application runs, such as a port taken by another program; the adapter retries by itself |
+| `interfaceListening` | `@lakutata/netif` | Another implementation of the listening on interfaces: an `IInterfaceListening`, the contract of lakutata that `@lakutata/netif` implements |
+
+- The interface may not exist yet when the application starts (a USB network adapter not plugged in): the start
+  succeeds, and the adapter listens once the interface appears. Until then the `addresses` of the listeners are empty.
+- The server itself does not listen, and its `address()` is `null`: the listeners give the port and the addresses.
+- `family`, `strict`, `onError` and `interfaceListening` without `interface` fail the creation of the adapter, as do
+  `interface` and `host` together.
+
 ## 3. Routes
 
 | Decorator | Methods |

package/doc/en/MCP.md

@@ -248,7 +248,8 @@ Application.run(() => ({
 |---|---|---|
 | `port`, `host`, `path` | `3000`, `'127.0.0.1'`, `'/mcp'` | Where it listens |
 | `authenticate` | | `(request) => MCPAuthInfo \| undefined`: the authentication of the client; throwing answers 401, returning `undefined` serves the request without one |
-| `allowedHosts`, `allowedOrigins` | the local names, on a local address | The `Host` and `Origin` headers accepted (403 otherwise); `false` checks none |
+| `allowedHosts`, `allowedOrigins` | the local names, on a local address or the loopback interface | The `Host` and `Origin` headers accepted (403 otherwise); `false` checks none |
+| `interface`, `family`, `strict`, `onError` | | Listen on a network interface instead of `host`, with the package `@lakutata/netif` (see [HTTP](HTTP.md), section 2) |
 | `legacy` | `'stateless'` | The clients of the revisions of 2025: served without sessions, or refused with `'reject'` |
 | `maxRequestBodySize` | 4 MiB | A larger body is answered with 413 |
 | `bus` | in memory | Where the notifications go, to share them between the instances of the application |
@@ -258,7 +259,8 @@ Application.run(() => ({
 - It serves the protocol over Streamable HTTP: the revision 2026-07-28, and the revisions of 2025 without sessions.
 - On a local address, the `Host` and `Origin` headers are checked against the local names, which protects the server
   from DNS rebinding: behind a proxy, list the names the clients use. On another address, nothing is checked unless you
-  list names.
+  list names. The same goes for `interface`: the loopback interface is checked against the local names, and on another
+  interface the clients of the network reach the server, so set `allowedHosts` and `authenticate`.
 - When the application stops, the calls in progress are answered, then the port closes.
 
 **Sharing the port of the HTTP adapter.** With `listen: false`, mount the `handler` of the adapter on the Express

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

@@ -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
 
@@ -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/ServiceCalls.md

@@ -197,7 +197,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 +284,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 +340,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 +417,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.

package/doc/zh/GRPC.md

@@ -52,10 +52,13 @@ Application.run(() => ({
 | `tls` | 无（明文 HTTP/2） | `{cert, key}` 启用 TLS；再加上 `ca` 时，客户端必须出示由它签发的证书（双向 TLS） |
 | `maxMessageSize` | 4 MiB | 请求的最大大小（解压前后都算）；超过时以 `RESOURCE_EXHAUSTED` 失败 |
 | `compression` | `'identity'` | 设为 `'gzip'` 或 `'deflate'` 时，对支持的客户端压缩响应。压缩过的请求总是可以接收 |
-| `listening` | | `(address) => void`，服务开始监听后调用；启动过程会等它完成 |
+| `listening` | | `(address, listeners) => void`，服务开始监听后调用；启动过程会等它完成 |
+| `interface`、`family`、`strict`、`onError` | | 按网口监听，而不是按地址监听，用法和 HTTP 适配器一样（见 [HTTP](HTTP.md) 第 2 节）；不能和 `host` 或 `socketPath` 一起设置 |
 | `middlewares` | | 通过 gRPC 调用的动作专用的中间件，在入口的中间件之后执行 |
 | `name` | | 适配器的名字，用来区分多个适配器 |
 
+设置 `interface` 时需要安装 `@lakutata/netif` 包。这时传给 `listening` 的 `address` 是第一个监听的地址；网口还不存在或还没有地址时是 `null`；`listeners` 是网口的监听器。
+
 服务端不提供反射服务，也不提供健康检查服务。
 
 ## 2. 从另一个应用调用
@@ -223,4 +226,4 @@ print(json.loads(response.payload) if response.success else json.loads(response.
 
 ## 8. 底层组件
 
-这个包也提供服务所依赖的底层组件，脱离 lakutata 也能使用：`GRPCConnection` 是可以调用任何 gRPC 服务端的客户端（一元调用、服务端流、双向流、元数据、TLS）；`GRPCServer` 是服务端；`encode`/`decode` 是基于 schema 的 protobuf 编解码器。详见 `@lakutata/grpc` 的 README。
+这个包也提供服务所依赖的底层组件，脱离 lakutata 也能使用：`GRPCConnection` 是可以调用任何 gRPC 服务端的客户端（一元调用、服务端流、双向流、元数据、TLS）；`GRPCServer` 是服务端；`encode`/`decode` 是基于 schema 的 protobuf 编解码器。详见 `@lakutata/grpc` 的 README。`GRPCServer.listenWith()` 也能像适配器一样，通过网口的监听器（`@lakutata/netif` 的 `listenOnAll()`）按网口监听。

package/doc/zh/HTTP.md

@@ -119,6 +119,8 @@ HTTP/1.1 400 Bad Request
 | `fallback` | | 响应动作路径之外的请求，比如 Web 界面的页面（第 7 节） |
 | `stop` | | 适配器停止、服务器关闭之后调用 |
 | `heartbeat` | `15000` | 每隔多久发送一条注释，让事件流保持连接，单位毫秒（第 5 节） |
+| `listening` | | `(server, listeners) => …`：服务器开始监听后调用；按网口监听时，在网口的监听器建好后调用（见下文） |
+| `interface` | | 按网口监听，而不是按地址监听，可以再配上 `family`、`strict` 和 `onError`（见下文） |
 
 `fastifyHTTPEntrypoint()` 的选项相同，只是没有 `server` 和 `app`，取而代之的是 `fastify`：一个 Fastify 实例，或者要创建的实例的选项（`bodyLimit`，默认 1 MiB；`trustProxy`；`connectionTimeout`、`keepAliveTimeout`、`requestTimeout`；`logger`……）。它的 `body` 选项只有 `text`，大小上限是实例的 `bodyLimit`。
 
@@ -136,6 +138,33 @@ HTTP/1.1 400 Bad Request
 
 应用停止时（见 [Entrypoint](Entrypoint.md) 第 4 节），适配器不再接受新的连接，并结束事件流；Fastify 还会对已打开的连接上仍然到达的请求返回 503。正在处理的请求可以在入口的 `shutdownTimeout` 内完成（超时后以 503 响应），之后最多再有一秒来发送响应，然后剩下的连接被关闭，WebSocket 连接也一样。
 
+### 按网口监听
+
+有多个网口的设备，常常只在其中一个网口上提供页面，而这个网口的地址来自 DHCP，会变。设置 `interface` 后，适配器监听的是这个网口，而不是某个地址：不管网口现在是什么地址，地址变化、网口拔掉再插回，都会继续监听。默认用的是 `@lakutata/netif` 包，需要另外安装，它会编译一个原生插件（见 [Netif](Netif.md)）。
+
+```typescript
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+//页面只在 eth1 上提供，不管它是什么地址
+export const http = expressHTTPEntrypoint({
+    port: 8080,
+    interface: 'eth1',
+    listening: (_server, listeners): void => console.log(listeners?.map(listener => listener.addresses))
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `interface` | | 网口的名字（`'eth1'`；Windows 上是网络连接的名字）、`{mac: '52:54:00:12:34:56'}` 或 `{index: 3}`；多个网口放在数组里，这时 `port` 不能是 `0`。不能和 `host` 一起设置 |
+| `family` | `'both'` | `'IPv4'`、`'IPv6'` 或两者都监听 |
+| `strict` | `false` | 如果系统挡不住从别的网口发往这个网口地址的连接，就让启动失败，并在挡不住的期间停止监听（见 [Netif](Netif.md) 第 2 节） |
+| `onError` | 应用的日志 | 接收应用运行期间重新监听时的错误，比如端口被别的程序占用；适配器会自己重试 |
+| `interfaceListening` | `@lakutata/netif` | 换用另一种按网口监听的实现：一个 `IInterfaceListening`，也就是 lakutata 定义、`@lakutata/netif` 实现的接口 |
+
+- 应用启动时网口可能还不存在（比如 USB 网卡还没插上）：启动照样成功，网口出现后适配器就开始监听。在那之前，监听器的 `addresses` 是空的。
+- 服务器自己不监听，它的 `address()` 是 `null`：端口和地址从监听器上读取。
+- 没有设置 `interface` 却设置了 `family`、`strict`、`onError` 或 `interfaceListening`，或者同时设置了 `interface` 和 `host`，创建适配器时就会报错。
+
 ## 3. 路由
 
 | 装饰器 | 方法 |

package/doc/zh/MCP.md

@@ -224,7 +224,8 @@ Application.run(() => ({
 |---|---|---|
 | `port`、`host`、`path` | `3000`、`'127.0.0.1'`、`'/mcp'` | 监听的位置 |
 | `authenticate` | | `(request) => MCPAuthInfo \| undefined`：客户端的身份认证；抛出错误时以 401 响应，返回 `undefined` 时不认证，照常处理请求 |
-| `allowedHosts`、`allowedOrigins` | 在本机地址上时为本机的名字 | 接受的 `Host` 和 `Origin` 请求头（否则为 403）；`false` 表示不检查 |
+| `allowedHosts`、`allowedOrigins` | 在本机地址或回环网口上时为本机的名字 | 接受的 `Host` 和 `Origin` 请求头（否则为 403）；`false` 表示不检查 |
+| `interface`、`family`、`strict`、`onError` | | 按网口监听，代替 `host`，需要安装 `@lakutata/netif` 包（见 [HTTP](HTTP.md) 第 2 节） |
 | `legacy` | `'stateless'` | 2025 年协议版本的客户端：以无会话的方式服务，或者用 `'reject'` 拒绝 |
 | `maxRequestBodySize` | 4 MiB | 更大的请求体以 413 响应 |
 | `bus` | 内存中 | 通知的去向，用于在应用的多个实例之间共享 |
@@ -232,7 +233,7 @@ Application.run(() => ({
 | `serverName`、`serverVersion`、`instructions`、`server`、`listening`、`name`、`middlewares` | | 与 stdio 相同；`server` 是 `node:http` 服务器的选项 |
 
 - 它通过 Streamable HTTP 提供协议：2026-07-28 版本，以及无会话方式的 2025 年版本。
-- 在本机地址上，`Host` 和 `Origin` 请求头会与本机的名字比对，防止 DNS 重绑定攻击：在代理之后时，要列出客户端使用的名字。在其他地址上，除非列出名字，否则不做检查。
+- 在本机地址上，`Host` 和 `Origin` 请求头会与本机的名字比对，防止 DNS 重绑定攻击：在代理之后时，要列出客户端使用的名字。在其他地址上，除非列出名字，否则不做检查。设置 `interface` 时也一样：在回环网口上与本机的名字比对；在其他网口上，网络中的客户端都能访问这个服务器，所以要设置 `allowedHosts` 和 `authenticate`。
 - 应用停止时，正在处理的调用会得到响应，然后端口关闭。
 
 **与 HTTP 适配器共用端口。** 设置 `listen: false`，在 Express 应用的 `before` 钩子中挂载适配器的 `handler`：

package/doc/zh/Netif.md

@@ -0,0 +1,207 @@
+# Lakutata Netif
+
+`@lakutata/netif` 包让 Node.js 的服务器按网口监听，而不是按地址监听。有多个网口的设备，常常只在其中一个网口上提供管理页面：这个网口的地址来自 DHCP，会变，设备开机时可能还没有；而监听 `0.0.0.0` 又会让管理页面出现在所有网口上。用这个包，服务器监听的是“eth1 这个网口”，不管它现在是什么地址，地址变化、网口拔掉再插回，都会继续监听。它不属于 `lakutata`，也不需要应用。它的特点是：
+
+- **任何服务器都能用**：`http`、`https`、`http2`、`tls`、Express 和 Fastify 都把这个网口的连接当成自己的连接处理；UDP 套接字也可以，适合只在一个网口上工作的服务（DHCP、mDNS、SSDP）。
+- **lakutata 的入口**有 `interface` 选项，可以让应用的控制器只在一个网口上提供服务（第 5 节）。
+- **系统能挡的，就让系统挡住别的网口**：在 Linux 上，套接字绑定在网口上，从别的网口发往这个网口地址的连接会被拒绝。在 Windows 和 macOS 上，监听的是这个网口的地址，`enforced` 告诉你系统会不会挡住那样的连接。
+- **网口和它们的变化**：本机每个网口的状态，以及地址、连通状态、网口出现和消失时的事件，都来自系统的通知。
+- **原生插件**：在安装这个包时编译，支持 Linux、macOS 和 Windows；也能在 Bun 和 Electron 的主进程里运行。
+
+`@lakutata/netif` 的 README 介绍了每个函数及其选项；这篇指南按用途逐一说明这个包能做什么，每种用途都给出一个例子。
+
+```bash
+npm install @lakutata/netif
+```
+
+原生插件在安装这个包时编译，所以机器上要有 Python 3 和支持 C++17 的编译器（Alpine Linux 还要内核的头文件：`apk add python3 make g++ linux-headers`）。包管理器必须运行这个包的安装脚本：npm 会运行它，可能会提示这个脚本“not yet covered by allowScripts”（运行 `npm install-scripts approve @lakutata/netif` 记录你允许它运行）；Bun 和 pnpm 只为被告知可以信任的包运行安装脚本（Bun 在 package.json 的 `trustedDependencies` 里设置，pnpm 用 `pnpm approve-builds`）。它的类型引用了 `@lakutata/core` 的类型，这是一个 peer 依赖，包管理器会一起安装；这个包运行时不会加载它。
+
+## 1. 在网口上监听
+
+`listenOn()` 让一个服务器在网口上监听。网口可以按名字、MAC 地址（`{mac: '52:54:00:12:34:56'}`，不随系统给网口起的名字变化）或序号指定；Windows 上的名字是网络连接的名字（`'以太网 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)
+```
+
+- 监听器接受连接后交给服务器，服务器像处理自己的连接一样处理它们。服务器自己并没有在监听：它的 `address()` 是 `null`，`server.close()` 也不能让监听器停下；请用 `listener.port`、`listener.addresses` 和 `listener.close()`。
+- 网口可以暂时不存在，也可以还没有地址：`listenOn()` 会立即返回，等网口能监听了就开始监听。网口拔掉再插回、地址变化时，会自动重新监听；已经建立的连接交给服务器处理。
+- 第一次监听的错误（比如端口被占用）会直接抛出；之后的错误是 `error` 事件，过一会儿会重试。请给监听器加上 `error` 的监听函数，就像对 `net.Server` 那样。
+- `family` 选择 `'IPv4'`、`'IPv6'` 或 `'both'`（默认）；`port: 0` 让系统选一个端口，重新监听时保持同一个端口。
+
+## 2. 哪些连接会被挡住
+
+另一个网络的客户端，可以自己加一条经过设备的路由，把发往管理网口地址的包从设备的另一个网口送进来。系统会不会拒绝这样的连接，就是 `enforced` 回答的问题：
+
+| | `enforced` |
+|---|---|
+| Linux | `true`：套接字绑定在网口上（`SO_BINDTODEVICE`）；Linux 5.7 以前这需要 `CAP_NET_RAW` 能力，没有的话就按地址监听，`enforced` 为 `false` |
+| Windows | 其他网口都按强主机模型收包、都没开转发时为 `true`，默认就是这样 |
+| macOS | 默认为 `false`；只有在系统设置为拒绝这样的包（`net.inet.ip.check_interface` 设为 2，IPv6 还有 `net.inet6.ip6.check_interface`）并且没开转发时才为 `true` |
+
+默认按系统允许的最好方式监听，无论如何都不会比用 `listen(port, host)` 按地址监听差；`reason` 说明为什么没有保证，以及怎样才能有。如果管理网口是一道安全边界，用 `strict: true`：没有保证就拒绝监听，运行中保证丢了就停止监听：
+
+```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. 跟踪一个网口
+
+`NetworkInterface` 给出一个网口现在的状态（`present`、`running`、`addresses` 等），并在每次变化时发出事件。事件来自系统的通知，不靠定时轮询。
+
+```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()` 也列出没有地址的网口，并带上它们的状态；`os.networkInterfaces()` 只列出有地址的网口。
+- IPv6 地址等它可用后才算：加上后大约一秒，重复地址检测结束时。
+- `close()` 停止跟踪这个网口（它的监听器也会关闭）。
+
+## 4. 网口上的 UDP
+
+`createUDPSocket()` 返回这个网口的 UDP 套接字，方法和事件和 `dgram` 的套接字一样。下面是一个只回答管理网络里发现广播的设备：
+
+```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))
+```
+
+在 Linux 上，这个套接字只接收从这个网口进来的数据，包括这个网口上的广播和用 `addMembership()` 加入的组播组，别的网口来的一概收不到。在 Windows 和 macOS 上，网口的每个地址各绑一个套接字；macOS 上这样的套接字收不到广播和组播。
+
+## 5. 在应用中使用
+
+lakutata 里自己监听端口的入口都有 `interface` 选项：`expressHTTPEntrypoint()`、`fastifyHTTPEntrypoint()`、`httpServiceEntrypoint()`、`socketIOServiceEntrypoint()`、`jsonRPCServiceEntrypoint()`、`@lakutata/grpc` 的 `grpcServiceEntrypoint()` 和 `@lakutata/mcp` 的 `httpMCPEntrypoint()`。设置后，控制器的动作就在这个网口上提供，不管它是什么地址：
+
+```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` 和 `onError` 与 `interface` 配合使用。没有设置 `onError` 时，重新监听的错误会写到应用的日志里。适配器的 `listening` 回调会拿到监听器。这些选项的说明见 [HTTP](HTTP.md) 第 2 节。
+- 网口还不存在时应用也能启动，网口出现后就能访问它的动作。
+- 入口通过 `IInterfaceListening` 按网口监听。这是 lakutata 定义的接口（来自 `@lakutata/core`），这个包实现了它，入口默认加载这个包。另一种实现可以用入口的 `interfaceListening` 选项给出；这个包的 `InterfaceListener` 就是一个 `IInterfaceListener`。
+
+不属于入口的服务器由一个组件持有：在 `startup()` 里开始监听，在 `destroy()` 里停止。网口和端口作为组件的选项。
+
+```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. 系统、运行环境和打包
+
+- **Linux** 把套接字绑定在网口上：系统会挡住别的网口，新加的地址立刻就能访问，UDP 能收到这个网口的广播和组播。Linux 5.7 以前，请给进程 `CAP_NET_RAW` 能力（`setcap cap_net_raw+ep`，或在 systemd 单元里写 `AmbientCapabilities=CAP_NET_RAW`）。
+- **Windows** 监听网口的地址；它的强主机模型会挡住别的网口，除非有网口被设成了弱主机模型（`netsh interface ipv4 set interface "<名字>" weakhostreceive=enabled`，有些负载均衡软件会这样做）或者开了转发。`reason` 会说出是哪个网口。
+- **macOS** 监听网口的地址，除非系统设置了，否则没有保证。macOS 27 对进程隐藏 MAC 地址（给出的都是 `02:00:00:00:00:00`）：在那里请按名字指定网口。
+- **Bun**：它的 `https` 服务器收到交过来的连接时不做 TLS，所以在 Bun 上 `listen()` 会拒绝它（用 `https` 选项创建的 Fastify 实例也一样）；在 Bun 上请改用 `http2.createSecureServer({key, cert, allowHTTP1: true})` 或 `tls.createServer()`。Bun 的服务器不会关闭交给它的空闲长连接，入口会自己关闭它们。交给服务器的连接不能升级为 WebSocket（在 Bun 1.4 上观察到），所以在 Bun 上，入口按网口监听时不支持 WebSocket。
+- **Electron**：在主进程里使用。
+- `lakutata package` 生成的打包文件、可执行文件和安装包会带上编译好的原生插件（`build/Release/netif.node`）：请在每个目标平台上先安装这个包，再在那里打包（见[打包](Packaging.md)和[原生插件](NativeAddons.md)）。
+
+## 7. 异常
+
+| 异常 | 什么时候 |
+|---|---|
+| `NetIfNotFoundException` | 指定的序号没有网口，指定的 MAC 有几个网口 |
+| `NetIfNotEnforcedException` | 用了 `strict`，但系统挡不住别的网口；或者运行中保证丢了（`error` 事件） |
+| `NetIfNotSupportedException` | 系统或运行环境做不到的操作：在 Linux 以外调用 `bindSocket()`，在 macOS 上给绑定在地址上的套接字加组播，在 Bun 上监听 `https` 服务器 |
+| `NetIfTimeoutException` | `waitForAddress()` 超过了 `timeout` |
+| `NetIfException` | 以上所有异常的基类；系统拒绝时，`errno` 是系统的错误码（`'EADDRINUSE'`、`'EACCES'`…） |

package/doc/zh/Overview.md

@@ -35,7 +35,7 @@
 | `lakutata/security`、`lakutata/provider/passwordHash` | 哈希、加解密、签名、`PasswordHash` 提供者 |
 | `lakutata/utils` | 辅助函数 |
 
-不在本包中的：`@lakutata/cli`（`lakutata` 命令：创建项目、执行迁移、打包应用，见 [Command](Command.md)）、`@lakutata/grpc`（gRPC 客户端、服务端和服务传输）、`@lakutata/nats`（NATS 组件和服务传输）、`@lakutata/dbus`（D-Bus）、`@lakutata/mcp`（Model Context Protocol）、`@lakutata/webrtc`（WebRTC：信令、TURN 服务器、媒体服务器、对等连接）、`@lakutata/ffi`（调用动态库中的 C 函数）和 `@lakutata/math`（符号计算和数值计算，直接作为函数使用，不需要 lakutata 应用）。
+不在本包中的：`@lakutata/cli`（`lakutata` 命令：创建项目、执行迁移、打包应用，见 [Command](Command.md)）、`@lakutata/grpc`（gRPC 客户端、服务端和服务传输）、`@lakutata/nats`（NATS 组件和服务传输）、`@lakutata/dbus`（D-Bus）、`@lakutata/mcp`（Model Context Protocol）、`@lakutata/webrtc`（WebRTC：信令、TURN 服务器、媒体服务器、对等连接）、`@lakutata/ffi`（调用动态库中的 C 函数）、`@lakutata/math`（符号计算和数值计算，直接作为函数使用，不需要 lakutata 应用）和 `@lakutata/netif`（服务器和 UDP 套接字按网口监听，不管网口的地址怎么变；本机的网口和它们的变化）。
 
 ## 指南
 
@@ -81,6 +81,7 @@
 | [WebRTC](WebRTC.md) | 点对点连接和媒体服务器（`@lakutata/webrtc`）：信令、TURN 服务器、浏览器和应用、通过数据通道调用应用的动作、WHIP 和 WHEP |
 | [FFI](FFI.md) | 调用动态库中的 C 函数（`@lakutata/ffi`）：从头文件复制的声明、结构体、回调、内存、打包 |
 | [Math](Math.md) | 数学计算（`@lakutata/math`）：公式和精确结果、方程、任意精度的十进制数、矩阵、统计、数值解法、单位 |
+| [Netif](Netif.md) | 网口（`@lakutata/netif`）：服务器按网口监听，不管网口的地址怎么变；挡住别的网口的连接；网口和它们的变化；单个网口上的 UDP |
 | [Command](Command.md) | `lakutata` 命令：创建项目、迁移、翻译、环境变量 |
 | [Workspaces](Workspaces.md) | 由多个包组成的项目：运行各个包的脚本、统一版本号、添加包 |
 | [NativeAddons](NativeAddons.md) | 用 C++ 或 Rust 编写的原生插件：创建、链接库、发布 |

package/doc/zh/ServiceCalls.md

@@ -181,7 +181,7 @@ export async function call<T>(message: Record<string, unknown>): Promise<T> {
 | `host` | 所有网络接口 | 监听的地址 |
 | `path` | `'/'` | 请求的路径；事件在它下面的 `<path>/events` |
 | `limit` | `10485760`（10 MiB） | 请求体的最大字节数 |
-| `listening` | | `(server) => …`，服务器开始监听后调用 |
+| `listening` | | `(server, listeners) => …`，服务器开始监听后调用（`listeners`：按网口监听时才有，见下文） |
 
 - 请求是发往 `path` 的 `POST`，请求体是 JSON 格式的消息。无论动作的结果如何，都以 200 和封套响应。请求体不是 JSON 时以 400 响应，超过 `limit` 时以 413 响应，其他方法或路径以 404 响应；这些响应也带有封套。
 - CORS 响应头允许任何来源，允许的方法是 `GET`、`POST` 和 `OPTIONS`，并允许任何请求头，例如 `Authorization`。
@@ -255,7 +255,7 @@ Application
 | `options` | | Socket.IO 服务器的选项：`cors`、`path`、`maxHttpBufferSize`…… |
 | `server` | | 共用的 HTTP 服务器，或者返回它的函数（见下文） |
 | `io` | | 一个已有的 Socket.IO 服务器，按原样使用 |
-| `listening` | | `(io, server) => …`，适配器就绪后调用 |
+| `listening` | | `(io, server, listeners) => …`，适配器就绪后调用 |
 
 ```typescript
 import {io, type Socket} from 'socket.io-client'
@@ -307,7 +307,7 @@ export const entrypoint = buildEntrypoints({
 | `input`、`output` | `process.stdin`、`process.stdout` | stdio 使用的流 |
 | `end` | `'application'` | stdio 的输入结束时：`'application'` 在正在处理的请求都得到响应后退出应用，`'none'` 什么都不做，或者一个函数 |
 | `heartbeat` | `30000` | WebSocket 的 ping 间隔，单位毫秒；`0` 表示不发送 |
-| `listening` | | `(server) => …`，HTTP 或 WebSocket 的服务器开始监听后调用 |
+| `listening` | | `(server, listeners) => …`，HTTP 或 WebSocket 的服务器开始监听后调用 |
 
 请求的方法名和参数构成消息：`{"method": "order.get", "params": {"id": 1}}` 就是消息 `{method: 'order.get', id: 1}`，所以动作要在模式中声明方法名：
 
@@ -378,6 +378,19 @@ $ echo '{"jsonrpc": "2.0", "id": 1, "method": "sum", "params": {"values": [1, 2,
 
 输入结束、请求都得到响应之后，应用就会退出（`end`）。
 
+### 按网口监听
+
+`httpServiceEntrypoint()`、使用自己服务器的 `socketIOServiceEntrypoint()`，以及走 HTTP 或 WebSocket 的 `jsonRPCServiceEntrypoint()`，都可以按网口监听，而不是按地址监听，不管网口现在是什么地址。这需要另外安装 `@lakutata/netif` 包。它们接受和 HTTP 适配器一样的 `interface`、`family`、`strict`、`onError` 和 `interfaceListening` 选项（见 [HTTP](HTTP.md) 第 2 节），`listening` 回调的最后一个参数是网口的监听器：
+
+```typescript
+import {httpServiceEntrypoint} from 'lakutata/com/entrypoint'
+
+//服务只在 eth1 上提供，不管它是什么地址
+export const service = httpServiceEntrypoint({port: 3000, interface: 'eth1'})
+```
+
+在 Bun 上，交给服务器的连接不能升级为 WebSocket（在 Bun 1.4 上观察到）。所以在 Bun 上，走 WebSocket 的 JSON-RPC 会启动失败；Socket.IO 也会启动失败，除非只用轮询（`options: {transports: ['polling']}`，客户端也要这样设置）。
+
 ### Electron
 
 `electronIPCServiceEntrypoint()` 在 Electron 应用的主进程中，向它的窗口提供动作。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lakutata",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "An IoC application framework for Node.js and TypeScript: one programming model for web services, CLI tools, desktop (Electron) and embedded applications.",
   "type": "module",
   "exports": {
@@ -354,18 +354,18 @@
     "mcp"
   ],
   "dependencies": {
-    "@lakutata/cache": "3.1.1",
-    "@lakutata/containerd": "3.1.1",
-    "@lakutata/core": "3.1.1",
-    "@lakutata/docker": "3.1.1",
-    "@lakutata/entrypoint": "3.1.1",
-    "@lakutata/i18n": "3.1.1",
-    "@lakutata/logger": "3.1.1",
-    "@lakutata/monitor": "3.1.1",
+    "@lakutata/cache": "3.1.4",
+    "@lakutata/containerd": "3.1.4",
+    "@lakutata/core": "3.1.4",
+    "@lakutata/docker": "3.1.4",
+    "@lakutata/entrypoint": "3.1.4",
+    "@lakutata/i18n": "3.1.4",
+    "@lakutata/logger": "3.1.4",
+    "@lakutata/monitor": "3.1.4",
     "@lakutata/mutex": "3.1.3",
-    "@lakutata/orm": "3.1.1",
-    "@lakutata/queue": "3.1.1",
-    "@lakutata/security": "3.1.1",
+    "@lakutata/orm": "3.1.4",
+    "@lakutata/queue": "3.1.4",
+    "@lakutata/security": "3.1.4",
     "@lakutata/utils": "3.1.1"
   },
   "files": [
@@ -379,6 +379,7 @@
   ],
   "peerDependencies": {
     "@inquirer/prompts": "^7.0.0 || ^8.0.0",
+    "@lakutata/netif": "~3.1.4",
     "commander": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
     "express": "^4.21.0 || ^5.0.0",
     "fastify": "^5.0.0",
@@ -403,6 +404,9 @@
     },
     "ws": {
       "optional": true
+    },
+    "@lakutata/netif": {
+      "optional": true
     }
   }
 }