Backend overview
AnyDrop is a front-end library. It ships no server: your backend implements a small HTTP contract. Every field the client adds to an upload request has the ad prefix (adUploadId, adChunkIndex, ...).
- Protocol (v2.0): the full contract, with every field, status code and edge case.
- Express example: a complete working server in about 100 lines.
- Laravel example: the same contract as a Laravel controller.
- Python (FastAPI) example: the same contract with FastAPI, plus notes for Flask and Django.
- Java (Spring Boot) example: the same contract as a Spring Boot 3
@RestController, with the multipart size limits.
The four endpoints
Your server implements these. Only the first is needed for plain uploads; the others switch on folders, resume and chunk assembly.
| Endpoint | Method | Option | Purpose |
|---|---|---|---|
/upload | POST multipart | url | One chunk (file, adUploadId, adChunkIndex, adChunkSize, adChunkOffset, adTotalSize, ...), or a whole file when it is not chunked: then there are no chunk fields, only file and adRelativePath. Files up to chunkSize are sent whole even with chunking: true. Accept chunks in any order and more than once. |
/upload/status?uploadId= | GET | chunkStatusUrl | { "received": [0, 1, 4] }, or { "received": [], "complete": true } once the file is assembled, or 404 if unknown. Lets the client resume. |
/upload/manifest | POST JSON | manifestUrl (with sendManifest) | The folders and files of a batch. Create every folder, including empty ones. A repeated manifest replaces the earlier one. |
/upload/finalize | POST JSON | finalizeUrl | { uploadId, relativePath, totalSize, totalChunks }: assemble the chunks into the final file. Must be idempotent. |
Errors are { "code": "...", "message": "..." } with an HTTP status; see the error table and the client-side error codes.
Optionally add HEAD /upload/ping (any status, Cache-Control: no-store) and set connectivityProbeUrl, so a dead network is detected quickly. See Offline and connectivity.
The matching client configuration
js
new AnyDrop('#uploader', {
url: '/upload',
chunking: true,
chunkSize: 5 * 1024 * 1024,
sendManifest: true,
manifestUrl: '/upload/manifest',
chunkStatusUrl: '/upload/status',
finalizeUrl: '/upload/finalize',
connectivityProbeUrl: '/upload/ping',
});Security checklist
The examples are minimal. Before you use anything like them in production:
- Authenticate every request, and check that an
uploadIdbelongs to the current user. - Never build a file path from client input without checking it. The examples reject paths that are empty, absolute, contain
\, or contain..or empty segments. - Limit the size of a chunk, of a manifest request body (a manifest lists every file of a batch) and of the total storage per user.
- Write chunks to a temporary name and rename them, so a cut-off write never counts as received.
- If the page and the API are on different origins, answer the CORS preflight for
GET,POSTandHEAD, and allow the headers the client sends (X-Requested-With,Cache-Control,Content-Typeand your own). - Check chunk lengths: a chunk whose length does not match
adChunkSize(or the rest of the file for the last chunk) should be answered with400 INVALID_CHUNK.