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

projectaria_debug_sharing/debug_sharing/_internal/spool.py

@@ -0,0 +1,673 @@
+# 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.
+
+"""
+Reports kept on disk between assembling one and sending it. Package-internal:
+nothing outside this package imports it.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import time
+import uuid
+from collections.abc import Collection, Iterable
+from dataclasses import astuple, dataclass
+from pathlib import Path, PurePosixPath
+from typing import Final
+
+from projectaria_commons.commons.constants import CONFIG_DIR
+from projectaria_debug_sharing.debug_sharing._internal.file_access import (
+    is_private_dir,
+    is_private_file,
+    leaf_name,
+    make_private_dir,
+    PRIVATE_DIR_MODE,
+    refuse_symlink,
+    write_private,
+)
+from projectaria_debug_sharing.debug_sharing._internal.manifest import (
+    Manifest,
+    MANIFEST_NAME,
+)
+from projectaria_debug_sharing.debug_sharing.types import (
+    Attachment,
+    DebugReport,
+    SpooledReportError,
+)
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+DEFAULT_SPOOL_DIR: Final[Path] = CONFIG_DIR / "debug-reports"
+
+FAILED_MARKER: Final[str] = ".failed"
+
+_RESERVED_NAMES: Final[frozenset[str]] = frozenset({MANIFEST_NAME, FAILED_MARKER})
+
+_STAGING_SUFFIX: Final[str] = ".tmp"
+_PREVIOUS_SUFFIX: Final[str] = ".old"
+_CLAIM_SUFFIX: Final[str] = ".sending"
+_FILED_SUFFIX: Final[str] = ".filed"
+
+_STAGING_MAX_AGE_SEC: Final[float] = 3600.0
+"""A save takes well under a second; a staging directory older than this was
+left by one that crashed."""
+
+_CLAIM_MAX_AGE_SEC: Final[float] = 3600.0
+"""A send takes seconds; a claim older than this was left by a drain that died.
+Nothing renews a live claim, so a send must end well within this. The FlyTrap
+submitter's `TOTAL_TIMEOUT_SEC` bounds its upload, but not the login refresh
+before it."""
+
+_DAY_SEC: Final[float] = 86400.0
+
+
+@dataclass(frozen=True)
+class Retention:
+    """How long a report stays on disk, counted from when it was saved."""
+
+    refused_duration_sec: float = 14 * _DAY_SEC
+
+    speculative_duration_sec: float = 3 * _DAY_SEC
+    """For a report collected on the user's behalf rather than at their request."""
+
+    max_duration_sec: float = 30 * _DAY_SEC
+    """Nothing outlives this, sent or not."""
+
+    def __post_init__(self) -> None:
+        if min(astuple(self)) < 0:
+            raise ValueError(f"retention durations must be non-negative, got {self}")
+
+
+class ReportSpool:
+    """
+    Reports kept on disk, readable by their owner only, until they are sent.
+
+    Each report is a directory named after its id, holding its attachments and
+    a manifest. A drain claims a report by renaming it, so two drains never
+    send the same one, and releases it if the send fails.
+    """
+
+    def __init__(
+        self, root: Path | None = None, retention: Retention | None = None
+    ) -> None:
+        """
+        Args:
+            root: Where reports are kept, `DEFAULT_SPOOL_DIR` unless given.
+                Created owner-only on the first save. Never used if it is a
+                symlink.
+            retention: How long reports are kept. Defaults to `Retention()`.
+        """
+        self._root: Path = root or DEFAULT_SPOOL_DIR
+        self._retention: Retention = retention or Retention()
+
+    @property
+    def root(self) -> Path:
+        """The directory reports are kept in."""
+        return self._root
+
+    def save(self, report: DebugReport, *, requested: bool = True) -> Path:
+        """
+        Saving an id that is already spooled replaces it, markers included: a
+        fresh save is a fresh attempt, and a stale `.failed` would stop it ever
+        being sent.
+
+        Args:
+            report: The report to keep.
+            requested: False for a report collected on the user's behalf rather
+                than at their request. It is kept for less time, and unattended
+                drains skip it.
+
+        Returns:
+            The report's directory.
+
+        Raises:
+            ValueError: The report id is not usable as a directory name.
+            OSError: The report could not be written, or the spool is a
+                symlink. A previous version of it is left in place.
+        """
+        report_dir = self._report_dir_for(report.report_id)
+        make_private_dir(self._root)
+        tag = uuid.uuid4().hex[:8]
+        staging = self._root / f".{report.report_id}.{tag}{_STAGING_SUFFIX}"
+        previous = self._root / f".{report.report_id}.{tag}{_PREVIOUS_SUFFIX}"
+        staging.mkdir(mode=PRIVATE_DIR_MODE)
+        try:
+            self._write_report(staging, report, requested)
+            self._swap_in(staging, report_dir, previous)
+        except BaseException:
+            shutil.rmtree(staging, ignore_errors=True)
+            raise
+        self._drop_previous(previous)
+        return report_dir
+
+    def load(self, report_dir: Path) -> DebugReport:
+        """
+        Reads a spooled report back. An attachment that is missing, unreadable
+        or changeable by another user is left out rather than failing the
+        report, which would lose all of it.
+
+        Args:
+            report_dir: The report's directory, as `pending`, `find` or `claim`
+                returned it.
+
+        Returns:
+            The report, under the id it was saved with.
+
+        Raises:
+            SpooledReportError: The report could have been changed by another
+                user, or is unreadable, or the spool is a symlink. A drain marks
+                it refused.
+        """
+        if self._root.is_symlink() or not is_private_dir(report_dir):
+            raise SpooledReportError(
+                f"{report_dir} is not a report directory that only you can change."
+            )
+        return self._load_report(report_dir, Manifest.read(report_dir))
+
+    def find(self, report_id: str) -> Path | None:
+        """
+        Args:
+            report_id: The id the report was saved under.
+
+        Returns:
+            The directory the report is kept in, refused or not; None when no
+            report with that id is kept, the id could never be saved, or the
+            spool is a symlink.
+        """
+        try:
+            report_dir = self._report_dir_for(report_id)
+        except ValueError:
+            return None
+        if self._root.is_symlink():
+            return None
+        return report_dir if is_private_dir(report_dir) else None
+
+    def pending(self, *, requested_only: bool = False) -> list[Path]:
+        """
+        Args:
+            requested_only: Also leave out reports collected on the user's
+                behalf. For an unattended drain, which may send what the user
+                asked for but nothing else.
+
+        Returns:
+            The directories of reports waiting to be sent, oldest save first.
+            Refused reports are left out. Empty when the spool does not exist.
+
+        Raises:
+            OSError: The spool cannot be listed, or is a symlink. Its reports
+                may still be waiting, so this is not reported as none.
+        """
+        unsent = [
+            report_dir
+            for report_dir in self._visible_dirs(self._children())
+            if is_private_dir(report_dir)
+            and not (report_dir / FAILED_MARKER).exists()
+            and (not requested_only or self.was_requested(report_dir))
+        ]
+        return sorted(unsent, key=self._saved_time_sec_for_sorting)
+
+    def was_requested(self, report_dir: Path) -> bool:
+        """
+        Args:
+            report_dir: The report's directory.
+
+        Returns:
+            Whether the user asked for this report to be sent. False for an
+            unreadable one: it can never be sent, and an unattended drain would
+            otherwise retry it forever.
+        """
+        try:
+            return Manifest.read(report_dir).requested
+        except SpooledReportError:
+            return False
+
+    def claim(self, report_dir: Path) -> Path | None:
+        """
+        Takes a report out of `pending` for sending.
+
+        Args:
+            report_dir: The report's directory, from `pending` or `find`.
+
+        Returns:
+            The claimed directory, or None if another drain claimed it first.
+
+        Raises:
+            OSError: The report is still there but could not be claimed, or the
+                spool is a symlink.
+        """
+        refuse_symlink(self._root)
+        claimed = report_dir.with_name(
+            f".{report_dir.name}.{int(time.time())}{_CLAIM_SUFFIX}"
+        )
+        try:
+            return report_dir.rename(claimed)
+        except FileNotFoundError:
+            return None
+
+    def release(self, claimed: Path, report_dir: Path) -> None:
+        """
+        Puts back a claimed report that was not filed. If its id was saved
+        again while it was claimed, the fresh save wins and the claimed copy is
+        deleted, just as saving an id always replaces it. A failure is logged,
+        and `prune` puts the claim back once it is old enough.
+
+        Args:
+            claimed: The directory `claim` returned.
+            report_dir: The directory the report was claimed from.
+        """
+        try:
+            if report_dir.exists():
+                shutil.rmtree(claimed)
+            else:
+                claimed.rename(report_dir)
+        except OSError as e:
+            logger.warning("Could not release %s: %s", report_dir.name, e.strerror or e)
+
+    def discard(self, report_dir: Path) -> bool:
+        """
+        Deletes a filed report. One that cannot be deleted is renamed out of
+        `pending` instead, for `prune` to remove later.
+
+        Args:
+            report_dir: The report's directory, claimed or not.
+
+        Returns:
+            False, logged, if the report is still where a drain would send it
+            again, or the spool is a symlink and nothing was touched.
+        """
+        if self._root.is_symlink():
+            logger.warning("Not discarding %s: the spool is a symlink", report_dir.name)
+            return False
+        return self._remove_tree(report_dir) or self._retire(report_dir)
+
+    def mark_failed(self, report_dir: Path, reason: str) -> bool:
+        """
+        Records that a report was refused, so drains stop sending it.
+
+        Args:
+            report_dir: The report's directory, claimed or not.
+            reason: Why it was refused, kept in the marker.
+
+        Returns:
+            False, logged, if the marker could not be written, or the spool is a
+            symlink.
+        """
+        if self._root.is_symlink():
+            logger.warning(
+                "Not marking %s refused: the spool is a symlink", report_dir.name
+            )
+            return False
+        try:
+            write_private(report_dir / FAILED_MARKER, f"{reason}\n".encode("utf-8"))
+        except OSError as e:
+            logger.warning(
+                "Could not mark %s refused: %s", report_dir.name, e.strerror or e
+            )
+            return False
+        return True
+
+    def secure(self) -> None:
+        """
+        Makes the spool and each report directory in it owner-only, in case
+        something created them readable by others. Directory modes are the
+        protection: a file inside an owner-only directory is out of other
+        users' reach whatever its own mode, so files are left as they are.
+        Failures are logged rather than raised.
+
+        A report directory others could write to is left as it is, so it is
+        never trusted and `prune` removes it: tightening it would vouch for
+        contents that may already have been changed. A spool that is a symlink
+        is left alone: changing it would change wherever it points.
+        """
+        if self._root.is_symlink():
+            logger.warning("Not securing %s: it is a symlink", self._root)
+            return
+        if not self._root.is_dir():
+            return
+        visible = self._visible_dirs(self._children_or_empty())
+        for directory in visible:
+            if not is_private_dir(directory):
+                logger.warning(
+                    "Not sending %s: other users could have changed it",
+                    directory.name,
+                )
+        trusted = [d for d in visible if is_private_dir(d)]
+        for directory in [self._root, *trusted]:
+            try:
+                directory.chmod(PRIVATE_DIR_MODE)
+            except OSError as e:
+                logger.warning("Could not restrict %s: %s", directory, e.strerror or e)
+
+    def prune(self) -> int:
+        """
+        Deletes reports past their `Retention` window, and tidies up after saves
+        and sends that crashed. Failures are logged rather than raised.
+
+        A report the user asked to send is kept while it might still be sent,
+        up to `max_duration_sec`. One collected on their behalf goes after
+        `speculative_duration_sec`, and a refused one after
+        `refused_duration_sec`. Ages count from the save, so being refused late
+        does not extend a report's life.
+
+        Returns:
+            How many directories were removed.
+        """
+        children = self._children_or_empty()
+        if not children:
+            return 0
+        now_time_sec = time.time()
+        removed = self._recover(self._hidden_dirs(children), now_time_sec)
+        for report_dir in self._visible_dirs(self._children_or_empty()):
+            if self._is_expired(report_dir, now_time_sec):
+                removed += self._remove_expired(report_dir)
+        if removed:
+            logger.info("Removed %d expired or leftover directories", removed)
+        return removed
+
+    def _report_dir_for(self, report_id: str) -> Path:
+        """
+        Raises:
+            ValueError: `report_id` is not a plain name, so as a directory it
+                could escape the spool, or it starts with "." like the spool's
+                own staging and claimed directories.
+        """
+        if (
+            not report_id
+            or report_id.startswith(".")
+            or leaf_name(report_id) != report_id
+        ):
+            raise ValueError(
+                f"report_id {report_id!r} is not usable as a directory name"
+            )
+        return self._root / report_id
+
+    def _children(self) -> list[Path]:
+        """
+        Empty when the spool is missing, which a running drain can meet if the
+        spool is removed under it.
+
+        Raises:
+            OSError: The spool cannot be listed, or is a symlink, which could
+                point anywhere.
+        """
+        refuse_symlink(self._root)
+        try:
+            return list(self._root.iterdir())
+        except FileNotFoundError:
+            return []
+
+    def _children_or_empty(self) -> list[Path]:
+        """`_children`, or empty, logged: tidying up can wait for the next drain."""
+        try:
+            return self._children()
+        except OSError as e:
+            logger.warning("Could not list the spool: %s", e.strerror or e)
+            return []
+
+    @staticmethod
+    def _visible_dirs(children: Iterable[Path]) -> list[Path]:
+        """Directories that are not the spool's hidden staging, claims or retirees."""
+        return [
+            d
+            for d in children
+            if not d.name.startswith(".") and d.is_dir() and not d.is_symlink()
+        ]
+
+    @staticmethod
+    def _hidden_dirs(children: Iterable[Path]) -> list[Path]:
+        return [d for d in children if d.name.startswith(".") and is_private_dir(d)]
+
+    def _is_expired(self, report_dir: Path, now_time_sec: float) -> bool:
+        """False when the report's age cannot be read: unknown is not old."""
+        saved_time_sec = self._saved_time_sec(report_dir)
+        if saved_time_sec is None:
+            return False
+        return now_time_sec - saved_time_sec >= self._window_duration_sec(report_dir)
+
+    def _window_duration_sec(self, report_dir: Path) -> float:
+        retention = self._retention
+        if (report_dir / FAILED_MARKER).exists():
+            return min(retention.refused_duration_sec, retention.max_duration_sec)
+        if not self.was_requested(report_dir):
+            return min(retention.speculative_duration_sec, retention.max_duration_sec)
+        return retention.max_duration_sec
+
+    def _remove_expired(self, report_dir: Path) -> int:
+        """
+        Logs the removal of a report the user asked to send, since that
+        discards their evidence unsent.
+        """
+        if not (report_dir / FAILED_MARKER).exists() and self.was_requested(report_dir):
+            logger.warning(
+                "Discarding %s: never delivered, and older than %g days",
+                report_dir.name,
+                self._retention.max_duration_sec / _DAY_SEC,
+            )
+        return 1 if self._remove_tree(report_dir) else 0
+
+    def _recover(self, hidden_dirs: Iterable[Path], now_time_sec: float) -> int:
+        """
+        Tidies up after saves and sends that crashed, returning how many
+        directories went. A version a save moved aside, or a claim a dead drain
+        abandoned, is put back unless a newer save replaced it, in which case it
+        goes. So does a staging directory older than any save takes, and a filed
+        report `discard` could only rename.
+        """
+        removed = 0
+        for hidden in hidden_dirs:
+            if self._is_set_aside(hidden, now_time_sec):
+                target = self._root / self._report_id_of(hidden)
+                if not target.exists():
+                    self._restore(hidden, target)
+                    continue
+            elif not self._is_leftover(hidden, now_time_sec):
+                continue
+            removed += 1 if self._remove_tree(hidden) else 0
+        return removed
+
+    @classmethod
+    def _write_report(
+        cls, report_dir: Path, report: DebugReport, requested: bool
+    ) -> None:
+        stored: dict[str, str] = {}
+        content_types: dict[str, str] = {}
+        for attachment in report.attachments:
+            file_name = cls._stored_file_name(attachment, taken=stored.keys())
+            if file_name:
+                write_private(report_dir / file_name, attachment.data)
+                stored[file_name] = attachment.name
+                content_types[file_name] = attachment.content_type
+        Manifest(
+            report_id=report.report_id,
+            description=report.description,
+            source_app=report.source_app,
+            created_time_sec=time.time(),
+            requested=requested,
+            metadata=dict(report.metadata),
+            attachments=stored,
+            content_types=content_types,
+        ).write(report_dir)
+
+    @staticmethod
+    def _stored_file_name(attachment: Attachment, *, taken: Collection[str]) -> str:
+        """
+        The file an attachment is stored as: its file name, made unique and kept
+        off the spool's own files, or "" if it has no usable name.
+        """
+        name = leaf_name(attachment.filename or attachment.name)
+        if not name:
+            logger.warning(
+                "Dropping attachment %r: no usable file name", attachment.name
+            )
+            return ""
+        path = PurePosixPath(name)
+        candidate = name
+        suffix = 1
+        while candidate in _RESERVED_NAMES or candidate in taken:
+            suffix += 1
+            candidate = f"{path.stem}_{suffix}{path.suffix}"
+        if candidate != name:
+            logger.warning("Storing attachment %s as %s", name, candidate)
+        return candidate
+
+    @classmethod
+    def _drop_previous(cls, previous: Path) -> None:
+        """
+        Deletes the version a save replaced. One that cannot be deleted is
+        retired for `prune` to remove, rather than left looking like a crash's
+        leftover, which `prune` would put back.
+        """
+        if previous.exists() and not cls._remove_tree(previous):
+            cls._retire(previous)
+
+    @staticmethod
+    def _swap_in(staging: Path, report_dir: Path, previous: Path) -> None:
+        """
+        Moves any existing version aside rather than deleting it, so a crash
+        between the two renames leaves it for `prune` to put back.
+        """
+        if report_dir.exists():
+            report_dir.replace(previous)
+        staging.replace(report_dir)
+
+    @classmethod
+    def _load_report(cls, report_dir: Path, manifest: Manifest) -> DebugReport:
+        attachments = (
+            cls._load_attachment(
+                report_dir, file_name, name, manifest.content_types[file_name]
+            )
+            for file_name, name in manifest.attachments.items()
+        )
+        return manifest.to_report(tuple(a for a in attachments if a is not None))
+
+    @staticmethod
+    def _load_attachment(
+        report_dir: Path, file_name: str, name: str, content_type: str
+    ) -> Attachment | None:
+        """None, logged, for a file that is not safe to read or cannot be read."""
+        if leaf_name(file_name) != file_name or file_name in _RESERVED_NAMES:
+            logger.warning("Skipping %r: not an attachment file name", file_name)
+            return None
+        path = report_dir / file_name
+        if not is_private_file(path):
+            logger.warning(
+                "Skipping %s: missing, a link, or changeable by another user",
+                file_name,
+            )
+            return None
+        try:
+            data = path.read_bytes()
+        except OSError as e:
+            logger.warning("Skipping %s: unreadable: %s", file_name, e.strerror or e)
+            return None
+        return Attachment(
+            name=name, data=data, content_type=content_type, filename=file_name
+        )
+
+    @classmethod
+    def _saved_time_sec(cls, report_dir: Path) -> float | None:
+        """
+        When the report was saved. For one whose manifest is unreadable, when
+        its directory last changed, so it still ages out. None if neither can be
+        read.
+        """
+        try:
+            return Manifest.read(report_dir).created_time_sec
+        except SpooledReportError:
+            return cls._modified_time_sec(report_dir)
+
+    @classmethod
+    def _saved_time_sec_for_sorting(cls, report_dir: Path) -> float:
+        """A report that vanished mid-scan, so has no age, sorts first."""
+        saved_time_sec = cls._saved_time_sec(report_dir)
+        return 0.0 if saved_time_sec is None else saved_time_sec
+
+    @staticmethod
+    def _modified_time_sec(path: Path) -> float | None:
+        try:
+            return path.stat().st_mtime
+        except OSError:
+            return None
+
+    @staticmethod
+    def _remove_tree(path: Path) -> bool:
+        """Deletes `path`. False, logged, if it is still there."""
+        try:
+            shutil.rmtree(path)
+        except OSError as e:
+            logger.warning("Could not remove %s: %s", path.name, e.strerror or e)
+            return False
+        return not path.exists()
+
+    @staticmethod
+    def _retire(report_dir: Path) -> bool:
+        retired = report_dir.with_name(f".{report_dir.name.lstrip('.')}{_FILED_SUFFIX}")
+        try:
+            report_dir.rename(retired)
+        except OSError as e:
+            logger.warning("Could not retire %s: %s", report_dir.name, e.strerror or e)
+            return False
+        return True
+
+    @staticmethod
+    def _report_id_of(hidden: Path) -> str:
+        return hidden.name[1:].rsplit(".", 2)[0]
+
+    @classmethod
+    def _is_set_aside(cls, hidden: Path, now_time_sec: float) -> bool:
+        """
+        A version a crashed save moved aside, or a claim abandoned by a drain
+        that died. A younger moved-aside version belongs to a save still in
+        progress.
+        """
+        if hidden.name.endswith(_PREVIOUS_SUFFIX):
+            return cls._is_older_than(hidden, now_time_sec, _STAGING_MAX_AGE_SEC)
+        if not hidden.name.endswith(_CLAIM_SUFFIX):
+            return False
+        try:
+            claimed_time_sec = int(hidden.name.rsplit(".", 2)[1])
+        except (IndexError, ValueError):
+            return False
+        return claimed_time_sec < now_time_sec - _CLAIM_MAX_AGE_SEC
+
+    @classmethod
+    def _is_leftover(cls, hidden: Path, now_time_sec: float) -> bool:
+        """A filed report `discard` could only rename, or a crashed save's staging."""
+        if hidden.name.endswith(_FILED_SUFFIX):
+            return True
+        if not hidden.name.endswith(_STAGING_SUFFIX):
+            return False
+        return cls._is_older_than(hidden, now_time_sec, _STAGING_MAX_AGE_SEC)
+
+    @classmethod
+    def _is_older_than(
+        cls, path: Path, now_time_sec: float, age_duration_sec: float
+    ) -> bool:
+        """False when the age cannot be read: unknown is not old."""
+        modified_time_sec = cls._modified_time_sec(path)
+        return (
+            modified_time_sec is not None
+            and modified_time_sec <= now_time_sec - age_duration_sec
+        )
+
+    @staticmethod
+    def _restore(moved: Path, target: Path) -> None:
+        try:
+            moved.replace(target)
+        except OSError as e:
+            logger.warning("Could not restore %s: %s", target.name, e.strerror or e)
+            return
+        logger.warning("Restored %s after an interrupted save or send", target.name)