Mercury Core

API HTTP em Nim para ingestão massiva de JSON com foco em throughput, latência e observabilidade

---

Documentação Modular

A documentação técnica foi organizada em módulos para facilitar onboarding e manutenção:

• docs/README.md
• docs/ARQUITETURA.md
• docs/API.md
• docs/OPERACAO_DEPLOY_MANUTENCAO.md
• docs/OBSERVABILIDADE_E_BENCHMARK.md
• docs/TESTES_AUTOMATIZADOS.md
• docs/METRICAS_AUTOMACAO_SHELL.md
• docs/ROADMAP_TECNICO.md

---

Módulo Frontend (Opcional)

O frontend Vue 3 é um console opcional para operação local e demonstração da API. O core do projeto continua sendo o backend Nim (src/velocitycore).

Quando usar o frontend:

• validação manual de fluxos de ingestão/cache/benchmark;
• demos técnicas e onboarding de novos colaboradores.

Quando não usar:

• execução de benchmark focada no core backend;
• cenários de deploy onde apenas a API é necessária.

Preview do console:

• frontend dev server: http://127.0.0.1:5173
• backend API: http://127.0.0.1:8080

---

Visão Geral

O Mercury Core é um backend HTTP escrito em Nim com foco em previsibilidade de latência e alta taxa de ingestão.

O projeto prioriza:

• I/O assíncrono com asynchttpserver e asyncdispatch;
• processamento paralelo de lotes em chunks;
• cache sharded com lock striping;
• métricas internas em tempo real;
• superfície de API enxuta para uso operacional.

---

Principais Recursos

• Ingestão massiva em POST /api/v1/ingest.
• Cache de lotes por batchId em GET /api/v1/cache.
• Métricas operacionais em GET /api/v1/benchmark.
• Simulação concorrente via POST /api/v1/simulate.
• Streaming NDJSON em GET /api/v1/stream.
• CLI integrada para benchmark de ingestão.

---

Arquitetura

Fluxo principal:

1. src/velocitycore.nim inicia a CLI.
2. src/velocitycore/cli.nim escolhe server ou bench.
3. src/velocitycore/server.nim recebe e roteia requests.
4. src/velocitycore/processor.nim agrega lotes em paralelo.
5. src/velocitycore/cache.nim mantém resultados de lotes em memória.
6. src/velocitycore/metrics.nim publica indicadores de saúde/performance.

---

Resultado Oficial de Testes Automatizados

Resultado de referência da automação local antes de publicação:

• Data: 2026-04-02 (America/Sao_Paulo)
• Execução: 2026-04-02T19:34:26-03:00
• Script: ./scripts/run_tests.sh
• Artefatos:
  • docs/reports/latest_test_report.md
  • docs/reports/latest_test_report.raw.log

Etapa	Status	Duração
Testes unitários Nim (tests/test_velocitycore.nim)	ok	161 ms
Build release backend (src/velocitycore.nim)	ok	2180 ms
Smoke test HTTP (scripts/http_smoke_test.sh)	ok	309 ms
Frontend build check (frontend)	skipped	0 ms

Observação técnica:

• Frontend pode ser pulado no ciclo backend-only com SKIP_FRONTEND=1.

---

Desafios Técnicos e Decisões

• Concorrência: chunking + workers para reduzir gargalo em lotes grandes.
• Observabilidade leve: atômicos para contadores globais sem lock global em hot path.
• Cache em memória: design simples e rápido com limpeza periódica (pruneOld).
• Trade-off atual: uso de pool de tarefas (taskpools) adiciona dependência externa para manter a concorrência suportada e sem warning de depreciação.

---

Roadmap

Próximos passos recomendados:

• incluir baseline de benchmark automatizado por versão;
• evoluir estratégia de exportação de métricas.

---

Stack Tecnológica

• Linguagem: Nim
• HTTP assíncrono: asynchttpserver, asyncdispatch
• Concorrência: taskpools
• Frontend (opcional): Vue 3 + Vite
• Automação de testes: shell script (scripts/run_tests.sh)

---

Estrutura do Projeto

.
├── docs/
│   ├── assets/
│   │   └── mercury-core-logo.png
│   ├── reports/
│   │   ├── latest_test_report.md
│   │   └── latest_test_report.raw.log
│   ├── API.md
│   ├── ARQUITETURA.md
│   ├── BENCHMARKS.md
│   ├── METRICAS_AUTOMACAO_SHELL.md
│   ├── OBSERVABILIDADE_E_BENCHMARK.md
│   ├── OPERACAO_DEPLOY_MANUTENCAO.md
│   ├── README.md
│   ├── ROADMAP_TECNICO.md
│   └── TESTES_AUTOMATIZADOS.md
├── frontend/
├── scripts/
│   ├── node_bench.js
│   ├── python_bench.py
│   ├── http_smoke_test.sh
│   └── run_tests.sh
├── src/
│   ├── velocitycore.nim
│   └── velocitycore/
├── tests/
│   └── test_velocitycore.nim
├── nim.cfg
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
└── velocitycore.nimble

---

Como Rodar Localmente

Pré-requisitos

• Nim >= 2.0
• Node >= 18 (apenas para frontend e validação completa com run_tests.sh)
• npm (apenas para frontend e validação completa)

Backend

nimble run -d:release -- server 8080

Frontend (opcional)

cd frontend
npm install
npm run dev

Endpoints principais

• GET /health
• POST /api/v1/ingest
• GET /api/v1/cache?batchId=<id>
• GET /api/v1/benchmark
• POST /api/v1/simulate?ops=<n>&workers=<n>
• GET /api/v1/stream?count=<n>

---

Deploy Local com Docker

Build e subida

docker compose up -d --build

Se a porta 8080 já estiver ocupada:

HOST_PORT=8081 docker compose up -d --build

Operação

docker compose logs -f mercury-core
docker compose down

Acesso

• aplicação: http://127.0.0.1:${HOST_PORT:-8080}
• health check: curl -i http://127.0.0.1:${HOST_PORT:-8080}/health

---

Scripts Principais

• ./scripts/run_tests.sh: executa validação automatizada completa (backend + frontend) e gera relatório em docs/reports.
• SKIP_FRONTEND=1 ./scripts/run_tests.sh: executa validação focada no core backend.
• ./scripts/http_smoke_test.sh: sobe servidor real e valida endpoints críticos com curl.
• nimble run -d:release -- server 8080: sobe a API.
• nimble run -d:release -- bench <url> <requests> <concorrencia> <records>: benchmark da API.
• node scripts/node_bench.js ...: benchmark comparativo Node.
• python3 scripts/python_bench.py ...: benchmark comparativo Python.
• docker compose up -d --build: builda imagem e sobe serviço containerizado.
• docker compose down: finaliza stack local.

---

Licença

Este projeto é open source sob licença MIT.

Consulte LICENSE quando o arquivo for incluído no repositório.