hicon-consensus/npm/README.md

Node.js bindings for HiCon hybrid consensus algorithm

# HiCon: Algoritmo de Consenso Híbrido CCR-CCC

[![NPM version](https://img.shields.io/npm/v/hicon-consensus.svg)](https://www.npmjs.com/package/hicon-consensus)
[![License](https://img.shields.io/npm/l/hicon-consensus.svg)](https://github.com/osvalois/hicon/blob/main/LICENSE)

Un algoritmo de consenso distribuido de alto rendimiento que combina Consenso por Redundancia de Capas Cruzadas (CCR) y Consenso por Comunicación de Capas Cruzadas (CCC) para lograr mejor escalabilidad, tolerancia a fallos y rendimiento.

## Características

- **Híbrido CCR-CCC**: Combina dos enfoques complementarios de consenso para mayor resistencia
- **Alto rendimiento**: Optimizado para alto throughput y baja latencia
- **Tolerancia a fallos**: Diseñado para ser resistente a fallos de nodos
- **Escalabilidad**: Funciona eficientemente en clusters grandes
- **Criptografía post-cuántica**: Implementación preparada para amenazas cuánticas
- **Bindings para Node.js**: API fácil de usar para aplicaciones JavaScript

## Instalación

```bash
npm install hicon-consensus
```

## Uso Básico

```javascript
const { createNode, createCluster } = require('hicon-consensus');

// Crear un solo nodo
const node = createNode({
  id: 'node-1',
  logPath: './data/node1',
  redundancyFactor: 3,
  enableEncryption: true
});

// Iniciar el nodo con una lista de peers
await node.start(['node-2', 'node-3', 'node-4']);

// Proponer un valor para consenso
const result = await node.propose({ key: 'test-key', value: 'test-value' });
console.log(`Consenso alcanzado: ${result.success}, término: ${result.term}, índice: ${result.index}`);

// O crear un clúster completo para pruebas
const cluster = await createCluster(5, 3); // 5 nodos, factor de redundancia 3

// Proponer un valor al clúster (se enruta automáticamente al líder)
const clusterResult = await cluster.propose({ key: 'cluster-key', value: 'cluster-value' });

// Simular fallos de nodos para probar tolerancia a fallos
await cluster.simulateNodeFailure(2); // Falla el tercer nodo (índice 2)
```

## API

### Clase `HiConNode`

```typescript
// Crear un nodo
const node = createNode({
  id: string,               // ID único para este nodo
  logPath?: string,         // Ruta para almacenar logs y estado (opcional)
  redundancyFactor?: number,// Factor redundancia para la capa CCR (default: 3)
  enableEncryption?: boolean// Habilitar cifrado de mensajes (default: false)
});

// Métodos disponibles
await node.start(peerIds: string[]);               // Iniciar nodo y conectar a peers
await node.propose(value: any);                    // Proponer valor para consenso
const state = node.getState();                     // Obtener estado actual del nodo
const logs = node.getLogEntries(startIndex, limit);// Obtener entradas de log
const metrics = node.getMetrics();                 // Obtener métricas de rendimiento
await node.stop();                                 // Detener nodo

// Eventos
node.on('stateChange', (oldState, newState) => {
  console.log(`Estado cambiado: ${oldState} -> ${newState}`);
});

node.on('entryCommitted', (entry) => {
  console.log(`Nueva entrada confirmada: ${entry.index}, término: ${entry.term}`);
});

node.on('leaderElected', (leaderId, term) => {
  console.log(`Nuevo líder elegido: ${leaderId} para término ${term}`);
});
```

### Clase `HiConCluster` (para pruebas)

```typescript
// Crear un clúster simulado
const cluster = await createCluster(
  nodeCount: number,        // Número de nodos en el clúster
  redundancyFactor?: number // Factor de redundancia (default: 3)
);

// Métodos disponibles
const nodes = cluster.getNodes();                    // Obtener todos los nodos
const leader = cluster.getLeader();                  // Obtener nodo líder
await cluster.propose(value: any);                   // Proponer valor (va al líder)
await cluster.simulateNodeFailure(nodeIndex: number);// Simular fallo de nodo
await cluster.restoreNode(nodeIndex: number);        // Restaurar nodo fallido
await cluster.stop();                                // Detener todos los nodos
```

## Integración con aplicaciones existentes

HiCon puede integrarse fácilmente en aplicaciones Node.js existentes para proporcionar un mecanismo de consenso robusto:

```javascript
const express = require('express');
const { createNode } = require('hicon-consensus');

const app = express();
app.use(express.json());

// Configurar nodo HiCon
const hiconNode = createNode({
  id: process.env.NODE_ID,
  logPath: './data/consensus',
  redundancyFactor: 3,
  enableEncryption: true
});

// Iniciar nodo al arrancar la aplicación
(async () => {
  // Lista de peers - en producción, esto vendría de config o discovery
  const peers = ['node-1', 'node-2', 'node-3'].filter(id => id !== process.env.NODE_ID);
  await hiconNode.start(peers);
  console.log(`Nodo HiCon iniciado con ID: ${process.env.NODE_ID}`);
})();

// Endpoint para proponer nuevos valores
app.post('/propose', async (req, res) => {
  try {
    const result = await hiconNode.propose(req.body);
    res.json({
      success: result.success,
      term: result.term,
      index: result.index
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Endpoint para consultar estado actual
app.get('/state', (req, res) => {
  res.json({
    state: hiconNode.getState(),
    metrics: hiconNode.getMetrics(),
    isLeader: hiconNode.getState() === 'leader'
  });
});

// Escuchar eventos importantes
hiconNode.on('leaderElected', (leaderId, term) => {
  console.log(`Nuevo líder: ${leaderId} en término ${term}`);
});

app.listen(3000, () => {
  console.log('API running on port 3000');
});

// Manejar shutdown gracefully
process.on('SIGINT', async () => {
  await hiconNode.stop();
  process.exit(0);
});
```

## Compilar desde el código fuente

Si necesitas compilar los bindings nativos desde el código fuente:

```bash
# Clonar el repositorio
git clone https://github.com/osvalois/hicon.git
cd hicon

# Instalar dependencias
npm install

# Compilar los bindings nativos (requiere Rust y napi-rs)
npm run build
```

## Licencia

MIT