node-netlink 0.0.3 → 0.0.5

package/dist/lib/netlink-socket.d.ts

@@ -0,0 +1,74 @@
+import { type TNetlinkMessage } from "./message.js";
+import { type TNetlinkStructures } from "./structures.js";
+type TNetlinkAddress = {
+    nl_pid: bigint;
+    nl_groups: bigint;
+};
+/**
+ * A netlink socket owned by the caller, opened and bound outside of this library.
+ *
+ * This is the seam between the netlink protocol handling and the operating system.
+ * `createPo6NetlinkTransport()` adapts a file descriptor, tests inject fakes.
+ */
+type TNetlinkTransport = {
+    address: TNetlinkAddress;
+    send: (args: {
+        data: Uint8Array;
+    }) => void;
+    listen: (args: {
+        onData: (args: {
+            data: Uint8Array;
+        }) => void;
+        onError: (args: {
+            error: Error;
+        }) => void;
+    }) => {
+        stop: () => void;
+    };
+};
+type TRequestHeader = {
+    nlmsg_type: bigint;
+    nlmsg_flags?: bigint;
+};
+type TSendHeader = TRequestHeader & {
+    nlmsg_seq?: bigint;
+    nlmsg_pid?: bigint;
+};
+type TTalkArgs = {
+    header: TRequestHeader;
+    payload: Uint8Array;
+    timeoutMs?: number;
+};
+type TTryTalkResult = {
+    errno: number | undefined;
+    messages: TNetlinkMessage[];
+};
+type TNetlinkSocket = {
+    nl_pid: bigint;
+    nl_groups: bigint;
+    send: (args: {
+        header: TSendHeader;
+        payload: Uint8Array;
+    }) => {
+        nlmsg_seq: bigint;
+    };
+    tryTalk: (args: TTalkArgs) => Promise<TTryTalkResult>;
+    talk: (args: TTalkArgs) => Promise<TNetlinkMessage[]>;
+    detach: () => void;
+};
+type TCreateNetlinkSocketArgs = {
+    transport: TNetlinkTransport;
+    onMessage?: (args: {
+        message: TNetlinkMessage;
+    }) => void;
+    onError?: (args: {
+        error: Error;
+    }) => void;
+    structures?: TNetlinkStructures;
+};
+declare const seqAfter: ({ seq }: {
+    seq: bigint;
+}) => bigint;
+declare const createNetlinkSocket: ({ transport, onMessage, onError, structures, }: TCreateNetlinkSocketArgs) => TNetlinkSocket;
+export { createNetlinkSocket, seqAfter, };
+export type { TNetlinkAddress, TNetlinkTransport, TNetlinkSocket, TCreateNetlinkSocketArgs, TTalkArgs, TTryTalkResult, TRequestHeader, TSendHeader, };

package/dist/lib/netlink-socket.js

