PD-284 — Agent Developer : Module seal-sse-client¶

Livrable : src/seal/sse-client.ts¶

Résumé¶

Ce module implémente le client SSE (Server-Sent Events) fetch-based pour le suivi temps réel des scellements PD-284. Il couvre :

• Connexion SSE via fetch + ReadableStream (parsing manuel text/event-stream)
• Reconnexion avec backoff exponentiel : delay = base × factor^attempt (1s, 2s, 4s par défaut)
• Plafond cumulé max_cumulative_delay=30s avant failover immédiat
• Failover polling à 5s après épuisement des tentatives SSE
• Tentative SSE parallèle à chaque cycle de polling (reprise automatique)
• Arrêt polling immédiat dès reconnexion SSE
• INV-284-09 : aucun badge Hors ligne déclenché par ce module (responsabilité NetInfo dans C9)

Décisions architecturales¶

architectural_decisions:
  - decision: "Factory function `createSSEClient()` au lieu d'une classe"
    rationale: "Encapsulation par closures — l'état interne (timers, AbortController) est inaccessible depuis l'extérieur. Plus idiomatique en React/hooks."
    alternatives_considered:
      - "Classe SSEClient — expose l'état interne via properties, plus complexe à tester avec mocks"
      - "Hook React `useSSE()` — couple le transport au lifecycle React, empêche l'utilisation depuis l'orchestrateur C7"
    trade_offs:
      - "Factory ne supporte pas le pattern `instanceof` — non nécessaire ici"
      - "Les closures capturent les références : attention au GC si le client n'est pas disconnect()"

Code source¶

Le fichier src/seal/sse-client.ts a été créé avec l'implémentation complète. Voici les éléments structurants :

Interfaces exportées¶

// Configuration du client SSE
export interface SSEClientConfig {
  readonly baseUrl: string;
  readonly getAuthToken: () => Promise<string>;
  readonly sealConfig?: Partial<SealConfig>;
  readonly buildPollingUrl: (sealId: SealId) => string;
  readonly buildSseUrl: (sealId: SealId) => string;
}

// Interface publique du client
export interface SSEClient {
  connect(sealId: SealId): void;
  disconnect(): void;
  readonly transportMode: TransportMode;
}

export type TransportMode = "SSE" | "POLLING" | "DISCONNECTED";
export type SSEEventCallback = (data: unknown) => void;
export type SSETransportChangeCallback = (mode: TransportMode) => void;

Factory¶

export function createSSEClient(
  config: SSEClientConfig,
  onEvent: SSEEventCallback,
  onTransportChange?: SSETransportChangeCallback,
): SSEClient;

Mécanismes clés¶

1. Parsing SSE manuel : readSSEStream() décode le flux text/event-stream ligne par ligne, accumule les lignes data:, et émet un événement JSON à chaque ligne vide (fin de bloc SSE). Les lignes de commentaire (:) sont ignorées (heartbeats).

2. Backoff exponentiel (reconnectWithBackoff) :

3. Boucle de 0 à max_attempts - 1
4. delay = base × factor^attempt → 1s, 2s, 4s avec les defaults
5. Accumulation de cumulativeDelay — si > max_cumulative_delay → failover immédiat sans attendre les tentatives restantes

6. Chaque tentative crée un nouvel AbortController pour annulation propre

7. Failover polling (startPolling) :

8. setInterval à polling_interval_after_sse_failover × 1000 ms
9. Chaque tick : pollOnce() (GET status) + attemptSSEReconnectFromPolling() en parallèle

10. Si SSE reconnecte → stopPolling() immédiat + setTransport("SSE")

11. Lifecycle :

12. connect() est idempotent — disconnect l'instance précédente
13. disconnect() abort toutes les connexions (AbortController), stop le polling, clear les timers de retry
14. Le flag disconnected est vérifié à chaque point de reprise async pour éviter les effets de bord post-disconnect

Matrice de couverture invariants¶

Vérification des interdits (forbidden)¶

Hypothèses¶

Fichiers hors périmètre identifiés¶

Aucun. Le module seal-sse-client ne dépend que de src/types/seal.ts (C1) et src/seal/telemetry.ts (C13), tous deux dans le périmètre autorisé.

Tests contractuels couverts¶