Paused ping handling can be controlled via API. Fixes #376

CHANGELOG.md

@@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+### Improvements
+- Paused ping handling can be controlled via API (#376)
+
 ### Bug Fixes
 - Removing Pager Team integration, project appears to be discontinued
 

hc/api/models.py

@@ -217,6 +217,7 @@ class Check(models.Model):
             "status": self.get_status(),
             "last_ping": isostring(self.last_ping),
             "next_ping": isostring(self.get_grace_start()),
+            "manual_resume": self.manual_resume,
         }
 
         if self.last_duration:

hc/api/schemas.py

@@ -9,6 +9,7 @@ check = {
         "schedule": {"type": "string", "format": "cron", "maxLength": 100},
         "tz": {"type": "string", "format": "timezone", "maxLength": 36},
         "channels": {"type": "string"},
+        "manual_resume": {"type": "boolean"},
         "unique": {
             "type": "array",
             "items": {"enum": ["name", "tags", "timeout", "grace"]},

hc/api/tests/test_create_check.py

@@ -225,3 +225,15 @@ class CreateCheckTestCase(BaseTestCase):
 
         r = self.post({"api_key": "R" * 32, "name": "Foo"})
         self.assertEqual(r.status_code, 401)
+
+    def test_it_sets_manual_resume(self):
+        r = self.post({"api_key": "X" * 32, "manual_resume": True})
+
+        self.assertEqual(r.status_code, 201)
+        check = Check.objects.get()
+        self.assertTrue(check.manual_resume)
+
+    def test_it_rejects_non_boolean_manual_resume(self):
+        r = self.post({"api_key": "X" * 32, "manual_resume": "surprise"})
+
+        self.assertEqual(r.status_code, 400)

hc/api/tests/test_get_check.py

@@ -33,7 +33,7 @@ class GetCheckTestCase(BaseTestCase):
         self.assertEqual(r["Access-Control-Allow-Origin"], "*")
 
         doc = r.json()
-        self.assertEqual(len(doc), 13)
+        self.assertEqual(len(doc), 14)
 
         self.assertEqual(doc["timeout"], 3600)
         self.assertEqual(doc["grace"], 900)
@@ -43,6 +43,7 @@ class GetCheckTestCase(BaseTestCase):
         self.assertEqual(doc["status"], "new")
         self.assertEqual(doc["channels"], str(self.c1.code))
         self.assertEqual(doc["desc"], "This is description")
+        self.assertFalse(doc["manual_resume"])
 
     def test_it_handles_invalid_uuid(self):
         r = self.get("not-an-uuid")

hc/api/tests/test_update_check.py

@@ -225,3 +225,20 @@ class UpdateCheckTestCase(BaseTestCase):
 
         r = self.post(self.check.code, {"api_key": "R" * 32, "name": "Foo"})
         self.assertEqual(r.status_code, 401)
+
+    def test_it_sets_manual_resume_to_true(self):
+        r = self.post(self.check.code, {"api_key": "X" * 32, "manual_resume": True})
+        self.assertEqual(r.status_code, 200)
+
+        self.check.refresh_from_db()
+        self.assertTrue(self.check.manual_resume)
+
+    def test_it_sets_manual_resume_to_false(self):
+        self.check.manual_resume = True
+        self.check.save()
+
+        r = self.post(self.check.code, {"api_key": "X" * 32, "manual_resume": False})
+        self.assertEqual(r.status_code, 200)
+
+        self.check.refresh_from_db()
+        self.assertFalse(self.check.manual_resume)

hc/api/views.py

@@ -92,6 +92,9 @@ def _update(check, spec):
     if "desc" in spec:
         check.desc = spec["desc"]
 
+    if "manual_resume" in spec:
+        check.manual_resume = spec["manual_resume"]
+
     if "timeout" in spec and "schedule" not in spec:
         check.kind = "simple"
         check.timeout = td(seconds=spec["timeout"])

hc/lib/jsonschema.py

@@ -39,6 +39,10 @@ def validate(obj, schema, obj_name="value"):
         if "maximum" in schema and obj > schema["maximum"]:
             raise ValidationError("%s is too large" % obj_name)
 
+    elif schema.get("type") == "boolean":
+        if not isinstance(obj, bool):
+            raise ValidationError("%s is not a boolean" % obj_name)
+
     elif schema.get("type") == "array":
         if not isinstance(obj, list):
             raise ValidationError("%s is not an array" % obj_name)

hc/lib/tests/test_jsonschema.py

@@ -82,3 +82,7 @@ class JsonSchemaTestCase(TestCase):
     def test_it_checks_timezone_format(self):
         with self.assertRaises(ValidationError):
             validate("X/Y", {"type": "string", "format": "timezone"})
+
+    def test_it_checks_boolean_type(self):
+        with self.assertRaises(ValidationError):
+            validate(123, {"type": "boolean"})

templates/docs/api.html

@@ -117,6 +117,7 @@ specified value.</p>
       <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;up&quot;</span><span class="p">,</span>
       <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T14:02:03+00:00&quot;</span><span class="p">,</span>
       <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T15:02:03+00:00&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
       <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINT31365bce-8da9-4729-8ff3-aaa71d56b712&quot;</span><span class="p">,</span>
       <span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712&quot;</span><span class="p">,</span>
       <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause&quot;</span><span class="p">,</span>
@@ -132,6 +133,7 @@ specified value.</p>
       <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
       <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
       <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+      <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
       <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
       <span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
       <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span>
@@ -158,6 +160,7 @@ is added. This identifier is stable across API calls. Example:</p>
       <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;up&quot;</span><span class="p">,</span>
       <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T14:02:03+00:00&quot;</span><span class="p">,</span>
       <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T15:02:03+00:00&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
       <span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;a6c7b0a8a66bed0df66abfdab3c77736861703ee&quot;</span><span class="p">,</span>
       <span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span>
     <span class="p">},</span>
@@ -170,6 +173,7 @@ is added. This identifier is stable across API calls. Example:</p>
       <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
       <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
       <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+      <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
       <span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;124f983e0e3dcaeba921cfcef46efd084576e783&quot;</span><span class="p">,</span>
       <span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span>
       <span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span>
@@ -208,6 +212,7 @@ is added. This identifier is stable across API calls. Example:</p>
   <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
   <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
   <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+  <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
   <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
   <span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
   <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span>
@@ -234,6 +239,7 @@ construct these URLs by itself.</p>
   <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
   <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
   <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+  <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
   <span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;124f983e0e3dcaeba921cfcef46efd084576e783&quot;</span><span class="p">,</span>
   <span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span>
   <span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span>
@@ -299,6 +305,15 @@ ignored and "schedule" will be used.</p>
 <p>Example:</p>
 <p><pre>{"tz": "Europe/Riga"}</pre></p>
 </dd>
+<dt>manual_resume</dt>
+<dd>
+<p>boolean, optional, default value: false.</p>
+<p>Controls whether a paused ping resumes automatically when pinged (the default),
+or not. If set to false, a paused check will leave the paused state when it receives
+a ping. If set to true, a paused check will ignore pings and stay paused until it is
+either manually resumed from the web dashboard or the <code>manual_resume</code> flag is
+changed.</p>
+</dd>
 <dt>channels</dt>
 <dd>
 <p>string, optional</p>
@@ -362,6 +377,7 @@ the limit is 20 checks per account.</dd>
   <span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
   <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
   <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+  <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
   <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
   <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
   <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>
@@ -427,6 +443,15 @@ ignored and "schedule" will be used.</p>
 <p>Example:</p>
 <p><pre>{"tz": "Europe/Riga"}</pre></p>
 </dd>
+<dt>manual_resume</dt>
+<dd>
+<p>boolean, optional, default value: false.</p>
+<p>Controls whether a paused ping resumes automatically when pinged (the default),
+or not. If set to false, a paused check will leave the paused state when it receives
+a ping. If set to true, a paused check will ignore pings and stay paused until it is
+either manually resumed from the web dashboard or the <code>manual_resume</code> flag is
+changed.</p>
+</dd>
 <dt>channels</dt>
 <dd>
 <p>string, optional.</p>
@@ -476,6 +501,7 @@ field values.</dd>
   <span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
   <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
   <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+  <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
   <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
   <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
   <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>
@@ -520,6 +546,7 @@ header is sometimes required by some network proxies and web servers.</p>
   <span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
   <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
   <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+  <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
   <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
   <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
   <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;paused&quot;</span><span class="p">,</span>
@@ -561,6 +588,7 @@ check that was just deleted.</p>
   <span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
   <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
   <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+  <span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
   <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
   <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
   <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>

templates/docs/api.md

@@ -97,6 +97,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
       "status": "up",
       "last_ping": "2020-03-24T14:02:03+00:00",
       "next_ping": "2020-03-24T15:02:03+00:00",
+      "manual_resume": false,
       "ping_url": "PING_ENDPOINT31365bce-8da9-4729-8ff3-aaa71d56b712",
       "update_url": "SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712",
       "pause_url": "SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause",
@@ -112,6 +113,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
       "status": "down",
       "last_ping": "2020-03-23T10:19:32+00:00",
       "next_ping": null,
+      "manual_resume": false,
       "ping_url": "PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d",
       "update_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
       "pause_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
@@ -139,6 +141,7 @@ is added. This identifier is stable across API calls. Example:
       "status": "up",
       "last_ping": "2020-03-24T14:02:03+00:00",
       "next_ping": "2020-03-24T15:02:03+00:00",
+      "manual_resume": false,
       "unique_key": "a6c7b0a8a66bed0df66abfdab3c77736861703ee",
       "timeout": 3600
     },
