+----------------------------+ | 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: 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 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: