Principios de arquitectura del cliente

Esta página describe cómo debe estructurarse un cliente, no el formato de los mensajes intercambiados (ver Modelo de datos y las páginas siguientes para eso).

Principio: un datastore único posee la verdad

El cliente mantiene una única estructura de datos que representa el estado actual (módulos → propiedades → elementos). Toda la UI lee esta estructura; nada más la modifica salvo los mensajes recibidos del servidor.

Lectura   :  Datastore ────────────► UI

Escritura :  UI ─── SV/SA ───► Servidor ─── update ───► Datastore

• Sin duplicación: si un componente necesita un valor, lo lee en el datastore, no lo almacena por su cuenta.
• Sin escritura directa: la UI nunca modifica el datastore ella misma, ni siquiera para una visualización optimista.

Principio: ninguna dependencia de internet

Un servidor OST suele ejecutarse en una red local aislada — un observatorio remoto sin acceso a internet es un despliegue normal, no un caso extremo. Un cliente debe funcionar correctamente en esa situación: cualquier recurso que necesite debe ir incluido con el propio cliente, no obtenerse de un CDN u otro servicio externo en tiempo de ejecución.

Esto afecta directamente al renderizado de iconos: preicon1/preicon2/posticon1/posticon2/preicon/posticon dan un nombre de icono de Google Fonts (Material Icons), no una URL — un cliente debe incluir localmente la fuente/los glifos de iconos (vendorizados, autoalojados, o empaquetados en la compilación) en vez de cargar la hoja de estilos del CDN de Google, que deja de funcionar silenciosamente en el momento en que no hay ruta hacia internet.

Lo mismo aplica a cualquier otra cosa que un cliente pudiera verse tentado a traer de un CDN: un framework JS, una librería de gráficos, una fuente web para la propia interfaz. Si el cliente lo necesita para funcionar, va incluido con el cliente.

Recomendación firme: soportar al menos un tema oscuro y uno claro

Los clientes OST se usan habitualmente junto al ocular o junto al telescopio, de noche — una interfaz a brillo total, con fondo blanco, no es ahí solo un desajuste de estilo, arruina activamente la visión nocturna del operador. Un cliente debe ofrecer como mínimo tanto un tema oscuro como uno claro, sin fijar uno u otro de forma rígida.

Esto no forma parte del protocolo de comunicación — nada de esto se impone ni es siquiera visible del lado del servidor — pero es una recomendación firme para cualquier cosa pensada para usarse en sesiones reales de astrofotografía, no solo como demo o como herramienta de pruebas de escritorio.

Dump completo vs actualizaciones parciales

Al conectarse, el cliente envía DU; el servidor responde con un dump completo (d) que contiene todos los módulos con sus metadatos completos (label, type, min/max, LOV, etc.).

Renderizado: limitar las actualizaciones a la propiedad modificada

Plantillas: pantallas por tipo de módulo con repliegue genérico

Cada instancia de módulo puede anunciar infos.template (ver Modelo de datos) — una cadena que nombra su tipo ("focus", "guider", "sequencer"…). Es solo indicativo, y puede estar ausente.

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

Formularios de propiedad: SA, obligatorio para directedit: false

Más allá del SV campo a campo, una propiedad editable necesita un camino de formulario: una pantalla que liste todos sus elementos editables a la vez, enviados juntos vía SA.

Solo los elementos editables pertenecen a este formulario — los tipos de solo visualización (img, video, light, prg, message) se renderizan, nunca se envían; hay que excluirlos por completo del payload en lugar de enviarles un valor sin sentido.

La misma forma de “enviar un conjunto de elementos a la vez” se reutiliza en la creación de línea de cuadrícula (GC) y su actualización (GU) — ambas toman un mapa e exactamente igual que SA. Vale la pena construir un único componente de formulario reutilizable que sirva tanto al formulario de propiedad simple como al diálogo de creación de fila de cuadrícula y al de edición de fila — en lugar de tres implementaciones separadas de esencialmente la misma lógica (“renderizar elementos editables, recoger sus valores”). Es lo que hace Rooster.

Heartbeat

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

Reconexión

Ejemplo mínimo: primer intercambio

Sin framework, solo el primer intercambio (conexión → DU → escucha) — extraído de test-ws-advanced.js, el script usado para el health-check horario del servidor:

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

Ejemplo: lectura y escritura en Rooster

Extractos reales que ilustran la separación lectura/escritura del inicio de esta página, una vez que se construye un cliente real (aquí Rooster, en Angular) alrededor de este principio.

Lectura — datastore.service.ts, un simple acceso al estado 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();
  });
}

Escritura — websocket.service.ts, sin ninguna mutación local, solo el envío del mensaje:

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