Add checks config fields and get_checks API

.github/workflows/framework-tests.yaml

@@ -67,7 +67,7 @@ jobs:
       - name: Start Pebble
         run: |
           umask 0
-          $HOME/go/bin/pebble run --create-dirs &
+          $HOME/go/bin/pebble run --create-dirs --http=:4000 &
         env:
           PEBBLE: /tmp/pebble
 

.github/workflows/observability-charm-tests.yaml

@@ -23,6 +23,7 @@ jobs:
         run: |
           sed -i -e "/^ops[ ><=]/d" -e "/canonical\/operator/d" -e "/#egg=ops/d" requirements.txt
           echo -e "\ngit+$GITHUB_SERVER_URL/$GITHUB_REPOSITORY@$GITHUB_SHA#egg=ops" >> requirements.txt
+          echo -e "\nmarkupsafe==2.0.1" >> requirements.txt  # temp fix for https://github.com/canonical/grafana-k8s-operator/pull/69
 
       - name: Install dependencies
         run: pip install tox

ops/pebble.py

@@ -19,6 +19,7 @@
 
 import binascii
 import cgi
+import copy
 import datetime
 import email.parser
 import enum
@@ -519,6 +520,8 @@ def __init__(self, raw: str):
         self._raw = raw
         self._services = {name: Service(name, service)
                           for name, service in d.get('services', {}).items()}
+        self._checks = {name: Check(name, check)
+                        for name, check in d.get('checks', {}).items()}
 
     @property
     def services(self):
@@ -528,14 +531,21 @@ def services(self):
         """
         return self._services
 
+    @property
+    def checks(self):
+        """This plan's checks mapping (maps check name to Check).
+
+        This property is currently read-only.
+        """
+        return self._checks
+
     def to_dict(self) -> typing.Dict[str, typing.Any]:
         """Convert this plan to its dict representation."""
-        as_dicts = {name: service.to_dict() for name, service in self._services.items()}
-        if not as_dicts:
-            return {}
-        return {
-            'services': as_dicts,
-        }
+        fields = [
+            ('services', {name: service.to_dict() for name, service in self._services.items()}),
+            ('checks', {name: check.to_dict() for name, check in self._checks.items()}),
+        ]
+        return {name: value for name, value in fields if value}
 
     def to_yaml(self) -> str:
         """Return this plan's YAML representation."""
@@ -553,7 +563,8 @@ class Layer:
     Attributes:
         summary: A summary of the purpose of this layer
         description: A long form description of this layer
