-vim: set ts=4 sw=4 tw=80:
-$Id$
-Propuesta de servidor v0.1:
+ +----------------------------+
+ | PROPUESTA DE SERVIDOR v0.2 |
+ +----------------------------+
+
+ $Id$
+
+ Leandro Lucarella <llucare@fi.uba.ar>
+ (creado el 18/10/2003)
+
+Descripción General:
+====================
El servidor estará dividido en 2 módulos que provean 2 servicios diferentes:
-1) Módulo de control.
- El módulo de control se basa en el protocolo TCP y se encarga de listar
- los archivos de planta disponibles en el servidor, permitiendo cambiar
- las propiedades de cada uno y conocer su estado en términos generales
- (si se está simulando o no). Todo lo que sean comandos (abrir una
- exclusa, parar una bomba, etc) se realizan a través de este módulo.
- El protocolo que maneja es un HTTP simplificado. Se aceptan comandos
- simples (en un principio solo GET) a través de URLs.
- Ejemplos:
- Obtiene lista de archivos:
- GET / HTTP/1.0
- Cierra la <exclusa1> de la planta <archivo>:
- GET /<archivo>/set/<exclusa1>?cerrar HTTP/1.0
- Pone el <caudal> de <canio1> en 3 l/s:
- GET /<archivo>/set/<canio1>?caudal=3 HTTP/1.0
- Comienza la simulación de la planta <archivo>:
- GET /<archivo>/start HTTP/1.0
- Empieza a transmitir a host:port la simulación de la planta <archivo>:
- GET /<archivo>/connect?host=localhost&port=1234 HTTP/1.0
- Deja de transmitir a host:port la simulación de la planta <archivo>:
- GET /<archivo>/disconnect?host=localhost&port=1234 HTTP/1.0
-
- Los datos que envía este módulo están en formato XML, preferentemente con
- un archivo de transformación XSLT (o como se llame :) para que pueda ser
- visto en un browser cualquiera (que soporte esto, como Mozilla).
-
-2) Módulo de transmisión:
- Este módulo se encarga de transmitir la simulación en tiempo real por UDP
- (como si fuera un video). Comienza luego de que el módulo de control recibe
- una petición de transmisión (con connect) y continúa transmitiendo (en un
- thread propio) hasta que recibe un disconnect. Envía un archivo XML con el
- estado de la planta. En este caso no tiene sentido la XSLT porque no hay
- browsers HTTP que usen UDP :).
- El cliente debe validar lo recibido y mostrar todos los 'frames' válidos.
- Mientras que no se reciban 'frames' válidos se debe mostrar el último
- válido. Si no se recibiece durante una cantidad de tiempo determinada ningún
- 'frame' válido, se asume un error en la red.
- Si por casualidad los datos recibidos son incorrectos pero válidos (por
- ejemplo, se recibe el comienzo de un 'frame' y el final del siguente), el
- cliente lo mostrará igual porque no tiene forma de darse cuenta. Esto no es
- problema si consideramos que en pocos milisegundos se recibirá un nuevo
- 'frame' válido y correcto (similar a lo que pasa en transmisiones de audio o
- video en tiempo real).
-
-Opcionalmente se puede hacer un Módulo de transmición sobre TCP, que sólo envíe
+
+Módulo de Control:
+------------------
+El módulo de control se basa en el protocolo TCP y se encarga de listar
+los archivos de planta disponibles en el servidor, permitiendo cambiar
+las propiedades de cada uno y conocer su estado en términos generales
+(si se está simulando o no). Todo lo que sean comandos (abrir una
+exclusa, parar una bomba, etc) se realizan a través de este módulo.
+El protocolo utilizado es una implementación limitada e incompleta de
+HTTP 1.1. Solo se implementan los métodos POST y GET, tomando solo en
+cuenta la ruta del archivo a obtener (se ignora el 'query string' de GET
+y los datos recibidos por POST). Cada comando se representa a través de una
+ruta a un archivo. Si el comando recibe parámetros, estos parámetros son
+también representados como componentes de dicha ruta.
+A cada comando se responde con una respuesta HTTP 1.1 (también a través de
+una implementación incompleta y limitada). El cuerpo de la respuesta es un
+archivo XML de texto plano en formato XML que contendrá la información
+requerida por el comando (ya sea una lista de archivos o una respuesta
+informando el éxito o error al cambiar las propiedades de una planta).
+
+Módulo de Transmisión:
+----------------------
+Este módulo se encarga de transmitir la simulación en tiempo real por UDP
+(como si fuera un video). Comienza luego de que el módulo de control recibe
+una petición de transmisión y continúa transmitiendo (en un principio)
+hasta que recibe una petición de desconexión.
+Lo que se envía es un archivo XML con el estado de la planta.
+El cliente debe validar lo recibido y mostrar todos los 'frames' válidos.
+Mientras que no se reciban 'frames' válidos se debe mostrar el último
+válido. Si no se recibiece durante una cantidad de tiempo determinada ningún
+'frame' válido, se asume un error en la red.
+Si por casualidad los datos recibidos son incorrectos pero válidos (por
+ejemplo, se recibe el comienzo de un 'frame' y el final del siguente), el
+cliente lo mostrará igual porque no tiene forma de darse cuenta. Esto no es
+problema si consideramos que en pocos milisegundos se recibirá un nuevo
+'frame' válido y correcto (similar a lo que pasa en transmisiones de audio o
+video en tiempo real).
+
+
+Lista de comandos disponibles para el módulo de control:
+========================================================
+
+Todos los comandos son rutas de archivos. En un principio no se van a utilizar
+los 'query string' de los datos pasados por GET ni datos adicionales pasados
+por POST. Es decir, de un 'request' HTTP solo se usara la ruta para codificar
+los comandos. Ejemplo: GET /ruta/que/representa/comando?query=string HTTP/1.1
+ '----------------------------'
+Este es el comando que entendera el servidor. La presencia de un 'query string'
+sera ignorada, al igual que datos enviados por POST, silenciosamente (sin
+producir un error).
+
+Todos los comandos son respondidos con una respuesta XML que *siempre* incluye
+un código de éxito/error. Adicionalmente puede devolver más datos en la
+respuesta en cuyo caso se especifica expresamente.
+
+Comandos Generales:
+-------------------
+Los nombres entre "<" y ">" denotan un argumento.
+
+Comando |Descripción |Respuesta
+----------------------+----------------------+----------------------------------
+/ |Obtiene estado general|Cantidad de plantas,
+ |del servidor. |conexiones, transmisiones,
+ | |versión, uptime, etc.
+----------------------+----------------------+----------------------------------
+/plants |Obtiene lista de |Lista de plantas con info mínima
+ |plantas. |de cada una (está corriendo o no,
+ | |uptime, cantidad de elementos,etc)
+----------------------+----------------------+----------------------------------
+/plants/<nombre> |Obtiene la planta de |El mismo archivo que se crea en el
+ |nombre <nombre>. |Constructor.
+----------------------+----------------------+----------------------------------
+/transmissions |Obtiene una lista de |Lista de transmisiones activas
+ |las transmisiones |(host, puerto, uptime, etc).
+ |activas. |
+
+Comandos para una Planta:
+-------------------------
+Todos los comandos de plantas comienzan con /plants/ y reciben un argumento que
+es el nombre de la planta, <nombre>, a la cual enviar el comando.
+Los comandos a continuación comienzan todos con '/plants/<nombre>'.
+
+Comando |Descripción |Respuesta
+----------------------+----------------------+----------------------------------
+/start |Comienza la simulación|Nada.
+ |de la planta de nombre|
+ |<planta>. |
+----------------------+----------------------+----------------------------------
+/start |Finaliza la simulación|Nada.
+ |de la planta de nombre|
+ |<planta>. |
+----------------------+----------------------+----------------------------------
+/set/<elem>/<prop>/<v>|Cambia la propiedad |Nada (a ver si no retorna el valor
+ |<prop> del elemento |realmente aceptado).
+ |<elem>, asignándole |
+ |el valor <v>. |
+
+Comandos para una Transmisión:
+------------------------------
+Todos los comandos de transmisiones comienzan con /transmissions.
+Los comandos a continuación comienzan todos con '/transmissions'.
+Los argumentos entre "[" y "]" son opcionales. De omitirse se usan valores por
+predefinidos.
+
+Comando |Descripción |Respuesta
+------------------------+--------------------------------------------+----------
+/start/<host>/[<port>] |Comienza la transmisión al <host> en el |Nada.
+ |puerto al <host> en el puerto <port>. |
+------------------------+--------------------------------------------+----------
+/stop/[<host>]/[<port>] |Finaliza la transmisiónal <host> en el |Nada.
+ |puerto <port>. Si se omite el <host>, se |
+ |finalizan todas las transmisiones. |
+
+
+Características adicionales (a desarrollar si el tiempo lo permite):
+====================================================================
+
+Hojas de estilo XSLT:
+---------------------
+Es factible crear hojas de transformación de XML a HTML para enviar con las
+respuestas XML del módulo de control, de forma tal que pueda controlarse la
+planta desde un navegador web que soporte esto (como Mozilla).
+Las hojas de estilos estarían en la ruta /web, al igual que imágenes y otros
+archivos complementarios.
+
+Módulo de Transmisión sobre TCP:
+--------------------------------
+Opcionalmente se puede hacer un Módulo de transmisión sobre TCP, que sólo envíe
el estado actual de la planta en ese instante y se desconecte, o directamente
implementarlo como un comando del módulo de control para poder verlo en un
-browser. Aunque esto ya sería más un cliente que un servidor :)
+navegador web. Aunque esto ya sería más un cliente que un servidor.
+
+'keep-alive' para el Módulo de Transmisión:
+-------------------------------------------
+En el futuro se puede agregar una respuesta de tipo 'keep-alive' para que el
+transmisor UDP deje de transmitir a un host si no recibe una señal del receptor
+cada una cantidad de tiempo determinada. De esta manera se evita seguir
+transmitiendo si un cliente se cierra sin enviar el comando de fin de
+transmisión por el Módulo de Control.
+
+Envío por 'broadcast' del módulo de transmisión:
+------------------------------------------------
+Es posible hacer que el comando /transmissions/start sin argumentos comience una
+transmisión por 'broadcast' de la planta para todo aquel que quiera monitorearla
+desde la red en la que se haga el 'broadcast'.
+
+
+vim: set et ts=4 sw=4 tw=80:
projects / z.facultad / 75.42 / plaqui.git / blobdiff