Allow using cached results

Author: Shutgun

CHANGELOG.md

@@ -4,7 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v1.1.0] - 2022/02/16
+## [v1.2.0] - 2023/03/06
+
+### Added
+
+- Allow using cached results
+
+## [v1.1.0] - 2023/02/16
 
 ### Added
 

README.md

@@ -59,7 +59,19 @@ async def analyze():
 asyncio.run(analyze())
 ```
 
-This will give you a [Host object](https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs-v3.md#host) as dataclass. This call runs quite long as it takes time to run all tests. You probably know that from using the [webinterface](https://www.ssllabs.com/ssltest).
+This will give you a [Host object](https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs-v3.md#host) as dataclass. This call runs quite long as it takes time to run all tests. You probably know that from using the [webinterface](https://www.ssllabs.com/ssltest). If you don't need a fresh result on every run, you can allow using ssllabs' cache. This will speed up the tests, if there are cached results. The maximum cache validity can be set in full hour steps.
+
+```python
+import asyncio
+
+from ssllabs import Ssllabs
+
+async def analyze():
+    ssllabs = Ssllabs()
+    return await ssllabs.analyze(host="devolo.de", from_cache=True, max_age=1)
+
+asyncio.run(analyze())
+```
 
 ### Check availability of the SSL Labs servers
 
@@ -75,7 +87,7 @@ async def availability():
 asyncio.run(availability())
 ```
 
-This will give you True, if the servers are up and running, otherwise False. It will also report False, if you exeeded your rate limits.
+This will give you True, if the servers are up and running, otherwise False. It will also report False, if you exceeded your rate limits.
 
 ### Retrieve API information
 
@@ -107,7 +119,7 @@ async def root_certs():
 asyncio.run(root_certs())
 ```
 
-This will give you a string containing the latest root certificates used for trust validation. By default it used the certificates provided by Mozilla. You can choose a differenty store by changing trust_store to 1: Mozilla, 2: Apple MacOS, 3: Android, 4: Java or 5: Windows.
+This will give you a string containing the latest root certificates used for trust validation. By default it used the certificates provided by Mozilla. You can choose a differently store by changing trust_store to 1: Mozilla, 2: Apple MacOS, 3: Android, 4: Java or 5: Windows.
 
 ### Retrieve known status codes
 

ssllabs/ssllabs.py

@@ -2,7 +2,7 @@
 import logging
 from typing import Optional
 
-from httpx import AsyncClient, ConnectTimeout, HTTPStatusError, ReadTimeout
+from httpx import AsyncClient, ConnectTimeout, HTTPStatusError, ReadError, ReadTimeout
 
 from .api import Analyze, Info, RootCertsRaw, StatusCodes
 from .data.host import HostData
@@ -29,17 +29,26 @@ async def availability(self) -> bool:
             await i.get()
             self._logger.info("SSL Labs servers are up an running.")
             return True
-        except (HTTPStatusError, ReadTimeout, ConnectTimeout) as ex:
+        except (HTTPStatusError, ReadError, ReadTimeout, ConnectTimeout) as ex:
             self._logger.error(ex)
             return False
 
-    async def analyze(self, host: str, publish: bool = False, ignore_mismatch: bool = False) -> HostData:
+    async def analyze(
+        self,
+        host: str,
+        publish: bool = False,
+        ignore_mismatch: bool = False,
+        from_cache: bool = False,
+        max_age: Optional[int] = None,
+    ) -> HostData:
         """
         Test a particular host with respect to the cool off and the maximum number of assessments.
 
         :param host: Host to test
         :param publish: True if assessment results should be published on the public results boards
         :param ignore_mismatch: True if assessment shall proceed even when the server certificate doesn't match the hostname
+        :param from_cache: True if cached results should be used instead of new assessments
+        :param max_age: Maximum age cached data might have in hours
 
         See also: https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs-v3.md#protocol-usage
         """
@@ -60,7 +69,11 @@ async def analyze(self, host: str, publish: bool = False, ignore_mismatch: bool
 
         a = Analyze(self._client)
         host_object = await a.get(
-            host=host, startNew="on", publish="on" if publish else "off", ignoreMismatch="on" if ignore_mismatch else "off"
+            host=host,
+            startNew="off" if from_cache else "on",
+            publish="on" if publish else "off",
+            ignoreMismatch="on" if ignore_mismatch else "off",
+            maxAge=max_age,
         )
         self._semaphore.release()
         while host_object.status not in ["READY", "ERROR"]:

tests/test_ssllabs.py

@@ -4,7 +4,7 @@
 
 import pytest
 from dacite import from_dict
-from httpx import ConnectTimeout, HTTPStatusError, ReadTimeout
+from httpx import ConnectTimeout, HTTPStatusError, ReadError, ReadTimeout, TransportError
 
 from ssllabs import Ssllabs
 from ssllabs.api.analyze import Analyze
@@ -33,16 +33,20 @@ async def test_ssllabs(self, request, api, result, parameters):
             assert dataclasses.asdict(api_data) == getattr(request.cls, call)
 
     @pytest.mark.asyncio
-    async def test_analyze(self, request):
+    async def test_analyze(self, request: pytest.FixtureRequest) -> None:
         with patch(
             "ssllabs.api.info.Info.get", new=AsyncMock(return_value=from_dict(data_class=InfoData, data=request.cls.info))
         ), patch(
             "ssllabs.api.analyze.Analyze.get",
             new=AsyncMock(return_value=from_dict(data_class=HostData, data=request.cls.analyze)),
-        ):
+        ) as get:
             ssllabs = Ssllabs()
             api_data = await ssllabs.analyze(host="devolo.de")
             assert dataclasses.asdict(api_data) == request.cls.analyze
+            get.assert_called_with(host="devolo.de", ignoreMismatch="off", publish="off", startNew="on", maxAge=None)
+            api_data = await ssllabs.analyze(host="devolo.de", from_cache=True, max_age=1)
+            assert dataclasses.asdict(api_data) == request.cls.analyze
+            get.assert_called_with(host="devolo.de", ignoreMismatch="off", publish="off", startNew="off", maxAge=1)
 
     @pytest.mark.asyncio
     async def test_analyze_not_ready_yet(self, request, mocker):
@@ -119,8 +123,8 @@ async def test_availabile(self, request):
             assert await ssllabs.availability()
 
     @pytest.mark.asyncio
-    @pytest.mark.parametrize("exception", [ReadTimeout, ConnectTimeout])
-    async def test_unavailabile_timeout(self, exception):
+    @pytest.mark.parametrize("exception", [ReadError, ReadTimeout, ConnectTimeout])
+    async def test_unavailabile_timeout(self, exception: TransportError) -> None:
         with patch("ssllabs.api.info.Info.get", new=AsyncMock(side_effect=exception(message="", request=""))):
             ssllabs = Ssllabs()
             assert not await ssllabs.availability()