Skip to content

Official Codebase of 3DCodeVerse

Python
14.4 KB
Raw Blame
// Headless-Chrome launcher for the WebGL renderers (render_glb / render_scene / probes).
//
// On this WSL2 box hardware WebGL needs BOTH the ANGLE gl-egl flags AND the
// Mesa d3d12 env trio; either alone silently lands on llvmpipe.  So every GPU
// attempt is verified through UNMASKED_RENDERER_WEBGL before it is trusted,
// and a negative verdict is cached (with a TTL) so the slow-to-fail GPU launch
// is not repeated on every render.
//
//   const { launchBrowser, rendererInfo } = require('./gpu_launch.cjs');
//   const handle = await launchBrowser({ gpu: 'auto' });
//   ... handle.browser / handle.gpu / handle.renderer ...
//   await handle.release();   // NOT browser.close(): the browser may be shared
//
// gpu: 'auto' (probe, cached) | 'on' (require hardware; throw otherwise) | 'off' (CPU).
//
// Browser reuse (connect-first): a launch costs ~0.55 s, a puppeteer.connect
// ~5 ms.  A detached `browser_daemon.cjs` owns one long-lived browser per
// backend ('gpu'|'cpu') and advertises its ws endpoint in a file under
// CACHE_DIR; launchBrowser connects to it when present, spawns the daemon when
// absent, and falls back to a plain owned launch when the daemon cannot help.
// `release()` disconnects from a shared browser (the daemon reaps it after
// ~90 s idle) and closes an owned one.  `C3D_BROWSER_REUSE=off` disables
// sharing entirely.
'use strict';

const { spawn } = require('child_process');
const crypto = require('crypto');
const fs = require('fs');
const os = require('os');
const path = require('path');

const CACHE_DIR = process.env.C3D_CACHE_DIR || path.join(os.homedir(), '.cache', 'codeverse3d');
const CACHE_PATH = path.join(CACHE_DIR, 'gpu_probe.json');
const NEGATIVE_TTL_MS = 20 * 60 * 1000; // how long a "no GPU" verdict is trusted
const PROTOCOL_TIMEOUT_MS = 15 * 60 * 1000; // big frame batches exceed puppeteer's 180 s default
const DAEMON_WAIT_MS = 25000;   // max wait for a spawned daemon to advertise its endpoint
const CANARY_TIMEOUT_MS = 6000; // a healthy browser answers pages() in ~5 ms
const MAX_SHARED_PAGES = 12;    // more open pages than any sane moment = leaked pages piling up
const SPAWN_LOCK_STALE_MS = 30000;

const BASE_ARGS = ['--no-sandbox', '--disable-setuid-sandbox', '--enable-webgl', '--ignore-gpu-blocklist'];
const GPU_ARGS = [...BASE_ARGS, '--enable-gpu-rasterization', '--use-angle=gl-egl'];
const CPU_ARGS = [...BASE_ARGS, '--enable-unsafe-swiftshader', '--use-angle=swiftshader'];
const GPU_ENV = {
  GALLIUM_DRIVER: 'd3d12',
  MESA_LOADER_DRIVER_OVERRIDE: 'd3d12',
  MESA_D3D12_DEFAULT_ADAPTER_NAME: 'NVIDIA',
};
const SOFTWARE_RE = /swiftshader|llvmpipe|softpipe|software|basic render/i;

function writeCache(decision) {
  try {
    fs.mkdirSync(CACHE_DIR, { recursive: true });
    fs.writeFileSync(CACHE_PATH, JSON.stringify({ ...decision, at: Date.now() }, null, 2));
  } catch (_e) {
    /* cache is an optimisation only */
  }
}

/**
 * Probe the browser's WebGL backend. Returns the UNMASKED_RENDERER string or null
 * when no WebGL context can be created.
 */
