@hienlh/ppm 0.23.11 → 0.23.12

package/src/services/android/android-input.ts

@@ -0,0 +1,129 @@
+/**
+ * Turning viewer gestures into emulator input.
+ *
+ * The one rule that shapes this file: **`sendKey.text` carries printable ASCII [32,127) and
+ * nothing else.** Measured in Phase 0 — `"café"` arrives as `"caf"`, and Vietnamese, emoji and
+ * CJK vanish entirely, with no error and no log. So text is split: ASCII goes through `text`,
+ * and everything else goes through the clipboard plus a paste combo, which was verified to
+ * carry `"Tiếng Việt 😀"` intact into the guest.
+ */
+import { unaryCall, type EmulatorChannel } from "./android-grpc.ts";
+import type { AndroidTouchPoint } from "../../shared/android-protocol.ts";
+
+/** The emulator accepts at most this many simultaneous contacts. */
+export const MAX_TOUCH_POINTS = 10;
+
+export function isInjectableAscii(text: string): boolean {
+  for (const ch of text) {
+    const code = ch.codePointAt(0)!;
+    if (code < 32 || code >= 127) return false;
+  }
+  return true;
+}
+
+/**
+ * Send one touch update.
+ *
+ * `pressure: 0` is how a finger is released, and it is mandatory: the proto states an identifier
+ * that never sees zero is not unregistered. The emulator does expire a slot on its own, but only
+ * after 120 seconds — far too long to rely on, which is why the session has its own release path.
+ */
+export async function sendTouch(channel: EmulatorChannel, touches: AndroidTouchPoint[]): Promise<void> {
+  const clamped = touches.slice(0, MAX_TOUCH_POINTS).map((t) => ({
+    x: Math.round(t.x),
+    y: Math.round(t.y),
+    identifier: Math.max(0, Math.round(t.id)),
+    pressure: t.pressure > 0 ? Math.max(1, Math.round(t.pressure)) : 0,
+  }));
+  await unaryCall(channel, "sendTouch", { touches: clamped }, 2000);
+}
+
+/** Release every contact. Called on blur, tab hide, lost control and disconnect. */
+export async function releaseAllTouches(channel: EmulatorChannel): Promise<void> {
+  const release = Array.from({ length: MAX_TOUCH_POINTS }, (_, i) => ({
+    x: 0, y: 0, identifier: i, pressure: 0,
+  }));
+  await unaryCall(channel, "sendTouch", { touches: release }, 2000);
+}
+
+/** The w3c `KeyboardEvent.key` values the emulator maps to Android's own buttons. */
+const HARDWARE_KEYS = {
+  home: "GoHome",
+  back: "GoBack",
+  recent: "AppSwitch",
+  power: "Power",
+  "volume-up": "AudioVolumeUp",
+  "volume-down": "AudioVolumeDown",
+} as const;
+
+export type HardwareKey = keyof typeof HARDWARE_KEYS;
+
+export async function sendHardwareKey(channel: EmulatorChannel, key: HardwareKey): Promise<void> {
+  await unaryCall(channel, "sendKey", { key: HARDWARE_KEYS[key], eventType: "keypress" }, 2000);
+}
+
+/** `key` takes the browser's own `KeyboardEvent.key` value — the proto follows the w3c list. */
+export async function sendKey(
+  channel: EmulatorChannel,
+  key: string,
+  action: "down" | "up" | "press",
+): Promise<void> {
+  const eventType = action === "down" ? "keydown" : action === "up" ? "keyup" : "keypress";
+  await unaryCall(channel, "sendKey", { key, eventType }, 2000);
+}
+
+/** ASCII only — the caller must have checked. Anything else is silently dropped by the emulator. */
+export async function sendAsciiText(channel: EmulatorChannel, text: string): Promise<void> {
+  // The proto warns the keyboard buffer can be overrun by >1 KB at a time, and points at the
+  // clipboard for bulk text. Chunking keeps ordinary typing on this path either way.
+  for (let i = 0; i < text.length; i += 256) {
+    await unaryCall(channel, "sendKey", { text: text.slice(i, i + 256) }, 3000);
+  }
+}
+
+/**
+ * The path for anything not ASCII: put it on the guest clipboard and paste.
+ *
+ * Verified end to end in Phase 0 — `setClipboard` carried `"Tiếng Việt 😀"` into the guest
+ * exactly, confirmed both by reading it back and by Android's own paste suggestion rendering it.
+ */
+export async function pasteText(channel: EmulatorChannel, text: string): Promise<void> {
+  await unaryCall(channel, "setClipboard", { text }, 3000);
+  await unaryCall(channel, "sendKey", { key: "Control", eventType: "keydown" }, 2000);
+  await unaryCall(channel, "sendKey", { key: "v", eventType: "keypress" }, 2000);
+  await unaryCall(channel, "sendKey", { key: "Control", eventType: "keyup" }, 2000);
+}
+
+/** Send text by whichever path can actually carry it. */
+export async function sendText(channel: EmulatorChannel, text: string): Promise<"typed" | "pasted"> {
+  if (isInjectableAscii(text)) {
+    await sendAsciiText(channel, text);
+    return "typed";
+  }
+  await pasteText(channel, text);
+  return "pasted";
+}
+
+/**
+ * Rotate the guest.
+ *
+ * `setPhysicalModel` with `ROTATION` takes three angles in degrees as [x, y, z], and the proto's
+ * own `Rotation.SkinRotation` enum names what each z angle means: PORTRAIT 0, LANDSCAPE 90,
+ * REVERSE_PORTRAIT -180, REVERSE_LANDSCAPE -90. So 270 is sent as **-90**, not 270 — the proto
+ * documents the angle as being in [-180, 180] and a value outside it has no defined meaning.
+ *
+ * Nothing here tracks the resulting orientation: every screenshot frame carries the emulator's
+ * own `format.rotation`, which is the authority (see `android-video.ts`).
+ */
+export async function setRotation(channel: EmulatorChannel, degrees: 0 | 90 | 180 | 270): Promise<void> {
+  const z = degrees === 270 ? -90 : degrees;
+  await unaryCall(channel, "setPhysicalModel", {
+    target: "ROTATION",
+    value: { data: [0, 0, z] },
+  }, 3000);
+}
+
+export async function getClipboard(channel: EmulatorChannel): Promise<string> {
+  const res = await unaryCall(channel, "getClipboard", {}, 3000);
+  return typeof res?.text === "string" ? res.text : "";
+}