@@ -151,6 +154,7 @@ is added. This identifier is stable across API calls. Example:
       "status": "down",
       "last_ping": "2020-03-23T10:19:32+00:00",
       "next_ping": null,
+      "manual_resume": false,
       "unique_key": "124f983e0e3dcaeba921cfcef46efd084576e783",
       "schedule": "15 5 * * *",
       "tz": "UTC"
@@ -197,6 +201,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/<uuid>
   "status": "down",
   "last_ping": "2020-03-23T10:19:32+00:00",
   "next_ping": null,
+  "manual_resume": false,
   "ping_url": "PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d",
   "update_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
   "pause_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
@@ -227,6 +232,7 @@ construct these URLs by itself.
   "status": "down",
   "last_ping": "2020-03-23T10:19:32+00:00",
   "next_ping": null,
+  "manual_resume": false,
   "unique_key": "124f983e0e3dcaeba921cfcef46efd084576e783",
   "schedule": "15 5 * * *",
   "tz": "UTC"
@@ -305,6 +311,15 @@ tz
 
     <pre>{"tz": "Europe/Riga"}</pre>
 
+manual_resume
+:   boolean, optional, default value: false.
+
+    Controls whether a paused ping resumes automatically when pinged (the default),
+    or not. If set to false, a paused check will leave the paused state when it receives
+    a ping. If set to true, a paused check will ignore pings and stay paused until it is
+    either manually resumed from the web dashboard or the `manual_resume` flag is
+    changed.
+
 channels
 :   string, optional
 
