rnxsim 0.1.370 → 0.1.371

package/cli/commands/box/checkout-plane.ts

@@ -1,4 +1,4 @@
-// ProjectFilePlane over a real local checkout — the second host behind the
+// ProjectFilePlane over a real local checkout: the second host behind the
 // seam Contrast's browser already implements. writes land on the user's actual
 // disk, so nothing here converts content: the plane reads and writes bytes.
 //
@@ -9,13 +9,10 @@
 // 67 ms. `index()` is a synchronous whole-project map, so the size of that set
 // is the whole cost model.
 
-import { execFile } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
-import { promisify } from 'node:util'
-import type { ProjectFileMeta, ProjectFilePlane } from '@contrast/harness'
-
-const execFileAsync = promisify(execFile)
+import type { ProjectFileMeta, ProjectFilePlane } from '@contrast/harness/plane'
 
 export class CheckoutRequiresGitError extends Error {}
 
@@ -29,6 +26,31 @@ export class CheckoutRequiresGitError extends Error {}
 // the fact has to be in the index where the filesystem layer can read it.
 const BINARY_SNIFF_BYTES = 8192
 
+// every command a box runs re-indexes first, and the index read waits on a git
+// subprocess. it used to await one, and that await could never finish: measured
+// here over 961 refreshes, the call either answered within 314ms (p50 25ms) or
+// never answered at all, once for 29 seconds while the process's own timer kept
+// firing every second. that is not a slow git, it is a lost answer, and no
+// budget reaches it.
+//
+// a deadline on the async form does not help either, which is why this is
+// synchronous. node's `execFile` timeout kills the child and then still waits
+// for a 'close' event to settle the promise, so the lost event takes the
+// deadline down with it: the bound below was armed and silent through all 29
+// of those seconds. `execFileSync` waits in the runtime instead of on a
+// javascript event, so there is nothing to miss, and its timeout is enforced
+// the same way.
+//
+// it costs nothing. the entry loop below is already synchronous stat and read,
+// and under 24-way load the two forms were indistinguishable over 960 calls
+// each, interleaved: p50 1529ms synchronous against 1520ms asynchronous.
+//
+// 10s is roughly fifteen times the slowest full refresh measured on a
+// 14,889-file checkout (430-840 ms, of which `git ls-files` itself is 67 ms),
+// so it cannot fire for a project that is merely large or a machine that is
+// merely busy.
+const LIST_FILES_TIMEOUT_MS = 10_000
+
 function looksBinary(filePath: string, size: number): boolean {
   if (size === 0) return false
   let fd: number | undefined
@@ -62,9 +84,14 @@ export class CheckoutFilePlane implements ProjectFilePlane {
   readonly root: string
   private entries = new Map<string, ProjectFileMeta>()
   private sniffed = new Map<string, SniffedFile>()
+  // the deadline above, as a number a caller can set. what it changes is how
+  // long a wedged git is waited on, never whether it is waited on, so proving
+  // the kill does not have to cost the production deadline.
+  private readonly listTimeoutMs: number
 
-  constructor(root: string) {
+  constructor(root: string, options: { listTimeoutMs?: number } = {}) {
     this.root = path.resolve(root)
+    this.listTimeoutMs = options.listTimeoutMs ?? LIST_FILES_TIMEOUT_MS
   }
 
   index(): ReadonlyMap<string, ProjectFileMeta> {
@@ -77,16 +104,40 @@ export class CheckoutFilePlane implements ProjectFilePlane {
       // -z so paths containing spaces or newlines survive; -co --exclude-standard
       // is tracked plus untracked-not-ignored, which is what a person means by
       // "the files in my project".
-      const result = await execFileAsync(
-        'git',
-        ['ls-files', '-co', '--exclude-standard', '-z'],
-        { cwd: this.root, maxBuffer: 64 * 1024 * 1024 },
-      )
-      stdout = result.stdout
+      stdout = execFileSync('git', ['ls-files', '-co', '--exclude-standard', '-z'], {
+        cwd: this.root,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: this.listTimeoutMs,
+        // stating the environment is not redundant here. bun 1.3.14 resolves
+        // the binary for the synchronous form against the PATH it captured at
+        // startup and ignores a later change to `process.env.PATH`, so without
+        // this it runs a different git than every other call in the process.
+        env: process.env,
+      })
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
+      // the deadline kills with SIGTERM, so that signal is what tells a bound
+      // run apart from git failing on its own terms, and it is worth naming
+      // separately: "git was killed by SIGTERM" reads as git's problem, when
+      // what happened is that it never answered.
+      const killed =
+        error instanceof Error && 'signal' in error && error.signal === 'SIGTERM'
+      throw new CheckoutRequiresGitError(
+        killed
+          ? `git did not list the project's files in ${this.root} within ${this.listTimeoutMs / 1000}s, so the box has no file set to serve. the checkout may be on a stalled filesystem, or this machine may be too loaded to start a subprocess.`
+          : `could not list the project's files with git in ${this.root}: ${message}`,
+      )
+    }
+
+    // a busy machine also hands back a child that exits 0 having written
+    // nothing, which docs/testing.md owns: empty child output never means an
+    // empty answer. without this the box would build an empty index and every
+    // read would report the file as missing, which is a broken project rather
+    // than a broken box, and nothing would say so.
+    if (stdout.length === 0) {
       throw new CheckoutRequiresGitError(
-        `could not list the project's files with git in ${this.root}: ${message}`,
+        `git listed no files in ${this.root}. either git tracks nothing there and nothing untracked is visible to it, or this machine could not read the child process's output.`,
       )
     }
 

package/cli/commands/box/cloud-box.ts

@@ -0,0 +1,294 @@
+// the client half of a cloud box: create it, seed this checkout into it, and
+// run its shell over the box's own WebSocket.
+//
+// the box holds the files and the shell; this process holds neither. so the
+// REPL here sends `shell:exec` and prints what comes back, and `cwd` is
+// whatever the box last reported rather than anything tracked locally. that is
+// the whole difference between the two placements, and it is why the same
+// readline loop drives both.
+//
+// there is no default endpoint. a cloud box has to be deployed before one can
+// exist, and pointing at a URL that answers nothing would advertise a
+// capability that always fails.
+
+import WebSocket from 'ws'
+import type { CheckoutFilePlane } from './checkout-plane'
+import type { HarnessShellResult } from '@contrast/harness/shell'
+
+// a checkout is 15k files on this repo, so seeding is batched by BYTES rather
+// than by count: one request carrying every file would be a single multi-
+// hundred-megabyte body, and one request per file would be 15k round trips.
+const SEED_BATCH_BYTES = 4 * 1024 * 1024
+// base64 costs 4 bytes for every 3, and a request carries the encoded size.
+const BASE64_OVERHEAD = 4 / 3
+
+export interface CloudBoxSession {
+  readonly cwd: string
+  exec(command: string): Promise<HarnessShellResult>
+  close(): void
+}
+
+export class CloudBoxError extends Error {}
+
+function endpointOf(base: string, name: string, verb: string): string {
+  return `${base.replace(/\/+$/, '')}/v1/boxes/${encodeURIComponent(name)}/${verb}`
+}
+
+async function boxFetch(
+  base: string,
+  name: string,
+  verb: string,
+  token: string | null,
+  body?: unknown,
+): Promise<Record<string, unknown>> {
+  const headers: Record<string, string> = { 'content-type': 'application/json' }
+  if (token) headers.authorization = `Bearer ${token}`
+  let response: Response
+  try {
+    response = await fetch(endpointOf(base, name, verb), {
+      method: body === undefined ? 'GET' : 'POST',
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+  } catch (error) {
+    throw new CloudBoxError(
+      `could not reach the box service at ${base}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+  }
+  const text = await response.text()
+  const parsed = text ? JSON.parse(text) : {}
+  if (!response.ok) {
+    throw new CloudBoxError(
+      String(parsed.error ?? `box ${verb} failed (${response.status})`),
+    )
+  }
+  return parsed
+}
+
+/**
+ * create the box and copy this checkout into it.
+ *
+ * `apiKey` is the ACCOUNT's key, which the box service forwards to
+ * /v1/rnx/sessions to authenticate the caller and start the session that pays
+ * for the box. the box's own token comes back minted by the box; a caller does
+ * not choose it.
+ */
+export async function createCloudBox(options: {
+  endpoint: string
+  name: string
+  apiKey: string
+  plane: CheckoutFilePlane
+  onProgress?: (seeded: number, total: number) => void
+}): Promise<{ files: number; token: string; sessionId: string }> {
+  const { endpoint, name, apiKey, plane } = options
+  const created = await boxFetch(endpoint, name, 'create', apiKey, { name })
+  const token = String(created.token ?? '')
+  if (!token) throw new CloudBoxError('the box service returned no access token')
+
+  const paths = [...plane.index().keys()].sort()
+  let batch: [string, string][] = []
+  let batchBytes = 0
+  let seeded = 0
+
+  const flush = async () => {
+    if (batch.length === 0) return
+    await boxFetch(endpoint, name, 'seed', token, { files: batch })
+    seeded += batch.length
+    options.onProgress?.(seeded, paths.length)
+    batch = []
+    batchBytes = 0
+  }
+
+  for (const path of paths) {
+    const bytes = await plane.readBytes(path)
+    batch.push([path, Buffer.from(bytes).toString('base64')])
+    batchBytes += bytes.byteLength * BASE64_OVERHEAD
+    if (batchBytes >= SEED_BATCH_BYTES) await flush()
+  }
+  await flush()
+
+  const status = await boxFetch(endpoint, name, 'status', token)
+  return {
+    files: Number(status.files ?? 0),
+    token,
+    sessionId: String(status.sessionId ?? ''),
+  }
+}
+
+/**
+ * stop a box, or stop and wipe it.
+ *
+ * takes the ACCOUNT key, not the box token: it ends the session the account is
+ * billed for, which the box deliberately cannot do on its own.
+ */
+export async function stopCloudBox(options: {
+  endpoint: string
+  name: string
+  apiKey: string
+  purge?: boolean
+}): Promise<Record<string, unknown>> {
+  return boxFetch(
+    options.endpoint,
+    options.name,
+    options.purge ? 'delete' : 'stop',
+    options.apiKey,
+    {},
+  )
+}
+
+/**
+ * the account's running boxes, from the session meter rather than from the box
+ * service. the meter already knows what this account is running and what it
+ * cost, so a second per-account index of boxes would be a second answer to the
+ * same question, free to drift.
+ */
+export async function listCloudBoxes(options: {
+  apiOrigin: string
+  apiKey: string
+}): Promise<{ id: string; name: string | null; startedAt: string; meteredMs: number }[]> {
+  const response = await fetch(
+    `${options.apiOrigin.replace(/\/+$/, '')}/v1/rnx/sessions`,
+    {
+      headers: { authorization: `Bearer ${options.apiKey}` },
+    },
+  )
+  const text = await response.text()
+  const parsed = text ? JSON.parse(text) : {}
+  if (!response.ok) {
+    throw new CloudBoxError(
+      String(parsed.message ?? parsed.error ?? 'could not list boxes'),
+    )
+  }
+  const sessions = Array.isArray(parsed.sessions) ? parsed.sessions : []
+  return sessions
+    .filter((session: { kind?: string }) => session.kind === 'box')
+    .map((session: Record<string, unknown>) => ({
+      id: String(session.id),
+      name: typeof session.name === 'string' ? session.name : null,
+      startedAt: String(session.startedAt ?? ''),
+      meteredMs: Number(session.meteredMs ?? 0),
+    }))
+}
+
+/**
+ * bank the wall clock while a box is open.
+ *
+ * the box holds no account credential and so cannot heartbeat for itself; the
+ * client that is actually using it does. when this process dies the heartbeats
+ * stop and the site's stale sweep closes the session at the last one, which is
+ * why there is no second idle timer in the box.
+ */
+export function heartbeatSession(options: {
+  apiOrigin: string
+  apiKey: string
+  sessionId: string
+  everyMs?: number
+}): { stop: () => void } {
+  const url = `${options.apiOrigin.replace(/\/+$/, '')}/v1/rnx/sessions/${encodeURIComponent(
+    options.sessionId,
+  )}`
+  const timer = setInterval(() => {
+    void fetch(url, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${options.apiKey}` },
+    }).catch(() => {
+      // a missed heartbeat is not an error worth interrupting a shell for.
+      // the sweep closes the session at the last one that landed.
+    })
+  }, options.everyMs ?? 60_000)
+  // do not hold the process open just to keep billing alive
+  timer.unref?.()
+  return { stop: () => clearInterval(timer) }
+}
+
+/** open the box's socket and return a session the REPL can drive. */
+export async function connectCloudBox(options: {
+  endpoint: string
+  name: string
+  token: string
+}): Promise<CloudBoxSession> {
+  const { endpoint, name, token } = options
+  const url = endpointOf(endpoint, name, 'connect').replace(/^http/, 'ws')
+  // as a subprotocol, not a header. a browser cannot set a header on a
+  // WebSocket, and the box takes the token one way rather than one way per
+  // kind of caller.
+  const socket = new WebSocket(url, [`rnx-box-token.${token}`])
+
+  // a persistent handler, installed before the handshake can fail. ws emits
+  // 'error' again after a refused upgrade, and a `once` listener consumed by
+  // the rejection leaves that second emit unhandled, which crashes the
+  // process rather than failing the command.
+  let socketError: string | null = null
+  socket.on('error', (error) => {
+    socketError = error.message
+  })
+  await new Promise<void>((resolve, reject) => {
+    socket.once('open', resolve)
+    socket.once('error', (error) => {
+      socket.close()
+      reject(error)
+    })
+  }).catch(async (error: unknown) => {
+    // ws's handshake error text is runtime-specific: node says "Unexpected
+    // server response: 401" and bun says "Expected 101 status code" with no
+    // status at all. so ask the service itself why, over plain HTTP, and
+    // report THAT. this runs only on the failure path.
+    const reason = await boxFetch(endpoint, name, 'status', token).then(
+      () => null,
+      (failure: unknown) =>
+        failure instanceof Error ? failure.message : String(failure),
+    )
+    const fallback = error instanceof Error ? error.message : String(error)
+    throw new CloudBoxError(`could not open the box shell: ${reason ?? fallback}`)
+  })
+
+  let nextId = 0
+  const waiting = new Map<number, (reply: Record<string, unknown>) => void>()
+  socket.on('message', (data) => {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(String(data))
+    } catch {
+      return
+    }
+    if (typeof parsed !== 'object' || parsed === null) return
+    const reply = parsed as Record<string, unknown>
+    const resolve = waiting.get(Number(reply.id))
+    if (!resolve) return
+    waiting.delete(Number(reply.id))
+    resolve(reply)
+  })
+
+  // the socket dying mid-command must fail the command rather than hang the
+  // prompt forever, so every waiter is settled when it closes.
+  let closedReason: string | null = null
+  const settleAll = (reason: string) => {
+    closedReason = reason
+    for (const [id, resolve] of waiting) resolve({ id, error: reason })
+    waiting.clear()
+  }
+  socket.on('close', () => settleAll(socketError ?? 'the box closed the connection'))
+  socket.on('error', (error) => settleAll(error.message))
+
+  let cwd = '/project'
+  return {
+    get cwd() {
+      return cwd
+    },
+    async exec(command: string): Promise<HarnessShellResult> {
+      if (closedReason) throw new CloudBoxError(closedReason)
+      const id = nextId++
+      const reply = await new Promise<Record<string, unknown>>((resolve) => {
+        waiting.set(id, resolve)
+        socket.send(JSON.stringify({ type: 'shell:exec', id, command }))
+      })
+      if (reply.error) throw new CloudBoxError(String(reply.error))
+      const result = reply.result as HarnessShellResult
+      if (result.cwd) cwd = result.cwd
+      return result
+    },
+    close: () => socket.close(),
+  }
+}

package/cli/commands/box/plane-share.ts

@@ -0,0 +1,208 @@
+// a local box authorizing its own checkout for browser access.
+//
+// the bridge daemon serves the `plane:*` envelope, but it will not open a root
+// nobody has authorized, because a WebSocket to 127.0.0.1 is not subject to
+// CORS and any page the user visits can open one. so the box registers its
+// root and holds the socket for as long as it runs; when the box exits, the
+// registration goes with it and the tab loses reach.
+//
+// THIS NEVER BLOCKS THE BOX. an earlier version awaited the socket before
+// printing the prompt and cost 1450ms of start time on every box, because a
+// daemon built before `plane:*` existed accepts the socket, ignores the
+// message, and never replies, so the client sat on its timeout. a box that
+// cannot share its plane is a box with one capability missing, not a box that
+// starts slowly.
+//
+// IT ALSO REFUSES TO GUESS A PORT. when no lockfile claims a bridge,
+// resolveBridgeWorld reports source 'default' and hands back
+// DEFAULT_SOOTSIM_BRIDGE_PORT, which on a machine running a real daemon is
+// that daemon. registering there would attach a test's or a benchmark's box to
+// another session's daemon, which is exactly what a private SOOTSIM_HOME
+// exists to prevent. so a guessed port is refused by name.
+
+import WebSocket from 'ws'
+import { bridgeWsUrl, resolveBridgeWorld } from '../../ws-bridge'
+
+const REGISTER_TIMEOUT_MS = 1500
+
+export interface PlaneShare {
+  /**
+   * resolves when the daemon has accepted the root, or with a reason it did
+   * not. `holders` is how many boxes now hold this checkout, including this
+   * one, so more than one means another box is writing the same tree.
+   */
+  readonly settled: Promise<{ port: number; holders: number } | { declined: string }>
+  close(): void
+}
+
+function target(
+  explicitPort: number | undefined,
+): { port: number } | { declined: string } {
+  if (explicitPort) return { port: explicitPort }
+  const world = resolveBridgeWorld()
+  if (world.source === 'default') {
+    return {
+      declined:
+        'no daemon or dev bridge claims a port, and the default is another session’s daemon on a shared machine',
+    }
+  }
+  return { port: world.bridgePort }
+}
+
+/**
+ * register `root` with the bridge daemon in the background. returns
+ * immediately; the box never waits on it.
+ */
+export function sharePlane(root: string, opts: { port?: number } = {}): PlaneShare {
+  const chosen = target(opts.port)
+  if ('declined' in chosen) {
+    return { settled: Promise.resolve(chosen), close: () => {} }
+  }
+
+  const port = chosen.port
+  let socket: WebSocket | null = null
+  let closed = false
+
+  const settled = new Promise<{ port: number; holders: number } | { declined: string }>(
+    (resolve) => {
+      let done = false
+      const finish = (
+        value: { port: number; holders: number } | { declined: string },
+      ) => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        resolve(value)
+      }
+
+      const timer = setTimeout(() => {
+        // an older daemon accepts the socket and ignores plane:* entirely, so
+        // silence is the expected shape of "not supported" rather than a fault.
+        socket?.close()
+        finish({ declined: `bridge on port ${port} did not answer plane:register` })
+      }, REGISTER_TIMEOUT_MS)
+
+      try {
+        socket = new WebSocket(bridgeWsUrl(port))
+      } catch (error) {
+        finish({ declined: error instanceof Error ? error.message : String(error) })
+        return
+      }
+      if (closed) {
+        socket.close()
+        finish({ declined: 'box exited before the plane registered' })
+        return
+      }
+
+      socket.on('error', (error) => finish({ declined: error.message }))
+      socket.on('close', () => finish({ declined: `bridge on port ${port} closed` }))
+      socket.on('open', () => {
+        // node sends no Origin, so this socket is already cli-role. a browser
+        // client has to send bridge:hello to be corrected off the provisional
+        // sim role; see plans/rnx-cloud/transport-decision.md.
+        socket?.send(JSON.stringify({ type: 'plane:register', id: 'register', root }))
+      })
+      socket.on('message', (data) => {
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(String(data))
+        } catch {
+          return
+        }
+        if (typeof parsed !== 'object' || parsed === null) return
+        const reply: Record<string, unknown> = { ...parsed }
+        if (reply.id !== 'register') return
+        if (reply.error) {
+          socket?.close()
+          finish({ declined: String(reply.error) })
+          return
+        }
+        // the daemon nests its payload under `result`; reading holders off the
+        // envelope silently reported 1 forever, which is the exact silence this
+        // field exists to remove.
+        const result = (reply.result ?? {}) as Record<string, unknown>
+        finish({ port, holders: Number(result.holders ?? 1) })
+      })
+    },
+  )
+
+  return {
+    settled,
+    close: () => {
+      closed = true
+      try {
+        socket?.close()
+      } catch {}
+    },
+  }
+}
+
+/**
+ * How many boxes hold `root` right now, without registering anything.
+ *
+ * `plane:register` cannot answer this: registering is what makes a root
+ * reachable over a loopback socket, so a readiness probe that asked with it
+ * would both authorize the root and count itself in the answer.
+ */
+export async function planeStatus(
+  root: string,
+  opts: { port?: number } = {},
+): Promise<{ holders: number; registered: boolean } | { declined: string }> {
+  const chosen = target(opts.port)
+  if ('declined' in chosen) return chosen
+  const port = chosen.port
+
+  return new Promise((resolve) => {
+    let done = false
+    let socket: WebSocket | null = null
+    const finish = (
+      value: { holders: number; registered: boolean } | { declined: string },
+    ) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      try {
+        socket?.close()
+      } catch {}
+      resolve(value)
+    }
+    const timer = setTimeout(
+      () => finish({ declined: `bridge on port ${port} did not answer plane:status` }),
+      REGISTER_TIMEOUT_MS,
+    )
+
+    try {
+      socket = new WebSocket(bridgeWsUrl(port))
+    } catch (error) {
+      finish({ declined: error instanceof Error ? error.message : String(error) })
+      return
+    }
+    socket.on('error', (error) => finish({ declined: error.message }))
+    socket.on('close', () => finish({ declined: `bridge on port ${port} closed` }))
+    socket.on('open', () => {
+      socket?.send(JSON.stringify({ type: 'plane:status', id: 'status', root }))
+    })
+    socket.on('message', (data) => {
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(String(data))
+      } catch {
+        return
+      }
+      if (typeof parsed !== 'object' || parsed === null) return
+      const reply: Record<string, unknown> = { ...parsed }
+      if (reply.id !== 'status') return
+      if (reply.error) {
+        finish({ declined: String(reply.error) })
+        return
+      }
+      // the daemon nests its payload under `result`, the same shape
+      // plane:register answers in.
+      const result = (reply.result ?? {}) as Record<string, unknown>
+      finish({
+        holders: Number(result.holders ?? 0),
+        registered: Boolean(result.registered),
+      })
+    })
+  })
+}

package/cli/commands/box/rnx-command.ts

@@ -8,8 +8,8 @@
 
 import { spawn } from 'node:child_process'
 import path from 'node:path'
-import { defineCommand, type CustomCommand } from '@contrast/harness'
-import { PROJECT_MOUNT } from '@contrast/harness'
+import { defineCommand, type CustomCommand } from '@contrast/harness/shell'
+import { PROJECT_MOUNT } from '@contrast/harness/shell'
 import { rnxPublicBrand } from '../../../src/public-brand'
 import { RNX_PLACEMENT_ENV } from '../../ws-bridge'