socket-function 1.2.24 → 1.2.25

package/index.d.ts

@@ -991,11 +991,12 @@ declare module "socket-function/src/forwardPort" {
     export declare function listPortMappings(): Promise<PortMapping[]>;
     /** Outcome of forwardPort. `owned` is true once we hold the router mapping for the port. When
      *      false, `reason` says why: "declined" = noPortStealing and another host holds the port (the
-     *      caller should try a different port); "error" = UPnP unreachable / create failed (best-effort,
-     *      nothing forwarded but the caller can carry on). */
+     *      caller should try a different port); "notBehindNat" = we have a public/directly-reachable
+     *      address so there's nothing to forward; "error" = UPnP unreachable / create failed (best-effort,
+     *      nothing forwarded but the caller can carry on). Only "declined" warrants trying another port. */
     export type ForwardPortResult = {
         owned: boolean;
-        reason?: "declined" | "error";
+        reason?: "declined" | "notBehindNat" | "error";
     };
     export declare function forwardPort(config: {
         externalPort: number;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "socket-function",
-	"version": "1.2.24",
+	"version": "1.2.25",
 	"main": "index.js",
 	"license": "MIT",
 	"dependencies": {

package/src/forwardPort.d.ts

@@ -26,11 +26,12 @@ export interface PortMapping {
 export declare function listPortMappings(): Promise<PortMapping[]>;
 /** Outcome of forwardPort. `owned` is true once we hold the router mapping for the port. When
  *      false, `reason` says why: "declined" = noPortStealing and another host holds the port (the
- *      caller should try a different port); "error" = UPnP unreachable / create failed (best-effort,
- *      nothing forwarded but the caller can carry on). */
+ *      caller should try a different port); "notBehindNat" = we have a public/directly-reachable
+ *      address so there's nothing to forward; "error" = UPnP unreachable / create failed (best-effort,
+ *      nothing forwarded but the caller can carry on). Only "declined" warrants trying another port. */
 export type ForwardPortResult = {
     owned: boolean;
-    reason?: "declined" | "error";
+    reason?: "declined" | "notBehindNat" | "error";
 };
 export declare function forwardPort(config: {
     externalPort: number;

package/src/forwardPort.ts

@@ -18,6 +18,13 @@ export async function resolveGateway(): Promise<{
     let internalIP = await getOutboundIP();
     if (!internalIP) throw new Error("Could not determine our local network address");
 
+    // A public/directly-reachable outbound address means there's no NAT and therefore no UPnP
+    //  gateway to reach — SSDP would just multicast into the void and time out after 2s. Fail fast
+    //  and clearly instead, so callers (and forwardPort) never spend that time on a public host.
+    if (!isPrivateIPv4(internalIP)) {
+        throw new Error(`Not behind a NAT (outbound address ${internalIP} is public) — no UPnP gateway to reach, skipping SSDP discovery.`);
+    }
+
     // The gateway that answers SSDP discovery is the router we forward through; take its IP
     //  and control port straight from the discovered device URL rather than parsing routes.
     let gateway = await discoverGateway(internalIP);
@@ -89,11 +96,12 @@ const SUPERSEDE_CHECK_INTERVAL = timeInMinute * 30;
 
 /** Outcome of forwardPort. `owned` is true once we hold the router mapping for the port. When
  *      false, `reason` says why: "declined" = noPortStealing and another host holds the port (the
- *      caller should try a different port); "error" = UPnP unreachable / create failed (best-effort,
- *      nothing forwarded but the caller can carry on). */
+ *      caller should try a different port); "notBehindNat" = we have a public/directly-reachable
+ *      address so there's nothing to forward; "error" = UPnP unreachable / create failed (best-effort,
+ *      nothing forwarded but the caller can carry on). Only "declined" warrants trying another port. */
 export type ForwardPortResult = {
     owned: boolean;
-    reason?: "declined" | "error";
+    reason?: "declined" | "notBehindNat" | "error";
 };
 
 export async function forwardPort(config: {
@@ -113,6 +121,12 @@ export async function forwardPort(config: {
     let duration = config.duration ?? PERMANENT_LEASE;
     let permanent = duration === PERMANENT_LEASE;
 
+    // Forwarding only makes sense behind a NAT. On a directly-reachable public host there's no
+    //  gateway, so skip UPnP entirely (no SSDP) rather than discovering-and-timing-out.
+    if (!await isBehindNAT()) {
+        return { owned: false, reason: "notBehindNat" };
+    }
+
     // Take ownership of the router's mapping for this external port: delete whatever's there (a
     //  stale mapping of ours, or another host's) so our AddPortMapping isn't rejected as a conflict
     //  (718), then install our mapping. This makes the last writer win — whichever application