"""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 hashlib 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' rbf_data = b'new bitstream fixture\n' digest = hashlib.sha256(rbf_data).hexdigest() self.rbf = '_Computer/.coco3plus/' + digest[:12] + '/coco3plus.rbf' contents = { # Deliberately put the launcher first: manifest ordering cannot activate it early. self.launcher: ('' + self.rbf[:-4] + 'coco3plus').encode(), self.boot0: b'new boot0 fixture\n', self.config: installer.default_config(False), self.boot1: b'new boot1 fixture\n', self.rbf: rbf_data, } 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') # Synthetic bytes are accepted ONLY through per-test patched identities. # These fixtures are not original ROMs and never leave disposable storage. boot = {Path(name).name: (len(contents[name]), entries[name]['sha256']) for name in (self.boot0, self.boot1)} boot_patch = patch.object(installer, 'BOOT', boot) boot_patch.start() self.addCleanup(boot_patch.stop) self.manifest = dict(format=1, public_package=False, roms_required_separately=False, ssc_included=False, files=entries, rbf_sha256=digest) (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 write_manifest(self): (self.package / 'manifest.json').write_text(json.dumps(self.manifest)) def replace_member(self, name, content): path = self.package / 'fat' / name path.parent.mkdir(parents=True, exist_ok=True) path.write_bytes(content) self.manifest['files'][name] = dict(bytes=len(content), sha256=installer.sha(path), policy='create-if-missing' if name == self.config else 'backup-and-replace') def add_synthetic_ssc(self): identities = {} for name in installer.SSC: content = ('synthetic SSC fixture ' + name).encode() path = 'games/coco3plus/' + name self.replace_member(path, content) identities[name] = (len(content), self.manifest['files'][path]['sha256']) ssc_patch = patch.object(installer, 'SSC', identities) ssc_patch.start() self.addCleanup(ssc_patch.stop) self.manifest['ssc_included'] = True self.replace_member(self.config, installer.default_config(True)) for index, name in ((4, 'pic-7040-510.bin'), (5, 'sp0256-al2.bin')): self.replace_member('config/coco3plus.f' + str(index), ('/media/fat/games/coco3plus/' + name).encode().ljust(1024, b'\0')) def assert_rejected_before_target(self): self.write_manifest() target = DisposableTarget(self.device, self.package) with self.assertRaises(RuntimeError): self.install(target) self.assertEqual(target.events, []) self.assertFalse((self.package / 'install-receipt.json').exists()) def test_missing_rbf_boot_or_config_rejected_before_target_access(self): for name in (self.rbf, self.boot0, self.boot1, self.config): with self.subTest(name=name): entry = self.manifest['files'].pop(name) self.assert_rejected_before_target() self.manifest['files'][name] = entry def test_missing_ssc_rom_or_path_record_rejected_before_target_access(self): self.add_synthetic_ssc() for name in ('games/coco3plus/pic-7040-510.bin', 'games/coco3plus/sp0256-al2.bin', 'config/coco3plus.f4', 'config/coco3plus.f5'): with self.subTest(name=name): entry = self.manifest['files'].pop(name) self.assert_rejected_before_target() self.manifest['files'][name] = entry def test_complete_synthetic_ssc_package_validates(self): self.add_synthetic_ssc() self.write_manifest() checked = installer.validated_manifest(self.package) self.assertTrue(checked['ssc_included']) def test_contradictory_launcher_or_rbf_digest_rejected_before_target(self): original = (self.package / 'fat' / self.launcher).read_bytes() for content in (original.replace(b'coco3plus', b'other'), original.replace(self.rbf[:-4].encode(), b'_Computer/other'), original.replace(b'', b'other')): with self.subTest(content=content): self.replace_member(self.launcher, content) self.assert_rejected_before_target() self.replace_member(self.launcher, original) # Keep the addressed prefix so this specifically checks full digest agreement. digest = self.manifest['rbf_sha256'] self.manifest['rbf_sha256'] = digest[:12] + ('0' if digest[12] != '0' else '1') + digest[13:] self.assert_rejected_before_target() def test_bad_flags_digests_and_rom_identity_rejected_before_target(self): for field, value in (('format', 2), ('format', True), ('public_package', True), ('public_package', 0), ('roms_required_separately', True), ('ssc_included', None), ('rbf_sha256', 'not-a-digest')): with self.subTest(field=field, value=value): original = self.manifest[field] self.manifest[field] = value self.assert_rejected_before_target() self.manifest[field] = original original_digest = self.manifest['files'][self.boot0]['sha256'] self.manifest['files'][self.boot0]['sha256'] = 'bad-file-digest' self.assert_rejected_before_target() self.manifest['files'][self.boot0]['sha256'] = original_digest self.replace_member(self.boot0, b'wrong synthetic boot identity') self.assert_rejected_before_target() def test_ssc_wrong_path_or_rom_identity_rejected_before_target(self): self.add_synthetic_ssc() self.replace_member('config/coco3plus.f4', b'/media/fat/games/wrong/pic.bin'.ljust(1024, b'\0')) self.assert_rejected_before_target() self.replace_member('config/coco3plus.f4', b'/media/fat/games/coco3plus/pic-7040-510.bin'.ljust(1024, b'\0')) self.replace_member('games/coco3plus/sp0256-al2.bin', b'wrong synthetic speech identity') self.assert_rejected_before_target() 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['load_command_sent']) 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['load_command_sent']) self.assertIs(receipt['startup_observed'], False) self.assertNotIn('loaded', receipt) 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_load_command_failure_is_uncertain_and_does_not_claim_startup(self): target = DisposableTarget(self.device, self.package) with patch.object(target, 'load', side_effect=OSError('Unconfirmed command write')): with self.assertRaisesRegex(OSError, 'Unconfirmed command write'): self.install(target, load=True) receipt = json.loads((self.package / 'install-receipt.json').read_text()) self.assertEqual(receipt['status'], 'failed') self.assertTrue(receipt['launcher_activated']) self.assertIsNone(receipt['load_command_sent']) self.assertIs(receipt['startup_observed'], False) self.assertNotIn('loaded', receipt) 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()