@@ -0,0 +1,314 @@
+import { NLM_F_ACK, NLM_F_REQUEST } from "./constants.js";
+import {
+  errnoOfMessage,
+  formatMessage,
+  isTerminatingMessage,
+  parseMessages,
+  /*type TNetlinkMessage
+*/} from "./message.js";
+import { createErrorFromErrno } from "./errno.js";
+import { hostStructures, /*type TNetlinkStructures */} from "./structures.js";
+
+/*type TNetlinkAddress = {
+  nl_pid: bigint;
+  nl_groups: bigint;
+};*/
+
+/**
+ * A netlink socket owned by the caller, opened and bound outside of this library.
+ *
+ * This is the seam between the netlink protocol handling and the operating system.
+ * `createPo6NetlinkTransport()` adapts a file descriptor, tests inject fakes.
+ */
+/*type TNetlinkTransport = {
+  // the address the socket is bound to
+  address: TNetlinkAddress;
+  // sends a datagram to the kernel, throws on failure
+  send: (args: { data: Uint8Array }) => void;
+  // starts passing received datagrams to onData until stop() is called
+  listen: (args: {
+    onData: (args: { data: Uint8Array }) => void;
+    onError: (args: { error: Error }) => void;
+  }) => { stop: () => void };
+};*/
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_SEQ = 0xFFFF_FFFFn;
+
+/*type TRequestHeader = {
+  nlmsg_type: bigint;
+  nlmsg_flags?: bigint;
+};*/
+
+/*type TSendHeader = TRequestHeader & {
+  nlmsg_seq?: bigint;
+  nlmsg_pid?: bigint;
+};*/
+
+/*type TTalkArgs = {
+  header: TRequestHeader;
+  payload: Uint8Array;
+  timeoutMs?: number;
+};*/
+
+/*type TTryTalkResult = {
+  // undefined if the request succeeded
+  errno: number | undefined;
+  // all responses except the terminating NLMSG_ERROR or NLMSG_DONE
+  messages: TNetlinkMessage[];
+};*/
+
+/*type TNetlinkSocket = {
+  // port id the socket is bound to
+  nl_pid: bigint;
+  // multicast groups the socket is bound to
+  nl_groups: bigint;
+
+  // sends a message without waiting for a response, returns the sequence number used
+  send: (args: { header: TSendHeader, payload: Uint8Array }) => { nlmsg_seq: bigint };
+  // sends a request and resolves with all responses, or the errno the kernel reported
+  tryTalk: (args: TTalkArgs) => Promise<TTryTalkResult>;
+  // like tryTalk, but rejects if the kernel reported an error
+  talk: (args: TTalkArgs) => Promise<TNetlinkMessage[]>;
+  // stops listening on the transport and rejects pending requests, the transport itself is left open
+  detach: () => void;
+};*/
+
+/*type TCreateNetlinkSocketArgs = {
+  transport: TNetlinkTransport;
+  // called for every received message that is not a response to a pending request
+  onMessage?: (args: { message: TNetlinkMessage }) => void;
+  // called for errors while receiving, if omitted such errors are thrown asynchronously
+  onError?: (args: { error: Error }) => void;
+  // layouts of the kernel structures, the ones of the host by default
+  structures?: TNetlinkStructures;
+};*/
+
+/*type TPendingRequest = {
+  messages: TNetlinkMessage[];
+  resolve: (result: TTryTalkResult) => void;
+  reject: (error: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
+};*/
+
+// sequence numbers are 32 bit, 0 is skipped as it is used by notifications
+const seqAfter = ({ seq }/*: { seq: bigint }*/) => {
+  return seq === MAX_SEQ ? 1n : seq + 1n;
+};
+
+// requests sent to us by other sockets are never responses, even if their sequence number matches
+const isRequest = ({ message }/*: { message: TNetlinkMessage }*/) => {
+  return (message.header.nlmsg_flags & NLM_F_REQUEST) !== 0n;
+};
+
+// errors without an onError handler must not go unnoticed, so they surface as uncaught exceptions
+const throwAsynchronously = ({ error }/*: { error: Error }*/) => {
+  queueMicrotask(() => {
+    throw error;
+  });
+};
+
+const createSeqAllocator = () => {
+  let nextSeq = 1n;
+
+  return () => {
+    const seq = nextSeq;
+    nextSeq = seqAfter({ seq });
+    return seq;
+  };
+};
+
+const createNetlinkSocket = ({
+  transport,
+  onMessage,
+  onError = throwAsynchronously,
+  structures = hostStructures,
+}/*: TCreateNetlinkSocketArgs*/)/*: TNetlinkSocket*/ => {
+
+  let detached = false;
+  let pendingRequests/*: Record<string, TPendingRequest>*/ = {};
+
+  const removePendingRequest = ({ seq }/*: { seq: bigint }*/) => {
+    const { [seq.toString()]: request, ...otherRequests } = pendingRequests;
+    pendingRequests = otherRequests;
+
+    clearTimeout(request.timeout);
+    return request;
+  };
+
+  const finishRequest = ({ request, message }/*: { request: TPendingRequest, message: TNetlinkMessage }*/) => {
+    let errno/*: number | undefined*/;
+
+    try {
+      errno = errnoOfMessage({ message, structures });
+    } catch (ex) {
+      request.reject(ex /*as Error*/);
+      return;
+    }
+
+    request.resolve({ errno, messages: request.messages });
+  };
+
+  const deliverUnsolicited = ({ message }/*: { message: TNetlinkMessage }*/) => {
+    if (onMessage !== undefined) {
+      onMessage({ message });
+    }
+  };
+
+  const dispatchMessage = ({ message }/*: { message: TNetlinkMessage }*/) => {
+    const { nlmsg_seq } = message.header;
+    const request = pendingRequests[nlmsg_seq.toString()];
+
+    if (request === undefined || isRequest({ message })) {
+      deliverUnsolicited({ message });
+      return;
+    }
+
+    if (!isTerminatingMessage({ message })) {
+      pendingRequests = {
+        ...pendingRequests,
+        [nlmsg_seq.toString()]: { ...request, messages: [...request.messages, message] },
+      };
+      return;
+    }
+
+    removePendingRequest({ seq: nlmsg_seq });
+    finishRequest({ request, message });
+  };
+
+  const onData = ({ data }/*: { data: Uint8Array }*/) => {
+    let messages/*: TNetlinkMessage[]*/;
+
+    try {
+      messages = parseMessages({ data, structures });
+    } catch (ex) {
+      onError({ error: ex /*as Error*/ });
+      return;
+    }
+
+    // a handler may detach the socket, the remaining messages are dropped then
+    messages.forEach((message) => {
+      if (!detached) {
+        dispatchMessage({ message });
+      }
+    });
+  };
+
+  const listener = transport.listen({ onData, onError });
+
+  const allocateSeq = createSeqAllocator();
+
+  const assertAttached = () => {
+    if (detached) {
+      throw Error("netlink socket is detached");
+    }
+  };
+
+  const send/*: TNetlinkSocket["send"]*/ = ({ header, payload }) => {
+    assertAttached();
+
+    const {
+      nlmsg_type,
+      nlmsg_flags = NLM_F_REQUEST,
+      nlmsg_seq = allocateSeq(),
+      nlmsg_pid = 0n,
+    } = header;
+
+    const data = formatMessage({
+      message: {
+        header: { nlmsg_type, nlmsg_flags, nlmsg_seq, nlmsg_pid },
+        payload,
+      },
+      structures,
+    });
+
+    transport.send({ data });
+
+    return { nlmsg_seq };
+  };
+
+  const tryTalk/*: TNetlinkSocket["tryTalk"]*/ = ({ header, payload, timeoutMs = DEFAULT_TIMEOUT_MS }) => {
+    return new Promise((resolve, reject) => {
+      assertAttached();
+
+      const seq = allocateSeq();
+
+      const timeout = setTimeout(() => {
+        removePendingRequest({ seq });
+        reject(Error(`netlink request timed out after ${timeoutMs} ms`));
+      }, timeoutMs);
+
+      pendingRequests = {
+        ...pendingRequests,
+        [seq.toString()]: { messages: [], resolve, reject, timeout },
+      };
+
+      try {
+        send({
+          header: {
+            nlmsg_type: header.nlmsg_type,
+            nlmsg_flags: (header.nlmsg_flags ?? 0n) | NLM_F_REQUEST | NLM_F_ACK,
+            nlmsg_seq: seq,
+          },
+          payload,
+        });
+      } catch (ex) {
+        removePendingRequest({ seq });
+        throw ex;
+      }
+    });
+  };
+
+  const talk/*: TNetlinkSocket["talk"]*/ = async (args) => {
+    const { errno, messages } = await tryTalk(args);
+
+    if (errno !== undefined) {
+      throw createErrorFromErrno({ operation: `netlink request of type ${args.header.nlmsg_type}`, errno });
+    }
+
+    return messages;
+  };
+
+  const detach = () => {
+    if (detached) {
+      return;
+    }
+
+    detached = true;
+    listener.stop();
+
+    const requests = Object.values(pendingRequests);
+    pendingRequests = {};
+
+    requests.forEach((request) => {
+      clearTimeout(request.timeout);
+      request.reject(Error("netlink socket was detached while waiting for a response"));
+    });
+  };
+
+  return {
+    nl_pid: transport.address.nl_pid,
+    nl_groups: transport.address.nl_groups,
+
+    send,
+    tryTalk,
+    talk,
+    detach,
+  };
+};
+
+export {
+  createNetlinkSocket,
+  seqAfter,
+};
+
+/*export type {
+  TNetlinkAddress,
+  TNetlinkTransport,
+  TNetlinkSocket,
+  TCreateNetlinkSocketArgs,
+  TTalkArgs,
+  TTryTalkResult,
+  TRequestHeader,
+  TSendHeader,
+};*/

