fix(auth): raise typed ServiceUnavailableError on token endpoint 5xx (#2099)

Fixes #2097

## Problem
When a vendor OAuth token endpoint (e.g. the Atlantic/CozyTouch token
URL) is temporarily down, it can return an **HTTP 5xx with an HTML
body**. The auth strategies parse token responses with `await
response.json()` **without checking the HTTP status first**, so aiohttp
raises a raw `ContentTypeError: Attempt to decode JSON with unexpected
mimetype: text/html`.

This:
- leaks an aiohttp implementation detail to consumers, and
- isn't caught by any `retry_on_*` decorator (they only match typed
Overkiz exceptions),

so a transient hiccup becomes a hard failure. Reported downstream in
Home Assistant core #160761.

The same unguarded `response.json()` pattern existed at four token
sites: Somfy, Cozytouch, Nexity, and Rexel.

A secondary gap: `check_response()` only mapped **503** to
`ServiceUnavailableError`; 500/502/504 with a non-JSON body fell through
to a generic `OverkizError`.

## Fix
1. **`auth/strategies.py`** — add `_raise_for_server_error()` which
routes any 5xx token response through `check_response()` before JSON
decoding, applied at the Somfy, Cozytouch, Nexity and Rexel token
endpoints. 4xx vendor JSON error formats (e.g. `{"error":
"invalid_grant"}`) are still handled by each strategy as before.
2. **`response_handler.py`** — generalize the non-JSON branch from `==
503` to `>= 500`, so any 5xx HTML body maps to
`ServiceUnavailableError`.

Implements points 1 & 2 of the issue. Point 3 (auto-retry of transient
5xx) was intentionally left out — consumers now get a typed, catchable
`ServiceUnavailableError`, which HA already treats as a retryable update
failure.

## Tests
- New `TestTokenEndpointServerErrors` reproduces the exact
`ContentTypeError` leak for Somfy/Cozytouch/Rexel and asserts it now
raises `ServiceUnavailableError`.
- New `check_response` cases for 500/502/504 + a `502-bad-gateway.html`
fixture.
- Full suite: **497 passed**, ruff + mypy clean.

Author: iMicknl

pyoverkiz/auth/strategies.py

@@ -14,7 +14,7 @@
 if TYPE_CHECKING:
     from botocore.client import BaseClient
 
-from aiohttp import ClientSession, FormData
+from aiohttp import ClientResponse, ClientSession, FormData
 
 from pyoverkiz.auth.base import AuthContext, AuthStrategy, GatewayCandidate
 from pyoverkiz.auth.credentials import (
@@ -58,6 +58,17 @@
 MIN_JWT_SEGMENTS = 2
 
 
+async def _raise_for_server_error(response: ClientResponse) -> None:
+    """Map a 5xx token-endpoint response to a typed Overkiz exception.
+
+    Token endpoints handle their own 4xx JSON error format, but on 5xx may
+    serve an HTML error page. Route 5xx through ``check_response`` so it raises
+    ``ServiceUnavailableError`` (or ``MaintenanceError``).
+    """
+    if response.status >= HTTPStatus.INTERNAL_SERVER_ERROR:
+        await check_response(response)
+
+
 class BaseAuthStrategy(AuthStrategy):
     """Base class for authentication strategies."""
 
@@ -197,6 +208,7 @@ async def _request_access_token(
             data=form,
             headers={"Content-Type": "application/x-www-form-urlencoded"},
         ) as response:
+            await _raise_for_server_error(response)
             token = await response.json()
 
             if token.get("message") == "error.invalid.grant":
@@ -229,6 +241,7 @@ async def login(self) -> None:
                 "Content-Type": "application/x-www-form-urlencoded",
             },
         ) as response:
+            await _raise_for_server_error(response)
             token = await response.json()
 
             if token.get("error") == "invalid_grant":
@@ -297,6 +310,7 @@ def _client() -> BaseClient:
             f"{NEXITY_API}/deploy/api/v1/domotic/token",
             headers={"Authorization": id_token},
         ) as response:
+            await _raise_for_server_error(response)
             token = await response.json()
 
             if "token" not in token:
@@ -467,6 +481,7 @@ async def _exchange_token(self, payload: Mapping[str, str]) -> None:
             REXEL_OAUTH_TOKEN_URL,
             data=payload,
         ) as response:
+            await _raise_for_server_error(response)
             token = await response.json()
 
             # Handle OAuth error responses explicitly before accessing the access token.

pyoverkiz/response_handler.py

@@ -135,7 +135,9 @@ async def check_response(response: ClientResponse) -> None:
         if "is down for maintenance" in result:
             raise MaintenanceError("Server is down for maintenance") from error
 
