projectaria-debug-sharing 0.1.0__py3-none-any.whl

projectaria_debug_sharing/debug_sharing/_internal/plain_files.py

@@ -0,0 +1,208 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Reading plain files without following links, for collectors whose paths a user
+or another process could swap underneath them.
+"""
+
+from __future__ import annotations
+
+import errno
+import fnmatch
+import logging
+import os
+import time
+from pathlib import Path
+from stat import S_ISDIR, S_ISLNK, S_ISREG
+from typing import BinaryIO, Final
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+ZIP_EARLIEST: Final[tuple[int, ...]] = (1980, 1, 1, 0, 0, 0)
+ZIP_LATEST: Final[tuple[int, ...]] = (2107, 12, 31, 23, 59, 58)
+
+
+def open_plain_file(path: Path) -> BinaryIO:
+    """
+    Opens `path` only if it is a plain file itself, not a link to one, and is
+    still the file that was opened.
+
+    Returns:
+        The open handle, which the caller closes.
+
+    Raises:
+        IsADirectoryError: `path` is a directory.
+        OSError: `path` is a link, FIFO or other special file, or was swapped
+            for another file while being opened.
+    """
+    handle = os.fdopen(os.open(path, _read_flags()), "rb")
+    try:
+        opened = os.fstat(handle.fileno())
+        if S_ISDIR(opened.st_mode):
+            raise IsADirectoryError(errno.EISDIR, "Is a directory", str(path))
+        if not _is_same_plain_file(opened, path.lstat()):
+            raise OSError(errno.EINVAL, "Refusing anything but a plain file", str(path))
+    except BaseException:
+        handle.close()
+        raise
+    return handle
+
+
+def open_directory(path: Path) -> int:
+    """
+    A handle on the directory itself, so entries are opened relative to it
+    and a root swapped afterwards is not followed.
+
+    Returns:
+        The directory's file descriptor, which the caller closes.
+
+    Raises:
+        OSError: `path` is a symlink, or the platform has no directory handles
+            (Windows), where there is no race-free way to read it.
+    """
+    if os.open not in os.supports_dir_fd or not hasattr(os, "O_DIRECTORY"):
+        raise OSError(
+            errno.ENOTSUP, "No race-free directory handle on this platform", str(path)
+        )
+    try:
+        return os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    except NotADirectoryError:
+        if path.is_symlink():
+            raise OSError(errno.ELOOP, "Refusing a symlinked directory", str(path))
+        raise
+
+
+def list_own_plain_files(dir_fd: int, pattern: str = "*") -> list[str]:
+    """
+    Lists the plain files directly in the directory that match `pattern` and
+    belong to this user. Other users' files in a shared directory are not ours
+    to upload. An entry that cannot be examined is skipped with a warning.
+
+    Args:
+        dir_fd: The directory, as from `open_directory`.
+        pattern: A glob the file names must match.
+
+    Returns:
+        The file names, newest first.
+
+    Raises:
+        OSError: The directory cannot be listed.
+    """
+    entries = []
+    with os.scandir(dir_fd) as found:
+        for entry in found:
+            try:
+                info = entry.stat(follow_symlinks=False)
+            except OSError as e:
+                logger.warning("Skipping %s: %s", entry.name, e.strerror or e)
+                continue
+            if (
+                S_ISREG(info.st_mode)
+                and _belongs_to_user(info)
+                and fnmatch.fnmatchcase(entry.name, pattern)
+            ):
+                entries.append((info.st_mtime, entry.name))
+    return [name for _, name in sorted(entries, reverse=True)]
+
+
+def open_plain_file_at(
+    name: str, dir_fd: int
+) -> tuple[BinaryIO, os.stat_result] | None:
+    """
+    Opens a directory entry listed by `list_own_plain_files`, checking the
+    opened file is still that entry and still this user's.
+
+    Args:
+        name: The entry's name.
+        dir_fd: The directory, as from `open_directory`.
+
+    Returns:
+        The open handle, which the caller closes, and its stat; or None if
+        the entry is no longer this user's plain file.
+
+    Raises:
+        OSError: The entry cannot be opened or examined, as when it is a link
+            or has been removed.
+    """
+    handle = os.fdopen(os.open(name, _read_flags(), dir_fd=dir_fd), "rb")
+    try:
+        opened = os.fstat(handle.fileno())
+        current = os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
+    except BaseException:
+        handle.close()
+        raise
+    if not (_is_same_plain_file(opened, current) and _belongs_to_user(opened)):
+        handle.close()
+        return None
+    return handle, opened
+
+
+def zip_date_time(modified_time_sec: float) -> tuple[int, ...]:
+    """
+    Args:
+        modified_time_sec: A modification time, in seconds since the epoch.
+
+    Returns:
+        The local time, clamped to what a ZIP entry can store.
+    """
+    try:
+        local = tuple(time.localtime(modified_time_sec)[:6])
+    except (OverflowError, OSError, ValueError):
+        return ZIP_EARLIEST if modified_time_sec < 0 else ZIP_LATEST
+    return min(max(local, ZIP_EARLIEST), ZIP_LATEST)
+
+
+def describe_entry(path: Path) -> dict[str, object]:
+    """
+    Describes a directory entry without following it if it is a link.
+
+    Args:
+        path: The entry.
+
+    Returns:
+        Its name and kind, and its size if it is a plain file.
+
+    Raises:
+        OSError: The entry cannot be examined.
+    """
+    info = path.lstat()
+    entry: dict[str, object] = {"name": path.name, "is_dir": S_ISDIR(info.st_mode)}
+    if S_ISLNK(info.st_mode):
+        entry["is_symlink"] = True
+    elif S_ISREG(info.st_mode):
+        entry["size_bytes"] = info.st_size
+    return entry
+
+
+def _read_flags() -> int:
+    """O_NONBLOCK, so opening a FIFO planted at the path does not hang."""
+    return (
+        os.O_RDONLY
+        | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_NONBLOCK", 0)
+        | getattr(os, "O_BINARY", 0)
+    )
+
+
+def _is_same_plain_file(opened: os.stat_result, current: os.stat_result) -> bool:
+    return S_ISREG(opened.st_mode) and (opened.st_dev, opened.st_ino) == (
+        current.st_dev,
+        current.st_ino,
+    )
+
+
+def _belongs_to_user(info: os.stat_result) -> bool:
+    """Always True on Windows, which has no POSIX owner to compare."""
+    return not hasattr(os, "getuid") or info.st_uid == os.getuid()