async function rendererInfo(browser) {
  const page = await browser.newPage();
  try {
    return await page.evaluate(() => {
      const canvas = document.createElement('canvas');
      const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
      if (!gl) return null;
      const ext = gl.getExtension('WEBGL_debug_renderer_info');
      const r = ext ? gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER);
      return String(r);
    });
  } finally {
    await page.close().catch(() => {});
  }
}

function loadPuppeteer(puppeteer) {
  return puppeteer || require('puppeteer');
}

function owned(browser, gpu, renderer) {
  return { browser, gpu, renderer, shared: false, release: () => browser.close().catch(() => {}) };
}

async function launchCpu(puppeteer) {
  const env = { ...process.env };
  for (const k of Object.keys(GPU_ENV)) delete env[k];
  const browser = await puppeteer.launch({
    headless: true,
    args: CPU_ARGS,
    env,
    protocolTimeout: PROTOCOL_TIMEOUT_MS,
  });
  let renderer = 'SwiftShader (CPU)';
  try {
    renderer = (await rendererInfo(browser)) || renderer;
  } catch (_e) {
    /* keep the default label */
  }
  return owned(browser, false, renderer);
}

async function tryGpu(puppeteer) {
  let browser = null;
  try {
    browser = await puppeteer.launch({
      headless: true,
      args: GPU_ARGS,
      env: { ...process.env, ...GPU_ENV },
      protocolTimeout: PROTOCOL_TIMEOUT_MS,
    });
    const renderer = await rendererInfo(browser);
    if (!renderer || SOFTWARE_RE.test(renderer)) {
      await browser.close().catch(() => {});
      return { browser: null, renderer: renderer || 'no WebGL context' };
    }
    return { browser, renderer };
  } catch (e) {
    if (browser) await browser.close().catch(() => {});
    return { browser: null, renderer: `launch failed: ${e.message}` };
  }
}

// --------------------------------------------------------------------- sharing
// A git worktree and the main checkout each run THEIR OWN runtime_js but share
// ~/.cache/codeverse3d unless the operator remembers C3D_CACHE_DIR, so both daemons
// used to advertise into one `browser_<backend>.json`: the second overwrote the
// first, the first exited on its superseded-endpoint check, and clients of both
// trees landed on a single browser whose page budget and canary were sized for one.
// Measured 2026-09-05 — two live daemons from two trees, `Session closed` across the
// scene suite, passing again the moment the trees were given separate cache dirs.
// Keying the endpoint by the runtime_js that spawned it makes that structural: two
// trees never share a browser, and neither can retire the other's.
const RUNTIME_KEY = crypto.createHash('sha1').update(__dirname).digest('hex').slice(0, 8);

/** Base name for this runtime's per-backend daemon files (endpoint, lock, failure). */
function endpointBase(backend) {
  return path.join(CACHE_DIR, `browser_${backend}_${RUNTIME_KEY}`);
}

function endpointPath(backend) {
  return `${endpointBase(backend)}.json`;
}

function daemonFailPath(backend) {
  return `${endpointBase(backend)}.failed.json`;
}

/** Single-flight spawn lock; the daemon deletes it once it has advertised. */
function spawnLockPath(backend) {
  return `${endpointBase(backend)}.lock`;
}

function reuseEnabled() {
  // the Settings Flag words (codeverse3d/config.py): off/0/false/no turn it off
  return !/^\s*(off|0|false|no)\s*$/i.test(process.env.C3D_BROWSER_REUSE || '');
}

function readJson(p) {
  try {
    return JSON.parse(fs.readFileSync(p, 'utf8'));
  } catch (_e) {
    return null;
  }
}

/** Touch the endpoint file: its mtime is the daemon's idle-reap heartbeat. */
function heartbeat(backend) {
  try {
    const now = new Date();
    fs.utimesSync(endpointPath(backend), now, now);
  } catch (_e) { /* endpoint may be gone; connect error handling covers it */ }
}

// The ws this process last REJECTED (canary timeout / page overflow).  The endpoint
// file stays for everyone else (only the daemon retires the browser), but re-testing
// the same wedged ws in sharedBrowser's 50 ms wait loop costs a 6 s canary per
// iteration — up to ~24 s of pure wait.  Skip it until a NEW ws is advertised.
let rejectedWs = null;

