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

nlbone/adapters/http_clients/{uploadchi_async.py → uploadchi/uploadchi_async.py}

@@ -4,20 +4,20 @@ from typing import Any, AsyncIterator, Optional
 
 import httpx
 
+from nlbone.adapters.auth.token_provider import ClientTokenProvider
+from nlbone.adapters.http_clients.uploadchi.uploadchi import UploadchiError, _filename_from_cd, _resolve_token
 from nlbone.config.settings import get_settings
 from nlbone.core.ports.files import AsyncFileServicePort
-
-from .uploadchi import UploadchiError, _auth_headers, _build_list_query, _filename_from_cd, _resolve_token
-from ..auth.token_provider import ClientTokenProvider
+from nlbone.utils.http import auth_headers, build_list_query
 
 
 class UploadchiAsyncClient(AsyncFileServicePort):
     def __init__(
-            self,
-            token_provider: ClientTokenProvider | None = None,
-            base_url: Optional[str] = None,
-            timeout_seconds: Optional[float] = None,
-            client: httpx.AsyncClient | None = None,
+        self,
+        token_provider: ClientTokenProvider | None = None,
+        base_url: Optional[str] = None,
+        timeout_seconds: Optional[float] = None,
+        client: httpx.AsyncClient | None = None,
     ) -> None:
         s = get_settings()
         self._base_url = base_url or str(s.UPLOADCHI_BASE_URL)
@@ -31,12 +31,12 @@ class UploadchiAsyncClient(AsyncFileServicePort):
         await self._client.aclose()
 
     async def upload_file(
-            self, file_bytes: bytes, filename: str, params: dict[str, Any] | None = None, token: str | None = None
+        self, file_bytes: bytes, filename: str, params: dict[str, Any] | None = None, token: str | None = None
     ) -> dict:
         tok = _resolve_token(token)
         files = {"file": (filename, file_bytes)}
         data = (params or {}).copy()
-        r = await self._client.post("", files=files, data=data, headers=_auth_headers(tok))
+        r = await self._client.post("", files=files, data=data, headers=auth_headers(tok))
         if r.status_code >= 400:
             raise UploadchiError(r.status_code, await r.aread())
         return r.json()
@@ -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 or self._token_provider.get_access_token())
+            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,36 +56,36 @@ 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 or self._token_provider.get_access_token())
+            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())
 
     async def list_files(
-            self,
-            limit: int = 10,
-            offset: int = 0,
-            filters: dict[str, Any] | None = None,
-            sort: list[tuple[str, str]] | None = None,
-            token: str | None = None,
+        self,
+        limit: int = 10,
+        offset: int = 0,
+        filters: dict[str, Any] | None = None,
+        sort: list[tuple[str, str]] | None = None,
+        token: str | None = None,
     ) -> dict:
         tok = _resolve_token(token)
-        q = _build_list_query(limit, offset, filters, sort)
-        r = await self._client.get("", params=q, headers=_auth_headers(tok))
+        q = build_list_query(limit, offset, filters, sort)
+        r = await self._client.get("", params=q, headers=auth_headers(tok))
         if r.status_code >= 400:
             raise UploadchiError(r.status_code, await r.aread())
         return r.json()
 
     async def get_file(self, file_id: str, token: str | None = None) -> dict:
         tok = _resolve_token(token)
-        r = await self._client.get(f"/{file_id}", headers=_auth_headers(tok))
+        r = await self._client.get(f"/{file_id}", headers=auth_headers(tok))
         if r.status_code >= 400:
             raise UploadchiError(r.status_code, await r.aread())
         return r.json()
 
     async def download_file(self, file_id: str, token: str | None = None) -> tuple[AsyncIterator[bytes], str, str]:
         tok = _resolve_token(token)
-        r = await self._client.get(f"/{file_id}/download", headers=_auth_headers(tok), stream=True)
+        r = await self._client.get(f"/{file_id}/download", headers=auth_headers(tok), stream=True)
         if r.status_code >= 400:
             body = await r.aread()
             raise UploadchiError(r.status_code, body.decode(errors="ignore"))
@@ -103,7 +103,7 @@ class UploadchiAsyncClient(AsyncFileServicePort):
 
     async def delete_file(self, file_id: str, token: str | None = None) -> None:
         tok = _resolve_token(token)
-        r = await self._client.delete(f"/{file_id}", headers=_auth_headers(tok))
+        r = await self._client.delete(f"/{file_id}", headers=auth_headers(tok))
         if r.status_code not in (204, 200):
             body = await r.aread()
             raise UploadchiError(r.status_code, body.decode(errors="ignore"))

nlbone/adapters/percolation/__init__.py

