@mentra/engine 3.2.0-dev.221 → 3.2.0-dev.222

package/src/services/SoftapCleanupBarrier.ts

@@ -0,0 +1,72 @@
+/**
+ * The wait a new SoftAP call does on the previous one's cleanup.
+ *
+ * Starting a call, stopping it before it finishes, and starting it again used to report "Cannot
+ * start glasses hotspot" and then fail the scoped join with the SSID missing from the scan. Both
+ * symptoms are the same cause: the second attempt raised a hotspot while the first attempt's
+ * `setHotspotState(false)` was still in flight, so the teardown of call N landed on call N+1.
+ *
+ * The rule this encodes is that the barrier is the *only* thing that decides when the next call
+ * may proceed, and it opens on evidence rather than on a clock. A timeout that says "long enough,
+ * probably safe" reintroduces exactly the race it was added to prevent, so there is deliberately
+ * no deadline here: a cleanup that never finishes holds the next call back forever, visibly,
+ * which is a bug someone can see and fix. The only thing time is used for is deciding whether the
+ * wait is worth mentioning — the common restart clears in a microtask, and a status line that
+ * flashed on every Start would teach the wearer to ignore the one time it mattered.
+ */
+
+import {softapTrace} from "../utils/softapTrace"
+
+export interface CleanupBarrierOptions {
+  /** Opens when the previous attempt's teardown *and* its in-flight join body have both finished. */
+  settled: Promise<void>
+  /** Already open: the caller can skip the wait, and the narration, entirely. */
+  settledDone: boolean
+  /** Told to the wearer only if the wait outlasts {@link narrateAfterMs}. */
+  narrate: (detail: string) => void
+  narrateAfterMs: number
+  /** Injectable for tests; a real timer everywhere else. */
+  delay?: (ms: number) => Promise<void>
+  /**
+   * Which attempt is being held, and which one it is held behind. Diagnostics only, and separate
+   * from the trace id because the barrier runs before the transport mints one: a restart that was
+   * delayed here is otherwise indistinguishable in the log from one that started slowly.
+   */
+  attempt?: number
+  waitingFor?: string
+}
+
+export const CLEANUP_BARRIER_COPY = "Still cleaning up the last call…"
+
+/**
+ * Resolves once the previous attempt has genuinely finished, narrating if the wait is noticeable.
+ *
+ * Returns whether the wearer was told, so a caller can assert on it and a log can record that the
+ * restart was held rather than instant.
+ */
+export async function awaitCleanupBarrier(options: CleanupBarrierOptions): Promise<{narrated: boolean}> {
+  const trace = {attempt: options.attempt ?? "unknown", waitingFor: options.waitingFor ?? "unknown"}
+  if (options.settledDone) {
+    softapTrace("softap_cleanup_barrier_open", {...trace, waitedMs: 0, reason: "already settled"})
+    return {narrated: false}
+  }
+  const startedAt = Date.now()
+  // Logged on entry as well as on exit, because the interesting case is the one where the exit
+  // line never arrives: a wait that is still open is only visible as an entry with nothing after it.
+  softapTrace("softap_cleanup_barrier_wait", trace)
+  const delay = options.delay ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+  const promptly = await Promise.race([
+    options.settled.then(() => true),
+    delay(options.narrateAfterMs).then(() => false),
+  ])
+  if (promptly) {
+    softapTrace("softap_cleanup_barrier_open", {...trace, waitedMs: Date.now() - startedAt, narrated: false})
+    return {narrated: false}
+  }
+  options.narrate(CLEANUP_BARRIER_COPY)
+  // The race decided what to say. It does not decide whether to proceed: that is this line, and
+  // it has no escape.
+  await options.settled
+  softapTrace("softap_cleanup_barrier_open", {...trace, waitedMs: Date.now() - startedAt, narrated: true})
+  return {narrated: true}
+}

package/src/utils/pcm16.ts

