Generic Backend Server Documents Messages Accounts Blobs PDF SVG Sendmail Submit UDP

Documents

⏵

A document has:

A read token, a 32-hexdigit token to access the document.
A write token, a 32-hexdigit token to modify (write) the document.
A revision, typically its last modification Unix timestamp in milliseconds since epoch.
The data, a JSON value.

HTTP/REST Requests

GET /backend/documents/READTOKEN

If-Newer-Than: REVISION

Retrieves a document.

Response

200 with the document
304, if there is no newer version of the document
404, if the document does not exist

PUT /backend/documents/READTOKEN

Write-Token: WRITETOKEN

Derived-From: REVISION

Revision: REVISION

Stores a new version of an existing document, or creates a new document.

To create a new document, the read and write tokens must be picked at random, and the Derived-From revision must be 0. Read and write token cannot be changed.

Response

200, if the document was saved successfully
400, if the document is not a valid JSON value
403, if the write token is wrong
409, if the Derived-From revision does not match current revision

GET /backend/documents?t=READTOKEN/IF-NEWER-THAN,READTOKEN/IF-NEWER-THAN,...

Retrieves a list of documents in a single request. The amount of documents that can be retrieved in a single request depends on the maximum path length the web browser or web server can handle. Older browsers can handle URIs up to 2000 bytes (~40 documents), while newer browsers can handle much longer URIs. NginX is limited to about 8170 bytes (~160 documents) by default, and CDNs are typically have similar limits.

Response

200

JavaScript

Using GenericBackend.js, a document can be retrieved as follows:

const backend = new GenericBackend('https://viereck.ch/backend');

backend.readDocument(readToken, onDone, onError);

function onDone(data, revision, request) {
	...
}

function onError(errorCode, request) {
	...
}

and stored as follows:

backend.writeDocument(readToken, writeToken, derivedFrom, revision, data, onDone, onError);

function onDone(request) {
	...
}

function onError(errorCode, request) {
	...
}

Working with Documents

Application data is typically stored as a series of documents, linked with each other. The application loads these documents by providing their read token, and saves them using their read and write tokens.

Documents are linked with each other by mentioning their read token (for read access only), or their read and write token (for read and write access). Links are JSON dictionaries with a read token:

{"read token": randomHex(16), "...": null}

or a read token and a write token:

{"read token": randomHex(16), "write token": randomHex(16), "...": null}

Blobs are linked using a token entry:

{"token": randomHex(32), "...": null}

In all three cases, the JSON dictionary may contain other keys as well.

All active documents must directly or indirectly be linked from the root document.

Documents are client-side merged. To perform a transaction, an application downloads the current version of the document, applies the desired changes, and writes resulting new version back to the server. If the document has been modified on the server in the meantime, the server refuses the new version. The client may then retry, or abort the transaction.

All application logic is implemented in the front-end.

Root Document and Garbage Collection

When first starting the server, it creates an empty root document. The read and write tokens of this document are stored in a file called root in the data folder.

The root document directly or indirectly links all data. Hence, only the system administrator should have access to it.

From time to time, a garbage collector sweeps through the data, starting with the root document, and following all linked documents and blobs. Documents and blobs which are not linked any more will be removed.

If the root document contains a gc key linking a document, the garbage collector will write a short report to this document whenever it completes.