362 lines
18 KiB
Python
362 lines
18 KiB
Python
"""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: ('<mistergamedescription><rbf>' + self.rbf[:-4] +
|
|
'</rbf><setname>coco3plus</setname></mistergamedescription>').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</setname>', b'other</setname>'),
|
|
original.replace(self.rbf[:-4].encode(), b'_Computer/other'),
|
|
original.replace(b'</rbf>', b'</rbf><rbf>other</rbf>')):
|
|
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()
|