documentation/specification/protocols.txt

i-scream Protocols
==================

Contents
--------
 - Conventions

 - Host Connection Protocol
 - Host Heartbeat Protocol
 - Host Data Protocol

 - Client Control Protocol
 - Client Data Protocol


Conventions
-----------
All protocols in this document assume a valid connection of
the appropriate type has been made, and that data streams
are already available.  All strings should, and will be,
terminated with a \n (newline character) to indicate the end
of the message.  All messages are sent as ASCII Strings.

Fixed protocol messages will appear in [] brackets, if there
is a variety of options they will be separated with the |
character.  For example:

    [OK|ERROR]
   
Indicates that the message "OK" OR the message "ERROR" will
be sent depending on the result of the last action.

Data messages will appear in {} brackets, where the name in
the brackets indicates the type (as in kind, not data type)
of data that will be returned.  For example:

    {lastmodified}

Indicates that data for use as 'last modified' will be 
returned.   

If [ERROR] is sent back at any time, this indicates that all 
communication is over. EXCEPT where otherwise specified!


Host Connection Protocol
------------------------
The initial connection of a host to the i-scream server is
through the FilterManager.  A Host gets its configuration
and then gets assigned a Filter to connect to and start
sending data.

The port number of the FilterManager is fully configurable,
however the default at this time is 4567.

Host         (direction) Server         Comment
------------------------------------------------------------
[STARTCONFIG]---------->                Requests to start
                                        receiving config
                                        information
            
             <---------- [OK|ERROR]     If the server ok's
                                        the request or not

[LASTMODIFIED]---------->               Asks when the config
                                        was last modified
                                        (used when checking
                                        if the config has
                                        changed)
            
             <---------- [{lastmodified}Returns a long int
                         |ERROR]        time since epoch
                                        eg, 123456789

[FILELIST]   ---------->                Asks the server for
                                        the list of files
                                        that were used to
                                        build the config
                                        (used when checking
                                        if the config has
                                        changed)
       
             <---------- [{filelist}    Returns a semi-colon
                         |ERROR]        separated list of
                                        filenames
                                        eg,
                                        a.conf;b.conf;c.conf

             ********** LOOP START **********
             This loop reads configuration
             properties from the config

[{property}] ---------->                Sends the name of a
                                        property to be
                                        retrieved from the
                                        config file
                                        eg, UDPUpdateTime
            
             <---------- [{value}|ERROR]Returns the value of
                                        the requested config
                                        property
                                        eg, 120
                                        If it is unable to
                                        find the requested
                                        property it returns
                                        ERROR to indicate
                                        that fact, but 
                                        communication still 
                                        proceeds
                                       
             ********** LOOP UNTIL **********
             The loop continues until the host
             sends the following message
            
[ENDCONFIG]  ---------->                Indicates that the
                                        host requires no
                                        more config
            
             ********** LOOP  END **********
             Communication continues
            
             <---------- [OK]           Indicates that the
                                        server is ready to
                                        proceed
                                       
[FILTER]     ---------->                Asks the server to
                                        send it the host
                                        information of a
                                        filter that it
                                        should connect to
                                       
             <---------- {filter}       Returns a semi-colon
                                        separated list of
                                        FQDN hostname, UDP
                                        port number and TCP
                                        port number that a
                                        configured Filter is
                                        running on and
                                        assigned to the
                                        calling host
                                        eg,
                                        raptor.ukc.ac.uk;
                                        1234;5678

[END]        ---------->                Indicates to the
                                        server that the host
                                        has finished an will
                                        disconnect
            
             <---------- [OK|ERROR]     Indicates that the
                                        server is either ok
                                        or that it thought
                                        there was an error
       
Host Heartbeat Protocol
-----------------------
When a host is configured after it has connected it should
obtain a property TCPUpdateTime.  This indicates how often
a host should send a "Heart Beat", which is a pro-active
connection to the server by the host to indicate that it is
still alive.  This "Heart Beat" also allows a host to see
its configuration has changed and act accordingly.  In a
well written host this should just be a case of dropping out
of a loop and heading back to the start (connecting to the
filter manager).

Host            (direction) Server      Comment
------------------------------------------------------------
[HEARTBEAT]     ---------->             Starts the
                                        heartbeat protocol
                                        off
                                       
                <---------- [OK|ERROR]  Indicates that the
                                        server is ok or not

[CONFIG]        ---------->             Indicates that the
                                        host wants to check
                                        its config

                <---------- [OK|ERROR]  Indicates that the
                                        server is ok or not

[{filelist}]    ---------->             Send a semi-colon
                                        separated list of
                                        filenames
                                        eg,
                                        a.conf;b.conf;c.conf
                                        This should be
                                        identical to the one
                                        received in the
                                        connection protocol

                <---------- [OK]        Indicates that the
                                        server is ok

