Metadata-Version: 2.4
Name: nexaql-core
Version: 0.1.0
Summary: High-performance binary protocol gateway bridging legacy SOAP/XML and modern Web/Edge architectures.
Home-page: https://github.com/YsaiasPeru/nexuql
Author: Ysaias
Author-email: contacto@nexaql.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: msgpack>=1.0.5
Requires-Dist: cryptography>=41.0.0
Requires-Dist: pydantic>=2.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

﻿<div align="center">

# ⚡ NexaQL Protocol

### *El pasado y el presente, para lograr el futuro.*
### *Para que la comunicacion no sea un mito, sino una realidad pura.*

[![Version](https://img.shields.io/badge/version-0.1.0--experimental-f1c40f?style=for-the-badge)](.)
[![License](https://img.shields.io/badge/license-MIT-2ecc71?style=for-the-badge)](./LICENSE)
[![Python](https://img.shields.io/badge/python-3.11+-3776ab?style=for-the-badge&logo=python)](.)
[![TypeScript](https://img.shields.io/badge/typescript-6.0+-3178c6?style=for-the-badge&logo=typescript)](.)
[![WebSocket](https://img.shields.io/badge/transport-WebSocket-e74c3c?style=for-the-badge)](.)
[![AES-GCM](https://img.shields.io/badge/security-AES--256--GCM-27ae60?style=for-the-badge)](.)

</div>

---

## El problema que nadie ha resuelto (hasta ahora)

Las organizaciones empresariales viven atrapadas en una paradoja tecnologica:

- Tienen sistemas **SOAP/XML de los 90s** que no pueden apagar porque procesan millones de transacciones al dia.
- Necesitan **aplicaciones moviles y web modernas** que esperan APIs rapidas, ligeras y seguras.
- Cada protocolo existente (REST, GraphQL, gRPC) resuelve **una parte** del problema, pero ninguno habla con el pasado Y el futuro al mismo tiempo.

**NexaQL resuelve esto de raiz.** Es el primer protocolo binario disenado para ser simultaneamente:

> **Compatible con el Pasado** (traduce a SOAP/XML nativo) +  
> **Optimo en el Presente** (binario, comprimido, cifrado) +  
> **Listo para el Futuro** (Edge Computing, V8 Isolates, Serverless)

---

## Benchmark en Vivo (100,000 registros reales)

| Protocolo | Tamano | Tiempo | Reduccion |
|---|---|---|---|
| XML/SOAP (El Pasado) | 10,465 KB | 2,313 ms | — |
| JSON/REST (El Presente) | 10,747 KB | 2,898 ms | -2.7% |
| **NexaQL (El Futuro)** | **998 KB** | **426 ms** | **-90.5%** |

> NexaQL transporta los mismos datos en menos de 1 MB lo que XML/REST envian en mas de 10 MB.
> Es 10x mas compacto y 5x mas rapido. Medido en vivo, no en teoria.

---

## Capacidades

| Capacidad | XML/REST | JSON/REST | GraphQL | gRPC | NexaQL |
|---|---|---|---|---|---|
| Compresion nativa | No | No | No | Si | **Si** |
| Cifrado E2E nativo (AES-GCM) | No | No | No | No | **Si** |
| Streaming bidireccional | No | No | Parcial | Si | **Si** |
| Multiplexing de esquemas | No | No | No | Si | **Si** |
| Filtros binarios (anti-overfetch) | No | No | Parcial | No | **Si** |
| Tipos nativos (Date, Decimal) | No | No | No | Si | **Si** |
| Schema Evolution zero-downtime | No | No | Parcial | No | **Si** |
| Error Frames binarios | No | No | No | No | **Si** |
| Edge/Serverless V8 nativo | Parcial | Parcial | Parcial | No | **Si** |
| Puente Legacy SOAP/XML | Si | No | No | No | **Si** |

**NexaQL es el UNICO protocolo que cumple con todos los requisitos modernos.**

---

## Arquitectura

```
[Browser / Mobile Client]
        |
        | WebSocket Binary Frames / HTTP POST (octet-stream)
        |
  [NexaQL Gateway (Python FastAPI)]    [Edge Worker (Node.js V8 / Cloudflare)]
   Schema Registry                      Simulador V8 Isolate
        |                                        |
        +------------ Traduce NexaQL -> SOAP/XML ---------> [Legacy Database]
```

### Estructura del Frame Binario

```
Offset  Longitud  Campo
0       2 bytes   Magic Bytes "NX" (0x4E 0x58)
2       2 bytes   Version (uint16 BE)
4       1 byte    Schema ID (multiplexing)
5       1 byte    Flags: 0x01=Zlib | 0x02=AES-GCM | 0x04=Error
6       4 bytes   Payload Length (uint32 BE)
10      4 bytes   CRC32 Checksum
14      N bytes   Payload (MsgPack + Zlib + AES-GCM)
```

---

## Las 11 Fases del Protocolo

| Fase | Nombre | Descripcion |
|---|---|---|
| 1-4 | **Foundation** | Frame binario, Zlib, Diccionario de Tipos, AES-GCM |
| 5 | **Streaming Transport** | WebSocket con chunks de 10k registros |
| 6 | **Multiplexing + ExtTypes** | Dos schemas en una sola conexion, Date y Decimal nativos |
| 7 | **Universal Translator** | Frontend escribe en NexaQL, Gateway entrega SOAP/XML |
| 8 | **Schema Registry** | Evolucion de schemas sin downtime ni parsers rotos |
| 9 | **Binary Query Engine** | Filtros binarios encriptados: anti-overfetch real |
| 10 | **Error Frames** | Errores fatales del servidor viajan cifrados al cliente |
| 11 | **Edge Computing** | SDK isomorfico corriendo en V8 sin servidor Python |
| 12 | **Benchmark + RFC** | Especificacion formal y medicion comparativa real |
| 13 | **WSDL Auto-Parser** | Generacion automatica de schemas desde SOAP XML |
| 14 | **Offline-First Sync** | Interceptor automatico con IndexedDB para caidas de red |
| 15 | **P2P WebRTC** | Intercambio binario y descentralizado de navegador a navegador |
| 16 | **WebAssembly Core** | Núcleo de alto rendimiento escrito en Rust para el navegador |
| 17 | **Criptografía ECDH + HKDF** | Handshake Zero-Knowledge con Curvas Elípticas (P-256) |
| 18 | **Suite de Pruebas Automáticas** | Tests unitarios con PyTest para integración CI/CD |

---

## Estructura del Repositorio

```
nexaql/
 |-- nexaql/                  # Gateway (Python / FastAPI)
 |   |-- server/
 |   |   |-- main.py          # Endpoints HTTP + WebSocket
 |   |   |-- registry.py      # Schema Registry
 |   |-- protocol/
 |   |   |-- encoder.py       # MsgPack + Zlib + AES-GCM
 |   |   |-- decoder.py       # Deserializacion + hidratacion
 |   |   |-- frame.py         # Frame binario con CRC32
 |   |   |-- security.py      # AES-256-GCM
 |   |-- legacy/
 |       |-- xml_adapter.py   # Adaptador bidireccional SOAP/XML
 |
 |-- frontend/                # SDK + UI (TypeScript / React)
 |   |-- src/
 |       |-- nexaql-client/
 |       |   |-- client.ts    # Cliente principal
 |       |   |-- encoder.ts   # Encoder isomorfico
 |       |   |-- decoder.ts   # Decoder isomorfico
 |       |   |-- frame.ts     # Frame encoder/decoder + CRC32
 |       |-- App.tsx          # Dashboard de demostracion
 |
 |-- edge/                    # Edge Worker (Node.js V8)
 |   |-- worker.ts            # Simulador Cloudflare Worker
 |
 |-- NEXAQL_PROTOCOL_SPEC.md  # Especificacion formal (estilo RFC)
 |-- README.md
```

---

## Como ejecutarlo localmente

### Requisitos
- Python 3.11+
- Node.js v22+

### 1. Backend Gateway
```bash
# Crear entorno virtual
python -m venv venv
.\venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Instalar dependencias
pip install fastapi uvicorn msgpack cryptography pydantic

# Iniciar el Gateway
uvicorn nexaql.server.main:app --reload
# -> http://localhost:8000
```

### 2. Edge Worker (nueva terminal)
```bash
node --experimental-strip-types edge/worker.ts
# -> http://localhost:8001
```

### 3. Frontend React (nueva terminal)
```bash
cd frontend
npm install
npm run dev
# -> http://localhost:5173
```

### 4. Probar el protocolo

Abre `http://localhost:5173` y ejecuta en orden:

1. **Fetch NexaQL (Native)** - Compara velocidad vs XML/JSON
2. **Stream NexaQL (Batch)** - Streaming de 100k registros en chunks
3. **Filtro Binario** - Activa el checkbox y mira como el servidor filtra en el backend
4. **Crash BD** - Simula un colapso y observa el Error Frame elegante
5. **Emitir Transaccion** - Escribe en NexaQL, el Edge lo traduce a SOAP/XML
6. **Benchmark Oficial** - Mide los numeros reales en tu maquina

---

## Documentacion

- [NEXAQL_PROTOCOL_SPEC.md](./NEXAQL_PROTOCOL_SPEC.md) - Especificacion formal completa (estilo RFC IETF)

---

## Roadmap

- [ ] SDK de TypeScript publicado en npm (`nexaql-client`)
- [ ] Gateway en Docker (imagen oficial)
- [ ] Soporte de TLS nativo en el Gateway
- [ ] Wasm binary target para browsers antiguos
- [ ] CLI: `nexaql generate-schema` desde JSON/Protobuf
- [ ] Integracion con Cloudflare Workers real

---

## Filosofia

> "El pasado no es un problema a eliminar. Es la base sobre la cual el futuro se construye.  
> NexaQL no reemplaza lo que funciona. Lo conecta con lo que viene."

Este protocolo nacio de una conviccion simple: la brecha entre sistemas Legacy y arquitecturas modernas no se cierra con migraciones costosas, sino con un lenguaje comun que todos puedan hablar. NexaQL es ese lenguaje.

---

## Licencia

MIT License - Ver [LICENSE](./LICENSE)

---

<div align="center">

**Construido con la conviccion de que la comunicacion no debe ser un mito.**

⭐ Si este proyecto te parece valioso, una estrella ayuda a que mas personas lo encuentren.

</div>





## 🐳 Despliegue Empresarial (Docker)

Para instalar el Gateway NexaQL en cualquier infraestructura (AWS, Azure, On-Premise) sin tocar bases de datos antiguas, utilizamos **Docker**.

1. **Clonar y levantar el contenedor:**
   `ash
   git clone https://github.com/YsaiasPeru/nexuql.git
   cd nexuql
   docker-compose up -d --build
   `

2. **Configuración de Entorno:**
   El archivo docker-compose.yml expone el servicio en el puerto 8000. Puedes modificar la variable de entorno LEGACY_SOAP_URL para apuntar a tu sistema antiguo.

## 📦 Distribución (PyPI & NPM)

NexaQL está diseñado para ser integrado rápidamente en cualquier ecosistema:

**Backend (Python Gateway)**
`ash
pip install nexaql-core
`
*Incluye el Gateway asíncrono, decodificadores binarios, encriptación ECDH y el adaptador legacy.*

**Frontend (Web/Mobile Client)**
`ash
npm install nexaql-client
`
*Incluye el cliente TypeScript con soporte Offline-First (IndexedDB), sincronización P2P (WebRTC) y encriptación nativa WebCrypto.*
