node-netlink 0.0.4 → 0.0.6

package/README.md

@@ -1,3 +1,243 @@
 # node-netlink
-[![Build Status](https://travis-ci.org/k13-engineering/node-netlink.svg?branch=master)](https://travis-ci.org/k13-engineering/node-netlink)<br/>
-netlink bindings for node.js
+
+[![CI](https://github.com/k13-engineering/node-netlink/actions/workflows/ci.yml/badge.svg)](https://github.com/k13-engineering/node-netlink/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/node-netlink)](https://www.npmjs.com/package/node-netlink)
+
+The [netlink](https://man7.org/linux/man-pages/man7/netlink.7.html) protocol for Node.js on Linux, written in TypeScript.
+
+- **Bring your own socket.** node-netlink never opens, binds or closes a socket. You pass in a netlink socket you own, and the library speaks the protocol on top of it.
+- **Request/response matching.** `talk()` sends a request, collects all responses including multipart dumps and resolves once the kernel acknowledges it or reports an error.
+- **Synchronous where possible.** Attaching to a socket, querying its address and sending are plain function calls. Only waiting for responses of the kernel returns a promise.
+- **No native code.** The adapter for file descriptors uses the [po6](https://www.npmjs.com/package/po6) API and the poller you pass in, e.g. [@k13engineering/uv-poll](https://www.npmjs.com/package/@k13engineering/uv-poll).
+- **Checked against the C headers.** The layouts of `struct sockaddr_nl`, `struct nlmsghdr` and `struct nlmsgerr` are defined with [ya-struct](https://www.npmjs.com/package/ya-struct) and compared with `<linux/netlink.h>` in the tests, as are all constants.
+
+node-netlink handles the netlink framing. The payloads of the individual protocols, e.g. `struct ifinfomsg` and attributes of rtnetlink, are `Uint8Array`s that you format and parse yourself.
+
+## Requirements
+
+- Linux
+- Node.js 24 or newer
+
+## Installation
+
+```sh
+npm install node-netlink
+```
+
+To use the included adapter for file descriptors, install po6 with its syscall and memory backends and a poller:
+
+```sh
+npm install po6 syscall-napi buffer2address @k13engineering/uv-poll
+```
+
+## Usage
+
+### Setup
+
+Open and bind the socket with po6, then attach node-netlink to it:
+
+```ts
+import { createPoller } from "@k13engineering/uv-poll";
+import { pinBuffer } from "buffer2address";
+import { createKernelAbiFor, createLinuxKernelInterface, createPo6Api, hostAbi } from "po6";
+import { syscall, syscallNumbers } from "syscall-napi";
+import {
+  AF_NETLINK,
+  NETLINK_ROUTE,
+  createNetlinkSocket,
+  createPo6NetlinkTransport,
+  formatNetlinkAddress,
+} from "node-netlink";
+
+const kernelAbi = createKernelAbiFor({ machineAbi: hostAbi });
+const po6 = createPo6Api({
+  kernelInterface: createLinuxKernelInterface({ syscall, syscallNumbers }),
+  kernelAbi,
+  memory: { pinBuffer },
+});
+
+// <linux/net.h> and <asm-generic/fcntl.h>
+const SOCK_RAW = 3n;
+const SOCK_CLOEXEC = 0o2000000n;
+
+// your socket: opened, bound and closed by your code
+const { errno, fd } = po6.socket({ domain: AF_NETLINK, type: SOCK_RAW | SOCK_CLOEXEC, protocol: NETLINK_ROUTE });
+if (errno !== undefined) {
+  throw po6.createErrorFromErrno({ operation: "socket()", errno });
+}
+
+const { errno: bindErrno } = po6.bind({ fd, sockaddr: formatNetlinkAddress({ address: { nl_pid: 0n, nl_groups: 0n } }) });
+if (bindErrno !== undefined) {
+  throw po6.createErrorFromErrno({ operation: "bind()", errno: bindErrno });
+}
+
+// the netlink protocol on top of it
+const transport = createPo6NetlinkTransport({ fd, po6, kernelAbi, createPoller });
+const netlink = createNetlinkSocket({ transport });
+```
+
+When you are done, detach node-netlink and close the socket yourself:
+
+```ts
+netlink.detach();
+po6.close({ fd });
+```
+
+### Requests
+
+```ts
+import { NLM_F_DUMP } from "node-netlink";
+
+// <linux/rtnetlink.h>
+const RTM_GETLINK = 18n;
+
+// dump all network interfaces, the payload is a zeroed struct ifinfomsg
+const links = await netlink.talk({
+  header: { nlmsg_type: RTM_GETLINK, nlmsg_flags: NLM_F_DUMP },
+  payload: new Uint8Array(16),
+});
+
+links.forEach(({ header, payload }) => {
+  const index = new DataView(payload.buffer, payload.byteOffset).getInt32(4, true);
+  console.log(`type ${header.nlmsg_type}, interface index ${index}`);
+});
+```
+
+`talk()` rejects if the kernel reports an error, e.g. `netlink request of type 16 failed with EPERM`. The error has the `errno` attached. Use `tryTalk()` to get the errno as a value instead:
+
+```ts
+const { errno, messages } = await netlink.tryTalk({
+  header: { nlmsg_type: RTM_GETLINK },
+  payload: ifinfomsgOfInterface,
+});
+
+if (errno !== undefined) {
+  // e.g. 19 (ENODEV) if the interface does not exist
+}
+```
+
+### Notifications
+
+Bind the socket to multicast groups, e.g. `nl_groups: 1n` for `RTMGRP_LINK`. Messages that are not responses to a pending request are passed to `onMessage`:
+
+```ts
+const netlink = createNetlinkSocket({
+  transport,
+  onMessage: ({ message }) => {
+    console.log("link changed", message.header.nlmsg_type);
+  },
+  onError: ({ error }) => {
+    console.error(error);
+  },
+});
+```
+
+While attached, the poller keeps the Node.js process alive.
+
+See [examples/](examples/) for complete programs that list interfaces and monitor link changes.
+
+## API
+
+All functions take a single object of arguments. Header fields are `bigint`s, like the values ya-struct parses.
+
+### `createNetlinkSocket({ transport, onMessage?, onError?, structures? })`
+
+Attaches the netlink protocol to `transport` and starts listening on it.
+
+- `transport`: the socket to use, see [Transports](#transports)
+- `onMessage({ message })`: called for every received message that is not a response to a pending request
+- `onError({ error })`: called for errors while receiving, e.g. `ENOBUFS` when the receive buffer overflowed and messages were lost. Without a handler, such errors are thrown asynchronously as uncaught exceptions.
+- `structures`: layouts of the kernel structures, `hostStructures` by default
+
+Returns:
+
+| Member | Description |
+| --- | --- |
+| `nl_pid`, `nl_groups` | the address the socket is bound to, as reported by the transport |
+| `talk({ header, payload, timeoutMs? })` | sends a request and resolves with all responses, rejects if the kernel reports an error |
+| `tryTalk({ header, payload, timeoutMs? })` | like `talk()`, but resolves with `{ errno, messages }`. `errno` is `undefined` on success |
+| `send({ header, payload })` | sends a message without waiting for a response and returns `{ nlmsg_seq }`. `nlmsg_flags` defaults to `NLM_F_REQUEST`, `nlmsg_seq` to the next sequence number |
+| `detach()` | stops listening and rejects pending requests. The socket stays open, closing it is up to you. Calling it again has no effect |
+
+For `talk()` and `tryTalk()`, `header` is `{ nlmsg_type, nlmsg_flags? }`. `NLM_F_REQUEST` and `NLM_F_ACK` are always set, and the sequence number is assigned automatically. A request completes with the acknowledgement (`NLMSG_ERROR`) or, for dumps, with `NLMSG_DONE`. `timeoutMs` defaults to 10 seconds.
+
+A message is `{ header: { nlmsg_type, nlmsg_flags, nlmsg_seq, nlmsg_pid }, payload: Uint8Array }`. The responses of `talk()` and `tryTalk()` don't include the terminating `NLMSG_ERROR` or `NLMSG_DONE`.
+
+### Transports
+
+A transport is the socket node-netlink talks through:
+
+```ts
+type TNetlinkTransport = {
+  // the address the socket is bound to
+  address: { nl_pid: bigint, nl_groups: bigint };
+  // sends a datagram to the kernel, throws on failure
+  send: (args: { data: Uint8Array }) => void;
+  // passes received datagrams to onData until stop() is called
+  listen: (args: {
+    onData: (args: { data: Uint8Array }) => void;
+    onError: (args: { error: Error }) => void;
+  }) => { stop: () => void };
+};
+```
+
+Implement it yourself, e.g. as a fake in tests, or adapt a file descriptor with `createPo6NetlinkTransport({ fd, po6, kernelAbi, createPoller, structures? })`:
+
+- `fd`: a netlink socket, opened and bound by you. Blocking and non-blocking sockets both work, as it receives with `MSG_DONTWAIT`.
+- `po6`: an object with `getsockname()`, `sendmsg()`, `recvmsg()` and `createErrorFromErrno()` of the po6 API
+- `kernelAbi`: the po6 kernel ABI, for the `MSG_*` constants and errno values
+- `createPoller({ fd })`: returns a poller with `armOnce({ readable, error })` and `close()`, like `createPoller` of @k13engineering/uv-poll
+
+The adapter queries the address with `getsockname()` when it is created and throws if `fd` is not a netlink socket. `listen()` creates a poller, `stop()` closes it. The file descriptor is never closed.
+
+### Messages
+
+| Function | Description |
+| --- | --- |
+| `parseMessages({ data, structures })` | splits a datagram into its messages, throws if it is malformed |
+| `formatMessage({ message, structures })` | formats a message, `nlmsg_len` is calculated |
+| `errnoOfMessage({ message, structures })` | the errno of an `NLMSG_ERROR` or `NLMSG_DONE`, `undefined` for acknowledgements and other messages |
+| `nlmsgAlign({ length })` | rounds up to the netlink alignment of 4 bytes |
+| `formatNetlinkAddress({ address, structures? })` | formats a `struct sockaddr_nl`, e.g. for `bind()` |
+| `createErrorFromErrno({ operation, errno })` | creates the errors `talk()` rejects with |
+
+Pass `hostStructures` as `structures`, or `createNetlinkStructuresFor({ abi })` for another byte order. The ya-struct definitions are exported as `sockaddrNlDefinition`, `nlmsghdrDefinition` and `nlmsgerrDefinition`.
+
+### Constants
+
+`AF_NETLINK`, the protocol families `NETLINK_*`, the header flags `NLM_F_*` and the message types `NLMSG_*` of `<linux/netlink.h>` are exported as `bigint`s.
+
+## Migrating from 0.0.x
+
+- node-netlink no longer creates sockets. Replace `netlink.open({ family, pid, groups })` with your own `socket()` and `bind()`, see [Setup](#setup), and `createNetlinkSocket({ transport })`. The new function is synchronous.
+- `close()` is replaced by `detach()`, which leaves the socket open. Close it yourself afterwards.
+- The package is an ES module with named exports, there is no default export anymore.
+- `talk(message, { timeout })` is now `talk({ header, payload, timeoutMs })`. `NLM_F_REQUEST` and `NLM_F_ACK` are set automatically instead of being required.
+- `tryTalk()` resolves with `{ errno, messages }` instead of `{ errorCode, packets }`. `errno` is `undefined` instead of `0` on success.
+- `on("message", listener)` is replaced by the `onMessage` and `onError` options. Responses to pending requests are no longer passed to it.
+- `createErrorFromErrorCode({ errorCode })` is now `createErrorFromErrno({ operation, errno })`.
+- po6-socket was replaced by po6, which needs no native code of its own.
+
+## Development
+
+```sh
+npm ci
+npm run build       # transpile to dist/
+npm run type-check
+npm run test        # mocha with c8, 100% coverage required
+npm run lint
+```
+
+The sources are in `lib/`, tests are next to them as `*.spec.ts`:
+
+- `lib/netlink-socket.ts`: requests, responses and sequence numbers on top of an injected transport
+- `lib/po6-transport.ts`: the transport for a file descriptor, using injected po6 syscalls and an injected poller
+- `lib/message.ts`, `lib/structures.ts`, `lib/constants.ts`, `lib/errno.ts`: framing, structure layouts, constants and errors
+
+The unit tests use the fakes in `lib/test-support/`. `lib/index.spec.ts` opens real sockets with `lib/test-support/host-socket.ts` and talks to the kernel of the host via `NETLINK_ROUTE`, which needs no privileges. The structure layouts and constants are compared with the C headers by compiling C programs, so `gcc` and the Linux headers are required.
+
+Releases are published by pushing a tag like `v0.1.0`, which builds the package, merges `package.npm.json` into `package.json` and sets the version.
+
+## License
+
+LGPL-2.1, see [LICENSE](LICENSE).

package/dist/lib/constants.d.ts

@@ -0,0 +1,47 @@
+declare const AF_NETLINK = 16n;
+declare const NETLINK_ROUTE = 0n;
+declare const NETLINK_UNUSED = 1n;
+declare const NETLINK_USERSOCK = 2n;
+declare const NETLINK_FIREWALL = 3n;
+declare const NETLINK_SOCK_DIAG = 4n;
+declare const NETLINK_NFLOG = 5n;
+declare const NETLINK_XFRM = 6n;
+declare const NETLINK_SELINUX = 7n;
+declare const NETLINK_ISCSI = 8n;
+declare const NETLINK_AUDIT = 9n;
+declare const NETLINK_FIB_LOOKUP = 10n;
+declare const NETLINK_CONNECTOR = 11n;
+declare const NETLINK_NETFILTER = 12n;
+declare const NETLINK_IP6_FW = 13n;
+declare const NETLINK_DNRTMSG = 14n;
+declare const NETLINK_KOBJECT_UEVENT = 15n;
+declare const NETLINK_GENERIC = 16n;
+declare const NETLINK_SCSITRANSPORT = 18n;
+declare const NETLINK_ECRYPTFS = 19n;
+declare const NETLINK_RDMA = 20n;
+declare const NETLINK_CRYPTO = 21n;
+declare const NETLINK_SMC = 22n;
+declare const NLM_F_REQUEST = 1n;
+declare const NLM_F_MULTI = 2n;
+declare const NLM_F_ACK = 4n;
+declare const NLM_F_ECHO = 8n;
+declare const NLM_F_DUMP_INTR = 16n;
+declare const NLM_F_DUMP_FILTERED = 32n;
+declare const NLM_F_ROOT = 256n;
+declare const NLM_F_MATCH = 512n;
+declare const NLM_F_ATOMIC = 1024n;
+declare const NLM_F_DUMP = 768n;
+declare const NLM_F_REPLACE = 256n;
+declare const NLM_F_EXCL = 512n;
+declare const NLM_F_CREATE = 1024n;
+declare const NLM_F_APPEND = 2048n;
+declare const NLM_F_NONREC = 256n;
+declare const NLM_F_BULK = 512n;
+declare const NLM_F_CAPPED = 256n;
+declare const NLM_F_ACK_TLVS = 512n;
+declare const NLMSG_NOOP = 1n;
+declare const NLMSG_ERROR = 2n;
+declare const NLMSG_DONE = 3n;
+declare const NLMSG_OVERRUN = 4n;
+declare const NLMSG_MIN_TYPE = 16n;
+export { AF_NETLINK, NETLINK_ROUTE, NETLINK_UNUSED, NETLINK_USERSOCK, NETLINK_FIREWALL, NETLINK_SOCK_DIAG, NETLINK_NFLOG, NETLINK_XFRM, NETLINK_SELINUX, NETLINK_ISCSI, NETLINK_AUDIT, NETLINK_FIB_LOOKUP, NETLINK_CONNECTOR, NETLINK_NETFILTER, NETLINK_IP6_FW, NETLINK_DNRTMSG, NETLINK_KOBJECT_UEVENT, NETLINK_GENERIC, NETLINK_SCSITRANSPORT, NETLINK_ECRYPTFS, NETLINK_RDMA, NETLINK_CRYPTO, NETLINK_SMC, NLM_F_REQUEST, NLM_F_MULTI, NLM_F_ACK, NLM_F_ECHO, NLM_F_DUMP_INTR, NLM_F_DUMP_FILTERED, NLM_F_ROOT, NLM_F_MATCH, NLM_F_ATOMIC, NLM_F_DUMP, NLM_F_REPLACE, NLM_F_EXCL, NLM_F_CREATE, NLM_F_APPEND, NLM_F_NONREC, NLM_F_BULK, NLM_F_CAPPED, NLM_F_ACK_TLVS, NLMSG_NOOP, NLMSG_ERROR, NLMSG_DONE, NLMSG_OVERRUN, NLMSG_MIN_TYPE, };

package/dist/lib/constants.js

@@ -0,0 +1,118 @@
+// values from <linux/netlink.h> and <linux/socket.h>, shared by all Linux architectures
+
+const AF_NETLINK = 16n;
+
+// netlink protocol families, passed as `family` when opening a socket
+const NETLINK_ROUTE = 0n;
+const NETLINK_UNUSED = 1n;
+const NETLINK_USERSOCK = 2n;
+const NETLINK_FIREWALL = 3n;
+const NETLINK_SOCK_DIAG = 4n;
+const NETLINK_NFLOG = 5n;
+const NETLINK_XFRM = 6n;
+const NETLINK_SELINUX = 7n;
+const NETLINK_ISCSI = 8n;
+const NETLINK_AUDIT = 9n;
+const NETLINK_FIB_LOOKUP = 10n;
+const NETLINK_CONNECTOR = 11n;
+const NETLINK_NETFILTER = 12n;
+const NETLINK_IP6_FW = 13n;
+const NETLINK_DNRTMSG = 14n;
+const NETLINK_KOBJECT_UEVENT = 15n;
+const NETLINK_GENERIC = 16n;
+const NETLINK_SCSITRANSPORT = 18n;
+const NETLINK_ECRYPTFS = 19n;
+const NETLINK_RDMA = 20n;
+const NETLINK_CRYPTO = 21n;
+const NETLINK_SMC = 22n;
+
+// flags of struct nlmsghdr
+const NLM_F_REQUEST = 0x01n;
+const NLM_F_MULTI = 0x02n;
+const NLM_F_ACK = 0x04n;
+const NLM_F_ECHO = 0x08n;
+const NLM_F_DUMP_INTR = 0x10n;
+const NLM_F_DUMP_FILTERED = 0x20n;
+
+// modifiers to GET requests
+const NLM_F_ROOT = 0x100n;
+const NLM_F_MATCH = 0x200n;
+const NLM_F_ATOMIC = 0x400n;
+const NLM_F_DUMP = 0x300n;
+
+// modifiers to NEW requests
+const NLM_F_REPLACE = 0x100n;
+const NLM_F_EXCL = 0x200n;
+const NLM_F_CREATE = 0x400n;
+const NLM_F_APPEND = 0x800n;
+
+// modifiers to DELETE requests
+const NLM_F_NONREC = 0x100n;
+const NLM_F_BULK = 0x200n;
+
+// flags for ACK messages
+const NLM_F_CAPPED = 0x100n;
+const NLM_F_ACK_TLVS = 0x200n;
+
+// reserved control message types
+const NLMSG_NOOP = 0x1n;
+const NLMSG_ERROR = 0x2n;
+const NLMSG_DONE = 0x3n;
+const NLMSG_OVERRUN = 0x4n;
+const NLMSG_MIN_TYPE = 0x10n;
+
+export {
+  AF_NETLINK,
+
+  NETLINK_ROUTE,
+  NETLINK_UNUSED,
+  NETLINK_USERSOCK,
+  NETLINK_FIREWALL,
+  NETLINK_SOCK_DIAG,
+  NETLINK_NFLOG,
+  NETLINK_XFRM,
+  NETLINK_SELINUX,
+  NETLINK_ISCSI,
+  NETLINK_AUDIT,
+  NETLINK_FIB_LOOKUP,
+  NETLINK_CONNECTOR,
+  NETLINK_NETFILTER,
+  NETLINK_IP6_FW,
+  NETLINK_DNRTMSG,
+  NETLINK_KOBJECT_UEVENT,
+  NETLINK_GENERIC,
+  NETLINK_SCSITRANSPORT,
+  NETLINK_ECRYPTFS,
+  NETLINK_RDMA,
+  NETLINK_CRYPTO,
+  NETLINK_SMC,
+
+  NLM_F_REQUEST,
+  NLM_F_MULTI,
+  NLM_F_ACK,
+  NLM_F_ECHO,
+  NLM_F_DUMP_INTR,
+  NLM_F_DUMP_FILTERED,
+
+  NLM_F_ROOT,
+  NLM_F_MATCH,
+  NLM_F_ATOMIC,
+  NLM_F_DUMP,
+
+  NLM_F_REPLACE,
+  NLM_F_EXCL,
+  NLM_F_CREATE,
+  NLM_F_APPEND,
+
+  NLM_F_NONREC,
+  NLM_F_BULK,
+
+  NLM_F_CAPPED,
+  NLM_F_ACK_TLVS,
+
+  NLMSG_NOOP,
+  NLMSG_ERROR,
+  NLMSG_DONE,
+  NLMSG_OVERRUN,
+  NLMSG_MIN_TYPE,
+};

package/dist/lib/errno.d.ts

@@ -0,0 +1,9 @@
+type TErrorWithErrno = Error & {
+    errno: number;
+};
+declare const createErrorFromErrno: ({ operation, errno }: {
+    operation: string;
+    errno: number;
+}) => TErrorWithErrno;
+export { createErrorFromErrno, };
+export type { TErrorWithErrno, };

package/dist/lib/errno.js

@@ -0,0 +1,27 @@
+import { createKernelAbiFor, hostAbi } from "po6";
+
+/*type TErrorWithErrno = Error & {
+  errno: number;
+};*/
+
+const { errnoCodes } = createKernelAbiFor({ machineAbi: hostAbi });
+
+// aliases like EWOULDBLOCK follow their canonical name, so the first name of an errno wins
+const errnoNames = Object.entries(errnoCodes).reduce((names, [name, errno]) => {
+  return names.has(errno) ? names : new Map([...names, [errno, name]]);
+}, new Map/*<number, string>*/());
+
+const createErrorFromErrno = ({ operation, errno }/*: { operation: string, errno: number }*/)/*: TErrorWithErrno*/ => {
+  const name = errnoNames.get(errno) ?? `unknown errno ${errno}`;
+
+  // eslint-disable-next-line fp/no-mutating-assign
+  return Object.assign(Error(`${operation} failed with ${name}`), { errno });
+};
+
+export {
+  createErrorFromErrno,
+};
+
+/*export type {
+  TErrorWithErrno,
+};*/

package/dist/lib/index.d.ts

@@ -0,0 +1,12 @@
+import { createErrorFromErrno } from "./errno.js";
+import { createNetlinkSocket } from "./netlink-socket.js";
+import { createPo6NetlinkTransport } from "./po6-transport.js";
+import { errnoOfMessage, formatMessage, nlmsgAlign, parseMessages } from "./message.js";
+import { createNetlinkStructuresFor, formatNetlinkAddress, hostStructures, nlmsgerrDefinition, nlmsghdrDefinition, sockaddrNlDefinition } from "./structures.js";
+export * from "./constants.js";
+export { createNetlinkSocket, createPo6NetlinkTransport, parseMessages, formatMessage, errnoOfMessage, nlmsgAlign, createErrorFromErrno, formatNetlinkAddress, createNetlinkStructuresFor, hostStructures, sockaddrNlDefinition, nlmsghdrDefinition, nlmsgerrDefinition, };
+export type { TNetlinkAddress, TNetlinkTransport, TNetlinkSocket, TCreateNetlinkSocketArgs, TTalkArgs, TTryTalkResult, TRequestHeader, TSendHeader, } from "./netlink-socket.ts";
+export type { TNetlinkHeader, TNetlinkMessage } from "./message.ts";
+export type { TNetlinkStructures } from "./structures.ts";
+export type { TErrorWithErrno } from "./errno.ts";
+export type { TPo6NetlinkSyscalls, TPoller, TCreatePoller, TCreatePo6NetlinkTransportArgs, } from "./po6-transport.ts";

package/dist/lib/index.js

@@ -0,0 +1,52 @@
+import { createErrorFromErrno } from "./errno.js";
+import { createNetlinkSocket } from "./netlink-socket.js";
+import { createPo6NetlinkTransport } from "./po6-transport.js";
+import { errnoOfMessage, formatMessage, nlmsgAlign, parseMessages } from "./message.js";
+import {
+  createNetlinkStructuresFor,
+  formatNetlinkAddress,
+  hostStructures,
+  nlmsgerrDefinition,
+  nlmsghdrDefinition,
+  sockaddrNlDefinition
+} from "./structures.js";
+
+export * from "./constants.js";
+
+export {
+  createNetlinkSocket,
+  createPo6NetlinkTransport,
+
+  parseMessages,
+  formatMessage,
+  errnoOfMessage,
+  nlmsgAlign,
+  createErrorFromErrno,
+
+  formatNetlinkAddress,
+  createNetlinkStructuresFor,
+  hostStructures,
+  sockaddrNlDefinition,
+  nlmsghdrDefinition,
+  nlmsgerrDefinition,
+};
+
+/*export type {
+  TNetlinkAddress,
+  TNetlinkTransport,
+  TNetlinkSocket,
+  TCreateNetlinkSocketArgs,
+  TTalkArgs,
+  TTryTalkResult,
+  TRequestHeader,
+  TSendHeader,
+} from "./netlink-socket.ts";*/
+/*export type { TNetlinkHeader, TNetlinkMessage } from "./message.ts";*/
+/*export type { TNetlinkStructures } from "./structures.ts";*/
+/*export type { TErrorWithErrno } from "./errno.ts";*/
+/*export type {
+  TPo6NetlinkSyscalls,
+  TPoller,
+  TCreatePoller,
+  TCreatePo6NetlinkTransportArgs,
+} from "./po6-transport.ts";*/

package/dist/lib/message.d.ts

@@ -0,0 +1,45 @@
+import type { TNetlinkStructures } from "./structures.js";
+type TNetlinkHeader = {
+    nlmsg_type: bigint;
+    nlmsg_flags: bigint;
+    nlmsg_seq: bigint;
+    nlmsg_pid: bigint;
+};
+type TNetlinkMessage = {
+    header: TNetlinkHeader;
+    payload: Uint8Array;
+};
+declare const nlmsgAlign: ({ length }: {
+    length: number;
+}) => number;
+/**
+ * Splits a received datagram into its netlink messages.
+ * Throws if the datagram is malformed.
+ */
+declare const parseMessages: ({ data, structures }: {
+    data: Uint8Array;
+    structures: TNetlinkStructures;
+}) => TNetlinkMessage[];
+/**
+ * Formats a netlink message, nlmsg_len is calculated from the payload.
+ */
+declare const formatMessage: ({ message, structures }: {
+    message: TNetlinkMessage;
+    structures: TNetlinkStructures;
+}) => Uint8Array;
+/**
+ * Whether the message terminates a request: NLMSG_ERROR (including acknowledgements) or NLMSG_DONE.
+ */
+declare const isTerminatingMessage: ({ message }: {
+    message: TNetlinkMessage;
+}) => boolean;
+/**
+ * Extracts the errno of an NLMSG_ERROR or NLMSG_DONE message.
+ * Returns `undefined` for an acknowledgement (error 0) and for other message types.
+ */
+declare const errnoOfMessage: ({ message, structures }: {
+    message: TNetlinkMessage;
+    structures: TNetlinkStructures;
+}) => number | undefined;
+export { nlmsgAlign, parseMessages, formatMessage, errnoOfMessage, isTerminatingMessage, };
+export type { TNetlinkHeader, TNetlinkMessage, };

package/dist/lib/message.js

@@ -0,0 +1,130 @@
+import { NLMSG_DONE, NLMSG_ERROR } from "./constants.js";
+/*import type { TNetlinkStructures } from "./structures.ts";*/
+
+/*type TNetlinkHeader = {
+  nlmsg_type: bigint;
+  nlmsg_flags: bigint;
+  nlmsg_seq: bigint;
+  nlmsg_pid: bigint;
+};*/
+
+/*type TNetlinkMessage = {
+  header: TNetlinkHeader;
+  payload: Uint8Array;
+};*/
+
+const NLMSG_ALIGNTO = 4;
+
+const nlmsgAlign = ({ length }/*: { length: number }*/) => {
+  return Math.ceil(length / NLMSG_ALIGNTO) * NLMSG_ALIGNTO;
+};
+
+const parseOneMessage = ({ data, structures }/*: { data: Uint8Array, structures: TNetlinkStructures }*/) => {
+  const headerSize = structures.nlmsghdr.size;
+
+  if (data.length < headerSize) {
+    throw Error(`malformed netlink message: ${data.length} bytes left, but a header needs ${headerSize} bytes`);
+  }
+
+  const { nlmsg_len, ...header } = structures.nlmsghdr.parse({ data: data.subarray(0, headerSize) });
+  const messageLength = Number(nlmsg_len);
+
+  if (messageLength < headerSize || messageLength > data.length) {
+    throw Error(`malformed netlink message: nlmsg_len ${messageLength} is out of range [${headerSize}, ${data.length}]`);
+  }
+
+  // copy, so the payload does not keep the whole receive buffer alive
+  const payload = data.slice(headerSize, messageLength);
+
+  return {
+    message: { header, payload },
+    space: nlmsgAlign({ length: messageLength }),
+  };
+};
+
+/**
+ * Splits a received datagram into its netlink messages.
+ * Throws if the datagram is malformed.
+ */
+const parseMessages = ({ data, structures }/*: { data: Uint8Array, structures: TNetlinkStructures }*/)/*: TNetlinkMessage[]*/ => {
+  let messages/*: TNetlinkMessage[]*/ = [];
+  let remaining = data;
+
+  while (remaining.length > 0) {
+    const { message, space } = parseOneMessage({ data: remaining, structures });
+    messages = [...messages, message];
+    remaining = remaining.subarray(space);
+  }
+
+  return messages;
+};
+
+/**
+ * Formats a netlink message, nlmsg_len is calculated from the payload.
+ */
+const formatMessage = ({ message, structures }/*: { message: TNetlinkMessage, structures: TNetlinkStructures }*/)/*: Uint8Array*/ => {
+  const { header, payload } = message;
+
+  const headerAsBuffer = structures.nlmsghdr.format({
+    value: {
+      ...header,
+      nlmsg_len: BigInt(structures.nlmsghdr.size + payload.length),
+    }
+  });
+
+  const result = new Uint8Array(headerAsBuffer.length + payload.length);
+  result.set(headerAsBuffer, 0);
+  result.set(payload, headerAsBuffer.length);
+  return result;
+};
+
+/**
+ * Whether the message terminates a request: NLMSG_ERROR (including acknowledgements) or NLMSG_DONE.
+ */
+const isTerminatingMessage = ({ message }/*: { message: TNetlinkMessage }*/) => {
+  const { nlmsg_type } = message.header;
+  return nlmsg_type === NLMSG_ERROR || nlmsg_type === NLMSG_DONE;
+};
+
+const readInt32 = ({ payload, structures }/*: { payload: Uint8Array, structures: TNetlinkStructures }*/) => {
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  return view.getInt32(0, structures.abi.endianness === "little");
+};
+
+/**
+ * Extracts the errno of an NLMSG_ERROR or NLMSG_DONE message.
+ * Returns `undefined` for an acknowledgement (error 0) and for other message types.
+ */
+const errnoOfMessage = ({ message, structures }/*: { message: TNetlinkMessage, structures: TNetlinkStructures }*/)/*: number | undefined*/ => {
+  if (!isTerminatingMessage({ message })) {
+    return undefined;
+  }
+
+  const { header, payload } = message;
+
+  // NLMSG_DONE carries an int, NLMSG_ERROR a struct nlmsgerr starting with an int
+  if (payload.length < 4) {
+    throw Error(`malformed netlink message: payload of type ${header.nlmsg_type} too short for an error code`);
+  }
+
+  const error = readInt32({ payload, structures });
+
+  if (error === 0) {
+    return undefined;
+  }
+
+  return -error;
+};
+
+export {
+  nlmsgAlign,
+  parseMessages,
+  formatMessage,
+  errnoOfMessage,
+  isTerminatingMessage,
+};
+
+/*export type {
+  TNetlinkHeader,
+  TNetlinkMessage,
+};*/