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
--revisionor--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.jsonbeside it; - epoch 1: the metadata in the file’s
user.pkgproxy.metaextended 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.