@push.rocks/smartnftables 3.0.0 → 4.0.1

package/rust/src/tests.rs

@@ -117,3 +117,103 @@ fn compiler_bounds_full_policy_and_keeps_directed_port_grants() {
     value.revision = 9_007_199_254_740_992;
     assert_eq!(value.prepare(), Err(Error::Invalid));
 }
+
+fn exhausted<T>(name: &'static str, limit: usize, actual: usize) -> crate::Result<T> {
+    Err(Error::Exhausted(crate::Bound {
+        name,
+        limit,
+        actual,
+    }))
+}
+
+/// Every endpoint with 16 prefixes and `rules` distinct directed rules between
+/// them: well-formed input whose only fault can be its size.
+fn sized(endpoints: u32, rules: u16) -> Policy {
+    let mut value = policy();
+    let template = value.endpoints[0].clone();
+    value.endpoints = (0..endpoints)
+        .map(|index| {
+            let mut endpoint = template.clone();
+            endpoint.id = format!("e{index}");
+            endpoint.interface_index = 10 + index;
+            endpoint.interface_name = format!("w{index}");
+            endpoint.source_prefixes = (0..16)
+                .map(|part| format!("10.{}.{part}.0/24", 100 + index))
+                .collect();
+            endpoint
+        })
+        .collect();
+    let template = value.rules[0].clone();
+    value.rules = (0..rules)
+        .map(|index| {
+            let (from, to) = (
+                u32::from(index) % endpoints,
+                (u32::from(index) + 1) % endpoints,
+            );
+            let mut rule = template.clone();
+            rule.source_endpoint = Some(format!("e{from}"));
+            rule.destination_endpoint = Some(format!("e{to}"));
+            rule.source_prefix = format!("10.{}.0.0/24", 100 + from);
+            rule.destination_prefix = format!("10.{}.0.0/24", 100 + to);
+            rule.destination_port = Some(1000 + index);
+            rule
+        })
+        .collect();
+    value
+}
+
+#[test]
+fn v1_capacity_refusals_name_their_bound_and_invalid_input_stays_invalid() {
+    assert_eq!(sized(2, 2).prepare().map(|_| ()), Ok(()));
+    // Within the schema's counts, the complete graph exceeds the byte and the
+    // operation budget; the complete program is measured, so both are exact.
+    assert_eq!(
+        sized(8, 16).prepare(),
+        exhausted("ruleBytes", 100_000, 186_952)
+    );
+    assert_eq!(sized(32, 128).prepare(), exhausted("operations", 768, 1667));
+    assert_eq!(sized(33, 16).prepare(), exhausted("endpoints", 32, 33));
+    assert_eq!(sized(8, 129).prepare(), exhausted("rules", 128, 129));
+    // Invalid input is never reported as capacity, whatever its size.
+    let mut value = sized(33, 129);
+    value.schema_version = 2;
+    assert_eq!(value.prepare(), Err(Error::Invalid));
+    let mut value = sized(2, 2);
+    value.endpoints[0].interface_name = "w".repeat(16);
+    assert_eq!(value.prepare(), Err(Error::Invalid));
+    let mut value = sized(2, 2);
+    value.endpoints[0]
+        .source_prefixes
+        .push("10.200.0.0/24".into());
+    assert_eq!(value.prepare(), Err(Error::Invalid));
+}
+
+#[test]
+fn failure_responses_carry_the_refusal_reason_and_capacity_bound() {
+    let bound = crate::Bound {
+        name: "targetBytes",
+        limit: 212_000,
+        actual: 212_345,
+    };
+    assert_eq!(
+        crate::failure("7", Error::Exhausted(bound)),
+        serde_json::json!({"id":"7","success":false,
+            "error":"Managed policy exceeds the targetBytes capacity of 212000: it reached 212345.",
+            "errorCode":"EXHAUSTED","errorData":{"bound":"targetBytes","limit":212_000,"actual":212_345}})
+    );
+    assert_eq!(
+        crate::failure("8", Error::Invalid),
+        serde_json::json!({"id":"8","success":false,"error":"Managed policy input is invalid.","errorCode":"INVALID"})
+    );
+    for error in [
+        Error::Conflict,
+        Error::Permission,
+        Error::Protocol,
+        Error::Unavailable,
+    ] {
+        assert_eq!(
+            crate::failure("9", error),
+            serde_json::json!({"id":"9","success":false,"error":"Managed policy operation failed.","errorCode":error.code()})
+        );
+    }
+}

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartnftables',
-  version: '3.0.0',
+  version: '4.0.1',
   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 } from './classes.managednftables.js';
