Bulk file uploads

Upload a docs folder or many files to a bucket with an upload session.

Requests go to https://api.revdoku.com. Every path starts with /v1, for
example https://api.revdoku.com/v1/buckets. Send your API key as a bearer token. For one file, see
Upload a file.

Use the CLI for a local folder: revdoku upload ./folder --bucket-id ID.
To implement folder uploads yourself:

1. Open an upload session with the expected file count.
2. Request upload URLs for a small batch of files.
3. Upload each file, then finalize that batch.
4. Repeat until all files are uploaded.
5. Complete the session.

POST /v1/buckets/bkt_.../upload_sessions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "expected_file_count": 123
}

Then request descriptors for one subbatch:

POST /v1/buckets/bkt_.../upload_sessions/bus_.../uploads
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "files": [
    {
      "path": "index.html",
      "name": "index.html",
      "byte_size": 1234,
      "checksum": "BASE64_MD5",
      "content_type": "text/html",
      "sha256": "HEX_SHA256"
    }
  ]
}

Use data.uploads[].upload.url and data.uploads[].upload.headers for the
object-storage PUT. Do not send Revdoku authorization headers to object
storage. After each successful descriptor subbatch, commit a bounded batch:

POST /v1/buckets/bkt_.../upload_sessions/bus_.../finalize_batch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "limit": 12
}

Repeat descriptor and finalize subbatches until all selected files are uploaded.

Close the session when all uploads are done. Use complete:false only when
canceling or interrupting the upload; it closes the session and releases the
lock without committing any unfinalized staged uploads.

POST /v1/buckets/bkt_.../upload_sessions/bus_.../finalize
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "complete": true
}

For large sessions, finalization can take several requests.

Repeat finalization until the pending flag is no longer true.