[{lastmodified}]---------->             Returns a long int
                                        time since epoch
                                        eg, 123456789
                                        This should be
                                        identical to the one
                                        received in the
                                        connection protocol

                <---------- [OK|ERROR]  The server then
                                        checks all the files
                                        in the file list to
                                        see if they have
                                        been modified more
                                        recently than the
                                        lastmodified value.
                                        If they HAVE that
                                        indicates that the
                                        configuration has
                                        changed and the host
                                        should re-configure,
                                        thus it sends ERROR.
                                        If the files remain
                                        unchanged the server
                                        will return OK to
                                        indicate the host
                                        should continue as
                                        before

[ENDHEARTBEAT]  ---------->             Indicates to the
                                        server that the host
                                        has finished an will
                                        disconnect
               
                <---------- [OK|ERROR]  Indicates that the
                                        server is either ok
                                        or that it thought
                                        there was an error

Host Data Protocol
------------------
The UDP data packets that are sent by the host contain
simply XML data.  For information on the format of this
data see the XML via UDP specification document at:

http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specificatio
n/xml_via_udp.txt

Client Control Protocol
-----------------------

<TODO>

Client Data Protocol
--------------------

<TODO>

About
-----
This document was written by AJ Moore [ajm4@ukc.ac.uk] for
use by the team working on a 3rd year Computer Science
project called "i-scream". More details can be found on the
project website;

