patchshuttle 0.1.0a2__py3-none-any.whl

patchshuttle/operations.py

@@ -0,0 +1,292 @@
+"""Project-level manual recovery operations."""
+
+from __future__ import annotations
+
+import stat
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from patchshuttle.backup import (
+    BackupStatus,
+    load_completed_backup,
+    update_loaded_backup,
+)
+from patchshuttle.errors import ExecutionError, ExecutionErrorCode, JobError
+from patchshuttle.logging import (
+    ManualRollbackLogRecord,
+    RunLogData,
+    current_run_clock,
+    write_run_log,
+)
+from patchshuttle.models import Job, JobKind
+from patchshuttle.parser import load_job
+from patchshuttle.planner import normalized_job_hash
+from patchshuttle.registry import get_job, load_registry, update_registry
+from patchshuttle.rollback import RollbackResult, rollback_completed_backup
+from patchshuttle.runner import acquire_workspace_lock
+from patchshuttle.workspace import Workspace
+
+
+@dataclass(frozen=True, slots=True)
+class ManualRollbackResult:
+    """A verified successful user-requested rollback."""
+
+    job_id: str
+    job_hash: str
+    backup_path: Path
+    restored_files: tuple[PurePosixPath, ...]
+    removed_files: tuple[PurePosixPath, ...]
+    removed_directories: tuple[PurePosixPath, ...]
+    log_path: Path
+
+
+def rollback_job(
+    workspace: Workspace,
+    job_id: str,
+    *,
+    approved: bool = False,
+) -> ManualRollbackResult:
+    """Safely restore one completed patch from its retained manifest."""
+
+    if not approved:
+        raise ExecutionError(
+            ExecutionErrorCode.APPROVAL_REQUIRED,
+            "explicit approval is required before a completed job is rolled back",
+            item_id=job_id,
+        )
+    clock = current_run_clock(workspace)
+    with acquire_workspace_lock(workspace):
+        registry = load_registry(workspace)
+        record = get_job(registry, job_id)
+        if record.kind != JobKind.PATCH.value:
+            raise ExecutionError(
+                ExecutionErrorCode.ROLLBACK_FAILED,
+                "only a completed patch job can be rolled back",
+                item_id=job_id,
+                rollback_succeeded=False,
+            )
+        if not record.completed or record.backup_reference is None:
+            raise ExecutionError(
+                ExecutionErrorCode.ROLLBACK_FAILED,
+                "job does not have a completed backup available for manual rollback",
+                item_id=job_id,
+                rollback_succeeded=False,
+            )
+        job, archived = _find_archived_job(
+            workspace,
+            job_id=job_id,
+            job_hash=record.job_hash,
+            preferred=record.archived_job_copy,
+        )
+        backup = load_completed_backup(
+            workspace,
+            record.backup_reference,
+            job_id=job_id,
+            job_hash=record.job_hash,
+        )
+        try:
+            rollback = rollback_completed_backup(workspace, backup)
+            if not rollback.success:
+                update_loaded_backup(
+                    backup,
+                    BackupStatus.ROLLBACK_FAILED,
+                    failure_code=ExecutionErrorCode.ROLLBACK_FAILED,
+                )
+                error = ExecutionError(
+                    ExecutionErrorCode.ROLLBACK_FAILED,
+                    "manual rollback left one or more transaction paths unresolved",
+                    item_id=job_id,
+                    path=rollback.unresolved[0].as_posix(),
+                    backup_path=backup.path,
+                    rollback_succeeded=False,
+                )
+                _record_failed_rollback(
+                    workspace,
+                    registry,
+                    job,
+                    record.job_hash,
+                    archived,
+                    clock,
+                    backup.path,
+                    rollback,
+                    error,
+                )
+                raise error
+        except ExecutionError as error:
+            if error.log_path is None:
+                _record_failed_rollback(
+                    workspace,
+                    registry,
+                    job,
+                    record.job_hash,
+                    archived,
+                    clock,
+                    backup.path,
+                    RollbackResult((), (), ()),
+                    error,
+                )
+            raise
+
+        update_loaded_backup(backup, BackupStatus.ROLLED_BACK)
+        log_record = ManualRollbackLogRecord(
+            status="SUCCESS",
+            backup_path=backup.path,
+            restored_files=rollback.restored_files,
+            removed_files=rollback.removed_files,
+            removed_directories=rollback.removed_directories,
+        )
+        log_path = write_run_log(
+            RunLogData(
+                workspace=workspace,
+                job=job,
+                job_hash=record.job_hash,
+                clock=clock,
+                result="ROLLED_BACK",
+                exit_code=0,
+                failure_stage=None,
+                failure_code=None,
+                archived_job_path=archived,
+                manual_rollback=log_record,
+            )
+        )
+        update_registry(
+            workspace,
+            registry,
+            job_id=job_id,
+            job_hash=record.job_hash,
+            kind=JobKind.PATCH,
+            occurred_at=clock.iso_timestamp,
+            result="ROLLED_BACK",
+            backup_path=backup.path,
+            rollback_state="SUCCESS",
+            archived_job_path=archived,
+            completed=False,
+            reset_completed=True,
+        )
+        return ManualRollbackResult(
+            job_id=job_id,
+            job_hash=record.job_hash,
+            backup_path=backup.path,
+            restored_files=rollback.restored_files,
+            removed_files=rollback.removed_files,
+            removed_directories=rollback.removed_directories,
+            log_path=log_path,
+        )
+
+
+def _record_failed_rollback(
+    workspace: Workspace,
+    registry,
+    job: Job,
+    job_hash: str,
+    archived: Path,
+    clock,
+    backup_path: Path,
+    rollback: RollbackResult,
+    error: ExecutionError,
+) -> None:
+    log_path = write_run_log(
+        RunLogData(
+            workspace=workspace,
+            job=job,
+            job_hash=job_hash,
+            clock=clock,
+            result="ROLLBACK_FAILED",
+            exit_code=8,
+            failure_stage="ROLLBACK",
+            failure_code=(error.cause_code or error.code).value,
+            archived_job_path=archived,
+            error=error,
+            manual_rollback=ManualRollbackLogRecord(
+                status="FAILED",
+                backup_path=backup_path,
+                restored_files=rollback.restored_files,
+                removed_files=rollback.removed_files,
+                removed_directories=rollback.removed_directories,
+                unresolved=rollback.unresolved,
+            ),
+        )
+    )
+    update_registry(
+        workspace,
+        registry,
+        job_id=job.id,
+        job_hash=job_hash,
+        kind=JobKind.PATCH,
+        occurred_at=clock.iso_timestamp,
+        result="ROLLBACK_FAILED",
+        backup_path=backup_path,
+        rollback_state="FAILED",
+        archived_job_path=archived,
+        completed=False,
+    )
+    error.log_path = log_path
+
+
+def _find_archived_job(
+    workspace: Workspace,
+    *,
+    job_id: str,
+    job_hash: str,
+    preferred: str,
+) -> tuple[Job, Path]:
+    candidates: list[Path] = []
+    preferred_path = _safe_archive_path(workspace, preferred)
+    if preferred_path is not None:
+        candidates.append(preferred_path)
+    for directory_name in ("applied", "failed"):
+        directory = workspace.patches_dir / directory_name
+        try:
+            paths = sorted(
+                directory.glob(f"{job_id}_*_{job_hash[:8]}.psh.yaml"),
+                reverse=True,
+            )
+        except OSError:
+            paths = []
+        candidates.extend(path for path in paths if path not in candidates)
+    for path in candidates:
+        try:
+            metadata = path.lstat()
+            if not stat.S_ISREG(metadata.st_mode) or path.is_symlink():
+                continue
+            job = load_job(
+                path,
+                max_bytes=workspace.config.execution.max_job_bytes,
+            )
+        except (OSError, JobError, ValueError):
+            continue
+        if (
+            job.id == job_id
+            and job.kind is JobKind.PATCH
+            and normalized_job_hash(job) == job_hash
+        ):
+            return job, path
+    raise ExecutionError(
+        ExecutionErrorCode.ROLLBACK_FAILED,
+        "an intact archived copy of the completed job was not found",
+        item_id=job_id,
+        rollback_succeeded=False,
+    )
+
+
+def _safe_archive_path(workspace: Workspace, value: str) -> Path | None:
+    relative = PurePosixPath(value)
+    if (
+        relative.is_absolute()
+        or "\\" in value
+        or len(relative.parts) != 3
+        or relative.parts[0] != "patches"
+        or relative.parts[1] not in {"applied", "failed"}
+        or any(part in {"", ".", ".."} for part in relative.parts)
+    ):
+        return None
+    path = workspace.root.joinpath(*relative.parts)
+    try:
+        if path.resolve() != path.absolute():
+            return None
+    except OSError:
+        return None
+    return path
+
+
+__all__ = ["ManualRollbackResult", "rollback_job"]

