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).

json

{ "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:

wf

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.