+import { snapshot, managedIpcBytes, ManagedNftablesError, nativeError } 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. */
@@ -103,8 +103,7 @@ export class ManagedDockerForwarding {
   #track<T>(work: Promise<T>): Promise<T> {
     const owned = work.catch((error) => {
       if (this.#state !== 'closing') this.#state = 'failed-owned';
-      const code = error instanceof plugins.smartrust.RustBridgeRequestError ? error.responseErrorCode : undefined;
-      throw new ManagedNftablesError(typeof code === 'string' && /^[A-Z_]{1,64}$/.test(code) ? code : 'UNAVAILABLE');
+      throw nativeError(error);
     });
     this.#work = owned;
     void owned.then(() => { this.#work = null; }, () => { this.#work = null; });

package/ts/classes.managednftables.ts

@@ -1,9 +1,46 @@
 import * as plugins from './plugins.js';
-import type { IManagedNftOptions, IManagedNftPolicy, IManagedNftTransition, IAppliedManagedNftPolicy,
-  IPreparedManagedNftPolicy, IManagedNftStatus, IManagedNftTransitionRelease, TManagedNftCommands, TManagedNftPolicy } from './managed.types.js';
+import type { IManagedNftOptions, IManagedNftPolicy, IManagedNftTransition, IAppliedManagedNftPolicy, IPreparedManagedNftPolicy,
+  IManagedNftStatus, IManagedNftTransitionRelease, TManagedNftCommands, TManagedNftPolicy, IManagedNftCapacity,
+  TManagedNftCapacityBound } from './managed.types.js';
 
+/** `INVALID`: the input is outside the contract. `EXHAUSTED`: the policy exceeds a
+ * 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. */
 export class ManagedNftablesError extends Error {
-  constructor(public readonly code: string) { super(`Managed nftables ${code}.`); }
+  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}`);
+  }
+}
+
+const capacityBounds: ReadonlySet<string> = new Set<TManagedNftCapacityBound>(['ruleBytes', 'targetBytes', 'operations',
+  'endpoints', 'links', 'rules', 'grants', 'hostGrants', 'workloadGrants', 'publishedPorts', 'localTcpPortOwners',
+  'restoreRules', 'restoreBytes']);
+
+function capacity(value: unknown): Readonly<IManagedNftCapacity> | null {
+  if (typeof value !== 'object' || value === null || Object.getPrototypeOf(value) !== Object.prototype
+    || Object.keys(value).sort().join(',') !== 'actual,bound,limit') return null;
+  const { bound, limit, actual } = value as Record<string, unknown>;
+  if (typeof bound !== 'string' || !capacityBounds.has(bound) || typeof limit !== 'number' || typeof actual !== 'number'
+    || !Number.isSafeInteger(limit) || !Number.isSafeInteger(actual) || limit < 0 || actual <= limit) return null;
+  return Object.freeze({ bound: bound as TManagedNftCapacityBound, limit, actual });
+}
+
+/** Maps a failed native request. An `INVALID` or `EXHAUSTED` response keeps the
+ * bounded native refusal text and, for `EXHAUSTED`, its bound; a refusal outside
+ * that shape is `PROTOCOL`. Other responses keep only their code, and a failure
+ * without a native code is `UNAVAILABLE`. */
+export function nativeError(error: unknown): ManagedNftablesError {
+  if (!(error instanceof plugins.smartrust.RustBridgeRequestError)) return new ManagedNftablesError('UNAVAILABLE');
+  const { responseErrorCode: code, message: reason, responseErrorData: data } = error;
+  if (typeof code !== 'string' || !/^[A-Z_]{1,64}$/.test(code)) return new ManagedNftablesError('UNAVAILABLE');
+  if (code !== 'INVALID' && code !== 'EXHAUSTED') return new ManagedNftablesError(code);
+  if (!/^[\x20-\x7e]{1,256}$/.test(reason)) return new ManagedNftablesError('PROTOCOL');
+  if (code === 'INVALID') return data === undefined ? new ManagedNftablesError(code, reason) : new ManagedNftablesError('PROTOCOL');
+  const details = capacity(data);
+  return details ? new ManagedNftablesError(code, reason, details) : new ManagedNftablesError('PROTOCOL');
 }
 
 /** Bounds of the private native IPC. A status carries up to three complete policies (applied,
@@ -240,16 +277,17 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
   #track<T>(work: Promise<T>, method: keyof TManagedNftCommands<TPolicy>): Promise<T> {
     const owned = work.catch((error) => {
       if (this.#state !== 'closing') this.#state = 'failed-owned';
-      const code = error instanceof plugins.smartrust.RustBridgeRequestError ? error.responseErrorCode : undefined;
-      // Only a native compiler rejection or explicit INVALID response proves
-      // effect-free validation. Other native errors can follow lost ownership
+      const failure = nativeError(error);
+      // Only a native compiler rejection or explicit INVALID or EXHAUSTED
+      // response proves effect-free validation: the native owner refuses both
+      // before any kernel work. Other native errors can follow lost ownership
       // or admitted kernel work. Recovery stays available; confidence is lost.
       const validation = error instanceof plugins.smartrust.RustBridgeRequestError
         && error.code === 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE'
-        && (method === 'preparePolicy' || code === 'INVALID');
+        && (method === 'preparePolicy' || failure.code === 'INVALID' || failure.code === 'EXHAUSTED');
       if (!validation && (this.#state !== 'closing'
         || ['reconcilePolicy', 'releasePolicy', 'releasePolicyTransition', 'detachPolicy'].includes(method))) this.#fail();
-      throw new ManagedNftablesError(typeof code === 'string' && /^[A-Z_]{1,64}$/.test(code) ? code : 'UNAVAILABLE');
+      throw failure;
     });
     this.#work = owned;
     void owned.then(() => { this.#work = null; }, () => { this.#work = null; });

package/ts/managed.egress.types.ts

@@ -172,6 +172,8 @@ export interface IManagedNftHostTransitScopeV2 {
   kind: 'hostTransit';
   protection: IManagedNftProtectionV2;
   handoffs: Array<{ link: IManagedNftLocalLinkV2; allocations: IManagedNftHandoffAllocationV2[] }>;
+  /** Its addresses need not lie in `protection.prefixes`; the host barrier protects each
+   * uncovered one as a `/32` destination. Handoff addresses must be protected. */
   uplink: IManagedNftLocalLinkV2;
   /** Exact current address present on uplink. No masquerade or default-route inference. */
   snatAddress: string;

package/ts/managed.types.ts

@@ -93,6 +93,23 @@ export interface IManagedNftOptions {
 
 export type TManagedNftPolicy = IManagedNftPolicy | IManagedNftPolicyV2;
 
+/** Capacity bounds of the atomic replacement budget. The compiled target's
+ * `ruleBytes` (100,000), `targetBytes` (212,000) and `operations` (768), the input
+ * counts that exist to hold it (`endpoints`, `links`, `rules`, `grants`,
+ * `hostGrants`, `workloadGrants`, `publishedPorts`, `localTcpPortOwners`) and the
+ * Docker forwarding contribution's `restoreRules` (192) and `restoreBytes` (100,000). */
+export type TManagedNftCapacityBound = 'ruleBytes' | 'targetBytes' | 'operations' | 'endpoints' | 'links' | 'rules'
+  | 'grants' | 'hostGrants' | 'workloadGrants' | 'publishedPorts' | 'localTcpPortOwners' | 'restoreRules' | 'restoreBytes';
+
+/** The bound an `EXHAUSTED` refusal names. `actual` is always above `limit`. It is
+ * exact for input counts and the schema-v1 budget; the other compiled budgets stop
+ * at the first message or rule past the limit, so the policy needs at least `actual`. */
+export interface IManagedNftCapacity {
+  bound: TManagedNftCapacityBound;
+  limit: number;
+  actual: number;
+}
+
 export type TManagedNftCommands<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> = {
   preparePolicy: { params: TPolicy; result: IPreparedManagedNftPolicy<TPolicy> };
   openOwner: { params: Pick<IManagedNftOptions, 'ownerId' | 'instanceId' | 'tableName'>; result: IManagedNftStatus<TPolicy> };