Saltearse al contenido

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

Ventana de terminal
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:7687

O con la imagen oficial (consulta Instalación):

Ventana de terminal
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:

Ventana de terminal
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 purpose

Elige una:

OpciónÚsala para
--auth-token / NAMIDB_AUTH_TOKENUn bearer token de lectura y escritura.
--auth-tokens-fileVarios tokens con nombre, roles de solo lectura, alcances por namespace, recarga en caliente.
--jwt-jwks-url y relacionadosBearer tokens OIDC / JWT (compila con la feature jwt).
--no-authSolo 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

TareaPor defectoFlag
Flush de la tabla en memoria a archivos de datos de nivel 0cada 30s, y en cuanto contiene 64 MiB--flush-interval, --memtable-flush-bytes
Compactar los archivos de nivel 0 y hacer sweep de los objetos inalcanzablescada 300s, y en cuanto un bucket contiene 8 archivos L0--compaction-interval, --compaction-l0-trigger
Borrar los objetos que ningún manifest vivo referenciadurante el sweep, solo si tienen más de 24h--sweep-min-age, --sweep-delete
Recargar --auth-tokens-filecada 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 con NAMIDB_MAX_CONCURRENT_SCANS (por defecto 4). Una lectura que no obtiene un slot dentro de NAMIDB_QUERY_ADMISSION_WAIT_MS (5000 ms) recibe un 503 reintentable.
  • Group commit (opcional). --group-commit-window 2ms (hasta 5ms) 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 defecto 0s confirma cada escritura por separado.
  • Leer tus propias escrituras. Una sentencia ve sus propias cláusulas anteriores (CREATE … WITH … MATCH encuentra lo que acaba de crear), y cada petición ve todas las escrituras confirmadas antes de ella.

Timeouts y límites

LímitePor defectoFlagAl superarse
Tiempo real de una sentencia de lectura30s--query-timeout504, code: "timeout"
Tiempo real de una sentencia de escritura60s--write-timeout504, code: "timeout"; no se confirma nada
Filas que cualquier operador de lectura puede materializar1000000--query-row-cap413, code: "row_cap"
Petición HTTP completaderivado (≥ 120 s, y 30 s por encima del mayor presupuesto de sentencia)--http-request-timeout408
Cuerpo de la petición HTTP para /v0/cypher2 MiB—413
Peticiones HTTP concurrentes1024NAMIDB_HTTP_MAX_CONCURRENCYen cola
Transacción explícita de Bolt inactiva30s--bolt-tx-timeoutrollback

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:

Ventana de terminal
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étodoRutaAutenticaciónPropósito
GET/v0/livezpúblicaLiveness. No toma locks ni lee ningún namespace.
GET/v0/healthpúblicaReadiness: versión del manifest, epoch, estado del writer, memoria. 503 cuando está degradado.
GET/v0/versionpública{"version":"3.3.0","build_target":"namidb-server"}
GET/v0/metricspúblicaExposición en texto de Prometheus.
POST/v0/cyphertokenEjecuta una sentencia Cypher.
POST/v0/admin/flushtoken de lectura y escrituraHace flush ahora.
POST/v0/admin/compacttoken de lectura y escrituraVacía el nivel 0 y espera.
POST/v0/admin/backuptoken de lectura y escrituraBackup en línea (requiere --backup-target-uri), también a un instante anterior.
GET/v0/admin/restore-pointstoken de lectura y escrituraLa ventana de puntos de restauración (Puntos de restauración).
GET/v0/admin/queriestoken de lectura y escrituraLista las consultas en curso.
POST/v0/admin/queries/:id/canceltoken de lectura y escrituraCancela una.

Formatos de petición y respuesta: API HTTP. Rutas multi-tenant: Modo multi-tenant.