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èreservices/internal/api/gen.go(types + serveur strict),ops_gen.go(tableOperations: méthode, chemin, mode d'authentification, permission, step-up) etunimplemented_gen.go(réponse 501 par défaut).tools/gen-api.pyproduit 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 deOperations. 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 testTestEveryClusterAndAdminOperationIsImplemented(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 (StreamEventsest servi hors du serveur généré, parevents_stream.go). - Relais des agents (
agent_proxy.go) : retransmet/agent/v1/*vers l'écoute « requêtes signées » detelemetry-ingest, en supprimantCookie,Authorizationet l'en-têteX-Forwarded-Forentrant (remplacé par l'adresse résolue parcontrol-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. PlafondGOMEMLIMIT=64MiBdans les fichiers launchd/systemd. - Processus :
max_memory_restart600 Mo (services Go) et 700 Mo (web) dansinfra/deploy/mld-manifest.json. - Limites connues : les réglages
retention.raw_days,retention.1m_days,retention.1h_daysmodifiables dans l'interface d'administration ne sont pas lus partelemetry-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-apipendant une coupure de base n'est couvert par aucun test automatisé. go test -racen'a pas été exécuté sur les paquetsingestetagent.- Les formes de plusieurs événements SSE émis diffèrent du contrat (API.md §8).
- Les versions rapportées par
telemetry-ingestetaction-orchestratorne sont pas estampillées parmake build(les-ldflagsne visent queinternal/api) : elles affichent0.1.0-devetdev. - Les applications natives ne sont pas décrites ici : voir APPLE-APPS.md.