@@ -1 +1 @@
-from .connection import get_es_client
+from .connection import get_es_client

nlbone/adapters/percolation/connection.py

@@ -4,9 +4,10 @@ from nlbone.config.settings import get_settings
 
 setting = get_settings()
 
+
 def get_es_client():
     es = Elasticsearch(
         setting.ELASTIC_PERCOLATE_URL,
-        basic_auth=(setting.ELASTIC_PERCOLATE_USER, setting.ELASTIC_PERCOLATE_PASS.get_secret_value().strip())
+        basic_auth=(setting.ELASTIC_PERCOLATE_USER, setting.ELASTIC_PERCOLATE_PASS.get_secret_value().strip()),
     )
     return es

nlbone/config/logging.py

@@ -11,6 +11,7 @@ from nlbone.utils.redactor import PiiRedactor
 
 settings = get_settings()
 
+
 # ---------- Filters ----------
 class ContextFilter(logging.Filter):
     def filter(self, record: logging.LogRecord) -> bool:
@@ -21,12 +22,32 @@ class ContextFilter(logging.Filter):
         record.user_agent = ctx.get("user_agent")
         return True
 
+
 # ---------- Formatter ----------
 class JsonFormatter(logging.Formatter):
     RESERVED = {
-        "args","asctime","created","exc_info","exc_text","filename","funcName","levelname","levelno",
-        "lineno","module","msecs","message","msg","name","pathname","process","processName",
-        "relativeCreated","stack_info","thread","threadName",
+        "args",
+        "asctime",
+        "created",
+        "exc_info",
+        "exc_text",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "module",
+        "msecs",
+        "message",
+        "msg",
+        "name",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "stack_info",
+        "thread",
+        "threadName",
     }
 
     def format(self, record: logging.LogRecord) -> str:
@@ -53,17 +74,23 @@ class JsonFormatter(logging.Formatter):
 
         return json.dumps(payload, ensure_ascii=False)
 
+
 class PlainFormatter(logging.Formatter):
     def __init__(self):
         super().__init__(
-            fmt="%(asctime)s | %(levelname)s | %(name)s | "
-                "req=%(request_id)s user=%(user_id)s ip=%(ip)s | %(message)s",
+            fmt="%(asctime)s | %(levelname)s | %(name)s | req=%(request_id)s user=%(user_id)s ip=%(ip)s | %(message)s",
             datefmt="%Y-%m-%dT%H:%M:%S%z",
         )
 
+
 # ---------- Setup ----------
