-vim: set ts=4 sw=4 tw=80:
-$Id$
-Propuesta de servidor v0.1:
+ +----------------------------+
+ | PROPUESTA DE SERVIDOR v0.4 |
+ +----------------------------+
+
+ $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).
+
+
+Descripción de los comandos 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'
+será 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 en general:
+--------------------
+Los comandos se tiene una estructura general compuesta por 3 elementos:
+- Destino: A quien se le envía el comando.
+- Comando: El comando en sí (la acción a realizar).
+- Argumentos: Opciones y datos necesarios para ejecutar el comando.
+Esto se estructura como una ruta, por lo que todos los comandos se componen la
+menos de 2 'directorios' anidados, con cero o más argumentos representados a su
+ves por archivos o más subdirectorios:
+/<destino>/<comando>/<argumento 1>/<argumento 2>/<...>/<argumento N>
+
+Los destinos disponibles serán:
+- server: Comandos para el servidor en sí.
+- plant: Comandos para las plantas.
+- transmission: Comandos para las transmisiones (el módulo de transmisión).
+
+Comandos para el servidor:
+--------------------------
+Los comandos para el servidor, como se vio previamente, comienzan con /server/
+seguido de alguna de las siguientes opciones.
+
+Comando | Descripción | Respuesta
+---------+------------------------+---------------------------------------------
+status | Obtiene estado general | Cantidad de plantas, conexiones,
+ | del servidor. | transmisiones, versión, uptime, etc.
+---------+------------------------+---------------------------------------------
+stop | Detiene el servidor. | Nada.
+
+Comandos para una Planta:
+-------------------------
+Todos los comandos de plantas comienzan con /plant/ y continúan con alguna de
+las siguientes opciones:
+
+Comando |Descripción |Respuesta
+---------------+-----------------------------+----------------------------------
+list |Obtiene lista de plantas. |Lista de plantas con info mínima
+ | |de cada una (está corriendo o no,
+ | |uptime, cantidad de elementos,etc)
+---------------+-----------------------------+----------------------------------
+get/<planta> |Obtiene la planta de |El mismo archivo que se crea en el
+ |nombre <planta>. |Constructor.
+---------------+-----------------------------+----------------------------------
+start/<planta> |Comienza la simulación de la |Nada.
+ |planta de nombre <planta>. |
+---------------+-----------------------------+----------------------------------
+stop/<planta> |Finaliza la simulación de la |Nada.
+ |planta de nombre <planta>. |
+---------------+-----------------------------+----------------------------------
+set/<planta> |Cambia la propiedad <prop> |Nada (a ver si no retorna el valor
+ /<elem> |del elemento <elem>, |realmente aceptado).
+ /<prop> |asignándole el valor <val> a |
+ /<val> |planta de nombre <planta>. |
+
+NOTA: Los nombres entre "<" y ">" denotan un argumento.
+
+Comandos para una Transmisión:
+------------------------------
+Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
+alguna de las siguientes opciones:
+
+Comando |Descripción |Respuesta
+-------------------+-----------------------------------------+------------------
+list |Obtiene una lista de las transmisiones |Lista de transmi-
+ |activas. |siones activas
+ | |(host, puerto,
+ | |uptime, etc).
+-------------------+-----------------------------------------+------------------
+start/<plant> |Comienza la transmisión de la planta |Nada.
+ /<host>/<port> |<plant> al <host> en elpuerto al <host> |
+ |en el puerto <port>. |
+-------------------+-----------------------------------------+------------------
+stop/<host>/<port> |Finaliza la transmisión al <host> en el |Nada.
+ |puerto <port>. Si se omite el <port>, se |
+ |finalizan todas las transmisiones al |
+ |<host>. Si se omite el <host>, se |
+ |finalizan todas las transmisiones. |
+
+Comandos para una Conexión de Control:
+--------------------------------------
+Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
+alguna de las siguientes opciones:
+
+Comando |Descripción |Respuesta
+-------------------+-----------------------------------------+------------------
+list |Obtiene una lista de las conexiones de |Lista de conexio-
+ |control activas. |nes activas (host,
+ | |puerto, uptime,
+ | |etc).
+-------------------+-----------------------------------------+------------------
+stop/<host>/<port> |Finaliza la conexión de control del host |Nada.
+ |<host> en el puerto <port>. Si se omite |
+ |el <port> se finalizan todas las |
+ |conexiones al <host>. Si se omite también|
+ |el <host>, se finalizan todas las |
+ |conexiones de control. |
+
+NOTA: Los nombres entre "<" y ">" denotan un argumento.
+
+
+Descripción de los comandos para el módulo de control:
+======================================================
+
+Todas las respuestas consisten de un archivo XML con esta forma (falta hacer la
+DTD):
+<plaqui version="0.1">
+ <response code="[código]" />
+</plaqui>
+El código es obligatorio e informará si el comando se realizó con éxito y en
+caso de no hacerlo, indicará la razón (los códigos faltan definirlos, pero usar
+un esquema similar a los códigos de HTTP sería un buen comienzo).
+La respuesta también puede tener otros contenidos (listado de plantas,
+conexiónes, transmisiones, descripción de una planta completa, etc). Dichos
+contenidos irán contenidos en el tag response:
+<plaqui version="0.1">
+ <response code= "[código]">
+ <list type="plants">
+ <item id="[id1]">
+ <prop name="[nombre1]" value="[valor1]" />
+ <prop name="[nombre2]" value="[valor2]" />
+ <!-- ... más ... -->
+ </item>
+ <item id="[id2]">
+ <prop name="[nombre1]" value="[valor3]" />
+ <prop name="[nombre2]" value="[valor4]" />
+ <!-- ... más ... -->
+ </item>
+ </list>
+ </response>
+</plaqui>
+
+TODO: Ver si la lista va dentro o fuera del tag <response>, ver si el tag
+ <plaqui> está bien, es útil y correcto.
+
+
+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'.
+
+Atajos de comandos:
+-------------------
+Se trata de 'alias' de comandos. Por ejemplo que '/' de un estado del server
+(/sever/status), que /plant de una lista de plantas, etc.
+
+Valores por defecto:
+--------------------
+Para los comandos que requieren argumentos se podría asumir valores por defecto
+en caso de faltar alguno.
+
+
+vim: set et ts=4 sw=4 tw=80:
projects / z.facultad / 75.42 / plaqui.git / blobdiff