Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Separate PMG decoding failures from gateway reachability

pulse-triage[bot]34e3502630a4
diff --git a/docs/MAIL_GATEWAY.md b/docs/MAIL_GATEWAY.md
index 4b9f009495..78361e8611 100644
--- a/docs/MAIL_GATEWAY.md
+++ b/docs/MAIL_GATEWAY.md
@@ -133,6 +133,23 @@ or permissions:
| Gateway is present but statistics are missing | Clear view filters, check whether the connection is paused, and compare the particular dataset and time window with PMG. A successful test or version read does not establish dataset access. |
| Cluster nodes or node queues are missing | Compare the gateway's existing cluster inventory and each affected node's native queue view. One reachable node does not prove every node was collected. |
+### Response decoding is not a network verdict
+
+An error such as `pmg_queue_status` followed by `failed to decode response` or
+`cannot unmarshal array` means Pulse received a response it could not interpret.
+It does not, by itself, establish that the gateway is unreachable, the password
+is wrong or the queue is empty. A separate transport or permission error still
+needs its own assessment; a successful **Test Connection** does not resolve the
+decoding failure.
+
+Use PMG's own existing queue view for queue status while Pulse cannot read it.
+Keep the affected dataset, original time and short redacted error for the report;
+do not attach the full queue response, which can contain mail details. Do not
+change DNS, disable certificate verification, grant broader permissions, re-add
+the connection or retry, delete or release mail to diagnose a decoder error.
+Turning off queue collection removes coverage; it does not repair decoding or
+establish that an existing alert has recovered.
+
For a new connection, allow its configured polling interval rather than a fixed
one- or two-cycle promise. If a previously working reading stops advancing,
retain that observation and the original bounded error; do not repeatedly test,
diff --git a/frontend-modern/public/docs/MAIL_GATEWAY.md b/frontend-modern/public/docs/MAIL_GATEWAY.md
index 4b9f009495..78361e8611 100644
--- a/frontend-modern/public/docs/MAIL_GATEWAY.md
+++ b/frontend-modern/public/docs/MAIL_GATEWAY.md
@@ -133,6 +133,23 @@ or permissions:
| Gateway is present but statistics are missing | Clear view filters, check whether the connection is paused, and compare the particular dataset and time window with PMG. A successful test or version read does not establish dataset access. |
| Cluster nodes or node queues are missing | Compare the gateway's existing cluster inventory and each affected node's native queue view. One reachable node does not prove every node was collected. |
+### Response decoding is not a network verdict
+
+An error such as `pmg_queue_status` followed by `failed to decode response` or
+`cannot unmarshal array` means Pulse received a response it could not interpret.
+It does not, by itself, establish that the gateway is unreachable, the password
+is wrong or the queue is empty. A separate transport or permission error still
+needs its own assessment; a successful **Test Connection** does not resolve the
+decoding failure.
+
+Use PMG's own existing queue view for queue status while Pulse cannot read it.
+Keep the affected dataset, original time and short redacted error for the report;
+do not attach the full queue response, which can contain mail details. Do not
+change DNS, disable certificate verification, grant broader permissions, re-add
+the connection or retry, delete or release mail to diagnose a decoder error.
+Turning off queue collection removes coverage; it does not repair decoding or
+establish that an existing alert has recovered.
+
For a new connection, allow its configured polling interval rather than a fixed
one- or two-cycle promise. If a previously working reading stops advancing,
retain that observation and the original bounded error; do not repeatedly test,
diff --git a/scripts/tests/test_pmg_docs.py b/scripts/tests/test_pmg_docs.py
index 9439562036..056779e263 100644
--- a/scripts/tests/test_pmg_docs.py
+++ b/scripts/tests/test_pmg_docs.py
@@ -191,6 +191,23 @@ class PMGDocsTest(unittest.TestCase):
self.assertIn("does not guarantee a notification was routed or received", self.guide)
self.assertIn("TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing", self.text)
+ def test_decoder_failure_preserves_native_coverage_without_gateway_changes(self):
+ section = self.guide.split("Response decoding is not a network verdict", 1)[1]
+ section = section.split("For a new connection", 1)[0]
+ for phrase in ("pmg_queue_status", "failed to decode response",
+ "cannot unmarshal array", "received a response it could not interpret",
+ "does not, by itself, establish", "queue is empty",
+ "separate transport or permission error",
+ "Test Connection does not resolve the decoding failure",
+ "PMG's own existing queue view", "short redacted error",
+ "do not attach the full queue response",
+ "Do not change DNS, disable certificate verification, grant broader permissions",
+ "retry, delete or release mail",
+ "Turning off queue collection removes coverage",
+ "does not repair decoding"):
+ self.assertIn(phrase, section)
+ self.assertNotRegex(section, r"https?://|```|\b(?:curl|wget)\b")
+
if __name__ == "__main__":
unittest.main()