@@ -381,6 +396,7 @@ curl SITE_ROOT/api/v1/checks/ \
   "n_pings": 0,
   "name": "Backups",
   "next_ping": null,
+  "manual_resume": false,
   "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
   "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
   "status": "new",
@@ -459,6 +475,15 @@ tz
 
     <pre>{"tz": "Europe/Riga"}</pre>
 
+manual_resume
+:   boolean, optional, default value: false.
+
+    Controls whether a paused ping resumes automatically when pinged (the default),
+    or not. If set to false, a paused check will leave the paused state when it receives
+    a ping. If set to true, a paused check will ignore pings and stay paused until it is
+    either manually resumed from the web dashboard or the `manual_resume` flag is
+    changed.
+
 channels
 :   string, optional.
 
@@ -521,6 +546,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
   "n_pings": 0,
   "name": "Backups",
   "next_ping": null,
+  "manual_resume": false,
   "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
   "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
   "status": "new",
@@ -575,6 +601,7 @@ header is sometimes required by some network proxies and web servers.
   "n_pings": 0,
   "name": "Backups",
   "next_ping": null,
+  "manual_resume": false,
   "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
   "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
   "status": "paused",
@@ -625,6 +652,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
   "n_pings": 0,
   "name": "Backups",
   "next_ping": null,
+  "manual_resume": false,
   "pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
   "ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
   "status": "new",