package/dist/lib/po6-transport.d.ts

@@ -0,0 +1,30 @@
+import type { TPo6Api, TPo6KernelAbi } from "po6";
+import type { TNetlinkTransport } from "./netlink-socket.js";
+import { type TNetlinkStructures } from "./structures.js";
+type TPo6NetlinkSyscalls = Pick<TPo6Api, "getsockname" | "sendmsg" | "recvmsg" | "createErrorFromErrno">;
+type TPoller = {
+    armOnce: (events: {
+        readable: () => void;
+        error: (args: {
+            errorCode: number;
+        }) => void;
+    }) => void;
+    close: () => void;
+};
+type TCreatePoller = (args: {
+    fd: number;
+}) => TPoller;
+type TCreatePo6NetlinkTransportArgs = {
+    fd: number;
+    po6: TPo6NetlinkSyscalls;
+    kernelAbi: Pick<TPo6KernelAbi, "constants" | "errnoCodes">;
+    createPoller: TCreatePoller;
+    structures?: TNetlinkStructures;
+};
+/**
+ * Adapts a netlink socket file descriptor to a transport, using the given po6 syscalls and poller.
+ * The socket is neither opened nor closed here, it is owned by the caller.
+ */
+declare const createPo6NetlinkTransport: ({ fd, po6, kernelAbi, createPoller, structures, }: TCreatePo6NetlinkTransportArgs) => TNetlinkTransport;
+export { createPo6NetlinkTransport, };
+export type { TPo6NetlinkSyscalls, TPoller, TCreatePoller, TCreatePo6NetlinkTransportArgs, };