http://www.i-scream.org.uk
Revision:	1.2
Committed:	Sun Jan 28 18:50:44 2001 UTC (23 years, 10 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
Changes since 1.1:	+47 -42 lines
Log Message:	Proof read. Just corrected a few spelling mistakes.
#	User	Rev	Content
1	ajm	1.1	i-scream Protocols
2			==================
3
4			Contents
5			--------
6			- Conventions
7
8			- Host Connection Protocol
9			- Host Heartbeat Protocol
10			- Host Data Protocol
11
12			- Client Control Protocol
13			- Client Data Protocol
14
15	tdb	1.2
16	ajm	1.1	Conventions
17			-----------
18			All protocols in this document assume a valid connection of
19			the appropriate type has been made, and that data streams
20	tdb	1.2	are already available. All strings should, and will be,
21	ajm	1.1	terminated with a \n (newline character) to indicate the end
22			of the message. All messages are sent as ASCII Strings.
23
24			Fixed protocol messages will appear in [] brackets, if there
25	tdb	1.2	is a variety of options they will be separated with the \|
26	ajm	1.1	character. For example:
27
28			[OK\|ERROR]
29	tdb	1.2
30	ajm	1.1	Indicates that the message "OK" OR the message "ERROR" will
31			be sent depending on the result of the last action.
32
33			Data messages will appear in {} brackets, where the name in
34			the brackets indicates the type (as in kind, not data type)
35			of data that will be returned. For example:
36
37			{lastmodified}
38
39	tdb	1.2	Indicates that data for use as 'last modified' will be
40			returned.
41
42			If [ERROR] is sent back at any time, this indicates that all
43			communication is over. EXCEPT where otherwise specified!
44	ajm	1.1
45
46			Host Connection Protocol
47			------------------------
48			The initial connection of a host to the i-scream server is
49			through the FilterManager. A Host gets its configuration
50	tdb	1.2	and then gets assigned a Filter to connect to and start
51	ajm	1.1	sending data.
52
53	tdb	1.2	The port number of the FilterManager is fully configurable,
54	ajm	1.1	however the default at this time is 4567.
55
56			Host (direction) Server Comment
57			------------------------------------------------------------
58			[STARTCONFIG]----------> Requests to start
59			receiving config
60			information
61	tdb	1.2
62	ajm	1.1	<---------- [OK\|ERROR] If the server ok's
63			the request or not
64
65			[LASTMODIFIED]----------> Asks when the config
66			was last modified
67			(used when checking
68	tdb	1.2	if the config has
69	ajm	1.1	changed)
70	tdb	1.2
71	ajm	1.1	<---------- [{lastmodified}Returns a long int
72	tdb	1.2	\|ERROR] time since epoch
73	ajm	1.1	eg, 123456789
74
75			[FILELIST] ----------> Asks the server for
76			the list of files
77			that were used to
78			build the config
79			(used when checking
80			if the config has
81			changed)
82	tdb	1.2
83	ajm	1.1	<---------- [{filelist} Returns a semi-colon
84	tdb	1.2	\|ERROR] separated list of
85	ajm	1.1	filenames
86			eg,
87			a.conf;b.conf;c.conf
88
89			******** LOOP START ********
90			This loop reads configuration
91			properties from the config
92
93			[{property}] ----------> Sends the name of a
94			property to be
95			retrieved from the
96			config file
97			eg, UDPUpdateTime
98	tdb	1.2
99	ajm	1.1	<---------- [{value}\|ERROR]Returns the value of
100			the requested config
101			property
102			eg, 120
103			If it is unable to
104	tdb	1.2	find the requested
105	ajm	1.1	property it returns
106			ERROR to indicate
107	tdb	1.2	that fact, but
108			communication still
109			proceeds
110
111	ajm	1.1	******** LOOP UNTIL ********
112			The loop continues until the host
113			sends the following message
114	tdb	1.2
115			[ENDCONFIG] ----------> Indicates that the
116	ajm	1.1	host requires no
117			more config
118	tdb	1.2
119	ajm	1.1	******** LOOP END ********
120			Communication continues
121	tdb	1.2
122	ajm	1.1	<---------- [OK] Indicates that the
123			server is ready to
124			proceed
125	tdb	1.2
126	ajm	1.1	[FILTER] ----------> Asks the server to
127			send it the host
128	tdb	1.2	information of a
129	ajm	1.1	filter that it
130			should connect to
131	tdb	1.2
132	ajm	1.1	<---------- {filter} Returns a semi-colon
133	tdb	1.2	separated list of
134	ajm	1.1	FQDN hostname, UDP
135			port number and TCP
136	tdb	1.2	port number that a
137	ajm	1.1	configured Filter is
138			running on and
139	tdb	1.2	assigned to the
140	ajm	1.1	calling host
141			eg,
142			raptor.ukc.ac.uk;
143			1234;5678
144
145			[END] ----------> Indicates to the
146			server that the host
147			has finished an will
148			disconnect
149	tdb	1.2
150	ajm	1.1	<---------- [OK\|ERROR] Indicates that the
151			server is either ok
152			or that it thought
153			there was an error
154	tdb	1.2
155	ajm	1.1	Host Heartbeat Protocol
156			-----------------------
157			When a host is configured after it has connected it should
158			obtain a property TCPUpdateTime. This indicates how often
159	tdb	1.2	a host should send a "Heart Beat", which is a pro-active
160	ajm	1.1	connection to the server by the host to indicate that it is
161			still alive. This "Heart Beat" also allows a host to see
162	tdb	1.2	its configuration has changed and act accordingly. In a
163	ajm	1.1	well written host this should just be a case of dropping out
164			of a loop and heading back to the start (connecting to the
165			filter manager).
166
167			Host (direction) Server Comment
168			------------------------------------------------------------
169			[HEARTBEAT] ----------> Starts the
170			heartbeat protocol
171			off
172	tdb	1.2
173	ajm	1.1	<---------- [OK\|ERROR] Indicates that the
174			server is ok or not
175
176			[CONFIG] ----------> Indicates that the
177			host wants to check
178			its config
179
180			<---------- [OK\|ERROR] Indicates that the
181			server is ok or not
182
183			[{filelist}] ----------> Send a semi-colon
184	tdb	1.2	separated list of
185	ajm	1.1	filenames
186			eg,
187			a.conf;b.conf;c.conf
188			This should be
189			identical to the one
190	tdb	1.2	received in the
191	ajm	1.1	connection protocol
192
193			<---------- [OK] Indicates that the
194			server is ok
195
196			[{lastmodified}]----------> Returns a long int
197	tdb	1.2	time since epoch
198	ajm	1.1	eg, 123456789
199			This should be
200			identical to the one
201	tdb	1.2	received in the
202	ajm	1.1	connection protocol
203
204			<---------- [OK\|ERROR] The server then
205			checks all the files
206			in the file list to
207			see if they have
208			been modified more
209			recently than the
210	tdb	1.2	lastmodified value.
211			If they HAVE that
212	ajm	1.1	indicates that the
213			configuration has
214			changed and the host
215			should re-configure,
216			thus it sends ERROR.
217			If the files remain
218			unchanged the server
219			will return OK to
220			indicate the host
221			should continue as
222			before
223
224			[ENDHEARTBEAT] ----------> Indicates to the
225			server that the host
226			has finished an will
227			disconnect
228	tdb	1.2
229	ajm	1.1	<---------- [OK\|ERROR] Indicates that the
230			server is either ok
231			or that it thought
232			there was an error
233
234			Host Data Protocol
235			------------------
236			The UDP data packets that are sent by the host contain
237			simply XML data. For information on the format of this
238			data see the XML via UDP specification document at:
239
240	tdb	1.2	http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specificatio
241			n/xml_via_udp.txt
242	ajm	1.1
243			Client Control Protocol
244			-----------------------
245
246			<TODO>
247
248			Client Data Protocol
249			--------------------
250
251			<TODO>
252
253			About
254			-----
255			This document was written by AJ Moore [ajm4@ukc.ac.uk] for
256			use by the team working on a 3rd year Computer Science
257			project called "i-scream". More details can be found on the
258			project website;
259
260			http://www.i-scream.org.uk