External Upload protocol used by Metronome

Protocol to use an external upstream service for HTTP Upload with mod_http_upload_external.


Metronome uses a custom protocol based on Prosody's v2 token script, to hand out and manage upload slots on the upstream service. What differs is the addition of DELETE verb support and change of the token http variable name (being "token" instead of "v2").

The Tokens, for PUT and DELETE

An authorization token to fill an upload slot (PUT) is a padded SHA256 HMAC sequence of the file name, file size and file name type authenticated by the configured secret acting as key.

Instead for file deletion the authorization token is composed by padded sequence of file name, delete secret and again authenticated by the config secret.

Codes

Metronome expects certain codes when talking with the upstream service to purge or clear expired upload slots, I'll list the codes which the provided default script (share.php) outputs:

  • 201 - When a file is created on PUT
  • 202 - When a file fails deletion on DELETE
  • 204 - When a file is deleted on DELETE
  • 403 - Whenever there's an issue authenticating the PUT or DELETE request
  • 409 - Whenever there's a conflict, a.k.a. the file already exists

Setting

Metronome provides a PHP script which you may use to provide an upstream http upload service, or that you may use as example to write your own. It's located into the plugins/http_upload_external/resources folder into the Metronome's sources.

To use it, drop it somewhere in your web server root and make sure PHP is enabled, then create a folder outside your web server root and make it writable/accessible by your web server then change the $CONFIG_STORE_DIR value into the script. After that you need to have $CONFIG_SECRET and optionally $DELETE_SECRET respectively match http_file_secret and http_file_delete_secret Metronome's configuration directives, the deletion secret is ONLY required in the case you want Metronome to handle file cleanup directly by setting http_file_external_delete_url in the configuration (SNI is not supported in case of https URL).