X-Git-Url: https://git.llucax.com/z.facultad/75.42/plaqui.git/blobdiff_plain/32157e590a73e061b32befd7f0b21973529632a1..340caac0e76b14e8deb7775d5059f61406df96bd:/docs/server.txt diff --git a/docs/server.txt b/docs/server.txt index 465dd76..eaee99a 100644 --- a/docs/server.txt +++ b/docs/server.txt @@ -1,54 +1,247 @@ -vim: set ts=4 sw=4 tw=80: -$Id$ -Propuesta de servidor v0.1: + +----------------------------+ + | PROPUESTA DE SERVIDOR v0.4 | + +----------------------------+ + + $Id$ + + Leandro Lucarella + (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 de la planta : - GET //set/?cerrar HTTP/1.0 - Pone el de en 3 l/s: - GET //set/?caudal=3 HTTP/1.0 - Comienza la simulación de la planta : - GET //start HTTP/1.0 - Empieza a transmitir a host:port la simulación de la planta : - GET //connect?host=localhost&port=1234 HTTP/1.0 - Deja de transmitir a host:port la simulación de la planta : - GET //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: +/////<...>/ + +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/ |Obtiene la planta de |El mismo archivo que se crea en el + |nombre . |Constructor. +---------------+-----------------------------+---------------------------------- +start/ |Comienza la simulación de la |Nada. + |planta de nombre . | +---------------+-----------------------------+---------------------------------- +stop/ |Finaliza la simulación de la |Nada. + |planta de nombre . | +---------------+-----------------------------+---------------------------------- +set/ |Cambia la propiedad |Nada (a ver si no retorna el valor + / |del elemento , |realmente aceptado). + / |asignándole el valor a | + / |planta de nombre . | + +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/ |Comienza la transmisión de la planta |Nada. + // | al en elpuerto al | + |en el puerto . | +-------------------+-----------------------------------------+------------------ +stop// |Finaliza la transmisión al en el |Nada. + |puerto . Si se omite el , se | + |finalizan todas las transmisiones al | + |. Si se omite el , 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// |Finaliza la conexión de control del host |Nada. + | en el puerto . Si se omite | + |el se finalizan todas las | + |conexiones al . Si se omite también| + |el , 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): + + + +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: + + + + + + + + + + + + + + + + + +TODO: Ver si la lista va dentro o fuera del tag , ver si el tag + 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: