| 1 | = Data server protocol = |
| 2 | |
| 3 | 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, '''file_upload_handler'''. |
| 4 | === Download === |
| 5 | File download is done by a GET request to a URL from the FILE_INFO element. The file offset, if any, is given in '''Range:''' attribute of the HTTP header. |
| 6 | |
| 7 | |
| 8 | === Upload === |
| 9 | 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. |
| 10 | |
| 11 | '''1) Get file size''' |
| 12 | |
| 13 | The request message has the form: |
| 14 | |
| 15 | |
| 16 | {{{ |
| 17 | <data_server_request> |
| 18 | <core_client_major_version>1</core_client_major_version> |
| 19 | <core_client_minor_version>1</core_client_minor_version> |
| 20 | <core_client_release>1</core_client_release> |
| 21 | <get_file_size>filename</get_file_size> |
| 22 | </data_server_request> |
| 23 | }}} |
| 24 | The reply message has the form: |
| 25 | |
| 26 | |
| 27 | {{{ |
| 28 | <data_server_reply> |
| 29 | <status>x</status> |
| 30 | [ <message>text<message> |
| 31 | | <file_size>nbytes</file_size> ] |
| 32 | </data_server_reply> |
| 33 | }}} |
| 34 | Status is |
| 35 | |
| 36 | '''''':: |
| 37 | Success. Nbytes is 0 if the file doesn't exist. |
| 38 | '''1''':: |
| 39 | Transient error. The client should try another data server, or try this one later. |
| 40 | '''-1''':: |
| 41 | Permanent error. The client should give up on the result. |
| 42 | In the error cases, the <file_size> element is omitted and the <message> element gives an explanation. |
| 43 | |
| 44 | '''2) Upload file''' |
| 45 | |
| 46 | Request message format: |
| 47 | |
| 48 | |
| 49 | {{{ |
| 50 | <data_server_request> |
| 51 | <core_client_major_version>1</core_client_major_version> |
| 52 | <core_client_minor_version>1</core_client_minor_version> |
| 53 | <core_client_release>1</core_client_release> |
| 54 | <file_upload> |
| 55 | <file_info> |
| 56 | ... |
| 57 | <xml_signature> |
| 58 | ... |
| 59 | </xml_signature> |
| 60 | </file_info> |
| 61 | <nbytes>x</nbytes> |
| 62 | <md5_cksum>x</md5_cksum> |
| 63 | <offset>x</offset> |
| 64 | <data> |
| 65 | ... (nbytes bytes of data; may include non-ASCII data) |
| 66 | (no closing tags) |
| 67 | }}} |
| 68 | The <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. <nbytes> is the size of the file. <md5_cksum> is MD5 of the entire file. <offset> is the offset within the file. |
| 69 | |
| 70 | Reply message format: |
| 71 | |
| 72 | |
| 73 | {{{ |
| 74 | <data_server_reply> |
| 75 | <status>x</status> |
| 76 | <message>text</message> |
| 77 | </data_server_reply> |
| 78 | }}} |
| 79 | Status is |
| 80 | |
| 81 | '''''':: |
| 82 | success |
| 83 | '''1''':: |
| 84 | transient error; The client should try another data server, or try this one later. |
| 85 | '''-1''':: |
| 86 | Permanent error. The client should give up on the result. |
| 87 | In the error cases, the <message> element gives an explanation. |
| 88 | |
| 89 | TODO: if there's an error in the header (bad signature, or file is too large) the client should learn this without actually uploading the file. |
| 90 | |