Principi di architettura client

Questa pagina descrive come deve essere strutturato un client, non il formato dei messaggi scambiati (vedi Modello dati e le pagine seguenti per quello).

Principio: un datastore unico detiene la verità

Il client mantiene un’unica struttura di dati che rappresenta lo stato corrente (moduli → proprietà → elementi). Tutta la UI legge questa struttura; nulla altro la modifica se non i messaggi ricevuti dal server.

Lettura   :  Datastore ────────────► UI

Scrittura :  UI ─── SV/SA ───► Server ─── update ───► Datastore

• Nessuna duplicazione: se un componente ha bisogno di un valore, lo legge dal datastore, non lo conserva per proprio conto.
• Nessuna scrittura diretta: la UI non modifica mai il datastore da sola, nemmeno per una visualizzazione ottimistica.

Principio: nessuna dipendenza da internet

Un server OST gira spesso su una rete locale isolata — un sito osservativo remoto senza accesso a internet è un’installazione normale, non un caso limite. Un client deve funzionare correttamente in questa situazione: ogni risorsa di cui ha bisogno deve essere inclusa nel client stesso, non recuperata da un CDN o un altro servizio esterno a runtime.

Questo riguarda direttamente il rendering delle icone: preicon1/preicon2/posticon1/posticon2/preicon/posticon forniscono un nome di icona Google Fonts (Material Icons), non un URL — un client deve includere localmente il font/le glyph delle icone (vendorizzati, autoospitati, o inclusi in fase di build) invece di caricare il foglio di stile del CDN di Google, che smette silenziosamente di funzionare nel momento in cui non c’è più una via verso internet.

Lo stesso vale per qualsiasi altra cosa che un client potesse essere tentato di prelevare da un CDN: un framework JS, una libreria di grafici, un web font per l’interfaccia stessa. Se serve al client per funzionare, viaggia insieme al client.

Raccomandazione forte: supportare almeno un tema scuro e uno chiaro

I client OST vengono usati comunemente all’oculare o accanto a un telescopio, di notte — un’interfaccia a piena luminosità, con sfondo bianco, lì non è solo una discordanza stilistica: rovina attivamente la visione notturna dell’operatore. Un client dovrebbe offrire come minimo sia un tema scuro sia uno chiaro, senza fissarne uno in modo rigido nel codice.

Questo non fa parte del protocollo di comunicazione — qui non c’è nulla che sia imposto o anche solo visibile lato server — ma è una raccomandazione forte per qualsiasi cosa pensata per essere usata in vere sessioni di astrofotografia, non solo come demo o strumento di test da scrivania.

Dump completo vs aggiornamenti parziali

Alla connessione, il client invia DU; il server risponde con un dump completo (d) contenente tutti i moduli con i loro metadati completi (label, tipo, min/max, LOV, ecc.).

Rendering: limitare gli aggiornamenti alla proprietà modificata

Template: schermate per tipo di modulo con fallback generico

Ogni istanza di modulo può dichiarare infos.template (vedi Modello dati) — una stringa che ne indica il tipo ("focus", "guider", "sequencer"…). È solo un suggerimento, ed è ammesso che sia assente.

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

Form di proprietà: SA, obbligatorio per directedit: false

Oltre a SV campo per campo, una proprietà editabile ha bisogno di un percorso form: una schermata che elenca tutti i suoi elementi editabili in una volta, inviati insieme tramite SA.

Solo gli elementi editabili appartengono a questo form — i tipi di sola visualizzazione (img, video, light, prg, message) vengono renderizzati, mai inviati; vanno esclusi del tutto dal payload piuttosto che inviare loro un valore privo di senso.

La stessa forma “inviare un insieme di elementi in una volta” è riusata dalla creazione di riga di griglia (GC) e dal suo aggiornamento (GU) — entrambi prendono una mappa e esattamente come SA. Vale la pena costruire un unico componente form riutilizzabile che serva sia il form della proprietà semplice, sia la finestra di creazione riga di griglia, sia quella di modifica riga — invece di tre implementazioni separate della stessa logica di fondo (“renderizzare elementi editabili, raccoglierne i valori”). È quello che fa Rooster.

Heartbeat

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

Riconnessione

Esempio minimo: primo scambio

Senza framework, solo il primissimo scambio (connessione → DU → ascolto) — estratto da test-ws-advanced.js, lo script usato per il health-check orario del server:

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());
});

Esempio: lettura e scrittura in Rooster

Estratti reali che illustrano la separazione lettura/scrittura vista in cima a questa pagina, una volta che un client reale (qui Rooster, in Angular) è costruito attorno a questo principio.

Lettura — datastore.service.ts, un semplice accesso allo stato interno:

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();
  });
}

Scrittura — websocket.service.ts, nessuna mutazione locale, solo l’invio del messaggio:

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