/** Connect to the shared browser advertised for `backend`; null when absent/poisoned. */
async function connectShared(puppeteer, backend) {
  const info = readJson(endpointPath(backend));
  if (!info || !info.ws || info.ws === rejectedWs) return null;
  try {
    const browser = await puppeteer.connect({ browserWSEndpoint: info.ws, protocolTimeout: PROTOCOL_TIMEOUT_MS });
    // Health canary: a long-lived shared browser can wedge (WSL GPU decay plus pages
    // leaked by SIGKILLed clients) and then every CDP roundtrip stalls ~100 s.  One
    // bounded pages() decides whether THIS caller uses it — nothing more.  It must not
    // retire the browser: deleting the endpoint makes the daemon close it, and a
    // busy box (four runs, blender pegging the CPU) answers pages() slowly, so a
    // false verdict killed a live scene probe's page mid-call with
    // 'Protocol error: Target closed' (measured 2026-08-27).  Only the daemon, which
    // knows whether anyone is working, may retire the browser; a caller that does not
    // like what it sees simply launches its own.
    let pages = null;
    try {
      let timer = null;
      pages = await Promise.race([
        browser.pages(),
        new Promise((_res, rej) => { timer = setTimeout(() => rej(new Error('canary timeout')), CANARY_TIMEOUT_MS); if (timer.unref) timer.unref(); }),
      ]);
      if (timer) clearTimeout(timer);
    } catch (_e) { pages = null; }
    if (!pages || pages.length > MAX_SHARED_PAGES) {
      rejectedWs = info.ws;
      try { await browser.disconnect(); } catch (_e) { /* ignore */ }
      return null;   // own launch for this caller; the endpoint stays for everyone else
    }
    heartbeat(backend);
    // Keep the heartbeat fresh WHILE the client works: it used to tick only on
    // connect and release, so a scene probe holding one page for 16 minutes looked
    // idle to the daemon, which closed its page (page TTL) or the whole browser
    // (HARD_REAP_MS) out from under it — 'Protocol error: Target closed'.
    const beat = setInterval(() => heartbeat(backend), 30_000);
    if (beat.unref) beat.unref();
    return {
      browser,
      gpu: !!info.gpu,
      renderer: String(info.renderer || ''),
      shared: true,
      release: async () => {
        clearInterval(beat);
        heartbeat(backend);
        try { await browser.disconnect(); } catch (_e) { /* already gone */ }
      },
    };
  } catch (_e) {
    // connect itself REFUSED: nothing listens at that ws, so the daemon (the browser's
    // parent) is gone too — clearing a DEAD advertisement does not violate "only the
    // daemon retires the browser"; a merely-slow browser is the canary's case above,
    // and the canary never touches the file.
    try { fs.rmSync(endpointPath(backend), { force: true }); } catch (_e2) { /* ignore */ }
    return null;
  }
}

/** Spawn the detached daemon for `backend` (single flight via a lock file). */
function spawnDaemon(backend) {
  fs.mkdirSync(CACHE_DIR, { recursive: true });
  const lock = spawnLockPath(backend);
  try {
    const st = fs.statSync(lock);
    if (Date.now() - st.mtimeMs < SPAWN_LOCK_STALE_MS) return; // someone else is spawning
    fs.rmSync(lock, { force: true });
  } catch (_e) { /* no lock */ }
  try {
    fs.writeFileSync(lock, String(process.pid), { flag: 'wx' });
  } catch (_e) {
    return; // lost the race
  }
  try { fs.rmSync(daemonFailPath(backend), { force: true }); } catch (_e) { /* ignore */ }
  const child = spawn(process.execPath, [path.join(__dirname, 'browser_daemon.cjs'), '--backend', backend],
    { detached: true, stdio: 'ignore', env: process.env });
  child.unref();
}

