M5-T10: add paho MQTT client with lifespan connect/reconnect and mqtt/test endpoint

openapi/openapi.json

@@ -53,7 +53,7 @@
           "api-config"
         ],
         "summary": "Put Config",
-        "description": "Save configuration updates.\n\n- Blank secret value keeps the existing stored value (no change).\n- Invalid values return 422 and nothing is written to the database.",
+        "description": "Save configuration updates.\n\n- Blank secret value keeps the existing stored value (no change).\n- Invalid values return 422 and nothing is written to the database.\n- If MQTT-related settings changed, the MQTT client reconnects automatically.",
         "operationId": "put_config_api_config_put",
         "parameters": [
           {
@@ -177,6 +177,76 @@
         }
       }
     },
+    "/api/config/mqtt/test": {
+      "post": {
+        "tags": [
+          "api-config"
+        ],
+        "summary": "Post Mqtt Test",
+        "description": "Test MQTT broker connectivity by attempting to connect and publishing a\ntest message to ``<ha_discovery_prefix>/home-automation/test``.\n\nThe message is visible in MQTT Explorer (or any subscriber) so users can\nconfirm the full broker publish path is working.\n\nThree possible outcomes:\n- 200 { \"result\": \"success\", \"message\": ... }\n- 400 { \"result\": \"config-error\", \"message\": ... }   (not configured)\n- 502 { \"result\": \"failed\", \"message\": ... }          (connection/publish error)\n\nMQTT credentials are never echoed in the response.",
+        "operationId": "post_mqtt_test_api_config_mqtt_test_post",
+        "parameters": [
+          {
+            "name": "X-CSRF-Token",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "X-Csrf-Token"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MqttTestResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MqttTestResponse"
+                }
+              }
+            },
+            "description": "Bad Request"
+          },
+          "502": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MqttTestResponse"
+                }
+              }
+            },
+            "description": "Bad Gateway"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/locations": {
       "get": {
         "tags": [
@@ -2329,6 +2399,30 @@
         "title": "ModbusTestReadResponse",
         "description": "Response for POST /api/modbus/devices/{uuid}/test.\n\nOn success ``ok=True`` and ``payload`` contains the decoded values.\nOn failure ``ok=False`` and ``error`` describes the problem."
       },
+      "MqttTestResponse": {
+        "properties": {
+          "result": {
+            "type": "string",
+            "enum": [
+              "success",
+              "config-error",
+              "failed"
+            ],
+            "title": "Result"
+          },
+          "message": {
+            "type": "string",
+            "title": "Message"
+          }
+        },
+        "type": "object",
+        "required": [
+          "result",
+          "message"
+        ],
+        "title": "MqttTestResponse",
+        "description": "Response from POST /api/config/mqtt/test."
+      },
       "PasswordChangeRequest": {
         "properties": {
           "current_password": {