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

projectaria_debug_sharing/debug_sharing/_internal/report_command.py

@@ -0,0 +1,560 @@
+# 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.
+
+"""What `aria-debug-report` runs, built on `ProjectAriaDebugSharing`."""
+
+from __future__ import annotations
+
+import asyncio
+import getpass
+import json
+import logging
+import sys
+from collections.abc import AsyncIterator, Mapping, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import ClassVar, Final
+
+from projectaria_debug_sharing.debug_sharing._internal.plain_files import (
+    open_plain_file,
+)
+from projectaria_debug_sharing.debug_sharing.collectors import Collector, FileCollector
+from projectaria_debug_sharing.debug_sharing.facade import (
+    CollectorFailure,
+    ConsentDeclinedError,
+    Delivery,
+    DrainResult,
+    OfferedCollector,
+    ProjectAriaDebugSharing,
+    RequestConsent,
+    RESERVED_METADATA_KEYS,
+)
+from projectaria_debug_sharing.debug_sharing.flytrap import (
+    DEV_SERVER_ENV,
+    FlyTrapSubmissionError,
+    FlyTrapSubmitter,
+    NotLoggedInError,
+    REPORT_BUG_URL,
+    report_bug_url,
+)
+from projectaria_debug_sharing.debug_sharing.submitter import Submitter
+from projectaria_login import (
+    AuthenticationConfig,
+    FileEncryptionKeyRequest,
+    KeyRequestPurpose,
+    ProjectAriaLogin,
+)
+
+CLI_LOGGER_NAME: Final[str] = "projectaria_debug_sharing.debug_sharing.cli"
+"""The logger whose lines reach the console without `--verbose`. Named
+explicitly: as the binary's `__main__`, `cli`'s `__name__` falls outside the
+package logger the console handler is attached to."""
+
+logger: logging.Logger = logging.getLogger(CLI_LOGGER_NAME)
+
+
+def debug_sharing_auth_config() -> AuthenticationConfig:
+    """The application `aria-debug-report` logs in as: ARK Debug Sharing.
+
+    Every value is one an installed client may carry. The FB part is the app's
+    client token, never its secret: device login accepts it, and the server
+    fetches the secret itself when it mints the ID token. The FRL client token
+    is Project Aria Login's until Debug Sharing's own is issued; only the
+    password login reads it.
+    """
+    return AuthenticationConfig(
+        fb_app_access_token="2004636393387720|867e3e56220e91334bd008e8607090f9",
+        client_token="FRL|1563499658844492|888ed02d3443510a67c96e63d4d71b7b",
+        client_application=29261831290084371,
+    )
+
+
+class ReportInputError(Exception):
+    """The user mistyped something. Reported as one line, not a traceback."""
+
+
+@dataclass(frozen=True)
+class ReportInput:
+    """What the user asked to send. Build it with `from_command_line`."""
+
+    description: str
+    attachments: tuple[Path, ...] = ()
+    metadata: Mapping[str, str] = field(default_factory=dict)
+
+    _JSON_FIELDS: ClassVar[frozenset[str]] = frozenset(
+        {"description", "attachments", "metadata"}
+    )
+    """The keys `--from-json` accepts. `ClassVar`, since a dataclass makes a
+    `Final` annotation a field."""
+
+    @classmethod
+    def from_command_line(
+        cls,
+        *,
+        description: str = "",
+        attachments: Sequence[Path] = (),
+        metadata: Sequence[tuple[str, str]] = (),
+        from_json: Path | None = None,
+    ) -> ReportInput:
+        """
+        Checks the `submit` flags, or reads `--from-json`, before anything logs
+        in, so a mistyped path fails before authentication starts.
+
+        Args:
+            description: `--description`.
+            attachments: Each `--attach`.
+            metadata: Each `--metadata KEY=VALUE`.
+            from_json: `--from-json`, which replaces the other three.
+
+        Returns:
+            The checked input; every attachment is a plain file that opens.
+
+        Raises:
+            ReportInputError: Anything the user mistyped, including flags that
+                `--from-json` would silently override, no description, a
+                metadata key the consent record owns, or an attachment that
+                cannot be read.
+        """
+        if from_json is not None:
+            if description or attachments or metadata:
+                raise ReportInputError(
+                    "--from-json cannot be combined with --description, --attach "
+                    "or --metadata"
+                )
+            return cls._from_json(from_json)
+        if not description:
+            raise ReportInputError("--description is required: say what went wrong")
+        return cls._checked(description, attachments, dict(metadata))
+
+    @classmethod
+    def _from_json(cls, path: Path) -> ReportInput:
+        fields = cls._read_json_object(path)
+        unknown = fields.keys() - cls._JSON_FIELDS
+        if unknown:
+            raise ReportInputError(
+                f"{path}: unknown field(s) {', '.join(sorted(unknown))}"
+            )
+        description = fields.get("description")
+        if not isinstance(description, str) or not description:
+            raise ReportInputError(f"{path}: description must be a non-empty string")
+        listed = fields.get("attachments", [])
+        if not isinstance(listed, list) or not all(isinstance(p, str) for p in listed):
+            raise ReportInputError(f"{path}: attachments must be a list of paths")
+        metadata = fields.get("metadata", {})
+        if not isinstance(metadata, dict) or not all(
+            isinstance(v, str) for v in metadata.values()
+        ):
+            raise ReportInputError(f"{path}: metadata must be an object of strings")
+        return cls._checked(description, [Path(p) for p in listed], metadata)
+
+    @staticmethod
+    def _read_json_object(path: Path) -> dict[str, object]:
+        try:
+            fields = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as e:
+            raise ReportInputError(f"{path} could not be read: {e}") from e
+        if not isinstance(fields, dict):
+            raise ReportInputError(f"{path} must contain a JSON object")
+        return fields
+
+    @classmethod
+    def _checked(
+        cls, description: str, attachments: Sequence[Path], metadata: dict[str, str]
+    ) -> ReportInput:
+        reserved = metadata.keys() & RESERVED_METADATA_KEYS
+        if reserved:
+            raise ReportInputError(
+                f"metadata key(s) {', '.join(sorted(reserved))} are reserved for "
+                "the sharer"
+            )
+        for path in attachments:
+            try:
+                open_plain_file(path).close()
+            except OSError as e:
+                raise ReportInputError(
+                    f"could not attach {path}: {e.strerror or type(e).__name__}"
+                ) from e
+        return cls(
+            description=description, attachments=tuple(attachments), metadata=metadata
+        )
+
+
+class DebugReportCommand:
+    """
+    Runs one `aria-debug-report` command through `ProjectAriaDebugSharing`:
+    files a report, which the sharer keeps if sending fails, or drains what is
+    kept.
+
+    Another tool's command line can run the same commands under its own
+    identity, with collectors of its own and a consent prompt. It says what
+    happened in its own words by overriding the `report_*` methods.
+    """
+
+    SOURCE_APP: Final[str] = "aria_debug_report"
+    """The name `aria-debug-report` files under, and the default `source_app`.
+    A tool that runs the command passes its own; no command line can set it,
+    so a report cannot claim another app."""
+
+    _CONTENT_TYPES: Final[Mapping[str, str]] = {
+        ".txt": "text/plain",
+        ".log": "text/plain",
+        ".json": "application/json",
+    }
+    """The type an attachment is sent as, by suffix; anything else is binary."""
+
+    def __init__(
+        self,
+        *,
+        source_app: str = SOURCE_APP,
+        auth_config: AuthenticationConfig | None = None,
+        distribution: str | None = None,
+        request_consent: RequestConsent | None = None,
+        spool_dir: Path | None = None,
+        submitter: Submitter | None = None,
+    ) -> None:
+        """
+        Args:
+            source_app: The tool filing the report.
+            auth_config: The application the login presents. Defaults to ARK
+                Debug Sharing's.
+            distribution: The tool's installed package, described in the
+                report's environment.
+            request_consent: Asks the user what may be collected, for
+                `submit(..., ask=True)`.
+            spool_dir: Where unsent reports are kept. Defaults to the spool
+                every Project Aria tool shares; the command line deliberately
+                offers no other location.
+            submitter: Where reports are sent. Defaults to FlyTrap, over the
+                saved Project Aria login, opened for each command.
+        """
+        self._source_app = source_app
+        self._auth_config = auth_config
+        self._distribution = distribution
+        self._request_consent = request_consent
+        self._spool_dir = spool_dir
+        self._submitter = submitter
+
+    async def submit(
+        self,
+        report_input: ReportInput,
+        *,
+        collectors: Sequence[Collector] = (),
+        report_id: str | None = None,
+        ask: bool = False,
+    ) -> int:
+        """
+        Files one report. Without `ask`, running the command is the user's
+        consent: naming a file on the command line, or a host's `--yes`, so
+        the report records everything offered as granted by the caller. The
+        console says only what happened and quotes the bug id; the error
+        itself, which can carry server detail, is logged at DEBUG for
+        `--verbose`.
+
+        Args:
+            report_input: The checked command line.
+            collectors: The calling tool's own collectors. One that fails is
+                reported with `report_collector_failure` and the report is
+                filed without it. They run with the attachments, so anything
+                one does while collecting has happened even if an attachment
+                then stops the report.
+            report_id: Correlates the report with another, such as the bug
+                report the glasses file; generated if None.
+            ask: Ask with the `request_consent` given at construction.
+
+        Returns:
+            0 when filed, else 1, including when the user declines.
+
+        Raises:
+            ReportInputError: PROJECTARIA_DEV_SERVER is malformed, checked
+                before logging in; a collector's name is already taken; or an
+                attachment could not be read after all, in which case the
+                report is not sent.
+            ValueError: `ask` without a `request_consent`.
+        """
+        if ask and self._request_consent is None:
+            raise ValueError("ask=True needs a request_consent")
+        self._check_destination()
+        async with self._open_submitter() as submitter:
+            sharer = self._sharer(submitter)
+            paths = self._register_attachments(sharer, report_input.attachments)
+            self._register_host_collectors(sharer, collectors)
+            if not ask:
+                self.report_consent_given(self._offered(sharer))
+            try:
+                report, failures = await sharer.collect(
+                    description=report_input.description,
+                    metadata=report_input.metadata,
+                    report_id=report_id,
+                    granted=None if ask else sharer.offered_scopes,
+                )
+            except ConsentDeclinedError:
+                return self.report_cancelled()
+            self._report_failures(failures, paths)
+            delivery = await sharer.deliver(report)
+        return self.report_delivery(delivery)
+
+    @staticmethod
+    def _register_host_collectors(
+        sharer: ProjectAriaDebugSharing, collectors: Sequence[Collector]
+    ) -> None:
+        for collector in collectors:
+            try:
+                sharer.register(collector)
+            except ValueError as e:
+                # A name already taken, such as by an attachment's stem.
+                raise ReportInputError(str(e)) from e
+
+    @staticmethod
+    def _offered(sharer: ProjectAriaDebugSharing) -> tuple[OfferedCollector, ...]:
+        return tuple(
+            OfferedCollector(c.name, c.scope, c.disclosure) for c in sharer.collectors
+        )
+
+    def _report_failures(
+        self, failures: Sequence[CollectorFailure], paths: Mapping[str, Path]
+    ) -> None:
+        """
+        Says each of the tool's own failed collectors, then raises for the
+        first attachment that could not be read. The tool's failures come
+        first: they are part of what the user sees even when an attachment
+        stops the report.
+
+        Raises:
+            ReportInputError: An attachment could not be read.
+        """
+        attachment_failures = [f for f in failures if f.collector_name in paths]
+        for failure in failures:
+            if failure.collector_name not in paths:
+                self.report_collector_failure(failure)
+        if attachment_failures:
+            failure = attachment_failures[0]
+            raise ReportInputError(
+                f"could not attach {paths[failure.collector_name]}: {failure.error}"
+            )
+
+    async def drain(self) -> int:
+        """
+        Sends every kept report. Running it by hand is the user asking, so it
+        includes reports they were offered but never asked to send.
+
+        Returns:
+            0 when nothing is left over, else 1, including when the kept
+            reports cannot be read. Never a count, which the process exit
+            status would wrap.
+
+        Raises:
+            ReportInputError: PROJECTARIA_DEV_SERVER is malformed. Checked
+                before logging in.
+        """
+        self._check_destination()
+        async with self._open_submitter() as submitter:
+            try:
+                result = await self._sharer(submitter).drain()
+            except OSError as e:
+                logger.error(
+                    "Could not read the kept reports: %s",
+                    e.strerror or type(e).__name__,
+                )
+                return 1
+        return self._report_drain(result)
+
+    def _sharer(self, submitter: Submitter) -> ProjectAriaDebugSharing:
+        return ProjectAriaDebugSharing(
+            source_app=self._source_app,
+            submitter=submitter,
+            request_consent=self._request_consent,
+            distribution=self._distribution,
+            spool_dir=self._spool_dir,
+        )
+
+    @classmethod
+    def _register_attachments(
+        cls, sharer: ProjectAriaDebugSharing, attachments: Sequence[Path]
+    ) -> dict[str, Path]:
+        """
+        Registers a `FileCollector` per attachment, named after the file's stem
+        and numbered when stems repeat, since the sharer refuses two collectors
+        with one name.
+
+        Returns:
+            Each collector's name, mapped to its file.
+        """
+        paths: dict[str, Path] = {}
+        for path in attachments:
+            name = path.stem
+            count = 1
+            while name in paths:
+                count += 1
+                name = f"{path.stem}-{count}"
+            paths[name] = path
+            sharer.register(
+                FileCollector(
+                    name,
+                    path,
+                    disclosure=f"the file {path}",
+                    content_type=cls._CONTENT_TYPES.get(
+                        path.suffix.lower(), "application/octet-stream"
+                    ),
+                )
+            )
+        return paths
+
+    def report_consent_given(self, offered: tuple[OfferedCollector, ...]) -> None:
+        """
+        Called when running the command was the consent, just before
+        collecting; collection can still fail after it, and then nothing is
+        sent. Says nothing by default: `aria-debug-report` sends only the files
+        its user named.
+
+        Args:
+            offered: Everything the report will collect.
+        """
+
+    def report_cancelled(self) -> int:
+        """
+        Says the user declined, when `submit` asked.
+
+        Returns:
+            The exit code.
+        """
+        logger.error("Report cancelled. Nothing was sent.")
+        return 1
+
+    def report_collector_failure(self, failure: CollectorFailure) -> None:
+        """
+        Says one of the calling tool's collectors failed. The report is filed
+        without it.
+
+        Args:
+            failure: Which collector, and why.
+        """
+        logger.warning(
+            "Could not collect %s: %s", failure.collector_name, failure.error
+        )
+
+    def report_delivery(self, delivery: Delivery) -> int:
+        """
+        Says what happened to the report. The error itself, which can quote the
+        server's response, goes to DEBUG only.
+
+        Args:
+            delivery: What happened.
+
+        Returns:
+            The exit code: 0 when filed, else 1.
+        """
+        if delivery.bug_id is not None:
+            logger.info("Filed as bug %s", delivery.bug_id)
+            return 0
+        logger.debug("Not filed: %s", delivery.error)
+        logged_out = isinstance(delivery.error, NotLoggedInError)
+        if logged_out:
+            logger.error(
+                "Not logged in to Project Aria, or the saved login could not be "
+                "unlocked, so the report was not sent."
+            )
+        if delivery.will_retry:
+            logger.error(
+                "The report could not be sent. Kept at %s; the next drain sends it.",
+                delivery.spooled,
+            )
+            if logged_out:
+                logger.error(
+                    "Log in to Project Aria, then run: aria-debug-report drain"
+                )
+            else:
+                logger.error(
+                    "To retry it now and see why it failed, run: "
+                    "aria-debug-report drain --verbose"
+                )
+            return 1
+        if delivery.error is not None and not delivery.error.retryable:
+            logger.error("The report was not accepted, so it will not be retried.")
+        else:
+            logger.error("The report could not be sent, and could not be kept either.")
+        logger.error("Run with --verbose for details.")
+        return 1
+
+    @staticmethod
+    def _report_drain(result: DrainResult) -> int:
+        if not (result.sent or result.waiting or result.rejected):
+            logger.info("Nothing pending.")
+            return 0
+        logger.info(
+            "Filed %d, %d still waiting, %d will not be sent",
+            len(result.sent),
+            result.waiting,
+            result.rejected,
+        )
+        if not (result.waiting or result.rejected):
+            return 0
+        logger.error("Run with --verbose for details.")
+        return 1
+
+    @asynccontextmanager
+    async def _open_submitter(self) -> AsyncIterator[Submitter]:
+        """The given submitter, or FlyTrap over the saved login; there is no token flag."""
+        if self._submitter is not None:
+            yield self._submitter
+            return
+        async with ProjectAriaLogin(
+            self._auth_config or debug_sharing_auth_config(),
+            on_need_file_encryption_key=self.ask_for_login_passphrase,
+        ) as login:
+            yield FlyTrapSubmitter(login=login)
+
+    @staticmethod
+    async def ask_for_login_passphrase(
+        request: FileEncryptionKeyRequest,
+    ) -> str | None:
+        """
+        The passphrase protecting a saved login, for machines with no keyring.
+
+        Args:
+            request: What the login wants the key for.
+
+        Returns:
+            The typed passphrase. None without a terminal to ask at, and for a
+            new login, which this tool never saves: `projectaria_login login`
+            does.
+        """
+        if request.purpose is not KeyRequestPurpose.LOAD or not sys.stdin.isatty():
+            return None
+        try:
+            return await asyncio.to_thread(
+                getpass.getpass, "Project Aria login passphrase: "
+            )
+        except EOFError:
+            return None
+
+    @staticmethod
+    def _check_destination() -> None:
+        """
+        Warns on the console when PROJECTARIA_DEV_SERVER sends reports
+        somewhere other than production; the library says so only at DEBUG.
+
+        Raises:
+            ReportInputError: PROJECTARIA_DEV_SERVER is set but malformed.
+                Checked before logging in, so it is a usage error rather than
+                a failed send.
+        """
+        try:
+            url = report_bug_url()
+        except FlyTrapSubmissionError as e:
+            raise ReportInputError(str(e)) from e
+        if url != REPORT_BUG_URL:
+            logger.warning(
+                "Sending to %s, not production: %s is set", url, DEV_SERVER_ENV
+            )