Stack Technique & Structure (Agent)

1. Stack technique

Besoin	Choix	Raison
Langage	Go 1.22+	Binaire unique, faible empreinte, concurrence native
Daemon local	Docker Engine API via github.com/docker/docker	Discovery, événements, stats, logs et actions
Transport Agent/API	gRPC + Protocol Buffers	Contrat typé, streaming et faible overhead
Chiffrement / identité	TLS 1.3 recommandé, mTLS	Authentification mutuelle de l’Agent et de l’API
Configuration	YAML (yaml.v3) + variables d’environnement	Déploiement lisible et surcharge simple
Logs Agent	slog structuré (JSON)	Dépendance minimale et exploitation systemd
Métriques locales	Docker stats + /proc/syscall (ou petite librairie host)	Pas de base locale nécessaire
Buffer de coupure	Fichier append-only borné ou bbolt optionnel	Résilience sans transformer l’Agent en serveur de données
Tests	testing, mocks d’interfaces, Docker de test	Tests rapides puis intégration réaliste

// go.mod (extrait)
module github.com/your-org/berth-agent

go 1.22

require (
    github.com/docker/docker v27.0.0+incompatible
    google.golang.org/grpc v1.65.0
    google.golang.org/protobuf v1.34.2
    gopkg.in/yaml.v3 v3.0.1
)

2. Arborescence du projet Go

berth-agent/
├── cmd/
│   └── agent/
│       └── main.go                 # composition root, signaux, graceful shutdown
├── internal/
│   ├── config/
│   │   ├── config.go               # YAML, env, validation
│   │   └── config_test.go
│   ├── docker/
│   │   ├── client.go               # wrapper minimal du Docker SDK
│   │   ├── discovery.go            # list + labels + événements
│   │   ├── actions.go              # start/stop/restart/pull/exec
│   │   ├── stats.go                # stats containers
│   │   └── mock.go                 # interface/mock de tests
│   ├── grpc/
│   │   ├── client.go               # connexion mTLS et appels vers API
│   │   ├── reconnect.go             # reconnexion et backoff
│   │   ├── actions.go               # réception/exécution des commandes
│   │   ├── logs.go                  # server-stream côté Agent
│   │   └── proto/berth_agent.proto
│   ├── metrics/
│   │   ├── collector.go             # orchestration des collectes
│   │   ├── container.go             # CPU/RAM/réseau/blkio
│   │   └── host_linux.go             # CPU/RAM/disque/réseau de l'hôte
│   ├── streaming/
│   │   ├── logs.go                  # fan-out, contexte et limites
│   │   └── buffer.go                # buffer mémoire/local borné
│   ├── security/
│   │   ├── tls.go                   # tls.Config, CA, rotation
│   │   └── enrollment.go             # bootstrap token à usage unique
│   ├── heartbeat/
│   │   └── heartbeat.go
│   └── resilience/
│       ├── backoff.go
│       ├── breaker.go
│       └── spool.go
├── pkg/
│   ├── model/                       # types partagés sans dépendance transport
│   └── version/
├── proto/                           # source proto et buf/gen.go (selon convention)
├── configs/config.example.yaml
├── deploy/berth-agent.service
├── Dockerfile
├── go.mod
└── go.sum

Les paquets internal/ encapsulent les choix d’implémentation. La logique métier ne dépend pas directement de *client.Client : elle dépend d’interfaces, ce qui rend possible un mock Docker en test.