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

openapi/openapi.yaml

@@ -42,7 +42,9 @@ paths:
 
         - Blank secret value keeps the existing stored value (no change).
 
-        - Invalid values return 422 and nothing is written to the database.'
+        - Invalid values return 422 and nothing is written to the database.
+
+        - If MQTT-related settings changed, the MQTT client reconnects automatically.'
       operationId: put_config_api_config_put
       parameters:
       - name: X-CSRF-Token
@@ -127,6 +129,68 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/HTTPValidationError'
+  /api/config/mqtt/test:
+    post:
+      tags:
+      - api-config
+      summary: Post Mqtt Test
+      description: 'Test MQTT broker connectivity by attempting to connect and publishing
+        a
+
+        test message to ``<ha_discovery_prefix>/home-automation/test``.
+
+
+        The message is visible in MQTT Explorer (or any subscriber) so users can
+
+        confirm the full broker publish path is working.
+
+
+        Three possible outcomes:
+
+        - 200 { "result": "success", "message": ... }
+
+        - 400 { "result": "config-error", "message": ... }   (not configured)
+
+        - 502 { "result": "failed", "message": ... }          (connection/publish
+        error)
+
+
+        MQTT 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:
@@ -1699,6 +1763,24 @@ components:
         On success ``ok=True`` and ``payload`` contains the decoded values.
 
         On 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: