@nativescript/vite 8.0.0-alpha.2 → 8.0.0-alpha.20

package/helpers/dev-host.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Canonical resolver for the Vite dev-server origin that a NativeScript
+ * device or simulator can actually reach.
+ *
+ * Why this exists. The Vite dev server commonly binds to `0.0.0.0`
+ * (the wildcard "all interfaces" address) so both the host browser and
+ * a sibling mobile device can hit it. That bind address is fine for
+ * the LISTENING socket — but it is NOT a routable hostname:
+ *
+ *   - iOS Simulator shares the host's network stack, so `localhost` /
+ *     `127.0.0.1` work from inside the simulator and even `0.0.0.0`
+ *     sometimes resolves there. The simulator path is forgiving.
+ *
+ *   - Android Emulator runs inside a virtual NIC with NAT (QEMU
+ *     `slirp`). `0.0.0.0` and `localhost` / `127.0.0.1` refer to the
+ *     EMULATOR ITSELF, not the development host. Two routable paths
+ *     exist:
+ *
+ *       (a) `adb reverse tcp:<port> tcp:<port>` — multiplexes the
+ *           device-side `127.0.0.1:<port>` over the existing ADB
+ *           transport to the host. This is the PREFERRED path: slirp
+ *           is famously flaky under burst-connect load and drops
+ *           ~80% of cold-boot module-loader fetches with
+ *           `IOException: unexpected end of stream`. The ADB tunnel
+ *           bypasses slirp entirely and is reliable. We try this
+ *           automatically — see `tryEnableAdbReverse`. We emit the
+ *           IPv4 literal `127.0.0.1` instead of `localhost` because
+ *           Android API 36+ system images periodically ship without
+ *           a `localhost` mapping in the resolver, and
+ *           `UnknownHostException` fires before adb-reverse can do
+ *           its job.
+ *
+ *       (b) `10.0.2.2` (Genymotion: `10.0.3.2`) — slirp's host alias.
+ *           Used as a fallback when ADB isn't available or the user
+ *           opted out via `NS_HMR_NO_ADB_REVERSE=1`. Works, just less
+ *           reliable than the ADB tunnel.
+ *
+ *   - Physical Android devices over USB get the same automatic
+ *     `adb reverse` treatment as emulators. Over Wi-Fi (no ADB
+ *     tunnel), the user must opt out of adb reverse via
+ *     `NS_HMR_NO_ADB_REVERSE=1` and supply a routable host via
+ *     `NS_HMR_HOST=<ip>` or `NS_HMR_PREFER_LAN_HOST=1`.
+ *
+ * Without this normalization, `bundle.mjs` ships with statically
+ * embedded URLs like `http://0.0.0.0:5173/ns/core/xhr` and the very
+ * first dynamic import during Application boot fails with
+ * `status=0 (network unreachable)` on Android, killing the runtime
+ * before any user code runs.
+ *
+ * Resolution rules (highest precedence first):
+ *
+ *   1. `process.env.NS_HMR_HOST` — always wins. CI, tunneled setups,
+ *      and remote devices use this to point at a known-good origin.
+ *
+ *   2. A concrete non-wildcard, non-loopback `host` arg — trust the
+ *      developer's explicit choice (`server.host: '192.168.1.42'`
+ *      already routes from any device on the LAN).
+ *
+ *   3. `process.env.NS_HMR_PREFER_LAN_HOST` truthy AND a LAN NIC is
+ *      detected — emit the LAN IP. Opt-in for physical-device-over-
+ *      Wi-Fi dev. Also disables the adb-reverse path below so the
+ *      caller actually gets LAN routing.
+ *
+ *   4. Wildcard bind (`0.0.0.0`, `::`, `true`, empty) OR Android
+ *      loopback — emit the platform-appropriate routable address.
+ *      For Android, we first try `adb reverse tcp:<port> tcp:<port>`
+ *      and emit `127.0.0.1` on success (bypasses slirp NAT entirely
+ *      and avoids Android API 36+'s missing-`localhost`-from-resolver
+ *      bug); on failure we fall back to `10.0.2.2`. iOS/visionOS get
+ *      `localhost` directly. iOS/visionOS loopback passes through
+ *      unchanged.
+ *
+ * Every dev-mode emitter that bakes a URL into `bundle.mjs` or sends
+ * one to a device-side fetch site MUST run through this helper so the
+ * device receives a single canonical, reachable origin.
+ */
+export type DevHostPlatform = 'android' | 'ios' | 'visionos';
+/**
+ * Per-port cache of `adb reverse` setup attempts. Keyed by port so
+ * dev servers that switch ports across restarts get a clean attempt
+ * each time. The cache is required because every entry point that
+ * embeds a device-reachable URL (the bundle.mjs boot path, the
+ * `/ns/core/*` external resolver, the websocket URL emitter, the
+ * served-module rewriter) hits `resolveDeviceReachable*` — if we
+ * spawned `adb reverse` on every call we'd fork ~half a dozen
+ * subprocesses per Vite startup and the cold-boot would slow
+ * noticeably.
+ *
+ * The cache also gives us a stable answer across all consumers: once
+ * the first caller learns that adb reverse is available, every later
+ * caller in the same process gets the same `localhost`/`10.0.2.2`
+ * decision. URL identity is what keeps the iOS HTTP ESM realm from
+ * splitting and what keeps the Android HMR client and bundle.mjs
+ * pointing at the same origin.
+ */
+interface AdbReverseStatus {
+    attempted: boolean;
+    succeeded: boolean;
+    error?: string;
+    /** Device serials that successfully received the reverse mapping. */
+    devices: string[];
+}
+/**
+ * Returns the first non-internal IPv4 address on the host machine, or
+ * `undefined` if no LAN NIC is up. Pure wrapper around
+ * `os.networkInterfaces()` so callers and tests can stub it cleanly.
+ */
+export declare function guessLanHost(): string | undefined;
+/**
+ * Whether the given host string is a wildcard "all interfaces" bind
+ * address rather than a routable hostname. `host` may be the literal
+ * string from a Vite config (`'0.0.0.0'`), an empty string, or `'true'`
+ * (some older Vite/CLI surfaces stringify the boolean).
+ */
+export declare function isWildcardHost(host: string): boolean;
+/**
+ * Whether the given host string is loopback. On Android the loopback
+ * address is the device itself, NOT the development host — so callers
+ * must remap it for Android consumers.
+ */
+export declare function isLoopbackHost(host: string): boolean;
+export interface DeviceHostResolution {
+    /** Final host string baked into the device-side URL. */
+    host: string;
+    /**
+     * How the value was chosen. `'env'` / `'explicit'` mean the result
+     * is locked-in; `'lan'`, `'adb-reverse'`, and `'platform-default'`
+     * are fallbacks selected by this helper.
+     */
+    source: 'env' | 'explicit' | 'lan' | 'adb-reverse' | 'platform-default';
+}
+export interface ResolveDeviceHostOptions {
+    /** The raw host value from the Vite config (`server.host`). */
+    host?: unknown;
+    /** Target device platform. Drives the loopback / wildcard fallback. */
+    platform: DevHostPlatform;
+    /**
+     * Override for `process.env`. Tests pass a fixture object; runtime
+     * callers omit this and pick up the ambient process environment.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Override for `guessLanHost()`. Tests stub a fixed return value;
+     * runtime callers omit this and the helper hits real NICs.
+     */
+    lanHostResolver?: () => string | undefined;
+    /**
+     * Dev-server port. When set AND `platform === 'android'`, this
+     * helper will lazily attempt `adb reverse tcp:<port> tcp:<port>`
+     * on first call and, if it succeeds, emit `localhost` instead of
+     * `10.0.2.2`. See `tryEnableAdbReverse` for the full rationale.
+     *
+     * Optional for backwards compatibility — callers that already have
+     * the port (which is everyone except a couple of legacy test
+     * fixtures) should pass it so Android emulator users get the
+     * reliable ADB tunnel path instead of QEMU slirp's flaky NAT.
+     */
+    port?: number;
+    /**
+     * Test seam for the adb-reverse subprocess. When passed, this
+     * helper uses the injected exec function instead of spawning
+     * `child_process.execSync`. Runtime callers omit this and pick
+     * up the real ADB binary on PATH.
+     */
+    adbExec?: AdbExec;
+}
+/**
+ * Subprocess shim used by `tryEnableAdbReverse`. Production code
+ * routes through `child_process.execSync`; tests stub it so the
+ * suite can exercise success / failure / "multiple devices" /
+ * "no ADB on PATH" paths without touching a real Android emulator.
+ *
+ * The signature deliberately matches the subset of `execSync` we
+ * need so we never have to plumb `ExecSyncOptionsWithBufferEncoding`
+ * through the call chain — a string-returning shim is enough here.
+ */
+export type AdbExec = (cmd: string, opts: {
+    timeout: number;
+}) => string;
+export interface TryEnableAdbReverseOptions {
+    /** Port to forward on both sides of the ADB bridge. */
+    port: number;
+    /** Override for `process.env`; tests pass a fixture object. */
+    env?: NodeJS.ProcessEnv;
+    /** Test seam — see `AdbExec`. */
+    exec?: AdbExec;
+}
+/**
+ * Read-only view of the current `adb reverse` status for a given
+ * dev-server port. Returns `undefined` if `tryEnableAdbReverse` has
+ * never been called for that port.
+ */
+export declare function getAdbReverseStatus(port: number): AdbReverseStatus | undefined;
+/**
+ * Test hook — clears the per-port cache so unit tests can exercise
+ * fresh "first call" behavior without leaking state between cases.
+ * NOT exported from the package barrel; spec files import via the
+ * file path directly.
+ */
+export declare function __resetAdbReverseCacheForTests(): void;
+/**
+ * Try to set up `adb reverse tcp:<port> tcp:<port>` for every
+ * connected Android device / emulator so device-side `localhost:port`
+ * routes through the ADB transport to the host's dev server.
+ *
+ * Why this beats `10.0.2.2`. The Android emulator's stock NAT is
+ * QEMU's `slirp` user-mode network stack, which is well-known to
+ * drop bursts of concurrent TCP setups to the host. In practice this
+ * surfaces as ~80% of synchronous module-loader fetches failing with
+ * `IOException: unexpected end of stream` — the connection establishes,
+ * the request goes out, and then slirp drops the response before
+ * okhttp can read the status line. The failures are random per-module
+ * across runs, retries help but don't eliminate them, and the symptom
+ * masquerades as a server-side bug.
+ *
+ * `adb reverse` bypasses the emulator NIC entirely — the device-side
+ * connection is multiplexed over the existing ADB USB / TCP channel
+ * to the host. It's the same mechanism React Native, Expo, and
+ * Flutter use for Android dev, and it works for both emulators and
+ * USB-connected physical devices.
+ *
+ * Caching. The result is cached per-port so repeat callers don't
+ * fork extra subprocesses. The cache is keyed on port (not platform)
+ * because the wildcard "Android-ness" of the call is already implied
+ * by the caller — only Android consumers hit this path.
+ *
+ * Failure modes (all surface as a cached `succeeded: false`):
+ *   - `NS_HMR_NO_ADB_REVERSE=1` — explicit opt-out for unusual
+ *     setups (e.g. Wi-Fi-connected device with no ADB tunnel, CI
+ *     containers without ADB installed).
+ *   - `adb` not on PATH — common in fresh dev machines that have
+ *     the Android SDK installed but no shell init.
+ *   - No connected devices — user started Vite before booting the
+ *     emulator. We do NOT keep retrying after the first failure
+ *     because the URL is baked into bundle.mjs at config-load time
+ *     and there's no point in flipping it later.
+ *   - "more than one device" — fatal for unqualified `adb reverse`,
+ *     so we enumerate via `adb devices` and apply the reverse
+ *     individually with `-s <serial>`. As long as at least one
+ *     device gets the mapping we treat the whole call as a success.
+ */
+export declare function tryEnableAdbReverse(opts: TryEnableAdbReverseOptions): AdbReverseStatus;
+/**
+ * Pick the host string a device or simulator can actually reach.
+ *
+ * See the file-level comment for the full resolution-precedence
+ * narrative. Returns the chosen host alongside a `source` tag so
+ * callers (and logs) can explain why a given URL was emitted.
+ */
+export declare function resolveDeviceReachableHost(opts: ResolveDeviceHostOptions): DeviceHostResolution;
+export interface ResolveDeviceOriginOptions extends ResolveDeviceHostOptions {
+    /** Wire protocol; usually 'http' unless `server.https` is set. */
+    protocol?: 'http' | 'https';
+    /** Server port; defaults to 5173 to match the Vite dev default. */
+    port?: number;
+}
+export interface DeviceOriginResolution extends DeviceHostResolution {
+    /** Fully assembled `protocol://host:port` string. */
+    origin: string;
+    protocol: 'http' | 'https';
+    port: number;
+}
+/**
+ * Convenience wrapper that returns the full `protocol://host:port`
+ * origin string alongside the host-resolution metadata. The vast
+ * majority of callers want the assembled origin to splice into a
+ * `/ns/...` URL, so this saves them the trivial template string.
+ *
+ * When the resolved host already includes a `:port` suffix (a common
+ * shape for `NS_HMR_HOST=tunnel.example.com:5173`), we split it back
+ * out so the assembled origin never doubles up the port.
+ */
+export declare function resolveDeviceReachableOrigin(opts: ResolveDeviceOriginOptions): DeviceOriginResolution;
+export {};