@reclaimprotocol/agent 0.1.26 → 0.1.28

package/src/live/tunnel.ts

@@ -24,42 +24,27 @@ import { type CloudflaredBinary, resolveCloudflared } from './cloudflared.ts'
 
 /** How long to wait for cloudflared to report its hostname before giving up. */
 const URL_TIMEOUT_MS = 30_000
-/** After the hostname is printed, Cloudflare needs a moment before the edge
- *  routes to it — measured at ~3s. Wait for it so the caller never hands out a
- *  URL that errors, but don't fail the share if it's slow. */
+/** After the hostname is printed, Cloudflare needs time before the edge routes
+ *  to it. Probe briefly, then return the still-running tunnel as propagating so
+ *  slow DNS or edge setup does not destroy an otherwise healthy share. */
 const READY_TIMEOUT_MS = 20_000
 const READY_POLL_MS = 1_000
+const STOP_TIMEOUT_MS = 5_000
 
 /** `https://<something>.trycloudflare.com`, as printed on cloudflared's log
  *  stream. Anchored to the scheme so a hostname inside prose can't match. */
 const QUICK_TUNNEL_URL = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i
 
-/**
- * cloudflared says this once per edge connection it establishes, and until it
- * does, the hostname resolves but routes nowhere.
- *
- * This is the signal to trust, because it is LOCAL. Asking whether we can fetch
- * the public URL ourselves conflates two questions — is the tunnel up, and does
- * this machine have egress to Cloudflare's edge — and reports "not ready" when
- * only the second fails. Observed: a tunnel printed its hostname and registered
- * nothing for 12s, which is indistinguishable from a blocked fetch unless you
- * read cloudflared's own account of it.
- */
-const REGISTERED = /Registered tunnel connection|connIndex=/i
-
 /** Tail of cloudflared's log kept for error messages. */
 const LOG_TAIL_BYTES = 4096
 
 export interface Tunnel {
 	/** The public HTTPS origin Cloudflare assigned. */
 	url: string
-	/** Whether the tunnel was carrying traffic before {@link READY_TIMEOUT_MS}
-	 *  elapsed. False means it may still be propagating rather than broken — say
-	 *  so rather than treating the share as failed. */
+	/** Whether the public viewer answered during the initial readiness probe. */
 	ready: boolean
-	/** cloudflared's own last words, for when `ready` is false and someone has
-	 *  to work out why. Absent when the tunnel came up normally. */
-	diagnostics?: string
+	/** Bounded cloudflared output when the edge is still propagating. */
+	cloudflaredLog?: string
 	/** Terminate the tunnel. Safe to call more than once. */
 	stop: () => Promise<void>
 	/** Which cloudflared ran, and whether we had to fetch it. */
@@ -69,37 +54,43 @@ export interface Tunnel {
 /**
  * Wait until the tunnel is actually carrying traffic.
  *
- * Two independent signals, either of which is proof:
- *  - cloudflared reported an edge registration (see {@link REGISTERED}). Local,
- *    so it works regardless of this machine's own egress.
- *  - the public origin answered. ANY HTTP response counts, including a 404:
- *    the live-view server 404s unknown paths, so a status code at all proves
- *    the hop is live. Kept as a second opinion in case a cloudflared release
- *    rewords its log.
+ * A cloudflared "Registered tunnel connection" log is not enough: Cloudflare
+ * can report one while the assigned hostname still returns DNS NXDOMAIN. The
+ * public viewer itself must return a successful response.
  */
 async function waitUntilRouted(
 	url: string,
-	isRegistered: () => boolean,
+	{
+		isRunning,
+		pollMs,
+		timeoutMs,
+	}: {
+		isRunning: () => boolean
+		pollMs: number
+		timeoutMs: number
+	},
 ): Promise<boolean> {
-	const deadline = Date.now() + READY_TIMEOUT_MS
+	const deadline = Date.now() + timeoutMs
 	while(Date.now() < deadline) {
-		if(isRegistered()) {
-			return true
+		if(!isRunning()) {
+			return false
 		}
 
 		try {
-			await fetch(url, {
+			const response = await fetch(url, {
 				method: 'GET',
 				redirect: 'manual',
-				signal: AbortSignal.timeout(READY_POLL_MS * 2),
+				signal: AbortSignal.timeout(pollMs * 2),
 			})
-			return true
-		} catch{
-			await new Promise((r) => setTimeout(r, READY_POLL_MS))
-		}
+			if(response.ok) {
+				return true
+			}
+		} catch{}
+
+		await new Promise((r) => setTimeout(r, pollMs))
 	}
 
-	return isRegistered()
+	return false
 }
 
 /**
@@ -111,7 +102,20 @@ async function waitUntilRouted(
  */
 export async function startTunnel(
 	port: number,
-	{ autoInstall = true }: { autoInstall?: boolean } = {},
+	{
+		autoInstall = true,
+		probePath = '/',
+		readyPollMs = READY_POLL_MS,
+		readyTimeoutMs = READY_TIMEOUT_MS,
+	}: {
+		autoInstall?: boolean
+		/** Public path that must answer before the tunnel is returned. */
+		probePath?: string
+		/** Test-only timing override. */
+		readyPollMs?: number
+		/** Test-only timing override. */
+		readyTimeoutMs?: number
+	} = {},
 ): Promise<Tunnel> {
 	// Resolves an existing cloudflared, or fetches one on first use. Throws
 	// with an actionable message when neither is possible.
@@ -121,25 +125,14 @@ export async function startTunnel(
 		'--no-autoupdate',
 		'--url', `http://127.0.0.1:${port}`,
 	], { stdio: ['ignore', 'pipe', 'pipe'] })
+	const exited = new Promise<void>((resolve) => {
+		child.once('exit', () => resolve())
+	})
 
-	const stop = async() => {
-		if(!child.killed) {
-			child.kill('SIGTERM')
-		}
-	}
+	let stopPromise: Promise<void> | undefined
+	const stop = () => stopPromise ??= stopChild()
 
 	return new Promise<Tunnel>((resolve, reject) => {
-		const timer = setTimeout(() => {
-			void stop()
-			reject(new Error(
-				'cloudflared did not report a tunnel hostname within '
-				+ `${URL_TIMEOUT_MS / 1000}s. Check network egress to Cloudflare, `
-				+ 'or run `cloudflared tunnel --url http://127.0.0.1:'
-				+ `${port}` + '` by hand to see its output.',
-			))
-		}, URL_TIMEOUT_MS)
-
-		let registered = false
 		let tail = ''
 		let settled = false
 		const finish = (fn: () => void) => {
@@ -152,30 +145,60 @@ export async function startTunnel(
 			fn()
 		}
 
+		const timer = setTimeout(() => {
+			finish(() => {
+				void stop().then(() => reject(new Error(
+					'cloudflared did not report a tunnel hostname within '
+					+ `${URL_TIMEOUT_MS / 1000}s. Check network egress to `
+					+ 'Cloudflare, or run `cloudflared tunnel --url '
+					+ `http://127.0.0.1:${port}` + '` by hand to see its output.',
+				)))
+			})
+		}, URL_TIMEOUT_MS)
+
 		// cloudflared logs the assigned hostname to stderr, not stdout. Watch
 		// both so a future version that switches streams still works.
 		const onChunk = (chunk: Buffer) => {
 			const text = chunk.toString()
-			// Keep watching after the hostname: registration lands a beat later, and
-			// on a bad run it never lands at all, which is the case worth reporting.
+			// Keep watching after the hostname so a readiness failure can include
+			// cloudflared's account of what happened.
 			tail = (tail + text).slice(-LOG_TAIL_BYTES)
-			if(REGISTERED.test(text)) {
-				registered = true
-			}
 
-			const match = QUICK_TUNNEL_URL.exec(text)
+			// Search the accumulated tail so a URL split across stream chunks is not
+			// missed. The tail is bounded and the URL appears near startup.
+			const match = QUICK_TUNNEL_URL.exec(tail)
 			if(match) {
 				const url = match[0]
 				finish(() => {
-					void waitUntilRouted(url, () => registered).then((ready) => {
+					const probeUrl = new URL(probePath, `${url}/`).toString()
+					void waitUntilRouted(probeUrl, {
+						isRunning: () => child.exitCode === null
+							&& child.signalCode === null,
+						pollMs: readyPollMs,
+						timeoutMs: readyTimeoutMs,
+					}).then((ready) => {
 						if(ready) {
 							resolve({ url, ready, stop, binary })
 							return
 						}
 
+						if(child.exitCode !== null || child.signalCode !== null) {
+							reject(new Error(
+								'cloudflared exited before the public viewer became reachable. '
+								+ 'cloudflared output:\n' + tail,
+							))
+							return
+						}
+
 						LOGGER.warn({ url, tail },
-							'tunnel never registered with an edge; returning anyway')
-						resolve({ url, ready, stop, binary, diagnostics: tail })
+							'tunnel still propagating; returning the live hostname')
+						resolve({
+							url,
+							ready,
+							cloudflaredLog: tail,
+							stop,
+							binary,
+						})
 					})
 				})
 			}
@@ -205,4 +228,27 @@ export async function startTunnel(
 			)))
 		})
 	})
+
+	async function stopChild() {
+		if(child.exitCode !== null || child.signalCode !== null) {
+			return
+		}
+
+		let timeout: NodeJS.Timeout | undefined
+		const timedOut = new Promise<void>((resolve) => {
+			timeout = setTimeout(resolve, STOP_TIMEOUT_MS)
+		})
+		child.kill('SIGTERM')
+		await Promise.race([
+			exited,
+			timedOut,
+		])
+		clearTimeout(timeout)
+		if(child.exitCode !== null || child.signalCode !== null) {
+			return
+		}
+
+		child.kill('SIGKILL')
+		await exited
+	}
 }