lakutata 3.1.2 → 3.1.4

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

@@ -47,8 +47,10 @@ tool, a web and a desktop application, calls between services, background jobs,
 Not part of this package: `@lakutata/cli` (the `lakutata` command for creating projects, running migrations and packing
 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) and
-`@lakutata/ffi` (the C functions of native libraries).
+Context Protocol), `@lakutata/webrtc` (WebRTC: the signaling, a TURN server, a media server, peer connections),
+`@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
 
@@ -93,6 +95,8 @@ Context Protocol), `@lakutata/webrtc` (WebRTC: the signaling, a TURN server, a m
 | [MCP](MCP.md) | The tools, resources and prompts of the Model Context Protocol (`@lakutata/mcp`), over stdio and HTTP |
 | [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`：