gitpane 1.0.0__py3-none-any.whl

gitpane/operation/launch_signature.py

@@ -0,0 +1,254 @@
+"""Detect a change in the files a queued write was checked against, from their metadata, never their content.
+
+Every native write the application queues is fully checked on a worker, then waits for the launcher. Its launch
+check runs on the Qt thread at the moment Git starts, so it must stay cheap: it reads again the metadata of exactly
+the paths the worker signed and refuses the launch on the smallest difference. The commit, rebase, stash and replay
+commands all share this one definition, so they detect the same changes.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from gitpane.commit.commit_metadata import read_path_metadata
+from gitpane.system.path_identity import canonical_path
+from gitpane.worktree.worktree_file import stat_identity
+from gitpane.worktree.worktree_snapshot import read_index
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.history.repository_value import RepositoryContext
+
+# Git names the Git directory of a worktree through this entry at its root: a directory for the main worktree, a
+# file pointing at the private directory for a linked one.
+WORKTREE_GIT_ENTRY_BASENAME = ".git"
+# A linked worktree's private Git directory names the shared one through this file.
+LINKED_COMMON_DIR_BASENAME = "commondir"
+PATH_MOVED_CAUSE = "A checked file changed while its launch signature was taken. Refresh before writing."
+SCOPE_MISMATCH_CAUSE = "Two launch signatures of different scope cannot be compared."
+
+
+@dataclass(frozen=True)
+class LaunchSignature:
+    """The metadata, without any content, of everything a queued command was checked against just before it waits.
+
+    Files and watched folders keep their identity, change time, link count and redirection tag, so a same-size
+    rewrite whose modification time was put back, an added hard link or a file replaced by a reparse point all still
+    differ; a watched folder changes when an entry appears in it. Containing folders keep only their identity, type,
+    redirection and resolved path, so unrelated activity next to a checked file changes nothing while replacing or
+    redirecting the folder does. Each entry keeps its path, and absence is recorded as None, so an absent file, an
+    empty file and two lists of different scope never compare equal. It proves nothing and authorizes nothing by itself.
+    """
+
+    file_signatures: tuple[tuple[str, tuple[int, ...] | None], ...]
+    directory_signatures: tuple[tuple[str, tuple[int, ...] | None], ...]
+    parent_identities: tuple[tuple[str, tuple[int | str, ...] | None], ...]
+
+
+def launch_path_metadata(filename: str) -> tuple[int, ...] | None:
+    """Read identity, type and permissions, change time, links and redirection of one path, refusing a path that moves.
+
+    The identity reader already compares the path before and after its change time; the last lstat adds the link count
+    and the redirection tag only if it still shows that same identity. A same-size write whose modification time was
+    put back still changes the change time, so it is seen here without reading a byte of the file.
+    """
+    metadata = read_path_metadata(filename)
+    try:
+        current = os.lstat(filename)
+    except FileNotFoundError:
+        current = None
+    if metadata is None and current is None:
+        return None
+    if metadata is None or current is None:
+        raise ValueError(PATH_MOVED_CAUSE)
+    identity = stat_identity(current)
+    if metadata[:len(identity)] != identity:
+        raise ValueError(PATH_MOVED_CAUSE)
+    return (*metadata, current.st_nlink, getattr(current, "st_reparse_tag", 0))
+
+
+def parent_identity(directory: str) -> tuple[int | str, ...] | None:
+    """Identify a containing folder by device, inode, type, redirection tag and resolved path, never by its activity.
+
+    Activity in a shared parent, such as another file appearing next to a checked one, leaves this identity alone;
+    replacing or redirecting the folder itself, or one of its own parents, does not.
+    """
+    try:
+        metadata = os.lstat(directory)
+    except FileNotFoundError:
+        return None
+    return (metadata.st_dev, metadata.st_ino, stat.S_IFMT(metadata.st_mode), getattr(metadata, "st_reparse_tag", 0), canonical_path(directory))
+
+
+def sign_launch_paths(filenames: list[str] | tuple[str, ...], watched_dirs: list[str] | tuple[str, ...], parent_dirs: list[str] | tuple[str, ...]) -> LaunchSignature:
+    """Take the metadata of the given paths in sorted order, so the result never depends on how the folders were listed.
+
+    Watched folders are compared on their own metadata, so an entry created in them changes the signature even when it
+    was not yet one of the listed files. Any read error is propagated: an unreadable file is never taken for an absent one.
+    """
+    file_signatures = []
+    for filename in sorted(set(filenames)):
+        file_signatures.append((filename, launch_path_metadata(filename)))
+    directory_signatures = []
+    for directory in sorted(set(watched_dirs)):
+        directory_signatures.append((directory, launch_path_metadata(directory)))
+    parent_identities = []
+    for directory in sorted(set(parent_dirs)):
+        parent_identities.append((directory, parent_identity(directory)))
+    return LaunchSignature(tuple(file_signatures), tuple(directory_signatures), tuple(parent_identities))
+
+
+def signed_paths(signature: LaunchSignature) -> tuple[list[str], list[str], list[str]]:
+    """List again exactly the files, watched folders and containing folders a signature covers, so a later look never walks a folder."""
+    filenames = []
+    for filename, _value in signature.file_signatures:
+        filenames.append(filename)
+    watched_dirs = []
+    for directory, _value in signature.directory_signatures:
+        watched_dirs.append(directory)
+    parent_dirs = []
+    for directory, _value in signature.parent_identities:
+        parent_dirs.append(directory)
+    return filenames, watched_dirs, parent_dirs
+
+
+def changed_launch_paths(before: LaunchSignature, after: LaunchSignature) -> tuple[str, ...]:
+    """Name every path whose metadata differs between two signatures of the same scope.
+
+    Two signatures of different scope differ everywhere by construction, so their comparison is refused outright.
+    """
+    changed_paths = []
+    for before_entries, after_entries in ((before.file_signatures, after.file_signatures), (before.directory_signatures, after.directory_signatures),
+                                          (before.parent_identities, after.parent_identities)):
+        before_paths = []
+        for path, _value in before_entries:
+            before_paths.append(path)
+        after_paths = []
+        for path, _value in after_entries:
+            after_paths.append(path)
+        if before_paths != after_paths:
+            raise ValueError(SCOPE_MISMATCH_CAUSE)
+        for (path, before_value), (_path, after_value) in zip(before_entries, after_entries, strict=True):
+            if before_value != after_value:
+                changed_paths.append(path)
+    return tuple(changed_paths)
+
+
+def exclude_covered_launch_paths(signature: LaunchSignature, covered: LaunchSignature) -> LaunchSignature:
+    """Keep, from a signature, only the entries whose path another signature does not list, with their earlier values.
+
+    A launch check compares both signatures; a path both list is left to `covered`, which holds the most recent
+    accepted value, such as a message the command itself rewrote after the first signature was taken.
+    """
+    covered_path_set = set()
+    for entries in (covered.file_signatures, covered.directory_signatures, covered.parent_identities):
+        for path, _value in entries:
+            covered_path_set.add(path)
+    kept_entries_by_kind = {}
+    for kind, entries in (("file", signature.file_signatures), ("directory", signature.directory_signatures), ("parent", signature.parent_identities)):
+        kept_entries = []
+        for path, value in entries:
+            if path not in covered_path_set:
+                kept_entries.append((path, value))
+        kept_entries_by_kind[kind] = tuple(kept_entries)
+    return LaunchSignature(kept_entries_by_kind["file"], kept_entries_by_kind["directory"], kept_entries_by_kind["parent"])
+
+
+def verify_launch_signature(signature: LaunchSignature, changed_cause: str, unreadable_cause: str | None = None) -> None:
+    """Take the same metadata again and refuse the launch on the smallest difference or on any read error.
+
+    This check opens no content and walks no folder: it reads again exactly the paths the signature lists, so it is
+    cheap enough for the moment a queued command is handed to Git. An unreadable path is refused with
+    `unreadable_cause` when the caller names one, with `changed_cause` otherwise.
+    """
+    try:
+        current = sign_launch_paths(*signed_paths(signature))
+    except OSError as error:
+        raise ValueError(unreadable_cause or changed_cause) from error
+    if changed_launch_paths(signature, current):
+        raise ValueError(changed_cause)
+
+
+@dataclass(frozen=True)
+class WriteLaunchSignature:
+    """What one native write command was checked against, from its first look at the repository until Git starts.
+
+    ``reference_state`` is the complete reference and configuration read taken before the Git checks, and
+    ``index_content`` the index the command was checked with, when it depends on one. ``metadata`` holds only metadata:
+    the files the reference inventory lists (and that index), the files that name this worktree's Git directories, the
+    extra files and folders the caller watches, the folders whose new entries change references, and the identity of
+    the folders that contain them. It lets the launch check tell a change from metadata alone; nothing here authorizes
+    a command by itself.
+    """
+
+    reference_state: tuple
+    index_filename: str | None
+    index_content: bytes | None
+    metadata: LaunchSignature
+
+
+def capture_write_launch_signature(context: RepositoryContext, changed_cause: str, read_references: Callable[[RepositoryContext], tuple],
+                                   read_reference_paths: Callable[[RepositoryContext], tuple[list[str], list[str]]], index_filename: str | None = None,
+                                   index_content: bytes | None = None, *, extra_filenames: list[str] | tuple[str, ...] = (),
+                                   extra_watched_dirs: list[str] | tuple[str, ...] = ()) -> WriteLaunchSignature:
+    """Take the first look a native write command relies on, before any of its Git checks: the complete reference read between two identical metadata looks.
+
+    Runs on a worker. The paths come from the one reference inventory, the worktree location files and the extra files
+    and folders the caller names (a replay watches the pause files of its worktree); the Git folders and the worktree
+    folder are compared by identity only, so unrelated activity next to a checked file changes nothing. The caller hands
+    in the reference reader and its inventory: the reference module reaches this one again through the modules it
+    imports, so this module cannot import it.
+    """
+    reference_filenames, reference_dirs = read_reference_paths(context)
+    location_filenames, location_parent_dirs = worktree_location_paths(context)
+    filenames = [*reference_filenames, *location_filenames, *extra_filenames]
+    watched_dirs = [*reference_dirs, *extra_watched_dirs]
+    parent_dirs = list(location_parent_dirs)
+    if index_filename is not None:
+        filenames.append(index_filename)
+        parent_dirs.append(os.path.dirname(index_filename))
+    before = sign_launch_paths(filenames, watched_dirs, parent_dirs)
+    reference_state = read_references(context)
+    after = sign_launch_paths(filenames, watched_dirs, parent_dirs)
+    if changed_launch_paths(before, after):
+        raise ValueError(changed_cause)
+    return WriteLaunchSignature(reference_state, index_filename, index_content, after)
+
+
+def prepare_write_launch_signature(context: RepositoryContext, baseline: WriteLaunchSignature, changed_cause: str,
+                                   read_references: Callable[[RepositoryContext], tuple]) -> WriteLaunchSignature:
+    """Check, just before the native write command is handed to the launcher, that nothing moved since the first look.
+
+    Runs on a worker. The reference contents are compared with the first look, read by the same reader, and the index
+    with the one the command was checked with, between two identical metadata looks that must also match the first
+    one. A change is refused, never adopted: the answer is the very signature the launch check compares with.
+    """
+    verify_launch_signature(baseline.metadata, changed_cause)
+    if read_references(context) != baseline.reference_state:
+        raise ValueError(changed_cause)
+    if baseline.index_filename is not None and read_index(baseline.index_filename) != baseline.index_content:
+        raise ValueError(changed_cause)
+    verify_launch_signature(baseline.metadata, changed_cause)
+    return baseline
+
+
+def worktree_location_paths(context: RepositoryContext) -> tuple[list[str], list[str]]:
+    """Name the files and containing folders that tell Git where this worktree's Git directories are.
+
+    Files: the pointer to the shared Git directory a linked worktree keeps, and the `.git` pointer file at the root of
+    a linked worktree. Containing folders: both Git directories, the worktree root and its `.git` entry. A worktree
+    redirected elsewhere while a command waits therefore changes the signature even when every reference is unchanged.
+    """
+    filenames = [os.path.join(context.git_dir, LINKED_COMMON_DIR_BASENAME)]
+    parent_dirs = [context.git_dir, context.common_git_dir]
+    if context.worktree_dir is None:
+        return filenames, parent_dirs
+    git_entry = os.path.join(context.worktree_dir, WORKTREE_GIT_ENTRY_BASENAME)
+    parent_dirs.extend((context.worktree_dir, git_entry))
+    if os.path.isfile(git_entry):
+        filenames.append(git_entry)
+    return filenames, parent_dirs

gitpane/operation/operation_status.py

@@ -0,0 +1,87 @@
+"""Name the statuses an operation reports, from a wait to its end.
+
+An operation reports the end of its work, or of one of its steps, with one of these members, and a wait still under way
+with PENDING. A process end becomes an operation end only through ``operation_status``, which keeps the word the
+process wrote, so the console keeps its text.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Self
+
+from gitpane.process.process_runner import ProcessStatus
+
+
+class OperationStatus(Enum):
+    """How an operation, or one of its steps, ended, or that it still waits; the value is the word its log and its JSON write.
+
+    ``end_word`` is the word that ends the readable line of the operation in its console, such as ``done`` for a
+    success. A status without a word of its own keeps its value, so it stays visible rather than hidden.
+    """
+
+    SUCCESS = ("success", "done")
+    """The operation reached its goal."""
+    FAILED = ("failed", "failed")
+    """The operation ran and did not reach its goal."""
+    REFUSED = ("refused", "not started")
+    """GitPane refused the operation before launching Git, such as a checkout into a folder that no longer exists."""
+    PARTIAL = ("partial", "partially done")
+    """The operation did part of its work, such as a Stash pop that applied the stash but stopped on conflicts.
+
+    An account exchange uses it too: the identity was accepted but the secure store did not keep the secret, or a secret
+    was erased but the saved list could not be written.
+    """
+    UNKNOWN = ("unknown", "outcome unknown")
+    """The effect of the operation could not be observed, such as a Push whose server could not be read again after sending."""
+    PAUSED = ("paused", "paused")
+    """The operation stopped to wait for the user, such as a rebase, a cherry-pick or a revert stopped on a conflict."""
+    ABORTED = ("aborted", "aborted")
+    """The result of a requested native Abort, reported only once the abandonment has been verified."""
+    CANCELLED = ("cancelled", "cancelled")
+    """The user stopped the operation."""
+    TIMEOUT = ("timeout", "timeout")
+    """The command of the operation was stopped because it ran past its time limit."""
+    IDLE_TIMEOUT = ("idle_timeout", "idle_timeout")
+    """The command of the operation was stopped because it wrote nothing for too long."""
+    VOLUME = ("volume", "volume")
+    """The command of the operation was stopped because it wrote more than its output limit."""
+    START_FAILED = ("start_failed", "start_failed")
+    """The command of the operation could not be launched."""
+    QUEUE_FULL = ("queue_full", "queue_full")
+    """The command of the operation was refused because too many were already waiting; it never ran."""
+    NOT_STARTED = ("not-started", "not-started")
+    """A step that never began, because an earlier step of the same operation did not let it.
+
+    The steps of a checkout, a branch or a tag change write the same meaning with a space, ``STEP_NOT_STARTED``; a
+    check for a step that never began must look for both members.
+    """
+    SIGN_IN_TIMEOUT = ("timed_out", "timed_out")
+    """A sign-in in the browser that was not finished in time."""
+    STEP_NOT_STARTED = ("not started", "not started")
+    """A step of a branch, tag or checkout change that never began, written with a space as its console shows it.
+
+    The steps of a transport write the same end as ``NOT_STARTED``; both members are kept so no console changes.
+    """
+    NO_CHANGE = ("no_change", "no_change")
+    """A stash was asked for while nothing had changed, so Git created none."""
+    PENDING = ("pending", "pending")
+    """An operation that still waits for the answer of the system, reported before its end, such as a move to the Trash."""
+
+    def __new__(cls, value: str, end_word: str) -> Self:
+        """Keep the status word as the value, with the word that ends the operation's line in its console."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.end_word = end_word
+        return member
+
+
+def operation_status(process_status: ProcessStatus) -> OperationStatus:
+    """Return the operation end that reports a process end, with the same word, so the console keeps its text.
+
+    This is the only place where a process status becomes an operation status. A process still running has not ended, so
+    it has no operation status and is refused with ``ValueError``.
+    """
+    if process_status == ProcessStatus.RUNNING:
+        raise ValueError("A running process has not ended")
+    return OperationStatus(process_status.value)