Deploy MQTT test backend with private viewer and Gitea CI/CD

2026-10-08 14:48:53 +03:30
commit 71ef622b4f
70 changed files with 7123 additions and 0 deletions
@@ -0,0 +1,66 @@
+{
+  "info": {
+    "_postman_id": "9c586a0e-2db4-4c70-963c-12b41d983b52",
+    "name": "MQTT Test Viewer (HTTP checks)",
+    "description": "Read-only checks for the local MQTT test viewer. The collection checks the viewer page and its current snapshot. To publish a test MQTT message, use the manual recipe in postman/README.md; Postman HTTP and MQTT requests must be saved in separate collections.",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "variable": [
+    {
+      "key": "viewerUrl",
+      "value": "http://127.0.0.1:8080",
+      "type": "string"
+    }
+  ],
+  "item": [
+    {
+      "name": "1. Viewer page is available",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": "{{viewerUrl}}/",
+        "description": "Confirms the browser viewer is serving its page."
+      },
+      "event": [
+        {
+          "listen": "test",
+          "script": {
+            "type": "text/javascript",
+            "exec": [
+              "pm.test('viewer returns HTTP 200', function () { pm.response.to.have.status(200); });",
+              "pm.test('viewer page is HTML', function () { pm.expect(pm.response.headers.get('Content-Type')).to.include('text/html'); });",
+              "pm.test('page identifies the MQTT message viewer', function () { pm.expect(pm.response.text()).to.include('MQTT message viewer'); });"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "name": "2. Snapshot shows broker and events",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": "{{viewerUrl}}/api/snapshot",
+        "description": "Returns the current observer connection state, event counts, compatibility evidence, and bounded event history. Run this after publishing MQTT telemetry to check whether the observer received it."
+      },
+      "event": [
+        {
+          "listen": "test",
+          "script": {
+            "type": "text/javascript",
+            "exec": [
+              "pm.test('snapshot returns HTTP 200 JSON', function () { pm.response.to.have.status(200); pm.expect(pm.response.headers.get('Content-Type')).to.include('application/json'); });",
+              "const snapshot = pm.response.json();",
+              "pm.test('observer is connected to the broker', function () { pm.expect(snapshot.connection).to.eql('connected'); });",
+              "pm.test('snapshot contains event history and counters', function () { pm.expect(snapshot.events).to.be.an('array'); pm.expect(snapshot.counts).to.be.an('object'); pm.expect(snapshot.last_event_id).to.be.a('number'); });",
+              "const received = (snapshot.counts && snapshot.counts.message_received) || 0;",
+              "pm.test('observer has received at least one MQTT message', function () { pm.expect(received, 'Send telemetry using the MQTT recipe, then run this request again').to.be.above(0); });",
+              "const latest = snapshot.events && snapshot.events.length ? snapshot.events[snapshot.events.length - 1] : null;",
+              "if (latest) console.log('Latest viewer event:', latest.kind, latest.topic || '', latest.payload && latest.payload.text || '');"
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
@@ -0,0 +1,21 @@
+# Manually test the broker and browser viewer with Postman
+
+In Postman v12, open the **project root** `/home/ryan/Media/Code/Code/robot-market/test-mqtt-5` using **Files → Open folder**, then select **Local View**. This MQTT collection uses Postman's v3 multi-file format; it is **not a standalone file to choose from Import**. Do not select the `.request.yaml` file or the nested collection directory in the Import dialog. Postman discovers the collection at `postman/collections/MQTT Broker UI Test`. Keep the observer container running and open <http://127.0.0.1:8080> in your browser.
+
+If you still get “We don't recognize this file” after opening the project root via **Files → Open folder**, bypass the saved collection and create the request inside Postman: click **+ → MQTT**, enter `mqtt://109.122.252.129:1884`, set MQTT version to **5.0**, enter the `sim-001` test username/password under the request's connection/auth settings, and click **Connect**. Then follow “Publish a test telemetry message” below. The message's topic and payload are the actual test inputs; the MQTT collection file only pre-fills the broker URL and provides notes.
+
+The older `MQTT Test Viewer.postman_collection.json` file is a Postman v2.1 HTTP collection with two read-only checks for the viewer page and `/api/snapshot`. The MQTT v3 collection below is for broker traffic. To subscribe to telemetry in Postman, use the **test-backend** credentials; device credentials can only subscribe to their commands topic. To publish as ESP32, use the **esp32-lab-001** credentials and its matching topic path. Current Postman supports MQTT requests in its v3 multi-protocol collection format.
+
+## Quick functional test
+
+1. Connect to `mqtt://109.122.252.129:1884` with any existing test account (including `esp32-lab-001`) and its current password. Select MQTT **5.0** and use a unique client ID such as `postman-functional-test-01`.
+2. Publish `hello from postman` to `robot-market/test/v1/sim-001/telemetry`, QoS **1**, retain **off**.
+3. Open http://127.0.0.1:8080/. It should appear as `message_received` with its raw contents.
+
+The test broker no longer restricts topics by username. Any test account may also subscribe to that topic in Postman to receive its own publication. The browser watches all topics under `robot-market/test/v1/#` and applies no JSON, device-ID or timestamp validation. Your previous JSON payload, including a literal `{{$isoTimestamp}}`, is displayed as supplied.
+
+TLS is also available at `mqtts://109.122.252.129:8884` with the supplied private CA. If a Postman send does not appear, inspect the connection state and publish acknowledgement. The Go simulator is not needed.
+
+## Receive the backend's application ACK
+
+In Topics, subscribe to `robot-market/test/v1/sim-001/acks` **before** publishing to `robot-market/test/v1/sim-001/telemetry`. Every live test payload gets a JSON `receipt_ack` reply with `ok=true`, source topic, observed time, byte count and SHA-256. Optional message_id/request_id are echoed; they are not required. For ESP32's own topic path, subscribe to `robot-market/test/v1/esp32-lab-001/acks`. The UI shows `receipt_ack_sent` and outbound publication events. This is separate from MQTT PUBACK.
@@ -0,0 +1,3 @@
+$kind: collection
+name: MQTT Broker UI Test
+description: Connect Postman to the test MQTT broker and publish test-device telemetry for the local browser viewer.
@@ -0,0 +1,24 @@
+$kind: mqtt-request
+name: Connect to Test Broker
+url: mqtt://109.122.252.129:1884
+description: |-
+  Connect with MQTT 5.0 using the sim-001 test account. Keep the local observer
+  running at http://127.0.0.1:8080.
+
+  Publish to robot-market/test/v1/sim-001/telemetry using QoS 1 and Retain off.
+  Use a new message_id each time and replace the timestamp with the current UTC
+  time (RFC3339, ending in Z).
+
+  {
+    "schema_version": 1,
+    "device_id": "sim-001",
+    "message_id": "postman-ui-test-001",
+    "boot_id": "postman-ui-session-001",
+    "sequence": 1,
+    "timestamp": "2026-10-06T12:00:00Z",
+    "readings": {
+      "temperature_c": 24.75,
+      "test_value": 123
+    }
+  }
+order: 1000