Server/include/plaqui/server/documentacion.h

   1 /** \page page_server PlaQui Server
   2
   3 \section page_server_general Descripción General.
   4         El servidor está dividido en 2 módulos que provean 2 servicios diferentes.
   5
   6         \subsection page_server_general_control Módulo de Control.
   7                 El módulo de control se basa en el protocolo TCP y se encarga de listar
   8                 los archivos de planta disponibles en el servidor, permitiendo cambiar
   9                 las propiedades de cada uno y conocer su estado en términos generales
  10                 (si se está simulando o no). Todo lo que sean comandos (abrir una
  11                 exclusa, parar una bomba, etc) se realizan a través de este módulo.
  12                 El protocolo utilizado es una implementación limitada e incompleta de
  13                 HTTP 1.1. Solo se implementan los métodos POST y GET, tomando sólo en
  14                 cuenta la ruta del archivo a obtener (se ignora el <em>query string</em> de
  15                 GET y los datos recibidos por POST). Cada comando se representa a través de
  16                 una ruta a un archivo. Si el comando recibe parámetros, estos parámetros
  17                 son también representados como componentes de dicha ruta.
  18                 A cada comando se responde con una respuesta HTTP 1.1 (también a través de
  19                 una implementación incompleta y limitada). El cuerpo de la respuesta es un
  20                 archivo XML de texto plano en formato XML que contendrá la información
  21                 requerida por el comando (ya sea una lista de archivos o una respuesta
  22                 informando el éxito o error al cambiar las propiedades de una planta).
  23                 Este módulo está implementado por las clases PlaQui::Server::ControlServer
  24                 y PlaQui::Server::ControlClient.
  25
  26                 \subsubsection page_server_general_control_http Ventajas del protocolo HTTP.
  27                         Las ventajas de montar el protocolo del servidor sobre el protocolo
  28                         HTTP son muchas. Las más destacables son las más obvias.
  29
  30                         Al usar el protocolo HTTP se puede controlar el servidor con
  31                         cualquier navegador web. Al ser las respuestas archivos XML es
  32                         fácil agregar hojas de estilo XSLT para convertirlas en HTML y
  33                         transformar un navegador web con capacidad de procesar hojas XSLT
  34                         (como Mozilla) en un cliente casi con las mismas capacidades y
  35                         facilidad de uso que uno hecho especialmente para PlaQui.
  36
  37                         Otra ventaja importante es que muchos lugares sin acceso real a
  38                         Internet tienen acceso a un proxy HTTP, por lo que la accesibilidad
  39                         del servicio se vuelve muy fácil incluso en redes muy protegidas.
  40
  41         \subsection page_server_general_transmision Módulo de Transmisión.
  42                 Este módulo se encarga de transmitir la simulación en tiempo real por UDP
  43                 (como si fuera un video). Comienza luego de que el módulo de control recibe
  44                 una petición de transmisión y continúa transmitiendo (en un principio)
  45                 hasta que recibe una petición de desconexión.
  46                 Lo que se envía es un archivo XML con el estado de la planta.
  47                 El cliente debe validar lo recibido y mostrar todos los <em>frames</em>
  48                 válidos. Mientras que no se reciban <em>frames</em> válidos se debe mostrar
  49                 el último válido. Si no se recibiece durante una cantidad de tiempo
  50                 determinada ningún <em>frame</em> válido, se asume un error en la red.
  51                 Si por casualidad los datos recibidos son incorrectos pero válidos (por
  52                 ejemplo, se recibe el comienzo de un <em>frame</em> y el final del siguente),
  53                 el cliente lo mostrará igual porque no tiene forma de darse cuenta. Esto no
  54                 es problema si consideramos que en pocos milisegundos se recibirá un nuevo
  55                 <em>frame</em> válido y correcto (similar a lo que pasa en transmisiones de
  56                 audio o video en tiempo real).
  57                 Este módulo está implementado por las clases PlaQui::Server::Transmitter y
  58                 PlaQui::Server::Receiver.
  59
  60
  61 \section page_server_protocolo Comandos del Módulo de Control.
  62         Todos los comandos son rutas de archivos. En un principio no se van a utilizar
  63         los <em>query string</em> de los datos pasados por GET ni datos adicionales
  64         recibidos por POST. Es decir, de un <em>request</em> HTTP solo se usara la ruta
  65         para codificar los comandos. Por ejemplo, de:
  66         \verbatim GET /ruta/que/representa/comando?query=string HTTP/1.1 \endverbatim
  67         Sólo se utilizará \verbatim /ruta/que/representa/comando \endverbatim para
  68         codificar el comando. El <em>query string</em> y los datos que se reciban por
  69         POST serán ignorados silenciosamente (sin producir un error).
  70
  71         Todos los comandos son respondidos con una respuesta XML que <b>siempre</b>
  72         incluye un código de éxito/error. Adicionalmente puede devolver más datos en
  73         la respuesta en cuyo caso se especifica expresamente.
  74
  75         Los comandos se tiene una estructura general compuesta por 3 elementos:
  76         - Destino: A quién se le envía el comando.
  77         - Comando: El comando en sí (la acción a realizar).
  78         - Argumentos: Opciones y datos necesarios para ejecutar el comando.
  79         Esto se estructura como una ruta, por lo que todos los comandos se componen la
  80         menos de 2 <em>directorios</em>, con cero o más argumentos representados a su
  81         ves por archivos o más subdirectorios:
  82         /verbatim /[destino]/[comando]/[argumento 1]/[...]/[argumento N] /endverbatim
  83
  84         Los destinos disponibles son:
  85         - <tt>server</tt>: Comandos para el servidor en sí.
  86         - <tt>connection</tt>: Comandos para las conexiones.
  87         - <tt>transmission</tt>: Comandos para las transmisiones.
  88         - <tt>plant</tt>: Comandos para las plantas.
  89
  90         \subsection page_server_protocolo_general Comandos para el Servidor.
  91                 Los comandos para el servidor, como se vio previamente, comienzan con
  92                 <tt>/server/</tt> seguido de alguna de las siguientes opciones:
  93                 <table>
  94                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
  95                         <tr>
  96                                 <td><tt>info</tt></td>
  97                                 <td>Obtiene información sobre el servidor.</td>
  98                                 <td>Cantidad de plantas, conexiones, transmisiones, versión,
  99                                     uptime, etc.</td>
 100                         </tr>
 101                         <tr>
 102                                 <td><tt>stop</tt></td>
 103                                 <td>Detiene el servidor.</td>
 104                                 <td>Nada.</td>
 105                         </tr>
 106                 </table>
 107
 108         \subsection page_server_protocolo_control Comandos para una Conexión de Control.
 109                 Todos los comandos de transmisiones comienzan con <tt>/connection/</tt>
 110                 y continúan con alguna de las siguientes opciones:
 111                 <table>
 112                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 113                         <tr>
 114                                 <td><tt>list</tt></td>
 115                                 <td>Obtiene una lista de las conexiones de control activas.</td>
 116                                 <td>Lista de conexiones activas (host, puerto, uptime, etc).</td>
 117                         </tr>
 118                         <tr>
 119                                 <td><tt>stop/[host]/[port]</tt></td>
 120                                 <td>Finaliza la conexión de control del host [host] en el puerto
 121                                     [port].</td>
 122                                 <td>Nada.</td>
 123                         </tr>
 124                 </table>
 125                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 126
 127         \subsection page_server_protocolo_transmision Comandos para una Transmisión.
 128                 Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
 129                 y continúan con alguna de las siguientes opciones:
 130                 <table>
 131                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 132                         <tr>
 133                                 <td><tt>list</tt></td>
 134                                 <td>Obtiene una lista de las transmisiones activas.</td>
 135                                 <td>Lista de transmisiones activas (host, puerto, uptime,
 136                                     etc).</td>
 137                         </tr>
 138                         <tr>
 139                                 <td><tt>start/[pl]/[host]/[port]</tt></td>
 140                                 <td>Comienza la transmisión de la planta [pl] al [host]
 141                                     en el puerto [port].</td>
 142                                 <td>Nada.</td>
 143                         </tr>
 144                         <tr>
 145                                 <td><tt>stop/[host]/[port]</tt></td>
 146                                 <td>Finaliza la transmisión al [host] en el puerto
 147                                     [port].</td>
 148                                 <td>Nada.</td>
 149                         </tr>
 150                 </table>
 151                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 152
 153         \subsection page_server_protocolo_planta Comandos para una Planta.
 154                 Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con
 155                 alguna de las siguientes opciones:
 156                 <table>
 157                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 158                         <tr>
 159                                 <td><tt>list</tt></td>
 160                                 <td>Obtiene lista de plantas.</td>
 161                                 <td>Lista de plantas con info mínima de cada una (está
 162                                     corriendo o no, uptime, cantidad de elementos,etc).</td>
 163                         </tr>
 164                         <tr>
 165                                 <td><tt>get/[pl]</tt></td>
 166                                 <td>Obtiene la planta de nombre [pl].</td>
 167                                 <td>El mismo archivo que se crea en el Constructor.</td>
 168                         </tr>
 169                         <tr>
 170                                 <td><tt>set/[pl]/[el]/[pr]/[val]</tt></td>
 171                                 <td>Cambia la propiedad [pr] del elemento [el], asignándole
 172                                     el valor [val] a planta de nombre [pl].</td>
 173                                 <td>Nada.</td>
 174                         </tr>
 175                         <tr>
 176                                 <td><tt>set_frequency/[pl]/[hz]</tt></td>
 177                                 <td>Cambia la frecuencia de refresco de la simulación de la
 178                                     planta de nombre [pl] a [hz] veces por segundo. Si [hz]
 179                                     es cero ("0"), se usa la frecuencia de refresco por
 180                                     omisión del servidor.</td>
 181                                 <td>Nada.</td>
 182                         </tr>
 183                         <tr>
 184                                 <td><tt>start/[pl]</tt></td>
 185                                 <td>Reanuda (o comienza) la simulación de la planta de nombre
 186                                     [pl].</td>
 187                                 <td>Nada.</td>
 188                         </tr>
 189                         <tr>
 190                                 <td><tt>stop/[pl]</tt></td>
 191                                 <td>Pausa la simulación de la planta de nombre
 192                                     [pl].</td>
 193                                 <td>Nada.</td>
 194                         </tr>
 195                         <tr>
 196                                 <td><tt>remove/[pl]</tt></td>
 197                                 <td>Finaliza la simulación de la planta de nombre
 198                                     [pl] eliminandola del servidor.</td>
 199                                 <td>Nada.</td>
 200                         </tr>
 201                 </table>
 202                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 203
 204 \section page_server_respuesta Respuestas del Módulo de Control.
 205         Las respuestas del servidor, como se dijo anteriormente, son respuestas HTTP, cuyo
 206         cuerpo es un archivo XML. Este archivo se compone de un <em>tag</em> XML
 207         <tt>plaqui-response</tt> y tiene como atributos obligatorios <tt>code</tt> (indica
 208         el código de respuesta, para saber si se realizó bien el comando) y <tt>version</tt>
 209         (indica la versión del formato del archivo XML, para preveer la posibilidad de que
 210          cambie en futuras versiones). También tiene un atributo opcional <tt>description</tt>
 211         que permite agregar una descripción sobre la respuesta, útil para observar respuestas
 212         con un navegador u otro cliente no específico. El <em>tag</em>plaqui-response</em>
 213         puede tener un contenido, en caso de que la respuesta necesite enviar información al
 214         cliente (como al obtener una planta o una lista). El contenido es a su vez XML y en
 215         el caso de la obtención de una planta tiene el mismo formato que el utilizado por el
 216         Constructor.
 217
 218 \section page_server_uso Modo de uso.
 219         \subsection page_server_uso_inicio Inicio del servidor
 220                 Para iniciar el servidor es necesario disponer de un archivo XML de
 221                 planta (por ejemplo, generado por el Constructor).
 222
 223                 Invocación del servidor:
 224                 \verbatim ./plaqui-server [archivo] [puerto] \endverbatim
 225
 226                 Ambos argumentos son opcionales. El primero, <tt>[archivo]</tt>, es la
 227                 ubicación del archivo con la descripción de la planta a simular (por omisión
 228                 <tt>planta.xml</tt>). El segundo, <tt>[puerto]</tt>, es el puerto en el cual
 229                 se van a atender las peticiones al servidor (por omisión 7522).
 230
 231         \subsection page_server_uso_estado Estado del servidor.
 232                 Mientras el servidor se ejecuta, va imprimiendo en la salida estándar su
 233                 estado. Se imprime cada vez que llega una conexión entrante y cada vez que
 234                 se detecta un error.
 235
 236                 Otro tipo de información del estado del servidor puede ser obtenida desde
 237                 el cliente a través del comando <tt>/server/info</tt> (ver
 238                 \ref page_server_protocolo_general).
 239
 240                 \note Los errores se imprimen en la salida de error, no en la salida
 241                       estándar.
 242
 243         \subsection page_server_uso_fin Finalización del servidor.
 244                 Hay varias formas de finalizar el servidor:
 245                 - Enviando una señal de interrupción (<tt>SIGINT</tt>), por ejemplo,
 246                   presionando la combinación de teclas <tt>CTRL-C</tt>.
 247                 - Enviando una señal de salida (<tt>SIGQUIT</tt>) o de terminación
 248                   (<tt>SIGTERM</tt>), por ejemplo, a través del comando
 249                   <tt>kill(1)</tt>.
 250                 - Enviando un comando <tt>/server/stop</tt> desde un cliente (ver
 251                   \ref page_server_protocolo_general).
 252
 253                 Cualquiera de estos métodos es válido y finaliza el servidor de forma
 254                 correcta.
 255
 256 */
 257
 258 /** \namespace PlaQui::Server
 259
 260 Infrastructura cliente-servidor para PlaQui.
 261
 262 Bajo este espacio de nombres (namespace) se encuentran todas las clases para la
 263 comunicación cliente-servidor de PlaQui. Esto no incluye la interfaz gráfica del
 264 cliente.
 265
 266 */
 267