-        if response.status == HTTPStatus.SERVICE_UNAVAILABLE:
+        # Any 5xx with a non-JSON body (e.g. an HTML error page from a proxy
+        # returning 500/502/503/504) is a transient server/gateway failure.
+        if response.status >= HTTPStatus.INTERNAL_SERVER_ERROR:
             raise ServiceUnavailableError(result) from error
 
         raise OverkizError(

tests/fixtures/exceptions/cloud/502-bad-gateway.html

@@ -0,0 +1 @@
+<html><head><title>502 Bad Gateway</title></head><body><h1>502 Bad Gateway</h1><p>The proxy server received an invalid response from an upstream server.</p></body></html>

tests/test_auth.py

@@ -663,6 +663,106 @@ async def test_login_propagates_non_auth_client_error(self):
                 await strategy.login()
 
 
+def _server_error_response(status: int = 502):
+    """Return a mock token-endpoint response with a 5xx HTML body.
+
+    Mirrors aiohttp: ``response.json()`` (the default, content-type-checked
+    call the strategies use) raises ContentTypeError on an HTML body, while
+    ``response.json(content_type=None)`` (used by check_response) raises
+    JSONDecodeError when it tries to parse the HTML as JSON.
+    """
+    from json import JSONDecodeError
+
+    from aiohttp import ContentTypeError
+
+    html = "<html><head><title>502 Bad Gateway</title></head></html>"
+
+    async def _json(content_type: str | None = "application/json"):
+        if content_type is None:
+            raise JSONDecodeError("Expecting value", html, 0)
+        raise ContentTypeError(
+            request_info=MagicMock(),
+            history=(),
+            message="Attempt to decode JSON with unexpected mimetype: text/html",
+        )
+
+    response = MagicMock()
+    response.status = status
+    response.url = "https://apis.groupe-atlantic.com/token"
+    response.json = AsyncMock(side_effect=_json)
+    response.text = AsyncMock(return_value=html)
+    response.__aenter__ = AsyncMock(return_value=response)
+    response.__aexit__ = AsyncMock(return_value=None)
+    return response
+
+
+class TestTokenEndpointServerErrors:
+    """A 5xx HTML body from a token endpoint must raise a typed Overkiz error."""
+
+    @pytest.mark.asyncio
+    async def test_somfy_token_502_raises_service_unavailable(self):
+        """Somfy token endpoint 502 maps to ServiceUnavailableError, not aiohttp."""
+        from pyoverkiz.exceptions import ServiceUnavailableError
+
+        server_config = ServerConfig(
+            server=Server.SOMFY_EUROPE,
+            name="Somfy",
+            endpoint="https://api.somfy.com",
+            manufacturer="Somfy",
+            api_type=APIType.CLOUD,
+        )
+        credentials = UsernamePasswordCredentials("user", "pass")
+        session = AsyncMock(spec=ClientSession)
+        session.post = MagicMock(return_value=_server_error_response(502))
+
+        strategy = SomfyAuthStrategy(credentials, session, server_config, True)
+
+        with pytest.raises(ServiceUnavailableError):
+            await strategy.login()
+
+    @pytest.mark.asyncio
+    async def test_cozytouch_token_502_raises_service_unavailable(self):
+        """Cozytouch token endpoint 502 maps to ServiceUnavailableError."""
+        from pyoverkiz.exceptions import ServiceUnavailableError
+
+        server_config = ServerConfig(
+            server=Server.ATLANTIC_COZYTOUCH,
+            name="Cozytouch",
+            endpoint="https://api.cozytouch.com",
+            manufacturer="Atlantic",
+            api_type=APIType.CLOUD,
+        )
+        credentials = UsernamePasswordCredentials("user", "pass")
+        session = AsyncMock(spec=ClientSession)
+        session.post = MagicMock(return_value=_server_error_response(502))
+
+        strategy = CozytouchAuthStrategy(credentials, session, server_config, True)
+
+        with pytest.raises(ServiceUnavailableError):
+            await strategy.login()
+
+    @pytest.mark.asyncio
+    async def test_rexel_token_504_raises_service_unavailable(self):
+        """Rexel token exchange 504 maps to ServiceUnavailableError."""
+        from pyoverkiz.exceptions import ServiceUnavailableError
+
+        server_config = ServerConfig(
+            server=Server.REXEL,
+            name="Rexel",
+            endpoint="https://api.rexel.com",
+            manufacturer="Rexel",
+            api_type=APIType.CLOUD,
+        )
+        credentials = RexelOAuthCodeCredentials("code", "https://redirect", "verifier")
+        session = AsyncMock(spec=ClientSession)
+        session.post = MagicMock(return_value=_server_error_response(504))
+
+        strategy = RexelAuthStrategy(credentials, session, server_config, True)
+
+        with pytest.raises(ServiceUnavailableError):
+            await strategy._exchange_token({"grant_type": "authorization_code"})
+
+
 class TestRexelAuthStrategy:
     """Tests for Rexel auth specifics."""
 

tests/test_client.py

@@ -445,6 +445,9 @@ async def test_get_diagnostic_data_returns_structured_dict(
         [
             ("cloud/503-empty.html", exceptions.ServiceUnavailableError, 503),
             ("cloud/503-maintenance.html", exceptions.MaintenanceError, 503),
+            ("cloud/502-bad-gateway.html", exceptions.ServiceUnavailableError, 502),
+            ("cloud/502-bad-gateway.html", exceptions.ServiceUnavailableError, 504),
+            ("cloud/502-bad-gateway.html", exceptions.ServiceUnavailableError, 500),
             (
                 "cloud/access-denied-to-gateway.json",
                 exceptions.AccessDeniedToGatewayError,