ruyi 0.44.0a20251118__py3-none-any.whl → 0.45.0__py3-none-any.whl

ruyi/telemetry/provider.py

@@ -7,6 +7,7 @@ import time
 from typing import Callable, TYPE_CHECKING, cast
 import uuid
 
+from ..i18n import _, d_
 from ..log import RuyiLogger
 from ..utils.node_info import NodeInfo, gather_node_info
 from .scope import TelemetryScope
@@ -18,23 +19,32 @@ if TYPE_CHECKING:
 
 FALLBACK_PM_TELEMETRY_ENDPOINT = "https://api.ruyisdk.cn/telemetry/pm/"
 
-TELEMETRY_CONSENT_AND_UPLOAD_DESC = """
-RuyiSDK collects anonymized usage data locally to help us improve the product.
+TELEMETRY_CONSENT_AND_UPLOAD_DESC = d_(
+    """
+RuyiSDK collects minimal usage data in the form of just a version number of
+the running [yellow]ruyi[/], to help us improve the product. With your consent,
+RuyiSDK may also collect additional non-tracking usage data to be sent
+periodically. The data will be recorded and processed by RuyiSDK team-managed
+servers located in the Chinese mainland.
 
 [green]By default, nothing leaves your machine[/], and you can also turn off usage data
-collection completely. Only with your explicit permission can [yellow]ruyi[/] upload
-collected telemetry, periodically to RuyiSDK team-managed servers located in
-the Chinese mainland. You can change this setting at any time by running
+collection completely. Only with your explicit permission can [yellow]ruyi[/] collect and
+upload more usage data. You can change this setting at any time by running
 [yellow]ruyi telemetry consent[/], [yellow]ruyi telemetry local[/], or [yellow]ruyi telemetry optout[/].
 
