@ultimat3/scraping 19.1.2 → 19.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "19.1.2",
+  "version": "19.2.0",
   "description": "Browser automation as a job: scrape() returns a JobHandle",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "19.1.2",
-    "@ultimat3/jobs": "19.1.2",
-    "@ultimat3/schema": "19.1.2",
-    "@ultimat3/storage": "19.1.2"
+    "@ultimat3/core": "19.2.0",
+    "@ultimat3/jobs": "19.2.0",
+    "@ultimat3/schema": "19.2.0",
+    "@ultimat3/storage": "19.2.0"
   }
 }

package/src/error-throws.ts

@@ -36,13 +36,64 @@ export const cdpAttachFailed = (cdpUrl: string, thrown: unknown): ScrapeError =>
     meta: { cdpUrl },
   });
 
+/**
+ * What separates "there is no browser" from "the browser stopped answering". Both arrive at the
+ * same `catch` around `launch()` (`driver-cdp.ts`), and only one of them is worth a second attempt.
+ *
+ * Matched on the LAUNCHER'S OWN WORDS rather than on a flag this function could be passed, because
+ * the launch site hands it one `unknown` and nothing else. Every entry below is a message a browser
+ * library or the kernel emits for a browser that is not there, and none of them is producible by a
+ * page that merely went away mid-run — which is what keeps the split honest at `cdp-target.ts`'s
+ * call site, where the browser demonstrably existed.
+ *
+ * Lowercase, and compared against a lowercased render, so a library re-capitalising its own message
+ * does not silently turn a permanent misconfiguration back into five retries.
+ */
+const BROWSER_ABSENT_SIGNS: readonly string[] = [
+  // puppeteer-core ships no browser and has no default: this is its whole message when nothing was
+  // configured — ``An `executablePath` or `channel` must be specified for `puppeteer-core```.
+  'must be specified',
+  // `spawn /usr/bin/google-chrome ENOENT` — an executablePath naming a file that is not there,
+  // which is what a CHROME_PATH left over from another machine is.
+  'enoent',
+  // The binary is there and this uid may not execute it. Attempt 2 runs as the same user.
+  'eacces',
+  // The two spellings puppeteer has shipped for "I looked for a browser and found none".
+  'could not find chrome',
+  'could not find browser',
+  'was not found at the configured executablepath',
+];
+
+const browserIsAbsent = (thrown: unknown): boolean => {
+  const text = renderThrowable(thrown).toLowerCase();
+  return BROWSER_ABSENT_SIGNS.some((sign) => text.includes(sign));
+};
+
+/**
+ * A launch or a page call that failed. TWO codes, because the two failures have opposite answers.
+ *
+ * `X_SCRAPE_BROWSER_UNREACHABLE` is transport and stays retryable: a browser that was there is
+ * gone, and attempt 2 may find it back.
+ *
+ * `X_SCRAPE_BROWSER_MISSING` is a misconfiguration and is terminal. Its fix used to read "raise
+ * watchdog: { idleMs } on the scrape() definition … otherwise re-run once the browser host is
+ * back", which on the `x shot` path names a definition that does not exist and an act that never
+ * helps — while the retry table spent five browser launches proving it.
+ */
 export const browserUnreachable = (driver: string, thrown: unknown): ScrapeError =>
