fix(controller): reconcile stuck "modified" config status on checksum request

When a device applies a new configuration but fails to report its
status back to the controller (e.g., due to a transient HTTP 502
error during server maintenance), the config remains in "modified"
state indefinitely.

The device's agent compares its local checksum with the remote
checksum on subsequent polling cycles and finds they match, so it
won't re-download or re-report. The status stays "modified" even
though the device already has the current configuration.

Fix: When a device with "modified" status requests its checksum and
enough time has passed since the config was last modified (grace
period of 5 minutes, configurable via _STATUS_RECONCILE_GRACE_SECONDS),
reconcile the status to "applied". The grace period ensures we don't
prematurely reconcile during the normal apply cycle.

This fix is backward compatible — it requires no changes to the
openwisp-config agent on the device side.

Author: MichaelUray

openwisp_controller/config/controller/views.py

@@ -144,6 +144,13 @@ class DeviceChecksumView(UpdateLastIpMixin, GetDeviceView):
     returns device's configuration checksum
     """
 
+    # Grace period before reconciling a "modified" status.
+    # If the config has been in "modified" state for longer than this,
+    # and the device is actively requesting its checksum (proving it's
+    # online and polling), we assume a previous report_status call was
+    # lost due to a transient error and reconcile the status to "applied".
+    _STATUS_RECONCILE_GRACE_SECONDS = 300  # 5 minutes
+
     def get(self, request, pk):
         device = self.get_device()
         bad_request = forbid_unallowed(request, "GET", "key", device.key)
@@ -156,10 +163,55 @@ def get(self, request, pk):
         checksum_requested.send(
             sender=device.__class__, instance=device, request=request
         )
+        self._reconcile_modified_status(device)
         return ControllerResponse(
             device.config.get_cached_checksum(), content_type="text/plain"
         )
 
+    @staticmethod
+    def _reconcile_modified_status(device):
+        """
+        Reconciles config status for devices stuck in "modified" state.
+
+        When a device applies a new configuration but fails to report its
+        status back (e.g., due to a transient HTTP error like 502), the
+        config remains in "modified" state on the controller even though
+        the device already has the current configuration.
+
+        The device's agent will compare its local checksum with the
+        remote checksum on the next polling cycle and find they match,
+        so it won't re-download or re-report. The status stays "modified"
+        indefinitely.
+
+        This method detects this condition: if the config has been in
+        "modified" state for longer than the grace period and the device
+        is actively polling (proven by this very checksum request), we
+        set the status to "applied".
+        """
+        from django.utils import timezone
+
+        config = device.config
+        if config.status != "modified":
+            return
+        grace = DeviceChecksumView._STATUS_RECONCILE_GRACE_SECONDS
+        elapsed = (timezone.now() - config.modified).total_seconds()
+        if elapsed < grace:
+            return
+        try:
+            config.set_status_applied()
+            logger.info(
+                "Reconciled config status for device %s: was 'modified' "
+                "for %d seconds with device actively polling, "
+                "setting to 'applied'.",
+                device,
+                int(elapsed),
+            )
+        except Exception:
+            logger.exception(
+                "Failed to reconcile config status for device %s",
+                device,
+            )
+
     @cache_memoize(
         timeout=Config._CHECKSUM_CACHE_TIMEOUT, args_rewrite=get_device_args_rewrite
     )

openwisp_controller/config/tests/test_controller.py

@@ -270,6 +270,63 @@ def test_device_checksum_requested_signal_is_emitted(self):
                 request=response.wsgi_request,
             )
 
+    def test_device_checksum_reconciles_modified_status(self):
+        """
+        When a device with status "modified" requests its checksum,
+        and enough time has passed (grace period), the status should
+        be automatically reconciled to "applied".
+        """
+        from unittest.mock import PropertyMock
+
+        d = self._create_device_config()
+        c = d.config
+        c.set_status_modified()
+        self.assertEqual(c.status, "modified")
+        url = reverse("controller:device_checksum", args=[d.pk])
+
+        # First request within grace period: status should stay "modified"
+        response = self.client.get(url, {"key": d.key})
+        self.assertEqual(response.status_code, 200)
+        c.refresh_from_db()
+        self.assertEqual(c.status, "modified")
+
+        # Simulate that grace period has elapsed by backdating the modified timestamp
+        from django.utils import timezone
+        from datetime import timedelta
+
+        Config.objects.filter(pk=c.pk).update(
+            modified=timezone.now() - timedelta(seconds=600)
+        )
+
+        # Second request after grace period: status should be reconciled to "applied"
+        response = self.client.get(url, {"key": d.key})
+        self.assertEqual(response.status_code, 200)
+        c.refresh_from_db()
+        self.assertEqual(c.status, "applied")
+
+    def test_device_checksum_no_reconcile_for_applied(self):
+        """Status "applied" should not be changed."""
+        d = self._create_device_config()
+        c = d.config
+        c.set_status_applied()
+        url = reverse("controller:device_checksum", args=[d.pk])
+        response = self.client.get(url, {"key": d.key})
+        self.assertEqual(response.status_code, 200)
+        c.refresh_from_db()
+        self.assertEqual(c.status, "applied")
+
+    def test_device_checksum_no_reconcile_within_grace_period(self):
+        """Status should not be reconciled if within the grace period."""
+        d = self._create_device_config()
+        c = d.config
+        c.set_status_modified()
+        url = reverse("controller:device_checksum", args=[d.pk])
+        response = self.client.get(url, {"key": d.key})
+        self.assertEqual(response.status_code, 200)
+        c.refresh_from_db()
+        self.assertEqual(c.status, "modified")
+
+
     def test_device_checksum_bad_uuid(self):
         d = self._create_device_config()
         pk = "{}-wrong".format(d.pk)