SPB Git

Repository Public

ARCHITECTURE.md 30.1 KB

# Architecture — MacLustr Command Center (MCC)

État décrit : dépôt au commit 45f0d03 (version 0.1.0), déploiement du 2026-11-18. Ce document décrit ce que le code fait. Quand il s'écarte de DESIGN-BRIEF.md, c'est le code qui est décrit et l'écart est signalé. Les faits de production marqués [prod] ont été observés par le responsable du déploiement le 2026-11-18 et ne sont pas vérifiables depuis ce dépôt.

Documents liés : SECURITY.md · OPERATIONS.md · API.md · AGENT-PROTOCOL.md · METRICS-CATALOG.md · ACCEPTANCE.md · DECISIONS/ · APPLE-APPS.md (rédigé séparément).

# 1. Contexte (C4 niveau 1)

MCC est un poste de pilotage d'infrastructure : il observe les machines d'un cluster (télémétrie, inventaire, services, serveurs d'inférence, volumes) et permet d'y lancer des actions typées. Il est écrit à partir d'un dépôt vide et cohabite avec l'ancien produit sans le lire ni le modifier (ADR 0001).

flowchart LR
  owner["Propriétaire / opérateurs<br/>(navigateur, apps Apple)"]
  host_admin["Administrateur hôte<br/>(SSH + mccctl)"]
  subgraph mcc["MacLustr Command Center"]
    cp["Plan de contrôle<br/>(nœud hôte unique)"]
    ag["mcc-agent<br/>(un par machine)"]
  end
  gw["Passerelle publique existante<br/>(Caddy TLS + WireGuard)"]
  nodes["Machines du cluster<br/>(macOS, 1 Linux)"]
  apns["APNs (Apple)<br/>inactif : aucune clé"]
  backup["Second nœud<br/>(copie des sauvegardes)"]
  mld["mld<br/>(outil de déploiement existant)"]

  owner -- "HTTPS clustr.spboucher.ai" --> gw --> cp
  ag -- "HTTPS sortant, requêtes signées" --> gw
  ag -- "lit (sans root)" --> nodes
  host_admin -- "hors bande" --> cp
  cp -. "push (non actif)" .-> apns
  cp -- "rsync restreint, 03:40" --> backup
  mld -- "place et supervise (PM2)" --> cp

Acteurs et systèmes externes :

Élément Rôle Source
Utilisateurs (owner, admin, operator, viewer) consultation, actions, administration services/internal/authz/authz.go
Administrateur hôte amorçage, récupération, sauvegarde, gel d'urgence, via mccctl en SSH services/cmd/mccctl/
Passerelle publique termine TLS, route clustr.spboucher.ai vers le port 8800 du nœud hôte infra/deploy/mld-manifest.json (tunnel)
mld outil existant utilisé « comme un opérateur » pour placer l'app et router le domaine ADR 0001, 0009
APNs notifications push ; fournisseur implémenté, inactif faute de clé services/internal/notify/apns.go

# 2. Conteneurs (C4 niveau 2)

flowchart TB
  subgraph internet["Internet"]
    browser["Navigateur"]
    apple["Apps macOS / iOS<br/>(voir APPLE-APPS.md)"]
    agents["mcc-agent × N"]
  end
  gw["Passerelle (Caddy TLS)"]
  subgraph host["Nœud hôte (M4M64c en production)"]
    api["control-api (Go)<br/>0.0.0.0:8800<br/>REST /api/v1, SSE, WebAuthn, AASA,<br/>relais /agent/v1, proxy web"]
    web["web (Next.js standalone)<br/>127.0.0.1:8803"]
    ingest["telemetry-ingest (Go)<br/>8804 requêtes signées (HTTP loopback)<br/>8801 mTLS · 8805 santé"]
    orch["action-orchestrator (Go)<br/>127.0.0.1:8802 (santé)<br/>actions, jobs, alertes, notifications,<br/>calendrier d'entretien, ménage"]
    pg[("PostgreSQL 17<br/>base mcc, 127.0.0.1:5432")]
    secrets[/"~/.config/mcc<br/>AC agents, clés de signature,<br/>clé CSRF, clé de sauvegarde"/]
    ctl["mccctl (CLI hors bande)"]
    bk["mcc-backup (cron 03:40)"]
  end
  browser --> gw
  apple --> gw
  agents --> gw
  gw --> api
  api -- "tout sauf /api, /agent, AASA" --> web
  api -- "/agent/v1/* (relais, sans identifiants utilisateur)" --> ingest
  api --> pg
  ingest --> pg
  orch --> pg
  ctl --> pg
  bk --> pg
  ingest -. "agent-ca.key" .-> secrets
  orch -. "command-signing.key" .-> secrets
  api -. "csrf.key, audit-signing.key" .-> secrets
  bk -. "backup.key" .-> secrets
Conteneur Binaire / source Écoute en production [prod] Défaut de développement (services/internal/config/config.go)
control-api services/cmd/control-api 0.0.0.0:8800 (seul port routé par la passerelle) 127.0.0.1:8730
telemetry-ingest services/cmd/telemetry-ingest 127.0.0.1:8801 (mTLS), 127.0.0.1:8804 (requêtes signées), 127.0.0.1:8805 (santé) 8731, 8734, 8741
action-orchestrator services/cmd/action-orchestrator 127.0.0.1:8802 (santé seulement) 127.0.0.1:8732
web apps/web (Next.js 16, sortie standalone) 127.0.0.1:8803 127.0.0.1:8733
mccctl services/cmd/mccctl, lanceur scripts/mccctl — —
mcc-agent services/cmd/mcc-agent, services/internal/agent/ aucune écoute —
PostgreSQL 17 — base mcc mcc_dev

Écarts avec DESIGN-BRIEF.md §1 : les ports de production sont 8800–8805 (le brief donne les défauts 8730–8733) ; telemetry-ingest écoute en loopback en production (le brief annonçait 0.0.0.0:8731 sur le LAN) parce que le transport par défaut est devenu la requête signée relayée par control-api (ADR 0004, amendement).

Tous les services Go forment un seul module (services/go.mod, go 1.26). La coordination entre services passe uniquement par PostgreSQL : tables durables et LISTEN/NOTIFY (canaux mcc_events, mcc_commands, mcc_command_updates, mcc_actions — services/internal/events/events.go, services/internal/actions/store.go). Il n'y a ni Redis ni file de messages (ADR 0003).

# 3. Composants (C4 niveau 3)

# 3.1 control-api

flowchart TB
  req["Requête HTTP"] --> ctx["httpx.WithRequestContext<br/>id de corrélation, IP cliente (proxys de confiance)"]
  ctx --> log["AccessLog → Recover → SecurityHeaders"]
  log --> mux{"routage"}
  mux -- "/api/v1/events" --> sse["serveEvents (SSE)"]
  mux -- "/api/v1/*" --> strict["serveur strict généré (gen.go)"]
  mux -- "/agent/v1/*" --> relay["agentProxy → telemetry-ingest"]
  mux -- "/.well-known/apple-app-site-association" --> aasa["serveAASA"]
  mux -- "reste" --> webp["proxy inverse → web"]
  strict --> admit["core.admit (server.go)<br/>identifiants → limites → CSRF → permission → step-up"]
  sse --> admit
  admit --> h1["identityHandlers"]
  admit --> h2["adminHandlers"]
  admit --> h3["clusterHandlers"]
  admit --> h4["opsHandlers"]
  h1 --> idsvc["identity.Service<br/>WebAuthn, sessions, invitations"]
  h2 & h3 & h4 --> authz["authz.Decide / DecideFacets"]
  h4 --> actions["actions (catalogue, pré-vérifications, verrous)"]
  h1 & h2 & h3 & h4 --> audit["audit.Append (chaîne de hachage)"]
  audit --> outbox["events.Publish → events_outbox"]
  • Contrat d'abord (ADR 0006) : packages/api-contracts/openapi.yaml (132 opérations) génère services/internal/api/gen.go (types + serveur strict), ops_gen.go (table Operations : méthode, chemin, mode d'authentification, permission, step-up) et unimplemented_gen.go (réponse 501 par défaut). tools/gen-api.py produit ces fichiers ; make gen-check échoue s'ils sont périmés.
  • Application centrale de la sécurité : core.admit (services/internal/api/server.go) refuse toute opération absente de Operations. Les handlers ajoutent les contrôles liés à la ressource (core.authorize) ou au contenu (core.requireStepUp, par exemple pour une action de criticité high).
  • Groupes de handlers (services/internal/api/groups.go) : identité (identity_handlers.go), administration (admin_*.go), lecture du cluster (cluster_*.go), opérations (ops_*.go). Le test TestEveryClusterAndAdminOperationIsImplemented (admin_test.go) vérifie que les opérations cluster/admin ne tombent pas sur le 501 ; un recoupement fait pour ce document montre que les 132 opérations ont un handler (StreamEvents est servi hors du serveur généré, par events_stream.go).
  • Relais des agents (agent_proxy.go) : retransmet /agent/v1/* vers l'écoute « requêtes signées » de telemetry-ingest, en supprimant Cookie, Authorization et l'en-tête X-Forwarded-For entrant (remplacé par l'adresse résolue par control-api). Il n'authentifie pas les agents.

# 3.2 telemetry-ingest

Composant Fichier Rôle
Authentification mTLS services/internal/ingest/server.go certificat client de l'AC privée, numéro de série recherché dans agents (cache ≤ 5 s)
Authentification par requête signée services/internal/ingest/signed.go certificat + horodatage + nonce + signature ECDSA ; fenêtre ±90 s, cache de nonces en mémoire
Enrôlement, renouvellement enroll.go, services/internal/pki/pki.go jeton à usage unique, CSR, certificat 30 jours
Rapports report.go validation stricte, idempotence (agent, seq), écriture en une transaction
Transport des commandes commands.go long-poll, accusé, sortie, résultat ; ne signe rien
Tâches de fond maintenance.go partitions, agrégats 1 min / 1 h, rétention, events.Prune, battement

# 3.3 action-orchestrator

services/cmd/action-orchestrator/main.go héberge une boucle principale et cinq tâches périodiques, chacune sous un verrou consultatif PostgreSQL (orchestrator.Leader) pour ne jamais tourner deux fois en même temps :

Tâche Période Paquet
Actions (expiration d'approbation, émission, réconciliation) sur notification + balayage toutes les 2 s services/internal/orchestrator
Jobs (placement, tentatives, planifications) 2 s services/internal/jobs
Alertes (évaluation des règles) 15 s services/internal/alerts
Notifications (file alert_notifications → APNs) 5 s services/internal/notify
Calendrier d'entretien (début/fin des fenêtres) 10 s services/internal/maintenance
Ménage (événements d'actions terminées, notifications livrées) 1 h services/internal/orchestrator/housekeeping.go

L'orchestrateur est le seul détenteur de la clé de signature des commandes (command-signing.key, services/internal/orchestrator/signer.go) ; seule la clé publique est écrite en base (command_keys).

# 3.4 mcc-agent

Paquet (services/internal/agent/…) Rôle
collect (platform_darwin.go, platform_linux.go, parsers.go) métriques et inventaire, sans cgo ni root
services découverte PM2, launchd, systemd, docker ; serveurs d'inférence (inference.go)
client transports (URL = requêtes signées, host:port = mTLS), bascule entre points d'accès
spool tampon disque hors ligne (6 h / 20 Mio)
policy liste blanche locale policy.json
nonce, journal anti-rejeu persistant, journal des commandes (reprise après crash)
executor, runcmd exécution sans shell, délais, plafonds de sortie, expurgation
state répertoire d'état (~/.mcc-agent, 0700)

Détail du protocole : AGENT-PROTOCOL.md.

# 3.5 web

Next.js 16 (App Router, React 19, TypeScript strict), sortie standalone, servie derrière control-api (même origine). Aucune récupération de données côté serveur : chaque page est une coquille rendue côté client qui n'appelle que /api/v1 (apps/web/next.config.ts). apps/web/src/proxy.ts pose une CSP à nonce par requête. Types générés depuis le contrat (apps/web/src/api/schema.d.ts), bibliothèque de composants propre (apps/web/DESIGN-SYSTEM.md), langues fr/en (apps/web/src/i18n/), jetons de design partagés (packages/ui-tokens/). Captures : docs/screenshots/web/.

# 4. Flux de données

# 4.1 Télémétrie

sequenceDiagram
  participant A as mcc-agent
  participant G as Passerelle (TLS)
  participant C as control-api (relais)
  participant I as telemetry-ingest
  participant P as PostgreSQL
  participant U as Client (SSE)
  loop toutes les 10 s (ReportAck.interval_s)
    A->>A: collecte (échantillons, disponibilité, services…)
    A->>G: POST /agent/v1/report (cert, ts, nonce, signature)
    G->>C: HTTP
    C->>I: relais (sans Cookie ni Authorization)
    I->>I: chaîne AC, validité, révocation, fenêtre ±90 s, signature, nonce
    I->>P: 1 transaction : samples_raw, node_state, services, volumes, inventaire, events_outbox
    I-->>A: ReportAck {seq, interval_s, want_inventory, renew_cert…}
    P-->>C: NOTIFY mcc_events
    C-->>U: event: node.state
  end
  Note over A: hors ligne : rapport écrit dans spool/, rejoué dans l'ordre (buffered=true)
  Note over I,P: toutes les 20 s : agrégats raw → 1 min → 1 h (verrou consultatif)

Règles importantes (services/internal/ingest/report.go) : un rapport en double est acquitté sans être réappliqué ; un rapport buffered ou plus ancien que l'état stocké n'apporte que des échantillons et n'écrase jamais l'état courant ; une métrique non mesurable est déclarée dans availability et ne produit aucun échantillon (ADR 0007). La fraîcheur (fresh < 30 s, stale 30–120 s, offline au-delà) est calculée par le serveur à la lecture (MCC_FRESH_AFTER, MCC_OFFLINE_AFTER).

# 4.2 Commande (action)

sequenceDiagram
  participant U as Utilisateur
  participant C as control-api
  participant P as PostgreSQL
  participant O as action-orchestrator
  participant I as telemetry-ingest
  participant A as mcc-agent
  U->>C: POST /actions (Idempotency-Key)
  C->>C: permission sur la cible, step-up, confirmation, justification, pré-vérifications
  C->>P: INSERT actions (+ action_locks) + audit, NOTIFY mcc_actions
  C-->>U: 201 Action (queued ou pending_approval)
  opt criticité critical
    U->>C: POST /actions/{id}/approve (autre personne, step-up)
  end
  O->>P: prend l'action (FOR UPDATE SKIP LOCKED), refait les pré-vérifications
  O->>O: signe l'enveloppe (Ed25519, validité 90 s, nonce)
  O->>P: INSERT agent_commands (1 par action) + état dispatched, NOTIFY mcc_commands
  A->>I: GET /agent/v1/commands?wait=25 (long-poll)
  I-->>A: SignedCommand (remise une seule fois)
  A->>A: FREEZE ? signature, destinataire, expiration, nonce, politique locale, paramètres
  A->>I: POST …/ack {accepted}
  A->>I: POST …/events (sortie expurgée)
  A->>I: POST …/result
  I->>P: agent_commands, action_events, NOTIFY mcc_command_updates
  O->>P: réconcilie : succeeded / failed / timed_out (+ outcome_unknown), libère le verrou
  P-->>C: NOTIFY mcc_events
  C-->>U: event: action.changed / action.output

Propriété centrale (ADR 0010) : une action émet au plus une commande (index unique agent_commands_one_per_action, migration 0006_ops.sql) et rien ne la ré-émet. Une commande jamais remise finit failed / agent_unreachable ; une commande remise sans résultat avant l'échéance finit timed_out avec result.outcome_unknown=true (services/internal/orchestrator/orchestrator.go). Les types node.maintenance.set et job.cancel sont exécutés par l'orchestrateur lui-même, sans commande agent (ServerSide dans services/internal/actions/catalog.go).

# 4.3 Événements temps réel

sequenceDiagram
  participant S as Service producteur
  participant P as PostgreSQL
  participant H as events.Hub (control-api)
  participant C as Client
  S->>P: dans la transaction métier : INSERT events_outbox (seq) + pg_notify('mcc_events')
  P-->>H: NOTIFY à la validation (et réveil de sécurité toutes les 5 s)
  C->>H: GET /api/v1/events (Last-Event-ID: n)
  H-->>C: retry: 3000 / event: hello {head}
  H->>P: SELECT … WHERE seq > n
  H-->>C: id: seq / event: topic / data: payload (filtré par permission)
  H-->>C: ": ping" toutes les 15 s
  Note over H,C: position purgée (rétention 1 h) → event: resync, le client recharge par REST
  Note over H,C: flux fermé après 30 min ; session revérifiée chaque minute

L'événement est écrit dans la même transaction que le changement d'état : un client ne voit jamais un événement non validé, et une coupure retarde les événements sans les perdre (dans la limite d'une heure). Formes des charges utiles et écarts avec le contrat : API.md §5.

# 4.4 Authentification

sequenceDiagram
  participant B as Navigateur
  participant C as control-api
  participant P as PostgreSQL
  Note over B,C: Invitation (lien /setup#jeton, le fragment ne quitte pas le navigateur)
  B->>C: POST /invitations/exchange {token}
  C->>P: UPDATE invitations SET consumed_at … WHERE consumed_at IS NULL (atomique)
  C-->>B: cookie mcc_setup (10 min)
  B->>C: POST /auth/webauthn/registration/begin
  C-->>B: défi (5 min, usage unique)
  B->>C: POST …/registration/finish {credential}
  C->>P: 1 transaction : compte, passkey, invitation terminée, session, audit
  C-->>B: cookie mcc_session + csrf_token
  Note over B,C: Connexion ultérieure (sans nom d'utilisateur)
  B->>C: POST /auth/webauthn/authentication/begin
  B->>C: POST …/authentication/finish {challenge_id, credential, client}
  C->>C: défi consommé, origine, RP ID, UV, compteur de signature
  C-->>B: cookie mcc_session + csrf_token (web) ou jetons d'accès/rafraîchissement (natif)

Détails et politiques : SECURITY.md §3–§5, exemples : API.md §3.

# 5. Frontières de confiance

flowchart LR
  subgraph z0["Zone 0 — Internet (non fiable)"]
    c["Clients"]
    a["Agents (chaque nœud = sa propre zone)"]
  end
  subgraph z1["Zone 1 — Passerelle (termine TLS)"]
    gw["Caddy"]
  end
  subgraph z2["Zone 2 — Nœud hôte"]
    api["control-api"]
    ing["telemetry-ingest"]
    orch["action-orchestrator"]
    db[("PostgreSQL")]
    sec[/"~/.config/mcc"/]
  end
  c --> gw --> api
  a --> gw
  api --> ing
  api --> db
  ing --> db
  orch --> db
  orch -.-> sec
Frontière Ce qui est vérifié au passage Ce qu'un composant compromis en amont ne peut pas faire
Internet → control-api session ou jeton, CSRF + Origin, permission, step-up, limites de débit —
control-api → telemetry-ingest rien (relais) ; l'ingestion vérifie elle-même chaque requête d'agent control-api ne peut pas forger une requête d'agent (pas de clé d'agent)
telemetry-ingest → agent l'agent vérifie la signature Ed25519 de l'orchestrateur, le destinataire, l'expiration, le nonce, puis sa politique locale l'ingestion (ou la passerelle) peut retarder ou jeter une commande, pas en forger, en modifier ni en rejouer
Agent → telemetry-ingest certificat de l'AC privée, non révoqué, preuve de possession par requête un agent ne voit que les commandes qui lui sont adressées (404 command_not_found sinon)
Hôte (SSH) → base accès direct ; opérations mccctl auditées avec actor_kind=cli —

Limite assumée : le nœud hôte est une seule zone. Un attaquant ayant le compte du service sur l'hôte lit la base et ~/.config/mcc, donc toutes les clés (voir SECURITY.md §14).

# 6. Modèle de données

Schéma : services/internal/db/migrations/0001_init.sql à 0006_ops.sql, appliqué au démarrage par control-api et action-orchestrator (db.Migrate : un fichier par transaction, verrou consultatif, somme de contrôle — une migration déjà appliquée puis modifiée est refusée). Toutes les clés primaires sont des UUID v7 (services/internal/ids). Les horodatages sont lus en UTC (services/internal/db/db.go).

erDiagram
  users ||--o{ passkeys : "possède"
  users ||--o{ devices : "possède"
  devices ||--o{ sessions : "porte"
  sessions ||--o{ refresh_tokens : "rotation (natif)"
  users ||--o{ invitations : "crée"
  invitations ||--o{ invitation_transactions : "ouvre"
  nodes ||--o| agents : "1 agent actif"
  nodes ||--o| node_state : "dernier état"
  nodes ||--o{ services : "héberge"
  nodes ||--o{ inference_servers : "héberge"
  nodes ||--o{ volumes : "monte"
  nodes ||--o{ samples_raw : "mesure"
  alert_rules ||--o{ alerts : "déclenche"
  incidents ||--o{ alerts : "regroupe"
  actions ||--o| agent_commands : "au plus 1"
  actions ||--o{ action_events : "journalise"
  actions ||--o| action_locks : "verrouille"
  jobs ||--o{ actions : "1 par tentative"
  job_schedules ||--o{ jobs : "planifie"
  maintenance_windows ||--o{ maintenance_window_nodes : "vise"
Domaine Tables Remarques
Identité users, passkeys, webauthn_challenges, devices, sessions, refresh_tokens, invitations, invitation_transactions jetons stockés hachés (SHA-256) uniquement
Autorisation policy_grants allow / deny par sujet (utilisateur ou rôle), permission, ressource
Audit audit_log chaîne de hachage ; déclencheurs refusant UPDATE, DELETE, TRUNCATE
Inventaire nodes, agents, agent_enrollment_tokens, node_state, services, service_events, inference_servers, volumes, nas_targets, nas_observations, backups un seul agent actif par nœud (index partiel agents_one_active_per_node)
Séries temporelles metric_catalog, samples_raw, samples_1m, samples_1h, rollup_state, rollup_dirty, agent_report_seqs partitions par plage de temps
Alertes alert_rules, alerts, incidents, timeline_events, silences, alert_notifications une alerte ouverte par empreinte (index alerts_open_fingerprint)
Entretien maintenance_windows, maintenance_window_nodes, maintenance_notes
Actions et jobs actions, action_locks, action_events, agent_commands, command_keys, jobs, job_schedules
Plateforme events_outbox, settings, service_heartbeats, user_dashboards, schema_migrations settings ne contient aucun secret

La table rate_limits existe dans 0001_init.sql mais n'est référencée par aucun code Go : les limites de débit sont en mémoire (services/internal/httpx/ratelimit.go).

# 7. Choix techniques

Choix Raison résumée ADR
Produit neuf, aucune reprise de l'ancien mandat 0001
Go pour les services et l'agent (binaire statique, CGO_ENABLED=0) 8 Macs sans Homebrew ni Node ; passerelle linux/amd64 ; protocole partagé à la compilation 0002
PostgreSQL partitionné, pas de TimescaleDB ni de Redis extension absente partout ; volume modeste 0003
Agents en sortie seulement ; requêtes signées via l'origine publique par défaut ; commandes signées par l'orchestrateur confidentialité du réseau local de macOS mesurée sur m4ml 0004
Passkeys seulement, sessions opaques, récupération hors bande révocation immédiate, pas de secret partagé 0005
OpenAPI 3.1 comme contrat unique, clients générés une seule vérité pour trois clients 0006
Agent sans root, métriques non mesurables déclarées sudo sans mot de passe sur 7 Macs seulement 0007
Catalogue d'actions typées, pas de shell distant moindre privilège 0008
Hôte unique derrière la passerelle existante robustesse par simplicité ; pas de réplication 0009
Au plus une commande par action ; issue inconnue = état, jamais une relance sûreté des opérations sur des machines réelles 0010

# 8. Modes dégradés et comportement en panne

Situation Comportement (source) Preuve
Base indisponible — ingestion toutes les routes répondent 503 avec Retry-After ; le service reste en marche et attend la base au démarrage (cmd/telemetry-ingest/main.go) ; les agents tamponnent TestDatabaseOutage (services/internal/ingest/integration_test.go)
Base indisponible — orchestrateur attend la base au démarrage (connect) ; les passes échouent, reprennent avec recul, puis tout est réconcilié depuis les tables TestSurvivesDatabaseConnectionLoss (services/internal/orchestrator/orchestrator_test.go)
Base indisponible — control-api GET /health/ready répond 503 unavailable ; un flux SSE ouvert est fermé (le client se reconnecte avec son dernier id) ; GET /admin/status rapporte database: down. Au démarrage, control-api n'attend pas la base : db.Open échoue, le processus sort et c'est PM2 (autorestart) qui le relance lecture du code (identity_handlers.go, events_stream.go, admin_settings.go, cmd/control-api/main.go) ; pas de test automatisé dédié à une coupure de base côté API
Ingestion arrêtée le relais répond 503 unavailable + Retry-After: 15 ; les agents tamponnent (6 h / 20 Mio) puis rejouent sans doublon ; les nœuds passent stale puis offline ; /admin/status montre l'ingestion degraded (> 30 s) puis down (> 120 s) TestOfflineBufferingAndReplay (ingest), admComponent (admin_settings.go)
Chemin Internet coupé (passerelle ou tunnel) même effet que ci-dessus pour les agents ; l'interface est elle aussi injoignable puisqu'elle passe par la même entrée (compromis assumé, ADR 0004). Au-delà de 6 h, les rapports les plus anciens sont perdus lecture de services/internal/agent/spool/spool.go, TestBounds
Agent hors ligne nœud offline après 120 s ; règle intégrée « Node offline » ; une action demandée est refusée 422 agent_offline ; une action déjà émise et jamais remise finit failed / agent_unreachable TestAbsenceRule (alerts), TestCreateActionRefusals (api), TestUndeliveredCommandIsAgentUnreachable (orchestrator)
Redémarrage de l'orchestrateur aucun état en mémoire ; aucune seconde commande n'est émise ; les actions en vol sont réconciliées TestCrashRestartNeverIssuesASecondCommand, TestTwoInstancesNoDuplicates, TestLeaderRunsOnce
Crash de l'agent pendant une commande au redémarrage, commande rapportée failed avec outcome_unknown=true, jamais relancée TestUnresolvedAfterCrash (agent/journal), TestUnknownOutcomeAfterAgentCrash (ingest)
Redémarrage de l'ingestion cache de nonces des requêtes perdu : protection anti-rejeu réduite à la fenêtre ±90 s (appels idempotents) documenté dans signed.go ; non testé en tant que tel
Redémarrage de control-api les sessions survivent (elles sont en base) ; le client SSE reprend avec Last-Event-ID test Playwright « the connection indicator reacts to a backend restart… » (apps/web/e2e/specs/04-realtime.spec.ts)
Web (Next) arrêté control-api répond 503 unavailable pour les pages ; l'API reste disponible lecture de server.go (rp.ErrorHandler)
Gel d'urgence (orchestrator.frozen) aucune commande émise ; POST /actions répond 503 orchestrator_frozen ; les actions déjà en file attendent TestFreezeHoldsQueuedActions, TestCancelAndFreeze

# 9. Capacité et rétention

Donnée Rétention Mécanisme Réglage
samples_raw (10 s) 7 jours partitions journalières supprimées MCC_RETAIN_RAW
samples_1m 30 jours partitions mensuelles + suppression MCC_RETAIN_1M
samples_1h 400 jours idem MCC_RETAIN_1H
events_outbox 1 heure events.Prune toutes les 5 min constante events.Retention
action_events d'actions terminées 90 jours ménage horaire réglage retention.action_events_days (lu par housekeeping.go, non exposé par l'API d'administration)
alert_notifications livrées 30 jours ménage horaire —
audit_log illimitée jamais purgé —
agent_report_seqs, rollup_dirty rétention brute + 1 jour Server.Retention —
nas_observations 24 heures Server.Retention —
Sauvegardes locales 14 fichiers mccctl backup --keep 14 manifeste mld
  • Volume attendu : l'ordre de grandeur retenu à la conception est ≈ 6 M lignes brutes par jour pour 29 nœuds (ADR 0003). Ce chiffre est une estimation ; le volume réel en production n'a pas été relevé pour ce document.
  • Cardinalité bornée par rapport (report.go) : ≤ 400 échantillons, ≤ 8 interfaces, ≤ 12 volumes, ≤ 15 processus, ≤ 200 services ; corps ≤ 1 Mio compressé, ≤ 4 Mio décompressé.
  • Charge de l'agent : ≈ 0 % CPU et ≈ 25 Mo de mémoire résidente mesurés sur le nœud pilote [prod] ; 23 Mo et 0,2 % d'un cœur dans le relevé local docs/pilot/2026-11-18/evidence-signed.txt. Plafond GOMEMLIMIT=64MiB dans les fichiers launchd/systemd.
  • Processus : max_memory_restart 600 Mo (services Go) et 700 Mo (web) dans infra/deploy/mld-manifest.json.
  • Limites connues : les réglages retention.raw_days, retention.1m_days, retention.1h_days modifiables dans l'interface d'administration ne sont pas lus par telemetry-ingest, qui applique sa configuration de démarrage. Seuil de révision du choix PostgreSQL natif : ≈ 50 M lignes/jour (ADR 0003).

# 10. Limites / non vérifié

  • Aucune réplication de base ni bascule automatique : l'objectif de reprise est « restaurer la sauvegarde de la nuit sur un autre nœud, les agents rejouent leur tampon » (OPERATIONS.md §9).
  • Le comportement de control-api pendant une coupure de base n'est couvert par aucun test automatisé.
  • go test -race n'a pas été exécuté sur les paquets ingest et agent.
  • Les formes de plusieurs événements SSE émis diffèrent du contrat (API.md §8).
  • Les versions rapportées par telemetry-ingest et action-orchestrator ne sont pas estampillées par make build (les -ldflags ne visent que internal/api) : elles affichent 0.1.0-dev et dev.
  • Les applications natives ne sont pas décrites ici : voir APPLE-APPS.md.
Files main
Menu

Theme