-def setup_logging(*, log_json: bool=settings.LOG_JSON, log_level: str =settings.LOG_LEVEL,
-                  log_file: str | None = None, silence_uvicorn_access: bool = True):
+def setup_logging(
+    *,
+    log_json: bool = settings.LOG_JSON,
+    log_level: str = settings.LOG_LEVEL,
+    log_file: str | None = None,
+    silence_uvicorn_access: bool = True,
+):
     handlers = {
         "console": {
             "class": "logging.StreamHandler",
@@ -82,23 +109,25 @@ def setup_logging(*, log_json: bool=settings.LOG_JSON, log_level: str =settings.
             "formatter": "json" if log_json else "plain",
         }
 
-    dictConfig({
-        "version": 1,
-        "disable_existing_loggers": False,
-        "filters": {
-            "ctx": {"()": ContextFilter},
-            "pii": {"()": PiiRedactor},
-        },
-        "formatters": {
-            "json": {"()": JsonFormatter},
-            "plain": {"()": PlainFormatter},
-        },
-        "handlers": handlers,
-        "root": {
-            "level": log_level,
-            "handlers": list(handlers.keys()),
-        },
-    })
+    dictConfig(
+        {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "filters": {
+                "ctx": {"()": ContextFilter},
+                "pii": {"()": PiiRedactor},
+            },
+            "formatters": {
+                "json": {"()": JsonFormatter},
+                "plain": {"()": PlainFormatter},
+            },
+            "handlers": handlers,
+            "root": {
+                "level": log_level,
+                "handlers": list(handlers.keys()),
+            },
+        }
+    )
 
     logging.getLogger("asyncio").setLevel(logging.WARNING)
     logging.getLogger("httpx").setLevel(logging.WARNING)
@@ -115,5 +144,6 @@ def setup_logging(*, log_json: bool=settings.LOG_JSON, log_level: str =settings.
         uvicorn_access.handlers = []
         uvicorn_access.propagate = True
 
+
 def get_logger(name: str | None = None) -> logging.Logger:
     return logging.getLogger(name or "app")

nlbone/config/settings.py

@@ -8,19 +8,22 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
 def _guess_env_file() -> str | None:
-    explicit = os.getenv("NLBONE_ENV_FILE")
-    if explicit:
-        return explicit
+    try:
+        explicit = os.getenv("NLBONE_ENV_FILE")
+        if explicit:
+            return explicit
 
-    cwd_env = Path.cwd() / ".env"
-    if cwd_env.exists():
-        return str(cwd_env)
+        cwd_env = Path.cwd() / ".env"
+        if cwd_env.exists():
+            return str(cwd_env)
 
-    for i in range(0, 8):
-        p = Path.cwd().resolve().parents[i]
-        f = p / ".env"
-        if f.exists():
-            return str(f)
+        for i in range(0, 8):
+            p = Path.cwd().resolve().parents[i]
+            f = p / ".env"
+            if f.exists():
+                return str(f)
+    except Exception as e:
+        raise Exception("Failed to guess env file path!") from e
 
 
 def is_production_env() -> bool:
@@ -82,10 +85,15 @@ class Settings(BaseSettings):
     # ---------------------------
     # PERCOLATE
     # ---------------------------
-    ELASTIC_PERCOLATE_URL: str =  Field(default="http://localhost:9200")
+    ELASTIC_PERCOLATE_URL: str = Field(default="http://localhost:9200")
     ELASTIC_PERCOLATE_USER: str = Field(default="")
     ELASTIC_PERCOLATE_PASS: SecretStr = Field(default="")
 
+    # ---------------------------
+    # Pricing
+    # ---------------------------
+    PRICING_SERVICE_URL: AnyHttpUrl = Field(default="https://pricing.numberland.ir/v1")
+
     model_config = SettingsConfigDict(
         env_prefix="",
         env_file=None,

nlbone/container.py

@@ -11,11 +11,12 @@ 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 import PricingService
 from nlbone.adapters.http_clients.uploadchi import UploadchiClient
-from nlbone.adapters.http_clients.uploadchi_async import UploadchiAsyncClient
+from nlbone.adapters.http_clients.uploadchi.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.cache import AsyncCachePort, CachePort
 from nlbone.core.ports.files import AsyncFileServicePort, FileServicePort
 
 
@@ -35,10 +36,15 @@ class Container(containers.DeclarativeContainer):
     # --- Services ---
     auth: providers.Singleton[KeycloakAuthService] = providers.Singleton(KeycloakAuthService, settings=config)
     token_provider = providers.Singleton(ClientTokenProvider, auth=auth, skew_seconds=30)
-    file_service: providers.Singleton[FileServicePort] = providers.Singleton(UploadchiClient,
-                                                                             token_provider=token_provider)
-    afiles_service: providers.Singleton[AsyncFileServicePort] = providers.Singleton(UploadchiAsyncClient,
-                                                                                    token_provider=token_provider)
+    file_service: providers.Singleton[FileServicePort] = providers.Singleton(
+        UploadchiClient, token_provider=token_provider
+    )
+    afiles_service: providers.Singleton[AsyncFileServicePort] = providers.Singleton(
+        UploadchiAsyncClient, token_provider=token_provider
+    )
+    pricing_service: providers.Singleton[PricingService] = providers.Singleton(
+        PricingService, token_provider=token_provider
+    )
 
     cache: providers.Singleton[CachePort] = providers.Selector(
         config.CACHE_BACKEND,

nlbone/core/application/base_worker.py

@@ -33,4 +33,4 @@ class BaseWorker(ABC):
 
     @abstractmethod
     async def process(self, *args, **kwargs) -> Any:
-        pass
+        pass

nlbone/core/domain/models.py

@@ -1,7 +1,8 @@
 import uuid
 from datetime import datetime
-from sqlalchemy import String, DateTime, Index, Text
+
 from sqlalchemy import JSON as SA_JSON
+from sqlalchemy import DateTime, Index, String, Text
 from sqlalchemy.orm import Mapped, mapped_column
 from sqlalchemy.sql import func
 
@@ -9,6 +10,7 @@ from nlbone.adapters.db import Base
 
 try:
     from sqlalchemy.dialects.postgresql import JSONB, UUID
+
     JSONType = JSONB
     UUIDType = UUID(as_uuid=True)
 except Exception:
@@ -35,4 +37,4 @@ class AuditLog(Base):
     __table_args__ = (
         Index("ix_audit_entity_entityid", "entity", "entity_id"),
         Index("ix_audit_created_at", "created_at"),
-    )
+    )

nlbone/core/ports/cache.py

@@ -1,37 +1,53 @@
-from typing import Protocol, Optional, Iterable, Any, Mapping, Sequence, Tuple, TypeVar, Callable
+from typing import Any, Callable, Iterable, Mapping, Optional, Protocol, Sequence, TypeVar
 
 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 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 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 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: ...
+    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 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 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 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: ...
+    async def get_or_set(self, key: str, producer, *, ttl: int, tags: Optional[Iterable[str]] = None) -> bytes: ...

nlbone/interfaces/api/dependencies/auth.py

@@ -59,3 +59,29 @@ def has_access(*, permissions=None):
         return wrapper
 
     return decorator
+
+
+def client_or_user_has_access(*, permissions=None, client_permissions=None):
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            request = current_request()
+            token = getattr(request.state, "token", None)
+            if not token:
+                raise UnauthorizedException()
+
+            auth = KeycloakAuthService()
+
+            if auth.get_client_id(token):
+                needed = client_permissions or permissions
+                if not auth.client_has_access(token, permissions=needed):
+                    raise ForbiddenException(f"Forbidden (client) {needed}")
+            else:
+                if not current_user_id():
+                    raise UnauthorizedException()
+                if not auth.has_access(token, permissions=permissions):
+                    raise ForbiddenException(f"Forbidden (user) {permissions}")
+
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator

nlbone/interfaces/cli/init_db.py

@@ -1,6 +1,6 @@
 import typer
 
-from nlbone.adapters.db import init_sync_engine, Base, sync_ping
+from nlbone.adapters.db import Base, init_sync_engine, sync_ping
 
 init_db_command = typer.Typer(help="Database utilities")
 

nlbone/interfaces/cli/main.py

@@ -1,6 +1,7 @@
-import typer
 from typing import Optional
 
+import typer
+
 from nlbone.adapters.db import init_sync_engine
 from nlbone.config.settings import get_settings
 from nlbone.interfaces.cli.init_db import init_db_command
@@ -9,12 +10,10 @@ app = typer.Typer(help="NLBone CLI")
 
 app.add_typer(init_db_command, name="db")
 
+
 @app.callback()
 def common(
-    env_file: Optional[str] = typer.Option(
-        None, "--env-file", "-e",
-        help="Path to .env file. In prod omit this."
-    ),
+    env_file: Optional[str] = typer.Option(None, "--env-file", "-e", help="Path to .env file. In prod omit this."),
     debug: bool = typer.Option(False, "--debug", help="Enable debug logging"),
 ):
     settings = get_settings(env_file=env_file)
@@ -22,8 +21,10 @@ def common(
         pass
     init_sync_engine(echo=settings.DEBUG)
 
+
 def main():
     app()
 
+
 if __name__ == "__main__":
     main()

nlbone/utils/cache.py

@@ -4,17 +4,20 @@ 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)
@@ -79,6 +82,7 @@ def _run_maybe_async(func: Callable, *args, **kwargs):
 
 # -------- cache decorators --------
 
+
 def cached(
     *,
     ttl: int,
@@ -94,10 +98,12 @@ def cached(
     - 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)()
@@ -165,10 +171,12 @@ 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)
@@ -179,6 +187,7 @@ def invalidate_by_tags(tags_builder: Callable[..., Iterable[str]]):
                 else:
                     cache.invalidate_tags(tags)
                 return out
+
             return aw
 
         @mf_wraps(func)
@@ -191,6 +200,7 @@ def invalidate_by_tags(tags_builder: Callable[..., Iterable[str]]):
             else:
                 cache.invalidate_tags(tags)
             return out
+
         return sw
 
     return deco

nlbone/utils/cache_keys.py

@@ -3,21 +3,26 @@ 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"
@@ -25,6 +30,7 @@ def tag_list(ns: str, **filters) -> str:
     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

@@ -1,5 +1,5 @@
-from typing import Callable, Optional, TypeVar
 from contextvars import ContextVar
+from typing import Callable, Optional, TypeVar
 
 T = TypeVar("T")
 
@@ -7,17 +7,20 @@ _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()
+    return fn()

nlbone/utils/http.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import urlparse, urlunparse
+
+
+def auth_headers(token: str | None) -> dict[str, str]:
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+def build_list_query(
+    limit: int, offset: int, filters: dict[str, Any] | None, sort: list[tuple[str, str]] | None
+) -> dict[str, Any]:
+    q: dict[str, Any] = {"limit": limit, "offset": offset}
+    if filters:
+        q["filters"] = json.dumps(filters)
+    if sort:
+        q["sort"] = ",".join([f"{f}:{o}" for f, o in sort])
+    return q
+
+
+def normalize_https_base(url: str, enforce_https: bool = True) -> str:
+    p = urlparse(url.strip())
+    if enforce_https:
+        p = p._replace(scheme="https")  # enforce https
+    if p.path.endswith("/"):
+        p = p._replace(path=p.path.rstrip("/"))
+    return str(urlunparse(p))