@push.rocks/smartnftables 2.1.0 → 2.3.0

package/ts/classes.managednftables.ts

@@ -1,6 +1,6 @@
 import * as plugins from './plugins.js';
 import type { IManagedNftOptions, IManagedNftPolicy, IManagedNftTransition, IAppliedManagedNftPolicy,
-  IPreparedManagedNftPolicy, IManagedNftStatus, TManagedNftCommands, TManagedNftPolicy } from './managed.types.js';
+  IPreparedManagedNftPolicy, IManagedNftStatus, IManagedNftTransitionRelease, TManagedNftCommands, TManagedNftPolicy } from './managed.types.js';
 
 export class ManagedNftablesError extends Error {
   constructor(public readonly code: string) { super(`Managed nftables ${code}.`); }
@@ -55,6 +55,7 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
   #retaining = false;
   #detachExpected: IAppliedManagedNftPolicy<TPolicy> | null = null;
   #detach: Promise<{ detached: true }> | null = null;
+  #transitionRelease: { request: IManagedNftTransitionRelease<TPolicy> } | null = null;
   readonly #failure = new AbortController();
   #processLost = false;
 
@@ -97,7 +98,7 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
         cliArgs: ['--management', ...(this.#options.networkNamespaceFd === undefined ? [] : ['--network-namespace-fd', '3'])],
         inheritedFileDescriptors: this.#options.networkNamespaceFd === undefined ? undefined : [this.#options.networkNamespaceFd],
         readyTimeoutMs: 3000, requestTimeoutMs: 30_000, maxPayloadSize: 262_144,
-        maxPendingRequestsByMethod: { preparePolicy: 1, openOwner: 1, reconcilePolicy: 1, inspectPolicy: 1, releasePolicy: 1, detachPolicy: 1, closeOwner: 1 },
+        maxPendingRequestsByMethod: { preparePolicy: 1, openOwner: 1, reconcilePolicy: 1, inspectPolicy: 1, releasePolicy: 1, releasePolicyTransition: 1, detachPolicy: 1, closeOwner: 1 },
       });
       this.#bridge.on('exit', () => {
         this.#processLost = true;
@@ -123,11 +124,20 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
     return this.#invoke('releasePolicy', expected);
   }
 
