socket-function 1.2.8 → 1.2.10

package/SocketFunction.d.ts

@@ -1,6 +1,5 @@
 /// <reference path="require/RequireController.d.ts" />
 /// <reference types="node" />
-/// <reference types="node" />
 import { SocketExposedInterface, SocketFunctionHook, SocketFunctionClientHook, SocketExposedShape, SocketRegistered, CallerContext, FullCallType, SocketRegisterType } from "./SocketFunctionTypes";
 import { SocketServerConfig } from "./src/webSocketServer";
 import { Args, MaybePromise } from "./src/types";

package/bin/upreal.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+require("typenode");
+require("../src/upreal");

package/index.d.ts

@@ -9,7 +9,6 @@ declare module "socket-function/SetProcessVariables" {
 declare module "socket-function/SocketFunction" {
     /// <reference path="require/RequireController.d.ts" />
     /// <reference types="node" />
-    /// <reference types="node" />
     import { SocketExposedInterface, SocketFunctionHook, SocketFunctionClientHook, SocketExposedShape, SocketRegistered, CallerContext, FullCallType, SocketRegisterType } from "socket-function/SocketFunctionTypes";
     import { SocketServerConfig } from "socket-function/src/webSocketServer";
     import { Args, MaybePromise } from "socket-function/src/types";
@@ -315,7 +314,6 @@ declare module "socket-function/require/CSSShim" {
 declare module "socket-function/require/RequireController" {
     /// <reference path="../../typenode/index.d.ts" />
     /// <reference types="node" />
-    /// <reference types="node" />
     declare global {
         namespace NodeJS {
             interface Module {
@@ -445,7 +443,6 @@ declare module "socket-function/require/compileFlags" {
 }
 
 declare module "socket-function/require/extMapper" {
-    /// <reference types="node" />
     /// <reference types="node" />
     export declare function getExtContentType(ext: string): string;
     export declare function getContentTypeFromBuffer(buffer: Buffer): string | undefined;
@@ -471,7 +468,6 @@ declare module "socket-function/require/require" {
 }
 
 declare module "socket-function/src/CallFactory" {
-    /// <reference types="node" />
     /// <reference types="node" />
     /// <reference types="node" />
     import { CallType } from "socket-function/SocketFunctionTypes";
@@ -530,7 +526,6 @@ declare module "socket-function/src/CallFactory" {
 }
 
 declare module "socket-function/src/JSONLACKS/JSONLACKS" {
-    /// <reference types="node" />
     /// <reference types="node" />
     export interface JSONLACKS_ParseConfig {
         extended?: boolean;
@@ -566,7 +561,6 @@ declare module "socket-function/src/JSONLACKS/JSONLACKS.generated.js" {
 }
 
 declare module "socket-function/src/Zip" {
-    /// <reference types="node" />
     /// <reference types="node" />
     import { MaybePromise } from "socket-function/src/types";
     export declare class Zip {
@@ -654,7 +648,6 @@ declare module "socket-function/src/batching" {
 }
 
 declare module "socket-function/src/bits" {
-    /// <reference types="node" />
     /// <reference types="node" />
     /** Subtracts the smallest possible value from a number (a double). This makes it possible to convert an exclusive range end
      *      to an inclusive range end, which is sometimes required (as in, < x is the same as <= minusEpsilon(x)).
@@ -681,7 +674,6 @@ declare module "socket-function/src/bits" {
 }
 
 declare module "socket-function/src/buffers" {
-    /// <reference types="node" />
     /// <reference types="node" />
     export type ArrayBufferViewTypes = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | BigUint64Array | BigInt64Array | Float64Array | Float32Array | Uint8ClampedArray;
     export type BufferType = ArrayBuffer | SharedArrayBuffer | ArrayBufferViewTypes;
@@ -759,7 +751,6 @@ declare module "socket-function/src/caching" {
 }
 
 declare module "socket-function/src/callHTTPHandler" {
-    /// <reference types="node" />
     /// <reference types="node" />
     /// <reference types="node" />
     import http from "http";
@@ -814,7 +805,6 @@ declare module "socket-function/src/callManager" {
 }
 
 declare module "socket-function/src/certStore" {
-    /// <reference types="node" />
     /// <reference types="node" />
     /** Must be populated before the server starts */
     export declare function trustCertificate(cert: string | Buffer): void;
@@ -942,11 +932,31 @@ declare module "socket-function/src/formatting/logColors" {
 }
 
 declare module "socket-function/src/forwardPort" {
+    export interface PortMapping {
+        externalPort: number;
+        internalPort: number;
+        protocol: string;
+        /** The LAN client the mapping forwards to (NewInternalClient). */
+        internalClient: string;
+        /** Empty string means "any" remote host (the usual case). */
+        remoteHost: string;
+        enabled: boolean;
+        description: string;
+        /** Remaining lease in seconds; 0 means a permanent (static) mapping. */
+        leaseDuration: number;
+    }
+    /** Queries the router for every existing UPnP port mapping by walking
+     *      GetGenericPortMappingEntry from index 0 until the gateway reports the index
+     *      is out of range (SOAP error 713 / a non-200 response). */
+    export declare function listPortMappings(): Promise<PortMapping[]>;
     export declare function forwardPort(config: {
         externalPort: number;
         internalPort: number;
         duration?: number;
     }): Promise<void>;
+    /** Our machine's LAN IP, as the router sees it — used to tell whether an existing port
+     *      mapping points at us or at a different machine on the network. */
+    export declare function getLocalInternalIP(): string | undefined;
 
 }
 
@@ -955,7 +965,6 @@ declare module "socket-function/src/getUniqueTime" {
 }
 
 declare module "socket-function/src/https" {
-    /// <reference types="node" />
     /// <reference types="node" />
     export declare function httpsRequest(url: string, payload?: Buffer | Buffer[], method?: string, sendSessionCookies?: boolean, config?: {
         headers?: {
@@ -967,7 +976,6 @@ declare module "socket-function/src/https" {
 }
 
 declare module "socket-function/src/lz4/LZ4" {
-    /// <reference types="node" />
     /// <reference types="node" />
     export declare class LZ4 {
         static compress(data: Buffer): Buffer;
@@ -1035,7 +1043,6 @@ declare module "socket-function/src/lz4/lz4_wasm_nodejs_bg.wasm" {
 }
 
 declare module "socket-function/src/misc" {
-    /// <reference types="node" />
     /// <reference types="node" />
     import { MaybePromise } from "socket-function/src/types";
     export declare const timeInSecond = 1000;
@@ -1465,7 +1472,6 @@ declare module "socket-function/src/storagePath" {
 }
 
 declare module "socket-function/src/tlsParsing" {
-    /// <reference types="node" />
     /// <reference types="node" />
     export declare function parseTLSHello(buffer: Buffer): {
         extensions: {
@@ -1489,8 +1495,12 @@ declare module "socket-function/src/types" {
 
 }
 
+declare module "socket-function/src/upreal" {
+    export {};
+
+}
+
 declare module "socket-function/src/webSocketServer" {
-    /// <reference types="node" />
     /// <reference types="node" />
     /// <reference types="node" />
     import https from "https";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "socket-function",
-	"version": "1.2.8",
+	"version": "1.2.10",
 	"main": "index.js",
 	"license": "MIT",
 	"dependencies": {
@@ -12,13 +12,17 @@
 		"preact": "10.24.3",
 		"typedev": "^0.4.0",
 		"typenode": "^6.0.1",
-		"ws": "^8.17.1"
+		"ws": "^8.21.0"
 	},
 	"optionalDependencies": {
 		"lmdb": "^3.5.1"
 	},
 	"types": "index.d.ts",
+	"bin": {
+		"upreal": "./bin/upreal.js"
+	},
 	"scripts": {
+		"upreal": "yarn typenode ./src/upreal.ts",
 		"test": "yarn typenode ./test.ts",
 		"test-all": "node run-test.js",
 		"type": "yarn tsc --noEmit",

package/require/RequireController.d.ts

@@ -1,6 +1,5 @@
 /// <reference path="../../typenode/index.d.ts" />
 /// <reference types="node" />
-/// <reference types="node" />
 declare global {
     namespace NodeJS {
         interface Module {

package/require/extMapper.d.ts

@@ -1,4 +1,3 @@
 /// <reference types="node" />
-/// <reference types="node" />
 export declare function getExtContentType(ext: string): string;
 export declare function getContentTypeFromBuffer(buffer: Buffer): string | undefined;

package/src/CallFactory.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="node" />
 /// <reference types="node" />
-/// <reference types="node" />
 import { CallType } from "../SocketFunctionTypes";
 import * as ws from "ws";
 import * as tls from "tls";

package/src/JSONLACKS/JSONLACKS.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 export interface JSONLACKS_ParseConfig {
     extended?: boolean;
     discardMissingReferences?: boolean;

package/src/Zip.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 import { MaybePromise } from "./types";
 export declare class Zip {
     static gzip(buffer: Buffer, level?: number): Promise<Buffer>;

package/src/bits.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 /** Subtracts the smallest possible value from a number (a double). This makes it possible to convert an exclusive range end
  *      to an inclusive range end, which is sometimes required (as in, < x is the same as <= minusEpsilon(x)).
  */

package/src/buffers.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 export type ArrayBufferViewTypes = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | BigUint64Array | BigInt64Array | Float64Array | Float32Array | Uint8ClampedArray;
 export type BufferType = ArrayBuffer | SharedArrayBuffer | ArrayBufferViewTypes;
 export declare function cloneBuffer(data: Buffer): Buffer;

package/src/callHTTPHandler.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="node" />
 /// <reference types="node" />
-/// <reference types="node" />
 import http from "http";
 import { CallType } from "../SocketFunctionTypes";
 export declare function setDefaultHTTPCall(call: CallType): void;

package/src/certStore.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 /** Must be populated before the server starts */
 export declare function trustCertificate(cert: string | Buffer): void;
 export declare function getTrustedCertificates(): string[];

package/src/forwardPort.d.ts

@@ -1,5 +1,25 @@
+export interface PortMapping {
+    externalPort: number;
+    internalPort: number;
+    protocol: string;
+    /** The LAN client the mapping forwards to (NewInternalClient). */
+    internalClient: string;
+    /** Empty string means "any" remote host (the usual case). */
+    remoteHost: string;
+    enabled: boolean;
+    description: string;
+    /** Remaining lease in seconds; 0 means a permanent (static) mapping. */
+    leaseDuration: number;
+}
+/** Queries the router for every existing UPnP port mapping by walking
+ *      GetGenericPortMappingEntry from index 0 until the gateway reports the index
+ *      is out of range (SOAP error 713 / a non-200 response). */
+export declare function listPortMappings(): Promise<PortMapping[]>;
 export declare function forwardPort(config: {
     externalPort: number;
     internalPort: number;
     duration?: number;
 }): Promise<void>;
+/** Our machine's LAN IP, as the router sees it — used to tell whether an existing port
+ *      mapping points at us or at a different machine on the network. */
+export declare function getLocalInternalIP(): string | undefined;

package/src/forwardPort.ts

@@ -6,6 +6,72 @@ import { timeInHour } from "./misc";
 const SSDP_DISCOVER_MX = 2;
 const SSDP_DISCOVER_MSG = `M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\nMAN: "ssdp:discover"\r\nMX: ${SSDP_DISCOVER_MX}\r\nST: urn:schemas-upnp-org:device:InternetGatewayDevice:1\r\n\r\n`;
 
+/** Resolves the UPnP Internet Gateway Device we can talk to, along with the local
+ *      addressing needed to build SOAP requests against it. Shared by every operation
+ *      that needs to reach the router's control endpoint. */
+async function resolveGateway(): Promise<{
+    internalIP: string;
+    gatewayIP: string;
+    controlPort: number;
+    controlURLs: string[];
+}> {
+    const localObj = getLocalInterfaceAddress();
+    if (!localObj) throw new Error("Could not find the local address / gateway");
+
+    const { internalIP, gatewayIP } = localObj;
+    console.log(`Local IP: ${internalIP}, Gateway IP: ${gatewayIP}`);
+    let gateway = await discoverGateway(internalIP);
+    let controlURLs = await getControlPaths(gateway);
+    let controlPort = Number(new URL(gateway).port);
+
+    return { internalIP, gatewayIP, controlPort, controlURLs };
+}
+
+export interface PortMapping {
+    externalPort: number;
+    internalPort: number;
+    protocol: string;
+    /** The LAN client the mapping forwards to (NewInternalClient). */
+    internalClient: string;
+    /** Empty string means "any" remote host (the usual case). */
+    remoteHost: string;
+    enabled: boolean;
+    description: string;
+    /** Remaining lease in seconds; 0 means a permanent (static) mapping. */
+    leaseDuration: number;
+}
+
+/** Queries the router for every existing UPnP port mapping by walking
+ *      GetGenericPortMappingEntry from index 0 until the gateway reports the index
+ *      is out of range (SOAP error 713 / a non-200 response). */
+export async function listPortMappings(): Promise<PortMapping[]> {
+    if (os.platform() === "linux") return [];
+
+    const { internalIP, gatewayIP, controlPort, controlURLs } = await resolveGateway();
+
+    let lastError: unknown;
+    for (let controlURL of controlURLs) {
+        try {
+            const mappings: PortMapping[] = [];
+            for (let index = 0; ; index++) {
+                const entry = await getGenericPortMappingEntry({
+                    gatewayIP,
+                    controlPort,
+                    controlPath: controlURL,
+                    index,
+                });
+                if (!entry) break;
+                mappings.push(entry);
+            }
+            return mappings;
+        } catch (e) {
+            lastError = e;
+            console.error(`Failed to list port mappings using controlURL ${controlURL}`, e);
+        }
+    }
+    throw new Error(`Failed to list port mappings, could not find a working controlURL. Last error: ${(lastError as Error)?.stack ?? lastError}`);
+}
+
 export async function forwardPort(config: {
     externalPort: number;
     internalPort: number;
@@ -18,14 +84,7 @@ export async function forwardPort(config: {
         const { externalPort, internalPort } = config;
         let duration = config.duration ?? timeInHour;
 
-        const localObj = getLocalInterfaceAddress();
-        if (!localObj) throw new Error("Could not find the local address / gateway");
-
-        const { internalIP, gatewayIP } = localObj;
-        console.log(`Local IP: ${internalIP}, Gateway IP: ${gatewayIP}`);
-        let gateway = await discoverGateway(internalIP);
-        let controlURLs = await getControlPaths(gateway);
-        let controlPort = Number(new URL(gateway).port);
+        const { internalIP, gatewayIP, controlPort, controlURLs } = await resolveGateway();
 
         for (let controlURL of controlURLs) {
             try {
@@ -49,6 +108,12 @@ export async function forwardPort(config: {
     }
 }
 
+/** Our machine's LAN IP, as the router sees it — used to tell whether an existing port
+ *      mapping points at us or at a different machine on the network. */
+export function getLocalInternalIP(): string | undefined {
+    return getLocalInterfaceAddress()?.internalIP;
+}
+
 function getLocalInterfaceAddress(): { internalIP: string; gatewayIP: string; } | undefined {
     let looksLikeRouter = (ip: string) => ip.startsWith("10.0.0") || ip.startsWith("10.0.1") || ip.startsWith("192.168.0");
 
@@ -216,3 +281,61 @@ async function createPortMapping(config: {
         throw new Error(`Failed to create port mapping: ${data}`);
     }
 }
+
+// UPnP returns this error code when we walk past the last mapping index, which is how
+//  we detect the end of the list rather than a real failure.
+const UPNP_ARRAY_INDEX_INVALID = 713;
+
+/** Fetches a single port mapping by its index. Returns undefined once the index is past
+ *      the end of the table (the router's signal that there are no more entries). */
+async function getGenericPortMappingEntry(config: {
+    gatewayIP: string;
+    controlPort: number;
+    controlPath: string;
+    index: number;
+}): Promise<PortMapping | undefined> {
+    const { gatewayIP, controlPort, controlPath, index } = config;
+    const action = "\"urn:schemas-upnp-org:service:WANIPConnection:1#GetGenericPortMappingEntry\"";
+
+    const soapBody = `
+        <?xml version="1.0"?>
+        <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
+            <s:Body>
+                <u:GetGenericPortMappingEntry xmlns:u="urn:schemas-upnp-org:service:WANIPConnection:1">
+                    <NewPortMappingIndex>${index}</NewPortMappingIndex>
+                </u:GetGenericPortMappingEntry>
+            </s:Body>
+        </s:Envelope>
+    `;
+
+    const res = await fetch(`http://${gatewayIP}:${controlPort}${controlPath}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/xml; charset=\"utf-8\"",
+            "SOAPAction": action,
+            "Content-Length": Buffer.byteLength(soapBody) + "",
+        },
+        body: soapBody
+    });
+
+    const data = await res.text();
+    if (res.status !== 200) {
+        let errorCode = Number(data.match(/<errorCode>(\d+)<\/errorCode>/)?.[1]);
+        if (errorCode === UPNP_ARRAY_INDEX_INVALID) {
+            return undefined;
+        }
+        throw new Error(`Failed to get port mapping entry ${index}: ${res.status} ${data}`);
+    }
+
+    let getField = (name: string) => data.match(new RegExp(`<${name}>(.*?)</${name}>`, "s"))?.[1] ?? "";
+    return {
+        externalPort: Number(getField("NewExternalPort")),
+        internalPort: Number(getField("NewInternalPort")),
+        protocol: getField("NewProtocol"),
+        internalClient: getField("NewInternalClient"),
+        remoteHost: getField("NewRemoteHost"),
+        enabled: getField("NewEnabled") === "1",
+        description: getField("NewPortMappingDescription"),
+        leaseDuration: Number(getField("NewLeaseDuration")),
+    };
+}

package/src/https.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 export declare function httpsRequest(url: string, payload?: Buffer | Buffer[], method?: string, sendSessionCookies?: boolean, config?: {
     headers?: {
         [key: string]: string | undefined;

package/src/lz4/LZ4.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 export declare class LZ4 {
     static compress(data: Buffer): Buffer;
     static compressUntracked(data: Buffer): Buffer;

package/src/misc.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 import { MaybePromise } from "./types";
 export declare const timeInSecond = 1000;
 export declare const timeInMinute: number;

package/src/tlsParsing.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="node" />
 export declare function parseTLSHello(buffer: Buffer): {
     extensions: {
         type: number;

package/src/upreal.d.ts

@@ -0,0 +1 @@
+export {};

package/src/upreal.ts

@@ -0,0 +1,197 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as https from "https";
+import { spawn } from "child_process";
+
+// Dependency sections in package.json that upreal is willing to update, in the order we search them.
+const DEP_SECTIONS = [
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+] as const;
+
+async function main() {
+    let packageName = process.argv.slice(2).find(arg => !arg.startsWith("-"));
+    if (!packageName) {
+        console.error("Usage: yarn upreal <package-name>");
+        process.exit(1);
+        return;
+    }
+
+    let projectRoot = process.cwd();
+    let packageJsonPath = path.join(projectRoot, "package.json");
+    let lockPath = path.join(projectRoot, "yarn.lock");
+
+    let packageJsonRaw = fs.readFileSync(packageJsonPath, "utf8");
+    let packageJson = JSON.parse(packageJsonRaw) as {
+        [section: string]: { [name: string]: string } | undefined;
+    };
+
+    let currentRange = findCurrentRange(packageJson, packageName);
+    if (currentRange === undefined) {
+        console.error(`Package "${packageName}" is not listed in ${DEP_SECTIONS.join(", ")} of package.json`);
+        process.exit(1);
+        return;
+    }
+
+    console.log(`Current range for ${packageName}: ${currentRange}`);
+
+    let latest = await getLatestVersion(packageName);
+    console.log(`Latest version of ${packageName}: ${latest}`);
+
+    let newRange = applyPrefix(currentRange, latest);
+    if (newRange === currentRange) {
+        console.log(`package.json range unchanged (${currentRange}); will still re-resolve the lockfile.`);
+    } else {
+        packageJsonRaw = replaceRange(packageJsonRaw, packageName, currentRange, newRange);
+        fs.writeFileSync(packageJsonPath, packageJsonRaw);
+        console.log(`Updated package.json: ${packageName} ${currentRange} -> ${newRange}`);
+    }
+
+    // Drop every lockfile entry for this package so `yarn install` re-resolves each of its ranges (ours and any
+    // transitive ones) to the newest version they can reach. This is what makes "everything that could be updated"
+    // update in one shot, rather than yarn pinning the previously-locked versions.
+    if (fs.existsSync(lockPath)) {
+        let lockRaw = fs.readFileSync(lockPath, "utf8");
+        let { lock, removed } = removeLockEntries(lockRaw, packageName);
+        if (removed > 0) {
+            fs.writeFileSync(lockPath, lock);
+            console.log(`Removed ${removed} lockfile entr${removed === 1 ? "y" : "ies"} for ${packageName} so they re-resolve.`);
+        }
+    }
+
+    console.log(`Running yarn install...`);
+    await runYarnInstall(projectRoot);
+    console.log(`Done. ${packageName} is now at ${newRange}.`);
+}
+
+function findCurrentRange(
+    packageJson: { [section: string]: { [name: string]: string } | undefined },
+    packageName: string
+): string | undefined {
+    for (let section of DEP_SECTIONS) {
+        let deps = packageJson[section];
+        if (deps && packageName in deps) {
+            return deps[packageName];
+        }
+    }
+    return undefined;
+}
+
+async function getLatestVersion(packageName: string): Promise<string> {
+    // Scoped names ("@scope/name") must have their slash encoded in the registry path.
+    let encodedName = packageName.startsWith("@")
+        ? "@" + encodeURIComponent(packageName.slice(1))
+        : encodeURIComponent(packageName);
+    let url = `https://registry.npmjs.org/${encodedName}/latest`;
+
+    let body = await new Promise<string>((resolve, reject) => {
+        https.get(url, res => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                reject(new Error(`Registry returned ${res.statusCode} for ${url}`));
+                return;
+            }
+            let chunks: Buffer[] = [];
+            res.on("data", chunk => chunks.push(chunk));
+            res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        }).on("error", reject);
+    });
+
+    let parsed = JSON.parse(body) as { version?: string };
+    if (!parsed.version) {
+        throw new Error(`Registry response for ${packageName} had no version field`);
+    }
+    return parsed.version;
+}
+
+// Keep whatever range operator the user already chose (^, ~, exact, or *) and point it at the new version.
+function applyPrefix(currentRange: string, latest: string): string {
+    if (currentRange === "*" || currentRange === "" || currentRange === "latest") {
+        return currentRange;
+    }
+    if (currentRange.startsWith("^")) {
+        return "^" + latest;
+    }
+    if (currentRange.startsWith("~")) {
+        return "~" + latest;
+    }
+    return latest;
+}
+
+function replaceRange(packageJsonRaw: string, packageName: string, oldRange: string, newRange: string): string {
+    // Rewrite the value in place (rather than JSON.stringify) so the file keeps its exact formatting and tab style.
+    let keyPattern = new RegExp(`("${escapeRegExp(packageName)}"\\s*:\\s*")${escapeRegExp(oldRange)}(")`);
+    if (!keyPattern.test(packageJsonRaw)) {
+        throw new Error(`Could not locate "${packageName}": "${oldRange}" in package.json to update`);
+    }
+    return packageJsonRaw.replace(keyPattern, `$1${newRange}$2`);
+}
+
+// Remove all yarn.lock v1 blocks that resolve the given package (across every range variant of it).
+function removeLockEntries(lockRaw: string, packageName: string): { lock: string; removed: number } {
+    // yarn.lock v1 blocks are separated by blank lines; the first line of each block is the comma-separated
+    // list of specs it satisfies, e.g. `"pkg@^1.0.0", "pkg@~1.2.0":`.
+    let blocks = lockRaw.split(/\r?\n\r?\n/);
+    let removed = 0;
+    let kept: string[] = [];
+    for (let block of blocks) {
+        if (blockResolvesPackage(block, packageName)) {
+            removed++;
+            continue;
+        }
+        kept.push(block);
+    }
+    return { lock: kept.join("\n\n"), removed };
+}
+
+function blockResolvesPackage(block: string, packageName: string): boolean {
+    let headerLine = block.split(/\r?\n/).find(line => line.trim().length > 0 && !line.startsWith("#"));
+    if (!headerLine || !headerLine.trimEnd().endsWith(":")) {
+        return false;
+    }
+    // Strip the trailing colon, then split on commas into individual quoted-or-bare specs.
+    let specsPart = headerLine.trimEnd().replace(/:$/, "");
+    let specs = specsPart.split(",").map(spec => spec.trim().replace(/^"|"$/g, ""));
+    for (let spec of specs) {
+        if (specNamePackage(spec) === packageName) {
+            return true;
+        }
+    }
+    return false;
+}
+
+// Extract the package name from a lock spec like `@scope/name@^1.0.0` or `name@~1.2.0`.
+function specNamePackage(spec: string): string {
+    let atIndex = spec.lastIndexOf("@");
+    // A leading "@" (scoped package) is part of the name, not the name/range separator.
+    if (atIndex <= 0) {
+        return spec;
+    }
+    return spec.slice(0, atIndex);
+}
+
+function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+async function runYarnInstall(cwd: string): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+        // yarn is a .cmd shim on Windows, so it must be spawned through the shell.
+        let child = spawn("yarn", ["install"], { cwd, stdio: "inherit", shell: true });
+        child.on("error", reject);
+        child.on("exit", code => {
+            if (code === 0) {
+                resolve();
+            } else {
+                reject(new Error(`yarn install exited with code ${code}`));
+            }
+        });
+    });
+}
+
+main().catch(e => {
+    console.error(e.stack ?? e);
+    process.exit(1);
+});

package/src/webSocketServer.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="node" />
 /// <reference types="node" />
-/// <reference types="node" />
 import https from "https";
 import { Watchable } from "./misc";
 export type SocketServerConfig = (https.ServerOptions & {

package/src/webSocketServer.ts

@@ -12,13 +12,14 @@ import debugbreak from "debugbreak";
 import { getNodeId } from "./nodeCache";
 import crypto from "crypto";
 import { Watchable, getRootDomain, timeInHour, timeInMinute } from "./misc";
-import { delay, runInfinitePoll, runInfinitePollCallAtStart } from "./batching";
+import { delay, runInfinitePoll } from "./batching";
 import { magenta, red } from "./formatting/logColors";
 import { yellow } from "./formatting/logColors";
 import { green } from "./formatting/logColors";
 import { formatTime } from "./formatting/format";
 import { getExternalIP, testTCPIsListening } from "./networking";
-import { forwardPort } from "./forwardPort";
+import { forwardPort, listPortMappings, getLocalInternalIP, PortMapping } from "./forwardPort";
+import os from "os";
 
 // When a requested port is taken and useAvailablePortIfPortInUse is set, we scan
 //  upwards from this base instead of binding a random OS-assigned port, so restarts
@@ -348,49 +349,103 @@ export async function startSocketServer(
         });
     }
 
-    let bound = false;
-    // Honor an explicitly requested port first. A falsy port (0, the default) means
-    //  "no preference" — skip straight to the scan so we land on a consistent port
-    //  instead of an OS-assigned random one.
-    if (port) {
-        bound = await tryListen(port);
-        if (!bound && !config.useAvailablePortIfPortInUse) {
-            throw new Error(`Port ${port} is already in use (set useAvailablePortIfPortInUse to fall back to another port)`);
+    // Frees the currently-bound listening socket so we can rebind on a different port
+    //  (used when a locally-free port turns out to be unusable for forwarding).
+    async function releasePort(): Promise<void> {
+        await new Promise<void>((resolve, reject) => {
+            if (!realServer.listening) {
+                resolve();
+                return;
+            }
+            realServer.close(e => e ? reject(e) : resolve());
+        });
+    }
+
+    // Forwarding maps the external port to an equal internal port, so a candidate is only
+    //  usable if we can also own its external mapping on the router. Skipped on linux,
+    //  where forwardPort is a no-op anyway.
+    const doForward = !!(config.autoForwardPort && config.public && os.platform() !== "linux");
+
+    // Ensures the router's external mapping for `externalPort` belongs to us. Returns true
+    //  if it's ours to keep (existing-and-ours → refresh the lease; free → create and
+    //  confirm we won it), false if another machine owns it and we should try a new port.
+    async function claimPortForward(externalPort: number): Promise<boolean> {
+        const ourIP = getLocalInternalIP();
+        const matches = (m: PortMapping) => m.externalPort === externalPort && m.protocol.toUpperCase() === "TCP";
+
+        const existing = (await listPortMappings()).find(matches);
+        if (existing) {
+            if (ourIP && existing.internalClient === ourIP) {
+                await forwardPort({ externalPort, internalPort: externalPort });
+                return true;
+            }
+            console.log(magenta(`External port ${externalPort} is already forwarded to ${existing.internalClient}, trying another port`));
+            return false;
+        }
+
+        // Free right now — create the mapping, then re-read it to make sure another host
+        //  didn't grab the same external port in the race between our list and our create.
+        await forwardPort({ externalPort, internalPort: externalPort });
+        const ours = (await listPortMappings()).find(matches);
+        if (!ours || (ourIP && ours.internalClient !== ourIP)) {
+            console.log(magenta(`Failed to claim external port ${externalPort} (now ${ours ? `forwarded to ${ours.internalClient}` : "still unmapped"}), trying another port`));
+            return false;
         }
+        return true;
     }
-    // Scan upwards from PORT_SCAN_START for the first free port, so restarts land on
-    //  predictable ports.
-    if (!bound) {
+
+    // Candidate ports: an explicitly requested port first (a falsy port, the default 0,
+    //  means "no preference"), then a consistent upward scan so restarts are predictable.
+    function* candidatePorts(): Generator<number> {
+        if (port) yield port;
         for (let candidate = PORT_SCAN_START; candidate < PORT_SCAN_START + PORT_SCAN_COUNT; candidate++) {
             if (candidate === port) continue;
-            if (await tryListen(candidate)) {
-                bound = true;
-                port = candidate;
-                break;
+            yield candidate;
+        }
+    }
+
+    let bound = false;
+    for (const candidate of candidatePorts()) {
+        if (!await tryListen(candidate)) {
+            if (candidate === config.port && !config.useAvailablePortIfPortInUse) {
+                throw new Error(`Port ${candidate} is already in use (set useAvailablePortIfPortInUse to fall back to another port)`);
             }
+            continue;
         }
-        if (!bound) {
-            throw new Error(`Could not find an available port in range ${PORT_SCAN_START}-${PORT_SCAN_START + PORT_SCAN_COUNT - 1} (requested ${config.port})`);
+        // Locally bound. If we also forward, the external mapping must be ours too, or we
+        //  release this port and keep scanning.
+        if (doForward) {
+            let claimed: boolean;
+            try {
+                claimed = await claimPortForward(candidate);
+            } catch (e) {
+                // UPnP unavailable (no gateway / discovery failed): fall back to best-effort
+                //  forwarding rather than refusing to start.
+                console.error(red(`Could not verify forwarding for port ${candidate}, continuing best-effort: ${(e as Error).stack}`));
+                claimed = true;
+            }
+            if (!claimed) {
+                await releasePort();
+                continue;
+            }
         }
+        port = candidate;
+        bound = true;
+        break;
+    }
+    if (!bound) {
+        throw new Error(`Could not find an available port in range ${PORT_SCAN_START}-${PORT_SCAN_START + PORT_SCAN_COUNT - 1} (requested ${config.port})`);
     }
 
     port = (realServer.address() as net.AddressInfo).port;
 
-    if (config.autoForwardPort && config.public) {
-        // let externalIP = await getExternalIP();
-        // let isListening = await testTCPIsListening(externalIP, port);
-        // if (!isListening) {
-        //     console.log(magenta(`Port ${port} is not externally reachable, trying to forward it`));
-        //     await forwardPort({ externalPort: port, internalPort: port });
-        // }
-        // Even if they are listening, they might not stay listening. Forward every 8 hours
-        //      (including at the start, in case the forward is about to expire).
-        async function forward() {
+    if (doForward) {
+        // The mapping is claimed above; keep refreshing the lease so it doesn't expire.
+        async function refreshForward() {
             await forwardPort({ externalPort: port, internalPort: port });
-            console.log(magenta(`Forwarded port ${port} to our machine`));
+            console.log(magenta(`Refreshed port forward ${port} to our machine`));
         }
-        // Every hour, in case our network configuration changes
-        runInfinitePollCallAtStart(timeInMinute * 30, forward).catch(e => console.error(red(`Error in port forwarding ${e.stack}`)));
+        runInfinitePoll(timeInMinute * 30, refreshForward);
     }
 
     let nodeId = getNodeId(getCommonName(config.cert), port);

package/test.ts

@@ -1,161 +1,17 @@
-import { computeTweenedOffset, getTimeComponentsDetailed, waitForFirstTimeSync } from "./time/trueTimeShim";
 import * as fs from "fs";
 import * as path from "path";
+import { listPortMappings } from "./src/forwardPort";
 
-const SAMPLE_COUNT = 1000;
-const SAMPLE_INTERVAL_MS = 10;
-
-// Generate a simple numeric ID for this test run
-const TEST_RUN_ID = Math.floor(Math.random() * 10000);
-
-async function sampleMode() {
-    await waitForFirstTimeSync();
-
-    type Sample = {
-        id: number;
-        systemTime: number;
-        offset: number;
-        fromOffset: number;
-        toOffset: number;
-        fromTime: number;
-        toTime: number;
-    };
-
-    const samples: Sample[] = [];
-
-    console.log(`[Test ID: ${TEST_RUN_ID}] Sampling ${SAMPLE_COUNT} time components...`);
-    for (let i = 0; i < SAMPLE_COUNT; i++) {
-        const detailed = getTimeComponentsDetailed();
-
-        // Calculate the tween using the same systemTime
-        const offset = computeTweenedOffset(detailed);
-
-        samples.push({
-            id: TEST_RUN_ID,
-            systemTime: detailed.systemTime,
-            offset,
-            fromOffset: detailed.fromOffset,
-            toOffset: detailed.toOffset,
-            fromTime: detailed.fromTime,
-            toTime: detailed.toTime,
-        });
-
-        if (SAMPLE_INTERVAL_MS > 0) {
-            await new Promise(resolve => setTimeout(resolve, SAMPLE_INTERVAL_MS));
-        }
-    }
-
-    // Write to file with unique name
-    const distDir = path.join(__dirname, "dist");
-    if (!fs.existsSync(distDir)) {
-        fs.mkdirSync(distDir, { recursive: true });
-    }
-
-    const filename = path.join(distDir, `time-samples-${Date.now()}-${process.pid}.json`);
-    fs.writeFileSync(filename, JSON.stringify(samples, null, 2));
-
-    console.log(`[Test ID: ${TEST_RUN_ID}] Wrote ${samples.length} samples to ${filename}`);
-}
-
-async function verifyMode() {
-    const distDir = path.join(__dirname, "dist");
-    if (!fs.existsSync(distDir)) {
-        console.error("No dist directory found. Run sampling mode first.");
-        process.exit(1);
-    }
-
-    const files = fs.readdirSync(distDir)
-        .filter(f => f.startsWith("time-samples-") && f.endsWith(".json"))
-        .map(f => path.join(distDir, f));
-
-    if (files.length === 0) {
-        console.error("No sample files found. Run sampling mode first.");
-        process.exit(1);
-    }
-
-    console.log(`Found ${files.length} sample files`);
-
-    type Sample = {
-        id: number;
-        systemTime: number;
-        offset: number;
-        fromOffset: number;
-        toOffset: number;
-        fromTime: number;
-        toTime: number;
-        file: string;
-    };
-
-    // Load all samples from all files
-    const allSamples: Sample[] = [];
-
-    for (const file of files) {
-        const content = fs.readFileSync(file, "utf-8");
-        const samples = JSON.parse(content);
-        for (const sample of samples) {
-            allSamples.push({ ...sample, file: path.basename(file) });
-        }
-    }
-
-    console.log(`Loaded ${allSamples.length} total samples`);
-
-    // Sort by systemTime
-    allSamples.sort((a, b) => a.systemTime - b.systemTime);
-
-    // Verify that systemTime + offset is monotonically increasing
-    let errors = 0;
-    let lastTrueTime = -Infinity;
-
-    for (let i = 0; i < allSamples.length; i++) {
-        const sample = allSamples[i];
-        const trueTime = sample.systemTime + sample.offset;
-
-        if (trueTime < lastTrueTime) {
-            errors++;
-            const prev = allSamples[i - 1];
-            const prevTrueTime = prev.systemTime + prev.offset;
-
-            console.error(`\nERROR at index ${i}: trueTime went backwards!`);
-            console.error(`  Previous [ID: ${prev.id}, file: ${prev.file}]:`);
-            console.error(`    systemTime: ${prev.systemTime}`);
-            console.error(`    offset: ${prev.offset}`);
-            console.error(`    trueTime: ${prevTrueTime}`);
-            console.error(`    tween: ${prev.fromOffset} -> ${prev.toOffset}`);
-            console.error(`    timeWindow: ${prev.fromTime} -> ${prev.toTime}`);
-            console.error(`  Current [ID: ${sample.id}, file: ${sample.file}]:`);
-            console.error(`    systemTime: ${sample.systemTime}`);
-            console.error(`    offset: ${sample.offset}`);
-            console.error(`    trueTime: ${trueTime}`);
-            console.error(`    tween: ${sample.fromOffset} -> ${sample.toOffset}`);
-            console.error(`    timeWindow: ${sample.fromTime} -> ${sample.toTime}`);
-            console.error(`  Difference: ${trueTime - lastTrueTime}ms`);
-        }
-
-        lastTrueTime = trueTime;
-    }
-
-    if (errors === 0) {
-        console.log(`✓ SUCCESS: All ${allSamples.length} samples are correctly ordered!`);
-        console.log(`  Time range: ${allSamples[0].systemTime} to ${allSamples[allSamples.length - 1].systemTime}`);
-        console.log(`  Duration: ${allSamples[allSamples.length - 1].systemTime - allSamples[0].systemTime}ms`);
-    } else {
-        console.error(`✗ FAILED: Found ${errors} ordering violations`);
-        process.exit(1);
-    }
-}
 
 async function main() {
-    const mode = process.argv[2];
-
-    if (mode === "once") {
-        await waitForFirstTimeSync();
-        console.log(Date.now());
-    }
-    else if (mode === "verify") {
-        await verifyMode();
-    } else {
-        await sampleMode();
-    }
+    let mappings = await listPortMappings();
+    console.log(`Found ${mappings.length} port mapping(s):`);
+    for (let mapping of mappings) {
+        let host = mapping.remoteHost || "*";
+        let lease = mapping.leaseDuration === 0 ? "permanent" : `${mapping.leaseDuration}s left`;
+        console.log(`  ${mapping.protocol} ${host}:${mapping.externalPort} -> ${mapping.internalClient}:${mapping.internalPort} (${mapping.enabled ? "enabled" : "disabled"}, ${lease})${mapping.description ? ` "${mapping.description}"` : ""}`);
+    }
+    console.table(mappings);
 }
 
-main().catch(e => console.error(e)).finally(() => process.exit(0));
+main().catch(e => console.error(e)).finally(() => process.exit(0));