Principes d'architecture client

Cette page décrit comment un client doit être structuré, pas le format des messages échangés (voir Structure des données et les pages suivantes pour ça).

Principe : un datastore unique détient la vérité

Le client maintient une seule structure de données représentant l’état courant (modules → propriétés → éléments). Toute l’UI lit cette structure ; rien d’autre ne la modifie que les messages reçus du serveur.

Lecture  :  Datastore ────────────► UI

Écriture :  UI ─── SV/SA ───► Serveur ─── update ───► Datastore

• Pas de duplication : si un composant a besoin d’une valeur, il la lit dans le datastore, il ne la stocke pas de son côté.
• Pas d’écriture directe : l’UI ne modifie jamais le datastore elle-même, même pour un affichage optimiste.

Principe : aucune dépendance à internet

Un serveur OST tourne souvent sur un réseau local isolé — un site d’observatoire distant sans accès à internet est un déploiement normal, pas un cas limite. Un client doit fonctionner correctement dans cette situation : toute ressource dont il a besoin doit être embarquée avec le client lui-même, pas récupérée depuis un CDN ou un autre service externe au moment de l’exécution.

Ça concerne directement le rendu des icônes : preicon1/preicon2/posticon1/posticon2/preicon/posticon donnent un nom d’icône Google Fonts (Material Icons), pas une URL — un client doit embarquer localement la police/les glyphes d’icônes (vendorisés, auto-hébergés, ou empaquetés à la construction) plutôt que de charger la feuille de style du CDN Google, qui casse silencieusement dès qu’il n’y a plus de route vers internet.

Ça vaut aussi pour tout ce qu’un client pourrait être tenté de tirer d’un CDN : un framework JS, une bibliothèque de graphes, une police web pour l’UI elle-même. Si le client en a besoin pour fonctionner, ça part avec le client.

Recommandation forte : proposer au moins un thème sombre et un thème clair

Les clients OST sont couramment utilisés à l’oculaire ou à côté d’un télescope, de nuit — une interface pleine luminosité à fond blanc n’est pas qu’un décalage de style dans ce contexte, elle détruit purement et simplement la vision nocturne de l’opérateur. Un client doit proposer au minimum un thème sombre et un thème clair, et non figer l’un ou l’autre en dur.

Ce n’est pas une exigence du protocole filaire — rien ici n’est imposé ni même visible côté serveur — mais c’est une recommandation forte pour tout ce qui est destiné à être utilisé lors de vraies sessions d’astrophotographie, pas seulement comme démo ou outil de test de bureau.

Dump complet vs mises à jour partielles

À la connexion, le client envoie DU ; le serveur répond avec un dump complet (d) contenant tous les modules avec leurs métadonnées complètes (label, type, min/max, LOV, etc.).

Rendu : ne rafraîchir que la propriété modifiée

Templates : écrans par type de module, avec un repli générique

Chaque instance de module peut annoncer infos.template (voir Modèle de données) — une chaîne nommant son type ("focus", "guider", "sequencer"…). C’est purement indicatif, et son absence est autorisée.

template = infos.template?.toLowerCase() || "default"
screen = registry[template] ?? registry["default"]

Formulaires de propriété : SA, obligatoire pour directedit: false

Au-delà du SV champ par champ, une propriété éditable a besoin d’un chemin formulaire : un écran listant tous ses éléments éditables à la fois, soumis ensemble via SA.

Seuls les éléments éditables ont leur place dans ce formulaire — les types d’affichage seul (img, video, light, prg, message) sont rendus, jamais soumis ; à exclure complètement du payload plutôt que d’y envoyer une valeur sans sens.

La même forme « soumettre un ensemble d’éléments à la fois » est réutilisée par la création de ligne de grille (GC) et sa mise à jour (GU) — les deux prennent une map e exactement comme SA. Ça vaut le coup de construire un seul composant formulaire réutilisable qui serve à la fois le formulaire de propriété, la boîte de création de ligne de grille et celle d’édition de ligne, plutôt que trois implémentations séparées d’une logique essentiellement identique (« rendre des éléments éditables, collecter leurs valeurs »). C’est ce que fait Rooster.

Heartbeat

→ {"XX": {}}
← {"xx": {}}

Reconnexion

Exemple minimal : premier échange

Sans framework, juste le tout premier échange (connexion → DU → écoute) — extrait de test-ws-advanced.js, le script utilisé pour le health-check horaire du serveur :

const ws = new WebSocket("ws://127.0.0.1:9624");

ws.on("open", () => {
  ws.send(JSON.stringify({ "DU": { "language": "en" } }));
});

ws.on("message", (data) => {
  console.log("received:", data.toString());
});

Exemple : lecture et écriture dans Rooster

Extraits réels illustrant la séparation lecture/écriture de tête de cette page, une fois qu’un vrai client (ici Rooster, en Angular) est construit autour de ce principe.

Lecture — datastore.service.ts, un simple accès à l’état interne :

getProperty(moduleName: string, propertyName: string): Observable<any> {
  return new Observable(subscriber => {
    const subscription = this.changed$.subscribe(() => {
      const module = this.modules[moduleName];
      const prop = (module as any)?.properties?.[propertyName] || null;
      subscriber.next(prop);
    });
    subscriber.next(this.modules[moduleName]?.properties?.[propertyName] || null);
    return () => subscription.unsubscribe();
  });
}

Écriture — websocket.service.ts, aucune mutation locale, juste l’envoi du message :

setPropertyOneElement(module: string, property: string, elements: { [key: string]: any }): void {
  this.send({
    SV: { m: { [module]: { p: { [property]: { e: elements } } } } }
  });
}