-        services: A mapping of name: :class:`Service` defined by this layer
+        services: A mapping of name to :class:`Service` defined by this layer
+        checks: A mapping of check to :class:`Check` defined by this layer
     """
 
     # This is how you do type annotations, but it is not supported by Python 3.5
@@ -570,6 +581,8 @@ def __init__(self, raw: typing.Union[str, typing.Dict] = None):
         self.description = d.get('description', '')
         self.services = {name: Service(name, service)
                          for name, service in d.get('services', {}).items()}
+        self.checks = {name: Check(name, check)
+                       for name, check in d.get('checks', {}).items()}
 
     def to_yaml(self) -> str:
         """Convert this layer to its YAML representation."""
@@ -580,7 +593,8 @@ def to_dict(self) -> typing.Dict[str, typing.Any]:
         fields = [
             ('summary', self.summary),
             ('description', self.description),
-            ('services', {name: service.to_dict() for name, service in self.services.items()})
+            ('services', {name: service.to_dict() for name, service in self.services.items()}),
+            ('checks', {name: check.to_dict() for name, check in self.checks.items()}),
         ]
         return {name: value for name, value in fields if value}
 
@@ -609,8 +623,14 @@ def __init__(self, name: str, raw: typing.Dict = None):
         self.user_id = raw.get('user-id')
         self.group = raw.get('group', '')
         self.group_id = raw.get('group-id')
+        self.on_success = raw.get('on-success', '')
+        self.on_failure = raw.get('on-failure', '')
+        self.on_check_failure = dict(raw.get('on-check-failure', {}))
+        self.backoff_delay = raw.get('backoff-delay', '')
+        self.backoff_factor = raw.get('backoff-factor')
+        self.backoff_limit = raw.get('backoff-limit', '')
 
-    def to_dict(self) -> typing.Dict:
+    def to_dict(self) -> typing.Dict[str, typing.Any]:
         """Convert this service object to its dict representation."""
         fields = [
             ('summary', self.summary),
@@ -626,6 +646,12 @@ def to_dict(self) -> typing.Dict:
             ('user-id', self.user_id),
             ('group', self.group),
             ('group-id', self.group_id),
+            ('on-success', self.on_success),
+            ('on-failure', self.on_failure),
+            ('on-check-failure', self.on_check_failure),
+            ('backoff-delay', self.backoff_delay),
+            ('backoff-factor', self.backoff_factor),
+            ('backoff-limit', self.backoff_limit),
         ]
         return {name: value for name, value in fields if value}
 
@@ -701,6 +727,78 @@ def __repr__(self):
                 ).format(self=self)
 
 
+class Check:
+    """Represents a check configuration in a Pebble configuration layer."""
+
+    def __init__(self, name: str, raw: typing.Dict = None):
+        self.name = name
+        raw = raw or {}
+        self.override = raw.get('override', '')
+        try:
+            self.level = CheckLevel(raw.get('level', ''))
+        except ValueError:
+            self.level = raw.get('level')
+        self.period = raw.get('period', '')
+        self.timeout = raw.get('timeout', '')
+        self.threshold = raw.get('threshold')
+
+        http = raw.get('http')
+        if http is not None:
+            http = copy.deepcopy(http)
+        self.http = http
+
+        tcp = raw.get('tcp')
+        if tcp is not None:
+            tcp = copy.deepcopy(tcp)
+        self.tcp = tcp
+
+        exec_ = raw.get('exec')
+        if exec_ is not None:
+            exec_ = copy.deepcopy(exec_)
+        self.exec = exec_
+
+    def to_dict(self) -> typing.Dict[str, typing.Any]:
+        """Convert this check object to its dict representation."""
+        fields = [
+            ('override', self.override),
+            ('level', self.level.value),
+            ('period', self.period),
+            ('timeout', self.timeout),
+            ('threshold', self.threshold),
+            ('http', self.http),
+            ('tcp', self.tcp),
+            ('exec', self.exec),
+        ]
+        return {name: value for name, value in fields if value}
+
+    def __repr__(self) -> str:
+        return 'Check({!r})'.format(self.to_dict())
+
+    def __eq__(self, other: typing.Union[typing.Dict, 'Check']) -> bool:
+        """Compare this check configuration to another."""
+        if isinstance(other, dict):
+            return self.to_dict() == other
+        elif isinstance(other, Check):
+            return self.to_dict() == other.to_dict()
+        else:
+            raise ValueError("Cannot compare pebble.Check to {}".format(type(other)))
+
+
+class CheckLevel(enum.Enum):
+    """Enum of check levels."""
+
+    UNSET = ''
+    ALIVE = 'alive'
+    READY = 'ready'
+
+
+class CheckStatus(enum.Enum):
+    """Enum of check statuses."""
+
+    UP = 'up'
+    DOWN = 'down'
+
+
 class FileType(enum.Enum):
     """Enum of file types."""
 
@@ -775,6 +873,52 @@ def __repr__(self):
                 ).format(self=self)
 
 
+class CheckInfo:
+    """Check status information."""
+
+    def __init__(
+        self,
+        name: str,
+        level: str,
+        status: str,
+        failures: int = 0,
+        threshold: int = 0,
+    ):
+        self.name = name
+        self.level = level
+        self.status = status
+        self.failures = failures
+        self.threshold = threshold
+
+    @classmethod
+    def from_dict(cls, d: typing.Dict) -> 'CheckInfo':
+        """Create new CheckInfo object from dict parsed from JSON."""
+        try:
+            level = CheckLevel(d.get('level', ''))
+        except ValueError:
+            level = d.get('level')
+        try:
+            status = CheckStatus(d['status'])
+        except ValueError:
+            status = d['status']
+        return cls(
+            name=d['name'],
+            level=level,
+            status=status,
+            failures=d.get('failures', 0),
+            threshold=d['threshold'],
+        )
+
+    def __repr__(self):
+        return ('CheckInfo('
+                'name={self.name!r}, '
+                'level={self.level!r}, '
+                'status={self.status}, '
+                'failures={self.failures}, '
+                'threshold={self.threshold!r})'
+                ).format(self=self)
+
+
 class ExecProcess:
     """Represents a process started by :meth:`Client.exec`.
 
