Arquitectura de Ruta de Escritura
Este apéndice proporciona una explicación detallada de cómo fluyen los commits a través del daemon de escritura de Asset Core, desde la solicitud HTTP hasta la persistencia duradera.
Visión general
El camino de escritura está diseñado para un alto rendimiento mientras mantiene estrictas garantías de orden y semánticas de durabilidad. Combina un ingreso amplio con una ejecución serial de un solo escritor y durabilidad en múltiples etapas.
Explicación detallada
Etapas del Pipeline
El camino de escritura consiste en nueve etapas:
- Admisión: el manejador HTTP asigna un número de secuencia, adquiere permisos
- Preverificación: Validación paralela (análisis, esquema, autenticación, tamaño, idempotencia)
- Buffer de Reordenamiento: Asegura un orden de secuencia estricto
- Escritor Único: Adquiere bloqueo en tiempo de ejecución, ejecuta operaciones
- Sellado: Crea un lote de eventos, registra el log de deshacer
- Anexar Envío: Envía el lote para agregar al grupo de trabajadores
- Durabilidad: Los trabajadores llaman a fsync, devuelven el resultado
- Finalización: Actualiza el estado, responde al cliente
- Controlador/Lector: registro de Tails, actualiza proyecciones
Subsistema de Ingress
La capa de ingreso acepta solicitudes HTTP y las alimenta en la canalización:
HTTP POST → Sequence Assignment → Precheck Workers → Reorder Buffer
Componentes clave:
- Contador de secuencia: u64 atómico para un orden estricto
- Semáforo de reordenamiento: Limita el tamaño del búfer
- Cola de trabajo: Canal limitado para prever trabajadores
Este diseño proporciona retropresión cuando el sistema está sobrecargado.
Precheck Pipeline
Los trabajadores de prechequeo ejecutan pasos de validación en paralelo:
- Analizar: Deserializar JSON, calcular hash canónico
- Esquema: Validar la estructura de la operación
- Autenticación: Verificar permisos (si está configurado)
- Tamaño: Hacer cumplir los límites de tamaño de las solicitudes
- Idempotencia: Verificar commits duplicados
Cada paso devuelve Continue o ShortCircuit. Los cortocircuitos devuelven respuestas en caché sin entrar en el carril de compromiso.
Carril de Escritor Único
El escritor único serializa todas las mutaciones en tiempo de ejecución:
Validated Commit → Lock Runtime → Execute Operations → Seal Batch → Submit Append
Esto garantiza:
- No hay condiciones de carrera en el estado
- Ordenamiento determinista
- Semántica de deshacer limpia
El bloqueo de tiempo de ejecución se mantiene solo durante la ejecución, no durante la entrada/salida.
Durabilidad de la Pipeline
Lotes sellados fluyen hacia el grupo de trabajo de anexado:
Sealed Batch → Append Queue → Worker Thread → Commit Log → fsync → Result
Los trabajadores son hilos del sistema operativo (no tareas asíncronas) para manejar la entrada/salida bloqueante. Los resultados fluyen de regreso al único escritor para la finalización.
Flujo del Evento
Los eventos llevan cargas híbridas:
- Delta: Lo que cambió (para análisis)
- Estado posterior: Valor final (para reproducción)
Esto permite tanto análisis eficientes como reproducción idempotente.
Notas de implementación
Topología de Canal
El sistema utiliza canales mpsc limitados entre etapas:
| Canal | Remitente | Receptor | Límites |
|---|---|---|---|
work_tx | Manejador HTTP | Gerente de prechequeo | queue_capacity |
result_tx | Trabajadores | Buffer de reordenamiento | Limitado |
commit_tx | Buffer de reordenamiento | Escritor único | append_queue_capacity |
append_tx | Escritor único | Trabajadores de anexado | Limitado |
append_rx | Trabajadores | Escritor único | Limitado |
Las colas limitadas proporcionan retroalimentación y observabilidad.
Integración de Métricas
Cada etapa registra telemetría:
- Profundidades de la cola: Puntos de presión visibles
- Duraciones de las etapas: Donde se gasta el tiempo
- Contadores de resultados: tasas de éxito/fracaso
Las métricas utilizan una nomenclatura consistente en todas las etapas.
Semántica de Reversión
Si la adición falla:
- El escritor único aplica el registro de deshacer
- Los commits dependientes se abortan en orden inverso
- Los clientes reciben 503 con explicación
- Las métricas registran la falla
Esto asegura que el tiempo de ejecución nunca tenga estado huérfano.
Apagado Elegante
El apagado se lleva a cabo en orden:
- Dejar de aceptar nuevas solicitudes
- Drenar trabajadores de prechequeo
- Drenar el búfer de reordenamiento
- Drenar la acumulación de un solo escritor
- Espere a que los trabajadores de anexado terminen
- Persistir puntos de control finales
No se abandona ningún trabajo en medio del vuelo.
Cuándo leer esto
Lea este apéndice cuando:
- Depuración de problemas de latencia de escritura
- Comprensión de las métricas de profundidad de cola
- Modificando el pipeline de ingreso
- Investigando garantías de durabilidad
Para el uso diario, la documentación conceptual es suficiente.
Ver también
- Modelo de Ejecución - Visión general conceptual
- Frescura y Repetición - Cómo los datos llegan a los lectores
- Salud y Métricas - Monitoreo de la canalización