waterplane 0.0.1 → 0.1.11

package/packages/host/dist/speedtest.js

@@ -0,0 +1,137 @@
+import { randomFillSync } from "node:crypto";
+import { lanIps, tailscaleBin, tailscaleIp } from "./net.js";
+import { execFileP } from "./proc.js";
+/** Ceiling on a single run so a stray/hostile request can't stream forever. */
+const MAX_TEST_BYTES = 256 * 1024 * 1024; // 256 MB
+const DEFAULT_BYTES = 8 * 1024 * 1024; //  8 MB
+/**
+ * A pre-filled random block reused for every download. Random (not zeros) so no
+ * transparent compressor anywhere on the path can inflate the apparent rate.
+ */
+const CHUNK = Buffer.allocUnsafe(256 * 1024);
+randomFillSync(CHUNK);
+/** Stream `bytes` of incompressible data to the phone, honouring backpressure. */
+export function serveDownload(res, bytes) {
+    const total = Math.max(0, Math.min(Math.floor(bytes) || DEFAULT_BYTES, MAX_TEST_BYTES));
+    res.writeHead(200, {
+        "content-type": "application/octet-stream",
+        "content-length": String(total),
+        "cache-control": "no-store, no-cache, must-revalidate",
+    });
+    let sent = 0;
+    const pump = () => {
+        while (sent < total) {
+            const n = Math.min(CHUNK.length, total - sent);
+            const slice = n === CHUNK.length ? CHUNK : CHUNK.subarray(0, n);
+            sent += n;
+            if (!res.write(slice)) {
+                res.once("drain", pump);
+                return;
+            } // paused: resume on drain
+        }
+        res.end();
+    };
+    pump();
+}
+/**
+ * Drain the upload body, counting bytes and measuring the server-side wall time
+ * from first to last byte (a cleaner throughput number than the client's, which
+ * includes connection setup + the response round-trip). Capped at MAX_TEST_BYTES.
+ */
+export function drainUpload(req) {
+    return new Promise((resolve, reject) => {
+        let bytes = 0;
+        let start = 0;
+        req.on("data", (c) => {
+            if (!start)
+                start = Date.now();
+            bytes += c.length;
+            if (bytes > MAX_TEST_BYTES) {
+                req.destroy();
+                reject(new Error("payload too large"));
+            }
+        });
+        req.on("end", () => resolve({ bytes, ms: start ? Date.now() - start : 0 }));
+        req.on("error", reject);
+    });
+}
+function normIp(ip) {
+    return ip.replace(/^::ffff:/, "");
+}
+function classify(ip) {
+    if (ip === "127.0.0.1" || ip === "::1" || ip.startsWith("127."))
+        return "loopback";
+    const p = ip.split(".").map(Number);
+    if (p.length === 4 && p[0] === 100 && p[1] >= 64 && p[1] <= 127)
+        return "tailscale";
+    if (p.length === 4 && (p[0] === 10 || (p[0] === 192 && p[1] === 168) || (p[0] === 172 && p[1] >= 16 && p[1] <= 31)))
+        return "lan";
+    if (p.length === 4)
+        return "public";
+    return "unknown";
+}
+const IPV4 = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+/** Run a tailscale subcommand via the resolved CLI path — argv, never a shell. */
+async function ts(bin, args, timeout) {
+    const { stdout } = await execFileP(bin, args, { timeout, maxBuffer: 1 << 20 });
+    return stdout;
+}
+export async function collectDebug(req) {
+    const clientIp = normIp(req.socket.remoteAddress || "");
+    const clientKind = classify(clientIp);
+    const dialedHost = (req.headers.host || "").split(":")[0] || "";
+    const overTailscale = clientKind === "tailscale";
+    const bin = await tailscaleBin();
+    const [tsIp, raw] = await Promise.all([
+        tailscaleIp().catch(() => null),
+        (async () => {
+            const out = {};
+            if (!bin)
+                return out;
+            // Ping the exact client peer to read THIS connection's current path.
+            // --until-direct=false so it reports the live route instead of blocking
+            // while it tries to upgrade to direct.
+            if (overTailscale && IPV4.test(clientIp)) {
+                out.ping = await ts(bin, ["ping", "--c", "3", "--until-direct=false", clientIp], 8000).catch((e) => `ping failed: ${e.message ?? e}`);
+            }
+            out.netcheck = await ts(bin, ["netcheck"], 12000).catch((e) => `netcheck failed: ${e.message ?? e}`);
+            out.status = await ts(bin, ["status"], 8000).catch((e) => `status failed: ${e.message ?? e}`);
+            return out;
+        })(),
+    ]);
+    // Parse the ping output for the live route. Lines look like:
+    //   "pong from host (100.x.y.z) via DERP(fra) in 31ms"  → relayed
+    //   "pong from host (100.x.y.z) via 192.168.1.5:41641 in 2ms" → direct
+    let route = "unknown";
+    let derpRegion = null;
+    if (raw.ping) {
+        const derp = /via DERP\(([^)]+)\)/i.exec(raw.ping);
+        if (derp) {
+            route = "derp";
+            derpRegion = derp[1];
+        }
+        else if (/via \d{1,3}(?:\.\d{1,3}){3}:\d+/i.test(raw.ping))
+            route = "direct";
+    }
+    const lan = lanIps();
+    const hint = lan.length ? `http://${lan[0]}:8770` : "the host's LAN IP";
+    let verdict;
+    if (clientKind === "loopback")
+        verdict = "Loopback — same machine. Not a network path.";
+    else if (clientKind === "lan")
+        verdict = `Direct LAN connection (${clientIp}) — not using the Tailscale tunnel. This is already the fast path.`;
+    else if (clientKind === "tailscale" && route === "derp")
+        verdict = `Relayed via DERP(${derpRegion}) — bytes detour through a Tailscale relay, THE usual cause of slow transfers. On the same WiFi, hit ${hint} to bypass the tunnel.`;
+    else if (clientKind === "tailscale" && route === "direct")
+        verdict = "Direct Tailscale (P2P) — the tunnel found a direct path, so this is about as fast as it gets over Tailscale.";
+    else if (clientKind === "tailscale")
+        verdict = `Over the Tailscale tunnel; route unknown (no ping result). If slow, try ${hint} on the same WiFi to compare.`;
+    else
+        verdict = `Connected from ${clientIp} (${clientKind}).`;
+    return {
+        clientIp, clientKind, dialedHost, overTailscale,
+        lanIps: lan, tailscaleIp: tsIp, tailscaleCli: !!bin,
+        route, derpRegion, raw, verdict,
+    };
+}
+//# sourceMappingURL=speedtest.js.map