+  /** Terminal release when an apply acknowledgement was lost. Retain the full
+   * original identity and transition first. The native owner accepts only an
+   * absent table or the exact previous/target graph; it never recreates policy
+   * or requires surviving interfaces. Exact retries and inspection remain
+   * available; close() retries admitted cleanup, closeRetaining() only joins. */
+  public releaseTransition(request: IManagedNftTransitionRelease<TPolicy>): Promise<{ released: true }> {
+    return this.#invoke('releasePolicyTransition', request);
+  }
+
   /** Permanently selects retention cleanup, verifies exact PERSIST retention, and
    * joins the native process. Retain the full applied value before this call.
    * After any failure close() only terminates; it never deletes the table. */
   public detach(expected: IAppliedManagedNftPolicy<TPolicy>): Promise<{ detached: true }> {
-    if (this.#closeRetainingSelected || this.#closeMode === 'delete') return Promise.reject(new ManagedNftablesError('UNAVAILABLE'));
+    if (this.#closeRetainingSelected || this.#closeMode === 'delete' || this.#transitionRelease) return Promise.reject(new ManagedNftablesError('UNAVAILABLE'));
     this.#retaining = true;
     let captured: IAppliedManagedNftPolicy<TPolicy>;
     try {
@@ -173,8 +183,13 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
       await this.#work?.catch(() => undefined);
       if (this.#bridge) {
         if (this.#nativeMayOwn && !retaining) {
-          const result = await this.#bridge.sendCommand('closeOwner', {});
-          if (result.released !== true) throw new ManagedNftablesError('PROTOCOL');
+          // Even native validation may have rejected before selecting its own
+          // terminal intent. Retry this exact request; generic close must not
+          // delete an earlier applied graph outside the requested transition.
+          const result = this.#transitionRelease
+            ? await this.#bridge.sendCommand('releasePolicyTransition', this.#transitionRelease.request)
+            : await this.#bridge.sendCommand('closeOwner', {});
+          if (result.released !== true || this.#transitionRelease && Object.keys(result).length !== 1) throw new ManagedNftablesError('PROTOCOL');
         }
         await this.#bridge.terminate({ gracePeriodMs: 1000 });
       }
@@ -191,15 +206,24 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
     if (this.#retaining || !['ready', 'failed-owned'].includes(this.#state) || !this.#bridge || this.#work) return Promise.reject(new ManagedNftablesError('UNAVAILABLE'));
     let captured: TManagedNftCommands<TPolicy>[K]['params'];
     try { captured = snapshot(params); } catch { return Promise.reject(new ManagedNftablesError('INVALID')); }
-    if (method === 'reconcilePolicy' || method === 'releasePolicy') this.#nativeMayOwn = true;
+    if (this.#transitionRelease && (method !== 'inspectPolicy' && method !== 'releasePolicyTransition'
+      || method === 'releasePolicyTransition' && !plugins.util.isDeepStrictEqual(this.#transitionRelease.request, captured))) {
+      return Promise.reject(new ManagedNftablesError('CONFLICT'));
+    }
+    if (method === 'releasePolicyTransition') this.#transitionRelease = { request: captured as IManagedNftTransitionRelease<TPolicy> };
+    if (method === 'reconcilePolicy' || method === 'releasePolicy' || method === 'releasePolicyTransition') this.#nativeMayOwn = true;
     return this.#track(this.#bridge.sendCommand(method, captured).then((result) => {
       const capturedResult = snapshot(result);
-      if (method === 'releasePolicy') this.#nativeMayOwn = false;
+      if (method === 'releasePolicy' || method === 'releasePolicyTransition') {
+        if (method === 'releasePolicyTransition' && ((capturedResult as { released: true })?.released !== true
+          || Object.keys(capturedResult).length !== 1)) throw new ManagedNftablesError('PROTOCOL');
+        this.#nativeMayOwn = false;
+      }
       if (method === 'inspectPolicy') {
         const status = capturedResult as IManagedNftStatus<TPolicy>;
         if (status.state === 'failed-owned' || status.error !== null) this.#fail();
       }
-      if (!this.#processLost && this.#state !== 'closing' && (method === 'reconcilePolicy' || method === 'releasePolicy'
+      if (!this.#processLost && this.#state !== 'closing' && (method === 'reconcilePolicy' || method === 'releasePolicy' || method === 'releasePolicyTransition'
         || method === 'inspectPolicy' && (capturedResult as IManagedNftStatus<TPolicy>).error === null
           && (capturedResult as IManagedNftStatus<TPolicy>).state !== 'failed-owned')) this.#state = 'ready';
       return capturedResult;
@@ -216,7 +240,7 @@ export class ManagedNftables<TPolicy extends TManagedNftPolicy = IManagedNftPoli
         && error.code === 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE'
         && (method === 'preparePolicy' || code === 'INVALID');
       if (!validation && (this.#state !== 'closing'
-        || ['reconcilePolicy', 'releasePolicy', 'detachPolicy'].includes(method))) this.#fail();
+        || ['reconcilePolicy', 'releasePolicy', 'releasePolicyTransition', 'detachPolicy'].includes(method))) this.#fail();
       throw new ManagedNftablesError(typeof code === 'string' && /^[A-Z_]{1,64}$/.test(code) ? code : 'UNAVAILABLE');
     });
     this.#work = owned;

package/ts/managed.egress.types.ts

@@ -68,6 +68,18 @@ export interface IManagedNftRouterEgressScopeV2 {
   generations: IManagedNftEgressGenerationV2[];
 }
 
+/** 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. */
+  hostPort: 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;
+}
+
 /** Shared-host capture barrier and explicit outer SNAT; Docker forwarding remains a separate owner. */
 export interface IManagedNftHostTransitScopeV2 {
   kind: 'hostTransit';
@@ -76,6 +88,11 @@ export interface IManagedNftHostTransitScopeV2 {
   uplink: IManagedNftLocalLinkV2;
   /** Exact current address present on uplink. No masquerade or default-route inference. */
   snatAddress: string;
+  /** Optional inbound destination NAT. Absent and empty are the same canonical policy and
+   * keep the compiled graph unchanged. Every entry compiles its own uplink DNAT plus the
+   * exact forward and reply admission in this generation, so a failed apply, a target
+   * without it, or release removes it with the generation. */
+  publishedPorts?: IManagedNftPublishedPortV2[];
 }
 
 /** Host-wide IPv4 destination denial for caller-authenticated private allocation pools.

package/ts/managed.types.ts

@@ -60,6 +60,14 @@ export interface IManagedNftTransition<TPolicy extends TManagedNftPolicy = IMana
   target: IPreparedManagedNftPolicy<TPolicy>;
 }
 
+/** Persist the original boot/namespace identity and full transition before cleanup.
+ * This releases only its exact owned table; it does not prove packet drain or
+ * authorize address reuse. Surviving policy interfaces are not required. */
+export interface IManagedNftTransitionRelease<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> {
+  identity: IManagedNftIdentity;
+  transition: IManagedNftTransition<TPolicy>;
+}
+
 export interface IManagedNftStatus<TPolicy extends TManagedNftPolicy = IManagedNftPolicy> {
   identity: IManagedNftIdentity;
   state: 'idle' | 'applied' | 'failed-owned' | 'released' | 'retained';
@@ -91,6 +99,7 @@ export type TManagedNftCommands<TPolicy extends TManagedNftPolicy = IManagedNftP
   reconcilePolicy: { params: IManagedNftTransition<TPolicy>; result: IAppliedManagedNftPolicy<TPolicy> };
   inspectPolicy: { params: Record<string, never>; result: IManagedNftStatus<TPolicy> };
   releasePolicy: { params: IAppliedManagedNftPolicy<TPolicy>; result: { released: true } };
+  releasePolicyTransition: { params: IManagedNftTransitionRelease<TPolicy>; result: { released: true } };
   detachPolicy: { params: IAppliedManagedNftPolicy<TPolicy>; result: { detached: true } };
   closeOwner: { params: Record<string, never>; result: { released: true } };
 };