# Descripción del Diseño de Software (SDD) ## Sistema de Gestión Dinámica de Subdominios Apache2 (`a2host`) **Estándar:** IEEE Std 1016-2009 / ISO/IEC/IEEE 42010:2011 **Proyecto:** a2host — Lightweight Subdomain Orchestrator **Versión:** 1.0.0 **Fecha de Emisión:** 19 de Noviembre de 2026 **Clasificación:** Documento de Diseño Técnico **Autor:** Arquitectura y Redacción Técnica (@docs) --- ### Registro de Revisiones | Versión | Fecha | Autor | Justificación y Cambios | | :---: | :---: | :---: | :--- | | `1.0.0` | 2026-11-19 | Arquitecto de Documentación (@docs) | Versión inicial del diseño de software bajo norma IEEE Std 1016-2009. Especificación de patrones Strategy, Máquina de Estados del Rollback Atómico, Modelo de Datos y Diseño Zero-Build. | --- ## 1. Introducción y Contexto Arquitectónico ### 1.1 Propósito del Documento El presente documento describe la arquitectura interna, descomposición modular, patrones de diseño, flujos de datos y estructuras de persistencia del sistema **`a2host`**, conforme al estándar internacional **IEEE Std 1016-2009** (*Information Technology — Systems and software engineering — Software Design Descriptions*). ### 1.2 Objetivos Arquitectónicos Primordiales 1. **Ultra-Baja Huella de Recursos (1 GB RAM Target):** Diseñar un sistema con cero sobrecarga en tiempo de ejecución que conviva sin contención con servicios como Gitea (puerto 3000), bases de datos y Apache2 nativo en un VPS con 1 GB de memoria física. 2. **Resiliencia Operativa y Aislamiento de Fallos:** Garantizar que ninguna mala configuración provocada por un usuario o falla de sintaxis pueda desestabilizar el servidor web Apache central mediante el desacoplamiento y un protocolo de *Rollback Atómico*. 3. **Inmunidad a Vulnerabilidades de Inyección:** Eliminar vectores de ataque de inyección de comandos en shell mediante la erradicación del shell subyacente en la ejecución de binarios y validación estricta de cadenas en el perímetro. 4. **Portabilidad y Desacoplamiento de Entorno:** Facilitar el desarrollo, testing automatizado y depuración en estaciones de trabajo locales (macOS, Linux sin Apache) mediante una abstracción por controladores (*Strategy Pattern*). --- ## 2. Vista Lógica y Arquitectura por Capas El sistema se estructura siguiendo una arquitectura en capas limpias (*Clean Architecture / Hexagonal Ports & Adapters*) adaptada a un runtime ligero en Node.js 22 LTS. ```mermaid flowchart TD subgraph PresentationLayer["Capa de Presentación (Zero-Build Frontend)"] SPA["index.html + app.js (Vanilla ES6+)"] Tailwind["Tailwind CSS (CDN / Native Utility Tokens)"] Components["Componentes UI: Modal, Tables, Toast, SystemStatus"] end subgraph TransportLayer["Capa de Transporte & Perímetro HTTP"] Router["Express App Router (/api/*)"] AuthGuard["AuthMiddleware (HMAC Cookie Guard)"] RateLimiter["IP Rate Limiter"] Validator["Input Sanitizer & Schema Validator (Regex Guards)"] end subgraph DomainServiceLayer["Capa de Dominio y Servicios de Negocio"] SubdomainService["SubdomainService (Lifecycle Management)"] AuthService["AuthService (scrypt & Credential Security)"] UserService["UserService (Operator Management)"] TelemetryService["TelemetryService (Memory, Process & Apache Health)"] TxCoordinator["ApacheTransactionCoordinator (Rollback Engine)"] end subgraph InfrastructureLayer["Capa de Infraestructura y Drivers (Strategy Pattern)"] DriverInterface["«interface»
IApacheDriver"] RealDriver["RealApacheDriver
(Linux execFile + sudo)"] MockDriver["MockApacheDriver
(Local Filesystem + Virtual Symlinks)"] UserRepo["UserRepository
(Atomic JSON / SQLite)"] end SPA -->|"JSON via Fetch"| Router Router --> AuthGuard AuthGuard --> RateLimiter RateLimiter --> Validator Validator --> SubdomainService Validator --> AuthService Validator --> UserService Validator --> TelemetryService SubdomainService --> TxCoordinator TxCoordinator --> DriverInterface AuthService --> UserRepo UserService --> UserRepo DriverInterface -.->|VPS Production| RealDriver DriverInterface -.->|Local Development| MockDriver ``` ### 2.1 Descripción de Capas 1. **Capa de Presentación (Zero-Build):** Servida como assets estáticos directamente por Express desde `/public/`. No realiza compilaciones complejas en caliente; utiliza JavaScript Vanilla moderno (módulos ES6) y Tailwind CSS. 2. **Capa de Transporte & Perímetro:** Gestiona el protocolo HTTP. Los middleware interceptan las peticiones para verificar la firma criptográfica de las cookies de sesión, limitar tasas de peticiones anómalas y convalidar entradas estrictas contra ataques de inyección. 3. **Capa de Dominio & Coordinación:** Implementa las reglas de negocio: validación de colisiones de nombres, exclusión de puertos reservados, coordinación del rollback y cálculo de métricas de telemetría. 4. **Capa de Infraestructura & Drivers:** Encapsula la comunicación con el sistema operativo y el sistema de archivos mediante una interfaz polimórfica que abstrae la presencia o ausencia de Apache2. --- ## 3. Patrones de Diseño de Software ### 3.1 Patrón Strategy: Abstracción de Controladores de Apache Para resolver la discrepancia crítica entre el entorno de desarrollo local (sin Apache2) y el servidor de producción (Ubuntu con Apache2 nativo), se implementa el patrón **Strategy**. ```mermaid classDiagram class IApacheDriver { <> +createVirtualHost(name: string, template: string) Promise~void~ +enableSite(name: string) Promise~void~ +disableSite(name: string) Promise~void~ +testConfig() Promise~ConfigTestResult~ +reloadApache() Promise~void~ +deleteVirtualHost(name: string) Promise~void~ +listSites() Promise~SiteInfo[]~ +ensureWebDirectory(name: string) Promise~void~ +removeWebDirectory(name: string) Promise~void~ } class RealApacheDriver { -sitesAvailablePath: string -sitesEnabledPath: string -webRoot: string -systemUser: string +createVirtualHost(name, template) +enableSite(name) +disableSite(name) +testConfig() +reloadApache() +deleteVirtualHost(name) +listSites() +ensureWebDirectory(name) +removeWebDirectory(name) -runCommand(bin: string, args: string[]) } class MockApacheDriver { -mockRoot: string -mockAvailable: string -mockEnabled: string -mockWww: string +createVirtualHost(name, template) +enableSite(name) +disableSite(name) +testConfig() +reloadApache() +deleteVirtualHost(name) +listSites() +ensureWebDirectory(name) +removeWebDirectory(name) -simulateSyntaxCheck(content: string) } class ApacheDriverFactory { +getDriver() IApacheDriver } IApacheDriver <|.. RealApacheDriver : implements IApacheDriver <|.. MockApacheDriver : implements ApacheDriverFactory --> IApacheDriver : instantiates ``` #### Reglas de Selección del Driver: - `ApacheDriverFactory.getDriver()` evalúa las condiciones de inicio: 1. Si `process.env.MOCK_APACHE === 'true'`, retorna `MockApacheDriver`. 2. Si el binario `apache2ctl` no se encuentra en el `PATH` del sistema, advierte en el log de inicio y retorna `MockApacheDriver`. 3. Si `apache2ctl` está presente y `MOCK_APACHE !== 'true'`, retorna `RealApacheDriver`. - **Comportamiento de `MockApacheDriver`:** - Redirige la raíz a `./.tmp/apache2/sites-available/`, `./.tmp/apache2/sites-enabled/` y `./.tmp/www/`. - Simula `a2ensite` mediante la creación de enlaces simbólicos relativos en el filesystem local. - Simula `apache2ctl configtest` parseando balanceo básico de tags XML/Apache (`` y ``). Si el contenido del template contiene la palabra `TRIGGER_SYNTAX_ERROR`, simula una falla sintáctica para probar el rollback. --- ## 4. Máquina de Estados del Rollback Atómico Para garantizar que ningún error en la configuración generada rompa el servidor web de producción (`apache2`), el aprovisionamiento de subdominios se ejecuta como una **transacción compensatoria atómica** modelada mediante una máquina de estados finitos (FSM). ```mermaid stateDiagram-v2 [*] --> Idle : Solicitud de Creación Recibida Idle --> ValidatingInput : Validar Regex y Puertos ValidatingInput --> Rejected : Validación Fallida (HTTP 400) ValidatingInput --> WritingFileSystem : Validación Exitosa state "Modo A (Directorio)" as WritingFileSystem { [*] --> MkdirWeb : Crear /var/www/ MkdirWeb --> WriteIndex : Generar index.html inicial WriteIndex --> ChmodSgid : sudo chown & chmod 2775 ChmodSgid --> [*] } WritingFileSystem --> WritingConf : Directorio Listo o Modo B WritingConf --> EnablingSite : Escribir sites-available/.conf EnablingSite --> RunningConfigtest : sudo a2ensite .conf RunningConfigtest --> SyntaxEvaluator : sudo apache2ctl configtest state SyntaxEvaluator <> SyntaxEvaluator --> FinalizingReload : Syntax OK (Código 0) SyntaxEvaluator --> RollbackCompensation : Syntax Error (Código != 0) state "Rollback Atómico Compensatorio" as RollbackCompensation { [*] --> DissiteAction : sudo a2dissite .conf DissiteAction --> UnlinkConf : rm sites-available/.conf UnlinkConf --> CleanupFs : Modo A recién creado? state FsCleanupDecision <> FsCleanupDecision --> PurgeFolder : Sí -> rm -rf /var/www/ FsCleanupDecision --> SkipPurge : No (Existía previamente) PurgeFolder --> [*] SkipPurge --> [*] } RollbackCompensation --> AbortedWithError : Rollback Finalizado AbortedWithError --> [*] : Retornar HTTP 422 {error: stderr} FinalizingReload --> Completed : sudo systemctl reload apache2 Completed --> [*] : Retornar HTTP 201 Created ``` ### 4.1 Especificación de Estados y Acciones Compensatorias | Estado | Acción Principal | Falla Posible | Acción Compensatoria (Rollback) | | :--- | :--- | :--- | :--- | | `ValidatingInput` | Convalidación regex y colisión de puertos. | Formato inválido o puerto en uso. | Ninguna. Rechazar con HTTP 400/409. | | `WritingFileSystem` | Crear `/var/www/`, `index.html` y fijar SGID `2775`. | Falla de disco o permisos I/O. | Eliminar directorio parcial y abortar. | | `WritingConf` | Escribir `/etc/apache2/sites-available/.conf`. | Falla de escritura o permisos. | Eliminar carpeta web creada (si aplica). | | `EnablingSite` | Invocación de `sudo a2ensite .conf`. | Enlace simbólico corrupto. | Eliminar `.conf` y carpeta creada. | | `RunningConfigtest` | Invocación de `sudo apache2ctl configtest`. | **Sintaxis Inválida de Apache.** | **1.** `sudo a2dissite .conf`
**2.** `rm sites-available/.conf`
**3.** Purgar carpeta `/var/www` si era nueva.
**4.** **NO EJECUTAR RELOAD.** Retornar HTTP 422. | | `FinalizingReload` | Invocación de `sudo systemctl reload apache2`. | Error interno de daemon. | Notificar alerta crítica del sistema. | --- ## 5. Modelo de Almacenamiento y Persistencia Ligera Considerando la restricción de **1 GB de RAM**, no se despliegan instancias pesadas de bases de datos adicionales. El almacenamiento de usuarios se modela mediante un repositorio desacoplado que soporta persistencia en un archivo JSON atómico (`users.json`) o SQLite embebido con `better-sqlite3`. ```mermaid erDiagram USUARIO { string id PK "UUID v4" string username UK "Identificador alfanumérico" string password_hash "scrypt hash ($N$r$p$salt$hash)" string role "admin | operator" string full_name "Nombre legible del operador" boolean active "Estado de habilitación" string created_at "ISO 8601 Timestamp" string updated_at "ISO 8601 Timestamp" } SESION { string session_id PK "Token criptográfico opaco" string user_id FK "Referencia al usuario autenticado" string ip_address "Dirección IP remota" string user_agent "Huella del navegador" string expires_at "ISO 8601 Timestamp" } SUBDOMINIO_CACHE { string name PK "Nombre subdominio" string full_domain "FQDN (name.elingejose.com)" string type "static | proxy" string target "Ruta de carpeta o puerto" boolean enabled "Estado en sites-enabled" boolean protected "Inmutable si es sitio del sistema" string updated_at "ISO 8601 Timestamp" } USUARIO ||--o{ SESION : "inicia" ``` ### 5.1 Protocolo de Escritura Atómica en Disco (`atomic-write`) Para prevenir corrupción del archivo `users.json` ante caídas de alimentación o reinicios forzados de PM2: 1. Se serializa el JSON en memoria. 2. Se escribe en un archivo temporal adyacente: `users.json.tmp.`. 3. Se sincroniza con disco mediante `fs.fsyncSync()`. 4. Se ejecuta una operación de renombre atómico a nivel de kernel: `fs.renameSync('users.json.tmp.', 'users.json')`. --- ## 6. Arquitectura de Interfaz Zero-Build La interfaz de usuario sigue una arquitectura de Single Page Application (SPA) sin empaquetadores (*bundlers* como Webpack, Vite o Rollup) para asegurar compatibilidad total con la memoria de 1 GB. ```mermaid flowchart LR subgraph BrowserClient["Navegador Web del Operador"] DOM["Document Object Model"] State["State Manager (Reactive Store en Memoria)"] EventBus["Vanilla Event Listeners"] RenderEngine["Template Literals Renderers"] end subgraph StaticAssets["Assets Servidos desde /public/"] IndexHtml["index.html (HTML5 Estructurado)"] AppJs["app.js (ES6 Módulos Nativos)"] TailwindCDN["Tailwind CSS CDN (Pre-procesado)"] end IndexHtml --> DOM TailwindCDN --> DOM AppJs --> State State --> RenderEngine RenderEngine --> DOM DOM --> EventBus EventBus --> State ``` ### 6.1 Principios del Diseño Zero-Build: 1. **Módulos Nativos de ECMAScript (ESM):** Código estructurado en submódulos cargados con `