Function markRequestFailed

Reports that the request named by id (from takeOutgoingRequests) was refused: you sent it, and what came back was not a success. Pass the HTTP status you received, or 0 if nothing came back at all, such as a dropped connection, a DNS failure, or a timeout.

An addition to the frozen surface, not a change to it. This is the counterpart to markRequestSent, and the reason that call is no longer the only thing you can say. A 502 from a proxy, or a 503 with an empty body, used to have nowhere to go but the success path.

const res = await fetch(url, { method, body: request.body })
if (res.ok) await markRequestSent(request.id, await res.text())
else await markRequestFailed(request.id, res.status)
Copy

This changes nothing about what the library knows, deliberately. A refused request taught it nothing. The request stays outstanding, so the retry is an ordinary second send, and nothing is recorded as answered.

Forgetting to call this is safe. A request you never report stays pending exactly as if you had reported it refused. Reporting a refusal and reporting nothing are the same to this library, and both are the safe direction: what advances its state is markRequestSent, and only that. The cross-signing bootstrap this protects has since shipped as bootstrapCrossSigning, and does exactly what this said it would: it refuses with 'account_keys_not_fetched' rather than mint an identity on a question it was never told the answer to. This sentence said the bootstrap was still to come for the whole of the release that shipped it. The failure mode of silence is work that will not proceed, which you will notice, and never an identity destroyed.

What is not safe is calling markRequestSent for a response the server refused, and this library cannot detect that for you in every case. It sees a body and no status.

A body is accepted there when it is shaped like that endpoint's response: an object with no keys, or an object carrying at least one field that endpoint really returns. That refuses a Matrix error, an authentication challenge, a gateway's {"error":"Bad Gateway"}, an array, a proxy's HTML page, and a bare {"message":"Internal server error"}. What it accepts is every genuine success and, unavoidably, any failure whose body falls inside the same shape. The member that matters is the object with no keys: {} is the entire success response of the signing-keys upload, so a 503 that carried nothing and a 200 with nothing to say are the same bytes. An empty body is turned into {} before parsing.

That is the gap this call exists to let you close, and it can only be closed from your side, by branching on the status before you choose which of the two calls to make.

On the key query, the same body no longer reaches as far as it did. This paragraph used to say {} was what /keys/query answers for an account with no signing identity; measured against Synapse, Dendrite and continuwuity, all three name the queried account even when they hold nothing for it. So a key query answer that does not name your account is accepted here and does not satisfy bootstrapCrossSigning's ordering gate, and a 503's empty body reported through markRequestSent leaves that gate shut rather than authorising a mint. Reporting the status is still the right thing to do, and still the only thing that closes the same collision on the signing-keys upload.

The one confusion of the pair this library can catch is a 2xx passed here, which is rejected with not_a_failure_status: a success has a body worth reporting, and it belongs in markRequestSent. Statuses outside 0 and 300-599 are rejected the same way.

unknown_request means the same thing it does on markRequestSent, including the eviction case described there.