Arquitectura del Camí de Escritura

Aquest apèndix proporciona una explicació detallada de com flueixen els commits a través del daemon d’escriptura d’Asset Core, des de la sol·licitud HTTP fins a la persistència durable.

Visió general

El camí d’escriptura està dissenyat per a un alt rendiment mentre manté garanties d’ordenació estrictes i semàntica de durabilitat. Combina una entrada àmplia amb una execució en sèrie d’un sol escriptor i durabilitat en múltiples etapes.

Explicació detallada

Etapes del Pipeline

El camí d’escriptura consta de nou etapes:

1. Admissió: el controlador HTTP assigna un número de seqüència, adquireix permisos
2. Precomprovació: Validació paral·lela (anàlisi, esquema, autenticació, mida, idempotència)
3. Reordre Buffer: Assegura un ordre de seqüència estricte
4. Escriptor Únic: Adquireix un bloqueig en temps d’execució, executa operacions
5. Segellat: Crea un lot d’esdeveniments, registra el registre d’anul·lació
6. Afegir Submissió: Envia el lot per afegir a la piscina de treballadors
7. Durabilitat: Els treballadors criden a fsync, retornen el resultat
8. Finalització: Actualitza l’estat, respon al client
9. Controlador/Lector: Registre de Tails, actualitza projeccions

Subsistema d’Ingressos

La capa d’ingressos accepta sol·licituds HTTP i les introdueix al pipeline:

HTTP POST → Sequence Assignment → Precheck Workers → Reorder Buffer

Components clau:

• Contador de seqüències: u64 atòmic per a un ordre estricte
• Reordenar semàfor: Mida del buffer de límits
• Cua de treball: Canal limitat per a la precomprovació de treballadors

Aquest disseny proporciona contrapressió quan el sistema està sobrecarregat.

Precheck Pipeline

Els treballadors de precomprovació executen passos de validació en paral·lel:

1. Analitzar: Deserialitzar JSON, calcular el hash canònic
2. Esquema: Validar l’estructura de l’operació
3. Auth: Comprovar permisos (si està configurat)
4. Mida: Fer complir els límits de mida de la sol·licitud
5. Idempotència: Comprovar si hi ha compromisos duplicats

Cada pas retorna Continue o ShortCircuit. Els curtcircuits retornen respostes emmagatzemades sense entrar al carril de compromís.

Carrer d’Escriptor Únic

El sol escriptor serialitza totes les mutacions en temps d’execució:

Validated Commit → Lock Runtime → Execute Operations → Seal Batch → Submit Append

Això garanteix:

• No hi ha condicions de competència sobre l’estat
• Ordenació determinista
• Semàntica de desfer neta

El bloqueig de temps d’execució es manté només durant l’execució, no durant l’entrada/sortida.

Durabilitat del Pipeline

Els lots segellats flueixen cap al grup de treball d’apèndix:

Sealed Batch → Append Queue → Worker Thread → Commit Log → fsync → Result

Els treballadors són fils OS (no tasques async) per gestionar I/O bloquejant. Els resultats tornen al sol escriptor per a la finalització.

Flux d’Esdeveniments

Els esdeveniments transporten càrregues híbrides:

• Delta: Què ha canviat (per a l’analítica)
• Post-estat: Valor final (per a la reproducció)

Això permet tant una analítica eficient com una reproducció idempotent.

Notes d’implementació

Topologia del Canal

El sistema utilitza canals mpsc limitats entre etapes:

Canal	Emissor	Receptor	Límits
work_tx	Gestor HTTP	Gestor de precomprovació	queue_capacity
result_tx	Treballadors	Buffer de reordenació	Limitat
commit_tx	Buffer de reordenació	Escrivà únic	append_queue_capacity
append_tx	Escrivà únic	Treballadors d’append	Limitat
append_rx	Treballadors	Escrivà únic	Limitat

Les cues limitades proporcionen pressió de retrocés i observabilitat.

Integració de Mètriques

Cada etapa registra telemetria:

• Profunditats de la cua: Punts de pressió visibles
• Durades de les etapes: On es dedica temps
• Contadors de resultats: Taxes d’èxit/fallida

Les mètriques utilitzen una nomenclatura consistent a totes les etapes.

Semàntica de Reversió

Si l’append falla:

Orientació addicional:

1. Un sol escriptor aplica el registre d’undo
2. Els commits dependents es cancel·len en ordre invers
3. Els clients reben 503 amb explicació
4. Les mètriques registren el fracàs

Això assegura que el temps d’execució mai tingui un estat orfe.

Apagat Elegant

La shutdown procedeix en ordre:

1. Deixeu d’acceptar noves sol·licituds
2. Drenatge de treballadors de precomprovació
3. Drenar el buffer de reordenament
4. Drenar el backlog d’un sol escriptor
5. Espereu que els treballadors d’append acabin
6. Persistir punts de control finals

No s’abandona cap treball a mitja volada.

Quan llegir això

Llegeix aquest annex quan:

• Depuració dels problemes de latència d’escriptura
• Comprensió de les mètriques de profunditat de la cua
• Modificant el pipeline d’entrada
• Investigant garanties de durabilitat

Per a l’ús diari, la documentació conceptual és suficient.

Veure també

• Model d’execució - Visió general conceptual
• Frescor i Repetició - Com les dades arriben als lectors
• Salut i mètriques - Monitorització del canal