Desarrollo

Este documento explica cómo compilar y probar el repositorio y ejecutar exchange localmente. Los procedimientos de despliegue, las tablas de campos del protocolo y la instalación en cada plataforma se describen en sus documentos específicos, enlazados al final.

Herramientas

El espacio de trabajo utiliza Rust 2021 y requiere Rust 1.88 o posterior. La versión figura en el campo rust-version del Cargo.toml de la raíz.

Espacio de trabajo y binarios

El espacio de trabajo Rust tiene nueve miembros: ocho en crates/ y el SDK de extensiones en sdk/extend/rust. Los tipos del protocolo se definen exclusivamente en crates/proto; exchange, agent y cli dependen de ese crate. No dupliques las estructuras de mensajes en un extremo.

El punto de entrada de exchange es crates/exchange/src/main.rs. Como no tiene una tabla [[bin]] separada, cargo build -p exchange genera exchange. agent y cli especifican los nombres remote-agent y remote-cli en sus respectivos Cargo.toml.

Las tablas de conexiones se dividen por responsabilidad:

• crates/exchange/src/hub.rs gestiona dispositivos conectados, sustituciones al reconectar y epoch.
• crates/exchange/src/hub/session_table.rs traduce identificadores entre operador y dispositivo.
• crates/exchange/src/hub/outbound.rs gestiona la cola de envío limitada de cada conexión.

Compilar

Ejecuta los comandos desde la raíz del repositorio.

El perfil de publicación, con opt-level = 2, thin LTO y unwind, compila el servidor, la CLI y el agente:

cargo build --release

Los binarios están en:

• target/release/exchange
• target/release/remote-cli
• target/release/remote-agent

release conserva unwind porque exchange es un proceso persistente con múltiples conexiones. Si una tarea de conexión entra en pánico, unwind permite a tokio detener esa tarea sin terminar las sesiones de otros dispositivos del mismo proceso.

El agente también dispone de un perfil que prioriza el tamaño: opt-level = "z", LTO, panic = "abort", strip y codegen-units = 1:

cargo build -p agent --no-default-features --profile release-small

Genera target/release-small/remote-agent. procd, systemd o una tarea programada reinician el agente tras un fallo, así que aquí se puede utilizar panic = "abort" para reducir el tamaño.

La compilación no necesita una base de datos. crates/exchange/src/db.rs utiliza consultas sqlx en tiempo de ejecución en lugar de la macro query!, por lo que cargo build funciona sin ella.

Pruebas

cargo test --workspace

Windows no ejecuta las pruebas que dependen de /bin/sh de Unix, /bin/ash en OpenWrt o PTY. El módulo de pruebas de crates/agent/src/pty.rs está protegido por #[cfg(all(test, unix))] y no se compila fuera de Unix. La implementación de PTY prueba primero /bin/ash y después /bin/sh. Las rutas de grupos de procesos y señales Unix de exec.rs también se compilan únicamente en Unix. Las pruebas de comandos de Windows utilizan PowerShell y no llaman a /bin/sh. Si modificas las rutas Unix de exec.rs o pty.rs, vuelve a ejecutar cargo test --workspace en Linux; el resultado de Windows no basta.

Puedes limitar el alcance a un crate, por ejemplo con cargo test -p proto o cargo test -p exchange -- hub::.

Ejecutar exchange localmente

Prepara PostgreSQL y guarda la cadena de conexión en DATABASE_URL. Esta variable corresponde a --database-url de exchange; consulta crates/exchange/src/config.rs. Al iniciar el proceso, db::connect ejecuta las migraciones incorporadas durante la compilación:

sqlx::migrate!("../../migrations")

Los archivos están en migrations/ en la raíz y se ejecutan automáticamente al iniciar, sin necesidad de sqlx-cli.

Las operaciones de auditoría también requieren una clave de cifrado. Los ejemplos siguientes generan una clave de prueba local. Guárdela de forma segura y reutilícela en los siguientes inicios; generar una nueva cada vez impide descifrar los detalles de auditoría existentes.

export DATABASE_URL='postgres://luci:luci@127.0.0.1:5432/luci'
export AUDIT_ENCRYPTION_KEY="$(python -c 'import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())')"
cargo run -p exchange -- --listen 127.0.0.1:8080

En PowerShell, define primero la variable de entorno:

$env:DATABASE_URL = "postgres://luci:luci@127.0.0.1:5432/luci"
$env:AUDIT_ENCRYPTION_KEY = python -c "import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"
cargo run -p exchange -- --listen 127.0.0.1:8080

Si ya compilaste el binario de publicación, sustituye cargo run -p exchange -- por ./target/release/exchange. La dirección de escucha predeterminada es 0.0.0.0:8080; para depurar localmente se recomienda especificar 127.0.0.1.

Si no existe ninguna cuenta de operador habilitada en la base de datos, el arranque crea un administrador inicial y muestra el token en ese registro de inicio. El texto sin cifrar solo aparece una vez. El despliegue, el proxy inverso y las cuentas se explican en docs/deployment.md del repositorio. Esa página incluye direcciones de servidores y no se publica en este sitio.

Comprobaciones antes del commit

Ejecute estas comprobaciones desde la raíz del repositorio. Para cambios Rust, empiece por las pruebas del crate afectado y después compruebe el workspace. Si el formato detecta diferencias existentes ajenas al cambio, formatee solo los archivos modificados. Android, la extensión del navegador y la consola móvil necesitan además sus propias compilaciones y pruebas; las pruebas Rust no cubren esas interfaces.

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Mantener la documentación

Verifique el comportamiento de la implementación antes de actualizar las guías en docs/. Los temas web tienen una referencia en website/docs/<topic>.md y nueve traducciones en website/docs/content/<locale>/<topic>.md. Mantenga alineados comandos, campos, ejemplos y niveles de títulos. Genere las páginas y los índices de búsqueda con el script en vez de editar solo HTML. Ejecute lo siguiente desde la raíz con Python 3.11+, markdown-it-py y Node.js instalados:

python -m pip install markdown-it-py
python scripts/build-docs.py
python scripts/build-docs.py --check
python scripts/test-docs.py
python scripts/test-docs-markdown.py
node scripts/test-docs-locale.js
python scripts/test-build-docs.py
python scripts/test-site-seo.py

La comprobación de generación también compara cada archivo generado byte a byte y falla si falta una salida o está desactualizada, sin escribir archivos. CI la ejecuta antes de regenerar.

Las comprobaciones validan traducciones completas, ejemplos, títulos, enlaces, anclas y rutas de idioma. Incluya las páginas generadas en el mismo commit que sus fuentes. La generación solo cambia archivos locales; el despliegue del sitio y la publicación de descargas son operaciones separadas.

Documentación relacionada

• Descripción técnica: conexiones de salida, traducción de sesiones, epoch, colas limitadas y almacenamiento de tokens.
• Uso: inicio de sesión, alta de dispositivos, arranque del agente, comandos y shell.
• Guía de despliegue en docs/deployment.md del repositorio; contiene direcciones de servidores y no se publica en el sitio.
• Protocolo de comunicación.
• Despliegue multiplataforma.