gitpane 1.0.0__py3-none-any.whl

gitpane/sequencer/replay_legacy.py

@@ -0,0 +1,253 @@
+"""Read what earlier GitPane versions left behind for Cherry-pick or Revert, so their anchor references can be retired without losing a backup.
+
+Earlier versions saved a journal and copies of the working files in a private folder before every Cherry-pick or
+Revert, and pinned the objects they saved with one reference per journal under refs/gitpane/replay-recovery/. The
+current version runs Git's own commands and writes none of this. Nothing here ever changes that folder: only the
+references are chosen for removal. The reference of a journal an earlier version left in the middle of a restoration
+is kept in every repository that holds it, including one moved or copied since the journal was written, because the
+objects it pins may be the only copy of that work outside the backup folder.
+
+This module has no Qt dependency beyond the location of the application's private data folder, and starts no process.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from dataclasses import dataclass
+
+from PySide6.QtCore import QStandardPaths
+
+from gitpane.config import REPLAY_RECORD_COUNT_LIMIT, REPLAY_RECORD_LIMIT_BYTES
+from gitpane.history.repository_value import validate_oid
+from gitpane.system.path_identity import canonical_path
+from gitpane.system.qt_folder import writable_folder
+
+LEGACY_REPLAY_STORE_BASENAME = "gitpane-replay-recovery"
+LEGACY_RECORD_BASENAME = "record.json"
+LEGACY_ANCHOR_REF_PREFIX = "refs/gitpane/replay-recovery/"
+LEGACY_RECORD_ID_LENGTH = 32
+LEGACY_RECORD_ID_CHARACTER_SET = frozenset("0123456789abcdef")
+# Every phase an earlier journal could be in. A journal naming any other phase is read as unreadable.
+LEGACY_REPLAY_PHASE_SET = frozenset(("prepared", "applying", "observed", "quitting", "quit_observed", "finalizing", "verified", "cleanup", "abort_prepared",
+                                     "abort_started", "abort_observed", "restitution_pending", "restituted", "external"))
+# The phases in which an earlier version was restoring the checkout (an Abort) or finishing a replay without a commit
+# when it stopped. The only copy of that work may then be in the backup folder and in the objects the anchor pins, so
+# the anchor of such a journal stays in whichever repository holds it, and the folder is named to the user there.
+LEGACY_RESTORATION_PHASE_SET = frozenset(("abort_prepared", "abort_started", "abort_observed", "restitution_pending", "quitting", "quit_observed", "finalizing"))
+# The phase given to a journal whose record cannot be read: nothing is known about it, so its anchor is kept.
+LEGACY_UNREADABLE_PHASE = ""
+# The fields of an earlier record this module reads; every other field is left alone.
+LEGACY_TEXT_FIELDS = ("record_id", "worktree_key", "common_git_dir", "phase", "anchor_ref", "anchor_oid")
+# The listing asked of for-each-ref: each reference name and the object it points to, separated by a NUL byte.
+LEGACY_ANCHOR_LISTING_FORMAT = "%(refname)%00%(objectname)"
+LEGACY_ANCHOR_LISTING_SEPARATOR = b"\0"
+LEGACY_ANCHOR_LISTING_FIELD_COUNT = 2
+# One deletion line of "update-ref --stdin -z": the command and the reference, then the value it must still hold.
+UPDATE_REF_DELETE_COMMAND = b"delete "
+UPDATE_REF_FIELD_TERMINATOR = b"\0"
+
+
+def legacy_replay_store_dir() -> str:
+    """Answer the folder in which earlier versions kept their Cherry-pick and Revert journals.
+
+    Called through this module's name everywhere, never bound to another name, so that the test suite can replace
+    it once and keep every test away from the folder of the person running it.
+    """
+    return os.path.join(writable_folder(QStandardPaths.StandardLocation.AppLocalDataLocation, sys.platform), LEGACY_REPLAY_STORE_BASENAME)
+
+
+def legacy_worktree_store_dir(store_dir: str, worktree_git_dir: str) -> str:
+    """Answer the subfolder an earlier version used for the journals of one working tree, named by the hash of its own Git folder."""
+    return os.path.join(store_dir, hashlib.sha256(os.fsencode(worktree_git_dir)).hexdigest())
+
+
+def is_legacy_record_id(name: str) -> bool:
+    """Tell whether a name is a journal identifier an earlier version generated: 32 lowercase hexadecimal characters."""
+    return len(name) == LEGACY_RECORD_ID_LENGTH and set(name) <= LEGACY_RECORD_ID_CHARACTER_SET
+
+
+def _unique_json_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    """Refuse a JSON object that names a field twice, instead of letting the last value silently win."""
+    value_by_name = {}
+    for name, value in pairs:
+        if name in value_by_name:
+            raise ValueError("An earlier replay journal repeats a field.")
+        value_by_name[name] = value
+    return value_by_name
+
+
+@dataclass(frozen=True)
+class LegacyReplayRecord:
+    """The part of one earlier journal that decides whether its anchor may go: which repository it served, its phase, its anchor."""
+
+    record_id: str
+    worktree_git_dir: str
+    common_git_dir: str
+    phase: str
+    anchor_ref: str
+    anchor_oid: str
+    record_dir: str
+
+
+def _unreadable_record(record_id: str, record_dir: str) -> LegacyReplayRecord:
+    """Describe a journal whose record cannot be trusted: only its folder name is known."""
+    return LegacyReplayRecord(record_id, "", "", LEGACY_UNREADABLE_PHASE, "", "", record_dir)
+
+
+def read_legacy_replay_record(record_dir: str) -> LegacyReplayRecord:
+    """Read the record of one earlier journal, bounded in size and refusing a repeated field, a missing field or a record of another folder.
+
+    Raises OSError, ValueError or TypeError when the record cannot be trusted. Nothing is written.
+    """
+    record_id = os.path.basename(record_dir)
+    filename = os.path.join(record_dir, LEGACY_RECORD_BASENAME)
+    with open(filename, "rb") as stream:
+        content = stream.read(REPLAY_RECORD_LIMIT_BYTES + 1)
+    if len(content) > REPLAY_RECORD_LIMIT_BYTES:
+        raise ValueError("An earlier replay journal is larger than its limit.")
+    try:
+        value_by_name = json.loads(content, object_pairs_hook=_unique_json_object)
+    except (UnicodeError, RecursionError) as error:
+        raise ValueError("An earlier replay journal cannot be decoded.") from error
+    if not isinstance(value_by_name, dict):
+        raise TypeError("An earlier replay journal is not a JSON object.")
+    text_by_name = {}
+    for name in LEGACY_TEXT_FIELDS:
+        value = value_by_name.get(name)
+        if not isinstance(value, str):
+            raise TypeError("An earlier replay journal lacks its " + name + " field.")
+        text_by_name[name] = value
+    if text_by_name["record_id"] != record_id or text_by_name["phase"] not in LEGACY_REPLAY_PHASE_SET:
+        raise ValueError("An earlier replay journal does not belong to its folder or names an unknown phase.")
+    # The subfolder is named by the hash of the working tree the journal served; a record found elsewhere was moved.
+    if legacy_worktree_store_dir(os.path.dirname(os.path.dirname(record_dir)), text_by_name["worktree_key"]) != os.path.dirname(record_dir):
+        raise ValueError("An earlier replay journal is not in the folder of its working tree.")
+    return LegacyReplayRecord(record_id, text_by_name["worktree_key"], text_by_name["common_git_dir"], text_by_name["phase"], text_by_name["anchor_ref"],
+                              text_by_name["anchor_oid"], record_dir)
+
+
+def legacy_replay_store_in_use(store_dir: str) -> bool:
+    """Tell whether an earlier version left at least one working tree subfolder in its journal folder; reads metadata only."""
+    if not os.path.isdir(store_dir):
+        return False
+    with os.scandir(store_dir) as entries:
+        for entry in entries:
+            if entry.is_dir(follow_symlinks=False):
+                return True
+    return False
+
+
+def read_legacy_replay_records(store_dir: str) -> tuple[LegacyReplayRecord, ...]:
+    """Read every earlier journal of every working tree, sorted by identifier, without changing a single file.
+
+    A journal whose record cannot be read is kept in the answer as unreadable, so that its anchor is kept too. More
+    journal folders than the limit raise ValueError: a journal that was not read could be one in the middle of a
+    restoration. The order in which the folders are listed is never used.
+    """
+    if not os.path.isdir(store_dir):
+        return ()
+    worktree_dirs = []
+    with os.scandir(store_dir) as entries:
+        for entry in entries:
+            if entry.is_dir(follow_symlinks=False):
+                worktree_dirs.append(entry.path)
+    record_dirs = []
+    for worktree_dir in sorted(worktree_dirs):
+        with os.scandir(worktree_dir) as entries:
+            for entry in entries:
+                if not entry.is_dir(follow_symlinks=False) or not is_legacy_record_id(entry.name):
+                    continue
+                record_dirs.append(entry.path)
+                if len(record_dirs) > REPLAY_RECORD_COUNT_LIMIT:
+                    raise ValueError("The folder of earlier replay journals holds too many journals to be read.")
+    records = []
+    for record_dir in record_dirs:
+        try:
+            records.append(read_legacy_replay_record(record_dir))
+        except (OSError, ValueError, TypeError):
+            records.append(_unreadable_record(os.path.basename(record_dir), record_dir))
+    records.sort(key=lambda record: (record.record_id, record.record_dir))
+    return tuple(records)
+
+
+def parse_legacy_anchor_listing(output: bytes) -> dict[str, str]:
+    """Read a for-each-ref listing written with LEGACY_ANCHOR_LISTING_FORMAT into the object each reference points to.
+
+    A line that does not hold exactly one name and one object raises ValueError, so that nothing is removed on a
+    listing that was not understood.
+    """
+    target_oid_by_ref = {}
+    for line in output.splitlines():
+        if not line:
+            continue
+        fields = line.split(LEGACY_ANCHOR_LISTING_SEPARATOR)
+        if len(fields) != LEGACY_ANCHOR_LISTING_FIELD_COUNT:
+            raise ValueError("Git gave back an unreadable reference listing.")
+        ref_field, oid_field = fields
+        target_oid_by_ref[ref_field.decode("utf-8")] = oid_field.decode("ascii")
+    return target_oid_by_ref
+
+
+def legacy_anchor_deletions(target_oid_by_ref: dict[str, str], records: tuple[LegacyReplayRecord, ...]) -> tuple[tuple[str, str], ...]:
+    """Choose the anchor references to remove from one repository, each with the object it must still point to when removed.
+
+    A candidate is a reference directly under LEGACY_ANCHOR_REF_PREFIX whose last component is a journal identifier and
+    whose target is a full object ID. It is kept when a journal of the same identifier is unreadable or stopped in the
+    middle of a restoration, whatever repository path that journal recorded. Every other candidate goes, including an
+    anchor whose journal is gone. The answer is sorted by reference name.
+    """
+    kept_record_id_set = set()
+    for record in records:
+        # The identifier is random, so a reference of that name in this repository comes from the repository the journal
+        # served, moved, renamed or copied since. Comparing paths would remove its anchor after a move; keeping it costs
+        # only one reference.
+        if record.phase == LEGACY_UNREADABLE_PHASE or record.phase in LEGACY_RESTORATION_PHASE_SET:
+            kept_record_id_set.add(record.record_id)
+    deletions = []
+    for ref, target_oid in target_oid_by_ref.items():
+        if not ref.startswith(LEGACY_ANCHOR_REF_PREFIX):
+            continue
+        record_id = ref.removeprefix(LEGACY_ANCHOR_REF_PREFIX)
+        if not is_legacy_record_id(record_id) or record_id in kept_record_id_set:
+            continue
+        try:
+            validate_oid(target_oid)
+        except ValueError:
+            continue
+        deletions.append((ref, target_oid))
+    return tuple(sorted(deletions))
+
+
+def kept_legacy_backup_dirs(records: tuple[LegacyReplayRecord, ...], target_oid_by_ref: dict[str, str], common_git_dir: str) -> tuple[str, ...]:
+    """Name, sorted, the journal folders an earlier version left in the middle of a restoration of the open repository, or could not read.
+
+    The anchor ties a journal to the open repository even after the repository moved, so a restoration or an
+    unreadable journal whose anchor this repository holds is named. A restoration recorded for this very repository
+    is named too when its anchor is gone, removed by hand or lost with a new clone: its backups are then the only copy
+    of that work. The recorded path only ever adds a folder to name; it never decides which anchor goes.
+    """
+    open_common_git_dir = canonical_path(common_git_dir)
+    kept_dirs = []
+    for record in records:
+        if record.phase != LEGACY_UNREADABLE_PHASE and record.phase not in LEGACY_RESTORATION_PHASE_SET:
+            continue
+        anchor_held = LEGACY_ANCHOR_REF_PREFIX + record.record_id in target_oid_by_ref
+        recorded_here = record.phase in LEGACY_RESTORATION_PHASE_SET and canonical_path(record.common_git_dir) == open_common_git_dir
+        if anchor_held or recorded_here:
+            kept_dirs.append(record.record_dir)
+    return tuple(sorted(kept_dirs))
+
+
+def legacy_anchor_deletion_input(deletions: tuple[tuple[str, str], ...]) -> bytes:
+    """Write the input of "git update-ref --stdin -z" that deletes each reference only while it still points to its listed object.
+
+    Git applies the lines as one transaction: a reference that moved in between makes the whole command fail and
+    removes nothing.
+    """
+    lines = []
+    for ref, old_oid in deletions:
+        lines.append(UPDATE_REF_DELETE_COMMAND + ref.encode("utf-8") + UPDATE_REF_FIELD_TERMINATOR + old_oid.encode("ascii") + UPDATE_REF_FIELD_TERMINATOR)
+    return b"".join(lines)