-  new ScrapeError({
-    code: 'X_SCRAPE_BROWSER_UNREACHABLE',
-    cause: `the ${driver} browser stopped answering: ${renderThrowable(thrown)}`,
-    fix: 'raise watchdog: { idleMs } on the scrape() definition if the site is genuinely slow, otherwise re-run once the browser host is back',
-    meta: { driver },
-  });
+  browserIsAbsent(thrown)
+    ? new ScrapeError({
+        code: 'X_SCRAPE_BROWSER_MISSING',
+        cause: `the ${driver} driver has no browser to launch: ${renderThrowable(thrown)}`,
+        fix: 'install a Chrome or Chromium and name it — localBrowser({ launcher, executablePath: env.CHROME_PATH }) — or attach to one somebody else is running with remoteBrowser({ cdpUrl: env.SCRAPE_CDP_URL })',
+        meta: { driver },
+      })
+    : new ScrapeError({
+        code: 'X_SCRAPE_BROWSER_UNREACHABLE',
+        cause: `the ${driver} browser stopped answering: ${renderThrowable(thrown)}`,
+        fix: 'raise watchdog: { idleMs } on the scrape() definition if the site is genuinely slow, otherwise re-run once the browser host is back',
+        meta: { driver },
+      });
 
 export const profileLocked = (profileDir: string): ScrapeError =>
   new ScrapeError({

package/src/errors.ts

@@ -11,6 +11,7 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_DRIVER_UNKNOWN',
   'X_SCRAPE_CDP_ATTACH_FAILED',
   'X_SCRAPE_BROWSER_UNREACHABLE',
+  'X_SCRAPE_BROWSER_MISSING',
   'X_SCRAPE_PROFILE_LOCKED',
   'X_SCRAPE_HOST_BLOCKED',
   'X_SCRAPE_SELECTOR_MISSING',
@@ -59,6 +60,7 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
   X_SCRAPE_DRIVER_UNKNOWN: 'no browser driver is installed for this run',
   X_SCRAPE_CDP_ATTACH_FAILED: 'the CDP endpoint refused the attach',
   X_SCRAPE_BROWSER_UNREACHABLE: 'the browser went away mid-run',
+  X_SCRAPE_BROWSER_MISSING: 'there is no browser on this machine for the driver to launch',
   X_SCRAPE_PROFILE_LOCKED: 'another process holds this browser profile',
   X_SCRAPE_HOST_BLOCKED: 'the page asked for a host allowHosts does not list',
   X_SCRAPE_SELECTOR_MISSING: 'the selector never appeared inside its window',
@@ -106,6 +108,10 @@ registerErrorCodes(
  */
 export const SCRAPE_ERROR_RETRY = {
   X_SCRAPE_CDP_ATTACH_FAILED: 'retryable',
+  // Retryable, and it now means ONLY what its title says: a browser that was there and stopped
+  // answering. It used to be raised for a launch that failed because there was no browser to
+  // launch at all, which the same run repeated five times — `X_SCRAPE_BROWSER_MISSING` below is
+  // that half, split out and terminal.
   X_SCRAPE_BROWSER_UNREACHABLE: 'retryable',
   X_SCRAPE_TIMEOUT: 'retryable',
   X_SCRAPE_WEDGED: 'retryable',
@@ -124,6 +130,14 @@ export const SCRAPE_ERROR_RETRY = {
   // Everything below is terminal, and each one is listed rather than left to the default so that
   // deleting a line is a visible decision.
   X_SCRAPE_DRIVER_UNKNOWN: 'terminal',
+  // TERMINAL where its sibling `X_SCRAPE_BROWSER_UNREACHABLE` is retryable, and the difference IS
+  // the reason the two codes are separate. "The browser host went away" is transport — attempt 2
+  // may find it back. "There is no browser binary on this box, or none was configured" is a
+  // MISCONFIGURATION: attempt 2 spawns the same absent path, five times, on a five-attempt policy,
+  // and on an authenticated target that is five arrivals at a login for no chance of a different
+  // answer. Measured on `x shot`, where there is no `scrape()` definition to raise a watchdog on
+  // and re-running never helps. The repair is an install or an `executablePath`, so a human decides.
+  X_SCRAPE_BROWSER_MISSING: 'terminal',
   X_SCRAPE_PROFILE_LOCKED: 'terminal',
   X_SCRAPE_HOST_BLOCKED: 'terminal',
   X_SCRAPE_SELECTOR_MISSING: 'terminal',