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
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 seperated 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 indicating for use as last modified will
be returned.    

If ever [ERROR] is sent back at any time, this indicates
that all communication is over. EXCEPT where 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 filter manager 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 epoc
                                        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]        seperated 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
                                        
             ********** 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
                                        seperated 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
                                        seperated list of
                                        filenames
                                        eg,
                                        a.conf;b.conf;c.conf
                                        This should be
                                        identical to the one
                                        recieved in the 
                                        connection protocol

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

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