feat: allow configure behavior on temporary check errors

Instead of blindly treating temporarily failing checks as activity, let
the user decide how to treat such an error. There are valid cases such
as a temporarily sleeping device that should not cause autosuspend to
leave the system running.

Error behavior is configured in set_up_checks instead of the typical
__init__ pattern to prevent all check classes from needing a
modification.

Fixes: #814

Author: languitar

doc/source/configuration_file.inc

@@ -111,6 +111,18 @@ For each check, these generic options can be specified:
    Needs to be ``true`` for a check to actually execute.
    ``false`` is assumed if not specified.
 
+.. option:: error_behavior
+
+   Determines how a temporary error raised by this check is handled.
+
+   ``active``
+      Treat the error as detected activity, preventing the system from suspending until the check succeeds again.
+
+   ``ignore``
+      Log the error and treat the check as if no activity was detected.
+
+   Default: ``active``.
+
 Furthermore, each check might have custom options.
 
 Wake up check configuration

src/autosuspend/__init__.py

@@ -19,7 +19,14 @@
 from dbus.mainloop.glib import DBusGMainLoop
 from gi.repository import GLib
 
-from .checks import Activity, CheckType, ConfigurationError, TemporaryCheckError, Wakeup
+from .checks import (
+    Activity,
+    CheckType,
+    ConfigurationError,
+    ErrorBehavior,
+    TemporaryCheckError,
+    Wakeup,
+)
 from .config import GENERAL_PARAMETERS, ConfigSchema
 from .util import logger_by_class_instance
 from .util.systemd import LogindDBusException, has_inhibit_lock
@@ -121,6 +128,11 @@ def _safe_execute_activity(check: Activity, logger: logging.Logger) -> str | Non
     try:
         return check.check()
     except TemporaryCheckError:
+        if check.error_behavior is ErrorBehavior.IGNORE:
+            logger.warning(
+                "Check %s failed. Ignoring as configured...", check, exc_info=True
+            )
+            return None
         logger.warning("Check %s failed. Ignoring...", check, exc_info=True)
         return f"Check {check.name} failed temporarily"
 
@@ -451,6 +463,17 @@ def _determine_check_class_name(name: str, section: configparser.SectionProxy) -
     return section.get("class", name)
 
 