package/src/services/android/android-logcat.ts

@@ -0,0 +1,169 @@
+/**
+ * Per-device logcat: one gRPC stream, many watchers, a bounded ring buffer and nothing on disk.
+ *
+ * Plan §Phase 3 is specific about the shape: filter, pause, clear-view and a ring buffer, with
+ * **nothing written to the database**. So this holds a fixed number of entries in memory and
+ * hands a new watcher that backlog; filtering, pausing and clearing the view are the client's,
+ * because all three are about what one person is looking at, not about what the device said.
+ *
+ * ## `sort: Parsed` does not work, and fails by being silently empty
+ *
+ * The proto offers `LogMessage.LogType.Parsed`, which would deliver `LogcatEntry` records with
+ * level, tag, pid and tid already separated — exactly what this file wants. Measured against
+ * emulator **36.5.10.0** it is not implemented:
+ *
+ *  - `streamLogcat({sort: "Parsed"})` → **334 messages in 8 seconds, every one of them with an
+ *    empty `entries` list AND an empty `contents` string**, each echoing `sort: Text` back. Not
+ *    an error, not `UNIMPLEMENTED`: a busy stream of nothing, which reads exactly like a device
+ *    that is not logging.
+ *  - The same with the numeric enum value (`sort: 1`) — 57 empty messages in 8 seconds.
+ *  - `streamLogcat({})` — the default, `Text` — delivers the real log.
+ *  - The deprecated unary `getLogcat` answers **12 UNIMPLEMENTED** outright, so there is no
+ *    snapshot RPC either; the ring buffer is the only backlog there is.
+ *
+ * So the lines are parsed here. Two more measured details that shape the parser: each gRPC
+ * message carries **exactly one line** with **no trailing newline** (so nothing has to buffer a
+ * partial line across messages — though the split still handles it, since a future build
+ * batching lines would otherwise silently concatenate them into one entry), and the format is
+ * logcat's `threadtime`, which carries no year.
+ */
+import type { EmulatorChannel } from "./android-grpc.ts";
+import type { AndroidLogEntry, AndroidLogLevel } from "../../shared/android-protocol.ts";
+
+/** Enough to scroll back through a crash, far too little to be a storage decision. */
+export const LOGCAT_RING_SIZE = 2_000;
+
+/** logcat's one-letter levels. `A` is assert, which Android also calls FATAL. */
+const LEVELS: Record<string, AndroidLogLevel> = {
+  V: "verbose", D: "debug", I: "info", W: "warn", E: "error", F: "fatal", A: "fatal", S: "verbose",
+};
+
+/** `MM-DD HH:MM:SS.mmm  PID  TID L TAG: message` — logcat's `threadtime`, which is the default. */
+const THREADTIME = /^(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})\.(\d{3})\s+(\d+)\s+(\d+)\s+([A-Z])\s+([^:]*?)\s*:\s?(.*)$/;
+
+/**
+ * Turn one logcat line into an entry.
+ *
+ * A line that does not parse is **kept**, not dropped: it is a continuation of the line above
+ * (a stack trace written with embedded newlines) or a banner like `--------- beginning of main`,
+ * and losing either would quietly cut a crash in half. It gets no level and no tag rather than
+ * an invented one.
+ */
+export function parseLogcatLine(line: string, id: number, now = new Date()): AndroidLogEntry | null {
+  if (line.length === 0) return null;
+  const m = THREADTIME.exec(line);
+  if (!m) return { id, timestamp: now.getTime(), pid: 0, tid: 0, level: "verbose", tag: "", message: line };
+
+  const [, mo, day, hh, mm, ss, ms, pid, tid, level, tag, message] = m;
+  // threadtime has no year. Assume this one, and step back if that puts the line in the future
+  // by more than a day — which is what reading a December log on January 1st looks like.
+  let at = new Date(now.getFullYear(), Number(mo) - 1, Number(day), Number(hh), Number(mm), Number(ss), Number(ms));
+  if (at.getTime() - now.getTime() > 24 * 60 * 60_000) at = new Date(at.getTime() - 365 * 24 * 60 * 60_000);
+
+  return {
+    id,
+    timestamp: at.getTime(),
+    pid: Number(pid),
+    tid: Number(tid),
+    level: LEVELS[level!] ?? "verbose",
+    tag: tag ?? "",
+    message: message ?? "",
+  };
+}
+
+export type LogcatListener = (entries: AndroidLogEntry[]) => void;
+
+interface DeviceLogcat {
+  channel: EmulatorChannel;
+  /** The live gRPC stream, or null while nobody is watching. */
+  call: any;
+  ring: AndroidLogEntry[];
+  listeners: Set<LogcatListener>;
+  nextId: number;
+}
+
+const streams = new Map<string, DeviceLogcat>();
+
+/**
+ * Start watching a device's logcat.
+ *
+ * The channel is the caller's and is NOT closed here: it belongs to the session, which may still
+ * be sending input on it long after the log panel is closed.
+ */
+export function subscribeLogcat(
+  deviceId: string,
+  channel: EmulatorChannel,
+  listener: LogcatListener,
+): () => void {
+  let stream = streams.get(deviceId);
+  if (!stream) {
+    stream = { channel, call: null, ring: [], listeners: new Set(), nextId: 1 };
+    streams.set(deviceId, stream);
+  }
+  // A session that reconnected has a new channel; the ring belongs to the device, not to it.
+  stream.channel = channel;
+  if (!stream.call) openStream(deviceId, stream);
+  stream.listeners.add(listener);
+  // Hand over what has already been said, so opening the panel does not show an empty box on a
+  // device that has been running for an hour.
+  if (stream.ring.length > 0) listener([...stream.ring]);
+
+  return () => {
+    const s = streams.get(deviceId);
+    if (!s) return;
+    s.listeners.delete(listener);
+    // Plan gate: "logs hidden ngừng subscription". Nobody watching means nothing streaming.
+    if (s.listeners.size === 0) closeStream(deviceId);
+  };
+}
+
+function openStream(deviceId: string, stream: DeviceLogcat): void {
+  // No `sort` field: the default is Text, and Parsed is the empty-stream trap described above.
+  const call = stream.channel.client.streamLogcat({}, stream.channel.metadata);
+  stream.call = call;
+  call.on("data", (msg: any) => {
+    const contents: string = msg?.contents ?? "";
+    if (contents.length === 0) return;
+    const entries: AndroidLogEntry[] = [];
+    for (const line of contents.split("\n")) {
+      const entry = parseLogcatLine(line.replace(/\r$/, ""), stream.nextId);
+      if (entry) { stream.nextId++; entries.push(entry); }
+    }
+    if (entries.length === 0) return;
+    stream.ring.push(...entries);
+    if (stream.ring.length > LOGCAT_RING_SIZE) {
+      stream.ring.splice(0, stream.ring.length - LOGCAT_RING_SIZE);
+    }
+    for (const l of stream.listeners) l(entries);
+  });
+  call.on("error", (e: any) => {
+    // code 1 is CANCELLED, which is how the last watcher leaving ends it.
+    if (e?.code !== 1) console.warn(`[android] logcat stream for ${deviceId} failed: ${e?.details ?? e?.message ?? e}`);
+  });
+}
+
+/**
+ * Stop the gRPC stream but **keep the ring**.
+ *
+ * The plan's gate is that hiding the log stops the subscription, which this does. Throwing the
+ * backlog away as well is a different thing and a worse one: closing the panel to read a stack
+ * trace on another screen and reopening it would show an empty box. The cost is that a reopened
+ * panel has a gap where nothing was being watched — the timestamps say so.
+ */
+function closeStream(deviceId: string): void {
+  const stream = streams.get(deviceId);
+  if (!stream?.call) return;
+  try { stream.call.cancel(); } catch { /* already gone */ }
+  stream.call = null;
+}
+
+/** Tear everything down for a device — the session closing, or the emulator stopping. */
+export function closeDeviceLogcat(deviceId: string): void {
+  closeStream(deviceId);
+  streams.delete(deviceId);
+}
+
+/** What a watcher would be handed right now. Exposed for tests and for a snapshot download. */
+export function logcatBacklog(deviceId: string): AndroidLogEntry[] {
+  return [...(streams.get(deviceId)?.ring ?? [])];
+}

