Arxi Sidecar Architecture

Audience: Engineers implementing or operating arxi-sidecar as the Audiència: Enginyers que implementen o operen arxi-sidecar com a la frontera del servei d’enregistrament d’evidències accessible a la xarxa.

Taula de continguts

Visió Executiva
Composició en temps d’execució
HTTP Superfície i Ruteig
Controls de Seguretat i Recursos
Idempotència i Seguretat de Reintents
Transport i Cicle de Vida
Envasament de contenidors i operacions de Docker
Validació i Cobertura de Proves
File per Fitxer Referència Creuada

Executive Overview

arxi-sidecar és el temps d’execució del servei HTTP/JSON d’Arxi que exposa enregistraments, consultes i fluxos de treball de paquets a través de sockets Unix i/o oients TCP.

El sidecar composa RecorderEngine, BundleBuilder, Verifier i una única instància de SqliteStore sota portes de middleware explícites per a la identitat de correlació, autenticació, identitat/política empresarial, aplicació de límits, idempotència i control de temps d’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ó en temps d’execució

Flux de startup:

Load and validate TOML config (config_version, api.major_version, Carrega i valida la configuració TOML (config_version, api.major_version, recorder, transport, seguretat, signant i límits).
Inicialitza el rastreig i obre SqliteStore.
Construir components d’execució del gravador.
Inicialitzar el gestor d’idempotència persistent a store_meta.
Construir el router axum amb la pila de middleware.
Vincula els listeners de transport configurats i serveix fins a la cancel·lació.

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 Superfície i Ruteig

El router actualment exposa:

Probes: GET /health, GET /startup, GET /ready
Segment lifecycle: POST /v1/segments, POST /v1/segments/seal, Cicle de vida del segment: POST /v1/segments, POST /v1/segments/seal, GET /v1/segments, GET /v1/segments/active
Envelope ingest: POST /v1/envelopes, Ingesta d’envelopes: POST /v1/envelopes, POST /v1/envelopes/with-attachments
Consulta: POST /v1/query/envelopes
Bundle workflows: POST /v1/bundles/build, POST /v1/bundles/verify, Agrupar fluxos de treball: POST /v1/bundles/build, POST /v1/bundles/verify, POST /v1/bundles/inspect
Inspecció en temps d’execució: GET /v1/config

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

Comportament de salut:

GET /health és una prova de vivència lleugera que retorna metadades del procés.
GET /startup is a startup-completion probe returning startup metadata, GET /startup és una sonda de completament d’inici que retorna metadades d’inici, incloent startup_verification_depth configurat.
GET /ready returns readiness state with dependency-aware fail-closed semantics:
- 503 amb raó=storage_unavailable quan falla l’accés a la botiga.
- Optional 503 with reason=request_capacity_exhausted when probes.ready_fail_on_admission_saturation=true and admission/execution Opcional 503 amb reason=request_capacity_exhausted quan probes.ready_fail_on_admission_saturation=true i els semàfors d’admissió/execució estan esgotats.
- Optional 503 with reason=enterprise_control_unavailable when probes.readiness_mode=storage_and_enterprise, enterprise mode is enabled, Opcional 503 amb reason=enterprise_control_unavailable quan probes.readiness_mode=storage_and_enterprise, el mode d’empresa està habilitat, i les comprovacions de disponibilitat del pla de control fallen.
- 200 amb ready=true en estat estable.

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

Controls de Seguretat i Recursos

Config Gate

La validació de la configuració és fail-closed i imposa:

esquema estricte i versionat de l’API,
ID del gravador i validesa de l’auto-segell,
restriccions d’host/port de transport,
non-loopback transport requires security.mode=token and keeps el transport no de loopback requereix security.mode=token i manté require_token_for_non_loopback=true (tancat per defecte),
token file hardening (security.token_file cannot be a symlink, must be a enduriment del fitxer de token (security.token_file no pot ser un enllaç simbòlic, ha de ser un fitxer normal, i a Unix no ha de concedir permisos de grup/altres),
parseabilitat de la clau del signant,
sol·licitud/capçalera/límits numèrics d’idempotència i comprovacions de límits màxims,
probe config fail-closed semantics: probes.enterprise_health_path must be absolute/safe and probes.readiness_mode=storage_and_enterprise requires enterprise mode not desactivat.

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

Middleware Stack

Ordre i controls del middleware:

Límit del cos de la sol·licitud (max_request_body_bytes).
Capa de traçabilitat.
Correlation middleware (server correlation IDs, sanitized client Middleware de correlació (IDs de correlació del servidor, client x-correlation-id sanititzat, compatibilitat amb x-request-id llegat).
Auth middleware (Bearer token mode with constant-time compare and RFC 6750 Middleware d’autenticació (mode de token Bearer amb comparació en temps constant i metadades de repte RFC 6750 en respostes 401).
Enterprise identity middleware (x-tenant-id, x-principal-id, x-authn-method, optional x-namespace-id, optional writer lease assertion) per a modes habilitats per a empreses.
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ímits (bytes d’encapçalament, negociació de contingut, comprovacions de longitud de contingut, cua d’admissió limitada, concurrència activa limitada, temps d’espera de la sol·licitud).

Comportament de prioritat de la sonda:

/health, /startup, and /ready are exempted from auth, enterprise policy, and bounds gating so liveness/startup/readiness state remains observable under sobrecàrrega o fracassos 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

Controls de límits d’empresa

Quan enterprise.mode està habilitat, el sidecar afegeix un control explícit de l’aplicació de límits del pla de control mentre preserva la semàntica del gravador/prova:

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 és un adaptador de límit únicament. Traduïx les identitats/operacions d’entrada del sidecar en les trucades d’admissió i ganxo del pla de control; no implementa ni altera la matemàtica de proves d’Arxi.
Enterprise config is fail-closed: enabled mode requires token security mode, La configuració de l’empresa és de fallada tancada: el mode habilitat requereix el mode de seguretat del token, la configuració de l’URL/token del pla de control i les comprovacions de fitxers de token reforçades.
Enterprise policy gate calls Crides de política empresarial de porta POST /v1/enterprise/ingress/check abans de les operacions de sidecar protegides.
Managed-cloud mode enforces writer-lease assertion for mutating operations El mode de núvol gestionat aplica l’assertiva de lloguer d’escriptor per a operacions de mutació quan require_writer_lease_header=true.
Sidecar emits deterministic enterprise boundary hooks to POST /v1/enterprise/sidecar/hooks at:
- admissió (permetre/denegar/error abans de l’execució del controlador),
- result (permet/rebutja/error després de l’estat de resposta 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 camí d’èxit no auditat.
Enterprise readiness dependency checks use probes.enterprise_health_path (default /health) against the configured enterprise control-plane base URL when Les comprovacions de dependència de preparació de l’empresa utilitzen probes.enterprise_health_path (per defecte /health) contra la URL base del pla de control de l’empresa configurada quan 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 Contract

Els errors es retornen com a detalls de problemes RFC 9457 (application/problem+json) amb codis d’error estables, metadades de reintents i camps de correlació servidor/client.

Detalls de la postura de seguretat:

malformed JSON rejections are normalized to typed bad_request problem details les rebuig de JSON mal formatades es normalitzen a un problema de tipus bad_request detalls en comptes de filtrar fallades d’extractors de framework/plaintext,
server-side (5xx) responses suppress internal detail fields to avoid leaking storage/runtime internals while preserving diagnostics in service registres,
401 unauthorized les respostes inclouen desafiaments WWW-Authenticate de l’RFC 6750.

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

Idempotència i seguretat de reintents

Els punts finals mutables utilitzen un estat d’idempotència persistent a través de SqliteStore::store_meta claus delimitades per (recorder_id, method, path, idempotency_key) i hashes de sol·licituds JCS canònics.

Comportament:

mateixa clau + mateix hash: reproduir l’estat/cos anterior,
mateixa clau + hash diferent: 409 idempotency_conflict,
fallada de storage/index: fail-closed idempotency_unavailable.

La retenció està limitada pel TTL i idempotency_max_entries amb expulsió determinista.

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

Transport i Cicle de Vida

Modes de transport:

Socket de domini Unix,
oient TCP,
ambdós simultàniament.

Cicle de vida d’execució:

neteja de sockets Unix obsolets abans de l’enllaç (socket-type-validated fail-closed),
token de cancel·lació impulsat per senyal,
apagada elegant per a l’escolta amb un temps d’espera shutdown_drain_seconds imposat,
Eliminació de sockets Unix en el camí de tancament.

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

Comandament operatiu superficial en binari:

inici normal del servei amb --config / ARXI_SIDECAR_CONFIG,
healthcheck ordre que suporta modes de sondatge TCP URL i Unix-socket.

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

Envasament de contenidors i operacions de Docker

El repositori ara inclou un perfil de contenidor sidecar de primera part sota docker/sidecar/.

Dockerfile: construcció de Rust de múltiples etapes per a una imatge d’execució sense distribució i sense permisos d’usuari.
docker-compose.yml: local operator profile with explicit UID/GID mapping, docker-compose.yml: perfil d’operador local amb mapeig explícit de UID/GID, rutes de configuració/dades/execució muntades per vinculació, comprovació de salut i mapeig de ports limitats.
config/sidecar.toml: container-oriented baseline config with token-mode config/sidecar.toml: configuració bàsica orientada a contenidors amb autenticació en mode token requerida per al transport no de loopback.
.env.example: canonical environment variable contract for image/tag/paths .env.example: contracte de variable d’entorn canònic per a imatges/etiquetes/camins i mapeig de UID/GID.

Contracte d’operador:

mount token_file as a regular non-symlink file with owner-only permissions muntar token_file com un fitxer normal no enllaçat amb permisos només per a l’owner (0600 en Unix),
run non-root with host UID/GID mapping so strict token checks remain readable executar sense permisos d’usuari root amb mapeig d’UID/GID de l’amfitrió perquè les comprovacions de token estrictes es mantinguin llegibles mentre s’evita l’execució com a root,
tracta docker/sidecar/config/token com a material secret i mantingues-lo fora del VCS.

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

Validació i Cobertura de Proves

L’actual pila de validació de sidecar inclou:

config fail-closed validation assertions (port, header hard cap, configurar les afirmacions de validació fail-closed (port, límit de capçalera, límits d’auto-seal),
comportament del middleware de límits de longitud de contingut,
comportament de sanitització de l’identificador de correlació,
comprovacions de determinisme del hash de la sol·licitud d’idempotència canònica.
generated error-registry compatibility assertions generades afirmacions de compatibilitat del registre d’errors (Docs/generated/arxi/apis/sidecar.errors.json vs línia base d’execució).
restart-boundary idempotency replay/conflict integration checks over real comprovacions d’integració de reproducció/conflicte d’idempotència de límits de reinici sobre el subprocess de sidecar real + persistència SQLite.
contract hardening checks for RFC 9457 payload shape, RFC 6750 auth challenge comprovacions de reforç del contracte per a la forma de càrrega de l’RFC 9457, capçaleres de repte d’autenticació de l’RFC 6750 i propagació de capçaleres de correlació.
probe hardening checks for unauthenticated probe routes and startup probe comprovacions de reforç de sondes per a rutes de sondes no autenticades i contracte de resposta de la sonda d’inici.
readiness hardening checks for admission saturation fail-closed behavior and verificacions de reforç de preparació per al comportament de fallada tancada de saturació d’admissió i transicions de mode de dependència del pla de control empresarial.
generated sidecar contract compatibility gates (openapi/errors/enums/examples/compat) portes de compatibilitat del contracte sidecar generades (openapi/errors/enums/examples/compat) aplicades en l’orquestració generate/check.
optional release perf gate (ARXI_SIDECAR_PERF_GATE=1) for SLO promotion enforcement, including generation of target/sidecar-perf/latest.json porta de rendiment de llançament opcional (ARXI_SIDECAR_PERF_GATE=1) per a l’aplicació de la promoció SLO, incloent la generació de target/sidecar-perf/latest.json a través del sistema de proves de rendiment del sidecar.
system-test sidecar suites for end-to-end HTTP record/seal/build/verify and suites de sidecar de prova del sistema per a l’enregistrament/sellat/construcció/verificació HTTP de punta a punta i la persistència d’idempotència en el reinici.
system-test Docker suite validating Dockerfile/Compose/config hardening plus Docker Compose build/up/down with containerized startup/readiness probes plus obrir/registre/consulta flux de treball.
system-test sidecar perf suite for write/read latency, throughput, memory suite de rendiment del sidecar de prova del sistema per a la latència d’escriptura/lectura, el rendiment, el creixement de la memòria i els camps del informe d’overload-429 utilitzats pel portell de rendiment.

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

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Límits de contenidor	`crates/arxi-sidecar/src/lib.rs`	Punt d’entrada públic del contenidor i composició de mòduls.
Temps d’execució binari	`crates/arxi-sidecar/src/main.rs`	CLI, inici del servei i comportament de comprovació de salut.
Configuració + validació	`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`	Model de configuració de contenidor canònic, validació de fallada tancada en l’inici i artefactes de projecció de configuració determinista.
Arrencada del servidor	`crates/arxi-sidecar/src/server.rs`	Connexió d’emmagatzematge/temps d’execució, construcció del router, cicle de vida del transport.
Estat compartit	`crates/arxi-sidecar/src/state.rs`	Gestors de temps d’execució i portes de concurrència.
Superfície d’error	`crates/arxi-sidecar/src/error.rs`	Model d’error API estructurat.
Extractors JSON	`crates/arxi-sidecar/src/extract.rs`	Normalització estricta de límits JSON per a errors de parseig tipats.
Base del contracte d’execució	`crates/arxi-sidecar/src/contract.rs`	Versió API exportada i constants del registre d’errors utilitzades per les proves de contracte.
Idempotència	`crates/arxi-sidecar/src/idempotency.rs`	Semàntica de reproducció/conflicte persistent i hash de sol·licitud canònic.
Porta de política empresarial	`crates/arxi-sidecar/src/control_plane_bridge.rs`	Adaptador de límit empresarial només: comprovacions d’entrada del pla de control i emissió de ganxos del contenidor.
Middleware d’autenticació	`crates/arxi-sidecar/src/middleware/auth.rs`	Comprovacions de token de portador amb comparació en temps constant.
Middleware empresarial	`crates/arxi-sidecar/src/middleware/enterprise.rs`	Extracció d’identitat empresarial i aplicació de límits/sequenciació de ganxos.
Middleware de límits	`crates/arxi-sidecar/src/middleware/bounds.rs`	Controls d’encapçalament/contenut/cua/concurrència/temps d’espera.
Paquet de Docker	`docker/sidecar/Dockerfile`, `docker/sidecar/docker-compose.yml`, `docker/sidecar/config/sidecar.toml`, `docker/sidecar/README.md`	Perfil de construcció/temps d’execució de contenidors de primer nivell i guia d’ús per a operadors.
Mòduls de proves unitàries del contenidor	`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`	Les proves unitàries s’externalitzen dels fitxers fonts de producció per a una organització de fitxers més neta.
Proves de sistema de Docker del contenidor	`system-tests/tests/suites/sidecar_docker.rs`	Enduriment del Dockerfile/Compose i validació del flux de treball del contenidor.
Gestors de sondes	`crates/arxi-sidecar/src/handlers/health.rs`	Comportament de viabilitat/inici/preparació, incloent modes de saturació i preparació de dependències empresarials.
Proves de conformitat del contracte	`crates/arxi-sidecar/tests/error_registry_contract.rs`, `crates/arxi-sidecar/tests/idempotency_restart.rs`, `crates/arxi-sidecar/tests/http_contract_hardening.rs`	Comprovacions de registre, idempotència de reinici i enduriment de límits HTTP.
Portes CI del contracte	`scripts/ci/sidecar_contract_gates.py`, `scripts/ci/sidecar_perf_gate.py`, `scripts/ci/generate_all.sh`	Compatibilitat només additiva més orquestració opcional de portes de rendiment de llançament.
Proves de sistema del contenidor	`system-tests/tests/suites/sidecar.rs`, `system-tests/tests/suites/sidecar_perf.rs`	Cobertura de cicle de vida HTTP de punta a punta i generació de informes de rendiment per a portes SLO.
Alineament de seguretat	Docs/security/threat_model.md	Mapeig d’amenaça autoritzada i riscos residuals.