@push.rocks/smartnftables 2.6.0 → 4.0.0

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

@@ -60,9 +60,14 @@ export interface IManagedNftEgressGenerationV2 extends IManagedNftHandoffAllocat
  * `transitSourceAddress:transitPort`, this translates on to the workload. */
 export interface IManagedNftRouterPublishedPortV2 {
   protocol: 'tcp' | 'udp';
-  /** Published handoff port, 1–65535 and unique per protocol across the scope.
-   * It is the `targetPort` of the matching host-transit publication. */
+  /** Published handoff port, 1–65535; published ports never overlap per protocol across the
+   * scope. It is the `targetPort` of the matching host-transit publication. */
   transitPort: number;
+  /** Optional last port of a published range `transitPort..transitPortEnd`, greater than
+   * `transitPort`. A range keeps every port, so `endpointPort` must equal `transitPort`; like one
+   * port it is one interval set element per set, and its translation keeps the port. Absent for
+   * one port, which is its only canonical form. */
+  transitPortEnd?: number;
   endpointPort: number;
   /** Exact current workload endpoint address behind one veth endpoint of this
    * scope. Never a router-local address, a gateway or a platform endpoint. */
@@ -70,6 +75,12 @@ export interface IManagedNftRouterPublishedPortV2 {
   /** Exact leased transit source address of one current generation, present on
    * `handoff`. No wildcard, secondary-address or route inference. */
   transitSourceAddress: string;
+  /** Optional: the workload may open flows from `endpointAddress` and its published endpoint
+   * port(s) toward unprotected space, source-translated to `transitSourceAddress` and the
+   * published transit port (a range keeps the port). The protected union stays denied, and its
+   * endpoint ports may not overlap another publication's on the same address. Absent and
+   * `false` are the same canonical policy. */
+  symmetric?: boolean;
 }
 
 /** One exact host-origin flow: the node's own host network namespace dials one port of one local
@@ -136,13 +147,24 @@ export interface IManagedNftRouterEgressScopeV2 {
 /** One inbound uplink publication, compiled inside the same host-transit generation. */
 export interface IManagedNftPublishedPortV2 {
   protocol: 'tcp' | 'udp';
-  /** Published uplink port, 1–65535 and unique per protocol across the scope. */
+  /** Published uplink port, 1–65535; published ports never overlap per protocol across the scope. */
   hostPort: number;
+  /** Optional last port of a published range `hostPort..hostPortEnd`, greater than `hostPort`.
+   * A range keeps every port, so `targetPort` must equal `hostPort`; like one port it is one
+   * interval set element per set, and its translation keeps the port. Absent for one port, which
+   * is its only canonical form. */
+  hostPortEnd?: number;
   targetPort: number;
   /** Exact leased transit source address of one current allocation; it selects the handoff. */
   targetAddress: string;
   /** Exact current uplink address that publishes this port. No wildcard or route inference. */
   hostIp: string;
+  /** Optional: flows from `targetAddress` and the published target port(s) may leave through the
+   * uplink toward unprotected space, source-translated to `hostIp` and the published uplink port
+   * (a range keeps the port). The protected union stays denied, its target ports may not fall in
+   * a leased range of `targetAddress` or overlap another publication's. Absent and `false` are
+   * the same canonical policy. */
+  symmetric?: boolean;
 }
 
 /** Shared-host capture barrier and explicit outer SNAT; Docker forwarding remains a separate owner. */

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> };