Contents · Upgrades, reverts and snap epochs

pkgproxy design: upgrades, reverts and snap epochs

How a release that changes what pkgproxy keeps on disk reaches machines that run an older one, and how they go back. Part of the pkgproxy design, whose index says which file holds each § number.

25. Upgrades, reverts and snap epochs

The snap keeps its cache in $SNAP_COMMON, which every revision of the snap shares: snapd neither copies it on a refresh nor restores it on a revert. A release that changes the format of what is there must therefore keep working with the revision before it, which may run on the same files again after a snap revert, and the snap declares the change with an epoch, so that snapd knows which revisions can read what.

25.1 What snapd checks

An epoch is a list of formats a revision reads and the format it writes. epoch: 1* reads 0 and 1, and writes 1; epoch: 1 reads and writes 1 alone; a snap with no epoch has epoch 0. snapd’s snapstate.checkEpochs accepts a new revision only if it reads the format the installed one writes. It runs for every install and refresh:

  • from the store, which offers a device only revisions it can take, and steps a device that skipped releases through each N* revision in turn;
  • with --revision or --channel, which could otherwise reach an old revision;
  • for a local file installed with --dangerous, which fails with “cannot refresh “pkgproxy” to local snap with epoch 0, because it can’t read the current epoch of 1*“.

snapstate.RevertToRevision checks no epoch: snap revert, and the undo of a refresh that failed, go back to the previous revision whatever it reads. An epoch keeps a machine from going back by any other way, but the release before must still find a cache it can use after a revert (§25.3).

25.2 Epochs of the cache

The epochs are formats of $SNAP_COMMON/cache:

  • epoch 0, pkgproxy 0.11 and earlier: the metadata of each cached file in objects/<key>.meta.json beside it;
  • epoch 1: the metadata in the file’s user.pkgproxy.meta extended attribute (§7.1), so that one rename switches a body and its metadata together.

The snap declares epoch: 1*: it reads both, and what it writes, the attribute and the .meta.json file, is still epoch 0 as well as epoch 1.

25.3 Going back keeps the cache

fslocal writes each object’s metadata to its attribute and to its .meta.json file, which pkgproxy 0.11 reads and nothing else needs. A revert to 0.11 then finds every object it would have written itself. Newer releases cache no apt file with a path segment that ends in .meta.json, which 0.11 kept where another file’s .meta.json file is (§7.1); what 0.11 cached so is not read.

The .meta.json file never describes another body than its file’s. Commit removes the old one before it renames the new body into place, and writes the new one after; a crash in between leaves an object without a .meta.json file, which 0.11 fetches again. UpdateMeta replaces it after the attribute, with a rename; a crash in between leaves the one before, for the same body. A failure to write it fails neither: only 0.11 would miss it.

Back on the newer release, what 0.11 wrote reads right. A file 0.11 committed is a new file without the attribute, which takes its metadata from its .meta.json file. A file 0.11 revalidated keeps the attribute of before, older than its .meta.json file, and is revalidated again sooner than it need be.

Keeping the .meta.json files in $SNAP_DATA, which snapd copies on a refresh and restores on a revert, would not keep the cache: the bodies stay in $SNAP_COMMON, so a revert would bring back the metadata of apt indexes the newer release has since replaced, the mismatch the attribute is there to prevent; and every refresh would copy them all.

25.4 The post-refresh migration

pkgproxy -migrate-cache gives the attribute to every file under -cache-dir that has only a .meta.json file (fslocal.Store.MigrateSidecars), and keeps the .meta.json files. The snap’s post-refresh hook runs it, and writes what it says to $SNAP_DATA/migrate-cache.log, since snapd keeps no output of a hook that succeeds.

The hook must never fail: snapd undoes a refresh whose post-refresh hook fails, and puts back the revision before, which may be 0.11. It ignores the command’s exit status, and the command stops after -migrate-cache-timeout, two minutes by default, well within the ten minutes snapd gives a hook. Nothing depends on the migration finishing: a file it did not reach reads its .meta.json file. It may run while the daemon serves: it sets an attribute only where there is none (XATTR_CREATE), on the file it opened, so one that a Commit or UpdateMeta sets meanwhile stays, and a body replaced meanwhile takes the attribute with it.

Outside the snap, pkgproxy -migrate-cache is there to run by hand; pkgproxy works the same without it.

25.5 Testing the migration

-cache-metadata=meta-json (the snap option cache-metadata) makes the stores write as 0.11 did, the .meta.json file alone (fslocal.Store.SidecarOnly), and read it before the attribute, which they no longer update. It makes a cache of epoch 0 with the confined snap, without 0.11 from the store: the spread task tests/install/migrate-meta makes one, refreshes, and checks that every file has its attribute and still its .meta.json file, that the log counts them, and that a copy of the snap repacked with epoch 0 is refused. It is for tests alone: it gives up the atomic switch of a body with its metadata.

25.6 Retiring a format

A later release can drop epoch 0 by declaring plain epoch: 1: no longer writing nor reading the .meta.json files, and removing them. The store offers it only to devices that run a 1* revision, so the migration of §25.4 has run on each of them, and a revert from it lands on a 1* revision, which reads the attribute. A device on 0.11 that skips releases is stepped through the newest 1* revision first.

A further change of format takes the next epoch the same way: a 2* release that reads 1 and writes 2, and later a plain 2.