Servidor HTTP
namidb-server sirve un namespace (o, con --multi-tenant, muchos) por
una API HTTP JSON y, opcionalmente, por Bolt para drivers de Neo4j. Es el
mismo motor que la librería embebida; el servidor agrega autenticación,
mantenimiento en segundo plano, control de admisión, métricas y endpoints
de administración.
Iniciarlo
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"
namidb-server \ --store "file:///var/lib/namidb?ns=prod" \ --listen 0.0.0.0:8080 \ --bolt-listen 0.0.0.0:7687O con la imagen oficial (consulta Instalación):
docker run -d --name namidb -p 8080:8080 -p 7687:7687 \ -v namidb-data:/var/lib/namidb \ -e NAMIDB_AUTH_TOKEN \ -e NAMIDB_BOLT_LISTEN=0.0.0.0:7687 \ namidb/namidb-server:3.3.0 --store "file:///var/lib/namidb?ns=prod"Cada flag también lee una variable de entorno (--store ↔ NAMIDB_STORE,
--listen ↔ NAMIDB_LISTEN, …); un flag en la línea de comandos gana sobre
la variable. La lista completa está en la
referencia de configuración.
Comprueba que está arriba:
curl -s localhost:8080/v0/health# {"status":"ok","namespace":"prod","manifest_version":0,"epoch":0,"writer":"ok","memtable_bytes":0,...}
curl -s localhost:8080/v0/cypher \ -H "Authorization: Bearer $NAMIDB_AUTH_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"query": "RETURN 1 + 41 AS n"}'# {"columns":["n"],"rows":[{"n":42}]}La autenticación es obligatoria
Desde 2.2.0 el servidor se niega a arrancar sin una fuente de autenticación:
Error: no auth configured: set --auth-token / NAMIDB_AUTH_TOKEN or --auth-tokens-file,or pass --no-auth / NAMIDB_NO_AUTH=1 to run without auth on purposeElige una:
| Opción | Úsala para |
|---|---|
--auth-token / NAMIDB_AUTH_TOKEN | Un bearer token de lectura y escritura. |
--auth-tokens-file | Varios tokens con nombre, roles de solo lectura, alcances por namespace, recarga en caliente. |
--jwt-jwks-url y relacionados | Bearer tokens OIDC / JWT (compila con la feature jwt). |
--no-auth | Solo desarrollo local: cada petición es anónima de lectura y escritura. |
Los endpoints de salud, liveness, versión y métricas son siempre públicos. Detalles: Autenticación.
Qué se ejecuta en segundo plano
| Tarea | Por defecto | Flag |
|---|---|---|
| Flush de la tabla en memoria a archivos de datos de nivel 0 | cada 30s, y en cuanto contiene 64 MiB | --flush-interval, --memtable-flush-bytes |
| Compactar los archivos de nivel 0 y hacer sweep de los objetos inalcanzables | cada 300s, y en cuanto un bucket contiene 8 archivos L0 | --compaction-interval, --compaction-l0-trigger |
| Borrar los objetos que ningún manifest vivo referencia | durante el sweep, solo si tienen más de 24h | --sweep-min-age, --sweep-delete |
Recargar --auth-tokens-file | cada 10s | --auth-tokens-reload-interval |
| Watchdog de memoria (cuando hay un tope definido) | cada 500 ms | --memory-max-bytes |
Define --flush-interval 0s o --compaction-interval 0s para apagar un
temporizador y conducir el trabajo con los
endpoints de administración.
Consulta Mantenimiento para ver
qué hace cada paso.
Cómo se atienden las peticiones
- Un writer por namespace. Las escrituras y el DDL toman el lock del
writer del namespace de a una. Una escritura que espera más de
--writer-lock-timeout(30 s) falla rápido con HTTP 503 en lugar de quedar en cola indefinidamente. - Las lecturas no toman el lock del writer. Las lecturas HTTP, las lecturas auto-commit de Bolt y las transacciones de lectura de Bolt se ejecutan sobre el último snapshot publicado, así que una escritura larga nunca bloquea las lecturas y viceversa.
- Admisión de lecturas. Las lecturas concurrentes se limitan en todo el
proceso con
NAMIDB_MAX_CONCURRENT_QUERIES(por defecto: la cantidad de núcleos de CPU, mínimo 4) y los full scans por separado conNAMIDB_MAX_CONCURRENT_SCANS(por defecto 4). Una lectura que no obtiene un slot dentro deNAMIDB_QUERY_ADMISSION_WAIT_MS(5000 ms) recibe un 503 reintentable. - Group commit (opcional).
--group-commit-window 2ms(hasta5ms) permite que las escrituras que llegan juntas compartan un append al WAL y un commit del manifest. Cada petición se sigue confirmando solo después de que su grupo es durable, y se mantiene read-your-own-writes. Las escrituras agrupadas comparten el destino si el commit falla. El valor por defecto0sconfirma cada escritura por separado. - Leer tus propias escrituras. Una sentencia ve sus propias cláusulas
anteriores (
CREATE … WITH … MATCHencuentra lo que acaba de crear), y cada petición ve todas las escrituras confirmadas antes de ella.
Timeouts y límites
| Límite | Por defecto | Flag | Al superarse |
|---|---|---|---|
| Tiempo real de una sentencia de lectura | 30s | --query-timeout | 504, code: "timeout" |
| Tiempo real de una sentencia de escritura | 60s | --write-timeout | 504, code: "timeout"; no se confirma nada |
| Filas que cualquier operador de lectura puede materializar | 1000000 | --query-row-cap | 413, code: "row_cap" |
| Petición HTTP completa | derivado (≥ 120 s, y 30 s por encima del mayor presupuesto de sentencia) | --http-request-timeout | 408 |
Cuerpo de la petición HTTP para /v0/cypher | 2 MiB | — | 413 |
| Peticiones HTTP concurrentes | 1024 | NAMIDB_HTTP_MAX_CONCURRENCY | en cola |
| Transacción explícita de Bolt inactiva | 30s | --bolt-tx-timeout | rollback |
Define un presupuesto en 0s (o el límite de filas en 0) para quitarlo.
Para una carga masiva puntual, divide las escrituras en partes o define
NAMIDB_WRITE_TIMEOUT=0s.
Bolt
Agrega --bolt-listen 0.0.0.0:7687 para aceptar drivers y herramientas de
Neo4j sobre el mismo namespace, con los mismos tokens y la misma
configuración TLS. Consulta Bolt.
TLS
Pasa --tls-cert y --tls-key (PEM) para servir HTTPS y Bolt sobre TLS
desde los mismos listeners. Sin ellos el servidor habla en texto plano; en
ese caso termina TLS delante de él. Consulta TLS.
Logs
El servidor escribe logs en stdout mediante tracing. Controla el nivel con
RUST_LOG:
RUST_LOG=info,namidb_storage=debug namidb-server --store "file:///var/lib/namidb?ns=prod"Las sentencias que igualan o superan --slow-query-threshold (por defecto
1s) se registran en WARN con su texto (nunca con sus parámetros).
Consulta Monitoreo.
Apagado
Con SIGTERM o Ctrl-C el servidor deja de aceptar conexiones, termina las
peticiones HTTP y las sesiones Bolt en curso, y sale. Las escrituras
confirmadas ya son durables en el WAL, así que no se pierde nada confirmado
si el proceso se mata; el siguiente arranque reproduce el WAL.
Endpoints
| Método | Ruta | Autenticación | Propósito |
|---|---|---|---|
GET | /v0/livez | pública | Liveness. No toma locks ni lee ningún namespace. |
GET | /v0/health | pública | Readiness: versión del manifest, epoch, estado del writer, memoria. 503 cuando está degradado. |
GET | /v0/version | pública | {"version":"3.3.0","build_target":"namidb-server"} |
GET | /v0/metrics | pública | Exposición en texto de Prometheus. |
POST | /v0/cypher | token | Ejecuta una sentencia Cypher. |
POST | /v0/admin/flush | token de lectura y escritura | Hace flush ahora. |
POST | /v0/admin/compact | token de lectura y escritura | Vacía el nivel 0 y espera. |
POST | /v0/admin/backup | token de lectura y escritura | Backup en línea (requiere --backup-target-uri), también a un instante anterior. |
GET | /v0/admin/restore-points | token de lectura y escritura | La ventana de puntos de restauración (Puntos de restauración). |
GET | /v0/admin/queries | token de lectura y escritura | Lista las consultas en curso. |
POST | /v0/admin/queries/:id/cancel | token de lectura y escritura | Cancela una. |
Formatos de petición y respuesta: API HTTP. Rutas multi-tenant: Modo multi-tenant.