# Desarrollo

> HTML: https://remote.ivjn.us/docs/es/development/

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.

| crate | Ruta | Resultado |
|---|---|---|
| `proto` | `crates/proto` | Biblioteca. Centraliza mensajes de control, tramas binarias y estructuras compartidas |
| `exchange` | `crates/exchange` | Binario `exchange`, con el mismo nombre que el paquete |
| `agent` | `crates/agent` | Binario `remote-agent` |
| `cli` | `crates/cli` | Binario `remote-cli` |
| `updater` | `crates/updater` | Biblioteca de actualización para `remote-agent` y `remote-cli` |
| `telemetry` | `crates/telemetry` | Biblioteca de informes de excepciones y registros compartida por los tres extremos |
| `tls-client` | `crates/tls-client` | Política TLS rustls compartida de clientes y conexiones proxy opcionales |
| `worker-proto` | `crates/worker-proto` | Validación de protocolo y hash de credenciales de Workers Exchange |
| `remote-extend-sdk` | `sdk/extend/rust` | Biblioteca de tramas y contratos para proveedores de extensiones |

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:

```bash
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`:

```bash
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

```bash
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:

```rust
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.

```bash
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:

```powershell
$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.

```sh
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:

```sh
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](/docs/es/architecture.md): conexiones de salida, traducción de sesiones, epoch, colas limitadas y almacenamiento de tokens.
- [Uso](/docs/es/getting-started.md): 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](/docs/es/websocket-protocol.md).
- [Despliegue multiplataforma](/docs/es/platform-installation.md).