HTTP API for artifact upload

POST /api/1.0/artifact

The body contains a JSON dictionary describing the artifact:

{
	"type": "$TYPE",
	"workspace": "$WORKSPACE",
	"files": {
		"$PATH_FILE1" : {
			"type": "file",
			"size": 1234,
			"checksums": {
				"sha256": "$SHA256SUM_FILE1",
				"md5": "$MD5SUM_FILE1",
				...
			}
		},
		"$PATH_FILE2": {
		...
		}
	},
	"data": {
		...
	},
}

$PATH_FILE* can have directory components (e.g. "directory/tree/followed/by/basename"). "type" can only be "file" for now, but it's to be expected that we will support more things in the future (like "symlink" or "empty-directory"). The content of the "data" key is blindly copied in the corresponding field.

In case of success, the normal HTTP 200 answer contains the artifact id with a list of files to upload. It is worth noting that we expect the server to identify files that are already available by identifying them with the size + SHA256 checksum. Note also that empty files don't have to be uploaded.

{
	"id": 4567,
	"type": "$TYPE",
	"files_to_upload": [
		"$PATH_FILE1",
		...
	],
}

Note that the JSON returned is allowed to contain more keys in order to reuse the standard object representation that we will create for artifacts.

At this point, the various associated files are created but they are marked as "partial", and the whole artifact will be considered as "incomplete" for as long as it has at least one partial file associated to it. In the future, we expect that depending on the type, the code might refuse to create the arfifact.

There are various failure scenario where it will return error codes:

• it can return HTTP 400 Bad Request in case the $WORKSPACE doesn't exist
• it can return HTTP 400 Bad Request when the input data is invalid (no JSON data, no "type/workspace" key, value of "type/workspace" is not a string, etc)
• it can return HTTP 403 Permission denied if the user doesn't have the permission to create an artifact (to be implemented later)

PUT /api/1.0/artifact/$ID/files/$PATH_FILE

Here we take inspiration from https://developers.google.com/drive/api/guides/manage-uploads#uploading to manage the upload of the files, with a possibility to resume an incomplete upload. So the initial request (and any post-failure try to resume) announces what it will upload through the Content-Range header.

And an empty PUT with Content-Range: */$SIZE or Content-Range: */* will trigger an answer where HTTP 200 means that the file is complete already, but an HTTP 206 Partial Content means that the file is incomplete and you need to process the Range field to know what's left to be uploaded.

When the request has received all the data for the file, it will answer with HTTP 201 Created. If there's still data to be sent, it will answer with HTTP 200.

There are various failure scenario where it will return error codes:

• it can return HTTP 404 Not found in case the artifact ID doesn't exist, or if the path does not exist in the artifact
• it can return HTTP 400 Bad Request when the range data is incompatible with the known size of the file
• it can return HTTP 403 Permission denied if the user is not the owner of the artifact
• it can return HTTP 409 Conflict when the checksum of the uploaded file does not match the initially announced checksum, in that case if will erase any data already received so that the user can re-upload from scratch if they wish so

See #63 (closed) for more information on how files are stored in debusine.