import io import json import os import subprocess import xml.etree.ElementTree as ET import tarfile import tempfile import unittest from pathlib import Path from unittest.mock import patch import receive_external from archive import COMPONENTS from external_session import ArchiveFrameWriter, read_ack, write_header class ExternalReceiverTests(unittest.TestCase): def test_windows_preflight_requires_full_protocol_archive_capacity(self): required = receive_external.MAX_ARCHIVE_BYTES + 1024 * 1024 receive_external.check_capacity(required) with self.assertRaisesRegex(ValueError, "maximum 100 GiB archive"): receive_external.check_capacity(required - 1) def setUp(self): self.request = { "version": 1, "action": "release", "run_id": "301", "commit": "a" * 40, "descriptor_sha256": "b" * 64, } self.manifest = { "format": 1, "created_at": "2026-10-31T12:00:00+00:00", "git_revision": "c" * 40, "images": {"backend": {"configured": "backend:old", "image_id": "sha256:" + "d" * 64}}, "deployment_files": {"deploy/production/compose.yaml": "e" * 64}, "components": sorted(COMPONENTS), } def source_stream(self, context=None): archive_stream = io.BytesIO() with tarfile.open(fileobj=archive_stream, mode="w:gz") as archive: manifest_bytes = json.dumps(self.manifest, sort_keys=True).encode("utf-8") member = tarfile.TarInfo("manifest.json") member.size = len(manifest_bytes) archive.addfile(member, io.BytesIO(manifest_bytes)) for component in COMPONENTS: member = tarfile.TarInfo(component + "/") member.type = tarfile.DIRTYPE archive.addfile(member) payload = archive_stream.getvalue() stream = io.BytesIO() manifest_sha = write_header( stream, session_nonce="f" * 64, backup_id="backup-20261031T120000Z", manifest=self.manifest, context=context or {key: self.request[key] for key in ("action", "run_id", "commit", "descriptor_sha256")}, ) framed = ArchiveFrameWriter(stream) framed.write(payload) size, digest = framed.finish() stream.seek(0) return stream, manifest_sha, size, digest def test_verified_archive_is_atomically_published_before_ack(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) final = root / "backup-20261031T120000Z" stream, manifest_sha, size, digest = self.source_stream() ack = io.BytesIO() with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \ patch.object(receive_external, "check_private_acl") as acl_check: result = receive_external.receive_backup( stream, ack, repository=root, request=self.request ) self.assertEqual(result, {"backup_id": final.name, "archive_sha256": digest, "size": size}) self.assertTrue((final / "backup.tar.gz").is_file()) if os.name == "nt": for path in (final, final / "backup.tar.gz", final / "backup.tar.gz.sha256"): acl_check.assert_any_call(path) else: self.assertEqual((final / "backup.tar.gz").stat().st_mode & 0o777, 0o600) self.assertEqual((final / "backup.tar.gz.sha256").read_text(), f"{digest} backup.tar.gz\n") ack.seek(0) self.assertTrue(read_ack( ack, session_nonce="f" * 64, backup_id=final.name, size=size, archive_sha256=digest, manifest_sha256=manifest_sha, )["verified"]) def test_mismatched_release_binding_never_publishes_or_acks(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) final = root / "backup-20261031T120000Z" stream, _manifest_sha, _size, _digest = self.source_stream( context={"action": "release", "run_id": "999", "commit": "a" * 40, "descriptor_sha256": "b" * 64} ) ack = io.BytesIO() with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \ patch.object(receive_external, "check_private_acl"): with self.assertRaisesRegex(ValueError, "does not match"): receive_external.receive_backup(stream, ack, repository=root, request=self.request) self.assertFalse(final.exists()) self.assertEqual(ack.getvalue(), b"") def test_invalid_saved_stream_is_removed_without_publication(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) final = root / "backup-20261031T120000Z" stream, _manifest_sha, _size, _digest = self.source_stream() raw = bytearray(stream.getvalue()) raw[-1] ^= 1 ack = io.BytesIO() with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \ patch.object(receive_external, "check_private_acl"): with self.assertRaisesRegex(ValueError, "SHA-256"): receive_external.receive_backup(io.BytesIO(raw), ack, repository=root, request=self.request) self.assertFalse(final.exists()) self.assertEqual(list(root.iterdir()), []) self.assertEqual(ack.getvalue(), b"") def test_post_publish_acl_failure_removes_owned_final_without_ack(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) final = root / "backup-20261031T120000Z" stream, _manifest_sha, _size, _digest = self.source_stream() ack = io.BytesIO() def fail_published_archive(path): if path == final / "backup.tar.gz": raise ValueError("post-publish ACL failed") with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \ patch.object(receive_external, "check_private_acl", side_effect=fail_published_archive): with self.assertRaisesRegex(ValueError, "post-publish ACL failed"): receive_external.receive_backup(stream, ack, repository=root, request=self.request) self.assertFalse(final.exists()) self.assertEqual(list(root.iterdir()), []) self.assertEqual(ack.getvalue(), b"") def test_cleanup_refuses_a_replaced_or_reparse_directory(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) owned = root / "owned" final = root / "final" owned.mkdir() identity = receive_external._directory_identity(owned) owned.rename(root / "moved-owned") final.mkdir() with self.assertRaisesRegex(ValueError, "replaced backup directory"): receive_external._remove_owned_directory(final, identity) self.assertTrue(final.is_dir()) self.assertTrue((root / "moved-owned").is_dir()) if os.name != "nt": link = root / "link" link.symlink_to(final, target_is_directory=True) with self.assertRaisesRegex(ValueError, "real directory"): receive_external._remove_owned_directory(link, identity) self.assertTrue(final.is_dir()) def test_cleanup_refuses_unexpected_directory_contents(self): with tempfile.TemporaryDirectory() as directory: path = Path(directory) / "owned" path.mkdir() identity = receive_external._directory_identity(path) (path / "foreign-data").write_text("keep", encoding="utf-8") with self.assertRaisesRegex(ValueError, "unexpected backup content"): receive_external._remove_owned_directory(path, identity) self.assertEqual((path / "foreign-data").read_text(encoding="utf-8"), "keep") def test_target_requires_exact_local_git_exclude_rule(self): with tempfile.TemporaryDirectory() as directory: repository = Path(directory) exclude = repository / ".git/info/exclude" exclude.parent.mkdir(parents=True) exclude.write_text("/.backups/\n", encoding="utf-8") responses = [ type("Result", (), {"stdout": str(repository / ".git"), "returncode": 0})(), type("Result", (), { "stdout": f"{exclude}:1:/.backups/\t.backups/backup-id/backup.tar.gz\n", "returncode": 0, })(), ] with patch.object(receive_external, "_WINDOWS", False), \ patch.object(receive_external.subprocess, "run", side_effect=responses), \ patch.object(receive_external, "check_private_acl"): root, final = receive_external.check_repository_target( repository, "backup-id" ) self.assertEqual(root, repository / ".backups") self.assertEqual(final, root / "backup-id") def test_windows_path_guard_rejects_a_synthetic_non_d_destination(self): with tempfile.TemporaryDirectory() as directory: repository = Path(directory) with patch.object(receive_external, "_WINDOWS", True): with self.assertRaisesRegex(ValueError, r"restricted to D:\\Dev\\akyldash"): receive_external.check_repository_target(repository, "backup-id") def test_windows_acl_probe_does_not_inherit_credentials(self): result = type("Result", (), {"returncode": 0})() with patch.dict("os.environ", {"GITEA_TOKEN": "must-not-pass"}, clear=True), \ patch.object(receive_external.subprocess, "run", return_value=result) as run_mock: receive_external.check_private_acl(Path(r"D:\Dev\akyldash\.backups")) child_env = run_mock.call_args.kwargs["env"] self.assertNotIn("GITEA_TOKEN", child_env) self.assertEqual(child_env["AKYLDASH_ACL_PATH"], r"D:\Dev\akyldash\.backups") self.assertIn("System.IO.DriveInfo", run_mock.call_args.args[0][-1]) self.assertNotIn("Get-Volume", run_mock.call_args.args[0][-1]) self.assertIn("$acl.GetOwner(", run_mock.call_args.args[0][-1]) self.assertIn("$acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])", run_mock.call_args.args[0][-1]) self.assertIn("$rule.IdentityReference.Value", run_mock.call_args.args[0][-1]) self.assertNotIn(".Translate(", run_mock.call_args.args[0][-1]) self.assertIn("$aclOwner -notin $allowed", run_mock.call_args.args[0][-1]) def test_private_acl_rejects_an_unapproved_acl_owner(self): result = type("Result", (), {"returncode": 6})() with patch.object(receive_external.subprocess, "run", return_value=result) as run_mock: with self.assertRaisesRegex(ValueError, "PowerShell status 6"): receive_external.check_private_acl(Path(r"D:\Dev\akyldash\.backups")) command = run_mock.call_args.args[0][-1] self.assertIn("$acl.GetOwner(", command) self.assertIn("if ($aclOwner -notin $allowed) { exit 6 }", command) def test_destination_preflight_fails_before_opening_ssh(self): with tempfile.TemporaryDirectory() as directory, \ patch.object(receive_external.shutil, "which", return_value="ssh"), \ patch.object(receive_external, "check_repository_target", side_effect=ValueError("preflight failed")) as preflight, \ patch.object(receive_external.subprocess, "Popen") as popen: with self.assertRaisesRegex(ValueError, "preflight failed"): receive_external.run_release(self.request, repository=Path(directory)) with self.assertRaisesRegex(ValueError, "preflight failed"): receive_external.run_rollback(repository=Path(directory)) self.assertEqual(preflight.call_count, 2) self.assertTrue(all(call.args[1].startswith("preflight-") for call in preflight.call_args_list)) popen.assert_not_called() def test_status_response_accepts_only_the_fixed_prepared_tuple(self): response = {"schema_version": 1, "state": "prepared", "reason": None, "release": {"run_id": "302", "commit": "a" * 40, "descriptor_sha256": "b" * 64}} self.assertEqual(receive_external.validate_status_response(json.dumps(response).encode()), {"version": 1, "action": "release", **response["release"]}) response["reason"] = [] with self.assertRaises(ValueError): receive_external.validate_status_response(json.dumps(response).encode()) self.assertIsNone(receive_external.validate_status_response( b'{"schema_version":1,"state":"not_ready","reason":"already_applied","release":null}' )) with self.assertRaisesRegex(ValueError, "state"): receive_external.validate_status_response( json.dumps({**response, "state": "candidate"}).encode() ) def test_status_response_rejects_extra_or_duplicate_fields(self): payload = (b'{"schema_version":1,"state":"not_ready","reason":"recovery_journal",' b'"release":null,"extra":0}') with self.assertRaisesRegex(ValueError, "schema"): receive_external.validate_status_response(payload) with self.assertRaisesRegex(ValueError, "duplicate"): receive_external.validate_status_response( b'{"schema_version":1,"state":"not_ready","reason":"recovery_journal",' b'"release":null,"release":null}') def test_status_query_uses_only_fixed_command_and_non_forwarding_ssh(self): payload = (b'{"schema_version":1,"state":"not_ready",' b'"reason":"no_current_main_release","release":null}\n') process = type("Process", (), { "stdout": io.BytesIO(payload), "stderr": io.BytesIO(), "wait": lambda self, timeout: 0, })() with patch.object(receive_external.shutil, "which", return_value="ssh"), \ patch.object(receive_external.subprocess, "Popen", return_value=process) as popen: self.assertIsNone(receive_external.query_release_status()) command = popen.call_args.args[0] self.assertEqual(command[-2:], ["akyldash_release", receive_external.RELEASE_STATUS_COMMAND]) self.assertIn("ForwardAgent=no", command) self.assertIn("ClearAllForwardings=yes", command) self.assertEqual(popen.call_args.kwargs["stdin"], subprocess.DEVNULL) def test_once_only_prepares_and_separate_interactive_apply_requires_exact_confirmation(self): config = {"schema_version": 1, "enabled": False, "repository": str(receive_external.DEFAULT_REPOSITORY), "ssh_alias": receive_external.DEFAULT_DEPLOY_SSH_ALIAS} with tempfile.TemporaryDirectory() as directory: path = Path(directory) / "trigger.json" path.write_text(json.dumps(config), encoding="utf-8") with patch.object(receive_external, "_WINDOWS", True), \ patch.object(receive_external, "check_private_acl"), \ patch.object(receive_external, "query_release_status") as query, \ patch.object(receive_external, "run_release") as deploy, \ patch.object(receive_external, "PREPARED_STATE_FILE", Path(directory) / "prepared.json"): receive_external.run_release_once(config_file=path, prepared_file=Path(directory) / "prepared.json") query.assert_not_called() deploy.assert_not_called() config["enabled"] = True path.write_text(json.dumps(config), encoding="utf-8") prepared = {"version": 1, "action": "release", "run_id": "302", "commit": "a" * 40, "descriptor_sha256": "b" * 64} query.return_value = prepared receive_external.run_release_once(config_file=path, prepared_file=Path(directory) / "prepared.json") deploy.assert_not_called() self.assertEqual(receive_external.read_prepared_request(Path(directory) / "prepared.json"), prepared) with patch.object(receive_external.sys.stdin, "isatty", return_value=False): with self.assertRaisesRegex(ValueError, "interactive owner confirmation"): receive_external.apply_prepared_release( config_file=path, prepared_file=Path(directory) / "prepared.json", ) with patch.object(receive_external.sys.stdin, "isatty", return_value=True), \ patch.object(receive_external, "run_release") as apply: receive_external.apply_prepared_release( config_file=path, prepared_file=Path(directory) / "prepared.json", confirm=lambda prompt: f"APPLY {'a' * 40}", ) apply.assert_called_once_with( prepared, repository=receive_external.DEFAULT_REPOSITORY, ssh="ssh", ssh_alias="akyldash_release") def test_auto_apply_requires_a_prior_matching_prepared_poll_and_separate_gate(self): previous = {"version": 1, "action": "release", "run_id": "301", "commit": "a" * 40, "descriptor_sha256": "b" * 64} latest = {"version": 1, "action": "release", "run_id": "302", "commit": "c" * 40, "descriptor_sha256": "d" * 64} with tempfile.TemporaryDirectory() as directory: root = Path(directory) prepared_file = root / "prepared.json" trigger_file = root / "trigger.json" auto_file = root / "auto.json" with patch.object(receive_external, "check_private_acl"): receive_external.write_prepared_request(previous, prepared_file) with patch.object(receive_external, "load_trigger_config", return_value={"enabled": True, "repository": str(receive_external.DEFAULT_REPOSITORY), "ssh_alias": "akyldash_release"}), \ patch.object(receive_external, "load_auto_apply_config", return_value={"enabled": True}), \ patch.object(receive_external, "query_release_status", return_value=latest) as query, \ patch.object(receive_external, "run_release") as deploy: receive_external.run_auto_apply_once( config_file=trigger_file, auto_apply_file=auto_file, prepared_file=prepared_file, ) query.assert_called_once() deploy.assert_not_called() self.assertEqual(receive_external.read_prepared_request(prepared_file), latest) query.reset_mock() query.return_value = latest receive_external.run_auto_apply_once( config_file=trigger_file, auto_apply_file=auto_file, prepared_file=prepared_file, ) deploy.assert_called_once_with( latest, repository=receive_external.DEFAULT_REPOSITORY, ssh="ssh", ssh_alias="akyldash_release", ) def test_auto_apply_disabled_does_not_open_ssh(self): with patch.object(receive_external, "load_trigger_config", return_value={"enabled": True}), \ patch.object(receive_external, "load_auto_apply_config", return_value={"enabled": False}), \ patch.object(receive_external, "query_release_status") as query, \ patch.object(receive_external, "run_release") as deploy: receive_external.run_auto_apply_once() query.assert_not_called() deploy.assert_not_called() def test_windows_trigger_templates_are_fixed_and_disabled(self): root = Path(__file__).resolve().parents[1] / "deploy" config = json.loads((root / "windows-release-trigger.example.json").read_text(encoding="utf-8")) self.assertEqual(config, { "schema_version": 1, "enabled": False, "repository": r"D:\Dev\akyldash", "ssh_alias": "akyldash_release", }) task = ET.parse(root / "windows-release-trigger.example.xml").getroot() ns = {"t": "http://schemas.microsoft.com/windows/2004/02/mit/task"} self.assertEqual(task.findtext("t:Settings/t:Enabled", namespaces=ns), "false") self.assertEqual(task.findtext("t:Settings/t:MultipleInstancesPolicy", namespaces=ns), "IgnoreNew") self.assertEqual(task.findtext("t:Settings/t:StopIfGoingOnBatteries", namespaces=ns), "false") self.assertEqual(task.findtext("t:Principals/t:Principal/t:RunLevel", namespaces=ns), "LeastPrivilege") self.assertEqual( task.findtext("t:Actions/t:Exec/t:Arguments", namespaces=ns), '-B -E -s -S "C:\\Program Files\\Akyldash\\windows_release_launcher.py" --once', ) auto_config = json.loads((root / "windows-release-auto-apply.example.json").read_text(encoding="utf-8")) self.assertEqual(auto_config, {"schema_version": 1, "enabled": False}) auto_task = ET.parse(root / "windows-release-auto-apply.example.xml").getroot() self.assertEqual(auto_task.findtext("t:Settings/t:Enabled", namespaces=ns), "false") self.assertEqual(auto_task.findtext("t:Triggers/t:CalendarTrigger/t:Enabled", namespaces=ns), "false") self.assertEqual( auto_task.findtext("t:Actions/t:Exec/t:Arguments", namespaces=ns), '-B -E -s -S "C:\\Program Files\\Akyldash\\windows_release_launcher.py" --auto-apply-prepared', ) if __name__ == "__main__": unittest.main()