@push.rocks/smartnftables 4.1.0 → 4.3.0

package/rust/src/forwardhooks_tests.rs

@@ -0,0 +1,136 @@
+use super::*;
+
+fn table(family: u8, name: &str, handle: u64) -> (u8, Vec<Attr>) {
+    (family, vec![Attr::string(1, name), Attr::u64(4, handle)])
+}
+fn base(
+    family: u8,
+    table: &str,
+    name: &str,
+    hook: u32,
+    priority: i32,
+    policy: u32,
+) -> (u8, Vec<Attr>) {
+    let hook = Attr::nested(
+        4,
+        vec![
+            Attr::bytes(1, hook.to_be_bytes().to_vec()),
+            Attr::bytes(2, priority.to_be_bytes().to_vec()),
+        ],
+    );
+    (
+        family,
+        vec![
+            Attr::string(1, table),
+            Attr::string(3, name),
+            hook,
+            Attr::bytes(5, policy.to_be_bytes().to_vec()),
+            Attr::string(7, "filter"),
+        ],
+    )
+}
+fn regular(family: u8, table: &str, name: &str) -> (u8, Vec<Attr>) {
+    (family, vec![Attr::string(1, table), Attr::string(3, name)])
+}
+
+#[test]
+fn forward_hooks_report_every_routed_forward_base_chain_with_its_table() {
+    let tables = [
+        table(1, "snft_host", 7),
+        table(2, "filter", 3),
+        table(10, "filter", 4),
+        table(7, "filter", 5),
+        table(5, "edge", 6),
+        table(1, "other", 8),
+    ];
+    let chains = [
+        base(1, "snft_host", "forward", 2, 0, 1),
+        base(1, "snft_host", "input", 1, 0, 1),
+        base(2, "filter", "FORWARD", 2, 0, 0),
+        regular(2, "filter", "DOCKER-USER"),
+        regular(2, "filter", "DOCKER-FORWARD"),
+        base(10, "filter", "FORWARD", 2, 0, 1),
+        // Bridge and netdev hooks do not see routed packets.
+        base(7, "filter", "FORWARD", 2, -200, 0),
+        base(5, "edge", "ingress", 0, -500, 1),
+        base(1, "other", "early", 2, -150, 0),
+    ];
+    let (chains, docker) = classify(&tables, &chains).unwrap();
+    let summary: Vec<_> = chains
+        .iter()
+        .map(|c| {
+            (
+                c.family,
+                c.table.as_str(),
+                c.table_handle.as_str(),
+                c.chain.as_str(),
+                c.priority,
+                c.policy,
+            )
+        })
+        .collect();
+    assert_eq!(
+        summary,
+        vec![
+            ("inet", "other", "8", "early", -150, "drop"),
+            ("inet", "snft_host", "7", "forward", 0, "accept"),
+            ("ip", "filter", "3", "FORWARD", 0, "drop"),
+            ("ip6", "filter", "4", "FORWARD", 0, "accept"),
+        ]
+    );
+    assert_eq!(
+        docker,
+        Docker {
+            docker_user: true,
+            docker_forward: true
+        }
+    );
+    let json = serde_json::to_value(&chains[0]).unwrap();
+    assert_eq!(
+        json,
+        serde_json::json!({"family":"inet","table":"other","tableHandle":"8","chain":"early",
+        "type":"filter","priority":-150,"policy":"drop"})
+    );
+}
+
+#[test]
+fn forward_hooks_report_absent_docker_chains_and_reject_inconsistent_dumps() {
+    let (chains, docker) = classify(
+        &[],
+        &[
+            regular(10, "filter", "DOCKER-USER"),
+            regular(2, "nat", "DOCKER-FORWARD"),
+        ],
+    )
+    .unwrap();
+    assert!(chains.is_empty());
+    assert_eq!(
+        docker,
+        Docker {
+            docker_user: false,
+            docker_forward: false
+        }
+    );
+    // A base chain whose table the table dump does not hold exactly once.
+    let chain = [base(2, "filter", "FORWARD", 2, 0, 0)];
+    assert_eq!(classify(&[], &chain), Err(Error::Conflict));
+    assert_eq!(
+        classify(&[table(2, "filter", 1), table(2, "filter", 2)], &chain),
+        Err(Error::Conflict)
+    );
+    assert_eq!(
+        classify(
+            &[table(2, "filter", 1)],
+            &[base(2, "filter", "FORWARD", 2, 0, 3)]
+        ),
+        Err(Error::Protocol)
+    );
+}
+
+#[test]
+fn forward_hooks_read_absent_legacy_tables_as_none() {
+    assert_eq!(
+        legacy("/proc/self/net/smartnftables-absent-fixture").unwrap(),
+        Vec::<String>::new()
+    );
+}