package/src/services/android/android-nonce.ts

@@ -0,0 +1,50 @@
+/**
+ * Single-use, short-lived nonces for `/ws/android`.
+ *
+ * The coarse PPM token already travels as `?token=` on every WS URL and proves only "holds the
+ * one reusable app token". A session that hands over touch and keyboard control of a running
+ * VM needs more than that, so `POST /api/android/devices/:id/sessions` mints a nonce that must
+ * be the client's *first* WS message and can be spent exactly once.
+ */
+const TTL_MS = 30_000;
+const MAX_OUTSTANDING = 32;
+
+interface Nonce {
+  value: string;
+  deviceId: string;
+  expiresAt: number;
+}
+
+const outstanding = new Map<string, Nonce>();
+
+function sweep(): void {
+  const now = Date.now();
+  for (const [k, n] of outstanding) if (n.expiresAt <= now) outstanding.delete(k);
+  // A client that mints and never connects must not be able to grow this without bound.
+  while (outstanding.size > MAX_OUTSTANDING) {
+    const oldest = [...outstanding.values()].sort((a, b) => a.expiresAt - b.expiresAt)[0];
+    if (!oldest) break;
+    outstanding.delete(oldest.value);
+  }
+}
+
+export function mintAndroidNonce(deviceId: string): string {
+  sweep();
+  const value = crypto.randomUUID().replace(/-/g, "");
+  outstanding.set(value, { value, deviceId, expiresAt: Date.now() + TTL_MS });
+  return value;
+}
+
+/** Spend a nonce. Returns the device it was minted for, or null if unknown/expired/already used. */
+export function consumeAndroidNonce(value: string): string | null {
+  sweep();
+  const n = outstanding.get(value);
+  if (!n) return null;
+  outstanding.delete(value);          // single use, even if the rest of the handshake fails
+  return n.expiresAt > Date.now() ? n.deviceId : null;
+}
+
+/** Revoke everything — used when the PPM token changes or auth is turned off. */
+export function revokeAllAndroidNonces(): void {
+  outstanding.clear();
+}

package/src/services/android/android-operations.ts

@@ -0,0 +1,124 @@
+/**
+ * Operation IDs for anything that takes longer than a request should wait for.
+ *
+ * Plan §5: "Các thao tác lâu trả operation ID, không giữ HTTP request chờ boot nhiều phút." A
+ * cold boot is minutes; an HTTP request held that long dies to some proxy's idle timeout and the
+ * client cannot tell a lost connection from a failed boot. So start returns an id and the client
+ * polls — and a client that reconnects mid-boot re-attaches rather than starting a second one.
+ */
+export type OperationState = "pending" | "running" | "succeeded" | "failed" | "cancelled";
+
+export interface Operation<T = unknown> {
+  id: string;
+  kind: string;
+  state: OperationState;
+  /** Human-readable progress, e.g. "booting (28s)". Not a percentage: boot has no honest one. */
+  detail: string;
+  startedAt: number;
+  endedAt: number | null;
+  result: T | null;
+  error: string | null;
+}
+
+/** Finished operations are kept this long so a client that reconnects can still read the outcome. */
+const RETAIN_FINISHED_MS = 5 * 60_000;
+const MAX_OPERATIONS = 200;
+
+const operations = new Map<string, Operation<any>>();
+
+function sweep(): void {
+  const now = Date.now();
+  for (const [id, op] of operations) {
+    if (op.endedAt !== null && now - op.endedAt > RETAIN_FINISHED_MS) operations.delete(id);
+  }
+  // Hard cap so a pathological caller cannot grow this without bound.
+  while (operations.size > MAX_OPERATIONS) {
+    const oldest = [...operations.values()].sort((a, b) => a.startedAt - b.startedAt)[0];
+    if (!oldest) break;
+    operations.delete(oldest.id);
+  }
+}
+
+export function createOperation<T>(kind: string, detail = ""): Operation<T> {
+  sweep();
+  const op: Operation<T> = {
+    id: crypto.randomUUID(),
+    kind,
+    state: "pending",
+    detail,
+    startedAt: Date.now(),
+    endedAt: null,
+    result: null,
+    error: null,
+  };
+  operations.set(op.id, op);
+  return op;
+}
+
+export function getOperation(id: string): Operation | null {
+  sweep();
+  return operations.get(id) ?? null;
+}
+
+export function updateOperation(id: string, patch: Partial<Pick<Operation, "state" | "detail">>): void {
+  const op = operations.get(id);
+  if (!op) return;
+  Object.assign(op, patch);
+}
+
+export function finishOperation<T>(id: string, result: T): void {
+  const op = operations.get(id);
+  if (!op) return;
+  cancellers.delete(id);
+  if (op.state === "cancelled") return;   // a cancel that landed first wins
+  op.state = "succeeded";
+  op.result = result;
+  op.endedAt = Date.now();
+}
+
+export function failOperation(id: string, error: string): void {
+  const op = operations.get(id);
+  if (!op) return;
+  cancellers.delete(id);
+  if (op.state === "cancelled") return;
+  op.state = "failed";
+  op.error = error;
+  op.endedAt = Date.now();
+}
+
+/** Test seam: drop everything. */
+export function _resetOperations(): void {
+  operations.clear();
+  cancellers.clear();
+}
+
+/* ---------------------------------------------------------------------------------------------
+ * Cancelling.
+ *
+ * An install can be cancelled where a boot cannot, so cancellation is registered per operation
+ * rather than assumed: `getOperation` reports `cancellable` and the route refuses to cancel one
+ * that never registered a way to stop.
+ * ------------------------------------------------------------------------------------------- */
+
+const cancellers = new Map<string, () => void>();
+
+export function registerCanceller(id: string, cancel: () => void): void {
+  if (operations.has(id)) cancellers.set(id, cancel);
+}
+
+export function isCancellable(id: string): boolean {
+  return cancellers.has(id);
+}
+
+/** Returns false when the operation does not exist, has already ended, or cannot be cancelled. */
+export function cancelOperation(id: string): boolean {
+  const op = operations.get(id);
+  const cancel = cancellers.get(id);
+  if (!op || !cancel || op.endedAt !== null) return false;
+  cancellers.delete(id);
+  op.state = "cancelled";
+  op.detail = "cancelled";
+  op.endedAt = Date.now();
+  try { cancel(); } catch { /* the work was already finishing */ }
+  return true;
+}

package/src/services/android/android-screenshot.ts

@@ -0,0 +1,53 @@
+/**
+ * A still of the device screen, and the clipboard both ways.
+ *
+ * Deliberately **PNG** rather than the raw RGBA the video pipeline consumes: the emulator encodes
+ * it itself, so nothing here has to know the buffer layout — and that layout is exactly what the
+ * proto's own comment gets wrong (it says "bottom up"; measured against `adb exec-out screencap`
+ * it is top-down, see the Phase 0 report §5.3). A file the user downloads is not the place to
+ * rediscover that.
+ *
+ * `getScreenshot` is a *unary* call, so it is independent of the session's `streamScreenshot` —
+ * measured in Phase 2: 343 frames before, 358 after, i.e. taking a still does not disturb a
+ * running stream.
+ */
+import { unaryCall, type EmulatorChannel } from "./android-grpc.ts";
+
+export interface Screenshot {
+  png: Uint8Array;
+  width: number;
+  height: number;
+}
+
+/**
+ * `width`/`height` in `ImageFormat` are a **bounding box** that preserves the device's aspect
+ * ratio, not an exact size (Phase 0 §5.4). Omitting them is what asks for the native resolution,
+ * which is what a screenshot should be.
+ */
+export async function takeScreenshot(channel: EmulatorChannel, timeoutMs = 10_000): Promise<Screenshot> {
+  const img = await unaryCall<any>(channel, "getScreenshot", { format: "PNG" }, timeoutMs);
+  const png: Uint8Array = img?.image instanceof Uint8Array ? img.image : new Uint8Array(img?.image ?? []);
+  if (png.length === 0) throw new Error("the emulator returned an empty screenshot");
+  return {
+    png,
+    // `format.width/height` is the authority; the top-level pair is deprecated in the proto.
+    width: Number(img?.format?.width ?? img?.width ?? 0),
+    height: Number(img?.format?.height ?? img?.height ?? 0),
+  };
+}
+
+/** A filename a person can find again: the AVD, then the local date and time. */
+export function screenshotFilename(avdName: string, at = new Date()): string {
+  const p = (n: number) => String(n).padStart(2, "0");
+  const stamp = `${at.getFullYear()}${p(at.getMonth() + 1)}${p(at.getDate())}-${p(at.getHours())}${p(at.getMinutes())}${p(at.getSeconds())}`;
+  const safe = avdName.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "") || "device";
+  return `${safe}-${stamp}.png`;
+}
+
+/** Longer than this and it is not a clipboard, it is a file transfer. */
+export const MAX_CLIPBOARD_CHARS = 64 * 1024;
+
+export async function setDeviceClipboard(channel: EmulatorChannel, text: string): Promise<void> {
+  if (text.length > MAX_CLIPBOARD_CHARS) throw new Error("clipboard text is too long");
+  await unaryCall(channel, "setClipboard", { text }, 3000);
+}