-If you enable uploads now, we'll also send a one-time report from this [yellow]ruyi[/]
-installation so the RuyiSDK team can better understand adoption. Thank you for
-helping us build a better experience!
+We'll also send a one-time report from this [yellow]ruyi[/] installation so the RuyiSDK
+team can better understand adoption. If you choose to opt out, this will be the
+only data to be ever uploaded, without any tracking ID being generated or kept.
+Thank you for helping us build a better experience!
 """
-TELEMETRY_CONSENT_AND_UPLOAD_PROMPT = (
-    "Enable telemetry uploads and send a one-time report now?"
 )
-TELEMETRY_OPTOUT_PROMPT = "\nDo you want to disable telemetry entirely?"
+TELEMETRY_CONSENT_AND_UPLOAD_PROMPT = d_(
+    "Do you agree to have usage data periodically uploaded?"
+)
+TELEMETRY_OPTOUT_PROMPT = d_("\nDo you want to opt out of telemetry entirely?")
+MALFORMED_TELEMETRY_STATE_MSG = d_(
+    "malformed telemetry state: unable to determine upload weekday, nothing will be uploaded"
+)
 
 
 def next_utc_weekday(wday: int, now: float | None = None) -> int:
@@ -108,29 +118,35 @@ def set_telemetry_mode(
         return
     match mode:
         case "on":
-            logger.I("telemetry data uploading is now enabled")
+            logger.I(_("telemetry data uploading is now enabled"))
             logger.I(
-                "you can opt out at any time by running [yellow]ruyi telemetry optout[/]"
+                _(
+                    "you can opt out at any time by running [yellow]ruyi telemetry optout[/]"
+                )
             )
         case "local":
-            logger.I("telemetry mode is now set to local collection only")
+            logger.I(_("telemetry mode is now set to local collection only"))
             logger.I(
-                "you can re-enable telemetry data uploading at any time by running [yellow]ruyi telemetry consent[/]"
+                _(
+                    "you can re-enable telemetry data uploading at any time by running [yellow]ruyi telemetry consent[/]"
+                )
             )
             logger.I(
-                "or opt out at any time by running [yellow]ruyi telemetry optout[/]"
+                _("or opt out at any time by running [yellow]ruyi telemetry optout[/]")
             )
         case "off":
-            logger.I("telemetry data collection is now disabled")
+            logger.I(_("telemetry data collection is now disabled"))
             logger.I(
-                "you can re-enable telemetry data uploads at any time by running [yellow]ruyi telemetry consent[/]"
+                _(
+                    "you can re-enable telemetry data uploads at any time by running [yellow]ruyi telemetry consent[/]"
+                )
             )
         case _:
             raise ValueError(f"invalid telemetry mode: {mode}")
 
 
 class TelemetryProvider:
-    def __init__(self, gc: "GlobalConfig") -> None:
+    def __init__(self, gc: "GlobalConfig", minimal: bool) -> None:
         self.state_root = pathlib.Path(gc.telemetry_root)
 
         self._discard_events = False
@@ -138,6 +154,7 @@ class TelemetryProvider:
         self._is_first_run = False
         self._stores: dict[TelemetryScope, TelemetryStore] = {}
         self._upload_on_exit = False
+        self.minimal = minimal
 
         # create the PM store
         self.init_store(TelemetryScope(None))
@@ -154,6 +171,8 @@ class TelemetryProvider:
 
     @property
     def upload_consent_time(self) -> datetime.datetime | None:
+        if self.minimal or self.local_mode:
+            return None
         return self._gc.telemetry_upload_consent_time
 
     def store(self, scope: TelemetryScope) -> TelemetryStore | None:
@@ -203,11 +222,18 @@ class TelemetryProvider:
     def installation_file(self) -> pathlib.Path:
         return self.state_root / "installation.json"
 
+    @property
+    def minimal_installation_marker_file(self) -> pathlib.Path:
+        return self.state_root / "minimal-installation-marker"
+
     def check_first_run_status(self) -> None:
         """Check if this is the first run of the application by checking if installation file exists.
         This must be done before init_installation() is potentially called.
         """
-        self._is_first_run = not self.installation_file.exists()
+        self._is_first_run = (
+            not self.installation_file.exists()
+            and not self.minimal_installation_marker_file.exists()
+        )
 
     @property
     def is_first_run(self) -> bool:
@@ -215,9 +241,15 @@ class TelemetryProvider:
         return self._is_first_run
 
     def init_installation(self, force_reinit: bool) -> NodeInfo | None:
+        if self.minimal:
+            # be extra safe by not reading or writing installation data at all
+            # in minimal mode
+            self._init_minimal_installation_marker(force_reinit)
+            return None
+
         installation_file = self.installation_file
         if installation_file.exists() and not force_reinit:
-            return self.read_installation_data()
+            return self._read_installation_data()
 
         # either this is a fresh installation or we're forcing a refresh
         installation_id = uuid.uuid4()
@@ -232,13 +264,26 @@ class TelemetryProvider:
             fp.write(json.dumps(installation_data).encode("utf-8"))
         return installation_data
 
-    def read_installation_data(self) -> NodeInfo | None:
+    def _init_minimal_installation_marker(self, force_reinit: bool) -> None:
+        if self.minimal_installation_marker_file.exists() and not force_reinit:
+            return
+
+        self.logger.D("initializing minimal installation marker file")
+        self.state_root.mkdir(parents=True, exist_ok=True)
+
+        # just touch the file
+        self.minimal_installation_marker_file.touch()
+
+    def _read_installation_data(self) -> NodeInfo | None:
         with open(self.installation_file, "rb") as fp:
             return cast(NodeInfo, json.load(fp))
 
-    def upload_weekday(self) -> int | None:
+    def _upload_weekday(self) -> int | None:
+        if self.minimal:
+            return None
+
         try:
-            installation_data = self.read_installation_data()
+            installation_data = self._read_installation_data()
         except FileNotFoundError:
             # init the node info if it's gone
             installation_data = self.init_installation(False)
@@ -253,120 +298,240 @@ class TelemetryProvider:
 
         return report_uuid_prefix % 7  # 0 is Monday
 
-    def has_upload_consent(self, time_now: float | None = None) -> bool:
+    def _has_upload_consent(self, time_now: float | None = None) -> bool:
         if self.upload_consent_time is None:
             return False
         if time_now is None:
             time_now = time.time()
         return self.upload_consent_time.timestamp() <= time_now
 
-    def print_telemetry_notice(self, for_cli_verbose_output: bool = False) -> None:
-        if self.local_mode:
-            if for_cli_verbose_output:
-                self.logger.I(
-                    "telemetry mode is [green]local[/]: local data collection only, no uploads"
-                )
-            return
-
-        now = time.time()
-        if self.has_upload_consent(now) and not for_cli_verbose_output:
-            self.logger.D("user has consented to telemetry upload")
-            return
-
-        upload_wday = self.upload_weekday()
-        if upload_wday is None:
-            return
-        upload_wday_name = calendar.day_name[upload_wday]
-
+    def _print_upload_schedule_notice(self, upload_wday: int, now: float) -> None:
         next_upload_day_ts = next_utc_weekday(upload_wday, now)
         next_upload_day = time.localtime(next_upload_day_ts)
         next_upload_day_end = time.localtime(next_upload_day_ts + 86400)
         next_upload_day_str = time.strftime("%Y-%m-%d %H:%M:%S %z", next_upload_day)
         next_upload_day_end_str = time.strftime(
-            "%Y-%m-%d %H:%M:%S %z", next_upload_day_end
+            "%Y-%m-%d %H:%M:%S %z",
+            next_upload_day_end,
         )
 
-        today_is_upload_day = self.is_upload_day(now)
-        if for_cli_verbose_output:
-            self.logger.I(
-                "telemetry mode is [green]on[/]: data is collected and periodically uploaded"
-            )
-            self.logger.I(
-                f"non-tracking usage information will be uploaded to RuyiSDK-managed servers [bold green]every {upload_wday_name}[/]"
-            )
-        else:
-            self.logger.W(
-                f"this [yellow]ruyi[/] installation has telemetry mode set to [yellow]on[/], and [bold]will upload non-tracking usage information to RuyiSDK-managed servers[/] [bold green]every {upload_wday_name}[/]"
-            )
-
-        if today_is_upload_day:
+        if self._is_upload_day(now):
             for scope, store in self._stores.items():
-                has_uploaded_today = self.has_uploaded_today(scope, now)
+                has_uploaded_today = self._has_uploaded_today(
+                    store.last_upload_timestamp,
+                    now,
+                )
                 if has_uploaded_today:
                     if last_upload_time := store.last_upload_timestamp:
                         last_upload_time_str = time.strftime(
                             "%Y-%m-%d %H:%M:%S %z", time.localtime(last_upload_time)
                         )
                         self.logger.I(
-                            f"scope {scope}: usage information has already been uploaded today at {last_upload_time_str}"
+                            _(
+                                "scope {scope}: usage information has already been uploaded today at {last_upload_time_str}"
+                            ).format(
+                                scope=scope,
+                                last_upload_time_str=last_upload_time_str,
+                            )
                         )
                     else:
                         self.logger.I(
-                            f"scope {scope}: usage information has already been uploaded sometime today"
+                            _(
+                                "scope {scope}: usage information has already been uploaded sometime today"
+                            ).format(
+                                scope=scope,
+                            )
                         )
                 else:
                     self.logger.I(
-                        f"scope {scope}: the next upload will happen [bold green]today[/] if not already"
+                        _(
+                            "scope {scope}: the next upload will happen [bold green]today[/] if not already"
+                        ).format(
+                            scope=scope,
+                        )
                     )
         else:
             self.logger.I(
-                f"the next upload will happen anytime [yellow]ruyi[/] is executed between [bold green]{next_upload_day_str}[/] and [bold green]{next_upload_day_end_str}[/]"
+                _("the next upload will happen anytime [yellow]ruyi[/] is executed:")
+            )
+            self.logger.I(
+                _(
+                    "  - between [bold green]{time_start}[/] and [bold green]{time_end}[/]"
+                ).format(
+                    time_start=next_upload_day_str,
+                    time_end=next_upload_day_end_str,
+                )
             )
+            self.logger.I(_("  - or if the last upload is more than a week ago"))
+
+    def print_telemetry_notice(self, for_cli_verbose_output: bool = False) -> None:
+        if self.minimal:
+            if for_cli_verbose_output:
+                self.logger.I(
+                    _(
+                        "telemetry mode is [green]off[/]: nothing is collected or uploaded after the first run"
+                    )
+                )
+            return
+
+        now = time.time()
+        upload_wday = self._upload_weekday()
+        if upload_wday is None:
+            if for_cli_verbose_output:
+                self.logger.W(MALFORMED_TELEMETRY_STATE_MSG)
+            else:
+                self.logger.D(MALFORMED_TELEMETRY_STATE_MSG)
+            return
+
+        upload_wday_name = self._gc.babel_locale.days["format"]["wide"][upload_wday]
+
+        if self.local_mode:
+            if for_cli_verbose_output:
+                self.logger.I(
+                    _(
+                        "telemetry mode is [green]local[/]: local usage collection only, no usage uploads except if requested"
+                    )
+                )
+            return
+
+        if self._has_upload_consent(now) and not for_cli_verbose_output:
+            self.logger.D("user has consented to telemetry upload")
+            return
+
+        if for_cli_verbose_output:
+            self.logger.I(
+                _(
+                    "telemetry mode is [green]on[/]: usage data is collected and periodically uploaded"
+                )
+            )
+            self.logger.I(
+                _(
+                    "non-tracking usage information will be uploaded to RuyiSDK-managed servers [bold green]every {weekday}[/]"
+                ).format(
+                    weekday=upload_wday_name,
+                )
+            )
+        else:
+            self.logger.W(
+                _(
+                    "this [yellow]ruyi[/] installation has telemetry mode set to [yellow]on[/], and [bold]will upload non-tracking usage information to RuyiSDK-managed servers[/] [bold green]every {weekday}[/]"
+                ).format(
+                    weekday=upload_wday_name,
+                )
+            )
+
+        self._print_upload_schedule_notice(upload_wday, now)
 
         if not for_cli_verbose_output:
-            self.logger.I("in order to hide this banner:")
-            self.logger.I("- opt out with [yellow]ruyi telemetry optout[/]")
-            self.logger.I("- or give consent with [yellow]ruyi telemetry consent[/]")
+            self.logger.I(_("in order to hide this banner:"))
+            self.logger.I(_(" - opt out with [yellow]ruyi telemetry optout[/]"))
+            self.logger.I(
+                _(" - or give consent with [yellow]ruyi telemetry consent[/]")
+            )
 
-    def next_upload_day(self, time_now: float | None = None) -> int | None:
-        upload_wday = self.upload_weekday()
+    def _next_upload_day(self, time_now: float | None = None) -> int | None:
+        upload_wday = self._upload_weekday()
         if upload_wday is None:
             return None
         return next_utc_weekday(upload_wday, time_now)
 
-    def is_upload_day(self, time_now: float | None = None) -> bool:
+    def _is_upload_day(self, time_now: float | None = None) -> bool:
         if time_now is None:
             time_now = time.time()
-        if upload_day := self.next_upload_day(time_now):
+        if upload_day := self._next_upload_day(time_now):
             return upload_day <= time_now
         return False
 
-    def has_uploaded_today(
+    def _has_uploaded_today(
         self,
-        scope: TelemetryScope,
+        last_upload_time: float | None,
         time_now: float | None = None,
     ) -> bool:
         if time_now is None:
             time_now = time.time()
-        if upload_day := self.next_upload_day(time_now):
+        if upload_day := self._next_upload_day(time_now):
             upload_day_end = upload_day + 86400
-            store = self.store(scope)
-            if store is None:
-                return False
-            if last_upload_time := store.last_upload_timestamp:
+            if last_upload_time is not None:
                 return upload_day <= last_upload_time < upload_day_end
         return False
 
     def record(self, scope: TelemetryScope, kind: str, **params: object) -> None:
+        if self.minimal:
+            self.logger.D(
+                f"minimal telemetry mode enabled, discarding event '{kind}' for scope {scope}"
+            )
+            return
+
         if store := self.store(scope):
             return store.record(kind, **params)
-        self.logger.D(f"no telemetry store for scope {scope}, discarding event")
+        self.logger.D(
+            f"no telemetry store for scope {scope}, discarding event '{kind}'"
+        )
 
     def discard_events(self, v: bool = True) -> None:
         self._discard_events = v
 
-    def flush(self, *, upload_now: bool = False) -> None:
-        now = time.time()
+    def _should_proceed_with_upload(
+        self,
+        scope: TelemetryScope,
+        explicit_request: bool,
+        cron_mode: bool,
+        now: float,
+    ) -> tuple[bool, str]:
+        # proceed to uploading if forced (explicit requested or _upload_on_exit)
+        # regardless of schedule
+        if explicit_request:
+            return True, "explicit request"
+        if self._upload_on_exit:
+            return True, "first-run upload on exit"
+
+        # this is not an explicitly requested upload, so only proceed if today
+        # is the day, or if the last upload is more than a week ago
+        #
+        # the last-upload-more-than-a-week-ago check is to avoid situations
+        # where the user has not run ruyi for a long time, thus missing
+        # the scheduled upload day.
+        #
+        # cron jobs are a mitigation, but we cannot rely on them either, because:
+        #
+        # * ruyi is more likely installed user-locally than system-wide, so
+        #   users may not set up cron jobs for themselves;
+        # * telemetry data is always recorded per user so system-wide cron jobs
+        #   cannot easily access this data.
+        last_upload_time: float | None = None
+        if store := self.store(scope):
+            last_upload_time = store.last_upload_timestamp
+
+        if not self._is_upload_day(now):
+            if last_upload_time is not None and now - last_upload_time >= 7 * 86400:
+                return True, "last upload more than a week ago"
+            return False, "not upload day"
+        # now we're sure today is the day
+
+        # if we're in cron mode, proceed as if it's an explicit request;
+        # otherwise, only proceed if mode is "on" and we haven't uploaded yet today
+        # for this scope
+        if cron_mode:
+            return True, "cron mode upload on upload day"
+
+        if self._gc.telemetry_mode != "on":
+            return False, "telemetry mode not 'on'"
+
+        if not self._has_uploaded_today(last_upload_time, now):
+            return True, "upload day, not yet uploaded today"
+        return False, "upload day, already uploaded today"
+
+    def flush(self, *, upload_now: bool = False, cron_mode: bool = False) -> None:
+        """
+        Flush collected telemetry data to persistent store, and upload if needed.
+
+        :param upload_now: Upload data right now regardless of schedule.
+        :type upload_now: bool
+        :param cron_mode: Whether this flush is called from a cron job. If true,
+            non-upload-day uploads will be skipped, otherwise acts just like
+            explicit uploads via `ruyi telemetry upload`.
+        :type cron_mode: bool
+        """
 
         # We may be self-uninstalling and purging all state data, and in this
         # case we don't want to record anything (thus re-creating directories).
@@ -374,31 +539,50 @@ class TelemetryProvider:
             self.logger.D("discarding collected telemetry data")
             return
 
-        self.logger.D("flushing telemetry to persistent store")
+        now = time.time()
+
+        def should_proceed(scope: TelemetryScope) -> tuple[bool, str]:
+            return self._should_proceed_with_upload(
+                scope,
+                explicit_request=upload_now,
+                cron_mode=cron_mode,
+                now=now,
+            )
+
+        if self.minimal:
+            if not self._upload_on_exit:
+                self.logger.D("skipping upload for non-first-run in minimal mode")
+                return
+
+            for scope, store in self._stores.items():
+                go_ahead, reason = should_proceed(scope)
+                self.logger.D(
+                    f"minimal telemetry upload check for scope {scope}: go_ahead={go_ahead}, reason={reason}"
+                )
+                if not go_ahead:
+                    continue
+                store.upload_minimal()
+            return
 
         for scope, store in self._stores.items():
+            self.logger.D(f"flushing telemetry to persistent store for scope {scope}")
             store.persist(now)
 
-            # try to upload if forced (upload_now or _upload_on_exit), or:
-            #
-            # * we're not in local mode
-            # * today is the day
-            # * we haven't uploaded today
-            if not (upload_now or self._upload_on_exit) and (
-                self.local_mode
-                or not self.is_upload_day(now)
-                or self.has_uploaded_today(scope, now)
-            ):
+            go_ahead, reason = should_proceed(scope)
+            self.logger.D(
+                f"regular telemetry upload check for scope {scope}: go_ahead={go_ahead}, reason={reason}"
+            )
+            if not go_ahead:
                 continue
 
-            self.prepare_data_for_upload(store)
-            self.upload_staged_payloads(store)
+            self._prepare_data_for_upload(store)
+            store.upload_staged_payloads()
 
-    def prepare_data_for_upload(self, store: TelemetryStore) -> None:
+    def _prepare_data_for_upload(self, store: TelemetryStore) -> None:
         installation_data: NodeInfo | None = None
         if store.scope.is_pm:
             try:
-                installation_data = self.read_installation_data()
+                installation_data = self._read_installation_data()
             except FileNotFoundError:
                 # should not happen due to is_upload_day() initializing it for us
                 # beforehand, but proceed without node info nonetheless
@@ -406,28 +590,32 @@ class TelemetryProvider:
 
         return store.prepare_data_for_upload(installation_data)
 
-    def upload_staged_payloads(self, store: TelemetryStore) -> None:
-        if self.local_mode:
-            return
-
-        return store.upload_staged_payloads()
-
     def oobe_prompt(self) -> None:
         """Ask whether the user consents to a first-run telemetry upload, and
         persist the user's exact telemetry choice."""
 
