1# Resumable uploads over HTTP. Protocol specification 2 3Valery Kholodkov [\<valery@grid.net.ru\>](mailto:valery@grid.net.ru), 42010 5 6## 1. Introduction 7 8This document describes application protocol that is used by [nginx 9upload module](upload.ru.html) to implement resumable file uploads. The 10first version of the module that supports this protocol is 2.2.0. 11 12<span id="2"></span> 13 14## 2. Purpose 15 16The HTTP implements file uploads according to 17[RFC 1867](http://www.ietf.org/rfc/rfc1867.txt). When the request length 18is excessively large, the probability that connection will be 19interrupted is high. HTTP does not foresee a resumption mechanism. The 20goal of the protocol being described is to implement a mechanism of 21resumption of interrupted file transfer or suspension of upload upon 22user request. 23 24<span id="2.1"></span> 25 26## 2.1. Splitting file into segments 27 28When TCP-connection interrupts abnormaly there is no way to determine 29what part of data stream has been succesfully delivered and what hasn't 30been delivered. Therefore a client cannot determine what position to 31resume from without communicating to server. In order to eliminate 32additional communication file is represented as an array of segments of 33reasonable length. When TCP-connection interrupts while transmitting 34certain segment, client retransmits the whole segment until a positive 35reponse will be received from server or maximal number of tries will be 36reached. In the protocol being described the client is responsible for 37choosing optimal length of a segment. 38 39For tracking the progress of file upload client and server use identical 40numbering scheme for each byte of a file. The first byte of a file has 41number 0, the last byte has number n-1, where n is the length of file in 42bytes. 43 44The order of transmission of a segment is not defined. Client may choose 45arbitrary order. However it is recommended to send segments in order 46ascention of byte numbers. Moreover, a user agent might decide to send 47multiple segments simultaneously using multiple independent connections. 48If a client exceeds maximal number of simultaneous connections allowed, 49server might return 503 "Service Unavailable" response. 50 51In case of simultaneous transmission it is prohibited to send 2 or more 52requests with overlapping ranges within one session. Whenever server 53detects simultaneous requests with overlapping ranges it must return an 54errorneous response. 55 56<span id="2.2"></span> 57 58## 2.2. Encapsulation 59 60Each segment of a file is encapsulated into a separate HTTP-request. The 61method of the request is POST. Each request contains following specific 62headers: 63 64| Header | Function | 65| ------------------- | ---------------------------------------------------------------------- | 66| Content-Disposition | `attachment, filename="name of the file being uploaded"` | 67| Content-Type | mime type of a file being uploaded (must not be `multipart/form-data`) | 68| X-Content-Range | byte range of a segment being uploaded | 69| X-Session-ID | identifier of a session of a file being uploaded (see [2.3](#2.3)) | 70 71`X-Content-Range` and `X-Session-Id` can also be `Content-Range` and `Session-ID`, respectively. 72 73The body of the request must contain a segment of the file, 74corresponding to the range that was specified in `X-Content-Range` or 75`Content-Range` headers. 76 77Whenever a user agent is not able to determine mime type of a file, it 78may use `application/octet-stream`. 79 80<span id="2.3"></span> 81 82## 2.3. Session management 83 84In order to identify requests containing segments of a file, a user 85agent sends a unique session identified in headers `X-Session-ID` or 86`Session-ID`. User agent is responsible for making session identifiers 87unique. Server must be ready to process requests from different 88IP-addresses corresponding to a single session. 89 90<span id="2.4"></span> 91 92## 2.4. Acknowledgment 93 94Server acknowledges reception of each segment with a positive response. 95Positive responses are: 201 "Created" whenever at the moment of the 96response generation not all segments of the file were received or other 972xx and 3xx responses whenever at the moment of the response generation 98all segments of the file were received. Server must return positive 99response only when all bytes of a segment were successfully saved and 100information about which of the byte ranges were received was 101successfully updated. 102 103Upon reception of 201 "Created" response client must proceed with 104transmission of a next segment. Upon reception of other positive 105response codes client must proceed according to their standart 106interpretation (see. [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt)). 107 108In each 201 "Created" response server returns a Range header containing 109enumeration of all byte ranges of a file that were received at the 110moment of the response generation. Server returns identical list of 111ranges in response body. 112 113<span id="appa"></span> 114 115## Appendix A: Session examples 116 117### Example 1: Request from client containing the first segment of the file 118 119```http 120POST /upload HTTP/1.1 121Host: example.com 122Content-Length: 51201 123Content-Type: application/octet-stream 124Content-Disposition: attachment; filename="big.TXT" 125X-Content-Range: bytes 0-51200/511920 126Session-ID: 1111215056 127 128<bytes 0-51200> 129``` 130 131### Example 2: Response to a request containing first segment of a file 132 133```http 134HTTP/1.1 201 Created 135Date: Thu, 02 Sep 2010 12:54:40 GMT 136Content-Length: 14 137Connection: close 138Range: 0-51200/511920 139 1400-51200/511920 141``` 142 143### Example 3: Request from client containing the last segment of the file 144 145```http 146POST /upload HTTP/1.1 147Host: example.com 148Content-Length: 51111 149Content-Type: application/octet-stream 150Content-Disposition: attachment; filename="big.TXT" 151X-Content-Range: bytes 460809-511919/511920 152Session-ID: 1111215056 153 154<bytes 460809-511919> 155``` 156 157### Example 4: Response to a request containing last segment of a file 158 159```http 160HTTP/1.1 200 OK 161Date: Thu, 02 Sep 2010 12:54:43 GMT 162Content-Type: text/html 163Connection: close 164Content-Length: 2270 165 166<response body> 167``` 168