Skip to content

Temporary Blob Service (TBS)

This plugins implements a "temporary blob service".

With this service, you can store and retrieve various files of any type through a REST api. It's not a permanent storage service because all objects have a lifetime and will be automatically cleaned.

Extra key/values can be associated with the data and will be retrieved when you get the file.

1. Concepts

1.1 namespace

A namespace is just a kind of bucket for yours blobs. It's a plain string (length <= 64 characters). Allowed characters are alphanumeric ones [0-9a-zA-Z], . (dot), _ (underscore) and - (hyphen).

1.2 blob

You can see blob as a binary file. It can be a text file, an image or anything else. The service does not make any assumptions about the content of your blobs. They are never altered.

When you submit your blob to the service, you will get a blob unique id (blob_uid). You have to know your blob_uid to retrieve it. There is no other way for the moment (no search service, no listing).

You can provide an indicative media type to your blob. It will be returned as a HTTP Content-Type header during retrieval.

1.3 lifetime

All blobs have a lifetime (in seconds). The lifetime can be specific to each blob, even if there is a default and a maximum value in global configuration. There is no real limit to this lifetime but keep in mind that this service was designed as a "temporary blob service" and not a "persistant storage solution". So we optimized it for speed, not for safety.

1.4 extra key/values (metadata)

You can add some extra key/values (limited to 64 key/values) for each blob you store.

Each key is limited to 64 characters. Allowed characters for keys are:

  • alphanumeric ones [0-9a-zA-Z]
  • and '-' (hyphen)

Each value is limited to 1024 characters. Allowed characters for keys are:

  • alphanumeric ones [0-9a-zA-Z]
  • . (dot)
  • _ (underscore)
  • - (hyphen)
  • + (plus)
  • / (slash)

So if you want to pass others things in metadata values, encode them in base64 for example.

Note: the total size of the http request (including metadata but excluding blob itself) is limited to 8 kB.

2. API

2.1 POST /tbs/{namespace}/blobs

This service add a new blob in the blob store inside the given namespace. The blob is the (raw) body of your POST request.

Note: The namespace is created automatically.

If the operation is successful, the service will respond with a HTTP/201 Created status code and you will get your blob_uid in the JSON reply (or in Location header).

HTTP/1.1 201 Created
Location: http://{...}/tbs/{namespace}/blobs/{blob_uid}
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "blob",
        "id": "{blob_uid}",
        "attributes": {
            "lifetime": 3600,
            "content-type": "application/octet-stream"
        },
        "links": {
            "self": "http://{...}/tmp/blob_store/{namespace}/blobs/{blob_uid}
        }
    }
}

If the operation is not successful, the service will respond with a:

  • HTTP/413: when your blob is too large (there is a max size in the global configuration)
  • HTTP/429: when you hit the number or the size limit of the namespace
  • HTTP/400: in other client error cases (bad namespace string for example, too big lifetime...)

You can also set:

  • a specific lifetime for your blob by adding (for example) a X-TmpBlobStore-Lifetime: 60 header to your request
  • a specific indicative Content-Type for your blob by adding (for example) a X-TmpBlobStore-ContentType: image/png header
  • a specific indicative Content-Disposition for your blob by adding (for example) a X-TmpBlobStore-ContentDisposition: attachment; filename="foobar.png" header
  • <FIXME>
  • any extra key/value pairs (see concepts) with one or several http headers in your POST request: X-TmpBlobStore-Extra-{Yourkey}: {your_value} with:
    • {Yourkey}: your key with the first character in uppercase (see concepts for allowed characters and size)
    • {your_value}: your value (see concepts for allowed characters and size)
  • </FIXME>

2.2 GET /tbs/{namespace}/blobs/{blob_uid}[?delete=1]

Get the given blob (the body posted with the previous POST request) or HTTP/404.

If delete=1, the blob is deleted just after the read. So, with this parameter, this is a "single use request".

Notes:

  • if you set a X-TmpBlobStore-ContentType header during POST operation, the value will be sent in the reply of this GET operation as standard Content-Type header (this is really important if (for example) you store a PNG image and you want this file to be automatically recognized as an image by a browser using this download link)
  • if you set a X-TmpBlobStore-ContentDisposition header during POST operation, the value will be sent in the reply of this GET operation as standard Content-Disposition header (this can be really useful if you want to force the download filename for a browser (or for wget with --content-disposition flag or for curl with -OJ flags)
  • <FIXME>
  • if you set some extra key-values during POST operation, the key/values will be returned as X-TmpBlobStore-Extra-{Yourkey}: {your_value} headers with the blob during this GET operation
  • </FIXME>

If the operation is not successful, the service will respond with a:

  • HTTP/404: when the (namespace, blob uid) tuple does not exist
  • HTTP/400: in other client error cases (bad namespace string for example)

2.3 DELETE /tbs/{namespace}/blobs/{blob_uid}

Delete the given blob or HTTP/404. (see note above)

2.4 POST /tbs/{namespace}/blobs/{blob_uid}/clone

FIXME: operation not implemented

Do a clone of the given blob_uid (without an internal copy of the whole blob).

The request body is ignored but you can override headers:

  • X-TmpBlobStore-Lifetime
  • X-TmpBlobStore-Extra-{Yourkey}: {your_value}

See POST operation for details

note: The data is effectively deleted when the last clone is deleted.

2.5 GET /tbs/{namespace}/blobs

FIXME: operation not implemented

Get a JSON with some statistics about the namespace

2.6 GET /tbs

FIXME: operation not implemented

Get a JSON with some statistics about the while service.