@@ -1135,7 +1279,7 @@ def _request_raw(
         """Make a request to the Pebble server; return the raw HTTPResponse object."""
         url = self.base_url + path
         if query:
-            url = url + '?' + urllib.parse.urlencode(query)
+            url = url + '?' + urllib.parse.urlencode(query, doseq=True)
 
         # python 3.5 urllib requests require their data to be a bytes object -
         # generators won't work.
@@ -1430,7 +1574,7 @@ def add_layer(
         self._request('POST', '/v1/layers', body=body)
 
     def get_plan(self) -> Plan:
-        """Get the Pebble plan (currently contains only combined services)."""
+        """Get the Pebble plan (contains combined layer configuration)."""
         resp = self._request('GET', '/v1/plan', {'format': 'yaml'})
         return Plan(resp['result'])
 
@@ -1976,3 +2120,28 @@ def send_signal(self, sig: typing.Union[int, str], services: typing.List[str]):
             'services': services,
         }
         self._request('POST', '/v1/signals', body=body)
+
+    def get_checks(
+        self,
+        level: CheckLevel = None,
+        names: typing.List[str] = None
+    ) -> typing.List[CheckInfo]:
+        """Get the check status for the configured checks.
+
+        Args:
+            level: Optional check level to query for. Because "ready" implies
+                "alive", if level is AliveLevel, checks with level "ready" are
+                included too.
+            names: Optional list of check names to query for (default is to
+                fetch all).
+
+        Returns:
+            List of CheckInfo objects.
+        """
+        query = {}
+        if level is not None:
+            query['level'] = level.value
+        if names:
+            query['names'] = names
+        resp = self._request('GET', '/v1/checks', query)
+        return [CheckInfo.from_dict(info) for info in resp['result']]

ops/testing.py

@@ -1577,6 +1577,9 @@ def exec(self, command, **kwargs):
     def send_signal(self, sig: typing.Union[int, str], services: typing.List[str]):
         raise NotImplementedError(self.send_signal)
 
+    def get_checks(self, level=None, names=None):
+        raise NotImplementedError(self.get_checks)
+
 
 class NonAbsolutePathError(Exception):
     """Error raised by _MockFilesystem.

test/pebble_cli.py

@@ -57,6 +57,11 @@ def main():
                    choices=[s.value for s in pebble.ChangeState], default='all')
     p.add_argument('--service', help='optional service name to filter on')
 
+    p = subparsers.add_parser('checks', help='show (filtered) checks')
+    p.add_argument('--level', help='check level to filter on, default all levels',
+                   choices=[c.value for c in pebble.CheckLevel], default='')
+    p.add_argument('name', help='check name(s) to filter on', nargs='*')
+
     p = subparsers.add_parser('exec', help='execute a command')
     p.add_argument('--env', help='environment variables to set', action='append',
                    metavar='KEY=VALUE')
@@ -157,6 +162,8 @@ def main():
         elif args.command == 'changes':
             result = client.get_changes(select=pebble.ChangeState(args.select),
                                         service=args.service)
+        elif args.command == 'checks':
+            result = client.get_checks(level=pebble.CheckLevel(args.level), names=args.name)
         elif args.command == 'exec':
             environment = {}
             for env in args.env or []: