Harden release packaging and recoverable installation after review

This commit is contained in:
bholman committed 2026-11-18 16:26:25 -07:00
1 parent cb40fed3b9
commit 8088c1fbf6
14 files changed
+933 -101

No files matched your search

+238
View File
@@ -0,0 +1,238 @@
"""Check launcher-last installation and recoverable interruption on a mock target.
Copyright (c) 2026 Brian K. Holman. BSD-3-Clause; see LICENSES/.
The target is a disposable local filesystem, never an SSH/device connection.
"""
import json
import os
from pathlib import Path, PurePosixPath
import shutil
import sys
import tempfile
import unittest
from unittest.mock import patch
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tools'))
import install_mister as installer
class DisposableTarget:
def __init__(self, root, package, *, interrupt_on=None, fail_preflight=False):
self.root = root
self.package = package
self.interrupt_on = interrupt_on
self.fail_preflight = fail_preflight
self.events = []
def local(self, remote):
relative = PurePosixPath(remote).relative_to('/media/fat')
return self.root.joinpath(*relative.parts)
def preflight(self):
self.events.append('preflight')
if self.fail_preflight:
raise OSError('Deliberate mock preflight failure')
return 'Disposable target only\n'
def prepare(self, stage, backup):
# The recovery plan must already be durable before this first target write.
receipt = json.loads((self.package / 'install-receipt.json').read_text())
assert receipt['stage'] == stage and receipt['backup'] == backup
assert receipt['phase'] == 'staging'
assert Path(receipt['receipt']).is_file()
self.events.append('prepare')
self.local(stage).mkdir(parents=True)
self.local(backup).mkdir(parents=True)
def upload(self, fat, stage):
self.events.append('upload')
shutil.copytree(fat, self.local(stage) / 'fat')
def verify(self, files):
self.events.append('verify')
for name, digest in files.items():
assert installer.sha(self.local(name)) == digest, name
def enter_menu(self):
self.events.append('menu')
def install_file(self, source, destination, backup, entry, temporary):
if self.interrupt_on and destination.endswith('/' + self.interrupt_on):
self.events.append('interrupted')
raise KeyboardInterrupt('Deliberate interruption before launcher activation')
target = self.local(destination)
target.parent.mkdir(parents=True, exist_ok=True)
if target.exists():
if entry['policy'] == 'create-if-missing':
self.events.append('preserved:' + destination)
return 'preserved'
old = self.local(backup)
old.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(target, old)
pending = self.local(temporary)
assert not pending.exists()
shutil.copyfile(self.local(source), pending)
assert installer.sha(pending) == entry['sha256']
os.replace(pending, target)
assert installer.sha(target) == entry['sha256']
self.events.append('installed:' + destination)
return 'installed'
def activate_launcher(self, source, destination, backup, entry, temporary):
self.events.append('activate')
return self.install_file(source, destination, backup, entry, temporary)
def sync(self):
self.events.append('sync')
def load(self):
self.events.append('load')
class InstallerTransactionTests(unittest.TestCase):
def setUp(self):
self.temporary = tempfile.TemporaryDirectory(dir=ROOT / 'build')
self.addCleanup(self.temporary.cleanup)
self.base = Path(self.temporary.name)
self.package = self.base / 'package'
self.device = self.base / 'device'
self.package.mkdir()
self.device.mkdir()
self.launcher = installer.LAUNCHER
self.boot0 = 'games/coco3plus/boot0.rom'
self.boot1 = 'games/coco3plus/boot1.rom'
self.config = 'config/coco3plus_v51.CFG'
self.rbf = '_Computer/.coco3plus/fixture/core.rbf'
contents = {
# Deliberately put the launcher first: manifest ordering cannot activate it early.
self.launcher: b'new launcher fixture\n',
self.boot0: b'new boot0 fixture\n',
self.config: b'new default configuration\n',
self.boot1: b'new boot1 fixture\n',
self.rbf: b'new bitstream fixture\n',
}
entries = {}
for name, data in contents.items():
path = self.package / 'fat' / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(data)
entries[name] = dict(
bytes=len(data), sha256=installer.sha(path),
policy='create-if-missing' if name == self.config else 'backup-and-replace')
self.manifest = dict(files=entries, rbf_sha256=entries[self.rbf]['sha256'])
(self.package / 'manifest.json').write_text(json.dumps(self.manifest))
for name, data in ((self.launcher, b'old launcher remains selectable\n'),
(self.boot0, b'old boot0 recoverable\n'),
(self.config, b'owner saved configuration\n')):
path = self.device / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(data)
def install(self, target, stamp='fixture-attempt', load=False):
return installer.install_release(
self.package, 'disposable.invalid', load=load, target=target, stamp=stamp)
def test_support_interruption_keeps_old_launcher_and_recovery_evidence(self):
target = DisposableTarget(self.device, self.package, interrupt_on=self.boot1)
original_launcher = (self.device / self.launcher).read_bytes()
original_boot0 = (self.device / self.boot0).read_bytes()
with self.assertRaises(KeyboardInterrupt):
self.install(target, load=True)
receipt = json.loads((self.package / 'install-receipt.json').read_text())
self.assertEqual(receipt['status'], 'failed')
self.assertEqual(receipt['phase'], 'supporting-assets')
self.assertEqual(receipt['active_file'], self.boot1)
self.assertIn(self.launcher, receipt['planned_files'])
self.assertFalse(receipt['activation_attempted'])
self.assertIs(receipt['launcher_activated'], False)
self.assertFalse(receipt['loaded'])
self.assertEqual(receipt['error']['type'], 'KeyboardInterrupt')
self.assertEqual((self.device / self.launcher).read_bytes(), original_launcher)
self.assertNotIn('activate', target.events)
self.assertNotIn('load', target.events)
self.assertEqual((self.device / self.boot0).read_bytes(),
(self.package / 'fat' / self.boot0).read_bytes())
self.assertEqual(target.local(receipt['backup'] + '/' + self.boot0).read_bytes(),
original_boot0)
self.assertEqual(target.local(receipt['stage'] + '/fat/' + self.launcher).read_bytes(),
(self.package / 'fat' / self.launcher).read_bytes())
self.assertTrue(Path(receipt['receipt']).is_file())
self.assertIn(self.boot0, {item['path'] for item in receipt['completed_files']})
def test_success_installs_support_then_atomically_activates_and_preserves_config(self):
target = DisposableTarget(self.device, self.package)
original_launcher = (self.device / self.launcher).read_bytes()
original_config = (self.device / self.config).read_bytes()
receipt = self.install(target, load=True)
self.assertEqual(receipt['status'], 'complete')
self.assertTrue(receipt['launcher_activated'])
self.assertTrue(receipt['loaded'])
self.assertEqual((self.device / self.config).read_bytes(), original_config)
self.assertEqual((self.device / self.launcher).read_bytes(),
(self.package / 'fat' / self.launcher).read_bytes())
self.assertEqual(target.local(receipt['backup'] + '/' + self.launcher).read_bytes(),
original_launcher)
activation = target.events.index('activate')
for i, event in enumerate(target.events):
if event.startswith('installed:') and not event.endswith('/' + self.launcher):
self.assertLess(i, activation)
self.assertEqual(target.events[activation - 1], 'sync')
self.assertGreater(target.events.index('load'), activation)
self.assertFalse(target.local(receipt['launcher_temporary']).exists())
self.assertTrue(target.local(receipt['stage'] + '/fat/' + self.launcher).exists())
def test_preflight_failure_keeps_plan_and_does_not_mutate_target(self):
target = DisposableTarget(self.device, self.package, fail_preflight=True)
before = {p.relative_to(self.device): p.read_bytes()
for p in self.device.rglob('*') if p.is_file()}
with self.assertRaisesRegex(OSError, 'mock preflight failure'):
self.install(target)
receipt = json.loads((self.package / 'install-receipt.json').read_text())
self.assertEqual(receipt['status'], 'failed')
self.assertEqual(receipt['phase'], 'preflight')
self.assertEqual(target.events, ['preflight'])
self.assertFalse(target.local(receipt['stage']).exists())
self.assertEqual(before, {p.relative_to(self.device): p.read_bytes()
for p in self.device.rglob('*') if p.is_file()})
def test_failed_retry_preserves_prior_complete_receipt(self):
first = self.install(DisposableTarget(self.device, self.package), stamp='first')
original_receipt = Path(first['receipt']).read_bytes()
with self.assertRaises(OSError):
self.install(DisposableTarget(self.device, self.package, fail_preflight=True),
stamp='second')
failed = json.loads((self.package / 'install-receipt.json').read_text())
self.assertEqual(failed['status'], 'failed')
self.assertEqual(Path(first['receipt']).read_bytes(), original_receipt)
self.assertEqual(Path(failed['previous_receipt']).read_bytes(), original_receipt)
def test_remote_launcher_primitive_verifies_temporary_file_before_rename(self):
target = installer.OpenSshTarget('disposable.invalid', 'root')
source = '/media/fat/.coco3plus/stage/' + self.launcher
destination = '/media/fat/' + self.launcher
temporary = destination + '.fixture.tmp'
backup = '/media/fat/.coco3plus/backup/' + self.launcher
with patch.object(target, 'run', return_value='installed\n') as run:
result = target.activate_launcher(
source, destination, backup, self.manifest['files'][self.launcher], temporary)
self.assertEqual(result, 'installed')
script = run.call_args.args[0]
copy = 'cp ' + installer.q(source) + ' ' + installer.q(temporary)
check = 'sha256sum ' + installer.q(temporary)
rename = 'mv -f ' + installer.q(temporary) + ' ' + installer.q(destination)
self.assertLess(script.index(copy), script.index(check))
self.assertLess(script.index(check), script.index(rename))
self.assertNotIn('cp ' + installer.q(source) + ' ' + installer.q(destination) + '\n', script)
if __name__ == '__main__':
unittest.main()