package/packages/host/dist/speedtest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speedtest.js","sourceRoot":"","sources":["../src/speedtest.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/spendwall.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What to do about a SPEND wall (`limit.ts`'s `spend`): an API-key / cloud
+ * account whose credits ran out or whose workspace / organisation / gateway
+ * spend limit was reached.
+ *
+ * A plan window has a reset the CLI prints and a ladder of probes that is worth
+ * walking. A balance has neither: typing "continue" into it earlier changes
+ * nothing, and the only instants worth believing are (1) one the message itself
+ * printed in full and (2) the reset of a dollar CALENDAR period the person
+ * configured (`shared/period.ts`'s `periodBounds`, the one reading of an edge).
+ * With neither, there is no time to wait for and none is invented - the session
+ * is held and `noteGaveUp` tells the person it needs them.
+ *
+ * The period's reset is a guess about WHICH limit was hit (a monthly cap, a
+ * daily one), so there is exactly one attempt at it; if that is refused too the
+ * answer is the same sentence to the person, not a second guess.
+ */
+import { type BudgetPeriod } from "@waterplane/shared";
+type Source = () => readonly BudgetPeriod[];
+/** Wired once at boot with the budget's dollar periods (`main.ts`). */
+export declare function setSpendPeriodSource(fn: Source): void;
+/** The earliest upcoming reset among ACTIVE dollar calendar periods, or null. */
+export declare function spendRetry(now: number): {
+    resetAt: number | null;
+};
+export declare function spendRetry(now: number, resetAt: number | null, attempts: number, bufferMs: number): {
+    kind: "at";
+    at: number;
+} | {
+    kind: "giveup";
+    why: string;
+};
+export {};

package/packages/host/dist/spendwall.js

@@ -0,0 +1,45 @@
+/**
+ * What to do about a SPEND wall (`limit.ts`'s `spend`): an API-key / cloud
+ * account whose credits ran out or whose workspace / organisation / gateway
+ * spend limit was reached.
+ *
+ * A plan window has a reset the CLI prints and a ladder of probes that is worth
+ * walking. A balance has neither: typing "continue" into it earlier changes
+ * nothing, and the only instants worth believing are (1) one the message itself
+ * printed in full and (2) the reset of a dollar CALENDAR period the person
+ * configured (`shared/period.ts`'s `periodBounds`, the one reading of an edge).
+ * With neither, there is no time to wait for and none is invented - the session
+ * is held and `noteGaveUp` tells the person it needs them.
+ *
+ * The period's reset is a guess about WHICH limit was hit (a monthly cap, a
+ * daily one), so there is exactly one attempt at it; if that is refused too the
+ * answer is the same sentence to the person, not a second guess.
+ */
+import { periodBounds } from "@waterplane/shared";
+let source = () => [];
+/** Wired once at boot with the budget's dollar periods (`main.ts`). */
+export function setSpendPeriodSource(fn) { source = fn; }
+export function spendRetry(now, resetAt, attempts, bufferMs = 0) {
+    if (attempts === undefined) {
+        let best = null;
+        try {
+            for (const p of source()) {
+                if (p.kind !== "calendar" || p.unit !== "usd")
+                    continue;
+                const b = periodBounds(p, now);
+                if (b.active && b.resetAt != null && b.resetAt > now && (best == null || b.resetAt < best))
+                    best = b.resetAt;
+            }
+        }
+        catch {
+            best = null;
+        }
+        return { resetAt: best };
+    }
+    if (attempts > 0)
+        return { kind: "giveup", why: "spend limit still in force after the attempt at its reset - needs you" };
+    if (resetAt == null)
+        return { kind: "giveup", why: "spend limit with no known reset - needs you" };
+    return { kind: "at", at: Math.max(now, resetAt + bufferMs) };
+}
+//# sourceMappingURL=spendwall.js.map

package/packages/host/dist/spendwall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spendwall.js","sourceRoot":"","sources":["../src/spendwall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAGrE,IAAI,MAAM,GAAW,GAAG,EAAE,CAAC,EAAE,CAAC;AAE9B,uEAAuE;AACvE,MAAM,UAAU,oBAAoB,CAAC,EAAU,IAAU,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC;AAMvE,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,OAAuB,EAAE,QAAiB,EAAE,QAAQ,GAAG,CAAC;IAC9F,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,IAAI,GAAkB,IAAI,CAAC;QAC/B,IAAI,CAAC;YACH,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,EAAE,CAAC;gBACzB,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;oBAAE,SAAS;gBACxD,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBAC/B,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI,IAAI,CAAC,CAAC,OAAO,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;oBAAE,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC;YAC/G,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YAAC,IAAI,GAAG,IAAI,CAAC;QAAC,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,uEAAuE,EAAE,CAAC;IAC1H,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,6CAA6C,EAAE,CAAC;IACnG,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAC;AAC/D,CAAC"}

package/packages/host/dist/sysstat.d.ts

@@ -0,0 +1,134 @@
+import type { CpuBusy, DiskVolume, MemBreakdown, ProcSnapshot, SysStat, Thermal } from "@waterplane/shared";
+import type { PluginThermalReader } from "@waterplane/shared";
+/** How many rows each process list carries. Enough to answer "who has my
+ *  memory" — the tail of a 793-process table is noise, and every row is bytes
+ *  on a tunnel this app spends its life apologising for. */
+export declare const PROC_CAP = 8;
+export declare function sysStatSlowMs(): number;
+/** The process table names every program running on the desktop, which is more
+ *  than some people want on a phone screen. Off ⇒ the section says it was
+ *  switched off, never that nothing is running. */
+export declare const procListEnabled: () => boolean;
+/** One core's cumulative tick counts, as `os.cpus()` reports them. */
+export interface CoreTicks {
+    user: number;
+    nice: number;
+    sys: number;
+    idle: number;
+    irq: number;
+}
+/**
+ * The CPU split between two cumulative readings.
+ *
+ * Pure, and exported, because this is the one number on the screen that is
+ * easy to compute plausibly and wrongly: ticks are CUMULATIVE since boot, so
+ * subtracting the wrong pair, or folding `nice` and `irq` into neither bucket,
+ * produces a figure that looks reasonable and is not utilization.
+ *
+ * Returns null — never zeroes — when the pair cannot be a delta: a different
+ * core count (a VM resized, or the arrays simply disagree), no elapsed ticks at
+ * all (two reads inside one tick period), or a counter that went backwards.
+ */
+export declare function cpuBusyFrom(prev: readonly CoreTicks[], next: readonly CoreTicks[], spanMs: number): CpuBusy | null;
+/**
+ * Parse `vm_stat`'s text dump into the Activity Monitor split.
+ *
+ * Exported so the arithmetic is pinned with no Mac, `parseGpuIoreg`'s reason.
+ *
+ * The page size is read from the HEADER, never assumed: it is 4096 on Intel and
+ * 16384 on Apple Silicon, and hard-coding either turns every figure here into a
+ * number that is wrong by 4× on half the fleet.
+ *
+ * `usedBytes` follows Activity Monitor: app (anonymous minus purgeable) + wired
+ * + what the compressor OCCUPIES. Not what is STORED in the compressor — that
+ * is the bigger number, and counting it as used would be counting the
+ * compressor's win as a cost.
+ */
+export declare function parseVmStat(text: string, memTotal: number): MemBreakdown | null;
+/** Parse `sysctl -n vm.swapusage`: `total = 10240.00M  used = 8990.75M  free = …`.
+ *  The suffix is the unit and is read, never assumed — a machine with a 2 G
+ *  swap file prints `G`, and reading that as megabytes understates it 1024×. */
+export declare function parseSwapUsage(text: string): {
+    used: number;
+    total: number;
+} | null;
+/**
+ * Parse `/proc/meminfo`.
+ *
+ * Linux has no app/wired/compressed split worth inventing, so those fields stay
+ * ABSENT and the phone words the caption off `source`. What it does have is
+ * `MemAvailable`, which is the kernel's own estimate of what a new program
+ * could get — a better number than anything derivable here, and the reason this
+ * reader does not try to reconstruct macOS's vocabulary.
+ */
+export declare function parseMemInfo(text: string): MemBreakdown | null;
+/** The memory reader alone — for the local runner's ledger (`localusage.ts`),
+ *  which samples the machine only while a model is resident and has no use
+ *  for the process table or the thermals. Never throws; null = no reader. */
+export declare function sampleMemory(): Promise<MemBreakdown | null>;
+/**
+ * Parse `ps -Ao pid=,rss=,pcpu=,comm=` and FOLD BY PROGRAM.
+ *
+ * Grouping is the feature, not a tidy-up: the honest answer to "what is holding
+ * 30 GB" on a desktop is usually one browser wearing twelve renderer processes,
+ * and twelve identical rows say that badly while pushing everything else off a
+ * phone screen. `procs` carries the count; `pid` survives only where the fold
+ * is a single process, because a pid printed beside a fold of twelve names
+ * whichever one `ps` happened to print first.
+ *
+ * `comm` is a PATH on macOS and a short name on Linux, so the name is the
+ * basename either way. RSS is in KiB (`ps` reports KiB on both platforms) and
+ * **counts shared pages once per process** — `rssSumBytes` in the snapshot
+ * exists so the phone can say that rather than let somebody total the column.
+ */
+export declare function parsePsTable(text: string, cap?: number): Omit<ProcSnapshot, "at">;
+/**
+ * The sentence a macOS desktop gets instead of a temperature, when no plugin
+ * contributes a reader.
+ *
+ * Exported and pinned because it is the whole feature on this platform: an
+ * empty row with no explanation reads as a broken app, and this repo's rule
+ * that a reading degrades to absent only works when the absence is legible.
+ */
+export declare const MAC_THERMAL_NOTE: string;
+/** Parse the first finite number out of a sysfs file. */
+export declare function firstNumber(text: string): number | null;
+/** Register a contributed thermal reader. Throws a sentence on a bad or taken name. */
+export declare function registerThermalReader(name: string, reader: PluginThermalReader): () => void;
+/**
+ * What a contributed reading may put on screen. A figure the core cannot vouch
+ * for is DROPPED, never repaired; a reading with nothing left is null. Pure,
+ * exported for the test.
+ */
+export declare function cleanThermal(r: unknown, source: string): Omit<Thermal, "at"> | null;
+/** One `statfs` answer, before folding. `dev` is `stat().dev` of the path —
+ *  the one key that says two folders are on the same volume. */
+export interface DiskProbe {
+    path: string;
+    name: string;
+    /** What of this app's lives at `path`, in words; null for a bare mount. */
+    holds: string | null;
+    dev: number;
+    totalBytes: number;
+    availBytes: number;
+}
+export declare const DISK_CAP = 8;
+/**
+ * Probes folded into rows: ONE row per device, its `holds` merged in probe
+ * order, the volumes that hold something of ours first (in that order), then
+ * the rest biggest first. A volume holding none of ours under 1 GiB is dropped.
+ * A probe with no size (a pseudo filesystem) is dropped, never a 0-byte disk.
+ */
+export declare function foldDisks(probes: DiskProbe[], cap?: number): DiskVolume[];
+/** `/proc/mounts` → the mount points of real block devices. Octal escapes
+ *  (`\040` for a space) undone; snaps (squashfs loop mounts) left out. */
+export declare function parseProcMounts(text: string): string[];
+/**
+ * One sample of the machine.
+ *
+ * Every section is independent and every failure is an ABSENT field (or, where
+ * a person would otherwise be looking at an unexplained blank, a sentence).
+ * Nothing here throws: this is called from the poll that feeds a readout, and a
+ * thrown sensor read would take the model list down with it.
+ */
+export declare function sampleSysStat(): Promise<SysStat>;