@bun-native/runtime 0.0.0-stage → 0.33.1

package/src/installation.ts

@@ -0,0 +1,46 @@
+import { writeFile } from 'node:fs/promises'
+
+/**
+ * The installed release this process was started as, from the variables that the verifying
+ * launcher sets (see docs/update-lifecycle.md). Undefined when the application was not started
+ * by that launcher, such as during development.
+ */
+export interface InstalledRelease {
+  /** The preserved per-user data directory, kept across updates and rollbacks. */
+  readonly dataDirectory: string
+  /** The installation root. */
+  readonly root: string
+  /** The release's manifest SHA-256. */
+  readonly release: string
+  /** True while this release awaits its health check; see `reportHealthy`. */
+  readonly healthPending: boolean
+}
+
+const sha256 = /^[0-9a-f]{64}$/
+
+export function installedRelease(): InstalledRelease | undefined {
+  const { BUN_NATIVE_DATA_DIR, BUN_NATIVE_INSTALL_ROOT, BUN_NATIVE_RELEASE } = process.env
+  if (!BUN_NATIVE_DATA_DIR || !BUN_NATIVE_INSTALL_ROOT || !sha256.test(BUN_NATIVE_RELEASE ?? ''))
+    return undefined
+  return {
+    dataDirectory: BUN_NATIVE_DATA_DIR,
+    root: BUN_NATIVE_INSTALL_ROOT,
+    release: BUN_NATIVE_RELEASE!,
+    healthPending: Boolean(process.env['BUN_NATIVE_HEALTH_FILE']),
+  }
+}
+
+/**
+ * Report that this release passed the application's own health check, such as a first
+ * window opening with its data loaded. The launcher then confirms the release, so a later
+ * start no longer counts toward the automatic rollback. Returns false when no health check
+ * is pending. Call it once the application is known to work; an update that never reports
+ * is rolled back after its allowed starts.
+ */
+export async function reportHealthy(): Promise<boolean> {
+  const installed = installedRelease()
+  const file = process.env['BUN_NATIVE_HEALTH_FILE']
+  if (!installed?.healthPending || !file) return false
+  await writeFile(file, installed.release + '\n')
+  return true
+}

package/src/startup-trace.ts

@@ -0,0 +1,105 @@
+import type { Command, NativeEvent } from '@bun-native/protocol'
+import { appendFileSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
+import { redactDiagnostic } from './exit-diagnostic.ts'
+
+const MAX_RECORDS = 256
+
+/** Explicit diagnostic mode only. This is not a request scheduler or transport proxy. */
+export class StartupTrace {
+  private readonly started = process.hrtime.bigint()
+  private records = 0
+  private unavailable = false
+
+  private constructor(
+    private readonly path: string,
+    private readonly nonce: string
+  ) {}
+
+  static fromEnvironment(): StartupTrace | undefined {
+    if (process.env['BUN_NATIVE_STARTUP_TRACE'] !== '1') return
+    const path = process.env['BUN_NATIVE_EVIDENCE_LOG']
+    const nonce = process.env['BUN_NATIVE_EVIDENCE_NONCE']
+    if (
+      !path ||
+      !isAbsolute(path) ||
+      !nonce ||
+      Buffer.byteLength(nonce) > 128 ||
+      [...nonce].some((character) => {
+        const code = character.charCodeAt(0)
+        return code < 32 || (code >= 127 && code <= 159)
+      })
+    )
+      throw new Error('Native startup tracing requires an absolute evidence path and valid nonce')
+    return new StartupTrace(path, nonce)
+  }
+
+  request(phase: string, command: Command, hostPid: number): void {
+    this.write(phase, {
+      host_pid: hostPid,
+      request_id: command.id,
+      command: command.type,
+      ...('window_id' in command ? { window_id: command.window_id } : {}),
+    })
+  }
+
+  response(event: NativeEvent, hostPid: number): void {
+    if (!('id' in event)) return
+    this.write('response_received', {
+      host_pid: hostPid,
+      request_id: event.id,
+      response: event.type,
+    })
+  }
+
+  /** `stderr` is the bounded capture; it is recorded redacted, like exit diagnostics. */
+  failure(error: Error, stderr: string, clipped: boolean, hostPid: number): void {
+    this.write(
+      'transport_failed',
+      {
+        host_pid: hostPid,
+        error: error.message.slice(-1_024),
+        stderr_tail: redactDiagnostic(stderr, clipped, process.env),
+      },
+      true
+    )
+  }
+
+  finished(exitCode: number | null, stderr: string, clipped: boolean, hostPid: number): void {
+    this.write(
+      'transport_finished',
+      {
+        host_pid: hostPid,
+        exit_code: exitCode,
+        stderr_tail: redactDiagnostic(stderr, clipped, process.env),
+      },
+      true
+    )
+  }
+
+  private write(phase: string, fields: Record<string, unknown>, terminal = false): void {
+    if (this.unavailable || (!terminal && this.records >= MAX_RECORDS)) return
+    if (!terminal && this.records === MAX_RECORDS - 1) {
+      phase = 'record_limit'
+      fields = { host_pid: fields['host_pid'], maximum_records: MAX_RECORDS }
+    }
+    const record = {
+      nonce: this.nonce,
+      stage: 'startup-diagnostic',
+      source: 'transport',
+      pid: process.pid,
+      clock: 'process_monotonic_relative',
+      elapsed_ns: String(process.hrtime.bigint() - this.started),
+      index: ++this.records,
+      phase,
+      ...fields,
+    }
+    try {
+      appendFileSync(this.path, JSON.stringify(record) + '\n', { mode: 0o600 })
+    } catch {
+      this.unavailable = true
+      // Do not replace the original transport result with a diagnostic I/O error.
+      console.error('Bun Native startup trace unavailable; evidence file could not be appended')
+    }
+  }
+}