]> git.llucax.com Git - z.facultad/75.42/plaqui.git/blob - docs/server.txt
Se termina de modificar el modelo de instalacion y compilacion del cliente
[z.facultad/75.42/plaqui.git] / docs / server.txt
1
2                          +----------------------------+
3                          | PROPUESTA DE SERVIDOR v0.4 |
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 Descripción de los comandos 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 será 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 en general:
71 --------------------
72 Los comandos se tiene una estructura general compuesta por 3 elementos:
73 - Destino: A quien se le envía el comando.
74 - Comando: El comando en sí (la acción a realizar).
75 - Argumentos: Opciones y datos necesarios para ejecutar el comando.
76 Esto se estructura como una ruta, por lo que todos los comandos se componen la
77 menos de 2 'directorios' anidados, con cero o más argumentos representados a su
78 ves por archivos o más subdirectorios:
79 /<destino>/<comando>/<argumento 1>/<argumento 2>/<...>/<argumento N>
80
81 Los destinos disponibles serán:
82 - server: Comandos para el servidor en sí.
83 - plant: Comandos para las plantas.
84 - transmission: Comandos para las transmisiones (el módulo de transmisión).
85
86 Comandos para el servidor:
87 --------------------------
88 Los comandos para el servidor, como se vio previamente, comienzan con /server/
89 seguido de alguna de las siguientes opciones.
90
91 Comando  | Descripción            | Respuesta                                   
92 ---------+------------------------+---------------------------------------------
93 status   | Obtiene estado general | Cantidad de plantas, conexiones,
94          | del servidor.          | transmisiones, versión, uptime, etc.
95 ---------+------------------------+---------------------------------------------
96 stop     | Detiene el servidor.   | Nada.
97
98 Comandos para una Planta:
99 -------------------------
100 Todos los comandos de plantas comienzan con /plant/ y continúan con alguna de
101 las siguientes opciones:
102
103 Comando        |Descripción                  |Respuesta
104 ---------------+-----------------------------+----------------------------------
105 list           |Obtiene lista de plantas.    |Lista de plantas con info mínima
106                |                             |de cada una (está corriendo o no,
107                |                             |uptime, cantidad de elementos,etc)
108 ---------------+-----------------------------+----------------------------------
109 get/<planta>   |Obtiene la planta de         |El mismo archivo que se crea en el
110                |nombre <planta>.             |Constructor.
111 ---------------+-----------------------------+----------------------------------
112 start/<planta> |Comienza la simulación de la |Nada.
113                |planta de nombre <planta>.   |
114 ---------------+-----------------------------+----------------------------------
115 stop/<planta>  |Finaliza la simulación de la |Nada.
116                |planta de nombre <planta>.   |
117 ---------------+-----------------------------+----------------------------------
118 set/<planta>   |Cambia la propiedad <prop>   |Nada (a ver si no retorna el valor
119  /<elem>       |del elemento <elem>,         |realmente aceptado).
120  /<prop>       |asignándole el valor <val> a |
121  /<val>        |planta de nombre <planta>.   |
122
123 NOTA: Los nombres entre "<" y ">" denotan un argumento.
124
125 Comandos para una Transmisión:
126 ------------------------------
127 Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
128 alguna de las siguientes opciones:
129
130 Comando            |Descripción                              |Respuesta
131 -------------------+-----------------------------------------+------------------
132 list               |Obtiene una lista de las transmisiones   |Lista de transmi-
133                    |activas.                                 |siones activas 
134                    |                                         |(host, puerto, 
135                    |                                         |uptime, etc).
136 -------------------+-----------------------------------------+------------------
137 start/<plant>      |Comienza la transmisión de la planta     |Nada.
138  /<host>/<port>    |<plant> al <host> en elpuerto al <host>  |
139                    |en el puerto <port>.                     |
140 -------------------+-----------------------------------------+------------------
141 stop/<host>/<port> |Finaliza la transmisión al <host> en el  |Nada.
142                    |puerto <port>. Si se omite el <port>, se |
143                    |finalizan todas las transmisiones al     |
144                    |<host>. Si se omite el <host>, se        |
145                    |finalizan todas las transmisiones.       |
146
147 Comandos para una Conexión de Control:
148 --------------------------------------
149 Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
150 alguna de las siguientes opciones:
151
152 Comando            |Descripción                              |Respuesta
153 -------------------+-----------------------------------------+------------------
154 list               |Obtiene una lista de las conexiones de   |Lista de conexio-
155                    |control activas.                         |nes activas (host,
156                    |                                         |puerto, uptime,
157                    |                                         |etc).
158 -------------------+-----------------------------------------+------------------
159 stop/<host>/<port> |Finaliza la conexión de control del host |Nada.
160                    |<host> en el puerto <port>. Si se omite  |
161                    |el <port> se finalizan todas las         |
162                    |conexiones al <host>. Si se omite también|
163                    |el <host>, se finalizan todas las        |
164                    |conexiones de control.                   |
165
166 NOTA: Los nombres entre "<" y ">" denotan un argumento.
167
168
169 Descripción de los comandos para el módulo de control:
170 ======================================================
171
172 Todas las respuestas consisten de un archivo XML con esta forma (falta hacer la
173 DTD):
174 <plaqui version="0.1">
175         <response code="[código]" />
176 </plaqui>
177 El código es obligatorio e informará si el comando se realizó con éxito y en
178 caso de no hacerlo, indicará la razón (los códigos faltan definirlos, pero usar
179 un esquema similar a los códigos de HTTP sería un buen comienzo).
180 La respuesta también puede tener otros contenidos (listado de plantas,
181 conexiónes, transmisiones, descripción de una planta completa, etc). Dichos
182 contenidos irán contenidos en el tag response:
183 <plaqui version="0.1">
184     <response code= "[código]">
185         <list type="plants">
186             <item id="[id1]">
187                 <prop name="[nombre1]" value="[valor1]" />
188                 <prop name="[nombre2]" value="[valor2]" />
189                 <!-- ... más ... -->
190             </item>
191             <item id="[id2]">
192                 <prop name="[nombre1]" value="[valor3]" />
193                 <prop name="[nombre2]" value="[valor4]" />
194                 <!-- ... más ... -->
195             </item>
196         </list>
197     </response>
198 </plaqui>
199
200 TODO: Ver si la lista va dentro o fuera del tag <response>, ver si el tag
201       <plaqui> está bien, es útil y correcto.
202
203
204 Características adicionales (a desarrollar si el tiempo lo permite):
205 ====================================================================
206
207 Hojas de estilo XSLT:
208 ---------------------
209 Es factible crear hojas de transformación de XML a HTML para enviar con las
210 respuestas XML del módulo de control, de forma tal que pueda controlarse la
211 planta desde un navegador web que soporte esto (como Mozilla).
212 Las hojas de estilos estarían en la ruta /web, al igual que imágenes y otros
213 archivos complementarios.
214
215 Módulo de Transmisión sobre TCP:
216 --------------------------------
217 Opcionalmente se puede hacer un Módulo de transmisión sobre TCP, que sólo envíe
218 el estado actual de la planta en ese instante y se desconecte, o directamente
219 implementarlo como un comando del módulo de control para poder verlo en un
220 navegador web. Aunque esto ya sería más un cliente que un servidor.
221
222 'keep-alive' para el Módulo de Transmisión:
223 -------------------------------------------
224 En el futuro se puede agregar una respuesta de tipo 'keep-alive' para que el
225 transmisor UDP deje de transmitir a un host si no recibe una señal del receptor
226 cada una cantidad de tiempo determinada. De esta manera se evita seguir
227 transmitiendo si un cliente se cierra sin enviar el comando de fin de
228 transmisión por el Módulo de Control.
229
230 Envío por 'broadcast' del módulo de transmisión:
231 ------------------------------------------------
232 Es posible hacer que el comando /transmissions/start sin argumentos comience una
233 transmisión por 'broadcast' de la planta para todo aquel que quiera monitorearla
234 desde la red en la que se haga el 'broadcast'.
235
236 Atajos de comandos:
237 -------------------
238 Se trata de 'alias' de comandos. Por ejemplo que '/' de un estado del server
239 (/sever/status), que /plant de una lista de plantas, etc.
240
241 Valores por defecto:
242 --------------------
243 Para los comandos que requieren argumentos se podría asumir valores por defecto
244 en caso de faltar alguno.
245
246
247 vim: set et ts=4 sw=4 tw=80: