Back state up to the account

Your app writes its state to the account once and reads it back on whichever device the person signs in on next, and a first run reads as empty rather than as a failure. This page covers the bounded wait, the read, the write and its unlock, following the account, and keeping one writer.

• Uses cloud.fs.available, cloud.fs.promises.readFile and writeFile, cloud.fs.unlock, cloud.quota, account.info, account.onChange, apiWithin and BrokerUnreachableError from @fkn/lib/api
• Needs an account
• Proven by one integration

The account is the FKN identity a person carries between sites, and the person connects it to your site with connect(), see connecting. cloud.fs is the file system whose bytes live in the account’s storage and nowhere on this device, see three file systems. Every call on it goes through the broker, the connection your page holds into FKN, and resolves when the account has answered. The app is the media library from the other pages: the list of what the person kept is serialized and written to backup/library.bin, and the same path is read on the next device.

Three things went wrong in the integration behind this page, and each cost real time. Absence is worded two different ways, and an app that matches only one of them retries forever. A custom error code does not cross out of the broker, and available() resolves whether a connect token is held rather than reporting a capability. The steps below meet them in order.

[Page] Bound the broker wait

cloud.fs and account.info() wait for the broker connection with no deadline. On a page where the broker never connects they never settle, and neither does a status line that awaits them. apiWithin from @fkn/lib/api is the bounded wait the socket calls use.

It resolves once the broker has answered and rejects with BrokerUnreachableError after 8,000 ms, then after 1,000 ms per call once any deadline in the realm was missed. A realm is one JavaScript execution context, such as this window, and the class is created in yours, so instanceof works. Run it before the first read, and resolve a fallback rather than rejecting, because a UI has to say something:

app.ts

const readBackup = async (): Promise<Library | null> => {
  try {
    await apiWithin('the library backup') // resolves once the broker answered, so the read below cannot park
    return decode(await cloud.fs.promises.readFile('backup/library.bin'))
  } catch (error) {
    if (!(error instanceof BrokerUnreachableError)) throw error
    error.message // @fkn/lib: no broker connection within 8000ms, so the library backup could not be requested
    return null // a resolved fallback, so the page can say the account was not reached
  }
}

const library = await readBackup() // the library, or null after 8 seconds with no broker

The phrase you pass is the one the message repeats after so. One apiWithin at startup is enough, because once the broker has answered every later call finds it at once. It bounds the wait for the broker and nothing after it: the read runs against a connected broker and has no deadline of its own, and a cap on that is a Promise.race of yours, see reading the account. A timer that wins says the call was not observed, never that the backup is gone, so keep the state you had.

Which calls wait and which give up is on connection and lifecycle.

[Page] Treat absence as empty

On a first run there is no backup and the read rejects. Absence arrives worded two completely different ways: Not found when the service, the FKN server that keeps the account’s files, refuses to presign a path with no committed row, and storage: read failed (404) when the presign succeeded and the object itself answered 404. Both mean the same thing. An app that matched only the first read a missing backup as a transient failure and retried forever, and a library went un-backed-up for a day with no error anywhere.

isNotFound from @fkn/lib/cloud/fs covers both. The library catches every cloud.fs read and write rejection on your side and, for absence, throws a fresh StorageNotFoundError whose code is FKN_STORAGE_NOT_FOUND. That code is there because it is minted in your realm. An error thrown in the broker crosses a realm before you catch it, and only its name, message, stack and cause survive the hop, so a code set beside a message in the broker is gone by the time you see it, see what crosses a realm.

Test absence with the helper and render an empty library:

app.ts

const empty: Library = { items: [] }

const restore = async (): Promise<Library> => {
  try {
    return decode(await cloud.fs.promises.readFile('backup/library.bin'))
  } catch (error) {
    if (isNotFound(error)) return empty // true on a first run, for 'Not found' and for 'storage: read failed (404)' alike
    throw error // locked, unreachable and a changed key pass through, since none of them is empty
  }
}

const library = await restore()
render(library, library.items.length ? '' : 'nothing saved yet') // what a first run shows, and the first write is safe

isNotFound answered true and the page rendered “nothing saved yet”. Nothing else is empty. A path that could not be read is not one to write a first backup over, so the locked case, storage: api unreachable and the messages of a changed key all pass through. The order to test them in is on handling errors.

[Page] Write and ask to unlock

cloud.fs.promises.writeFile resolves once the object is committed in the account, so a resolved write is a durable one, see cloud.fs is async only. Every file is encrypted in the broker before it is uploaded, and your app never handles a key, see encryption.

Locked means the broker holds no usable key for this app and account. A write on a locked account does not fail at once.

It raises the broker’s unlock card, Storage locked. Click to unlock., inside the call and waits on the person, with no deadline. StorageLockedError arrives only after the card was dismissed, could not be shown, or delivered no usable key, see locked.

Ask once more through unlock(), which raises the same card and answers what it answered, and retry the write once:

app.ts

const save = async (attempt = 0): Promise<boolean> => {
  try {
    await cloud.fs.promises.writeFile('backup/library.bin', encode(library)) // committed in the account once this resolves
    return true
  } catch (error) {
    if (!(error instanceof StorageLockedError)) throw error
    if (attempt > 0 || !(await cloud.fs.unlock())) return false // a second dismissal is an answer, so the card is not raised again
    return save(attempt + 1) // the write again, now that the broker holds a key
  }
}

await save() // true, after one unlock card when the account was locked