+        if self._gc.is_telemetry_optout:
+            # user has already explicitly opted out via the environment variable,
+            # don't bother asking
+            return
+
+        # We always report installation info on first run, regardless of
+        # user's telemetry choice. In case the user opts out, only do a one-time
+        # upload now, and never upload anything again.
+        self._upload_on_exit = True
+
         from ..cli import user_input
 
-        self.logger.stdout(TELEMETRY_CONSENT_AND_UPLOAD_DESC)
+        self.logger.stdout(_(TELEMETRY_CONSENT_AND_UPLOAD_DESC))
         if not user_input.ask_for_yesno_confirmation(
             self.logger,
-            TELEMETRY_CONSENT_AND_UPLOAD_PROMPT,
+            _(TELEMETRY_CONSENT_AND_UPLOAD_PROMPT),
             False,
         ):
             # ask if the user wants to opt out entirely
             if user_input.ask_for_yesno_confirmation(
                 self.logger,
-                TELEMETRY_OPTOUT_PROMPT,
+                _(TELEMETRY_OPTOUT_PROMPT),
                 False,
             ):
                 set_telemetry_mode(self._gc, "off")
@@ -441,4 +629,3 @@ class TelemetryProvider:
 
         consent_time = datetime.datetime.now().astimezone()
         set_telemetry_mode(self._gc, "on", consent_time)
-        self._upload_on_exit = True