Arquitectura

EmuLabZip es un workspace de Cargo. El código de cada plataforma vive en crates pequeños detrás de un único trait, y dos front ends (la app de escritorio y la CLI) los usan de la misma manera.

                ┌──────────────────────┐      ┌──────────────────┐
                │  apps/desktop        │      │  emulabzip-cli   │
                │  Svelte UI ◄─► Tauri │      │  (clap)          │
                └──────────┬───────────┘      └────────┬─────────┘
                           │        Lab (routes by platform)
                           └───────────────┬───────────┘
                                 ┌─────────┴─────────┐
                      Backend    │                   │   Backend
                ┌────────────────┴───┐        ┌──────┴──────────────┐
                │ emulabzip-android  │        │ emulabzip-apple     │
                │ logcat, getprop,   │        │ simctl, log stream, │
                │ dumpsys, pm, ps    │        │ listapps, plutil    │
                └─────────┬──────────┘        └──────┬──────────────┘
                ┌─────────┴──────────┐               │
                │ emulabzip-adb      │          xcrun simctl
                │ ADB host protocol  │
                └─────────┬──────────┘
                    adb server :5037

Crates#

El trait Backend#

#[async_trait]
pub trait Backend: Send + Sync {
    fn platform(&self) -> Platform;
    async fn is_available(&self) -> bool;
    async fn devices(&self) -> Result<Vec<Device>>;
    async fn info(&self, id: &str) -> Result<Vec<InfoSection>>;
    async fn apps(&self, id: &str) -> Result<Vec<App>>;
    async fn logs(&self, id: &str, options: LogOptions) -> Result<Stream<LogEntry>>;
    async fn screenshot(&self, id: &str) -> Result<Vec<u8>>;

    // Optional: the default implementations return `Error::Unsupported`.
    async fn perf(&self, id: &str, options: PerfOptions) -> Result<Stream<PerfSample>>;
    async fn memory(&self, id: &str, app: &str) -> Result<MemoryReport>;
    async fn heap_dump(&self, id: &str, app: &str) -> Result<HeapDump>;
    async fn storage_roots(&self, id: &str, app: &str) -> Result<Vec<StorageRoot>>;
    async fn list_files(&self, id: &str, app: &str, root: &str, path: &str) -> Result<Vec<FileEntry>>;
    async fn read_file(&self, id: &str, app: &str, root: &str, path: &str) -> Result<Vec<u8>>;
    async fn trace_templates(&self, id: &str) -> Result<Vec<String>>;
    async fn record_trace(&self, id: &str, request: &TraceRequest, out_dir: &Path, stop: watch::Receiver<bool>) -> Result<TraceFile>;
    async fn clock(&self, id: &str) -> Result<DeviceClock>;
    async fn input(&self, id: &str) -> Result<Stream<InputEvent>>;
    async fn slow_frames(&self, id: &str, app: &str) -> Result<Stream<SlowFrame>>;
    async fn record_video(&self, id: &str, out_dir: &Path, segment_secs: u32, stop: watch::Receiver<bool>, segments: mpsc::UnboundedSender<VideoSegment>) -> Result<()>;
    async fn crashes(&self, id: &str, app: Option<&str>) -> Result<Vec<CrashSummary>>;
    async fn crash(&self, id: &str, crash_id: &str) -> Result<CrashReport>;
    async fn controls(&self, id: &str, app: Option<&str>) -> Result<ControlInfo>;
    async fn control(&self, id: &str, control: &Control) -> Result<()>;
    async fn network_status(&self, id: &str) -> Result<NetworkStatus>;
    async fn connect_network(&self, id: &str, port: u16) -> Result<NetworkStatus>;
    async fn disconnect_network(&self, id: &str) -> Result<NetworkStatus>;
    async fn install_ca(&self, id: &str, pem: &str, der: &[u8]) -> Result<CaInstall>;
}

Lab contiene todos los backends y enruta las llamadas por Target { platform, id }. Una herramienta ausente (adb, xcrun) hace que un backend no esté disponible sin afectar a los demás.

Streams#

Los logs los produce una tarea en segundo plano y se entregan a través de un canal acotado (Stream<T>). Al soltar el stream se aborta la tarea, lo que cierra el socket de ADB o mata el proceso hijo de log stream, de modo que nada sobrevive al lector.

En la app de escritorio, cada stream es una sesión que pertenece al estado de Tauri. Las líneas se agrupan cada 100 ms y se envían a la interfaz por un canal IPC de Tauri. Un lote contiene como máximo 4,000 líneas; el excedente se cuenta y se informa como descartado en lugar de ralentizar el dispositivo o la interfaz. La interfaz mantiene su propio búfer acotado y dibuja solo las filas visibles.

Un solo eje de tiempo#

Cada stream marca el tiempo a su manera (el log imprime la hora local del dispositivo sin año, las muestras cuentan desde que empezaron, los toques y los fotogramas cuentan desde que arrancó el dispositivo), así que una grabación guarda un DeviceClock: el reloj de pared del dispositivo frente al de este equipo, su zona horaria y el momento en que su reloj monotónico marcaba cero. timeline::build de emulabzip-session lo usa para poner toques, problemas del log, peticiones, fotogramas lentos, recolecciones de basura, fallos, capturas de pantalla y vídeo en un solo eje, en milisegundos desde el inicio. Un fotograma lento se ubica con el Uptime que imprime el volcado de gfxinfo, que es el reloj en el que están los tiempos de los fotogramas. El vídeo de la pantalla se graba en fragmentos cortos (consulta Línea de tiempo y vídeo de pantalla), cada uno notificado al completarse, así que una grabación interrumpida conserva lo que tenía.

El proxy#

emulabzip-net no sabe nada de dispositivos. Los backends solo deciden cómo llega un dispositivo hasta él y cómo llega a confiar en el certificado; la CLI y la app de escritorio inician el proxy y le entregan un FlowStore.

 device ──► 127.0.0.1:<port> ──► proxy ──► the internet
                                   │
              CONNECT, first byte is 0x16 (TLS)?
                 yes ─► terminate TLS with a leaf for the SNI name, serve HTTP/1.1 or HTTP/2,
                        forward over a new TLS connection, record the flow
                 no  ─► copy bytes both ways, record a tunnel
              handshake refused ─► remember the host, pass it through next time

Una repetición (replay) es un paso más antes de consultar al servidor: tras las reglas, forward busca la petición en el ReplaySet y responde desde él, o responde 504 cuando no está. Mientras se repite una grabación, se rechazan los caminos que no se pueden responder desde un HAR (un túnel que el proxy no puede decodificar, un WebSocket, una llamada gRPC, un reenvío), de modo que nada llega a la red. Consulta Repetir una grabación.

Los cuerpos de las respuestas se transmiten al cliente mientras se graba una copia (hasta 10 MB), así que las descargas y los flujos de eventos siguen funcionando. Los cuerpos de las peticiones se leen completos antes de reenviarlos. Las actualizaciones a WebSocket se tunelizan tras el handshake, y los bytes también se pasan a un parser de tramas que registra los mensajes.

Antes de reenviar una petición, el proxy consulta las reglas (gana la primera que coincida): un mock responde de inmediato, un retraso espera, un bloqueo falla y un breakpoint retiene la petición, o la respuesta, en un registro hasta que la interfaz la continúa. Con HTTP/3 activado, un host que anunció Alt-Svc: h3 se alcanza por QUIC, con una alternativa a TCP.

Rutas de almacenamiento#

Las rutas de archivos son siempre relativas a una raíz de almacenamiento elegida por el backend (data, external, bundle…). Lab rechaza las rutas absolutas y .. antes de que un backend las vea, y el backend de iOS además resuelve los enlaces simbólicos y rechaza cualquier cosa que acabe fuera del contenedor.

Reglas de diseño#

• Solo interfaces públicas. Todo lo que lee EmuLabZip es algo que podrías obtener con adb shell o xcrun simctl. Consulta Cómo funcionan las herramientas oficiales.
• Sin inyección de shell. Los valores que llegan al shell del dispositivo se entrecomillan (emulabzip_adb::quote), los nombres de paquete se validan y simctl se invoca sin shell.
• Agrupa las idas y vueltas al dispositivo. El Overview es una sola llamada de shell en Android; los parsers dividen su salida.
• Los parsers se prueban con salida real. Los fixtures capturados de emuladores y simuladores viven junto a cada crate.
• Solo escrituras explícitas. Los archivos se escriben únicamente tras un diálogo de guardado o un flag de la CLI.