package/rust/src/main.rs

@@ -1,5 +1,6 @@
 mod egress;
 mod docker;
+mod forwardhooks;
 mod managed;
 mod namespace;
 mod owner;
@@ -172,14 +173,12 @@ fn failure(id: &str, error: Error) -> serde_json::Value {
 
 fn main() {
     let arguments = std::env::args().skip(1).collect::<Vec<_>>();
-    let (docker_mode, descriptor) = match arguments.as_slice() {
-        [management] if management == "--management" => (false, None),
-        [management] if management == "--docker-forwarding" => (true, None),
-        [management, option, fd]
-            if (management == "--management" || management == "--docker-forwarding") && option == "--network-namespace-fd" =>
-        {
+    const MODES: [&str; 3] = ["--management", "--docker-forwarding", "--forward-hooks"];
+    let (mode, descriptor) = match arguments.as_slice() {
+        [mode] if MODES.contains(&mode.as_str()) => (mode.clone(), None),
+        [mode, option, fd] if MODES.contains(&mode.as_str()) && option == "--network-namespace-fd" => {
             match fd.parse::<i32>() {
-                Ok(value) => (management == "--docker-forwarding", Some(value)),
+                Ok(value) => (mode.clone(), Some(value)),
                 Err(_) => std::process::exit(2),
             }
         }
@@ -217,7 +216,12 @@ fn main() {
             std::process::exit(2);
         }
         let id = request.id.clone();
-        let response = match if docker_mode { docker::dispatch(&mut docker, request) } else { dispatch(&mut owner, request) } {
+        let result = match mode.as_str() {
+            "--docker-forwarding" => docker::dispatch(&mut docker, request),
+            "--forward-hooks" => forwardhooks::dispatch(request),
+            _ => dispatch(&mut owner, request),
+        };
+        let response = match result {
             Ok(result) => serde_json::json!({"id":id,"success":true,"result":result}),
             Err(error) => failure(&id, error),
         };

package/rust/src/wire.links.rs

@@ -22,6 +22,11 @@ pub struct BoundInterface<'a> {
 }
 
 fn read_link(socket: &mut Socket, index: u32) -> Result<Link> {
+    query_link(socket, index)?.map_err(Error::kernel)
+}
+/// The link at `index`, or the kernel's refusal code, such as `-ENODEV` for an
+/// index no link holds.
+fn query_link(socket: &mut Socket, index: u32) -> Result<std::result::Result<Link, i32>> {
     let sequence = socket.sequence()?;
     let mut request = Vec::new();
     request.extend(32_u32.to_ne_bytes());
@@ -49,17 +54,17 @@ fn read_link(socket: &mut Socket, index: u32) -> Result<Link> {
                         .unwrap(),
                 );
                 if error != 0 {
-                    return Err(Error::kernel(error));
+                    return Ok(Err(error));
                 }
             } else if message.kind == 16 && message.payload.len() >= 16 {
                 if u32::from_ne_bytes(message.payload[4..8].try_into().unwrap()) != index {
                     return Err(Error::Conflict);
                 }
-                return Ok(Link {
+                return Ok(Ok(Link {
                     hardware: u16::from_ne_bytes(message.payload[2..4].try_into().unwrap()),
                     flags: u32::from_ne_bytes(message.payload[8..12].try_into().unwrap()),
                     attributes: attrs(&message.payload[16..])?,
-                });
+                }));
             } else {
                 return Err(Error::Protocol);
             }
@@ -271,9 +276,26 @@ pub fn verify_bound_interfaces<'a>(
 pub fn verify_bound_interfaces_down<'a>(interfaces: impl Iterator<Item = BoundInterface<'a>>) -> Result<()> {
     let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
     for binding in interfaces {
-        let link = read_link(&mut socket, binding.index)?;
-        matches(&link, &binding)?;
-        if link.flags & libc::IFF_UP as u32 != 0 {return Err(Error::Conflict);}
+        down(&read_link(&mut socket, binding.index)?, &binding)?;
     }
     Ok(())
 }
+/// Cleanup fence: a bound link whose index no link holds any more carries no
+/// packets and counts as down. A link at that index must still be the exact
+/// bound link, and down.
+pub fn verify_bound_interfaces_down_or_absent<'a>(interfaces: impl Iterator<Item = BoundInterface<'a>>) -> Result<()> {
+    let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
+    for binding in interfaces {
+        match query_link(&mut socket, binding.index)? {
+            Ok(link) => down(&link, &binding)?,
+            Err(code) if code == -libc::ENODEV => {}
+            Err(code) => return Err(Error::kernel(code)),
+        }
+    }
+    Ok(())
+}
+fn down(link: &Link, binding: &BoundInterface<'_>) -> Result<()> {
+    matches(link, binding)?;
+    if link.flags & libc::IFF_UP as u32 != 0 {return Err(Error::Conflict);}
+    Ok(())
+}

package/rust/src/wire.rs

@@ -139,7 +139,10 @@ pub struct Socket {
 
 #[path = "wire.links.rs"]
 mod links;
-pub use links::{verify_bound_interfaces, verify_bound_interfaces_down, verify_interfaces, BoundInterface};
+pub use links::{
+    verify_bound_interfaces, verify_bound_interfaces_down, verify_bound_interfaces_down_or_absent,
+    verify_interfaces, BoundInterface,
+};
 impl Socket {
     pub fn open() -> Result<Self> {
         Self::open_protocol(libc::NETLINK_NETFILTER)
@@ -311,6 +314,23 @@ impl Socket {
         self.query_family(operation, input, dump, 2)
     }
     fn query_family(&mut self, operation: u16, input: Vec<Attr>, dump: bool, family: u8) -> Result<Vec<Vec<Attr>>> {
+        Ok(self
+            .query_families(operation, input, dump, family)?
+            .into_iter()
+            .map(|(_, attributes)| attributes)
+            .collect())
+    }
+    /// Dump every object of one kind across all families, each with its family.
+    pub fn dump_all_families(&mut self, operation: u16) -> Result<Vec<(u8, Vec<Attr>)>> {
+        self.query_families(operation, vec![], true, 0)
+    }
+    fn query_families(
+        &mut self,
+        operation: u16,
+        input: Vec<Attr>,
+        dump: bool,
+        family: u8,
+    ) -> Result<Vec<(u8, Vec<Attr>)>> {
         let (sequence, bytes) =
             self.message_family(0x0a00 | operation, 1 | if dump { 0x300 } else { 0 }, &input, family)?;
         self.send(&bytes)?;
@@ -350,7 +370,7 @@ impl Socket {
                         return Err(Error::Protocol);
                     }
                     if family == 2 && message.payload[0] != family {return Err(Error::Protocol);}
-                    result.push(attrs(&message.payload[4..])?);
+                    result.push((message.payload[0], attrs(&message.payload[4..])?));
                     if !dump {
                         return Ok(result);
                     }

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartnftables',
-  version: '4.1.0',
+  version: '4.3.0',
   description: 'A TypeScript module for managing nftables rules including NAT, firewall, and rate limiting with a high-level API.'
 }

package/ts/classes.manageddockerforwarding.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import { snapshot, managedIpcBytes, ManagedNftablesError, nativeError } from './classes.managednftables.js';
+import { snapshot, managedIpcBytes, ManagedNftablesError, nativeError, cleanupUnconfirmed } from './classes.managednftables.js';
 import type { IManagedDockerForwardingOptions, IManagedDockerForwardingStatus, IManagedDockerForwardingPolicy, IPreparedManagedDockerForwardingPolicy, IManagedDockerForwardingTransition, IAppliedManagedDockerForwardingPolicy, TManagedDockerForwardingCommands } from './managed.docker.types.js';
 
 /** One node-level Docker DOCKER-USER contribution. Caller owns durable intents and handoff lifetimes. */
@@ -65,7 +65,10 @@ export class ManagedDockerForwarding {
     return this.#invoke('releaseDockerForwarding', expected);
   }
 
-  /** Join operations and exact contributed-rule deletion, then native termination. Keep affected handoff links down through cleanup. */
+  /** Join operations and exact contributed-rule deletion, then native termination. Keep affected handoff links down
+   * through cleanup; a handoff link that no longer exists counts as down. An owner that holds no rule, such as one
+   * whose first apply was refused, closes once the filter table reads without one, whatever Docker's forwarding
+   * path is. A failed read rejects `CLEANUP_UNCONFIRMED` with its native code as `cause`. */
   public close(): Promise<void> {
     if (this.#close) return this.#close;
     if (this.#state === 'stopped') return Promise.resolve();
@@ -80,9 +83,9 @@ export class ManagedDockerForwarding {
         await this.#bridge.terminate({ gracePeriodMs: 1000 });
       }
       this.#bridge = null; this.#state = 'stopped';
-    })().catch(() => {
+    })().catch((error: unknown) => {
       this.#state = 'failed-owned'; this.#close = null;
-      throw new ManagedNftablesError('CLEANUP_UNCONFIRMED');
+      throw cleanupUnconfirmed(error);
     });
     return this.#close;
   }

package/ts/classes.managednftables.ts

@@ -7,14 +7,22 @@ import type { IManagedNftOptions, IManagedNftPolicy, IManagedNftTransition, IApp
  * capacity bound of the atomic replacement budget, and a smaller policy may fit.
  * Both carry the native refusal text in `reason`; `EXHAUSTED` also names its
  * bound in `details`. Every other code, and the facade's own rejections, carry
- * neither. */
+ * neither. `CLEANUP_UNCONFIRMED` names the failure that left cleanup unconfirmed
+ * in `cause`. */
 export class ManagedNftablesError extends Error {
+  declare public readonly cause?: ManagedNftablesError;
   constructor(public readonly code: string, public readonly reason: string | null = null,
-    public readonly details: Readonly<IManagedNftCapacity> | null = null) {
-    super(reason === null ? `Managed nftables ${code}.` : `Managed nftables ${code}: ${reason}`);
+    public readonly details: Readonly<IManagedNftCapacity> | null = null, options: { cause?: ManagedNftablesError } = {}) {
+    super(reason === null ? `Managed nftables ${code}.` : `Managed nftables ${code}: ${reason}`, options);
   }
 }
 
+/** The close failure, naming its cause: a facade error as itself, a native one by its code. */
+export function cleanupUnconfirmed(error: unknown): ManagedNftablesError {
+  return new ManagedNftablesError('CLEANUP_UNCONFIRMED', null, null,
+    { cause: error instanceof ManagedNftablesError ? error : nativeError(error) });
+}
+
 const capacityBounds: ReadonlySet<string> = new Set<TManagedNftCapacityBound>(['ruleBytes', 'targetBytes', 'operations',
   'endpoints', 'links', 'rules', 'grants', 'hostGrants', 'workloadGrants', 'publishedPorts', 'localTcpPortOwners',
   'restoreRules', 'restoreBytes']);
@@ -239,10 +247,10 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
         await this.#bridge.terminate({ gracePeriodMs: 1000 });
       }
       this.#bridge = null; this.#state = 'stopped';
-    })().catch(() => {
+    })().catch((error: unknown) => {
       this.#state = 'failed-owned'; this.#close = null;
       this.#fail();
-      throw new ManagedNftablesError('CLEANUP_UNCONFIRMED');
+      throw cleanupUnconfirmed(error);
     });
     return this.#close;
   }

package/ts/forwardhooks.ts

@@ -0,0 +1,39 @@
+import * as plugins from './plugins.js';
+import { snapshot, managedIpcBytes, ManagedNftablesError, nativeError } from './classes.managednftables.js';
+import type { IForwardHookInspection, IForwardHookInspectionOptions, TForwardHookCommands } from './managed.forwardhooks.types.js';
+
+/** Reads every packet-filter owner on the IPv4/IPv6 forward hook of one network
+ * namespace: nf_tables forward base chains of the `ip`, `ip6` and `inet`
+ * families, Docker's DOCKER-USER/DOCKER-FORWARD chains and registered legacy
+ * xtables tables. One native process takes one generation-consistent read and
+ * exits; it claims, adopts and changes nothing. The result is a point-in-time
+ * view: another owner can appear after it. */
+export async function inspectForwardHooks(options: IForwardHookInspectionOptions = {}): Promise<IForwardHookInspection> {
+  const captured = snapshot(options);
+  if (Object.keys(captured).some((key) => !['binaryPath', 'networkNamespaceFd'].includes(key))
+    || captured.binaryPath !== undefined && (typeof captured.binaryPath !== 'string'
+      || !plugins.path.isAbsolute(captured.binaryPath) || captured.binaryPath.includes('\0'))
+    || captured.networkNamespaceFd !== undefined && (!Number.isInteger(captured.networkNamespaceFd)
+      || captured.networkNamespaceFd < 0 || captured.networkNamespaceFd > 0x7fff_ffff)) {
+    throw new ManagedNftablesError('INVALID');
+  }
+  if (process.platform !== 'linux' || !['x64', 'arm64'].includes(process.arch)) throw new ManagedNftablesError('UNSUPPORTED_PLATFORM');
+  const root = plugins.url.fileURLToPath(new URL('../', import.meta.url));
+  const bridge = new plugins.smartrust.RustBridge<TForwardHookCommands>({
+    binaryName: 'smartnftables', binaryPath: captured.binaryPath
+      ?? plugins.path.join(root, 'dist_rust', `smartnftables_linux_${process.arch === 'x64' ? 'amd64' : 'arm64'}_musl`),
+    localPaths: [], searchSystemPath: false,
+    cliArgs: ['--forward-hooks', ...(captured.networkNamespaceFd === undefined ? [] : ['--network-namespace-fd', '3'])],
+    inheritedFileDescriptors: captured.networkNamespaceFd === undefined ? undefined : [captured.networkNamespaceFd],
+    readyTimeoutMs: 3000, requestTimeoutMs: 30_000, maxPayloadSize: managedIpcBytes,
+    maxPendingRequestsByMethod: { inspectForwardHooks: 1 },
+  });
+  try {
+    if (!await bridge.spawn()) throw new ManagedNftablesError('UNAVAILABLE');
+    return snapshot(await bridge.sendCommand('inspectForwardHooks', {}));
+  } catch (error) {
+    throw error instanceof ManagedNftablesError ? error : nativeError(error);
+  } finally {
+    await bridge.terminate({ gracePeriodMs: 1000 });
+  }
+}

package/ts/index.ts

@@ -64,3 +64,5 @@ export type {
 } from './nft.types.js';
 export * from './managed.docker.types.js';
 export * from './classes.manageddockerforwarding.js';
+export type * from './managed.forwardhooks.types.js';
+export { inspectForwardHooks } from './forwardhooks.js';

package/ts/managed.docker.types.ts

@@ -25,7 +25,8 @@ export interface IAppliedManagedDockerForwardingPolicy {
   receipt: { identity: IManagedDockerForwardingIdentity; backend: string; revision: number; digest: string };
   prepared: IPreparedManagedDockerForwardingPolicy;
 }
-/** Persist before mutation. Keep both generations' exact handoff links down until reconciliation is confirmed. */
+/** Persist before mutation. A handoff link both generations bind exactly may stay up: one atomic transaction swaps
+ * the contribution. Keep every link the transition adds or drops down until reconciliation is confirmed. */
 export interface IManagedDockerForwardingTransition {
   previous: IAppliedManagedDockerForwardingPolicy | null;
   target: IPreparedManagedDockerForwardingPolicy;

package/ts/managed.forwardhooks.types.ts

@@ -0,0 +1,26 @@
+import type { IManagedNftOptions } from './managed.types.js';
+
+export interface IForwardHookInspectionOptions extends Pick<IManagedNftOptions, 'binaryPath' | 'networkNamespaceFd'> {}
+/** One nf_tables base chain on the forward hook of the `ip`, `ip6` or `inet` family. */
+export interface IForwardHookChain {
+  family: 'ip' | 'ip6' | 'inet';
+  table: string;
+  /** Kernel table handle, as a managed receipt's `tableHandle`. */
+  tableHandle: string;
+  chain: string;
+  type: string;
+  priority: number;
+  policy: 'accept' | 'drop';
+}
+/** One consistent read of every packet-filter owner on the routed forward path of a network namespace. */
+export interface IForwardHookInspection {
+  /** Every forward base chain, sorted by family, table and chain; managed tables included. */
+  chains: IForwardHookChain[];
+  /** Docker's iptables-nft dispatch chains in table `ip filter`. */
+  docker: { dockerUser: boolean; dockerForward: boolean };
+  /** Registered legacy xtables tables, whose hooks are not nf_tables chains. */
+  legacyTables: { ipv4: string[]; ipv6: string[] };
+}
+export type TForwardHookCommands = {
+  inspectForwardHooks: { params: Record<string, never>; result: IForwardHookInspection };
+};