How-to
Website
Web app
Keep writes made offline
Keep the reader's changes when the network drops, and send them when it comes back. This needs offline support turned on (Make a site work offline), with "sync": true in its config:
Needs: offline with "sync": true in webfluent.app.json, below, and a site served over HTTPS (Make a site work offline).
{ "offline": { "precache": ["/"], "sync": true } }
This page saves a note, says when the save is waiting for the connection, and lists any the server refused once they were sent:
type Note { id: String, text: String }
api Backend(base: "/api") { }
api Backend.notes {
get list() at "notes" -> [Note]!
put save(id: String, body: Note) at "notes/{id}" -> Note!
invalidates [list]
}
page Notes(path: "/notes", title: "Notes", description: "Notes that save offline.") {
state draft = ""
state said = ""
Heading("Notes").h1
Input(bind: draft, label: "Note")
Button("Save") {
on click {
match await Backend.notes.save(id: "n1", body: Note(id: "n1", text: draft)) {
.ok(_) { said = "Saved." }
.err(.offline(true)) { said = "Saved here; it will be sent when you are back online." }
.err(e) { said = e.message }
}
}
}
Text(said)
if network.queued > 0 {
Text("{network.queued} change(s) will be sent when you are back online").muted
}
for r in network.refused by r.at {
Alert("The server refused a change ({r.status}).").danger
}
if network.refused.length > 0 {
Button("Dismiss") { on click { network.clearRefused() } }
}
}
How it works
With sync on, a write that is safe to send twice — a PUT or a DELETE, or a POST or PATCH its endpoint marks idempotent — that fails because the network is gone is kept. Its call still fails, as .offline(queued: true): no answer came, so there is no value to show, and the page can say the change is waiting. A POST or PATCH that is not idempotent is not kept: one whose answer was lost may already have reached the server, so it fails as .offline(queued: false) and the page decides.
network.queued is how many writes are waiting. Show it, as the page above does, so the reader knows their changes are safe.
What is kept
Only a write that failed for want of a network is kept: the browser says it is offline, or the site's own server could not be reached. A request to another origin that is refused while the browser is online — a CORS refusal, a closed port — fails as it would without sync.
A credential is never stored with a kept write. What an api's middleware adds — bearer(Session.token), an Authorization header from the session — is added again when the write is sent, by the middleware as it is then: a write made before a logout goes out with no one's token, never the old one. A write whose call carries a credential header itself (headers: { "Authorization": token }) cannot be kept without it, so it is not kept, and its call fails as it would without sync.
A File body is not kept, and its call fails as it would without sync.
When it is sent
When the connection returns, the kept writes are sent in order:
- by Background Sync, where the browser has it, so a closed tab still sends them;
- by the page otherwise, the next time it is open.
A server that takes the write makes stale what its endpoint invalidates: every read of those on an open page asks again, as it would after the write had gone at once. A server that refuses it — a 4xx — has answered, so the write is not sent again; it is listed in network.refused, each { method, url, status, at }, until network.clearRefused(). A server that is down, or asks the client to wait, keeps the write waiting for later.
A write whose service adds credentials with its middleware is sent by a page that has that service open, so the worker leaves it — and the writes after it, to keep them in order — for the next such page.
Forget the kept writes
To forget every kept write — when the reader logs out, for example — call WF.clearQueued() from one of the project's scripts.