@tapflowio/relay 0.20.1 → 0.21.0

package/dist/RelayServer.d.ts

@@ -91,6 +91,9 @@ export declare class RelayServer {
     private readonly agentGraceMs;
     private readonly corsAllowed;
     private warnedProxyMisconfig;
+    /** Agent identities already warned about a missing `build-download`. See `warnLegacyInstaller`. */
+    private readonly warnedLegacyInstaller;
+    private readonly buildTickets;
     private pendingScreenshots;
     private readonly uiTreeTimeoutMs;
     private pendingUITrees;
@@ -410,6 +413,20 @@ export declare class RelayServer {
      *  from silence and it waits out the deadline (#445). `Session not found` is app-specific for the
      *  same reason: a generic `error` cannot be correlated by construction. */
     private handleBrowserAppInstall;
+    /**
+     * Says once, per agent, that this agent cannot fetch builds over HTTP.
+     *
+     * **The wording is conditional on purpose.** Such an agent installs perfectly well when it shares
+     * the relay's filesystem, which is every `tapflow start`, so "installs will fail" would be false
+     * for most of the people who see it. What it cannot do is install from a relay that is somewhere
+     * else — and the relay cannot tell which case this is: the dashboard hands agents a **LAN**
+     * address even for the same machine (`pickLanAddress`), so the socket's own address answers a
+     * different question than the one that matters.
+     *
+     * Once per identity, because `agent:register` runs again on every reconnect — a Wi-Fi blip or a
+     * laptop waking up would otherwise repeat this indefinitely. Same shape as `warnedProxyMisconfig`.
+     */
+    private warnLegacyInstaller;
     /** Relay looks up bundle_id from DB. Same correlation rules as `handleBrowserAppInstall`. */
     private handleBrowserAppLaunch;
     private handleGetScreenshot;
@@ -420,6 +437,20 @@ export declare class RelayServer {
     private handleScreenshotError;
     private flushResourceBuffers;
     private handleRequest;
+    /**
+     * Serves one build to the agent that was just told to install it.
+     *
+     * **The ticket is the whole credential, and it travels in a header.** No PAT is asked for —
+     * requiring one would break `tapflow start`, whose agent connects on loopback with no token at
+     * all. In a URL the ticket would reach the request log the first time this handler threw
+     * (`router.ts` logs `${method} ${url}`, and its redaction only knows PAT and JWT shapes) and every
+     * reverse proxy's access log besides.
+     *
+     * The three failures are answered separately because a user does something different about each:
+     * a ticket nobody minted, a ticket that sat too long, and a file that went away between the mint
+     * and the fetch. Collapsing them is the defect this change exists to stop repeating.
+     */
+    private handleBuildDownload;
     private serveUpload;
     private serveStatic;
 }

package/dist/RelayServer.d.ts.map

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

package/dist/RelayServer.js

@@ -11,6 +11,7 @@ import { Router, json } from './router.js';
 import { requireViewAuth, requireAuth, getAuth, verifyPat } from './middleware/auth.js';
 import { classifyConnection } from './lib/connectionAuth.js';
 import { resolveClientAddress } from './lib/clientAddress.js';
+import { BuildTicketStore } from './lib/buildTickets.js';
 import { resolveCorsHeaders } from './lib/cors.js';
 import { isCsrfBlocked } from './lib/csrf.js';
 import { pickLanAddress } from './lib/lanAddress.js';
@@ -229,6 +230,9 @@ export class RelayServer {
     corsAllowed;
     // One-shot warning when XFF arrives on a loopback socket but TAPFLOW_TRUSTED_PROXIES is unset.
     warnedProxyMisconfig = false;
+    /** Agent identities already warned about a missing `build-download`. See `warnLegacyInstaller`. */
+    warnedLegacyInstaller = new Set();
+    buildTickets = new BuildTicketStore();
     pendingScreenshots = new Map();
     uiTreeTimeoutMs;
     pendingUITrees = new Map();
@@ -301,6 +305,12 @@ export class RelayServer {
         this.router.post('/api/v1/builds/:id/schedule-deletion', handleScheduleBuildDeletion);
         this.router.delete('/api/v1/builds/:id/schedule-deletion', handleCancelBuildDeletion);
         this.router.post('/api/v1/builds', (req, res) => handleUploadBuild(req, res, u));
+        // **Deliberately not under `/api/v1/builds/`.** `:id` compiles to `([^/]+)` and the router
+        // returns on the first registered match, so `/api/v1/builds/download` is captured by
+        // `/api/v1/builds/:id` as `id="download"` — `requireBuildAuth` then answers 401 to a ticketed
+        // agent carrying no PAT. Registration order could avoid it, which is exactly the objection:
+        // that makes the order load-bearing with nothing to say so.
+        this.router.get('/api/v1/build-download', (req, res) => this.handleBuildDownload(req, res));
         // webhooks (outbound build-status notifications)
         this.router.get('/api/v1/webhooks', handleListWebhooks);
         this.router.post('/api/v1/webhooks', handleCreateWebhook);
@@ -1418,6 +1428,7 @@ export class RelayServer {
         // its socket before creating the new ones. Identity is agentId (unique per Mac) when present,
         // else agentName. (Heartbeat backstop for never-reconnecting agents: #313.)
         const identity = msg.agentId ?? msg.agentName;
+        this.warnLegacyInstaller(identity, msg.capabilities ?? []);
         // Deduplicate first. Everything below is keyed by device id, so a payload naming one device
         // twice would collapse to a single entry in `registeredSessions` while `create()` had already
         // made two sessions — leaving one the agent is never told about. That is the same orphan the
@@ -1956,13 +1967,56 @@ export class RelayServer {
         // agent's reply is forwarded back generically without the relay looking at it. So if the id does not
         // reach the agent, nothing downstream can attribute the reply. Nothing type-checks that the value is
         // the *request's*: a brand cannot express provenance, so a test carries it.
+        // **`statSync`, and this handler stays synchronous.** Its caller does not await it
+        // (`case 'app:install'` above), and the message loop's `catch` is synchronous — so making this
+        // `async` would turn the `getDb()` throw named in the comment at the top of this function
+        // (SQLITE_BUSY, a closed db, I/O) from "logged, one request hangs" into an unhandled rejection,
+        // and the CLI exits the process on those. The relay would die with every session on it.
+        //
+        // A missing file is answered rather than thrown for the same reason the lookup above is: the
+        // build row outlives its file whenever a bind mount goes away or a purge half-ran, and an
+        // unanswered install is a spinner that never stops and a caller that times out with no cause.
+        let bytes;
+        try {
+            bytes = fs.statSync(build.file_path).size;
+        }
+        catch {
+            return fail('The relay cannot read this build file. It may have been deleted — re-upload the build.');
+        }
         this.sendTo(session.agentSocket, {
             type: 'app:install',
             sessionId,
             requestId,
-            payload: { filePath: build.file_path, bundleId: build.bundle_id },
+            payload: {
+                // Still sent, and sent first: an agent that predates `build-download` reads only this.
+                filePath: build.file_path,
+                bundleId: build.bundle_id,
+                buildTicket: this.buildTickets.mint(msg.buildId, build.file_path),
+                buildName: path.basename(build.file_path),
+                buildBytes: bytes,
+            },
         });
     }
+    /**
+     * Says once, per agent, that this agent cannot fetch builds over HTTP.
+     *
+     * **The wording is conditional on purpose.** Such an agent installs perfectly well when it shares
+     * the relay's filesystem, which is every `tapflow start`, so "installs will fail" would be false
+     * for most of the people who see it. What it cannot do is install from a relay that is somewhere
+     * else — and the relay cannot tell which case this is: the dashboard hands agents a **LAN**
+     * address even for the same machine (`pickLanAddress`), so the socket's own address answers a
+     * different question than the one that matters.
+     *
+     * Once per identity, because `agent:register` runs again on every reconnect — a Wi-Fi blip or a
+     * laptop waking up would otherwise repeat this indefinitely. Same shape as `warnedProxyMisconfig`.
+     */
+    warnLegacyInstaller(identity, capabilities) {
+        if (capabilities.includes('build-download') || this.warnedLegacyInstaller.has(identity))
+            return;
+        this.warnedLegacyInstaller.add(identity);
+        logger.warn(`[relay] agent ${identity} predates build downloading. If it is not on the same machine as ` +
+            'this relay, installing a build will fail — update the agent to match the relay.');
+    }
     /** Relay looks up bundle_id from DB. Same correlation rules as `handleBrowserAppInstall`. */
     handleBrowserAppLaunch(ws, msg) {
         const sessionId = msg.sessionId;
@@ -2180,6 +2234,52 @@ export class RelayServer {
         // SPA static fallback
         this.serveStatic(req, res);
     }
+    /**
+     * Serves one build to the agent that was just told to install it.
+     *
+     * **The ticket is the whole credential, and it travels in a header.** No PAT is asked for —
+     * requiring one would break `tapflow start`, whose agent connects on loopback with no token at
+     * all. In a URL the ticket would reach the request log the first time this handler threw
+     * (`router.ts` logs `${method} ${url}`, and its redaction only knows PAT and JWT shapes) and every
+     * reverse proxy's access log besides.
+     *
+     * The three failures are answered separately because a user does something different about each:
+     * a ticket nobody minted, a ticket that sat too long, and a file that went away between the mint
+     * and the fetch. Collapsing them is the defect this change exists to stop repeating.
+     */
+    handleBuildDownload(req, res) {
+        const ticket = req.headers['x-tapflow-build-ticket'];
+        if (typeof ticket !== 'string' || ticket === '') {
+            return json(res, 401, { error: 'Missing X-Tapflow-Build-Ticket' });
+        }
+        const found = this.buildTickets.redeem(ticket);
+        if (found === 'unknown') {
+            return json(res, 404, { error: 'This build ticket is not valid. It may already have been used.' });
+        }
+        if (found === 'expired') {
+            return json(res, 410, { error: 'This build ticket expired before it was used.' });
+        }
+        let size;
+        try {
+            size = fs.statSync(found.filePath).size;
+        }
+        catch {
+            return json(res, 404, { error: 'The build file is no longer on the relay.' });
+        }
+        // Set even though the agent compares against `buildBytes` instead: a correct header costs
+        // nothing and helps anything else that looks. It is not the check — a proxy may drop it.
+        res.writeHead(200, { 'Content-Type': 'application/octet-stream', 'Content-Length': size });
+        // **`pipe` does not destroy its source when the destination goes away** — it only unpipes — so an
+        // aborted download leaves the read stream and its file descriptor open for the life of the
+        // process. Measured: after a client abort, `rs.destroyed` is still false and the fd still stats.
+        // On this route an abort is the *ordinary* failure, not an edge case: the agent's own idle
+        // timeout destroys the request, and so does an agent that exits or a link that drops. Enough of
+        // them and the relay hits its descriptor limit and stops accepting connections at all.
+        const rs = fs.createReadStream(found.filePath);
+        res.on('close', () => { rs.destroy(); });
+        rs.on('error', () => { res.destroy(); });
+        rs.pipe(res);
+    }
     serveUpload(req, res) {
         const urlPath = (req.url ?? '/').split('?')[0];
         const filePath = path.join(this.uploadsDir, urlPath.replace('/uploads/', ''));
@@ -2196,9 +2296,11 @@ export class RelayServer {
         }
         const contentType = MIME_TYPES[path.extname(filePath)] ?? 'application/octet-stream';
         res.writeHead(200, { 'Content-Type': contentType });
-        fs.createReadStream(filePath)
-            .on('error', () => { res.destroy(); })
-            .pipe(res);
+        // Same leak as `handleBuildDownload` above, and the same one line closes it.
+        const rs = fs.createReadStream(filePath);
+        res.on('close', () => { rs.destroy(); });
+        rs.on('error', () => { res.destroy(); });
+        rs.pipe(res);
     }
     serveStatic(req, res) {
         const urlPath = (req.url ?? '/').split('?')[0];
@@ -2222,34 +2324,69 @@ export class RelayServer {
         const contentType = MIME_TYPES[path.extname(filePath)] ?? 'text/html';
         const headers = { 'Content-Type': contentType };
         // Content-hashed build assets never change → cache them forever.
+        // HTML entry points must revalidate on every load so updates are picked up immediately.
         if (urlPath.startsWith('/assets/')) {
             headers['Cache-Control'] = 'public, max-age=31536000, immutable';
         }
-        // Serve the build-time .br sibling when accepted (precompressed → no runtime CPU on the stream path).
+        else if (filePath.endsWith('index.html')) {
+            headers['Cache-Control'] = 'no-cache';
+        }
+        // Serve precompressed siblings (.br or .gz) when accepted (precompressed → no runtime CPU on the stream path).
         const acceptHeader = req.headers['accept-encoding'];
         const accept = Array.isArray(acceptHeader) ? acceptHeader.join(',') : acceptHeader ?? '';
-        const brAccepted = accept.split(',').some((token) => {
-            const [name, ...params] = token.trim().split(';');
-            const coding = name.trim().toLowerCase();
-            if (coding !== 'br' && coding !== '*')
-                return false;
-            const qParam = params.map((p) => p.trim()).find((p) => p.startsWith('q='));
-            const q = qParam ? Number(qParam.slice(2)) : 1;
-            return !Number.isNaN(q) && q > 0;
-        });
+        // **An explicit coding outranks `*`, rather than being maxed with it.** RFC 9110 §12.5.3 gives
+        // the more specific match precedence, and taking the maximum across both meant
+        // `Accept-Encoding: br;q=0, *` answered 1 for `br` — serving brotli to a client that named it
+        // and refused it. The two are tracked apart and the wildcard is consulted only when the coding
+        // was never named.
+        const parseQuality = (codingName) => {
+            let named = -1;
+            let wildcard = -1;
+            for (const token of accept.split(',')) {
+                const [name, ...params] = token.trim().split(';');
+                const coding = name.trim().toLowerCase();
+                if (coding !== codingName && coding !== '*')
+                    continue;
+                // Lowercased because RFC 9110 §5.6.6 makes parameter names case-insensitive: `br;Q=0` was
+                // missed, fell through to the default weight of 1, and served brotli to a client that had
+                // refused it. The qvalue itself is numeric, so folding the whole token is safe.
+                const qParam = params.map((p) => p.trim().toLowerCase()).find((p) => p.startsWith('q='));
+                const q = qParam ? Number(qParam.slice(2)) : 1;
+                if (Number.isNaN(q))
+                    continue;
+                if (coding === '*')
+                    wildcard = Math.max(wildcard, q);
+                else
+                    named = Math.max(named, q);
+            }
+            return named >= 0 ? named : wildcard;
+        };
+        const brQ = parseQuality('br');
+        const gzQ = Math.max(parseQuality('gzip'), parseQuality('x-gzip'));
+        // **`Vary` unconditionally, and that is what lets the probes below be skipped.** It declares a
+        // cache key rather than describing this response: a shared cache that stored the uncompressed
+        // body without it would hand that body to the next client, which may accept brotli. Deriving it
+        // from "does a sibling exist" is what forced a `stat` on every static request even when the
+        // client asked for no encoding at all — a syscall per asset per request, on the path this exists
+        // to make cheaper. Set it always, and ask the filesystem only about codings that could be served.
+        headers['Vary'] = 'Accept-Encoding';
+        const hasBr = brQ > 0 && fs.existsSync(filePath + '.br');
+        const hasGz = gzQ > 0 && fs.existsSync(filePath + '.gz');
         let servePath = filePath;
-        const hasBr = fs.existsSync(filePath + '.br');
-        // Vary whenever a compressed variant exists, even if raw is served, so caches don't cross-serve.
-        if (hasBr)
-            headers['Vary'] = 'Accept-Encoding';
-        if (brAccepted && hasBr) {
+        if (brQ > 0 && hasBr && (gzQ <= 0 || !hasGz || brQ >= gzQ)) {
             servePath = filePath + '.br';
             headers['Content-Encoding'] = 'br';
         }
+        else if (gzQ > 0 && hasGz) {
+            servePath = filePath + '.gz';
+            headers['Content-Encoding'] = 'gzip';
+        }
         res.writeHead(200, headers);
-        fs.createReadStream(servePath)
-            .on('error', () => { res.destroy(); })
-            .pipe(res);
+        // Same leak as `handleBuildDownload` above, and the same one line closes it.
+        const rs = fs.createReadStream(servePath);
+        res.on('close', () => { rs.destroy(); });
+        rs.on('error', () => { res.destroy(); });
+        rs.pipe(res);
     }
 }
 //# sourceMappingURL=RelayServer.js.map