popufare/Documentation/passdb-to-server.txt

	The passdb module keeps track of the local copy of the bus pass 
database by polling the server from time to time to ask for updates
newer than the latest locally recorded sequence number.  Each message
is a single line of ASCII text with tab delimited fields (there is no
valid reason to allow a tab in any of the fields, any tabs inside the
fields should be translated to single spaces) and terminated by a
newline.

	When the client wants to inquire about any new records, it 
issues a query request in this format:

QUERY	1234567890

	Where QUERY is the command, then a tab character, then the
newest sequence number which the local client has in its database,
followed by a newline.  The QUERY record has the following fields:

0) Command 		= QUERY
1) Sequence Number 	= Newest locally stored sequence number.  If
			  this number is zero, it indicates a table 
			  flush to the server, triggering a flush 
			  marker to be sent before the first reply
			  record.

	The server will respond with a sequence of bus pass updates
with the following allowable formats:

UPDATE	1234567891	54321	2:771231232	35:111:2357	ORG-NRIDE	7
DELETE	1234567892	938773

	The UPDATE record has the following fields:

0) Command 		= UPDATE
1) Sequence Number 	= Sequence number of this update.
2) Rider ID		= Unique ID of this rider's record.
3) Magstripe Token	= The magnetic stripe token in the format of
			  track:track_data by which this rider is
		          recognized.
4) RFID Token		= The RFID token in the format of
			  n_bits:site:id by which this rider is
			  recognized.
5) Rule Name		= The name of the rule to apply to this rider.
6) Rule Parameter	= An (optionally blank) parameter to pass to the
			  rule that validates this rider.

	The DELETE record has the following fields:

0) Command		= DELETE
1) Sequence Number	= The sequence number of this deletion.
2) Rider ID		= Unique ID of this rider's record.


	If the client requests a query from Sequence Number 0, the
server will send a flush marker which will prompt the client to flush
its tables before processing any further records.  This is sent to
prevent lag from causing a previous request's records from polluting
a clean refresh.  It looks like this:

ZFLUSH	523498
<523498 octets of binary data>

0) Command 		= ZFLUSH
1) Data Size		= How many bytes of zlib compressed (with deflate)
			  binary data follow before the command stream picks
			  up again.

	A flush is also triggered by the server if a query is sent with
an extremely old sequence number, or a sequence number greater than the
newest sequence number on the master server.

	After a flush in completed, the server MUST send a ZFLUSHDONE
command so the client can become aware that it is no longer in ZFLUSH mode.
Doing so will trigger the client to actually apply the compressed data which
it received in the ZFLUSH blob.

This looks like this:

ZFLUSHDONE

0) Command		= ZFLUSHDONE


NOP

0) Command		= NOP

	If a QUERY message results in NO data sent back to the requesting
client, an NOP command will be sent to indicate that the connection is still
alive.  This is useful for debugging, but has little value for end-user
display.

-----------------------OBSOLETE----------------------------------------
-	If the client requests a query from Sequence Number 0, the
-server will send a flush marker which will prompt the client to flush
-its tables before processing any further records.  This is sent to
-prevent lag from causing a previous request's records from polluting
-a clean refresh.  It looks like this:
-
-FLUSH
-
-0) Command 		= FLUSH
-
-	A flush is also triggered by the server if a query is sent with
-an extremely old sequence number, or a sequence number greater than the
-newest sequence number on the master server.
-
-	After a flush in completed, the server should send a FLUSHDONE
-command so the client can become aware that it is no longer in FLUSH mode.
-This looks like thise:
-
-FLUSHDONE
-
-0) Command		= FLUSHDONE