patchshuttle/parser.py

@@ -0,0 +1,243 @@
+"""Safe loading and structural validation for ``.psh.yaml`` jobs."""
+
+from __future__ import annotations
+
+import json
+import re
+import stat
+from collections.abc import Mapping
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+from yaml.nodes import MappingNode, Node, ScalarNode, SequenceNode
+from yaml.tokens import AliasToken, AnchorToken
+
+from patchshuttle.errors import JobError, JobErrorCode
+from patchshuttle.models import Job
+
+DEFAULT_MAX_JOB_BYTES = 2_000_000
+_CANONICAL_EXTENSION = ".psh.yaml"
+_STRING_TAG = "tag:yaml.org,2002:str"
+_SAFE_STANDARD_TAGS = frozenset(
+    tag for tag in yaml.SafeLoader.yaml_constructors if isinstance(tag, str)
+)
+_PLAIN_PATH_SEGMENT = re.compile(r"[A-Za-z_][A-Za-z0-9_-]*")
+
+
+def load_job(
+    path: str | PathLike[str],
+    *,
+    max_bytes: int = DEFAULT_MAX_JOB_BYTES,
+) -> Job:
+    """Load one canonical UTF-8 YAML file and return a validated immutable job."""
+
+    if type(max_bytes) is not int or max_bytes <= 0:
+        raise ValueError("max_bytes must be a positive integer")
+
+    job_path = Path(path)
+    if not job_path.name.endswith(_CANONICAL_EXTENSION):
+        raise JobError(
+            JobErrorCode.JOB_EXTENSION_INVALID,
+            f"job filename must end with {_CANONICAL_EXTENSION}",
+        )
+
+    try:
+        file_stat = job_path.stat()
+    except FileNotFoundError as exc:
+        raise JobError(
+            JobErrorCode.JOB_FILE_NOT_FOUND,
+            "job file was not found",
+        ) from exc
+    except OSError as exc:
+        raise JobError(
+            JobErrorCode.JOB_FILE_READ_FAILED,
+            "job file metadata could not be read",
+        ) from exc
+
+    if not stat.S_ISREG(file_stat.st_mode):
+        raise JobError(
+            JobErrorCode.JOB_FILE_NOT_REGULAR,
+            "job path must identify a regular file",
+        )
+    if file_stat.st_size > max_bytes:
+        raise JobError(
+            JobErrorCode.JOB_SIZE_LIMIT_EXCEEDED,
+            f"job file exceeds the {max_bytes}-byte input limit",
+        )
+
+    try:
+        raw = job_path.read_bytes()
+    except FileNotFoundError as exc:
+        raise JobError(
+            JobErrorCode.JOB_FILE_NOT_FOUND,
+            "job file was not found",
+        ) from exc
+    except OSError as exc:
+        raise JobError(
+            JobErrorCode.JOB_FILE_READ_FAILED,
+            "job file could not be read",
+        ) from exc
+
+    if len(raw) > max_bytes:
+        raise JobError(
+            JobErrorCode.JOB_SIZE_LIMIT_EXCEEDED,
+            f"job file exceeds the {max_bytes}-byte input limit",
+        )
+
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise JobError(
+            JobErrorCode.JOB_ENCODING_INVALID,
+            "job file must be valid UTF-8 text",
+        ) from exc
+
+    return validate_job(_load_yaml(text))
+
+
+def validate_job(value: object) -> Job:
+    """Validate mapping-like data with the same models used by YAML jobs."""
+
+    if isinstance(value, Job):
+        return value
+    if not isinstance(value, Mapping):
+        raise JobError(
+            JobErrorCode.JOB_ROOT_INVALID,
+            "job document root must be a mapping",
+            field_path="$",
+        )
+
+    try:
+        return Job.model_validate(value)
+    except ValidationError as exc:
+        first_error = exc.errors(include_url=False)[0]
+        raise JobError(
+            JobErrorCode.JOB_SCHEMA_INVALID,
+            str(first_error["msg"]),
+            field_path=_format_validation_path(first_error["loc"]),
+        ) from exc
+
+
+def _load_yaml(text: str) -> Mapping[str, Any]:
+    try:
+        _reject_references(text)
+        node = yaml.compose(text, Loader=yaml.SafeLoader)
+    except JobError:
+        raise
+    except (yaml.YAMLError, RecursionError) as exc:
+        raise _yaml_syntax_error(exc) from exc
+
+    if node is None:
+        raise JobError(
+            JobErrorCode.JOB_ROOT_INVALID,
+            "job document root must be a mapping",
+            field_path="$",
+        )
+
+    _validate_node(node, path="$")
+
+    try:
+        data = yaml.safe_load(text)
+    except (yaml.YAMLError, RecursionError) as exc:
+        raise _yaml_syntax_error(exc) from exc
+
+    if not isinstance(data, Mapping):
+        raise JobError(
+            JobErrorCode.JOB_ROOT_INVALID,
+            "job document root must be a mapping",
+            field_path="$",
+        )
+    return data
+
+
+def _reject_references(text: str) -> None:
+    for token in yaml.scan(text, Loader=yaml.SafeLoader):
+        if isinstance(token, AnchorToken):
+            raise JobError(
+                JobErrorCode.YAML_ANCHOR_FORBIDDEN,
+                "YAML anchors are not allowed",
+                field_path="$",
+                line=token.start_mark.line + 1,
+                column=token.start_mark.column + 1,
+            )
+        if isinstance(token, AliasToken):
+            raise JobError(
+                JobErrorCode.YAML_ALIAS_FORBIDDEN,
+                "YAML aliases are not allowed",
+                field_path="$",
+                line=token.start_mark.line + 1,
+                column=token.start_mark.column + 1,
+            )
+
+
+def _validate_node(node: Node, *, path: str) -> None:
+    if node.tag not in _SAFE_STANDARD_TAGS:
+        raise JobError(
+            JobErrorCode.YAML_TAG_FORBIDDEN,
+            "custom YAML tags are not allowed",
+            field_path=path,
+            line=node.start_mark.line + 1,
+            column=node.start_mark.column + 1,
+        )
+
+    if isinstance(node, MappingNode):
+        seen: set[str] = set()
+        for key_node, value_node in node.value:
+            if not isinstance(key_node, ScalarNode) or key_node.tag != _STRING_TAG:
+                raise JobError(
+                    JobErrorCode.YAML_MAPPING_KEY_INVALID,
+                    "YAML mapping keys must be strings",
+                    field_path=path,
+                    line=key_node.start_mark.line + 1,
+                    column=key_node.start_mark.column + 1,
+                )
+
+            key = key_node.value
+            child_path = _append_field(path, key)
+            if key in seen:
+                raise JobError(
+                    JobErrorCode.YAML_DUPLICATE_KEY,
+                    f"duplicate mapping key {key!r}",
+                    field_path=child_path,
+                    line=key_node.start_mark.line + 1,
+                    column=key_node.start_mark.column + 1,
+                )
+            seen.add(key)
+            _validate_node(value_node, path=child_path)
+
+    elif isinstance(node, SequenceNode):
+        for index, item in enumerate(node.value):
+            _validate_node(item, path=f"{path}[{index}]")
+
+
+def _yaml_syntax_error(exc: BaseException) -> JobError:
+    mark = getattr(exc, "problem_mark", None) or getattr(exc, "context_mark", None)
+    return JobError(
+        JobErrorCode.YAML_INVALID,
+        "job file contains invalid YAML syntax",
+        field_path="$",
+        line=mark.line + 1 if mark is not None else 1,
+        column=mark.column + 1 if mark is not None else 1,
+    )
+
+
+def _format_validation_path(location: tuple[int | str, ...]) -> str:
+    path = "$"
+    for part in location:
+        if isinstance(part, int):
+            path = f"{path}[{part}]"
+        else:
+            path = _append_field(path, str(part))
+    return path
+
+
+def _append_field(path: str, field: str) -> str:
+    if _PLAIN_PATH_SEGMENT.fullmatch(field):
+        return f"{path}.{field}"
+    return f"{path}[{json.dumps(field, ensure_ascii=False)}]"
+
+
+__all__ = ["DEFAULT_MAX_JOB_BYTES", "load_job", "validate_job"]