package/dist/lib/po6-transport.js

@@ -0,0 +1,175 @@
+/*import type { TPo6Api, TPo6KernelAbi } from "po6";*/
+import { AF_NETLINK } from "./constants.js";
+/*import type { TNetlinkAddress, TNetlinkTransport } from "./netlink-socket.ts";*/
+import { formatNetlinkAddress, hostStructures, /*type TNetlinkStructures */} from "./structures.js";
+
+/*type TPo6NetlinkSyscalls = Pick<TPo6Api, "getsockname" | "sendmsg" | "recvmsg" | "createErrorFromErrno">;*/
+
+/*type TPoller = {
+  armOnce: (events: {
+    readable: () => void;
+    error: (args: { errorCode: number }) => void;
+  }) => void;
+  close: () => void;
+};*/
+
+/*type TCreatePoller = (args: { fd: number }) => TPoller;*/
+
+/*type TCreatePo6NetlinkTransportArgs = {
+  // a netlink socket opened and bound by the caller, who also closes it
+  fd: number;
+  po6: TPo6NetlinkSyscalls;
+  kernelAbi: Pick<TPo6KernelAbi, "constants" | "errnoCodes">;
+  createPoller: TCreatePoller;
+  structures?: TNetlinkStructures;
+};*/
+
+/*type TReceiveResult = {
+  errno: number;
+  data: undefined;
+} | {
+  errno: undefined;
+  data: Uint8Array;
+};*/
+
+/**
+ * Adapts a netlink socket file descriptor to a transport, using the given po6 syscalls and poller.
+ * The socket is neither opened nor closed here, it is owned by the caller.
+ */
+const createPo6NetlinkTransport = ({
+  fd,
+  po6,
+  kernelAbi,
+  createPoller,
+  structures = hostStructures,
+}/*: TCreatePo6NetlinkTransportArgs*/)/*: TNetlinkTransport*/ => {
+
+  const { MSG_DONTWAIT, MSG_PEEK, MSG_TRUNC } = kernelAbi.constants;
+  const { EAGAIN, ENOBUFS } = kernelAbi.errnoCodes;
+
+  const queryAddress = ()/*: TNetlinkAddress*/ => {
+    const { errno, sockaddr } = po6.getsockname({ fd });
+
+    if (errno !== undefined) {
+      throw po6.createErrorFromErrno({ operation: "getsockname()", errno });
+    }
+
+    const { nl_family, nl_pid, nl_groups } = structures.sockaddrNl.parse({ data: sockaddr });
+
+    if (nl_family !== AF_NETLINK) {
+      throw Error(`file descriptor ${fd} is not a netlink socket, its address family is ${nl_family}`);
+    }
+
+    return { nl_pid, nl_groups };
+  };
+
+  const address = queryAddress();
+  const kernelAddress = formatNetlinkAddress({ address: { nl_pid: 0n, nl_groups: 0n }, structures });
+
+  const receiveDatagram = ()/*: TReceiveResult*/ => {
+    // with MSG_TRUNC, netlink reports the full length of the datagram, even if the buffer is smaller
+    const { errno: peekErrno, bytesReceived: datagramLength } = po6.recvmsg({
+      fd,
+      data: new Uint8Array(1),
+      flags: MSG_PEEK | MSG_TRUNC | MSG_DONTWAIT,
+    });
+
+    if (peekErrno !== undefined) {
+      return { errno: peekErrno, data: undefined };
+    }
+
+    const data = new Uint8Array(Math.max(datagramLength, 1));
+    const { errno, bytesReceived } = po6.recvmsg({ fd, data, flags: MSG_DONTWAIT });
+
+    if (errno !== undefined) {
+      return { errno, data: undefined };
+    }
+
+    return { errno: undefined, data: data.subarray(0, bytesReceived) };
+  };
+
+  const send/*: TNetlinkTransport["send"]*/ = ({ data }) => {
+    const { errno } = po6.sendmsg({ fd, data, msghdr: { msg_name: kernelAddress } });
+
+    if (errno !== undefined) {
+      throw po6.createErrorFromErrno({ operation: "sendmsg()", errno });
+    }
+  };
+
+  const listen/*: TNetlinkTransport["listen"]*/ = ({ onData, onError }) => {
+    const poller = createPoller({ fd });
+    let stopped = false;
+
+    const receiveAndDispatch = ()/*: "continue" | "wait" | "stop"*/ => {
+      const { errno, data } = receiveDatagram();
+
+      if (errno === undefined) {
+        onData({ data });
+        return "continue";
+      }
+
+      if (errno === EAGAIN) {
+        return "wait";
+      }
+
+      onError({ error: po6.createErrorFromErrno({ operation: "recvmsg()", errno }) });
+
+      // ENOBUFS: the receive buffer overflowed and messages were lost, the socket is still usable
+      return errno === ENOBUFS ? "continue" : "stop";
+    };
+
+    // receives until the socket is empty, returns whether to wait for more data
+    const drain = () => {
+      let state = receiveAndDispatch();
+
+      while (state === "continue" && !stopped) {
+        state = receiveAndDispatch();
+      }
+
+      return state === "wait" && !stopped;
+    };
+
+    const arm = () => {
+      poller.armOnce({
+        readable: () => {
+          if (drain()) {
+            arm();
+          }
+        },
+        error: ({ errorCode }) => {
+          onError({ error: Error(`polling netlink socket failed with libuv error ${errorCode}`) });
+        },
+      });
+    };
+
+    arm();
+
+    return {
+      stop: () => {
+        if (stopped) {
+          return;
+        }
+
+        stopped = true;
+        poller.close();
+      },
+    };
+  };
+
+  return {
+    address,
+    send,
+    listen,
+  };
+};
+
+export {
+  createPo6NetlinkTransport,
+};
+
+/*export type {
+  TPo6NetlinkSyscalls,
+  TPoller,
+  TCreatePoller,
+  TCreatePo6NetlinkTransportArgs,
+};*/