gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/worktree_file.py

@@ -0,0 +1,406 @@
+"""Handle owned file images (capture, materialization, replacement) without following working-tree links."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+import tempfile
+import uuid
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from gitpane.config import GIT_MUTATION_TIMEOUT_MS, MUTATION_IDLE_TIMEOUT_MS, PROCESS_CHUNK_BYTES
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE
+from gitpane.system.path_identity import canonical_path
+from gitpane.tool.system_tool import worktree_filename
+from gitpane.worktree.command_sequence import GitCommand
+from gitpane.worktree.worktree_snapshot import fingerprint
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+    from typing import BinaryIO
+
+    from gitpane.history.repository_value import RepositoryContext
+
+PRIVATE_DIRECTORY_MODE = 0o700
+PRIVATE_FILE_MODE = 0o600
+REGULAR_FILE_MODE = 0o666
+BATCH_TERMINATOR_BYTES = 1
+FILE_OBJECT_IDENTITY_FIELDS = 2
+# Position of st_mode in stat_identity; the change time is the only field after the stable ones.
+FILE_MODE_IDENTITY_FIELD = 2
+FILE_STABLE_IDENTITY_FIELDS = 5
+MISSING_PARENT_IDENTITY = (0, 0)
+# A file reachable under two names while it has a single link can only be one directory entry seen twice.
+SINGLE_LINK_COUNT = 1
+
+
+@dataclass(frozen=True)
+class FileImage:
+    """Distinguish absence, file type, exact bytes and filesystem identity for safe replacement."""
+
+    exists: bool
+    mode: int
+    content: bytes | None = None
+    content_filename: str | None = None
+    identity: tuple[int, ...] | None = None
+    parents: tuple[tuple[str, tuple[int, int]], ...] = ()
+    publication_mode: int | None = None
+
+    def read(self) -> bytes:
+        """Read owned content while keeping missing files distinct from empty files."""
+        if not self.exists:
+            return b""
+        if self.content is not None:
+            return self.content
+        if self.content_filename is None:
+            raise ValueError("The file image has no owned content")
+        with open(self.content_filename, "rb") as stream:
+            return stream.read()
+
+    def digest(self) -> str:
+        """Describe content and type without putting private file bytes in the journal."""
+        if not self.exists:
+            return "absent"
+        if self.content is not None or self.content_filename is None:
+            return str(self.mode) + ":" + fingerprint(self.read())
+        digest = hashlib.sha256()
+        with open(self.content_filename, "rb") as stream:
+            while chunk := stream.read(PROCESS_CHUNK_BYTES):
+                digest.update(chunk)
+        return str(self.mode) + ":" + digest.hexdigest()
+
+
+def stat_identity(metadata: os.stat_result) -> tuple[int, ...]:
+    """Recognize a replaced file even when its content and size were preserved."""
+    return (metadata.st_dev, metadata.st_ino, metadata.st_mode, metadata.st_size, metadata.st_mtime_ns, metadata.st_ctime_ns)
+
+
+def matches_after_announced_mode(actual: tuple[int, ...], recorded: tuple[int, ...], announced_mode: int | None) -> bool:
+    """Recognize a recorded file after the permission change its owner announced, and nothing else.
+
+    Changing permissions also moves the change time, so the file only differs from its recorded identity in those two
+    fields. Device, inode, size and modification time must still match and the mode must be exactly the announced one,
+    so a file another program rewrote, replaced or gave other permissions is still a different file.
+    """
+    if announced_mode is None:
+        return False
+    expected = list(recorded)
+    expected[FILE_MODE_IDENTITY_FIELD] = announced_mode
+    return tuple(actual)[:FILE_STABLE_IDENTITY_FIELDS] == tuple(expected)[:FILE_STABLE_IDENTITY_FIELDS]
+
+
+def validate_destination(context: RepositoryContext, path: bytes, allow_missing_parents: bool = False) -> tuple[str, tuple[tuple[str, tuple[int, int]], ...]]:
+    """Reject administrative and linked paths, optionally capturing missing historical parents."""
+    filename = worktree_filename(context, path)
+    for part in path.split(b"/"):
+        if part.rstrip(b" .").lower() in (b".git", b"git~1"):
+            raise ValueError("Git administrative paths cannot be replaced")
+    # Git names its folders as the disk spells them, while the file is built from the folder the user opened, which on
+    # macOS may be typed in another letter case or Unicode form: both sides take the same identity before comparing.
+    normalized_filename = canonical_path(filename)
+    for protected_dir in (context.git_dir, context.common_git_dir):
+        normalized_dir = canonical_path(protected_dir)
+        try:
+            ancestor_dir = os.path.commonpath((normalized_dir, normalized_filename))
+        except ValueError:
+            # Windows worktrees can live on a different drive from their shared Git directory.
+            continue
+        if ancestor_dir == normalized_dir:
+            raise ValueError("Git administrative paths cannot be replaced")
+    root_dir = os.path.normcase(os.path.abspath(context.worktree_dir))
+    parent_dir = os.path.dirname(filename)
+    parents: list[tuple[str, tuple[int, int]]] = []
+    while True:
+        try:
+            metadata = os.lstat(parent_dir)
+        except FileNotFoundError:
+            if not allow_missing_parents or os.path.normcase(parent_dir) == root_dir:
+                raise
+            parents.append((parent_dir, MISSING_PARENT_IDENTITY))
+        else:
+            if not stat.S_ISDIR(metadata.st_mode) or os.path.islink(parent_dir) or os.path.isjunction(parent_dir):
+                raise ValueError("A selected path traverses a linked or invalid directory")
+            parents.append((parent_dir, (metadata.st_dev, metadata.st_ino)))
+        if os.path.normcase(parent_dir) == root_dir:
+            break
+        ancestor_dir = os.path.dirname(parent_dir)
+        if ancestor_dir == parent_dir:
+            raise ValueError("A selected path is outside the working tree")
+        parent_dir = ancestor_dir
+    return filename, tuple(parents)
+
+
+def capture_image(context: RepositoryContext, path: bytes, allow_missing_parents: bool = False) -> FileImage:
+    """Capture exact file bytes and lstat identity, refusing links and replacement during reading."""
+    filename, parents = validate_destination(context, path, allow_missing_parents)
+    try:
+        metadata = os.lstat(filename)
+    except FileNotFoundError:
+        return FileImage(False, 0, parents=parents)
+    if os.path.isjunction(filename):
+        raise ValueError("A junction cannot be replaced as a file")
+    if stat.S_ISLNK(metadata.st_mode):
+        content = os.fsencode(os.readlink(filename))
+    elif stat.S_ISREG(metadata.st_mode):
+        with open(filename, "rb") as stream:
+            # Windows fstat and lstat can report different ctime meanings; compare handle identity, mode, size and mtime here.
+            if stat_identity(os.fstat(stream.fileno()))[:FILE_STABLE_IDENTITY_FIELDS] != stat_identity(metadata)[:FILE_STABLE_IDENTITY_FIELDS]:
+                raise ValueError("Working file changed while reading")
+            content = stream.read()
+    else:
+        raise ValueError("This working file type cannot be replaced")
+    if stat_identity(os.lstat(filename)) != stat_identity(metadata):
+        raise ValueError("Working file changed while reading")
+    return FileImage(True, metadata.st_mode, content, identity=stat_identity(metadata), parents=parents)
+
+
+def validate_image(context: RepositoryContext, path: bytes, expected: FileImage) -> None:
+    """Require unchanged parents, type, identity and bytes immediately before publication."""
+    current = capture_image(context, path, allow_missing_parents=any(identity == MISSING_PARENT_IDENTITY for _parent_dir, identity in expected.parents))
+    if (current.exists, current.identity, current.parents, current.digest()) != (expected.exists, expected.identity, expected.parents, expected.digest()):
+        raise ValueError("Working file or parent changed after confirmation; select the changes again")
+
+
+def private_file_dir(context: RepositoryContext, path: bytes, operation_dir: str, allow_missing_parents: bool = False) -> str:
+    """Choose a private directory on the target volume, never a temporary file inside user content."""
+    _filename, parents = validate_destination(context, path, allow_missing_parents)
+    existing_parent_dir = next(parent_dir for parent_dir, identity in parents if identity != MISSING_PARENT_IDENTITY)
+    target_device = os.stat(existing_parent_dir).st_dev
+    if os.stat(operation_dir).st_dev == target_device:
+        return operation_dir
+    parent_dir = os.path.dirname(os.path.abspath(context.worktree_dir))
+    if os.path.islink(parent_dir) or os.path.isjunction(parent_dir) or os.stat(parent_dir).st_dev != target_device:
+        raise ValueError("No private directory on the working file's volume is available")
+    private_dir = tempfile.mkdtemp(prefix=".gitpane-operation-", dir=parent_dir)
+    os.chmod(private_dir, PRIVATE_DIRECTORY_MODE)
+    root_dir = canonical_path(context.worktree_dir)
+    if os.path.commonpath((root_dir, canonical_path(private_dir))) == root_dir:
+        os.rmdir(private_dir)
+        raise ValueError("Private file preparation would enter the working tree")
+    return private_dir
+
+
+def publication_image(expected: FileImage, created_dirs: list[tuple[str, tuple[int, int]]]) -> FileImage:
+    """Account only for parents created and still owned by this publication."""
+    identity_by_directory = dict(created_dirs)
+    parents = []
+    for directory, identity in expected.parents:
+        parents.append((directory, identity_by_directory.get(directory, identity) if identity == MISSING_PARENT_IDENTITY else identity))
+    return replace(expected, parents=tuple(parents))
+
+
+def create_missing_parents(context: RepositoryContext, path: bytes, expected: FileImage, created_dirs: list[tuple[str, tuple[int, int]]], persist: Callable[[], None]) -> FileImage:
+    """Revalidate each ancestor before creating and journaling missing destination directories."""
+    validate_image(context, path, publication_image(expected, created_dirs))
+    for directory, identity in reversed(expected.parents):
+        if identity != MISSING_PARENT_IDENTITY or directory in dict(created_dirs):
+            continue
+        validate_image(context, path, publication_image(expected, created_dirs))
+        os.mkdir(directory)
+        created_dirs.append((directory, stat_identity(os.lstat(directory))[:FILE_OBJECT_IDENTITY_FIELDS]))
+        persist()
+    current = publication_image(expected, created_dirs)
+    validate_image(context, path, current)
+    return current
+
+
+def clean_created_parents(created_dirs: list[tuple[str, tuple[int, int]]]) -> None:
+    """Remove only owned empty parents, retaining external files and replacement directories."""
+    for directory, identity in reversed(created_dirs):
+        try:
+            if not os.path.islink(directory) and not os.path.isjunction(directory) and stat_identity(os.lstat(directory))[:FILE_OBJECT_IDENTITY_FIELDS] == tuple(identity):
+                os.rmdir(directory)
+        except OSError:
+            # Another writer may now own content inside this directory.
+            pass
+
+
+class FilteredBlobStream:
+    """Validate one NUL-framed filtered blob while retaining only its trailing separator."""
+
+    def __init__(self, stream: BinaryIO, oid: str) -> None:
+        """Bind an owned destination to the exact requested Git object and blob type."""
+        self.stream = stream
+        self.expected_header = oid.encode("ascii") + b" blob"
+        self.header = bytearray()
+        self.header_complete = False
+        self.tail = b""
+
+    def consume(self, chunk: bytes) -> None:
+        """Write bounded body chunks, rejecting unexpected headers before any result is usable."""
+        if not self.header_complete:
+            header, separator, remainder = chunk.partition(b"\0")
+            self.header.extend(header)
+            if len(self.header) > len(self.expected_header):
+                raise ValueError("Git returned an invalid filtered blob header")
+            if not separator:
+                return
+            if bytes(self.header) != self.expected_header:
+                raise ValueError("Git returned a different filtered object")
+            self.header_complete = True
+            chunk = remainder
+        content = self.tail + chunk
+        if content:
+            self.stream.write(content[:-BATCH_TERMINATOR_BYTES])
+            self.tail = content[-BATCH_TERMINATOR_BYTES:]
+
+    def finish(self) -> None:
+        """Require the terminal NUL only after Git has exited successfully and stdout reached EOF."""
+        if not self.header_complete or self.tail != b"\0":
+            raise ValueError("Git returned an incomplete filtered blob stream")
+        self.stream.flush()
+        os.fsync(self.stream.fileno())
+
+
+def materialize_blob(oid: str, path: bytes, mode: str, destination_filename: str, symlinks: bool = True) -> Generator[GitCommand, bytes, FileImage]:
+    """Stream Git's actual working representation into an owned file outside the working tree."""
+    if mode == "160000":
+        raise ValueError("A submodule cannot be materialized as a file")
+    if mode not in ("100644", "100755", "120000"):
+        raise ValueError("Unsupported Git file mode")
+    with open(destination_filename, "xb") as stream:
+        os.chmod(destination_filename, PRIVATE_FILE_MODE)
+        if mode == "120000":
+            yield GitCommand(["cat-file", "blob", oid], stdout_limit_bytes=None, consume=stream.write,
+                             timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=MUTATION_IDLE_TIMEOUT_MS)
+        else:
+            consumer = FilteredBlobStream(stream, oid)
+            yield GitCommand(["cat-file", "--batch=%(objectname) %(objecttype)", "--filters", "-Z"], stdin=oid.encode("ascii") + b" ./" + path + b"\0",
+                             stdout_limit_bytes=None, consume=consumer.consume, timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=MUTATION_IDLE_TIMEOUT_MS, profile=LOCAL_WRITE_PROFILE)
+            consumer.finish()
+        stream.flush()
+        os.fsync(stream.fileno())
+    file_mode = stat.S_IFLNK if mode == "120000" and symlinks else stat.S_IFREG
+    permission_mode = 0o755 if mode == "100755" else REGULAR_FILE_MODE
+    return FileImage(True, file_mode | permission_mode, content_filename=destination_filename)
+
+
+def write_image(filename: str, image: FileImage) -> None:
+    """Create an owned publication candidate with the requested regular-file bytes and mode."""
+    if not image.exists:
+        return
+    if stat.S_ISLNK(image.mode):
+        os.symlink(os.fsdecode(image.read()), filename)
+        return
+    with open(filename, "xb") as stream:
+        os.chmod(filename, PRIVATE_FILE_MODE)
+        if image.content_filename is not None and image.content is None:
+            with open(image.content_filename, "rb") as source:
+                while chunk := source.read(PROCESS_CHUNK_BYTES):
+                    stream.write(chunk)
+        else:
+            stream.write(image.read())
+        stream.flush()
+        os.fsync(stream.fileno())
+    os.chmod(filename, stat.S_IMODE(image.mode))
+
+
+def creation_permission_mode(directory: str, executable: bool = False) -> int:
+    """Observe kernel-granted creation permissions using an empty file, without changing umask."""
+    filename = os.path.join(directory, "creation-mode-" + uuid.uuid4().hex)
+    requested_mode = REGULAR_FILE_MODE | (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH) if executable else REGULAR_FILE_MODE
+    descriptor = os.open(filename, os.O_CREAT | os.O_EXCL | os.O_WRONLY, requested_mode)
+    metadata: os.stat_result | None = None
+    try:
+        metadata = os.fstat(descriptor)
+        return stat.S_IMODE(metadata.st_mode)
+    finally:
+        os.close(descriptor)
+        current = os.lstat(filename)
+        if metadata is not None and (current.st_dev, current.st_ino) == (metadata.st_dev, metadata.st_ino):
+            os.unlink(filename)
+
+
+def prepare_publication_image(filename: str, image: FileImage, before: FileImage) -> FileImage:
+    """Keep content private while recording final permissions separately from the candidate's mode."""
+    if not image.exists or stat.S_ISLNK(image.mode):
+        write_image(filename, image)
+        return replace(image, mode=os.lstat(filename).st_mode) if image.exists else image
+    permission_mode = stat.S_IMODE(image.mode)
+    if not before.exists or not stat.S_ISREG(before.mode):
+        permission_mode = creation_permission_mode(os.path.dirname(filename), bool(image.mode & stat.S_IXUSR))
+    write_image(filename, replace(image, mode=stat.S_IFREG | PRIVATE_FILE_MODE))
+    # Windows chmod controls only the read-only flag, so the image digest must describe its actual file mode.
+    mode = stat.S_IFREG | permission_mode
+    if os.name == "nt":
+        write_mask = stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH
+        mode = stat.S_IFREG | (REGULAR_FILE_MODE if permission_mode & stat.S_IWUSR else REGULAR_FILE_MODE & ~write_mask)
+    return replace(image, mode=mode, publication_mode=permission_mode)
+
+
+def publication_permission(image: FileImage) -> int | None:
+    """Name the permissions publish_image_mode gives a candidate, or None when it leaves the file as it is.
+
+    A recovery journal records this before the change happens, so an interruption right after it is still recognizable.
+    """
+    if not image.exists or stat.S_ISLNK(image.mode):
+        return None
+    return image.publication_mode if image.publication_mode is not None else stat.S_IMODE(image.mode)
+
+
+def publish_image_mode(filename: str, image: FileImage) -> None:
+    """Apply accepted permissions only at publication, leaving symbolic links themselves untouched."""
+    permission = publication_permission(image)
+    if permission is not None:
+        os.chmod(filename, permission)
+
+
+def respell_single_entry(context: RepositoryContext, spelled_path: bytes, wanted_path: bytes) -> None:
+    """Give one directory entry the spelling Git expects when the filesystem finds it under another letter case or Unicode form.
+
+    Replacing a file through another spelling of its name keeps the spelling already on disk on macOS, so the Reset of
+    a case-only rename would leave the restored file under the renamed spelling. Renaming the entry onto itself under
+    the wanted spelling changes only its name. Both names must still lead to the same single-link file: anything else
+    is a second file, which is left untouched rather than replaced.
+    """
+    if spelled_path == wanted_path:
+        return
+    spelled_filename, _parents = validate_destination(context, spelled_path)
+    wanted_filename, _parents = validate_destination(context, wanted_path)
+    spelled_metadata = os.lstat(spelled_filename)
+    wanted_metadata = os.lstat(wanted_filename)
+    if (spelled_metadata.st_dev, spelled_metadata.st_ino) != (wanted_metadata.st_dev, wanted_metadata.st_ino) or wanted_metadata.st_nlink != SINGLE_LINK_COUNT:
+        return
+    os.replace(spelled_filename, wanted_filename)
+
+
+def owned_inventory(directory: str) -> list[tuple[str, tuple[int, ...]]]:
+    """Record private files and directories without following any symbolic links."""
+    owned_files: list[tuple[str, tuple[int, ...]]] = []
+    with os.scandir(directory) as iterator:
+        entries = sorted(iterator, key=lambda entry: entry.name)
+    for entry in entries:
+        if entry.name in ("record.json", "record.next"):
+            continue
+        if entry.is_dir(follow_symlinks=False) and not os.path.isjunction(entry.path):
+            owned_files.extend(owned_inventory(entry.path))
+        owned_files.append((entry.path, stat_identity(os.lstat(entry.path))))
+    return owned_files
+
+
+def clean_owned(directory: str, owned_files: list[tuple[str, tuple[int, ...]]]) -> None:
+    """Delete only inventoried private artifacts whose paths and filesystem identities still agree."""
+    root_dir = os.path.normcase(os.path.abspath(directory))
+    for filename, expected in owned_files:
+        normalized_filename = os.path.normcase(os.path.abspath(filename))
+        if os.path.commonpath((root_dir, normalized_filename)) != root_dir or normalized_filename == root_dir:
+            raise ValueError("Recovery cleanup path escapes its private directory")
+        parent_dir = os.path.dirname(filename)
+        while os.path.normcase(os.path.abspath(parent_dir)) != root_dir:
+            if os.path.islink(parent_dir) or os.path.isjunction(parent_dir):
+                raise ValueError("Recovery cleanup path traverses a replaced directory")
+            parent_dir = os.path.dirname(parent_dir)
+        if not os.path.lexists(filename):
+            continue
+        metadata = os.lstat(filename)
+        actual = stat_identity(metadata)
+        if stat.S_ISDIR(metadata.st_mode):
+            if actual[:FILE_OBJECT_IDENTITY_FIELDS] != tuple(expected)[:FILE_OBJECT_IDENTITY_FIELDS] or os.path.isjunction(filename):
+                raise ValueError("An owned directory changed; cleanup refused")
+            os.rmdir(filename)
+        else:
+            if actual != tuple(expected):
+                raise ValueError("An owned file changed; cleanup refused")
+            os.unlink(filename)