Merge pull request #317 from msqd/custom-cache

Custom cache

docs/apps/http_client/examples/http_client_settings.yml

@@ -0,0 +1,6 @@
+http_client:
+  timeout: 10.0
+  cache:
+    disabled: false
+    cacheable_methods: [GET]
+    cacheable_status_codes: [200, 300, 3001]

docs/apps/http_client/index.rst

@@ -0,0 +1,47 @@
+HttpClient
+==========
+
+The `harp_apps.http_client` application implements the core HTTP client features. It uses caching to store responses and avoid making the same request multiple times, improving the efficiency of your application.
+The caching mechanism is implemented using `Hishel <https://hishel.com/>`_ a powerful caching library.
+
+Overview
+--------
+
+The HTTP client provides efficient and configurable HTTP request handling with caching capabilities.
+It is designed to be integrated seamlessly into the `harp` framework.
+
+Features
+--------
+
+- **Caching:** Reduces redundant network calls by storing responses.
+- **Configurable Timeouts:** Allows setting custom timeout values for requests.
+- **Flexible Cache Settings:** Offers options to configure cacheable methods and status codes.
+
+Loading
+-------
+
+The HTTP client application is loaded by default when using the `harp start` command.
+
+Configuration
+-------------
+
+Below is an example configuration for the HTTP client:
+
+.. literalinclude:: ./examples/http_client_settings.yml
+    :language: yaml
+
+
+
+- **timeout:** Specifies the request timeout duration in seconds (default: 30 seconds).
+- **cache:** Configuration for caching behavior.
+  - **disabled:** Boolean flag to enable or disable caching.
+  - **cacheable_methods:** List of HTTP methods that can be cached (e.g., GET).
+  - **cacheable_status_codes:** List of HTTP status codes that can be cached (e.g., 200, 300).
+
+Internal Implementation
+-----------------------
+
+The internal implementation leverages the following classes:
+
+- :class:`CacheSettings <harp_apps.http_client.settings.CacheSettings>`
+- :class:`HttpClientSettings <harp_apps.http_client.settings.HttpClientSettings>`

docs/apps/index.rst

@@ -6,4 +6,5 @@ Applications
 
     dashboard/index
     proxy/index
+    http_client/index
     sqlalchemy_storage/index

docs/reference/apps/harp_apps.http_client.rst

@@ -5,3 +5,11 @@ HTTP Client (harp_apps.http_client)
     :members:
     :undoc-members:
     :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+    :maxdepth: 1
+
+    harp_apps.http_client.settings

docs/reference/apps/harp_apps.http_client.settings.rst

@@ -0,0 +1,7 @@
+harp_apps.http_client.settings
+==============================
+
+.. automodule:: harp_apps.http_client.settings
+    :members:
+    :undoc-members:
+    :show-inheritance:

harp_apps/http_client/__app__.py

@@ -1,27 +1,43 @@
 from hishel import HEURISTICALLY_CACHEABLE_STATUS_CODES, AsyncCacheTransport, Controller
 from httpx import AsyncClient, AsyncHTTPTransport
 
+from harp import get_logger
 from harp.config import Application
 from harp.config.events import FactoryBindEvent
 from harp.settings import DEFAULT_TIMEOUT
 
+from .settings import HttpClientSettings
 
-class HttpClientApplication(Application):
-    async def on_bind(self, event: FactoryBindEvent):
-        # todo timeout config ?
-        # todo lazy build ?
+logger = get_logger(__name__)
+
+
+class AsyncHttpClient(AsyncClient):
+    settings: HttpClientSettings
+
+    def __init__(self, settings: HttpClientSettings):
         transport = AsyncHTTPTransport()
-        cache_transport = AsyncCacheTransport(
-            transport=transport,
-            controller=Controller(
+        if settings.cache and not settings.cache.disabled:
+            controller = Controller(
                 allow_heuristics=True,
-                cacheable_status_codes=HEURISTICALLY_CACHEABLE_STATUS_CODES,
+                cacheable_methods=settings.cache.cacheable_methods,
+                cacheable_status_codes=settings.cache.cacheable_status_codes
+                or list(HEURISTICALLY_CACHEABLE_STATUS_CODES),
                 allow_stale=True,
-            ),
-        )
-        event.container.add_instance(
-            AsyncClient(
-                timeout=DEFAULT_TIMEOUT,
-                transport=cache_transport,
             )
-        )
+            transport = AsyncCacheTransport(transport=transport, controller=controller)
+
+        super().__init__(transport=transport, timeout=settings.timeout)
+
+
+class HttpClientApplication(Application):
+    settings_namespace = "http_client"
+    settings_type = HttpClientSettings
+
+    @classmethod
+    def defaults(cls, settings=None) -> dict:
+        settings = settings if settings is not None else {}
+        settings.setdefault("timeout", DEFAULT_TIMEOUT)
+        return settings
+
+    async def on_bind(self, event: FactoryBindEvent):
+        event.container.add_singleton(AsyncClient, AsyncHttpClient)

harp_apps/http_client/settings.py

@@ -0,0 +1,21 @@
+from typing import Optional
+
+from harp.config.settings.base import BaseSetting, settings_dataclass
+from harp.settings import DEFAULT_TIMEOUT
+
+
+@settings_dataclass
+class CacheSettings:
+    cacheable_methods: Optional[list[str]] = None
+    cacheable_status_codes: Optional[list[int]] = None
+    disabled: Optional[bool] = False
+
+
+@settings_dataclass
+class HttpClientSettings(BaseSetting):
+    cache: Optional[CacheSettings] = None
+    timeout: Optional[float] = DEFAULT_TIMEOUT
+
+    def __post_init__(self):
+        if self.cache:
+            self.cache = self.cache if isinstance(self.cache, CacheSettings) else CacheSettings(**self.cache)