+def _determine_error_behavior(section: configparser.SectionProxy) -> ErrorBehavior:
+    raw = section.get("error_behavior", fallback=ErrorBehavior.ACTIVE.value)
+    try:
+        return ErrorBehavior(raw)
+    except ValueError as error:
+        raise ConfigurationError(
+            f"Invalid value for option 'error_behavior': {raw!r}. "
+            f"Allowed values: {[e.value for e in ErrorBehavior]}"
+        ) from error
+
+
 def _set_up_single_check(
     section: configparser.SectionProxy,
     prefix: str,
@@ -486,6 +509,8 @@ def _set_up_single_check(
         raise ConfigurationError(
             "Check %s is not a correct %s instance", check, target_class.__name__
         )
+    if isinstance(check, Activity):
+        check.error_behavior = _determine_error_behavior(section)
     _logger.debug("Created check instance %s with options %s", check, check.options())
 
     return check

src/autosuspend/checks/__init__.py

@@ -4,6 +4,7 @@
 import configparser
 from collections.abc import Mapping
 from datetime import datetime
+from enum import Enum
 from typing import Any, Self, TypeVar
 
 from autosuspend.config import ParameterSchemaAware
@@ -29,6 +30,13 @@ class SevereCheckError(RuntimeError):
     """
 
 
+class ErrorBehavior(Enum):
+    """Configures how a :class:`TemporaryCheckError` is handled for a check."""
+
+    ACTIVE = "active"
+    IGNORE = "ignore"
+
+
 CheckType = TypeVar("CheckType", bound="Check")
 
 
@@ -85,6 +93,10 @@ class Activity(Check):
     Subclasses must call this class' __init__ method.
     """
 
+    def __init__(self, name: str | None = None) -> None:
+        super().__init__(name)
+        self.error_behavior = ErrorBehavior.ACTIVE
+
     @abc.abstractmethod
     def check(self) -> str | None:
         """Determine if system activity exists that prevents suspending.

tests/test_autosuspend.py

@@ -114,6 +114,80 @@ class = Mpd
 
         mock_class.create.assert_called_once_with("Foo", parser["check.Foo"])
 
+    def test_error_behavior_defaults_to_active(self, mocker: MockerFixture) -> None:
+        mock_class = mocker.patch("autosuspend.checks.activity.Mpd")
+        check = mocker.MagicMock(spec=autosuspend.checks.Activity)
+        mock_class.create.return_value = check
+
+        parser = configparser.ConfigParser()
+        parser.read_string("""
+            [check.Foo]
+            class = Mpd
+            enabled = True
+            """)
+
+        autosuspend.set_up_checks(
+            parser, "check", "activity", autosuspend.Activity  # type: ignore
+        )
+
+        assert check.error_behavior == autosuspend.ErrorBehavior.ACTIVE
+
+    def test_error_behavior_can_be_set_to_ignore(self, mocker: MockerFixture) -> None:
+        mock_class = mocker.patch("autosuspend.checks.activity.Mpd")
+        check = mocker.MagicMock(spec=autosuspend.checks.Activity)
+        mock_class.create.return_value = check
+
+        parser = configparser.ConfigParser()
+        parser.read_string("""
+            [check.Foo]
+            class = Mpd
+            enabled = True
+            error_behavior = ignore
+            """)
+
+        autosuspend.set_up_checks(
+            parser, "check", "activity", autosuspend.Activity  # type: ignore
+        )
+
+        assert check.error_behavior == autosuspend.ErrorBehavior.IGNORE
+
+    def test_error_behavior_rejects_invalid_value(self, mocker: MockerFixture) -> None:
+        mock_class = mocker.patch("autosuspend.checks.activity.Mpd")
+        mock_class.create.return_value = mocker.MagicMock(
+            spec=autosuspend.checks.Activity
+        )
+
+        parser = configparser.ConfigParser()
+        parser.read_string("""
+            [check.Foo]
+            class = Mpd
+            enabled = True
+            error_behavior = bogus
+            """)
+
+        with pytest.raises(autosuspend.ConfigurationError):
+            autosuspend.set_up_checks(
+                parser, "check", "activity", autosuspend.Activity  # type: ignore
+            )
+
+    def test_error_behavior_not_set_for_wakeups(self, mocker: MockerFixture) -> None:
+        mock_class = mocker.patch("autosuspend.checks.wakeup.File")
+        check = mocker.MagicMock(spec=autosuspend.checks.Wakeup)
+        mock_class.create.return_value = check
+
+        parser = configparser.ConfigParser()
+        parser.read_string("""
+            [wakeup.Foo]
+            class = File
+            enabled = True
+            """)
+
+        autosuspend.set_up_checks(
+            parser, "wakeup", "wakeup", autosuspend.Wakeup  # type: ignore
+        )
+
+        assert not hasattr(check, "error_behavior")
+
     def test_external_class(self, mocker: MockerFixture) -> None:
         mock_class = mocker.patch("os.path.TestCheck", create=True)
         mock_class.create.return_value = mocker.MagicMock(
@@ -290,6 +364,7 @@ def test_all_called(self, mocker: MockerFixture) -> None:
     def test_treat_temporary_errors_as_activity(self, mocker: MockerFixture) -> None:
         matching_check = mocker.MagicMock(spec=autosuspend.Activity)
         matching_check.name = "foo"
+        matching_check.error_behavior = autosuspend.ErrorBehavior.ACTIVE
         matching_check.check.side_effect = autosuspend.TemporaryCheckError()
 
         assert (
@@ -298,6 +373,20 @@ def test_treat_temporary_errors_as_activity(self, mocker: MockerFixture) -> None
         )
         matching_check.check.assert_called_once_with()
 
+    def test_ignore_temporary_errors_when_configured(
+        self, mocker: MockerFixture
+    ) -> None:
+        matching_check = mocker.MagicMock(spec=autosuspend.Activity)
+        matching_check.name = "foo"
+        matching_check.error_behavior = autosuspend.ErrorBehavior.IGNORE
+        matching_check.check.side_effect = autosuspend.TemporaryCheckError()
+
+        assert (
+            autosuspend.execute_checks([matching_check], False, mocker.MagicMock())
+            is False
+        )
+        matching_check.check.assert_called_once_with()
+
 
 class TestExecuteWakeups:
     def test_no_wakeups(self, mocker: MockerFixture) -> None:

tests/test_checks.py

@@ -1,6 +1,6 @@
 import configparser
 
-from autosuspend.checks import Check
+from autosuspend.checks import Activity, Check, ErrorBehavior
 
 
 class DummyCheck(Check):
@@ -12,6 +12,15 @@ def check(self) -> str | None:
         pass
 
 
+class DummyActivity(Activity):
+    @classmethod
+    def create(cls, name: str, config: configparser.SectionProxy) -> "DummyActivity":
+        raise NotImplementedError()
+
+    def check(self) -> str | None:
+        pass
+
+
 class TestCheck:
     class TestName:
         def test_returns_the_provided_name(self) -> None:
@@ -23,3 +32,8 @@ def test_has_a_sensible_default(self) -> None:
 
     def test_has_a_string_representation(self) -> None:
         assert isinstance(str(DummyCheck("test")), str)
+
+
+class TestActivity:
+    def test_error_behavior_defaults_to_active(self) -> None:
+        assert DummyActivity("test").error_behavior == ErrorBehavior.ACTIVE