Re: [QStat-devx] draft for new query protocol and API

[Steve J. <ste...@ya...>]

Thanks, Ludwig.  I've made some comments on the package format.

But first, I'm not convinced the world needs another game query
protocol.  If you implement something for BZFlag that's compatible
with an existing game (HL or Quake), then other game browsers can
support it straight away.  That's good for BZFlag, right?

See my comments below on the query protocol.

I could comment on the API, but without knowing the architecture of
the application (BZFlag) I can't say if the API meets the needs of
the app.  From scanning the API, I imagine that the API might be
perfect, or it might be intrusive.  Depends on the BZFlag data
structures and main control flow.

If you go ahead with the API, let me know and I'll give you some feedback
on the API.  Just for giggles if nothing else.

Steve


> Query:
> ~~~~~~
> 
> QUERY ::= HEADER QUERYDATA
> 
> HEADER ::= 'q' 'c' PROTOVERS PKGID
> 
> PROTOVERS ::= uint8
> 
> PKGID ::= uint8
> 
> QUERYDATA ::= string
> 
> Query response:
> ~~~~~~~~~~~~~~~
> 
> QUERYRESPONSE ::= HEADER MANDDATA '\n' (RULE)* '\n' (TEAM)* '\n' (PLAYER)*
'\n'

I'm concerned about using \n since it might appear in a string (rule value).
I suggest using \0 since that's not a legal character.

> 
> HEADER ::= 'q' 's' PROTOVERS PKGID FRAGMENTNO (DATALEN)?
> 
> PROTOVERS ::= uint8
> 
> PKGID ::= uint8
> 
> FRAGMENTNO ::= uint8
> 
> DATALEN ::= uint32
> 
> MANDDATA ::= CURPLAYERS MAXPLAYERS PRODUCT SERVERNAME MAP
> 
> CURPLAYERS ::= uint32
> 
> MAXPLAYERS ::= uint32
> 
> PRODUCT ::= string
> 
> SERVERNAME ::= string
> 
> MAP ::= string
> 
> RULE ::= KEY VALUE
> 
> TEAM ::= KEY VALUE
> 
> PLAYER ::= KEY VALUE
> 
> KEY ::= string
> 
> VALUE ::= string
> 
> 
> 
> integers are in network byte order
> strings are null terminated C-strings in UTF-8 or iso8859-1 encoding

How do you distinguish between encodings?

> 
> PKGID has to be copied from the query packet to the query response packet by
> the server, it is used by the client to distinguish retry packets
> 
> DATALEN is only present if FRAGMENTNO == 0

Optional bits of data are annoying.  It's only a few extra bytes.

On the topic of DATALEN, I'd rather know the total number of packets
to expect.  Once I have all the packets, then I'll know how much data
there is; I don't have to be told.  The trouble is knowing if I got all
the packets.  If each packets tells me the total # packets, then it's
easier.

Change the header to:

HEADER ::= 'q' 's' PROTOVERS PKGID TOTALFRAGMENTS FRAGMENTNO

The API should build the whole packet, then divide by 1394 (1400 minus
the 6 byte header).  Then it will know how many fragments there will
be and can put this in each frag header.

I chose 1400 to avoid exceeding the MTU (usually 1500 on ethernet, but
occasionally smaller).

> the first key of each player or team must be "name"
> 
> PROTOVERS is 0x01 in this revision of the protocol
> 
> QUERYDATA is "sendreport"

Maybe allow fetching of different data sets:

"send:"          send just the MANDDATA
"send:all"       send everything
"send:rules"     send rules
"send:players"   send players
"send:teams"     send teams
"send:teams,players"    send just teams and players

Of course, MANDDATA is always included.

For now, you can support just "send:" and "send:all", but you've left
yourself room for expansion to support other queries.

The "send:" query is useful for collecting "ping" stats.  Pings are most
accurate when the data is small.

> 
> 
> 
> TODO:
> 
> - use fragment offset instead of fragment number?
> - are all integers of appropriate size?

32bits is overkill for most of the values.  DATALEN, CURPLAYER, and
MAXPLAYER can all be uint16 and still be more than enough.