@@ -0,0 +1,93 @@
+/**
+ * Level statistics for 16-bit little-endian mono PCM, as delivered by `mic_pcm`.
+ *
+ * Shared by the call uplink and the dev mic probe so both report the same number: a soak that
+ * says `meanAbs=40` in one log and `meanAbs=40` in the other is measuring the same thing.
+ */
+
+/**
+ * Hermes / the Expo bridge delivers `mic_pcm.pcm` as a Uint8Array, not an ArrayBuffer.
+ * `new DataView(uint8Array)` throws `buffer must be an ArrayBuffer` — that is the redbox
+ * attributed to whatever screen happens to be up (wifi scan, home, …).
+ */
+export function pcmDataView(frame: unknown): DataView | null {
+  if (frame instanceof ArrayBuffer) {
+    return new DataView(frame)
+  }
+  if (ArrayBuffer.isView(frame)) {
+    try {
+      return new DataView(frame.buffer, frame.byteOffset, frame.byteLength)
+    } catch {
+      const copy = Uint8Array.from(frame as unknown as ArrayLike<number>)
+      return new DataView(copy.buffer)
+    }
+  }
+  if (Array.isArray(frame)) {
+    const copy = Uint8Array.from(frame)
+    return new DataView(copy.buffer)
+  }
+  return null
+}
+
+export type Pcm16Level = {
+  /** Mean absolute sample value (16-bit scale). ~30–60 is a quiet room on Mentra Live LC3. */
+  meanAbs: number
+  /** Largest absolute sample. */
+  peak: number
+  /** Samples counted. */
+  samples: number
+}
+
+/** Level statistics over a batch of PCM16 frames. Unreadable frames are skipped, never thrown on. */
+export function summarizePcm16(frames: unknown[]): Pcm16Level {
+  let sum = 0
+  let peak = 0
+  let samples = 0
+  for (const frame of frames) {
+    const view = pcmDataView(frame)
+    if (!view) continue
+    const n = Math.floor(view.byteLength / 2)
+    for (let i = 0; i < n; i++) {
+      const v = Math.abs(view.getInt16(i * 2, true))
+      sum += v
+      if (v > peak) peak = v
+    }
+    samples += n
+  }
+  return {meanAbs: samples ? Math.round(sum / samples) : 0, peak, samples}
+}
+
+/**
+ * Incremental accumulator for the same statistics, for hot paths that see one frame at a time
+ * and report once a window (the call uplink logs every 5 s at 20 frames/s).
+ */
+export class Pcm16LevelMeter {
+  private sum = 0
+  private peakValue = 0
+  private count = 0
+
+  add(frame: unknown): void {
+    const view = pcmDataView(frame)
+    if (!view) return
+    const n = Math.floor(view.byteLength / 2)
+    for (let i = 0; i < n; i++) {
+      const v = Math.abs(view.getInt16(i * 2, true))
+      this.sum += v
+      if (v > this.peakValue) this.peakValue = v
+    }
+    this.count += n
+  }
+
+  /** Read the window and start a new one. */
+  take(): Pcm16Level {
+    const level = {
+      meanAbs: this.count ? Math.round(this.sum / this.count) : 0,
+      peak: this.peakValue,
+      samples: this.count,
+    }
+    this.sum = 0
+    this.peakValue = 0
+    this.count = 0
+    return level
+  }
+}

