Arquitectura de Arxi Sidecar

Audience: Engineers implementing or operating arxi-sidecar as the Audiencia: Ingenieros que implementan o operan arxi-sidecar como el servicio de grabación de evidencia accesible a través de la red.

Tabla de Contenidos

Resumen Ejecutivo
Composición en Tiempo de Ejecución
HTTP Superficie y Enrutamiento
Controles de Seguridad y Recursos
Idempotencia y Seguridad de Reintentos
Transporte y Ciclo de Vida
Empaque de Contenedores y Operaciones de Docker
Validación y Cobertura de Pruebas
Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

arxi-sidecar es el tiempo de ejecución del servicio HTTP/JSON de Arxi que expone grabador, consulta y flujos de trabajo de paquete a través de socket Unix y/o oyentes TCP.

El sidecar compone RecorderEngine, BundleBuilder, Verifier y una única instancia de SqliteStore bajo puertas de middleware explícitas para la identidad de correlación, autenticación, identidad/política empresarial, aplicación de límites, idempotencia y control de tiempo de espera.

F:crates/arxi-sidecar/src/server.rs L42-L133 F:crates/arxi-sidecar/src/state.rs L29-L56 F:crates/arxi-sidecar-config/src/config.rs

Composición en Tiempo de Ejecución

Flujo de inicio:

Load and validate TOML config (config_version, api.major_version, Cargar y validar la configuración TOML (config_version, api.major_version, recorder, transport, security, signer y limits).
Inicializar el seguimiento y abrir SqliteStore.
Construir componentes de tiempo de ejecución del grabador.
Inicializar el gestor de idempotencia persistente en store_meta.
Construir el enrutador axum con la pila de middleware.
Vincular los oyentes de transporte configurados y servir hasta la cancelación.

F:crates/arxi-sidecar-config/src/config.rs F:crates/arxi-sidecar-config/src/validation.rs F:crates/arxi-sidecar/src/server.rs L43-L247 F:crates/arxi-sidecar/src/idempotency.rs L61-L138

HTTP Superficie y Enrutamiento

El enrutador actualmente expone:

Sondeos: GET /health, GET /startup, GET /ready
Segment lifecycle: POST /v1/segments, POST /v1/segments/seal, Ciclo de vida del segmento: POST /v1/segments, POST /v1/segments/seal, GET /v1/segments, GET /v1/segments/active
Envelope ingest: POST /v1/envelopes, Ingesta de sobres: POST /v1/envelopes, POST /v1/envelopes/with-attachments
Consulta: POST /v1/query/envelopes
Bundle workflows: POST /v1/bundles/build, POST /v1/bundles/verify, Agrupar flujos de trabajo: POST /v1/bundles/build, POST /v1/bundles/verify, POST /v1/bundles/inspect
Inspección en tiempo de ejecución: GET /v1/config

F:crates/arxi-sidecar/src/server.rs L135-L160

Comportamiento de salud:

GET /health es una verificación de disponibilidad ligera que devuelve metadatos del proceso.
GET /startup is a startup-completion probe returning startup metadata, GET /startup es una sonda de finalización de inicio que devuelve metadatos de inicio, incluyendo la startup_verification_depth configurada.
GET /ready returns readiness state with dependency-aware fail-closed semantics:
- 503 con razón=storage_unavailable cuando falla el acceso a la tienda.
- Optional 503 with reason=request_capacity_exhausted when probes.ready_fail_on_admission_saturation=true and admission/execution los semáforos están agotados.
- Optional 503 with reason=enterprise_control_unavailable when probes.readiness_mode=storage_and_enterprise, enterprise mode is enabled, Opcional 503 con reason=enterprise_control_unavailable cuando probes.readiness_mode=storage_and_enterprise, el modo empresarial está habilitado y las comprobaciones de disponibilidad del plano de control fallan.
- 200 con ready=true en estado estable.

F:crates/arxi-sidecar/src/handlers/health.rs L42-L94

Controles de Seguridad y Recursos

Config Gate

La validación de la configuración es de cierre seguro y aplica:

esquema estricto y versionado de API,
validez del ID del grabador y del auto-sello,
restricciones de host/puerto de transporte,
non-loopback transport requires security.mode=token and keeps el transporte no de bucle requiere security.mode=token y mantiene require_token_for_non_loopback=true (cerrado por defecto),
token file hardening (security.token_file cannot be a symlink, must be a endurecimiento del archivo de token (security.token_file no puede ser un enlace simbólico, debe ser un archivo regular y en Unix no debe otorgar permisos de grupo/otros),
analizabilidad de la clave del firmante,
límites numéricos de idempotencia en la solicitud/cabecera y verificaciones de límite máximo,
probe config fail-closed semantics: probes.enterprise_health_path must be absolute/safe and probes.readiness_mode=storage_and_enterprise requires enterprise mode not deshabilitado.

F:crates/arxi-sidecar-config/src/config.rs F:crates/arxi-sidecar-config/src/validation.rs

Middleware Stack

Orden y controles del middleware:

Capa de límite del cuerpo de la solicitud (max_request_body_bytes).
Capa de trazado.
Correlation middleware (server correlation IDs, sanitized client Middleware de correlación (IDs de correlación del servidor, x-correlation-id sanitizado, compatibilidad con x-request-id heredado).
Auth middleware (Bearer token mode with constant-time compare and RFC 6750 Middleware de autenticación (Bearer token en modo con comparación en tiempo constante y metadatos de desafío RFC 6750 en respuestas 401).
Enterprise identity middleware (x-tenant-id, x-principal-id, x-authn-method, optional x-namespace-id, optional writer lease assertion) para modos habilitados para empresas.
Enterprise policy middleware (control-plane ingress checks for protected routes plus sidecar boundary hook emission at admission and result fases).
Bounds middleware (header bytes, content negotiation, content-length checks, Middleware de límites (bytes de encabezado, negociación de contenido, verificaciones de longitud de contenido, cola de admisión limitada, concurrencia activa limitada, tiempo de espera de solicitud).

Comportamiento de prioridad de sondeo:

/health, /startup, and /ready are exempted from auth, enterprise policy, and bounds gating so liveness/startup/readiness state remains observable under sobrecarga o fallos de política.

F:crates/arxi-sidecar/src/server.rs L155-L160 F:crates/arxi-sidecar/src/middleware/request_id.rs L15-L30 F:crates/arxi-sidecar/src/middleware/auth.rs L21-L84 F:crates/arxi-sidecar/src/control_plane_bridge.rs F:crates/arxi-sidecar/src/middleware/enterprise.rs F:crates/arxi-sidecar/src/middleware/bounds.rs L21-L172

Controles de Límite Empresarial

Cuando enterprise.mode está habilitado, el sidecar añade un control explícito de la aplicación de límites del plano de control mientras preserva la semántica del grabador/evidencia:

crates/arxi-sidecar/src/control_plane_bridge.rs is a boundary adapter only. It translates sidecar ingress identities/operations into control-plane crates/arxi-sidecar/src/control_plane_bridge.rs es un adaptador de frontera únicamente. Traduce las identidades/operaciones de ingreso del sidecar en llamadas de admisión y gancho del plano de control; no implementa ni altera la matemática de evidencia de Arxi.
Enterprise config is fail-closed: enabled mode requires token security mode, La configuración empresarial es de cierre en caso de fallo: el modo habilitado requiere el modo de seguridad de token, la configuración de URL/token del plano de control y verificaciones de archivos de token endurecidos.
Enterprise policy gate calls Llamadas de puerta de política empresarial POST /v1/enterprise/ingress/check antes de las operaciones de sidecar protegidas.
Managed-cloud mode enforces writer-lease assertion for mutating operations El modo de nube gestionada impone la afirmación de arrendamiento de escritor para operaciones mutantes cuando require_writer_lease_header=true.
Sidecar emits deterministic enterprise boundary hooks to POST /v1/enterprise/sidecar/hooks at:
- admisión (permitir/negar/error antes de la ejecución del controlador),
- resultado (permitir/negar/error después del estado de respuesta del controlador).
Hook emission is fail-closed for successful protected operations: if enterprise hook export fails, the sidecar returns an error instead of silently accepting un camino de éxito no auditado.
Enterprise readiness dependency checks use probes.enterprise_health_path (default /health) against the configured enterprise control-plane base URL when Las comprobaciones de dependencia de preparación empresarial utilizan probes.enterprise_health_path (por defecto /health) contra la URL base del plano de control empresarial configurada cuando probes.readiness_mode=storage_and_enterprise.

F:crates/arxi-sidecar-config/src/validation.rs F:crates/arxi-sidecar/src/control_plane_bridge.rs F:crates/arxi-sidecar/src/middleware/enterprise.rs

Error de Contrato

Los errores se devuelven como Detalles del Problema RFC 9457 (application/problem+json) con códigos de error estables, metadatos de reintento y campos de correlación entre servidor y cliente.

Detalles de la postura de seguridad:

malformed JSON rejections are normalized to typed bad_request problem details los rechazos de JSON malformado se normalizan a un problema de tipo bad_request detalles en lugar de filtrar fallos del extractor de marco/texto plano,
server-side (5xx) responses suppress internal detail fields to avoid leaking storage/runtime internals while preserving diagnostics in service registros,
401 unauthorized las respuestas incluyen desafíos WWW-Authenticate de la RFC 6750.

F:crates/arxi-sidecar/src/error.rs L13-L229 F:crates/arxi-sidecar/src/extract.rs

Idempotencia y Seguridad de Reintentos

Los puntos finales mutantes utilizan un estado de idempotencia persistente a través de SqliteStore::store_meta claves delimitadas por (recorder_id, method, path, idempotency_key) y hashes de solicitud JCS canónicos.

Comportamiento:

misma clave + mismo hash: reproducir estado/cuerpo anterior,
misma clave + hash diferente: 409 idempotency_conflict,
fallo de almacenamiento/index: fail-closed idempotency_unavailable.

La retención está limitada por TTL y idempotency_max_entries con desalojo determinista.

F:crates/arxi-sidecar/src/idempotency.rs L20-L316

Transporte y Ciclo de Vida

Modos de transporte:

Socket de dominio Unix,
Escuchador TCP,
ambos simultáneamente.

Ciclo de vida en tiempo de ejecución:

limpieza de sockets Unix obsoletos antes de la vinculación (fallo cerrado validado por tipo de socket),
token de cancelación impulsado por señales,
cierre elegante por oyente con un tiempo de espera shutdown_drain_seconds impuesto,
Eliminación del socket de Unix en la ruta de apagado.

F:crates/arxi-sidecar/src/server.rs L163-L262 F:crates/arxi-sidecar/src/shutdown.rs L8-L34

Superficie de comando operativo en binario:

inicio de servicio normal con --config / ARXI_SIDECAR_CONFIG,
healthcheck comando que soporta modos de sondeo TCP URL y Unix-socket.

F:crates/arxi-sidecar/src/main.rs L18-L175

Empaque de Contenedores y Operaciones de Docker

El repositorio ahora incluye un perfil de contenedor sidecar de primera parte en docker/sidecar/:

Dockerfile: construcción de Rust de múltiples etapas para una imagen de tiempo de ejecución sin raíz y sin distribución.
docker-compose.yml: local operator profile with explicit UID/GID mapping, docker-compose.yml: perfil de operador local con mapeo explícito de UID/GID, rutas de configuración/datos/ejecución montadas por enlace, verificación de estado y mapeo de puertos limitado.
config/sidecar.toml: container-oriented baseline config with token-mode config/sidecar.toml: configuración base orientada a contenedores con autenticación en modo token requerida para transporte no de bucle invertido.
.env.example: canonical environment variable contract for image/tag/paths .env.example: contrato canónico de variables de entorno para imágenes/etiquetas/rutas y mapeo de UID/GID.

Contrato de operador:

mount token_file as a regular non-symlink file with owner-only permissions montar token_file como un archivo regular no simbólico con permisos solo para el propietario (0600 en Unix),
run non-root with host UID/GID mapping so strict token checks remain readable ejecutar sin privilegios de root con mapeo de UID/GID del host para que las verificaciones de token estrictas sigan siendo legibles mientras se evita la ejecución como root,
trata docker/sidecar/config/token como material secreto y mantenlo fuera de VCS.

F:docker/sidecar/Dockerfile F:docker/sidecar/docker-compose.yml F:docker/sidecar/config/sidecar.toml F:docker/sidecar/README.md

Validación y Cobertura de Pruebas

La pila de validación de sidecar actual incluye:

config fail-closed validation assertions (port, header hard cap, validar las afirmaciones de cierre de configuración (puerto, límite duro de encabezado, límites de auto-sellado),
comportamiento del middleware de límites de longitud de contenido,
comportamiento de sanitización del correlation-id,
comprobaciones de determinismo del hash de solicitud idempotente canónica.
generated error-registry compatibility assertions se generaron afirmaciones de compatibilidad del registro de errores (Docs/generated/arxi/apis/sidecar.errors.json vs línea base de tiempo de ejecución).
restart-boundary idempotency replay/conflict integration checks over real reinicio de la idempotencia de límites, verificación de integración de reproducción/conflicto sobre el subprocess de sidecar real + persistencia en SQLite.
contract hardening checks for RFC 9457 payload shape, RFC 6750 auth challenge verificaciones de endurecimiento de contrato para la forma de carga útil del RFC 9457, encabezados de desafío de autenticación del RFC 6750 y propagación de encabezados de correlación.
probe hardening checks for unauthenticated probe routes and startup probe comprobaciones de endurecimiento de sondas para rutas de sondas no autenticadas y contrato de respuesta de la sonda de inicio.
readiness hardening checks for admission saturation fail-closed behavior and verificaciones de endurecimiento de preparación para el comportamiento de fallo cerrado por saturación de admisión y transiciones de modo de dependencia del plano de control empresarial.
generated sidecar contract compatibility gates (openapi/errors/enums/examples/compat) puertas de compatibilidad del contrato de sidecar generadas (openapi/errors/enums/examples/compat) aplicadas en la orquestación de generate/check.
optional release perf gate (ARXI_SIDECAR_PERF_GATE=1) for SLO promotion enforcement, including generation of target/sidecar-perf/latest.json a través del conjunto de pruebas del sistema de rendimiento sidecar.
system-test sidecar suites for end-to-end HTTP record/seal/build/verify and suites de pruebas de sistema sidecar para grabar/sellar/construir/verificar y persistencia de idempotencia de reinicio.
system-test Docker suite validating Dockerfile/Compose/config hardening plus Docker Compose build/up/down with containerized startup/readiness probes plus flujo de trabajo de abrir/grabar/consultar.
system-test sidecar perf suite for write/read latency, throughput, memory suite de rendimiento del sidecar de prueba del sistema para latencia de escritura/lectura, rendimiento, crecimiento de memoria y campos del informe de sobrecarga-429 utilizados por la puerta de rendimiento.

F:crates/arxi-sidecar-config/src/config/tests.rs F:crates/arxi-sidecar/tests/unit/middleware/bounds/tests.rs F:crates/arxi-sidecar/tests/unit/idempotency/tests.rs F:crates/arxi-sidecar/tests/error_registry_contract.rs F:crates/arxi-sidecar/tests/idempotency_restart.rs F:crates/arxi-sidecar/tests/http_contract_hardening.rs F:scripts/ci/sidecar_contract_gates.py F:scripts/ci/sidecar_perf_gate.py F:scripts/ci/generate_all.sh F:system-tests/tests/suites/sidecar.rs F:system-tests/tests/suites/sidecar_docker.rs F:system-tests/tests/suites/sidecar_perf.rs

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Límite de crate	`crates/arxi-sidecar/src/lib.rs`	Puntos de entrada públicos del crate y composición de módulos.
Tiempo de ejecución binario	`crates/arxi-sidecar/src/main.rs`	CLI, inicio del servicio y comportamiento de verificación de salud.
Configuración + validación	`crates/arxi-sidecar-config/src/config.rs`, `crates/arxi-sidecar-config/src/validation.rs`, `crates/arxi-sidecar-config/src/schema.rs`, `crates/arxi-sidecar-config/src/compat.rs`	Modelo de configuración de sidecar canónico, validación de inicio que falla en cerrado y artefactos de proyección de configuración determinista.
Arranque del servidor	`crates/arxi-sidecar/src/server.rs`	Conexión de almacenamiento/tiempo de ejecución, construcción de enrutador, ciclo de vida del transporte.
Estado compartido	`crates/arxi-sidecar/src/state.rs`	Manejadores de tiempo de ejecución y puertas de concurrencia.
Superficie de error	`crates/arxi-sidecar/src/error.rs`	Modelo de error de API estructurado.
Extractores JSON	`crates/arxi-sidecar/src/extract.rs`	Normalización estricta del límite JSON para fallos de análisis tipados.
Línea base del contrato de tiempo de ejecución	`crates/arxi-sidecar/src/contract.rs`	Versión de API exportada y constantes del registro de errores utilizadas por las pruebas de contrato.
Idempotencia	`crates/arxi-sidecar/src/idempotency.rs`	Semánticas de repetición/conflicto persistentes y hash de solicitud canónico.
Puerta de política empresarial	`crates/arxi-sidecar/src/control_plane_bridge.rs`	Adaptador de límite empresarial únicamente: verificaciones de ingreso del plano de control y emisión de ganchos de sidecar.
Middleware de autenticación	`crates/arxi-sidecar/src/middleware/auth.rs`	Verificaciones de token portador con comparación en tiempo constante.
Middleware empresarial	`crates/arxi-sidecar/src/middleware/enterprise.rs`	Extracción de identidad empresarial y aplicación de límites/secuenciación de ganchos.
Middleware de límites	`crates/arxi-sidecar/src/middleware/bounds.rs`	Controles de encabezado/contenido/cola/concurrencia/tiempo de espera.
Empaquetado de Docker	`docker/sidecar/Dockerfile`, `docker/sidecar/docker-compose.yml`, `docker/sidecar/config/sidecar.toml`, `docker/sidecar/README.md`	Perfil de construcción/tiempo de ejecución de contenedor de primera parte y guía de uso para operadores.
Módulos de pruebas unitarias de sidecar	`crates/arxi-sidecar-config/src/config/tests.rs`, `crates/arxi-sidecar/tests/unit/idempotency/tests.rs`, `crates/arxi-sidecar/tests/unit/middleware/bounds/tests.rs`	Las pruebas unitarias se externalizan de los archivos fuente de producción para una organización de archivos más limpia.
Pruebas de sistema de Docker de sidecar	`system-tests/tests/suites/sidecar_docker.rs`	Fortalecimiento de Dockerfile/Compose y validación del flujo de trabajo de sidecar en contenedores.
Manejadores de sondeo	`crates/arxi-sidecar/src/handlers/health.rs`	Comportamiento de vitalidad/inicio/listo, incluyendo modos de saturación y preparación de dependencias empresariales.
Pruebas de conformidad de contrato	`crates/arxi-sidecar/tests/error_registry_contract.rs`, `crates/arxi-sidecar/tests/idempotency_restart.rs`, `crates/arxi-sidecar/tests/http_contract_hardening.rs`	Verificaciones de registro, idempotencia de reinicio y fortalecimiento de límites HTTP.
Puertas de CI de contrato	`scripts/ci/sidecar_contract_gates.py`, `scripts/ci/sidecar_perf_gate.py`, `scripts/ci/generate_all.sh`	Compatibilidad solo aditiva más orquestación opcional de puerta de rendimiento de lanzamiento.
Pruebas de sistema de sidecar	`system-tests/tests/suites/sidecar.rs`, `system-tests/tests/suites/sidecar_perf.rs`	Cobertura de ciclo de vida HTTP de extremo a extremo y generación de informes de rendimiento para la puerta SLO.
Alineación de seguridad	Docs/security/threat_model.md	Mapeo de amenazas autoritativo y riesgos residuales.