Replicacion

KVNode logra alta disponibilidad mediante un modelo de replicación líder-seguidor. Los cambios escritos en un nodo principal (líder) se transmiten en tiempo real a los nodos réplica (seguidores) a través de un protocolo de replicación basado en NDJSON.

Cómo Funciona la Replicación

1. Un cliente escribe un par clave-valor en cualquier nodo del clúster.
2. El nodo receptor persiste la escritura en su WAL y la aplica al almacenamiento en memoria.
3. Si el nodo tiene un padre configurado, reenvía la escritura upstream mediante el endpoint /v1/replicate.
4. Si el nodo tiene hijos, transmite la escritura a todas las réplicas conectadas a través del flujo de replicación.
5. Cada réplica aplica el cambio en su propio almacenamiento, manteniendo una copia eventualmente consistente.

Protocolo de Replicación

El endpoint de replicación (POST /v1/replicate) usa NDJSON (JSON Delimitado por Nueva Línea) como formato de transmisión. El protocolo soporta estos tipos de comando:

Ejemplo: Flujo de Replicación

1{"type":"BASELINE_BEGIN","collection":"my-collection","snapshotSeq":1}
2{"type":"SET","collection":"my-collection","key":"usuario:alice","value":{"rol":"admin"},"version":1,"timestamp":1700000000}
3{"type":"BASELINE_END","collection":"my-collection","seq":1}
4{"type":"SET","collection":"my-collection","key":"usuario:bob","value":{"rol":"usuario"},"version":1,"timestamp":1700000001}
5{"type":"PING","timestamp":1700000010}

Estado del Nodo

El endpoint /v1/status expone la topología de replicación:

1curl "https://api.hola.cloud/v1/status" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret"

Respuesta:

 1{
 2  "node": "node-1",
 3  "role": "primary",
 4  "parent": "",
 5  "collections": {
 6    "mi-coleccion": {
 7      "keys": 42,
 8      "lastSeq": 128,
 9      "walSizeBytes": 65536
10    }
11  },
12  "children": 2,
13  "uptimeSeconds": 86400,
14  "replication": {
15    "enabled": true,
16    "parent_connected": false
17  }
18}

Métricas del Nodo

Monitorea el rendimiento con el endpoint /v1/metrics:

1curl "https://api.hola.cloud/v1/metrics" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret"

Respuesta:

1{
2  "writes_total": 15000,
3  "reads_total": 82000,
4  "replication_commands_sent_total": 15000,
5  "replication_commands_received_total": 0,
6  "children_connected": 2,
7  "parent_connected": false
8}

Verificaciones de Disponibilidad

El endpoint /readyz verifica que un nodo esté listo para recibir tráfico. Para las réplicas, esto significa que la conexión con el padre debe estar establecida y el WAL completamente reproducido. Para los primarios, la disponibilidad es inmediata después del inicio.

1curl "https://api.hola.cloud/readyz"

Respuesta cuando no está listo:

1{"ok":false,"node":"node-2","role":"replica","ready":false,"checks":{"wal_replayed":true,"parent_connected":false}}

Backends de WAL Intercambiables

KVNode soporta múltiples backends de WAL, seleccionables al iniciar:

Cada backend implementa la misma interfaz de WAL, por lo que cambiar entre ellos no requiere modificaciones a nivel de aplicación.