package/src/utils/softapTrace.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Correlated stage logging for the SoftAP calling pipeline (host side).
+ *
+ * TEMPORARY DIAGNOSTIC. Every line carries the literal `SOFTAP_TRACE` marker so a single
+ * `rg -n 'SOFTAP_TRACE'` finds all of them at cleanup time. Set `SOFTAP_TRACE_ENABLED` to
+ * false to mute the layer for a release without deleting call sites.
+ *
+ * The `phase=` shape matches the `[AcsMeeting] phase=...` convention already used by
+ * AcsMeetingService, so existing log tooling keeps parsing it.
+ *
+ * `traceId` is minted here when the hotspot request starts and travels to the glasses in
+ * `start_stream`. Both devices stamp the same id on every line, which is the only way to
+ * correlate two logs whose clocks were never synchronised.
+ */
+
+/** Master switch. Flip to false to mute the trace without removing call sites. */
+export const SOFTAP_TRACE_ENABLED = true
+
+/** Grep marker. Never build this by concatenation — a single grep must be exhaustive. */
+export const SOFTAP_TRACE_MARKER = "SOFTAP_TRACE"
+
+const REDACTED = "<redacted>"
+
+/** Keys whose values must never reach the log. Matched case-insensitively as substrings. */
+const SENSITIVE_KEYS = [
+  "password",
+  "passwd",
+  "passphrase",
+  "psk",
+  "token",
+  "secret",
+  "credential",
+  "authorization",
+  "bearer",
+  "meetingurl",
+]
+
+let traceId = ""
+let originMs = 0
+let lastStage = ""
+
+/** Mint a trace id and reset the elapsed-time origin. Called when the hotspot request starts. */
+export function beginSoftapTrace(id: string = newSoftapTraceId()): string {
+  traceId = id
+  originMs = Date.now()
+  lastStage = ""
+  return id
+}
+
+export function resetSoftapTrace(): void {
+  traceId = ""
+  originMs = 0
+  lastStage = ""
+}
+
+export function softapTraceId(): string {
+  return traceId
+}
+
+/** Last stage logged; use as failure context when reporting an error. */
+export function softapLastStage(): string {
+  return lastStage
+}
+
+export function newSoftapTraceId(): string {
+  return Math.floor(Math.random() * 0xffffffff).toString(16)
+}
+
+function isSensitive(key: string): boolean {
+  const lower = key.toLowerCase()
+  return SENSITIVE_KEYS.some((sensitive) => lower.includes(sensitive))
+}
+
+/** Drop `?query`, `#fragment`, and `user:pass@` from anything URL-shaped. */
+function stripUrlSecrets(text: string): string {
+  const schemeIndex = text.indexOf("://")
+  if (schemeIndex < 0) return text
+
+  let result = text
+  const query = result.indexOf("?")
+  if (query >= 0) result = `${result.slice(0, query)}?${REDACTED}`
+  const fragment = result.indexOf("#")
+  if (fragment >= 0) result = result.slice(0, fragment)
+
+  const at = result.indexOf("@", schemeIndex + 3)
+  if (at >= 0) {
+    result = `${result.slice(0, schemeIndex + 3)}${REDACTED}@${result.slice(at + 1)}`
+  }
+  return result
+}
+
+/**
+ * Redact secrets outright and strip query strings from URLs. The local WHIP URL is genuinely
+ * useful in a trace, but a URL carrying a watch token is not, so query and userinfo go.
+ */
+export function sanitizeSoftapField(key: string, value: unknown): unknown {
+  if (isSensitive(key)) return REDACTED
+  if (typeof value === "string") return stripUrlSecrets(value)
+  return value
+}
+
+/** Apply {@link sanitizeSoftapField} across an object, leaving non-string values alone. */
+export function sanitizeSoftapData(data: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(data)) {
+    result[key] = sanitizeSoftapField(key, value)
+  }
+  return result
+}
+
+/** Build the log head. Exported for tests. */
+export function formatSoftapTrace(id: string, stage: string, elapsedMs: number): string {
+  const head = id ? `[${SOFTAP_TRACE_MARKER}] traceId=${id} phase=${stage}` : `[${SOFTAP_TRACE_MARKER}] phase=${stage}`
+  return `${head} elapsedMs=${elapsedMs}`
+}
+
+/** Log one pipeline stage transition. */
+export function softapTrace(stage: string, data?: Record<string, unknown>): void {
+  if (!SOFTAP_TRACE_ENABLED) return
+  lastStage = stage
+  const elapsedMs = originMs === 0 ? 0 : Date.now() - originMs
+  const head = formatSoftapTrace(traceId, stage, elapsedMs)
+  if (data) console.log(head, sanitizeSoftapData(data))
+  else console.log(head)
+}
+
+/** Warn-level variant so genuine failures survive a log level filter. */
+export function softapTraceFailure(stage: string, data?: Record<string, unknown>): void {
+  if (!SOFTAP_TRACE_ENABLED) return
+  const elapsedMs = originMs === 0 ? 0 : Date.now() - originMs
+  const head = formatSoftapTrace(traceId, stage, elapsedMs)
+  console.warn(head, sanitizeSoftapData({...(data ?? {}), afterStage: lastStage}))
+}