@nocville/npc 0.2.1 → 0.2.3

package/dist/npcs/github-watcher/index.js

@@ -1,7 +1,9 @@
 import { PollingNPC } from '../../core/polling-npc.js';
 import { truncate } from '../../core/text.js';
+import { moodForStatus } from '../../core/thresholds.js';
+import { NpcConfigError } from '../../core/errors.js';
 import { DEFAULTS } from './defaults.js';
-import { fetchCommits, fetchDefaultBranch, newCommitsSince, commitsWithin } from './github-api.js';
+import { fetchCommits, fetchDefaultBranch, newCommitsSince, commitsWithin, isValidRepo, } from './github-api.js';
 import { relativeTime } from './format.js';
 export class GitHubWatcherNPC extends PollingNPC {
     repo;
@@ -12,12 +14,24 @@ export class GitHubWatcherNPC extends PollingNPC {
     lastSeenSha = null;
     commits = [];
     rateRemaining = null;
+    /** While rate-limited, don't call GitHub again before this time (epoch ms). */
+    rateLimitedUntil = 0;
+    consecutiveFailures = 0;
     newCommitPollsLeft = 0;
     constructor(config) {
-        super({ ...config, pollInterval: config.pollInterval ?? DEFAULTS.pollInterval });
+        super({
+            ...config,
+            // Unauthenticated requests get 60/hour and 304s still count against
+            // them, so a 60s poll (plus the branch lookup) would hit the limit.
+            pollInterval: config.pollInterval ??
+                (config.token ? DEFAULTS.pollInterval : DEFAULTS.unauthenticatedPollInterval),
+        });
+        if (!isValidRepo(config.repo)) {
+            throw new NpcConfigError(`--repo must look like owner/name (got "${truncate(config.repo, 80)}")`);
+        }
         this.repo = config.repo;
-        this.token = config.token;
-        this.branch = config.branch;
+        this.token = config.token || undefined;
+        this.branch = config.branch?.trim() || undefined;
         this.fetchFn = config.fetchFn;
     }
     get name() {
@@ -39,7 +53,8 @@ export class GitHubWatcherNPC extends PollingNPC {
         };
     }
     async onStart() {
-        // Resolve the default branch once if the user didn't pin one.
+        // Resolve the default branch once if the user didn't pin one (it only
+        // labels the board; the commits API already defaults to that branch).
         if (!this.branch) {
             const def = await fetchDefaultBranch(this.repo, {
                 token: this.token,
@@ -54,6 +69,8 @@ export class GitHubWatcherNPC extends PollingNPC {
         await super.onStart();
     }
     async collect() {
+        if (Date.now() < this.rateLimitedUntil)
+            return this.rateLimited();
         const result = await fetchCommits(this.repo, {
             token: this.token,
             etag: this.etag,
@@ -64,39 +81,68 @@ export class GitHubWatcherNPC extends PollingNPC {
         });
         if (result.rateRemaining !== null)
             this.rateRemaining = result.rateRemaining;
-        if (result.status === 403) {
-            return this.report('warning', 'concerned', 'GitHub API rate-limited (403)', 'rate-limited');
+        const failure = this.classifyFailure(result);
+        if (failure)
+            return failure;
+        this.consecutiveFailures = 0;
+        if (result.notModified)
+            return this.reportIdle();
+        if (result.status === 409)
+            return this.report('healthy', 'Repository is empty');
+        this.etag = result.etag ?? this.etag;
+        if (result.commits.length === 0)
+            return this.reportIdle();
+        const fresh = newCommitsSince(result.commits, this.lastSeenSha);
+        this.commits = result.commits;
+        const seeded = this.lastSeenSha !== null;
+        this.lastSeenSha = result.commits[0].sha;
+        if (!seeded || fresh.length === 0)
+            return this.reportIdle();
+        this.newCommitPollsLeft = DEFAULTS.newCommitPolls;
+        return this.reportNewCommits(fresh);
+    }
+    /** Map an error response to a report, or null when the fetch succeeded. */
+    classifyFailure(result) {
+        const { status } = result;
+        if (status === 304 || status === 409 || (status >= 200 && status < 300))
+            return null;
+        if (status === 429 || (status === 403 && result.rateRemaining === 0)) {
+            this.rateLimitedUntil = result.rateResetAt ?? Date.now() + 15 * 60_000;
+            if (!this.token) {
+                this.logger.warn('GitHub rate limit reached; set GITHUB_TOKEN for a higher limit');
+            }
+            return this.rateLimited();
         }
-        if (result.status === 404) {
-            return this.report('warning', 'concerned', `Repo not found: ${this.repo}`, 'not-found');
+        if (status === 401) {
+            return this.report('warning', 'GitHub token rejected (401)', 'auth-failed');
         }
-        if (result.status === 0 && this.commits.length === 0) {
-            return this.report('warning', 'concerned', 'GitHub API unreachable', 'unreachable');
+        if (status === 403) {
+            return this.report('warning', `Access to ${this.repo} denied (403)`, 'forbidden');
         }
-        if (result.notModified) {
-            return this.reportIdle();
+        if (status === 404) {
+            const hint = this.token ? '' : ' (private repos need GITHUB_TOKEN)';
+            return this.report('warning', `Repo not found: ${this.repo}${hint}`, 'not-found');
         }
-        if (result.commits.length > 0) {
-            const fresh = newCommitsSince(result.commits, this.lastSeenSha);
-            this.commits = result.commits;
-            this.etag = result.etag ?? this.etag;
-            if (this.lastSeenSha === null) {
-                this.lastSeenSha = result.commits[0].sha;
-                return this.reportIdle();
-            }
-            if (fresh.length > 0) {
-                this.lastSeenSha = result.commits[0].sha;
-                this.newCommitPollsLeft = DEFAULTS.newCommitPolls;
-                return this.reportNewCommits(fresh);
-            }
+        // Network error, timeout or 5xx: ride out blips while there's a board to show.
+        this.consecutiveFailures++;
+        if (this.commits.length > 0 && this.consecutiveFailures < DEFAULTS.failuresBeforeWarning) {
+            return this.reportIdle();
         }
-        return this.reportIdle();
+        const what = status === 0 ? 'unreachable' : `error (HTTP ${status})`;
+        return this.report('warning', `GitHub API ${what}`, 'unreachable');
+    }
+    rateLimited() {
+        const resumes = new Date(this.rateLimitedUntil).toLocaleTimeString([], {
+            hour: '2-digit',
+            minute: '2-digit',
+        });
+        return this.report('warning', `GitHub API rate-limited until ${resumes}`, 'rate-limited');
     }
     reportNewCommits(fresh) {
         const newest = fresh[0];
         const latest = `${newest.author}: ${truncate(newest.message, 120)} (${newest.sha.slice(0, 7)})`;
         const message = fresh.length > 1 ? `${fresh.length} new commits — latest: ${latest}` : latest;
-        return this.report('healthy', 'happy', message, 'new-commit');
+        return this.report('healthy', message, 'new-commit');
     }
     reportIdle() {
         if (this.newCommitPollsLeft > 0)
@@ -106,16 +152,16 @@ export class GitHubWatcherNPC extends PollingNPC {
         const message = newest
             ? `Last: ${truncate(newest.message, 80)} (${relativeTime(newest.date)})`
             : `Watching ${this.repo}`;
-        return this.report('healthy', 'happy', message, subStatus);
+        return this.report('healthy', message, subStatus);
     }
-    report(status, mood, message, subStatus) {
-        const newest = this.commits[0];
-        const secondsSinceLast = newest && newest.date
-            ? Math.max(0, Math.round((Date.now() - Date.parse(newest.date)) / 1000))
+    report(status, message, subStatus) {
+        const newestAt = Date.parse(this.commits[0]?.date ?? '');
+        const secondsSinceLast = Number.isFinite(newestAt)
+            ? Math.max(0, Math.round((Date.now() - newestAt) / 1000))
             : 0;
         return {
             status,
-            mood,
+            mood: moodForStatus(status),
             message,
             subStatus,
             screenData: this.buildBoard(),
@@ -129,9 +175,9 @@ export class GitHubWatcherNPC extends PollingNPC {
     buildBoard() {
         const now = Date.now();
         const header = this.branch ? `${this.repo}@${this.branch}` : this.repo;
-        const values = [{ label: 'repo', value: header }];
-        for (const c of this.commits.slice(0, 8)) {
-            const recent = c.date && now - Date.parse(c.date) < 3600_000;
+        const values = [{ label: 'repo', value: truncate(header, 60) }];
+        for (const c of this.commits.slice(0, DEFAULTS.boardRows)) {
+            const recent = now - Date.parse(c.date) < 3600_000;
             values.push({
                 label: c.sha.slice(0, 7),
                 value: truncate(`${c.author}: ${c.message}`, 60),

package/dist/npcs/internet-connectivity/checks.d.ts

@@ -1,24 +1,21 @@
 import type { LatencyHost } from './defaults.js';
-export interface DnsCheckResult {
-    host: string;
+/** One probe's outcome. `timeMs` is only meaningful when `ok`. */
+export interface CheckResult {
+    target: string;
     ok: boolean;
     timeMs: number;
     error?: string;
 }
-export declare function checkDns(hosts: string[]): Promise<DnsCheckResult[]>;
-export interface HttpCheckResult {
-    url: string;
-    ok: boolean;
-    timeMs: number;
-    statusCode?: number;
-    error?: string;
-}
-export declare function checkHttp(urls: string[], timeout: number): Promise<HttpCheckResult[]>;
-export interface LatencyCheckResult {
-    host: string;
-    ok: boolean;
-    timeMs: number;
-    error?: string;
-}
-export declare function checkLatency(hosts: LatencyHost[]): Promise<LatencyCheckResult[]>;
+/**
+ * Resolve each host's A records through a dedicated resolver with a bounded
+ * timeout (the default resolver retries for tens of seconds when DNS is down).
+ */
+export declare function checkDns(hosts: string[], timeoutMs: number): Promise<CheckResult[]>;
+/**
+ * Time to response headers for each URL. The body is discarded unread, so a
+ * large or endless response costs nothing. Only 2xx counts as reachable.
+ */
+export declare function checkHttp(urls: string[], timeoutMs: number): Promise<CheckResult[]>;
+/** Time to establish a TCP connection to each host:port. */
+export declare function checkLatency(hosts: LatencyHost[], timeoutMs: number): Promise<CheckResult[]>;
 //# sourceMappingURL=checks.d.ts.map

package/dist/npcs/internet-connectivity/checks.js

@@ -1,84 +1,87 @@
 import { promises as dns } from 'node:dns';
 import net from 'node:net';
-export async function checkDns(hosts) {
-    return Promise.all(hosts.map(resolveSingleDns));
+import { NPC_USER_AGENT, discardBody, displayUrl } from '../../core/http.js';
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
 }
-async function resolveSingleDns(host) {
-    const start = performance.now();
-    try {
-        await dns.resolve(host);
-        return { host, ok: true, timeMs: performance.now() - start };
-    }
-    catch (err) {
-        return {
-            host,
-            ok: false,
-            timeMs: performance.now() - start,
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-export async function checkHttp(urls, timeout) {
-    return Promise.all(urls.map((url) => fetchSingleUrl(url, timeout)));
-}
-async function fetchSingleUrl(url, timeout) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-    const start = performance.now();
+// ---------- DNS ----------
+/**
+ * Resolve each host's A records through a dedicated resolver with a bounded
+ * timeout (the default resolver retries for tens of seconds when DNS is down).
+ */
+export async function checkDns(hosts, timeoutMs) {
+    const resolver = new dns.Resolver({
+        timeout: Math.max(250, Math.floor(timeoutMs / 2)),
+        tries: 2,
+    });
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), timeoutMs);
+    });
     try {
-        const response = await fetch(url, { signal: controller.signal });
-        // Consume body to ensure connection is completed
-        await response.text();
-        return {
-            url,
-            ok: response.ok,
-            timeMs: performance.now() - start,
-            statusCode: response.status,
-        };
-    }
-    catch (err) {
-        return {
-            url,
-            ok: false,
-            timeMs: performance.now() - start,
-            error: err instanceof Error ? err.message : String(err),
-        };
+        return await Promise.all(hosts.map(async (host) => {
+            const start = performance.now();
+            try {
+                const outcome = await Promise.race([resolver.resolve4(host), deadline]);
+                if (outcome === 'timeout')
+                    return { target: host, ok: false, timeMs: 0, error: 'timeout' };
+                return { target: host, ok: true, timeMs: performance.now() - start };
+            }
+            catch (err) {
+                return { target: host, ok: false, timeMs: 0, error: errorText(err) };
+            }
+        }));
     }
     finally {
         clearTimeout(timer);
+        resolver.cancel();
     }
 }
-export async function checkLatency(hosts) {
-    return Promise.all(hosts.map(measureTcpConnect));
+// ---------- HTTP ----------
+/**
+ * Time to response headers for each URL. The body is discarded unread, so a
+ * large or endless response costs nothing. Only 2xx counts as reachable.
+ */
+export async function checkHttp(urls, timeoutMs) {
+    return Promise.all(urls.map(async (url) => {
+        const target = displayUrl(url); // never echo credentials or query tokens
+        const start = performance.now();
+        try {
+            const res = await fetch(url, {
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { 'User-Agent': NPC_USER_AGENT },
+            });
+            const timeMs = performance.now() - start;
+            await discardBody(res);
+            return res.ok
+                ? { target, ok: true, timeMs }
+                : { target, ok: false, timeMs: 0, error: `HTTP ${res.status}` };
+        }
+        catch (err) {
+            return { target, ok: false, timeMs: 0, error: errorText(err) };
+        }
+    }));
+}
+// ---------- Latency (TCP connect) ----------
+/** Time to establish a TCP connection to each host:port. */
+export async function checkLatency(hosts, timeoutMs) {
+    return Promise.all(hosts.map((h) => measureTcpConnect(h, timeoutMs)));
 }
-function measureTcpConnect(target) {
+function measureTcpConnect(target, timeoutMs) {
+    const label = target.host.includes(':')
+        ? `[${target.host}]:${target.port}`
+        : `${target.host}:${target.port}`;
     return new Promise((resolve) => {
         const start = performance.now();
         const socket = net.connect({ host: target.host, port: target.port });
-        const timeout = setTimeout(() => {
+        const finish = (result) => {
+            clearTimeout(timer);
             socket.destroy();
-            resolve({
-                host: target.host,
-                ok: false,
-                timeMs: performance.now() - start,
-                error: 'Connection timed out',
-            });
-        }, 5000);
-        socket.on('connect', () => {
-            clearTimeout(timeout);
-            const timeMs = performance.now() - start;
-            socket.destroy();
-            resolve({ host: target.host, ok: true, timeMs });
-        });
-        socket.on('error', (err) => {
-            clearTimeout(timeout);
-            resolve({
-                host: target.host,
-                ok: false,
-                timeMs: performance.now() - start,
-                error: err.message,
-            });
-        });
+            resolve(result);
+        };
+        const timer = setTimeout(() => finish({ target: label, ok: false, timeMs: 0, error: 'Connection timed out' }), timeoutMs);
+        socket.once('connect', () => finish({ target: label, ok: true, timeMs: performance.now() - start }));
+        socket.once('error', (err) => finish({ target: label, ok: false, timeMs: 0, error: err.message }));
     });
 }
 //# sourceMappingURL=checks.js.map

package/dist/npcs/internet-connectivity/defaults.d.ts

@@ -8,7 +8,10 @@ export interface InternetConnectivityDefaults {
     dnsHosts: string[];
     httpUrls: string[];
     latencyHosts: LatencyHost[];
+    /** Port for a `--latency-hosts` entry given without one. */
+    latencyPort: number;
     slowThreshold: number;
+    /** Per-check timeout (DNS, HTTP and TCP) in ms. */
     httpTimeout: number;
     thresholds: {
         dnsTime: ThresholdConfig;

package/dist/npcs/internet-connectivity/defaults.js

@@ -4,10 +4,13 @@ export const DEFAULTS = {
     // gstatic generate_204 is a stable, low-latency 204 endpoint used by many
     // OSes for connectivity checks (replaces the flaky httpbin.org default).
     httpUrls: ['https://1.1.1.1/cdn-cgi/trace', 'https://www.gstatic.com/generate_204'],
+    // 443, not 80: Google's 8.8.8.8 doesn't listen on port 80, so that default
+    // timed out on every poll and pinned the NPC at warning.
     latencyHosts: [
-        { host: '8.8.8.8', port: 80 },
-        { host: '1.1.1.1', port: 80 },
+        { host: '8.8.8.8', port: 443 },
+        { host: '1.1.1.1', port: 443 },
     ],
+    latencyPort: 80,
     slowThreshold: 1000, // ms
     httpTimeout: 5000, // ms
     thresholds: {

package/dist/npcs/internet-connectivity/index.d.ts

@@ -10,17 +10,20 @@ export interface ConnectivityThresholds {
 export interface InternetConnectivityConfig extends PollingNpcConfig {
     dnsHosts?: string[];
     httpUrls?: string[];
+    /** `{host, port}` pairs, or "host" / "host:port" / "[v6]:port" strings. */
     latencyHosts?: LatencyHost[] | string[];
     slowThreshold?: number;
+    /** Per-check timeout in ms (DNS, HTTP and TCP). */
     httpTimeout?: number;
     thresholds?: ConnectivityThresholds;
 }
 interface ConnectivitySample {
     allFailed: boolean;
     anyFailed: boolean;
-    dnsAvg: number;
-    httpAvg: number;
-    latencyAvg: number;
+    /** Mean time of the successful checks of each kind; null when none succeeded. */
+    dnsAvg: number | null;
+    httpAvg: number | null;
+    latencyAvg: number | null;
 }
 /**
  * Derive overall status from live per-check thresholds. All checks failing is
@@ -28,6 +31,11 @@ interface ConnectivitySample {
  * escalate per their own thresholds.
  */
 export declare function evaluateConnectivityStatus(sample: ConnectivitySample, thresholds: ConnectivityThresholds): Status;
+/**
+ * Parse a latency target: "host", "host:port", "[ipv6]:port" or a bare IPv6
+ * address. Throws NpcConfigError on an out-of-range port.
+ */
+export declare function parseLatencyHost(input: string, defaultPort?: number): LatencyHost;
 export declare class InternetConnectivityNPC extends PollingNPC {
     private dnsHosts;
     private httpUrls;
@@ -44,10 +52,15 @@ export declare class InternetConnectivityNPC extends PollingNPC {
     get behavior(): BehaviorHints;
     get companion(): CompanionDecl;
     protected collect(): Promise<CollectedMetrics>;
-    private buildOnlineMessage;
-    private buildOfflineMessage;
     /**
-     * Build config from CLI flags. Merges with any programmatic overrides.
+     * One dashboard panel. A category whose checks all failed shows FAIL in red
+     * (and a 0 sparkline sample) rather than a misleading latency; a partial
+     * failure is amber.
+     */
+    private panel;
+    /**
+     * Build config from CLI flags. List flags are comma-separated; latency
+     * hosts accept "host", "host:port" or "[ipv6]:port".
      */
     static configFromFlags(flags: Record<string, string | boolean>): Partial<InternetConnectivityConfig>;
 }