nlbone 0.4.3__py3-none-any.whl → 0.5.0__py3-none-any.whl

nlbone/adapters/cache/async_redis.py

@@ -0,0 +1,180 @@
+import asyncio
+import json
+import os
+from typing import Optional, Iterable, Any, Mapping, Sequence, List
+
+from redis.asyncio import Redis
+from nlbone.core.ports.cache import AsyncCachePort
+
+
+def _nsver_key(ns: str) -> str: return f"nsver:{ns}"
+def _tag_key(tag: str) -> str: return f"tag:{tag}"
+
+class AsyncRedisCache(AsyncCachePort):
+    def __init__(self, url: str, *, invalidate_channel: str | None = None):
+        self._r = Redis.from_url(url, decode_responses=False)
+        self._ch = invalidate_channel or os.getenv("NLBONE_REDIS_INVALIDATE_CHANNEL", "cache:invalidate")
+
+    @property
+    def redis(self) -> Redis:
+        return self._r
+
+    async def _current_ver(self, ns: str) -> int:
+        v = await self._r.get(_nsver_key(ns))
+        return int(v) if v else 1
+
+    async def _full_key(self, key: str) -> str:
+        try:
+            ns, rest = key.split(":", 1)
+        except ValueError:
+            ns, rest = "app", key
+        ver = await self._current_ver(ns)
+        return f"{ns}:{ver}:{rest}"
+
+    # -------- basic --------
+    async def get(self, key: str) -> Optional[bytes]:
+        fk = await self._full_key(key)
+        return await self._r.get(fk)
+
+    async def set(self, key: str, value: bytes, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None:
+        fk = await self._full_key(key)
+        if ttl is None:
+            await self._r.set(fk, value)
+        else:
+            await self._r.setex(fk, ttl, value)
+        if tags:
+            pipe = self._r.pipeline()
+            for t in tags:
+                pipe.sadd(_tag_key(t), fk)
+            await pipe.execute()
+
+    async def delete(self, key: str) -> None:
+        fk = await self._full_key(key)
+        await self._r.delete(fk)
+
+    async def exists(self, key: str) -> bool:
+        return (await self.get(key)) is not None
+
+    async def ttl(self, key: str) -> Optional[int]:
+        fk = await self._full_key(key)
+        t = await self._r.ttl(fk)
+        return None if t < 0 else int(t)
+
+        # -------- multi --------
+
+    async def mget(self, keys: Sequence[str]) -> list[Optional[bytes]]:
+        fks = [await self._full_key(k) for k in keys]
+        return await self._r.mget(fks)
+
+    async def mset(self, items: Mapping[str, bytes], *, ttl: Optional[int] = None,
+                   tags: Optional[Iterable[str]] = None) -> None:
+        pipe = self._r.pipeline()
+        if ttl is None:
+            for k, v in items.items():
+                fk = await self._full_key(k)
+                pipe.set(fk, v)
+        else:
+            for k, v in items.items():
+                fk = await self._full_key(k)
+                pipe.setex(fk, ttl, v)
+        await pipe.execute()
+
+        if tags:
+            pipe = self._r.pipeline()
+            for t in tags:
+                for k in items.keys():
+                    fk = await self._full_key(k)
+                    pipe.sadd(_tag_key(t), fk)
+            await pipe.execute()
+
+        # -------- json --------
+
+    async def get_json(self, key: str) -> Optional[Any]:
+        b = await self.get(key)
+        return None if b is None else json.loads(b)
+
+    async def set_json(self, key: str, value: Any, *, ttl: Optional[int] = None,
+                       tags: Optional[Iterable[str]] = None) -> None:
+        await self.set(key, json.dumps(value).encode("utf-8"), ttl=ttl, tags=tags)
+
+        # -------- invalidation --------
+
+    async def invalidate_tags(self, tags: Iterable[str]) -> int:
+        removed = 0
+        pipe = self._r.pipeline()
+        key_sets: list[tuple[str, set[bytes]]] = []
+        for t in tags:
+            tk = _tag_key(t)
+            members = await self._r.smembers(tk)
+            if members:
+                pipe.delete(*members)
+            pipe.delete(tk)
+            key_sets.append((tk, members))
+            removed += len(members or [])
+        await pipe.execute()
+
+        # publish notification for other processes
+        try:
+            payload = json.dumps({"tags": list(tags)}).encode("utf-8")
+            await self._r.publish(self._ch, payload)
+        except Exception:
+            pass
+
+        return removed
+
+    async def bump_namespace(self, namespace: str) -> int:
+        v = await self._r.incr(_nsver_key(namespace))
+        # اطلاع‌رسانی اختیاری
+        try:
+            await self._r.publish(self._ch, json.dumps({"ns_bump": namespace}).encode("utf-8"))
+        except Exception:
+            pass
+        return int(v)
+
+    async def clear_namespace(self, namespace: str) -> int:
+        cnt = 0
+        cursor = 0
+        pattern = f"{namespace}:*"
+        while True:
+            cursor, keys = await self._r.scan(cursor=cursor, match=pattern, count=1000)
+            if keys:
+                await self._r.delete(*keys)
+                cnt += len(keys)
+            if cursor == 0:
+                break
+        try:
+            await self._r.publish(self._ch, json.dumps({"ns_clear": namespace}).encode("utf-8"))
+        except Exception:
+            pass
+        return cnt
+
+        # -------- dogpile-safe get_or_set --------
+
+    async def get_or_set(self, key: str, producer, *, ttl: int, tags=None) -> bytes:
+        fk = await self._full_key(key)
+        val = await self._r.get(fk)
+        if val is not None:
+            return val
+
+        lock_key = f"lock:{fk}"
+        got = await self._r.set(lock_key, b"1", ex=10, nx=True)
+        if got:
+            try:
+                produced = await producer() if asyncio.iscoroutinefunction(producer) else producer()
+                if isinstance(produced, str):
+                    produced = produced.encode("utf-8")
+                await self.set(key, produced, ttl=ttl, tags=tags)
+                return produced
+            finally:
+                await self._r.delete(lock_key)
+
+        await asyncio.sleep(0.05)
+        val2 = await self._r.get(fk)
+        if val2 is not None:
+            return val2
+        # fallback
+        produced = await producer() if asyncio.iscoroutinefunction(producer) else producer()
+        if isinstance(produced, str):
+            produced = produced.encode("utf-8")
+        await self.set(key, produced, ttl=ttl, tags=tags)
+        return produced

nlbone/adapters/cache/memory.py

@@ -0,0 +1,104 @@
+import json, threading, time
+from typing import Optional, Iterable, Any, Mapping, Sequence, Dict, Set
+from nlbone.core.ports.cache import CachePort
+
+
+class InMemoryCache(CachePort):
+    def __init__(self):
+        self._data: Dict[str, tuple[bytes, Optional[float]]] = {}
+        self._tags: Dict[str, Set[str]] = {}
+        self._ns_ver: Dict[str, int] = {}
+        self._lock = threading.RLock()
+
+    def _expired(self, key: str) -> bool:
+        v = self._data.get(key)
+        if not v: return True
+        _, exp = v
+        return exp is not None and time.time() > exp
+
+    def _gc(self, key: str) -> None:
+        if self._expired(key):
+            self._data.pop(key, None)
+
+    def _attach_tags(self, key: str, tags: Optional[Iterable[str]]) -> None:
+        if not tags: return
+        for t in tags:
+            self._tags.setdefault(t, set()).add(key)
+
+    def get(self, key: str) -> Optional[bytes]:
+        with self._lock:
+            self._gc(key)
+            v = self._data.get(key)
+            return v[0] if v else None
+
+    def set(self, key: str, value: bytes, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None:
+        with self._lock:
+            exp = None if ttl is None else time.time() + ttl
+            self._data[key] = (value, exp)
+            self._attach_tags(key, tags)
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._data.pop(key, None)
+            for s in self._tags.values():
+                s.discard(key)
+
+    def exists(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def ttl(self, key: str) -> Optional[int]:
+        with self._lock:
+            self._gc(key)
+            v = self._data.get(key)
+            if not v: return None
+            _, exp = v
+            if exp is None: return None
+            rem = int(exp - time.time())
+            return rem if rem >= 0 else 0
+
+    def mget(self, keys: Sequence[str]) -> list[Optional[bytes]]:
+        return [self.get(k) for k in keys]
+
+    def mset(self, items: Mapping[str, bytes], *, ttl: Optional[int] = None,
+             tags: Optional[Iterable[str]] = None) -> None:
+        for k, v in items.items():
+            self.set(k, v, ttl=ttl, tags=tags)
+
+    def get_json(self, key: str) -> Optional[Any]:
+        b = self.get(key)
+        return None if b is None else json.loads(b)
+
+    def set_json(self, key: str, value: Any, *, ttl: Optional[int] = None,
+                 tags: Optional[Iterable[str]] = None) -> None:
+        self.set(key, json.dumps(value).encode("utf-8"), ttl=ttl, tags=tags)
+
+    def invalidate_tags(self, tags: Iterable[str]) -> int:
+        removed = 0
+        with self._lock:
+            for t in tags:
+                keys = self._tags.pop(t, set())
+                for k in keys:
+                    if k in self._data:
+                        self._data.pop(k, None)
+                        removed += 1
+        return removed
+
+    def bump_namespace(self, namespace: str) -> int:
+        with self._lock:
+            self._ns_ver[namespace] = self._ns_ver.get(namespace, 0) + 1
+            return self._ns_ver[namespace]
+
+    def clear_namespace(self, namespace: str) -> int:
+        with self._lock:
+            keys = [k for k in self._data.keys() if k.startswith(namespace + ":")]
+            for k in keys: self.delete(k)
+            return len(keys)
+
+    def get_or_set(self, key: str, producer, *, ttl: int, tags=None) -> bytes:
+        with self._lock:
+            b = self.get(key)
+            if b is not None:
+                return b
+        val: bytes = producer()
+        self.set(key, val, ttl=ttl, tags=tags)
+        return val

nlbone/adapters/cache/pubsub_listener.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+import asyncio
+import json
+from typing import Awaitable, Callable, Optional
+from redis.asyncio import Redis
+
+async def run_cache_invalidation_listener(
+    redis: Redis,
+    channel: str = "cache:invalidate",
+    *,
+    on_tags: Optional[Callable[[list[str]], Awaitable[None]]] = None,
+    on_ns_bump: Optional[Callable[[str], Awaitable[None]]] = None,
+    on_ns_clear: Optional[Callable[[str], Awaitable[None]]] = None,
+    stop_event: Optional[asyncio.Event] = None,
+) -> None:
+    pubsub = redis.pubsub()
+    await pubsub.subscribe(channel)
+    try:
+        while True:
+            if stop_event and stop_event.is_set():
+                break
+            message = await pubsub.get_message(ignore_subscribe_messages=True, timeout=1.0)
+            if not message:
+                await asyncio.sleep(0.05)
+                continue
+            try:
+                data = json.loads(message["data"])
+            except Exception:
+                continue
+
+            if "tags" in data and on_tags:
+                tags = data.get("tags") or []
+                await on_tags(list(tags))
+            if "ns_bump" in data and on_ns_bump:
+                await on_ns_bump(str(data["ns_bump"]))
+            if "ns_clear" in data and on_ns_clear:
+                await on_ns_clear(str(data["ns_clear"]))
+    finally:
+        try:
+            await pubsub.unsubscribe(channel)
+        finally:
+            await pubsub.close()

nlbone/adapters/cache/redis.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+import json, os, time
+from typing import Optional, Iterable, Any, Mapping, Sequence, List, Set
+import redis  # redis-py (sync)
+from nlbone.core.ports.cache import CachePort
+
+
+
+def _nsver_key(ns: str) -> str: return f"nsver:{ns}"
+def _tag_key(tag: str) -> str: return f"tag:{tag}"
+
+class RedisCache(CachePort):
+    def __init__(self, url: str):
+        self.r = redis.Redis.from_url(url, decode_responses=False)
+
+    def _current_ver(self, ns: str) -> int:
+        v = self.r.get(_nsver_key(ns))
+        return int(v) if v else 1
+
+    def _full_key(self, key: str) -> str:
+        try:
+            ns, rest = key.split(":", 1)
+        except ValueError:
+            ns, rest = "app", key
+        ver = self._current_ver(ns)
+        return f"{ns}:{ver}:{rest}"
+
+    def get(self, key: str) -> Optional[bytes]:
+        fk = self._full_key(key)
+        return self.r.get(fk)
+
+    def set(self, key: str, value: bytes, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None:
+        fk = self._full_key(key)
+        if ttl is None:
+            self.r.set(fk, value)
+        else:
+            self.r.setex(fk, ttl, value)
+        if tags:
+            pipe = self.r.pipeline()
+            for t in tags:
+                pipe.sadd(_tag_key(t), fk)
+            pipe.execute()
+
+    def delete(self, key: str) -> None:
+        fk = self._full_key(key)
+        self.r.delete(fk)
+
+    def exists(self, key: str) -> bool:
+        return bool(self.get(key))
+
+    def ttl(self, key: str) -> Optional[int]:
+        fk = self._full_key(key)
+        t = self.r.ttl(fk)
+        return None if t < 0 else int(t)
+
+    def mget(self, keys: Sequence[str]) -> list[Optional[bytes]]:
+        fks = [self._full_key(k) for k in keys]
+        return self.r.mget(fks)
+
+    def mset(self, items: Mapping[str, bytes], *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None:
+        pipe = self.r.pipeline()
+        if ttl is None:
+            for k, v in items.items():
+                pipe.set(self._full_key(k), v)
+        else:
+            for k, v in items.items():
+                pipe.setex(self._full_key(k), ttl, v)
+        pipe.execute()
+        if tags:
+            pipe = self.r.pipeline()
+            for t in tags:
+                for k in items.keys():
+                    pipe.sadd(_tag_key(t), self._full_key(k))
+            pipe.execute()
+
+    def get_json(self, key: str) -> Optional[Any]:
+        b = self.get(key)
+        return None if b is None else json.loads(b)
+
+    def set_json(self, key: str, value: Any, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None:
+        self.set(key, json.dumps(value).encode("utf-8"), ttl=ttl, tags=tags)
+
+    def invalidate_tags(self, tags: Iterable[str]) -> int:
+        removed = 0
+        pipe = self.r.pipeline()
+        for t in tags:
+            tk = _tag_key(t)
+            keys = self.r.smembers(tk)
+            if keys:
+                pipe.delete(*keys)
+            pipe.delete(tk)
+            removed += len(keys or [])
+        pipe.execute()
+        try:
+            ch = os.getenv("NLBONE_REDIS_INVALIDATE_CHANNEL", "cache:invalidate")
+            self.r.publish(ch, json.dumps({"tags": list(tags)}).encode("utf-8"))
+        except Exception:
+            pass
+        return removed
+
+    def bump_namespace(self, namespace: str) -> int:
+        v = self.r.incr(_nsver_key(namespace))
+        return int(v)
+
+    def clear_namespace(self, namespace: str) -> int:
+        cnt = 0
+        cursor = 0
+        pattern = f"{namespace}:*"
+        while True:
+            cursor, keys = self.r.scan(cursor=cursor, match=pattern, count=1000)
+            if keys:
+                self.r.delete(*keys); cnt += len(keys)
+            if cursor == 0: break
+        return cnt
+
+    def get_or_set(self, key: str, producer, *, ttl: int, tags=None) -> bytes:
+        fk = self._full_key(key)
+        val = self.r.get(fk)
+        if val is not None:
+            return val
+        lock_key = f"lock:{fk}"
+        got = self.r.set(lock_key, b"1", nx=True, ex=10)
+        if got:
+            try:
+                produced: bytes = producer()
+                self.set(key, produced, ttl=ttl, tags=tags)
+                return produced
+            finally:
+                self.r.delete(lock_key)
+        time.sleep(0.05)
+        val2 = self.r.get(fk)
+        if val2 is not None:
+            return val2
+        produced: bytes = producer()
+        self.set(key, produced, ttl=ttl, tags=tags)
+        return produced

nlbone/adapters/http_clients/uploadchi.py

@@ -91,7 +91,7 @@ class UploadchiClient(FileServicePort):
         tok = _resolve_token(token)
         r = self._client.post(
             f"{self._base_url}/{file_id}/commit",
-            headers=_auth_headers(tok),
+            headers=_auth_headers(tok or self._token_provider.get_access_token()),
         )
         if r.status_code not in (204, 200):
             raise UploadchiError(r.status_code, r.text)
@@ -102,7 +102,7 @@ class UploadchiClient(FileServicePort):
         tok = _resolve_token(token)
         r = self._client.post(
             f"{self._base_url}/{file_id}/rollback",
-            headers=_auth_headers(tok),
+            headers=_auth_headers(tok or self._token_provider.get_access_token()),
         )
         if r.status_code not in (204, 200):
             raise UploadchiError(r.status_code, r.text)

nlbone/adapters/http_clients/uploadchi_async.py

@@ -46,7 +46,7 @@ class UploadchiAsyncClient(AsyncFileServicePort):
             raise UploadchiError(detail="token_provider is not provided", status=400)
         tok = _resolve_token(token)
         r = await self._client.post(
-            f"/{file_id}/commit", headers=_auth_headers(tok)
+            f"/{file_id}/commit", headers=_auth_headers(tok or self._token_provider.get_access_token())
         )
         if r.status_code not in (204, 200):
             raise UploadchiError(r.status_code, await r.aread())
@@ -56,7 +56,7 @@ class UploadchiAsyncClient(AsyncFileServicePort):
             raise UploadchiError(detail="token_provider is not provided", status=400)
         tok = _resolve_token(token)
         r = await self._client.post(
-            f"/{file_id}/rollback", headers=_auth_headers(tok)
+            f"/{file_id}/rollback", headers=_auth_headers(tok or self._token_provider.get_access_token())
         )
         if r.status_code not in (204, 200):
             raise UploadchiError(r.status_code, await r.aread())

nlbone/config/settings.py

@@ -65,6 +65,8 @@ class Settings(BaseSettings):
     # Messaging / Cache
     # ---------------------------
     REDIS_URL: str = Field(default="redis://localhost:6379/0")
+    CACHE_BACKEND: Literal["memory", "redis"] = Field(default="memory")
+    CACHE_DEFAULT_TTL_S: int = Field(default=300)
 
     # --- Event bus / Outbox ---
     EVENT_BUS_BACKEND: Literal["inmemory"] = Field(default="inmemory")

nlbone/container.py

@@ -6,12 +6,16 @@ from dependency_injector import containers, providers
 
 from nlbone.adapters.auth.keycloak import KeycloakAuthService
 from nlbone.adapters.auth.token_provider import ClientTokenProvider
+from nlbone.adapters.cache.async_redis import AsyncRedisCache
+from nlbone.adapters.cache.memory import InMemoryCache
+from nlbone.adapters.cache.redis import RedisCache
 from nlbone.adapters.db.postgres import AsyncSqlAlchemyUnitOfWork, SqlAlchemyUnitOfWork
 from nlbone.adapters.db.postgres.engine import get_async_session_factory, get_sync_session_factory
 from nlbone.adapters.http_clients.uploadchi import UploadchiClient
 from nlbone.adapters.http_clients.uploadchi_async import UploadchiAsyncClient
 from nlbone.adapters.messaging import InMemoryEventBus
 from nlbone.core.ports import EventBusPort
+from nlbone.core.ports.cache import CachePort, AsyncCachePort
 from nlbone.core.ports.files import AsyncFileServicePort, FileServicePort
 
 
@@ -36,6 +40,18 @@ class Container(containers.DeclarativeContainer):
     afiles_service: providers.Singleton[AsyncFileServicePort] = providers.Singleton(UploadchiAsyncClient,
                                                                                     token_provider=token_provider)
 
+    cache: providers.Singleton[CachePort] = providers.Selector(
+        config.CACHE_BACKEND,
+        memory=providers.Singleton(InMemoryCache),
+        redis=providers.Singleton(RedisCache, url=config.REDIS_URL),
+    )
+
+    async_cache: providers.Singleton[AsyncCachePort] = providers.Selector(
+        config.CACHE_BACKEND,
+        memory=providers.Singleton(InMemoryCache),
+        redis=providers.Singleton(AsyncRedisCache, url=config.REDIS_URL),
+    )
+
 
 def create_container(settings: Optional[Any] = None) -> Container:
     c = Container()

nlbone/core/ports/cache.py

@@ -0,0 +1,37 @@
+from typing import Protocol, Optional, Iterable, Any, Mapping, Sequence, Tuple, TypeVar, Callable
+
+T = TypeVar("T")
+
+class CachePort(Protocol):
+    def get(self, key: str) -> Optional[bytes]: ...
+    def set(self, key: str, value: bytes, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None: ...
+    def delete(self, key: str) -> None: ...
+    def exists(self, key: str) -> bool: ...
+    def ttl(self, key: str) -> Optional[int]: ...
+
+    def mget(self, keys: Sequence[str]) -> list[Optional[bytes]]: ...
+    def mset(self, items: Mapping[str, bytes], *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None: ...
+
+    def get_json(self, key: str) -> Optional[Any]: ...
+    def set_json(self, key: str, value: Any, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None: ...
+
+    def invalidate_tags(self, tags: Iterable[str]) -> int: ...
+    def bump_namespace(self, namespace: str) -> int: ...  # versioned keys
+    def clear_namespace(self, namespace: str) -> int: ...
+
+    def get_or_set(self, key: str, producer: Callable[[], bytes], *, ttl: int, tags: Optional[Iterable[str]] = None) -> bytes: ...
+
+class AsyncCachePort(Protocol):
+    async def get(self, key: str) -> Optional[bytes]: ...
+    async def set(self, key: str, value: bytes, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None: ...
+    async def delete(self, key: str) -> None: ...
+    async def exists(self, key: str) -> bool: ...
+    async def ttl(self, key: str) -> Optional[int]: ...
+    async def mget(self, keys: Sequence[str]) -> list[Optional[bytes]]: ...
+    async def mset(self, items: Mapping[str, bytes], *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None: ...
+    async def get_json(self, key: str) -> Optional[Any]: ...
+    async def set_json(self, key: str, value: Any, *, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None: ...
+    async def invalidate_tags(self, tags: Iterable[str]) -> int: ...
+    async def bump_namespace(self, namespace: str) -> int: ...
+    async def clear_namespace(self, namespace: str) -> int: ...
+    async def get_or_set(self, key: str, producer, *, ttl: int, tags: Optional[Iterable[str]] = None) -> bytes: ...

nlbone/utils/cache.py

@@ -0,0 +1,196 @@
+import asyncio
+import inspect
+import json
+from typing import Any, Callable, Iterable, Optional
+
+from makefun import wraps as mf_wraps
+from nlbone.utils.cache_registry import get_cache
+
+try:
+    from pydantic import BaseModel  # v1/v2
+except Exception:  # pragma: no cover
+    class BaseModel:  # minimal fallback
+        pass
+
+
+# -------- helpers --------
+
+def _bind(func: Callable, args, kwargs):
+    sig = inspect.signature(func)
+    bound = sig.bind_partial(*args, **kwargs)
+    bound.apply_defaults()
+    return bound
+
+
+def _key_from_template(
+    tpl: Optional[str],
+    func: Callable,
+    args,
+    kwargs,
+) -> str:
+    """Format key template with bound arguments or build a stable default."""
+    bound = _bind(func, args, kwargs)
+    if tpl:
+        return tpl.format(**bound.arguments)
+
+    # Default stable key: module:qualname:sha of args
+    payload = json.dumps(bound.arguments, sort_keys=True, default=str)
+    return f"{func.__module__}:{func.__qualname__}:{hash(payload)}"
+
+
+def _format_tags(
+    tag_tpls: Optional[Iterable[str]],
+    func: Callable,
+    args,
+    kwargs,
+) -> list[str] | None:
+    if not tag_tpls:
+        return None
+    bound = _bind(func, args, kwargs)
+    return [t.format(**bound.arguments) for t in tag_tpls]
+
+
+def default_serialize(val: Any) -> bytes:
+    """Serialize BaseModel (v2/v1) or JSON-serializable data to bytes."""
+    if isinstance(val, BaseModel):
+        if hasattr(val, "model_dump_json"):  # pydantic v2
+            return val.model_dump_json().encode("utf-8")
+        if hasattr(val, "json"):  # pydantic v1
+            return val.json().encode("utf-8")
+    return json.dumps(val, default=str).encode("utf-8")
+
+
+def default_deserialize(b: bytes) -> Any:
+    return json.loads(b)
+
+
+def _is_async_method(obj: Any, name: str) -> bool:
+    meth = getattr(obj, name, None)
+    return asyncio.iscoroutinefunction(meth)
+
+
+def _run_maybe_async(func: Callable, *args, **kwargs):
+    """Call a function that may be async from sync context."""
+    result = func(*args, **kwargs)
+    if inspect.isawaitable(result):
+        return asyncio.run(result)
+    return result
+
+
+# -------- cache decorators --------
+
+def cached(
+    *,
+    ttl: int,
+    key: str | None = None,
+    tags: Iterable[str] | None = None,
+    serializer: Callable[[Any], bytes] = default_serialize,
+    deserializer: Callable[[bytes], Any] = default_deserialize,
+    cache_resolver: Optional[Callable[[], Any]] = None,
+):
+    """
+    Framework-agnostic caching for SYNC or ASYNC callables.
+    - Preserves function signature (good for FastAPI/OpenAPI).
+    - Works with sync/async cache backends (CachePort / AsyncCachePort).
+    - `key` & `tags` are string templates, e.g. "file:{file_id}".
+    """
+    def deco(func: Callable):
+        is_async_func = asyncio.iscoroutinefunction(func)
+
+        if is_async_func:
+            @mf_wraps(func)
+            async def aw(*args, **kwargs):
+                cache = (cache_resolver or get_cache)()
+                k = _key_from_template(key, func, args, kwargs)
+                tg = _format_tags(tags, func, args, kwargs)
+
+                # GET
+                if _is_async_method(cache, "get"):
+                    cached_bytes = await cache.get(k)
+                else:
+                    cached_bytes = cache.get(k)
+
+                if cached_bytes is not None:
+                    return deserializer(cached_bytes)
+
+                # MISS -> compute
+                result = await func(*args, **kwargs)
+
+                # SET
+                data = serializer(result)
+                if _is_async_method(cache, "set"):
+                    await cache.set(k, data, ttl=ttl, tags=tg)
+                else:
+                    cache.set(k, data, ttl=ttl, tags=tg)
+
+                return result
+
+            return aw
+
+        # SYNC callable
+        @mf_wraps(func)
+        def sw(*args, **kwargs):
+            cache = (cache_resolver or get_cache)()
+            k = _key_from_template(key, func, args, kwargs)
+            tg = _format_tags(tags, func, args, kwargs)
+
+            # GET (may be async)
+            if _is_async_method(cache, "get"):
+                cached_bytes = _run_maybe_async(cache.get, k)
+            else:
+                cached_bytes = cache.get(k)
+
+            if cached_bytes is not None:
+                return deserializer(cached_bytes)
+
+            # MISS -> compute
+            result = func(*args, **kwargs)
+
+            # SET (may be async)
+            data = serializer(result)
+            if _is_async_method(cache, "set"):
+                _run_maybe_async(cache.set, k, data, ttl=ttl, tags=tg)
+            else:
+                cache.set(k, data, ttl=ttl, tags=tg)
+
+            return result
+
+        return sw
+
+    return deco
+
+
+def invalidate_by_tags(tags_builder: Callable[..., Iterable[str]]):
+    """
+    Invalidate computed tags after function finishes.
+    Works with sync or async functions and cache backends.
+    """
+    def deco(func: Callable):
+        is_async_func = asyncio.iscoroutinefunction(func)
+
+        if is_async_func:
+            @mf_wraps(func)
+            async def aw(*args, **kwargs):
+                out = await func(*args, **kwargs)
+                cache = get_cache()
+                tags = list(tags_builder(*args, **kwargs))
+                if _is_async_method(cache, "invalidate_tags"):
+                    await cache.invalidate_tags(tags)
+                else:
+                    cache.invalidate_tags(tags)
+                return out
+            return aw
+
+        @mf_wraps(func)
+        def sw(*args, **kwargs):
+            out = func(*args, **kwargs)
+            cache = get_cache()
+            tags = list(tags_builder(*args, **kwargs))
+            if _is_async_method(cache, "invalidate_tags"):
+                _run_maybe_async(cache.invalidate_tags, tags)
+            else:
+                cache.invalidate_tags(tags)
+            return out
+        return sw
+
+    return deco

nlbone/utils/cache_keys.py

@@ -0,0 +1,30 @@
+import hashlib
+import json
+import random
+from typing import Any, Mapping
+
+def _stable_params(params: Mapping[str, Any]) -> str:
+    return json.dumps(params, sort_keys=True, separators=(",", ":"))
+
+def make_key(ns: str, *parts: str) -> str:
+    safe_parts = [p.replace(" ", "_") for p in parts if p]
+    return f"{ns}:{':'.join(safe_parts)}" if safe_parts else f"{ns}:root"
+
+def make_param_key(ns: str, base: str, params: Mapping[str, Any]) -> str:
+    payload = _stable_params(params)
+    digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+    return f"{ns}:{base}:{digest}"
+
+def tag_entity(ns: str, entity_id: Any) -> str:
+    return f"{ns}:{entity_id}"
+
+def tag_list(ns: str, **filters) -> str:
+    if not filters:
+        return f"{ns}:list"
+    payload = _stable_params(filters)
+    digest = hashlib.md5(payload.encode("utf-8")).hexdigest()[:12]
+    return f"{ns}:list:{digest}"
+
+def ttl_with_jitter(base_ttl: int, *, jitter_ratio: float = 0.1) -> int:
+    jitter = int(base_ttl * jitter_ratio)
+    return base_ttl + random.randint(-jitter, jitter)

nlbone/utils/cache_registry.py

@@ -0,0 +1,23 @@
+from typing import Callable, Optional, TypeVar
+from contextvars import ContextVar
+
+T = TypeVar("T")
+
+_global_resolver: Optional[Callable[[], T]] = None
+
+_ctx_resolver: ContextVar[Optional[Callable[[], T]]] = ContextVar("_ctx_resolver", default=None)
+
+def set_cache_resolver(fn: Callable[[], T]) -> None:
+    """Set process-wide cache resolver (e.g., lambda: container.cache())."""
+    global _global_resolver
+    _global_resolver = fn
+
+def set_context_cache_resolver(fn: Optional[Callable[[], T]]) -> None:
+    """Override resolver in current context (useful in tests/background tasks)."""
+    _ctx_resolver.set(fn)
+
+def get_cache() -> T:
+    fn = _ctx_resolver.get() or _global_resolver
+    if fn is None:
+        raise RuntimeError("Cache resolver not configured. Call set_cache_resolver(...) first.")
+    return fn()

{nlbone-0.4.3.dist-info → nlbone-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nlbone
-Version: 0.4.3
+Version: 0.5.0
 Summary: Backbone package for interfaces and infrastructure in Python projects
 Author-email: Amir Hosein Kahkbazzadeh <a.khakbazzadeh@gmail.com>
 License: MIT
@@ -11,6 +11,7 @@ Requires-Dist: dependency-injector>=4.48.1
 Requires-Dist: elasticsearch==8.14.0
 Requires-Dist: fastapi>=0.116
 Requires-Dist: httpx>=0.27
+Requires-Dist: makefun>=1.16.0
 Requires-Dist: psycopg>=3.2.9
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: pydantic>=2.0

{nlbone-0.4.3.dist-info → nlbone-0.5.0.dist-info}/RECORD

@@ -1,10 +1,15 @@
 nlbone/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-nlbone/container.py,sha256=wmamsFU0Be6DlEqhLW30J2w4zVCwNlcZDd7HxkzWil0,2481
+nlbone/container.py,sha256=gbO8D23HOCHe2lpZpHCvpb5zPMSJnShK9AOna1UQFWg,3169
 nlbone/types.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/adapters/auth/__init__.py,sha256=hkDHvsFhw_UiOHG9ZSMqjiAhK4wumEforitveSZswVw,42
 nlbone/adapters/auth/keycloak.py,sha256=dfAxODiARfR8y3FKoWNo9fjfb6QyWd_Qr7AbJ0E78AM,2729
 nlbone/adapters/auth/token_provider.py,sha256=NhqjqTUsoZO4gbK-cybs0OkKydFN7CPTxAiypEw081o,1433
+nlbone/adapters/cache/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nlbone/adapters/cache/async_redis.py,sha256=E61tpBwAElMoGgyJ8CWO5G81n7u1-Wi_kVRDoh5rJuM,6206
+nlbone/adapters/cache/memory.py,sha256=lRJqMdD2lbojndQ_dJ7AulfhSYY_uqjgXvd4ZT_J8co,3655
+nlbone/adapters/cache/pubsub_listener.py,sha256=2y6DbWsERXlMOkmJSJMg8hNU9MTGwR7BhwQRveivh50,1457
+nlbone/adapters/cache/redis.py,sha256=gMNfUIk1HkeXVBmtAtVchcr59ll06E4wam9rGWAhalM,4535
 nlbone/adapters/db/__init__.py,sha256=saW-wN4E0NZ2_ldi-nrm5AgsH7EULNSa62lYMwfy1oo,252
 nlbone/adapters/db/postgres/__init__.py,sha256=6JYJH0xZs3aR-zuyMpRhsdzFugmqz8nprwTQLprqhZc,313
 nlbone/adapters/db/postgres/audit.py,sha256=zFzL-pXmfjcp5YLx6vBYczprsJjEPxSYKhQNR3WjKL0,4675
@@ -18,8 +23,8 @@ nlbone/adapters/db/redis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZ
 nlbone/adapters/db/redis/client.py,sha256=XAKcmU0lpPvWPMS0fChVQ3iSJfHV1g4bMOCgJaj2bCI,512
 nlbone/adapters/http_clients/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/adapters/http_clients/email_gateway.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-nlbone/adapters/http_clients/uploadchi.py,sha256=iMLbXUXqi60gQMEI7wfaqWG0G7p9fQN7otT9c8npnLQ,5470
-nlbone/adapters/http_clients/uploadchi_async.py,sha256=wmb2XIUNkowh48GJwttNZ_STgsFQdGKKRZc_luYNCu8,4609
+nlbone/adapters/http_clients/uploadchi.py,sha256=-goyqa3DNnDdkiIvrJRMlk5KVCaRNy34pPYklLHV04w,5556
+nlbone/adapters/http_clients/uploadchi_async.py,sha256=9QxunVxPEyf6LxcGaQ9I2JFtVB6s-JtR9f7RtND8pIk,4695
 nlbone/adapters/messaging/__init__.py,sha256=UDAwu3s-JQmOZjWz2Nu0SgHhnkbeOhKDH_zLD75oWMY,40
 nlbone/adapters/messaging/event_bus.py,sha256=w-NPwDiPMLFPU_enRQCtfQXOALsXfg31u57R8sG_-1U,781
 nlbone/adapters/messaging/redis.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -27,7 +32,7 @@ nlbone/adapters/percolation/__init__.py,sha256=viq5WZqcSLlRBF5JwuyTD_IZaNWfpKzGJ
 nlbone/adapters/percolation/connection.py,sha256=xZ-OtQVbyQYH83TUizS0UWI85Iic-AhUjiuyzO0e46s,331
 nlbone/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/config/logging.py,sha256=rGQz9W5ZgUFXBK74TFmTuwx_WMJhD8zPN39zfKVxwnI,4115
-nlbone/config/settings.py,sha256=xxdZQDQJ7wSEGODKljtQWcfITXbSHoqAXOlQ9vhNSe4,3474
+nlbone/config/settings.py,sha256=-FcCbS30yDK-ZXlC_336T4yea7sVjnzNak22wSptOXI,3596
 nlbone/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/core/application/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/core/application/base_worker.py,sha256=uHqglsd33jXl_0kmkFlB4KQ5NdI1wArcOeQmdcifPQc,1192
@@ -41,6 +46,7 @@ nlbone/core/domain/events.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,
 nlbone/core/domain/models.py,sha256=e2ig7PMBBpmc8pdHLNMnXhucMXr9OUq-G7bKGTq9Qj0,1458
 nlbone/core/ports/__init__.py,sha256=gx-Ubj7h-1vvnu56sNnRqmer7HHfW3rX2WLl-0AX5U0,214
 nlbone/core/ports/auth.py,sha256=Gh0yQsxx2OD6pDH2_p-khsA-bVoypP1juuqMoSfjZUo,493
+nlbone/core/ports/cache.py,sha256=C9exWYPZsppCpkrAMiGfJuf4ehHkibtFfvB1aFbWuO4,2257
 nlbone/core/ports/event_bus.py,sha256=_Om1GOOT-F325oV6_LJXtLdx4vu5i7KrpTDD3qPJXU0,325
 nlbone/core/ports/files.py,sha256=7Ov2ITYRpPwwDTZGCeNVISg8e3A9l08jbOgpTImgfK8,1863
 nlbone/core/ports/messaging.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -69,11 +75,14 @@ nlbone/interfaces/cli/main.py,sha256=65XXNmH0dX9Lib_yW5iQXo7wp_GRFwx9xXDYgy2LJtY
 nlbone/interfaces/jobs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/interfaces/jobs/sync_tokens.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nlbone/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nlbone/utils/cache.py,sha256=3sKtWoGBlrEvkg74r4C-Sx8u41OTup_G4s-Q57IaOXg,5921
+nlbone/utils/cache_keys.py,sha256=a1yRMUuyRJ2-CswjtgVkLcJAeT2QmThLQ5kQWvpOKL4,1069
+nlbone/utils/cache_registry.py,sha256=0csax1-GmKBcsZmQYWI4Bs0X9_BMo6Jdoac-e9Zusv8,819
 nlbone/utils/context.py,sha256=MmclJ24BG2uvSTg1IK7J-Da9BhVFDQ5ag4Ggs2FF1_w,1600
 nlbone/utils/redactor.py,sha256=JbbPs2Qtnz0zHN85BGPYQNWwBigXMSzmMEmmZZOTs_U,1277
 nlbone/utils/time.py,sha256=6e0A4_hG1rYDCrWoOklEGVJstBf8j9XSSTT7VNV2K9Y,1272
-nlbone-0.4.3.dist-info/METADATA,sha256=dKKof0RuBfc3ONT-R1n5qD_oJXaE4BIhqcezwx8NH8Q,2163
-nlbone-0.4.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nlbone-0.4.3.dist-info/entry_points.txt,sha256=CpIL45t5nbhl1dGQPhfIIDfqqak3teK0SxPGBBr7YCk,59
-nlbone-0.4.3.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-nlbone-0.4.3.dist-info/RECORD,,
+nlbone-0.5.0.dist-info/METADATA,sha256=4EzJYpbkzQZ1LsKAYpY94NrDARztMctvov_bf1vjmfI,2194
+nlbone-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nlbone-0.5.0.dist-info/entry_points.txt,sha256=CpIL45t5nbhl1dGQPhfIIDfqqak3teK0SxPGBBr7YCk,59
+nlbone-0.5.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nlbone-0.5.0.dist-info/RECORD,,