/**
 * Get a shared browser for `backend` ('gpu'|'cpu'): connect to the advertised
 * endpoint, spawning the daemon first when there is none.
 * @returns handle, or {failed: string} when the daemon reported a launch
 *          failure (meaningful for 'gpu'), or null on timeout/no daemon.
 */
async function sharedBrowser(puppeteer, backend) {
  let handle = await connectShared(puppeteer, backend);
  if (handle) return handle;
  // Still advertised = this caller REJECTED a live browser (canary timeout / page budget).
  // It is everyone else's, so this caller launches its own.  Spawning a daemon here
  // superseded it, and a superseded daemon closes its browser under its clients' pages:
  // 'Target closed' across a loaded suite, six browsers in 30 s (2026-09-23).
  const rejected = () => { const cur = readJson(endpointPath(backend)); return !!cur && cur.ws === rejectedWs; };
  if (rejected()) return null;
  spawnDaemon(backend);
  const deadline = Date.now() + DAEMON_WAIT_MS;
  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, 50));
    handle = await connectShared(puppeteer, backend);
    if (handle) return handle;
    if (rejected()) return null;
    const failed = readJson(daemonFailPath(backend));
    if (failed) return { failed: String(failed.error || 'daemon launch failed') };
  }
  return null;
}

async function cpuBrowser(puppeteer) {
  if (reuseEnabled()) {
    const h = await sharedBrowser(puppeteer, 'cpu');
    if (h && h.browser) return h;
  }
  return launchCpu(puppeteer);
}

/** GPU browser or {browser:null, renderer:<why>} — shared first, owned fallback. */
async function gpuBrowser(puppeteer) {
  if (reuseEnabled()) {
    const h = await sharedBrowser(puppeteer, 'gpu');
    if (h && h.browser) return h;
    if (h && h.failed) return { browser: null, renderer: h.failed };
    // daemon never answered: fall through to an owned launch
  }
  const attempt = await tryGpu(puppeteer);
  if (!attempt.browser) return { browser: null, renderer: attempt.renderer };
  return owned(attempt.browser, true, attempt.renderer);
}

/**
 * Launch (or connect to) headless Chrome on the best available WebGL backend.
 * @param {{gpu?: 'auto'|'on'|'off', puppeteer?: object}} opts
 * @returns {Promise<{browser: object, gpu: boolean, renderer: string, shared: boolean, release: () => Promise<void>}>}
 */
async function launchBrowser(opts = {}) {
  const mode = String(opts.gpu || process.env.C3D_RENDER_GPU || 'auto').toLowerCase();
  const puppeteer = loadPuppeteer(opts.puppeteer);
  if (!['auto', 'on', 'off'].includes(mode)) throw new Error(`gpu must be auto|on|off, got ${mode}`);

  if (mode === 'off') return cpuBrowser(puppeteer);

  if (mode === 'on') {
    const attempt = await gpuBrowser(puppeteer);
    if (!attempt.browser) throw new Error(`gpu=on but no hardware WebGL: ${attempt.renderer}`);
    return attempt;
  }

  // auto: a fresh negative verdict skips the slow GPU attempt; a positive one is
  // re-verified by the GPU attempt itself (shared endpoint or launch), since the
  // GPU can go away.
  const cached = readJson(CACHE_PATH);
  const fresh = cached && typeof cached.at === 'number' && Date.now() - cached.at < NEGATIVE_TTL_MS;
  if (cached && cached.use_gpu === false && fresh) return cpuBrowser(puppeteer);

  const attempt = await gpuBrowser(puppeteer);
  if (attempt.browser) {
    writeCache({ use_gpu: true, renderer: attempt.renderer });
    return attempt;
  }
  writeCache({ use_gpu: false, renderer: attempt.renderer });
  return cpuBrowser(puppeteer);
}

module.exports = {
  launchBrowser, rendererInfo,
  // internals shared with browser_daemon.cjs (not a public surface)
  _internal: { launchCpu, tryGpu, loadPuppeteer, readJson, endpointPath, daemonFailPath, spawnLockPath, CACHE_DIR },
};