Protocol

#summary The Client/Server Protocol

##Introduction

The client and the server communicate with HTTP. The server replies with XML structured data, images, and animations. After the redirection, if the user has entered credentials, then they included in the HTTP requests using the Basic Authentication.

##On Install

When the client is installed it generates a 8-byte random unique ID, written with hex digits, eg FDB1C06A94A0FC87. This UID is passed to all subsequent queries.

##On Startup

When the client starts up it makes a redirection query. The resulting hostname is used for all subsequent non-redirection queries. The redirection is cached.

http://community.sheepserver.net/query.php?q=redir&u=$ACCOUNT&p=$HASH&v=$VERSION&i=$UID

Where $ACCOUNT is the drupal login, $HASH is the md5 hash with salt, VERSION is the client version number, and UID was generated on install. For example:

http://community.sheepserver.net/query.php?q=redir&u=spot&p=E42D7CD78F00B204E9800998ECF8427E&v=LNX_2.7b12&i=8D94A5E812F4D8E9

reply:

<query><redir host="http://v2d7c.sheepserver.net/"/></query>

##Password Hash and Salt

The password is stored and transmitted with "per-row salt". We use md5 of the concatenation of the password, the username, and the salt string which is the constant "sh33p". In pseudocode:

hash = md5(password + username + "sh33p")

##List Sheep To get a directory of current live sheep the client fetches:

$HOST/cgi/list?u=$UID&v=$VERSION

reply is gzipped XML:

<list gen="244" size="800 592" retry="600">
<sheep id="27045" type="0" state="done" time="1283912914" size="1688352" rating="102" first="27045" last="27045" url="http://v2d7c.sheepserver.net.nyud.net/gen/244/27045/sheep.avi"/>
<sheep id="33860" type="0" state="done" time="1291465044" size="2513326" rating="91" first="33259" last="27045" url="http://v2d7c.sheepserver.net.nyud.net/gen/244/33860/sheep.avi"/>
...
</list>

The first line has the generation and resolution for this flock.

Each sheep element stands for a video that can be downloaded from the url field. It should be stored as a file named like 00244=27045=27045=27045.avi or 00244=33860=33259=27045.avi for the two examples above, named according to the gen/id/first/last fields. More explicitly, on the list element:

• gen the generation currently live on the server. Occasionally this increases. Edges only connecte within a generation (it must match). If the first digit is 1 (eg 10244) then they are gold sheep.
• size width and height of the videos in pixels.
• retry not used yet.

And for sheep:

• id each sheep has a unique ID (within its generation). They are numbered consecutively.
• type and state ignore these.
• time that this sheep was completed in seconds since the unix epoch.
• size in bytes of the file. After downloading, make sure that you actually got this many bytes.
• rating the popularity of this sheep among the audience.
• first the ID of the sheep at the beginning of this clip.
• last the ID of the sheep at the end of this clip.
• url a string, where the sheep can be downloaded. You cannot rely on any information in this string as it might have been generated by a CDN.

##File Names

The files names have 5 components, 4 are a 5 digit number, plus the extension. The first (reading left to right) is the generation containing the sheep. The 2nd is the ID of that sheep. the 3rd and 4th are the keyframes at the beginning and end (first and last) of the sheep. The keyframes are IDs of other sheep.

The extension depends on the device. For the regular screensaver client it's "avi" and that is what is used in the examples here. Mobile devices use "mp4" or "shp".

A sheep that is a loop has the same number for components 2, 3, and 4. A sheep that is an edge has different numbers for the first and last keyframe. Sheep will play seamlessly if the keyframes match. So if the last field of one sheep is the same as the first field of the next, then they will fit together. For example, the following files make a continuous sequence:

00244=01423=01324=01251.avi
00244=01368=01251=01260.avi
00244=01260=01260=01260.avi
00244=01314=01260=01229.avi

##Voting

To vote for a sheep issue this:

$HOST/cgi/vote?u=$UID&v=$VERSION&id=$ID&vote=1

and against replace vote=1 with vote=-1.

##Get A Rendering Job

GET $HOST/cgi/get?n=$NICK&w=$URL&v=$VERSION&u=$UID&r=1&c=1

$NICK is the account name (nick name) of the user. $URL is the credit URL provided by the user. r and c are both hardcoded to 1 in the client but they are ignored by the server.

The response is gzipped XML

<get gen="12" id="1" type="0" prog="flame" job="3" frame="3">
<args bits="33" jpeg="100" />

followed by the output from one of these

• if loop: env rotate=$spex_file enclosed=0 frame=$frame_id nframes=$nframes /usr/bin/flam3-genome
• if edge: env inter=$spex_file enclosed=0 frame=$frame_id nframes=$nframes /usr/bin/flam3-genome

And finished off by

</get>

• gen = the generation currently live on the server.
• id = unique sheep id
• type = ignored
• prog = ignored
• job = which frame of the sheep to be rendered
• frame = time to render. this is like job but sometimes there are more than one job with the same time/frame.

the attributes of the "args" element are passed to flam3-render as environment variables.

##Submit a Rendered Job

PUT $HOST/cgi/put?j=$JOB&id=$SHEEP_ID&s=$SIZE&g=$GENERATION&v=$VERSION&u=$UID

The PUT data is the complete rendered frame. $SIZE = the number of bytes to be uploaded