Se actualiza el paper sobre el protocolo del servidor. Se agrega la lista de comandos...

diff --git a/docs/server.txt b/docs/server.txt
index 465dd765c0291181d808992f4527648817c87e85..9b17a81ffa5d7d3ab4ef3c6d8496509a9a343631 100644 (file)
--- a/docs/server.txt
+++ b/docs/server.txt
@@ -1,54 +1,162 @@
-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:
 
 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
 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: