docs/server.txt

   1
   2                          +----------------------------+
   3                          | PROPUESTA DE SERVIDOR v0.2 |
   4                          +----------------------------+
   5
   6                  $Id$
   7
   8                      Leandro Lucarella <llucare@fi.uba.ar>
   9                              (creado el 18/10/2003)
  10
  11 Descripción General:
  12 ====================
  13
  14 El servidor estará dividido en 2 módulos que provean 2 servicios diferentes:
  15
  16 Módulo de Control:
  17 ------------------
  18 El módulo de control se basa en el protocolo TCP y se encarga de listar
  19 los archivos de planta disponibles en el servidor, permitiendo cambiar
  20 las propiedades de cada uno y conocer su estado en términos generales
  21 (si se está simulando o no). Todo lo que sean comandos (abrir una
  22 exclusa, parar una bomba, etc) se realizan a través de este módulo.
  23 El protocolo utilizado es una implementación limitada e incompleta de
  24 HTTP 1.1. Solo se implementan los métodos POST y GET, tomando solo en
  25 cuenta la ruta del archivo a obtener (se ignora el 'query string' de GET
  26 y los datos recibidos por POST). Cada comando se representa a través de una
  27 ruta a un archivo. Si el comando recibe parámetros, estos parámetros son
  28 también representados como componentes de dicha ruta.
  29 A cada comando se responde con una respuesta HTTP 1.1 (también a través de
  30 una implementación incompleta y limitada). El cuerpo de la respuesta es un
  31 archivo XML de texto plano en formato XML que contendrá la información
  32 requerida por el comando (ya sea una lista de archivos o una respuesta
  33 informando el éxito o error al cambiar las propiedades de una planta).
  34
  35 Módulo de Transmisión:
  36 ----------------------
  37 Este módulo se encarga de transmitir la simulación en tiempo real por UDP
  38 (como si fuera un video). Comienza luego de que el módulo de control recibe
  39 una petición de transmisión y continúa transmitiendo (en un principio)
  40 hasta que recibe una petición de desconexión.
  41 Lo que se envía es un archivo XML con el estado de la planta.
  42 El cliente debe validar lo recibido y mostrar todos los 'frames' válidos.
  43 Mientras que no se reciban 'frames' válidos se debe mostrar el último
  44 válido. Si no se recibiece durante una cantidad de tiempo determinada ningún
  45 'frame' válido, se asume un error en la red.
  46 Si por casualidad los datos recibidos son incorrectos pero válidos (por
  47 ejemplo, se recibe el comienzo de un 'frame' y el final del siguente), el
  48 cliente lo mostrará igual porque no tiene forma de darse cuenta. Esto no es
  49 problema si consideramos que en pocos milisegundos se recibirá un nuevo
  50 'frame' válido y correcto (similar a lo que pasa en transmisiones de audio o
  51 video en tiempo real).
  52
  53
  54 Lista de comandos disponibles para el módulo de control:
  55 ========================================================
  56
  57 Todos los comandos son rutas de archivos. En un principio no se van a utilizar
  58 los 'query string' de los datos pasados por GET ni datos adicionales pasados
  59 por POST. Es decir, de un 'request' HTTP solo se usara la ruta para codificar
  60 los comandos. Ejemplo: GET /ruta/que/representa/comando?query=string HTTP/1.1
  61                           '----------------------------'
  62 Este es el comando que entendera el servidor. La presencia de un 'query string'
  63 sera ignorada, al igual que datos enviados por POST, silenciosamente (sin
  64 producir un error).
  65
  66 Todos los comandos son respondidos con una respuesta XML que *siempre* incluye
  67 un código de éxito/error. Adicionalmente puede devolver más datos en la
  68 respuesta en cuyo caso se especifica expresamente.
  69
  70 Comandos Generales:
  71 -------------------
  72 Los nombres entre "<" y ">" denotan un argumento.
  73
  74 Comando               |Descripción           |Respuesta
  75 ----------------------+----------------------+----------------------------------
  76 /                     |Obtiene estado general|Cantidad de plantas,
  77                       |del servidor.         |conexiones, transmisiones,
  78                       |                      |versión, uptime, etc.
  79 ----------------------+----------------------+----------------------------------
  80 /plants               |Obtiene lista de      |Lista de plantas con info mínima
  81                       |plantas.              |de cada una (está corriendo o no,
  82                       |                      |uptime, cantidad de elementos,etc)
  83 ----------------------+----------------------+----------------------------------
  84 /plants/<nombre>      |Obtiene la planta de  |El mismo archivo que se crea en el
  85                       |nombre <nombre>.      |Constructor.
  86 ----------------------+----------------------+----------------------------------
  87 /transmissions        |Obtiene una lista de  |Lista de transmisiones activas
  88                       |las transmisiones     |(host, puerto, uptime, etc).
  89                       |activas.              |
  90
  91 Comandos para una Planta:
  92 -------------------------
  93 Todos los comandos de plantas comienzan con /plants/ y reciben un argumento que
  94 es el nombre de la planta, <nombre>, a la cual enviar el comando.
  95 Los comandos a continuación comienzan todos con '/plants/<nombre>'.
  96
  97 Comando               |Descripción           |Respuesta
  98 ----------------------+----------------------+----------------------------------
  99 /start                |Comienza la simulación|Nada.
 100                       |de la planta de nombre|
 101                       |<planta>.             |
 102 ----------------------+----------------------+----------------------------------
 103 /stop                 |Finaliza la simulación|Nada.
 104                       |de la planta de nombre|
 105                       |<planta>.             |
 106 ----------------------+----------------------+----------------------------------
 107 /set/<elem>/<prop>/<v>|Cambia la propiedad   |Nada (a ver si no retorna el valor
 108                       |<prop> del elemento   |realmente aceptado).
 109                       |<elem>, asignándole   |
 110                       |el valor <v>.         |
 111
 112 Comandos para una Transmisión:
 113 ------------------------------
 114 Todos los comandos de transmisiones comienzan con /transmissions.
 115 Los comandos a continuación comienzan todos con '/transmissions'.
 116 Los argumentos entre "[" y "]" son opcionales. De omitirse se usan valores por
 117 predefinidos.
 118
 119 Comando                 |Descripción                                 |Respuesta
 120 ------------------------+--------------------------------------------+----------
 121 /start/<host>/[<port>]  |Comienza la transmisión al <host> en el     |Nada.
 122                         |puerto al <host> en el puerto <port>.       |
 123 ------------------------+--------------------------------------------+----------
 124 /stop/[<host>]/[<port>] |Finaliza la transmisiónal <host> en el      |Nada.
 125                         |puerto <port>. Si se omite el <host>, se    |
 126                         |finalizan todas las transmisiones.          |
 127
 128
 129 Características adicionales (a desarrollar si el tiempo lo permite):
 130 ====================================================================
 131
 132 Hojas de estilo XSLT:
 133 ---------------------
 134 Es factible crear hojas de transformación de XML a HTML para enviar con las
 135 respuestas XML del módulo de control, de forma tal que pueda controlarse la
 136 planta desde un navegador web que soporte esto (como Mozilla).
 137 Las hojas de estilos estarían en la ruta /web, al igual que imágenes y otros
 138 archivos complementarios.
 139
 140 Módulo de Transmisión sobre TCP:
 141 --------------------------------
 142 Opcionalmente se puede hacer un Módulo de transmisión sobre TCP, que sólo envíe
 143 el estado actual de la planta en ese instante y se desconecte, o directamente
 144 implementarlo como un comando del módulo de control para poder verlo en un
 145 navegador web. Aunque esto ya sería más un cliente que un servidor.
 146
 147 'keep-alive' para el Módulo de Transmisión:
 148 -------------------------------------------
 149 En el futuro se puede agregar una respuesta de tipo 'keep-alive' para que el
 150 transmisor UDP deje de transmitir a un host si no recibe una señal del receptor
 151 cada una cantidad de tiempo determinada. De esta manera se evita seguir
 152 transmitiendo si un cliente se cierra sin enviar el comando de fin de
 153 transmisión por el Módulo de Control.
 154
 155 Envío por 'broadcast' del módulo de transmisión:
 156 ------------------------------------------------
 157 Es posible hacer que el comando /transmissions/start sin argumentos comience una
 158 transmisión por 'broadcast' de la planta para todo aquel que quiera monitorearla
 159 desde la red en la que se haga el 'broadcast'.
 160
 161
 162 vim: set et ts=4 sw=4 tw=80: