16 KiB
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
- 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.
- 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.
- 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.
- 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.
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»<br/>IApacheDriver"]
RealDriver["RealApacheDriver<br/>(Linux execFile + sudo)"]
MockDriver["MockApacheDriver<br/>(Local Filesystem + Virtual Symlinks)"]
UserRepo["UserRepository<br/>(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
- 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. - 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.
- 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.
- 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.
classDiagram
class IApacheDriver {
<<interface>>
+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:- Si
process.env.MOCK_APACHE === 'true', retornaMockApacheDriver. - Si el binario
apache2ctlno se encuentra en elPATHdel sistema, advierte en el log de inicio y retornaMockApacheDriver. - Si
apache2ctlestá presente yMOCK_APACHE !== 'true', retornaRealApacheDriver.
- Si
- Comportamiento de
MockApacheDriver:- Redirige la raíz a
./.tmp/apache2/sites-available/,./.tmp/apache2/sites-enabled/y./.tmp/www/. - Simula
a2ensitemediante la creación de enlaces simbólicos relativos en el filesystem local. - Simula
apache2ctl configtestparseando balanceo básico de tags XML/Apache (<VirtualHost>y</VirtualHost>). Si el contenido del template contiene la palabraTRIGGER_SYNTAX_ERROR, simula una falla sintáctica para probar el rollback.
- Redirige la raíz a
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).
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/<subdominio>
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/<subdominio>.conf
EnablingSite --> RunningConfigtest : sudo a2ensite <subdominio>.conf
RunningConfigtest --> SyntaxEvaluator : sudo apache2ctl configtest
state SyntaxEvaluator <<choice>>
SyntaxEvaluator --> FinalizingReload : Syntax OK (Código 0)
SyntaxEvaluator --> RollbackCompensation : Syntax Error (Código != 0)
state "Rollback Atómico Compensatorio" as RollbackCompensation {
[*] --> DissiteAction : sudo a2dissite <subdominio>.conf
DissiteAction --> UnlinkConf : rm sites-available/<subdominio>.conf
UnlinkConf --> CleanupFs : Modo A recién creado?
state FsCleanupDecision <<choice>>
FsCleanupDecision --> PurgeFolder : Sí -> rm -rf /var/www/<subdominio>
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/<subdominio>, index.html y fijar SGID 2775. |
Falla de disco o permisos I/O. | Eliminar directorio parcial y abortar. |
WritingConf |
Escribir /etc/apache2/sites-available/<subdominio>.conf. |
Falla de escritura o permisos. | Eliminar carpeta web creada (si aplica). |
EnablingSite |
Invocación de sudo a2ensite <subdominio>.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 <subdominio>.conf2. rm sites-available/<subdominio>.conf3. 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.
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:
- Se serializa el JSON en memoria.
- Se escribe en un archivo temporal adyacente:
users.json.tmp.<pid>. - Se sincroniza con disco mediante
fs.fsyncSync(). - Se ejecuta una operación de renombre atómico a nivel de kernel:
fs.renameSync('users.json.tmp.<pid>', '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.
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:
- Módulos Nativos de ECMAScript (ESM): Código estructurado en submódulos cargados con
<script type="module" src="/app.js">. - Componentización Funcional Ligera: Componentes desacoplados definidos como funciones puras que retornan cadenas HTML mediante Template Literals, interpolando valores de forma sanitizada.
- Estado Reactivo Centralizado: Un objeto
stateobservable que dispara re-renderizados dirigidos de elementos del DOM (tabla de subdominios, cards de telemetría, modales de confirmación) ante mutaciones. - Micro-interacciones y Feedback Inmediato: Toasts flotantes accesibles para notificaciones de éxito o errores sintácticos de Apache, badges de estado animados con pulsaciones sutiles y diálogos modales nativos
<dialog>con foco atrapado.
7. Diagrama de Secuencia: Ciclo de Vida de Petición Típica
sequenceDiagram
autonumber
actor Admin as Administrador
participant Browser as UI (Browser)
participant Auth as Auth Middleware
participant SubSvc as SubdomainService
participant Apache as ApacheDriver (Real)
participant FS as Linux Filesystem
Admin->>Browser: Clic en "Crear Subdominio" (Modo B, Puerto 8080)
Browser->>Auth: POST /api/subdomains (Cookie: a2host_session=...)
Auth->>Auth: Verificar firma HMAC de cookie
alt Cookie inválida o expirada
Auth-->>Browser: HTTP 401 Unauthorized
Browser->>Browser: Redirigir a /login.html
else Sesión Válida
Auth->>SubSvc: createSubdomain({name: "api", type: "proxy", port: 8080})
SubSvc->>SubSvc: Validar regex 'api' y colisión con puerto 8080
SubSvc->>FS: fs.existsSync('/etc/apache2/sites-available/api.conf')
SubSvc->>Apache: createVirtualHost("api", template)
Apache->>FS: fs.writeFileSync('sites-available/api.conf', content)
SubSvc->>Apache: enableSite("api")
Apache->>FS: sudo a2ensite api.conf
SubSvc->>Apache: testConfig()
Apache->>FS: sudo apache2ctl configtest
FS-->>Apache: "Syntax OK"
SubSvc->>Apache: reloadApache()
Apache->>FS: sudo systemctl reload apache2
SubSvc-->>Browser: HTTP 201 Created {name: "api", status: "enabled"}
Browser->>Browser: Añadir fila a tabla y mostrar Toast de éxito
end