Skip to content

Cross Requests

An app's page sends an object its own backend does not list to the apps that do list it. The user allows it once; the object then reaches every instance of every app in the mailbox that lists its key, and their answers arrive on the page's event stream.

Three objects of the base namespace https://sobamail.com/module/base/v1 carry the exchange. The client handles all three itself; they reach no backend, and no app lists them.

Object Direction Carries
GrantRequest Page to client, POST /api/v2/object The key of the object the page wants to send.
CrossRequest Page to client, POST /api/v2/object An id the page chooses, and the object.
CrossResponse Client to page, an event on GET /api/v2/event The id, and one app's answer or the end-of-stream marker.

A page opens its event stream first, asks for the grant, then sends its requests. Asking Other Apps walks through a complete example.

Asking for the grant

{
    "namespace": "https://sobamail.com/module/base/v1",
    "name": "GrantRequest",
    "content": { "objectKey": "{https://example.com/module/orders/v1}GetOrder" }
}
Status When
200 OK The grant is on record, or the user allowed it now.
400 Bad request objectKey is missing or is no object key.
401 Unauthorized The user denied the request, or the view that asked went away before an answer.
404 Not found No other app instance in the mailbox lists the key.
500 Internal error The grants cannot be read or written.

No reply carries a body. With a grant on record the reply is immediate. With none, the client shows a banner atop the app's view naming the app, the object and the apps that list it, and the request stays open until the user answers:

Answer Effect
Allow The grant is recorded for this instance of the app.
Always Allow The grant is recorded for every instance of the app, present and future.
Deny Nothing is recorded; the next GrantRequest asks again.

A grant covers one object key. The app manager records it as a row of its own and replicates it like any other, so a grant given on one device holds on every device of the mailbox. The Application Manager lists the grants on its Grants screen, where the user removes them; a removal replicates as the grant did.

Sending the request

{
    "namespace": "https://sobamail.com/module/base/v1",
    "name": "CrossRequest",
    "content": {
        "id": "7f3c",
        "object": {
            "namespace": "https://example.com/module/orders/v1",
            "name": "GetOrder",
            "content": { "number": 4712 }
        }
    }
}
Key Value
id A string of 1 to 128 bytes the page chooses. Every CrossResponse to this request carries it.
object The object to send, a whole SMC document.
Status When
202 Accepted The object is on its way to the apps that list it.
400 Bad request id is missing, empty or too long, or object is no SMC document.
401 Unauthorized The instance holds no grant for the object's key.
429 Too many requests Five requests of the instance are waiting already. The request is dropped.
500 Internal error The grants or the list of apps cannot be read.

No reply carries a body. The object is handed to every instance, other than the asking one, of every app in the mailbox that lists its key. Each backend receives it in process() as it receives an object its own page posts (runtime.md), and answers with soba.task.respond().

The requests of one instance are handled one at a time, in the order they were accepted: a request is handed out once the one before it has been answered, its end-of-stream event sent. Each is still answered 202 at once. The events of two requests of an instance therefore never interleave.

Beside the request being handled, an instance may have five waiting. A request posted while five wait is answered 429 Too many requests and is not kept: no event follows for its id, and the page sends it again later if it still wants the answer. Every instance has a queue of its own.

Receiving the answers

Each answer is one event on the asking instance's stream:

event: {https://sobamail.com/module/base/v1}CrossResponse
data: {"content":{"appId":"orders.example.com","id":"7f3c","instanceId":"AQ6I3IU9JD3BB88MHPV7FKQRI0Z1","object":{"content":{"total":99},"name":"Order","namespace":"https://example.com/module/orders/v1"}},"name":"CrossResponse","namespace":"https://sobamail.com/module/base/v1"}
Key Value
id The id of the CrossRequest this answers.
appId The id of the app that answered.
instanceId The id of the instance that answered.
object The answer, an SMC document as JSON. For a request the backend failed it is the backend's own refusal, or a StructuredError of the code Server.InternalError.

An instance that answers nothing leaves no event. After every instance has been heard, one last event ends the request:

event: {https://sobamail.com/module/base/v1}CrossResponse
data: {"content":{"eos":true,"id":"7f3c"},"name":"CrossResponse","namespace":"https://sobamail.com/module/base/v1"}

It carries eos: true and the id, and neither appId, instanceId nor object. A request no instance answered gets this event alone.

The events have no id field, so Last-Event-ID and the reconnect catch-up stay the mutations'. They are pushed to the streams open at that moment: a page whose stream is down while an answer is pushed does not receive it.

From a page

const BASE = "https://sobamail.com/module/base/v1";
const events = new EventSource("/api/v2/event");
const waiting = new Map();

events.addEventListener(`{${BASE}}CrossResponse`, (ev) => {
    const { id, eos, appId, instanceId, object } = JSON.parse(ev.data).content;
    const request = waiting.get(id);
    if (!request) {
        return;
    }

    if (eos) {
        waiting.delete(id);
        request.resolve(request.answers);
    }
    else {
        request.answers.push({ appId, instanceId, object });
    }
});

async function post(name, content) {
    return fetch("/api/v2/object", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ namespace: BASE, name, content }),
    });
}

async function crossRequest(object) {
    const objectKey = `{${object.namespace}}${object.name}`;
    if ((await post("GrantRequest", { objectKey })).status !== 200) {
        throw new Error("not allowed");
    }

    const id = crypto.randomUUID();
    const answers = new Promise((resolve) => waiting.set(id, { resolve, answers: [] }));
    if ((await post("CrossRequest", { id, object })).status !== 202) {
        waiting.delete(id);
        throw new Error("not sent");
    }

    return answers;
}