Skip to content

The Sobamail web environment

Sobamail Desktop serves an app instance's page from an origin of its own:

soba://<instid>.<replica>.instance/

<instid> is the instance id and <replica> the uuid of the mailbox the instance belongs to, both as 26 base32hex digits. Everything the page asks of that origin is answered by the client itself; nothing leaves the machine. The origin offers four things:

Request Answers with
GET /<path> A file of the app's user interface.
POST /api/v2/object The reply of the app's backend to one object.
GET /api/v2/blob/<blob id> The contents of a stored blob.
GET /api/v2/event The instance's mutations, as a stream of server-sent events.

A page writes these URLs relative to its origin, fetch("/api/v2/object", ...), so that the same page works for every instance of the app.

The origin

The host names one instance in one mailbox, and the page gets what a browser gives an origin: storage of its own, and no reach into the frames, requests or event streams of another instance. The host names neither the app nor the account; the client reads both from the instance it looks up by the id.

Before it serves anything, the client checks the host:

Status When
400 Invalid appinst The host is no <instid>.<replica>.instance.
404 App not found The mailbox holds no instance with that id, or the host names a mailbox other than the one the view shows.
500 No mailbox open The view shows no mailbox.

The whole path under the origin is the instance's own. A path that starts with /api/ is an API call; any other path names a file.

Static files

GET /<path>

The response is the file at <path> in the app's assets/ folder, with the Content-Type its extension names and its size as Content-Length. The empty path is index.html, the app's entry point. A path that names no file there is answered 404 Not found.

A deployed instance is served from the assets frozen with its version, so its files do not change until the instance is upgraded. A developer-mode instance is served from the assets/ folder of its develroot as it is on disk at the time of the request: a reload of the page shows what the build just wrote. See Shipping Sobamail Apps.

An app may come without a user interface. For such an instance / and /index.html are answered 200 OK with a page that says the application has no graphical user interface, and any other path 404 Not found.

API calls

An API URL carries a version and a section, /api/v<version>/<section>. The version is 2; the sections are object, blob and event.

Status When
400 The version is missing, unreadable, or no version the client knows; or the section is missing.
404 The section is none of the three.

The object and event sections are the page's own. A request for them that names another instance than the one the requesting frame belongs to, or one made from a frame that is not an app page, is answered 403 Forbidden.

/api/v2/object

POST /api/v2/object
Content-Type: application/msgpack

The body is one SMC document, the object the page sends to the app's backend, and the response is the backend's reply to it. Structured Message Content describes the documents; this section is the HTTP side.

The Content-Type says how the body is encoded, and it is compared whole: a parameter after it, such as ; charset=utf-8, makes it a type the route does not take.

Content-Type Body
application/msgpack, application/x-msgpack, application/x.msgpack, application/vnd.msgpack The document as MessagePack, with string or integer keys.
application/json The document as a JSON object. A whole number is read as an integer, any other number as a float.

The object's key must be one of the objects the app lists; the backend's process() then runs on it (runtime.md).

The reply is a MessagePack SMC document with integer keys and Content-Type: application/msgpack, whatever the request's encoding and whatever the status. A backend that responds nothing leaves the body empty.

Status When Body
200 OK The backend processed the object. What it passed to soba.task.respond(), or nothing.
400 Bad request The Content-Type is none of the above; the body is empty, is no SMC document, or is a Structured Message with a malformed field; or the app does not list the object. None.
400 Bad request The backend refused the request as invalid. The backend's own document, or a StructuredError of the code Client.Validation.
403 Forbidden The request comes from another instance's page, or from a frame that is not an app page. None.
405 Method not allowed The method is not POST. None.
413 Response too large The reply is over 2 GiB. None.
500 Internal error The backend failed: its process() threw, or the app could not be started. The backend's own document, or a StructuredError of the code Server.InternalError; none when the app could not be started.
503 Service unavailable The client is shutting down. None.
504 Gateway timeout The backend did not start, or did not finish, within 30 seconds. None.

POST is the route's one method: a page sends every object with it, whether or not the object writes anything.

/api/v1 takes the same requests as /api/v2/object, as MessagePack alone.

One object key is the client's own and reaches no backend: {https://sobamail.com/module/contacts/v1}GetOnlineUsers, answered 202 Accepted to the contacts app and 401 Unauthorized to any other. See Presence.

Two more are the client's own, from any app: {https://sobamail.com/module/base/v1}GrantRequest and {https://sobamail.com/module/base/v1}CrossRequest, with which a page sends an object to the other apps that list it. Their status codes are their own; see Cross Requests.

/api/v2/blob

GET /api/v2/blob/<blob id>?pt=<parent type>&pi=<parent id>

The response is the contents of one stored blob of the mailbox, as the bytes that were stored: 200 OK, the blob's media type as Content-Type, its size as Content-Length.

Part Value
<blob id> The id of the blob, the blobId of a {https://sobamail.com/module/base/v1}Blob object as soba.blob.create() returns it.
pt The type of the blob's parent, as a decimal number. 26 is the data of an app instance.
pi The id of the blob's parent. For pt=26, the instance id.

A blob is stored in chunks, each a Blob object with an id of its own, and the route answers one chunk per request; a page that wants the whole asks for each blobId in order. Data shorter than 512 bytes is never stored as a blob: soba.blob.create() hands it back inline, and there is nothing to fetch.

Status When
200 OK The blob is served.
400 The blob id is missing, pt is missing or names no parent type, or pi is no id of a parent of that type.
404 The mailbox holds no blob with that id under that parent, or its contents cannot be read.

/api/v2/event

GET /api/v2/event
Accept: text/event-stream

The response is a server-sent events stream that announces every mutation written to the instance, and the online status of the account's colleagues to an app that asks for it. App Event Stream is its reference.