The card appeared once, inside the write, and the write completed when the person unlocked. unlock() runs only after a dismissal, and the retry only once, so a lock the person keeps declining cannot loop the card in front of them. Every other refusal passes through: a write with no account connected rejects with storage: not connected, a full account with Storage quota exceeded, and a key that changed with the messages on encryption.

.bin is not an extension the library knows, so the broker stores the object as application/octet-stream, and a contentType option chooses otherwise, see content types.

[Page] Follow the account

account.onChange(callback) calls you whenever the connection changes: an account connected, its token refreshed or refused, or a disconnect. The callback receives no argument, so call account.info() for the new state, which the broker caches for 5 seconds, see following changes.

cloud.fs.available() answers whether the broker holds a connect token for this site, and nothing about reachability or the locked state, see cloud.fs is async only. It is not a capability check, and it answers false both when no token is held and when the call itself failed, since the library turns a rejection into false. A person who is signed in can therefore read false, and onChange stays silent then because the account did not change.

So read info() beside it. A name next to false is a token the broker does not hold yet, and asking again is the only event coming. null next to false is a signed-out person, for whom onChange is the event to wait for:

app.ts

const sync = async () => {
  const info = await account.info() // null while nobody is connected, the username otherwise
  if (info === null) return stopWriting() // nowhere to back up to, and nothing is wrong
  if (await cloud.fs.available()) return restore() // a connect token is held, so the read runs
  setTimeout(sync, 5_000) // signed in with no token yet, and no event follows a late grant, so ask again on an interval of your own
}

const unsubscribe = await account.onChange(sync) // onChange resolves to its own unsubscribe
await sync()

// later, on teardown: unsubscribe() removes this callback only, and the broker keeps its registration

onChange resolved to its unsubscribe, and the first sync ran before any change. Keep the username beside the state you restored. When info() answers a different name, the state on this device belongs to the previous account, so read the new account’s backup before writing anything, or one person’s library lands in another’s account. Signing out clears the token and the keys the broker remembered for this app, so the next write rejects with storage: not connected until the person connects again, see disconnecting.

[Page] Keep one writer

Two tabs of the same app both restore, both follow the account, and both write backup/library.bin. The service refuses a write that overlaps another’s presign and commit with Concurrent update, retry, and a write that starts after the other’s commit replaces the object. So the tab holding the older library overwrites the one holding the newer, and a debounce on each only decides which loses.

Keep one writer per browser. The Web Locks API is the election: the first tab to request the lock holds it, every other tab waits at the same call, and the browser releases the lock when the holder closes, so the next tab becomes the writer without a message between them:

app.ts

let writer = false
const schedule = () => { if (writer) sync() } // a second tab reaches this line and starts nothing

onLibraryChange(schedule)
await account.onChange(schedule)

navigator.locks.request('library-backup', async () => {
  writer = true // this tab is the writer, and every other tab is parked on this request
  await sync()
  await new Promise<never>(() => {}) // held for the life of the tab, and released by the browser when it closes
})

Every tab follows the account and the library, and only the holder acts on either. A second tab runs schedule and starts nothing, until the first tab closes and the lock passes to it, at which point its callback restores and takes over. Coalesce the writer’s writes with a debounce of your own, since the library changes more often than it is worth committing.

Check it worked

Sign in on a second device and open the app there. The library the first device wrote renders, and a device that has never saved renders “nothing saved yet” with no error and no retry. When that is not what you see:

1. The first device reports a failure and keeps retrying, and the second shows nothing. The read matches one wording of absence. Not found and storage: read failed (404) both mean nothing is stored, and isNotFound answers true for both.
2. A write never settles and no error arrives. On a locked account the write raised the unlock card inside the call and is waiting on the person, with no deadline. StorageLockedError arrives only after the card is dismissed.
3. Neither the read nor account.info() settles, and no card is showing. The page has no broker connection, and apiWithin is what turns that into @fkn/lib: no broker connection within 8000ms, so the library backup could not be requested after 8,000 ms.
4. available() answers false while info() answers a name. The token was not held when it was asked, and no event follows, so ask again.
5. The write rejects with Not signed in. The token this site holds no longer names a live session, so connect again, see connecting.
6. The write rejects with Storage quota exceeded. The account is full across every app it connects, and cloud.fs.quota() reports the headroom, as the next section shows.

Optional: Show the account’s quota

Two quotas apply, and neither is the other. cloud.fs.quota() is the account’s storage across every app it connects, 1,000,000,000 bytes and 10,000 objects on a free account by default, and a backup write counts against it. cloud.quota() is today’s metered volume through the relay, which holds the real socket for net and dgram, and the proxy, which cloud.fetch sends a request through, and its fields are on account and quota:

app.ts

const storage = await cloud.fs.quota() // the account's storage, across every app it connects
storage.remaining // bytes a write may still add, 0 once the account is full
storage.objects < storage.maxObjects // true while a new path can still be created

const volume = await cloud.quota() // today's volume through the relay and the proxy, where a cloud.fs write is not counted
volume.throttled // false, or true once a free account spent the day's volume

Both calls wait for the broker like the read does, so they run after the apiWithin of the first step. cloud.quota() rejects when the broker is replaced under it, see a replaced broker.

Optional: Keep a copy on this device

opfs never contacts the broker, so a copy of the last good backup written there renders while the account is unreachable, and the read on encryption falls back to it on storage: api unreachable.

Optional: Read the seal time

cloud.fs.readFileSealed() reads the backup and the time it was sealed, so a device can refuse to apply a copy older than the one it already holds, see reading with the seal time.

See also

• account and quota
• storage
• encryption
• handling errors
• limits and timeouts