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

projectaria_debug_sharing/debug_sharing/facade.py

@@ -0,0 +1,435 @@
+# 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.
+
+"""`ProjectAriaDebugSharing`, the one object a tool builds to file a report."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Final
+
+from projectaria_debug_sharing.debug_sharing._internal.delivery import ReportDelivery
+from projectaria_debug_sharing.debug_sharing._internal.spool import ReportSpool
+from projectaria_debug_sharing.debug_sharing.collectors import (
+    Collector,
+    EnvironmentCollector,
+)
+from projectaria_debug_sharing.debug_sharing.submitter import (
+    Delivery,
+    DrainResult,
+    SubmissionError,
+    Submitter,
+)
+from projectaria_debug_sharing.debug_sharing.types import (
+    Attachment,
+    CollectionScope,
+    CollectorFailure,
+    ConsentDeclinedError,
+    ConsentRequest,
+    ConsentSource,
+    DebugReport,
+    NoConsentBasisError,
+    OfferedCollector,
+    RequestConsent,
+    ShareOutcome,
+)
+
+__all__ = [
+    "COLLECTOR_FAILURES_METADATA_KEY",
+    "CONSENT_METADATA_KEY",
+    "CONSENT_SOURCE_METADATA_KEY",
+    "CollectionScope",
+    "CollectorFailure",
+    "ConsentDeclinedError",
+    "ConsentRequest",
+    "Delivery",
+    "DrainResult",
+    "NoConsentBasisError",
+    "OfferedCollector",
+    "ProjectAriaDebugSharing",
+    "RESERVED_METADATA_KEYS",
+    "RequestConsent",
+    "ShareOutcome",
+    "SubmissionError",
+]
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+CONSENT_METADATA_KEY: Final[str] = "consent"
+"""Report metadata naming the granted scopes, comma-separated."""
+
+CONSENT_SOURCE_METADATA_KEY: Final[str] = "consent_source"
+"""Report metadata naming the `ConsentSource` of that grant."""
+
+COLLECTOR_FAILURES_METADATA_KEY: Final[str] = "collector_failures"
+"""Report metadata naming each failed collector as `name:ExceptionType`,
+comma-separated. Absent when every granted collector succeeded."""
+
+RESERVED_METADATA_KEYS: Final[frozenset[str]] = frozenset(
+    {CONSENT_METADATA_KEY, CONSENT_SOURCE_METADATA_KEY, COLLECTOR_FAILURES_METADATA_KEY}
+)
+"""Metadata keys the sharer sets, which `collect` and `share` refuse from the
+tool."""
+
+
+class ProjectAriaDebugSharing:
+    """
+    Assembles and submits a debug report. The tool supplies its collectors and
+    submitter; this owns what every tool shares: consent, correlation, running
+    collectors concurrently, partial failures, and keeping a report that could
+    not be sent until a later `drain`.
+    """
+
+    def __init__(
+        self,
+        *,
+        source_app: str,
+        submitter: Submitter,
+        request_consent: RequestConsent | None = None,
+        distribution: str | None = None,
+        spool_dir: Path | None = None,
+    ) -> None:
+        """
+        Args:
+            source_app: The tool filing reports.
+            submitter: Where reports are sent.
+            request_consent: Asks the user what may be collected. Without it,
+                every `collect` must say how consent was obtained (`granted=`).
+            distribution: The tool's installed package; adds an
+                `EnvironmentCollector` for it.
+            spool_dir: Where reports are kept until they are sent. Defaults to
+                the directory every Project Aria tool shares, so any of them
+                can send what another kept.
+        """
+        self._source_app = source_app
+        self._submitter = submitter
+        self._request_consent = request_consent
+        self._spool = ReportSpool(spool_dir)
+        self._collectors: list[Collector] = []
+        if distribution is not None:
+            self._collectors.append(EnvironmentCollector(distribution=distribution))
+
+    @property
+    def collectors(self) -> tuple[Collector, ...]:
+        """The registered collectors, in registration order."""
+        return tuple(self._collectors)
+
+    @property
+    def offered_scopes(self) -> frozenset[CollectionScope]:
+        """The consent categories the registered collectors read under."""
+        return frozenset(c.scope for c in self._collectors)
+
+    def register(self, collector: Collector) -> None:
+        """
+        Adds a collector. Order is kept; collection itself is concurrent.
+
+        Raises:
+            ValueError: A collector with that name is already registered; its
+                attachment would collide with this one's.
+        """
+        if any(c.name == collector.name for c in self._collectors):
+            raise ValueError(
+                f"a collector named {collector.name!r} is already registered"
+            )
+        self._collectors.append(collector)
+
+    async def share(
+        self,
+        *,
+        description: str,
+        metadata: Mapping[str, str] | None = None,
+        report_id: str | None = None,
+    ) -> ShareOutcome:
+        """
+        Asks for consent, collects, and submits.
+
+        Args:
+            description: What went wrong, in the user's words.
+            metadata: Tool fields for the report. The `RESERVED_METADATA_KEYS`
+                are reserved.
+            report_id: Correlates this report with another; generated if None.
+
+        Returns:
+            The bug id, report id and any collectors that failed.
+
+        Raises:
+            ValueError: `metadata` uses a reserved key.
+            ConsentDeclinedError: The user declined.
+            NoConsentBasisError: There is no consent prompt.
+            SubmissionError: The report was not filed; it carries the report.
+        """
+        report, failures = await self.collect(
+            description=description, metadata=metadata, report_id=report_id
+        )
+        bug_id = await self.submit(report)
+        return ShareOutcome(
+            bug_id=bug_id, report_id=report.report_id, failures=failures
+        )
+
+    async def submit(self, report: DebugReport) -> str:
+        """
+        Sends a report that `collect` produced.
+
+        Args:
+            report: The report. It must carry the consent record `collect`
+                writes, so nothing reaches Meta without one.
+
+        Returns:
+            The bug id.
+
+        Raises:
+            NoConsentBasisError: The report has no consent record.
+            SubmissionError: The report was not filed. It carries the report,
+                so the caller can keep it rather than lose the user's work.
+        """
+        self._require_consent_record(report)
+        try:
+            bug_id = await self._submitter.submit(report)
+        except SubmissionError as e:
+            if e.report is None:
+                e.report = report
+            raise
+        logger.info("Submitted debug report %s as bug %s", report.report_id, bug_id)
+        return bug_id
+
+    async def deliver(self, report: DebugReport) -> Delivery:
+        """
+        Sends a report that `collect` produced, and keeps it for `drain` if
+        that fails and a retry could succeed. A refused report is not kept. A
+        copy `keep` saved earlier is held back from drains during the send,
+        removed once the report is filed or refused, and put back if the send
+        is cancelled.
+        Cancelling a send with no earlier copy keeps nothing.
+
+        Args:
+            report: The report. It must carry the consent record `collect`
+                writes.
+
+        Returns:
+            The bug id; or the error, and where the report was kept.
+
+        Raises:
+            NoConsentBasisError: The report has no consent record. It is
+                neither sent nor kept.
+        """
+        self._require_consent_record(report)
+        return await ReportDelivery(self, self._spool).deliver(report)
+
+    async def drain(self, *, requested_only: bool = False) -> DrainResult:
+        """
+        Sends the reports kept for later, oldest first, deleting each once it
+        is filed. The spool may hold reports other tools kept. One with no
+        consent record is refused rather than sent, so it never stops a drain.
+
+        Args:
+            requested_only: Send only reports the user asked to send, not ones
+                collected on their behalf. For a drain the user did not start.
+
+        Returns:
+            The bug ids filed, and how many reports are still waiting or were
+            refused.
+
+        Raises:
+            OSError: The spool cannot be listed, or is a symlink, so whether any
+                report is waiting is unknown.
+        """
+        delivery = ReportDelivery(
+            _ConsentCheckedSubmitter(self._submitter), self._spool
+        )
+        return await delivery.drain(requested_only=requested_only)
+
+    def keep(self, report: DebugReport, *, requested: bool = True) -> Path:
+        """
+        Keeps a report for `drain` without sending it, for example while the
+        tool finishes work the report should mention. Keeping the same report
+        again replaces the copy. Until `deliver` claims it, the copy is an
+        ordinary kept report: a drain, in this process or another, may send it
+        first, and the report is then filed twice.
+
+        Args:
+            report: The report. It must carry the consent record `collect`
+                writes.
+            requested: False for a report collected on the user's behalf rather
+                than at their request. It is kept for less time, and
+                `drain(requested_only=True)` skips it.
+
+        Returns:
+            Where the report is kept.
+
+        Raises:
+            NoConsentBasisError: The report has no consent record.
+            ValueError: The report id is not usable as a directory name.
+            OSError: The report could not be written.
+        """
+        self._require_consent_record(report)
+        return self._spool.save(report, requested=requested)
+
+    async def collect(
+        self,
+        *,
+        description: str,
+        metadata: Mapping[str, str] | None = None,
+        report_id: str | None = None,
+        granted: frozenset[CollectionScope] | None = None,
+    ) -> tuple[DebugReport, tuple[CollectorFailure, ...]]:
+        """
+        Assembles a report without sending it. Only collectors whose scope was
+        granted run, and the report records the grant and where it came from.
+        A scope nobody was offered is never recorded.
+
+        Args:
+            description: What went wrong, in the user's words.
+            metadata: Tool fields for the report. The `RESERVED_METADATA_KEYS`
+                are reserved.
+            report_id: Correlates this report with another; generated if None.
+            granted: Scopes the calling tool already has the user's consent
+                for, recorded as `ConsentSource.CALLER`. None asks through
+                `request_consent`, recorded as `ConsentSource.PROMPTED`.
+
+        Returns:
+            The report, and the collectors that failed.
+
+        Raises:
+            ValueError: `metadata` uses a reserved key. Checked before
+                asking, so the user is not prompted for a request that cannot
+                succeed.
+            ConsentDeclinedError: The user declined.
+            NoConsentBasisError: There is no prompt and no `granted`.
+        """
+        metadata = dict(metadata or {})
+        if metadata.keys() & RESERVED_METADATA_KEYS:
+            raise ValueError(
+                f"{sorted(RESERVED_METADATA_KEYS)} are reserved for the sharer"
+            )
+        offered = tuple((c, c.scope) for c in self._collectors)
+        if granted is None:
+            granted, source = await self._ask_for_consent(offered)
+        else:
+            source = ConsentSource.CALLER
+        granted = frozenset(granted) & frozenset(scope for _, scope in offered)
+        metadata[CONSENT_METADATA_KEY] = ",".join(sorted(s.value for s in granted))
+        metadata[CONSENT_SOURCE_METADATA_KEY] = source.value
+
+        attachments, failures = await self._run_consented_collectors(offered, granted)
+        if failures:
+            metadata[COLLECTOR_FAILURES_METADATA_KEY] = ",".join(
+                f"{f.collector_name}:{f.error_type}" for f in failures
+            )
+        report = DebugReport(
+            report_id=report_id or str(uuid.uuid4()),
+            description=description,
+            source_app=self._source_app,
+            attachments=attachments,
+            metadata=metadata,
+        )
+        return report, failures
+
+    async def _ask_for_consent(
+        self, offered: Sequence[tuple[Collector, CollectionScope]]
+    ) -> tuple[frozenset[CollectionScope], ConsentSource]:
+        """
+        Args:
+            offered: Each collector with its scope, read once per `collect` so
+                the prompt and the run cannot disagree about it.
+
+        Raises:
+            NoConsentBasisError: There is no prompt. Fails closed: granting
+                everything would let a tool that forgot its prompt upload
+                whatever its collectors reach, recordings included.
+            ConsentDeclinedError: The user declined.
+        """
+        if self._request_consent is None:
+            raise NoConsentBasisError(
+                "No request_consent callback and no explicit `granted` set. "
+                "Pass one: a callback to ask the user, or granted= to record "
+                "consent the tool obtained itself."
+            )
+        request = ConsentRequest(
+            source_app=self._source_app,
+            offered=tuple(
+                OfferedCollector(name=c.name, scope=scope, disclosure=c.disclosure)
+                for c, scope in offered
+            ),
+        )
+        granted = await self._request_consent(request)
+        if granted is None:
+            raise ConsentDeclinedError("User declined to share debug information")
+        return granted, ConsentSource.PROMPTED
+
+    @staticmethod
+    def _require_consent_record(report: DebugReport) -> None:
+        """
+        Raises:
+            NoConsentBasisError: The report has no consent record.
+        """
+        if CONSENT_SOURCE_METADATA_KEY not in report.metadata:
+            raise NoConsentBasisError(
+                f"Report {report.report_id} has no consent record; build it with collect()"
+            )
+
+    @staticmethod
+    async def _run_consented_collectors(
+        offered: Sequence[tuple[Collector, CollectionScope]],
+        granted: frozenset[CollectionScope],
+    ) -> tuple[tuple[Attachment, ...], tuple[CollectorFailure, ...]]:
+        """
+        Runs the granted collectors concurrently. One that raises is reported as
+        a failure; cancellation and other process-level exits are re-raised,
+        since they mean the process is going away, not that a collector is
+        broken.
+        """
+        consented = [c for c, scope in offered if scope in granted]
+        results = await asyncio.gather(
+            *(c.collect() for c in consented), return_exceptions=True
+        )
+        attachments: list[Attachment] = []
+        failures: list[CollectorFailure] = []
+        for collector, result in zip(consented, results):
+            if isinstance(result, BaseException) and not isinstance(result, Exception):
+                raise result
+            if isinstance(result, Exception):
+                logger.warning(
+                    "Collector %s failed: %s", collector.name, result, exc_info=result
+                )
+                failures.append(
+                    CollectorFailure(
+                        collector_name=collector.name,
+                        error=str(result) or type(result).__name__,
+                        error_type=type(result).__name__,
+                    )
+                )
+                continue
+            attachments.extend(result)
+        return tuple(attachments), tuple(failures)
+
+
+class _ConsentCheckedSubmitter(Submitter):
+    """
+    Refuses, rather than sends, a kept report with no consent record. A refusal
+    is marked and skipped, where `NoConsentBasisError` would stop the drain.
+    """
+
+    def __init__(self, submitter: Submitter) -> None:
+        self._submitter = submitter
+
+    async def submit(self, report: DebugReport) -> str:
+        if CONSENT_SOURCE_METADATA_KEY not in report.metadata:
+            raise SubmissionError(
+                f"Report {report.report_id} has no consent record", retryable=False
+            )
+        return await self._submitter.submit(report)