boinc/doc/upload.html

<title>Data server protocol</title>

<h2>Data server protocol</h2>

Core client communicate with data servers using HTTP.
A data server is typically implemented using
a web server together with a BOINC-supplied CGI program,
<b>file_upload_handler</b>.

<h3>Download</h3>
<p>
File download is done by a GET request
to a URL from the FILE_INFO element.
The file offset, if any, is given in <b>Range:</b> attribute
of the HTTP header.

<h3>Upload</h3>
<p>
File upload is done using POST operations to a CGI program.
A security mechanism prevents unauthorized
upload of large amounts of data to the server.
Two RPC operations are used.
<p>
<b>1) Get file size</b>
<p>
The request message has the form:
<pre>
&lt;data_server_request>
    &lt;core_client_major_version>1&lt;/core_client_major_version>
    &lt;core_client_minor_version>1&lt;/core_client_minor_version>
    &lt;get_file_size>filename&lt;/get_file_size>
&lt;/data_server_request>
</pre>

<p>
The reply message has the form:
<pre>
&lt;data_server_reply>
    &lt;status>x&lt;/status>
    [ &lt;message>text&lt;/message>
    | &lt;file_size>nbytes&lt;/file_size> ]
&lt;/data_server_reply>
</pre>
The &lt;file_size> element is omitted in error cases;
nbytes is -1 if the file doesn't exist.
There are no security mechanisms.
TODO: should distinguish between permanent and transient errors
(i.e. whether should retry or give up).

<p>
<b>2) Upload file</b>
<p>
Request message format:
<pre>
&lt;data_server_request>
&lt;core_client_major_version>1&lt;/core_client_major_version>
&lt;core_client_minor_version>1&lt;/core_client_minor_version>
&lt;file_upload>
&lt;file_info>
   ...
&lt;xml_signature>
   ...
&lt;/xml_signature>
&lt;/file_info>
&lt;nbytes>x&lt;/nbytes>
&lt;offset>x&lt;/offset>
&lt;data>
... (nbytes bytes of data; may be binary)
&lt;/data>
</pre>
<p>
The &lt;file_info> element is the exact text sent from the
scheduling server to the client.
It includes a signature based on the project's file upload
authentication key pair.
&lt;nbytes> is the amount of data being uploaded.
&lt;offset> is the offset within the file.
<p>
Reply message format:
<pre>
&lt;data_server_reply>
    &lt;status>x&lt;/status>
    &lt;message>x&lt;/message>
&lt;/data_server_reply>
</pre>
The status is zero if the operation succeeded.
TODO: should distinguish between permanent and transient errors
(i.e. whether should retry or give up).