350 lines
16 KiB
Markdown
350 lines
16 KiB
Markdown
# 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»<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
|
|
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 {
|
|
<<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:
|
|
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 (`<VirtualHost>` y `</VirtualHost>`). 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/<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>.conf`<br/>**2.** `rm sites-available/<subdominio>.conf`<br/>**3.** Purgar carpeta `/var/www` si era nueva.<br/>**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.<pid>`.
|
|
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.<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.
|
|
|
|
```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 `<script type="module" src="/app.js">`.
|
|
2. **Componentización Funcional Ligera:** Componentes desacoplados definidos como funciones puras que retornan cadenas HTML mediante *Template Literals*, interpolando valores de forma sanitizada.
|
|
3. **Estado Reactivo Centralizado:** Un objeto `state` observable que dispara re-renderizados dirigidos de elementos del DOM (tabla de subdominios, cards de telemetría, modales de confirmación) ante mutaciones.
|
|
4. **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
|
|
|
|
```mermaid
|
|
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
|
|
```
|