Python-3xui 0.0.10.post2__tar.gz → 0.0.11__tar.gz

{python_3xui-0.0.10.post2 → python_3xui-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Python-3xui
-Version: 0.0.10.post2
+Version: 0.0.11
 Summary: 3x-ui wrapper for python
 Project-URL: Homepage, https://github.com/Artem-Potapov/3x-py
 Project-URL: Issues, https://github.com/Artem-Potapov/3x-py/issues

{python_3xui-0.0.10.post2 → python_3xui-0.0.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Python-3xui"
-version = "0.0.10r2"
+version = "0.0.11"
 authors = [
   { name="JustMe_001", email="justme001.causation755@passinbox.com" },
 ]
@@ -46,7 +46,8 @@ build-backend = "hatchling.build"
 include = [
     "python_3xui/*.py",
     "/tests/*.py",
-    "/tests/pytest.ini"
+    "/tests/pytest.ini",
+    "python_3xui/api_core/*.py"
 ]
 exclude = [
     "requirements.txt",

{python_3xui-0.0.10.post2 → python_3xui-0.0.11}/python_3xui/__init__.py

@@ -4,7 +4,7 @@ from .api import XUIClient
 import python_3xui.custom_exceptions as exceptions
 
 __author__ = "JustMe_001"
-__version__ = "0.0.10r2"
+__version__ = "0.0.11"
 __email__ = ""
 
 

python_3xui-0.0.11/python_3xui/api_core/__init__.py

@@ -0,0 +1,4 @@
+from .identity import IdentityResolver
+from .prod_cache import ProductionInboundCache
+from .session_core import SessionCore
+from .client_service import TgIDClientService

python_3xui-0.0.11/python_3xui/api_core/client_service.py

@@ -0,0 +1,301 @@
+"""Telegram-ID-oriented high-level client operations."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from asyncio import Task
+from datetime import datetime, UTC
+from typing import TYPE_CHECKING, List, Literal
+
+from httpx import Response
+
+from python_3xui import util
+from python_3xui.custom_exceptions import ClientDoesNotExistError, ClientEmailAlreadyExistsError
+from python_3xui.models import ClientStats, Inbound, SingleInboundClient
+from python_3xui.util import get_client_in_inbound
+
+if TYPE_CHECKING:
+    from python_3xui.endpoints import Clients, Inbounds
+    from python_3xui.api_core.identity import IdentityResolver
+    from python_3xui.api_core.prod_cache import ProductionInboundCache
+
+
+class TgIDClientService:
+    """Orchestrates TGID-derived flows against panel endpoints."""
+
+    __slots__ = ("_clients", "_inbounds", "_identity", "_prod_cache")
+
+    def __init__(self,
+                 clients_endpoint: Clients,
+                 inbounds_endpoint: Inbounds,
+                 identity: IdentityResolver,
+                 prod_cache: ProductionInboundCache,
+                 ) -> None:
+        self._clients = clients_endpoint
+        self._inbounds = inbounds_endpoint
+        self._identity = identity
+        self._prod_cache = prod_cache
+
+    async def get_client_with_tgid(self, tgid: int, inbound_id: int | None = None) -> list[ClientStats]:
+        #FIXME: Implement the fallback described in the docstring (api.py)
+        if inbound_id:
+            email = util.generate_email_from_tgid_inbid(tgid, inbound_id)
+            return [await self._clients.get_client_with_email(email)]
+        uuid = await self._identity.resolve_uuid(tgid)
+        return await self._clients.get_client_with_uuid(uuid)
+
+    async def create_and_add_prod_client(self,
+                                         telegram_id: int,
+                                         *,
+                                         additional_remark: str | None = None,
+                                         expiry_time: int = 0,
+                                         exist_ok: bool = False,
+                                         replace_if_exist: bool = False,
+                                         ) -> dict[int, Response]:
+        production_inbounds: tuple[Inbound, ...] = await self._prod_cache.get()
+
+        custom_sub = await self._identity.resolve_sub(telegram_id)
+        uuid = await self._identity.resolve_uuid(telegram_id)
+
+        # --- Phase 1: build clients and burst-add them ---
+        _to_exec: list[asyncio.Task[Response]] = []
+        clients_by_inbound: dict[int, SingleInboundClient] = {}
+        for inb in production_inbounds:
+            tmp_email = util.generate_email_from_tgid_inbid(telegram_id, inb.id)
+            client = SingleInboundClient(
+                uuid=uuid,
+                flow="",
+                email=tmp_email,
+                limit_gb=0,
+                enable=True,
+                subscription_id=custom_sub,
+                comment=f"{additional_remark + ', ' if additional_remark else ''}created at {datetime.now(UTC)}",
+                expiry_time=expiry_time,
+            )
+            clients_by_inbound[inb.id] = client
+            _to_exec.append(
+                asyncio.create_task(self._clients.add_client(client, inb.id))
+            )
+
+        raw_results: list[Response] = await asyncio.gather(*_to_exec)
+
+        # Map inbound IDs to their add responses
+        responses: dict[int, Response] = {}
+        for i, inb in enumerate(production_inbounds):
+            responses[inb.id] = raw_results[i]
+
+        # --- Phase 2: replace duplicates when replace_if_exist is set ---
+        if replace_if_exist:
+            _update_exec: list[asyncio.Task[Response]] = []
+            # Track which inbound each update task corresponds to via list index
+            update_inbound_ids: list[int] = []
+
+            for inb_id, resp in list(responses.items()):
+                json_resp = resp.json()
+                msg = json_resp.get("msg", "")
+                if "duplicate email" in msg.lower():
+                    client = clients_by_inbound[inb_id]
+                    _update_exec.append(
+                        asyncio.create_task(
+                            self._clients.request_update_client(
+                                client, inb_id, original_uuid=client.uuid,
+                            )
+                        )
+                    )
+                    update_inbound_ids.append(inb_id)
+
+            if _update_exec:
+                update_results: list[Response] = await asyncio.gather(*_update_exec)
+                for i, inb_id in enumerate(update_inbound_ids):
+                    responses[inb_id] = update_results[i]
+
+        # --- Phase 3: raise on remaining duplicates if not exist_ok ---
+        if not exist_ok:
+            for inb_id, resp in responses.items():
+                json_resp = resp.json()
+                msg = json_resp.get("msg", "")
+                if "duplicate email" in msg.lower():
+                    logging.error(
+                        "ERROR: Client already exists and exist_ok not set: %s",
+                        msg,
+                    )
+                    raise ClientEmailAlreadyExistsError(msg)
+
+        return responses
+
+    async def _find_client_in_inbound(self,
+                                      client_uuid: str,
+                                      inbound_id: int,
+                                      *,
+                                      use_cache: bool = False,
+                                      ) -> SingleInboundClient | None:
+        if use_cache:
+            prod_inbs = await self._prod_cache.get()
+            prod_inb_index = None
+            for i, prod_inb in enumerate(prod_inbs):
+                if inbound_id == prod_inb.id:
+                    prod_inb_index = i
+
+            if prod_inb_index is not None:
+                needed_inb: Inbound = prod_inbs[prod_inb_index]
+                result = get_client_in_inbound(client_uuid, needed_inb)
+                if result is None:
+                    self._prod_cache.get.cache_clear()
+                    new_inb = (await self._prod_cache.get())[prod_inb_index]
+                    return get_client_in_inbound(client_uuid, new_inb)
+
+        inb = await self._inbounds.get_specific_inbound(inbound_id)
+        for client in inb.settings.clients:
+            if client.uuid == client_uuid:
+                return client
+        return None
+
+    async def update_client_by_tgid_only(self,
+                                         telegram_id: int,
+                                         prod_only: bool,
+                                         /,
+                                         *,
+                                         security: str | None = None,
+                                         password: str | None = None,
+                                         flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] | None = None,
+                                         limit_ip: int | None = None,
+                                         limit_gb: int | None = None,
+                                         expiry_time: int | None = None,
+                                         enable: bool | None = None,
+                                         sub_id: str | None = None,
+                                         comment: str | None = None,
+                                         verbose: bool = True,
+                                         force_search_by_email: bool = False,
+                                         not_found_action: Literal["raise", "ignore"] = "ignore",
+                                         client_to_create: SingleInboundClient | None = None
+                                         ) -> list[Response]:
+        updates = {
+            "security": security,
+            "password": password,
+            "flow": flow,
+            "limit_ip": limit_ip,
+            "limit_gb": limit_gb,
+            "expiry_time": expiry_time,
+            "enable": enable,
+            "sub_id": sub_id,
+            "comment": comment,
+        }
+        updates = {k: v for k, v in updates.items() if v is not None}
+
+        if verbose:
+            if expiry_time and expiry_time < 1e9:
+                logging.warning(
+                    "Warning: You're trying to update a client with expiry time %s. "
+                    "You set it to expire before 2001, likely because you provided the DURATION. "
+                    "You need to provide a TIMESTAMP. "
+                    "If you want to disable this message, set verbose=false.",
+                    expiry_time,
+                )
+
+        _to_exec: list[Task] = []
+        client_uuid = await self._identity.resolve_uuid(telegram_id)
+        if prod_only:
+            self._prod_cache.get.cache_clear()
+            inbounds = await self._prod_cache.get()
+        else:
+            inbounds = await self._inbounds.get_all()
+        for inbound in inbounds:
+            found_client = util.get_client_in_inbound(client_uuid, inbound)
+            if not found_client:
+                if force_search_by_email:
+                    _email_to_search = util.generate_email_from_tgid_inbid(telegram_id, inbound.id)
+                    found_traffics = await self._clients.get_client_with_email(_email_to_search, raise_if_none=False)
+                    if found_traffics:
+                        resp = await self._inbounds.get_specific_inbound(inbound.id)
+                        found_client = util.get_client_in_inbound(found_traffics.uuid, resp)
+                # this double-check is better than 2 branches doing the same thing
+                if not found_client:
+                    if not_found_action == "ignore":
+                        pass
+                    if not_found_action == "raise":
+                        raise ClientDoesNotExistError(f"Client not found: {client_uuid}")
+
+            if found_client:
+                new_client = found_client.model_copy(update=updates, deep=True)
+                _to_exec.append(
+                    asyncio.create_task(
+                        self._clients.request_update_client(
+                            new_client, inbound.id, original_uuid=client_uuid
+                        )
+                    )
+                )
+        return await asyncio.gather(*_to_exec)
+
+    async def update_client_by_tgid_inbid(self,
+                                          telegram_id: int,
+                                          inbound_id: int,
+                                          /,
+                                          *,
+                                          security: str | None = None,
+                                          password: str | None = None,
+                                          flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] | None = None,
+                                          limit_ip: int | None = None,
+                                          limit_gb: int | None = None,
+                                          expiry_time: int | None = None,
+                                          enable: bool | None = None,
+                                          sub_id: str | None = None,
+                                          comment: str | None = None,
+                                          email: str | None = None,
+                                          verbose: bool = True,
+                                          force_resolve_by_email: bool = False,
+                                          ) -> Response:
+        if verbose:
+            if expiry_time and expiry_time < 1e9:
+                logging.warning(
+                    "Warning: You're trying to update a client with expiry time %s. "
+                    "You set it to expire before 2001, likely because you provided the DURATION. "
+                    "You need to provide a TIMESTAMP. "
+                    "If you want to disable this message, set verbose=false.",
+                    expiry_time,
+                )
+
+        client_uuid = await self._identity.resolve_uuid(telegram_id)
+        found = await self._find_client_in_inbound(client_uuid, inbound_id)
+        if not found:
+            if force_resolve_by_email:
+                _email_to_search = util.generate_email_from_tgid_inbid(telegram_id, inbound_id)
+                resp = await self._clients.get_client_with_email(_email_to_search, raise_if_none=False)
+                if resp is None:
+                    raise ClientDoesNotExistError(f"The target inbound was force-checked by email but client {_email_to_search} was not found.")
+                client_uuid = resp.uuid
+            else:
+                raise ClientDoesNotExistError(
+                    f"The target inbound was checked but client {client_uuid} was not found."
+                )
+        return await self._clients.update_single_client(
+            inbound_id=inbound_id,
+            found_client=found,
+            security=security,
+            password=password,
+            email=email,
+            flow=flow,
+            limit_ip=limit_ip,
+            limit_gb=limit_gb,
+            expiry_time=expiry_time,
+            enable=enable,
+            sub_id=sub_id,
+            comment=comment,
+        )
+
+    async def delete_client_by_tgid(self, telegram_id: int, inbound_id: int) -> Response:
+        email = util.generate_email_from_tgid_inbid(telegram_id, inbound_id)
+        return await self._clients.delete_client_by_email(email, inbound_id)
+
+    async def revoke_client_by_tgid_all_inbounds(self, telegram_id: int) -> List[Response]:
+        production_inbounds = await self._prod_cache.get()
+        _to_exec: list[Task] = []
+        for inbound in production_inbounds:
+            email = util.generate_email_from_tgid_inbid(telegram_id, inbound.id)
+            _to_exec.append(
+                asyncio.create_task(
+                    self._clients.delete_client_by_email(email, inbound.id)
+                )
+            )
+            logging.info("Clients of of tgid %s pending deletion", telegram_id)
+        return await asyncio.gather(*_to_exec)

python_3xui-0.0.11/python_3xui/api_core/identity.py

@@ -0,0 +1,28 @@
+from collections.abc import Awaitable, Callable
+from inspect import iscoroutinefunction
+
+
+class IdentityResolver:
+    """Resolves Telegram IDs to UUIDs and subscription IDs.
+
+    Wraps user-supplied sync-or-async generator callables and exposes
+    consistently-async resolve_* methods. Pure (no I/O, no state beyond the
+    injected callables).
+    """
+
+    def __init__(self,
+                 sub_gen: Callable[[int], str] | Callable[[int], Awaitable[str]],
+                 uuid_gen: Callable[[int], str] | Callable[[int], Awaitable[str]],
+                 ) -> None:
+        self.sub_gen = sub_gen
+        self.uuid_gen = uuid_gen
+
+    async def resolve_uuid(self, telegram_id: int) -> str:
+        if iscoroutinefunction(self.uuid_gen):
+            return await self.uuid_gen(telegram_id)
+        return self.uuid_gen(telegram_id)
+
+    async def resolve_sub(self, telegram_id: int) -> str:
+        if iscoroutinefunction(self.sub_gen):
+            return await self.sub_gen(telegram_id)
+        return self.sub_gen(telegram_id)

python_3xui-0.0.11/python_3xui/api_core/prod_cache.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import re
+from asyncio import Task
+from typing import TYPE_CHECKING, Any
+
+from async_lru import alru_cache
+
+from python_3xui.models import Inbound
+
+if TYPE_CHECKING:
+    from python_3xui.endpoints import Inbounds
+
+
+class ProductionInboundCache:
+    """Per-instance cache of production inbounds + background refresher.
+
+    The wrapper around the fetch impl is built per-instance (not via a
+    class-level decorator) so each XUIClient owns its own async-lru cache
+    bound to its own event loop. Using a class-level ``@alru_cache()`` on
+    the underlying coroutine binds the cache to the first event loop that
+    touches it (see async_lru._check_loop), which breaks any caller that
+    creates a new XUIClient on a fresh loop (e.g. each pytest-asyncio test).
+    Building the wrapper in ``__init__`` gives every instance its own cache
+    bound to its own loop.
+    """
+
+    def __init__(self, inbounds_endpoint: Inbounds, prod_string_pattern: str,
+                 *, panel_id: Any = None, refresh_interval: float = 3600, cache_size: int = 128,
+                 ) -> None:
+        self._inbounds = inbounds_endpoint
+        self.PROD_STRING = re.compile(prod_string_pattern)
+        self.panel_id = panel_id
+        self._refresh_interval = refresh_interval
+        self.get = alru_cache(maxsize=cache_size)(self._fetch_impl)
+        self._task: Task | None = None
+        self._running: bool = False
+
+    async def _fetch_impl(self) -> tuple[Inbound, ...]:
+        inbounds = await self._inbounds.get_all()
+        usable: list[Inbound] = [inb for inb in inbounds if self.PROD_STRING.search(inb.remark)]
+        if not usable:
+            # Note: this is meant to fail if the prod_string is not found.
+            raise RuntimeError("No production inbounds found! Change prod_string!")
+        return tuple(usable)
+
+    def start(self, *, create_new: bool = False) -> None:
+        """Idempotent. Mirrors the create_new guard from the original task."""
+        if self._task is not None and not create_new:
+            logging.warning(
+                "Cache cleaner task already running; pass create_new=True to override."
+            )
+            return
+        self._running = True
+        logging.info("Initializing cache cleaner task for %s", self.panel_id)
+        self._task = asyncio.create_task(
+            self._refresh_loop(),
+            name=f"inb_cache_clearer_for_{self.panel_id}",
+        )
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task is not None:
+            with contextlib.suppress(asyncio.CancelledError):
+                self._task.cancel("Panel is exiting.")
+            self._task = None
+
+    async def _refresh_loop(self) -> None:
+        while self._running:
+            self.get.cache_clear()
+            await self.get()
+            await asyncio.sleep(self._refresh_interval)

python_3xui-0.0.11/python_3xui/api_core/session_core.py

@@ -0,0 +1,333 @@
+"""HTTP session, credentials, TOTP, and retry-with-relogin policy for the panel API."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import AsyncIterable, Iterable, Mapping, Sequence
+from datetime import UTC, datetime
+from logging import DEBUG
+from typing import Any, Literal, Self, Tuple, Type, Union, overload
+
+import httpx
+import pyotp
+from httpx import AsyncClient, Request, Response
+from pydantic import SecretStr
+
+from python_3xui import util
+from python_3xui.util import JsonType, async_range
+
+DataType: Type[str | bytes | Iterable[bytes] | AsyncIterable[bytes]] = Union[
+    str, bytes, Iterable[bytes], AsyncIterable[bytes]
+]
+PrimitiveData = Union[str, int, float, bool] | None
+ParamType = Union[
+    Mapping[str, Union[PrimitiveData, Sequence[PrimitiveData]]],
+    list[Tuple[str, PrimitiveData]],
+    tuple[Tuple[str, PrimitiveData], ...],
+    str,
+    bytes,
+]
+CookieType = Union[dict[str, str], list[tuple[str, str]]]
+HeaderType = Union[
+    Mapping[str, str],
+    Mapping[bytes, bytes],
+    Sequence[tuple[str, str]],
+    Sequence[tuple[bytes, bytes]],
+]
+
+
+class SessionCore:
+    """Owns HTTP session, credentials, TOTP, and the retry-with-relogin policy.
+
+    Single object that talks to the panel. Endpoint classes receive a
+    SessionCore (not the full XUIClient) and call ``safe_get`` / ``safe_post``
+    on it. The 404-with-expired-session branch in ``_safe_request`` calls
+    ``self.login()``, so transport and auth must live together.
+    """
+
+    def __init__(self, base_website: str, base_port: int, base_path: str,
+                 *, username: str | None = None, password: str | None = None,
+                 two_fac_code: str | None = None, session_duration: int = 3600,
+                 max_retries: int = 5, retry_delay: int = 1, panel_id: Any = None,
+                 ) -> None:
+        self.connected: bool = False
+        self.session: AsyncClient | None = None
+        self.base_host: str = base_website
+        self.base_port: int = base_port
+        self.base_path: str = base_path
+        self.base_url: str = f"https://{self.base_host}:{self.base_port}{self.base_path}"
+        self.session_start: float | None = None
+        self.session_duration: int = session_duration
+        self.xui_username: str | None = username
+        self.xui_password: str | None = password
+        self.two_fac_secret: SecretStr | None = (
+            SecretStr(two_fac_code) if two_fac_code is not None else None
+        )
+        self.totp: pyotp.TOTP | None = None
+        self.max_retries: int = max_retries
+        self.retry_delay: int = retry_delay
+        self.panel_id = panel_id
+        if self.two_fac_secret:
+            if len(self.two_fac_secret.get_secret_value()) <= 8:
+                print(
+                    "WARNING: You seem to have entered a 2FA **code**, not a 2FA secret."
+                    "Although entering the secret is dangerous, there is no other way to provide a consistent way"
+                    "for continuous login. This code will only work for this specific login."
+                )
+                self.totp = None
+            else:
+                self.totp = pyotp.TOTP(self.two_fac_secret.get_secret_value())
+
+    @overload
+    async def _safe_request(self, *, request_to_send: httpx.Request) -> Response:
+        ...
+
+    @overload
+    async def _safe_request(self,
+                            method: Literal["get", "post", "patch", "delete", "put"],
+                            **kwargs: Any,
+                            ) -> Response:
+        ...
+
+    async def _safe_request(self,
+                            method: Literal["get", "post", "patch", "delete", "put"] | None = None,
+                            **kwargs: Any,
+                            ) -> Response:
+        """Execute an HTTP request with automatic retry on database lock.
+
+        The request can be made either from a prebuilt ``request_to_send`` or
+        from an HTTP method plus keyword arguments accepted by ``httpx``.
+        The method handles automatic session refresh on expired 404 responses
+        and retries when the 3X-UI database is locked.
+
+        Args:
+            method: The HTTP method to use when building a new request.
+            **kwargs: Either ``request_to_send`` by itself, or request
+                arguments such as ``url``, ``json``, ``params``, and headers.
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            ValueError: If neither a method nor a prebuilt request is provided,
+                or both request styles are mixed.
+            RuntimeError: If max retries are exceeded or a valid session gets
+                an unexpected 404 response.
+        """
+        if "request_to_send" in kwargs and len(kwargs.keys()) != 1:
+            raise ValueError(
+                "Provide either a prebuilt request or arguments to build one."
+            )
+        if "request_to_send" not in kwargs:
+            if method is None:
+                raise ValueError(
+                    "If there's no prebuilt request, you must provide a method."
+                )
+
+        url = (
+            kwargs["url"]
+            if "url" in kwargs.keys()
+            else kwargs["request_to_send"].url
+        )
+        if "json" in kwargs:
+            json_payload = kwargs["json"]
+        elif "request_to_send" in kwargs:
+            _req = kwargs["request_to_send"]
+            if _req.content:
+                try:
+                    json_payload = json.loads(_req.content.decode())
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    json_payload = None
+            else:
+                json_payload = None
+        else:
+            json_payload = None
+        if __debug__:
+            logging.info(
+                "Safe %s is running to %s%s\nJSON Payload: %s",
+                method,
+                str(self.session.base_url),
+                str(url),
+                json.dumps(json_payload) if json_payload is not None else "(no payload)",
+            )
+        async for attempt in async_range(self.max_retries):
+            if "request_to_send" in kwargs:
+                _request: Request = kwargs["request_to_send"]
+                resp = await self.session.send(_request)
+            else:
+                # noinspection PyTypeChecker
+                resp = await self.session.request(method, **kwargs)
+            if resp.status_code // 100 != 2:  # because it can return either 201 or 202
+                if resp.status_code == 404:
+                    now: float = datetime.now(UTC).timestamp()
+                    if (
+                            self.session_start is None
+                            or now - self.session_start > self.session_duration
+                    ):
+                        logging.info(
+                            "Client (panel: %s) is not logged in, logging in...",
+                            self.panel_id or self.base_host,
+                        )
+                        await self.login()
+                        continue
+                    else:
+                        logging.error(
+                            "Server returned a status code of %s with a valid session",
+                            resp.status_code,
+                        )
+                        raise RuntimeError(
+                            "Server returned a 404, and the session should still be valid, likely it's a REAL 404"
+                        )
+                else:
+                    logging.error(
+                        "Server returned a status code of %s", resp.status_code
+                    )
+                    resp.raise_for_status()
+
+            status = await util.check_xui_response(resp)
+            if status == "OK":
+                return resp
+            if status == "DB_LOCKED":
+                if attempt + 1 >= self.max_retries:
+                    raise RuntimeError("Too many retries")
+                await asyncio.sleep(self.retry_delay)
+                continue
+            logging.error(
+                "A %s request was unsuccessful (code 200, but success=false).\nPayload: %s",
+                method,
+                json.dumps(resp.json()),
+            )
+            return resp
+        raise RuntimeError(
+            f"For some reason safe_request didn't exit, dump:\nmethod:\n{method}\n{kwargs}"
+        )
+
+    async def safe_get(self,
+                       url: httpx.URL | str,
+                       *,
+                       params: ParamType | None = None,
+                       headers: HeaderType | None = None,
+                       cookies: CookieType | None = None,
+                       ) -> Response:
+        """Execute a safe GET request with automatic retry on database lock.
+
+        Note:
+            "Safe" only means "with retries if database is locked".
+
+        Args:
+            url: The URL to request.
+            params: Query parameters (optional).
+            headers: Request headers (optional).
+            cookies: Request cookies (optional).
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            RuntimeError: If the session is not initialized.
+        """
+        if self.session is None:
+            raise RuntimeError("Session is not initialized")
+
+        return await self._safe_request(
+            method="get",
+            url=url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+        )
+
+    async def safe_post(self,
+                        url: httpx.URL | str,
+                        *,
+                        content: DataType | None = None,
+                        data: JsonType | None = None,
+                        json: Any | None = None,
+                        params: ParamType | None = None,
+                        headers: HeaderType | None = None,
+                        cookies: CookieType | None = None,
+                        ) -> Response:
+        """Execute a safe POST request with automatic retry on database lock.
+
+        Note:
+            "Safe" only means "with retries if database is locked".
+
+        Args:
+            url: The URL to request.
+            content: Request content (optional).
+            data: Form data (optional).
+            json: JSON body (optional).
+            params: Query parameters (optional).
+            headers: Request headers (optional).
+            cookies: Request cookies (optional).
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            RuntimeError: If the session is not initialized.
+        """
+        if self.session is None:
+            raise RuntimeError("Session is not initialized")
+
+        return await self._safe_request(
+            method="post",
+            url=url,
+            content=content,
+            data=data,
+            json=json,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+        )
+
+    async def login(self) -> None:
+        """Authenticate with the 3X-UI panel."""
+        payload = {
+            "username": self.xui_username,
+            "password": self.xui_password,
+        }
+        if self.totp:
+            if (
+                    self.totp.interval - datetime.now().timestamp() % self.totp.interval
+                    < 3
+            ):
+                await asyncio.sleep(3.1)  # just to not submit an invalid code
+            payload["twoFactorCode"] = self.totp.now()
+        elif self.two_fac_secret:
+            payload["twoFactorCode"] = self.two_fac_secret.get_secret_value()
+
+        logging.info(
+            "Client is logging in (panel: %s)", self.panel_id or self.base_host
+        )
+        resp = await self.session.post("/login", data=payload)
+        if resp.status_code == 200:
+            resp_json = resp.json()
+            if "success" not in resp_json:
+                raise RuntimeError(
+                    f"Error: server returned a status code of {resp.status_code} but the response is not valid: {resp_json}"
+                )
+            if not resp_json["success"]:
+                raise ValueError(
+                    "Error: wrong credentials (including status code) or failed login."
+                )
+            self.session_start = datetime.now(UTC).timestamp()
+            return
+        raise RuntimeError(f"Error: server returned a status code of {resp.status_code}")
+
+    def connect(self) -> Self:
+        """Create an async HTTP client session."""
+        logging.log(
+            DEBUG, "Client connected (panel: %s)", self.panel_id or self.base_url
+        )
+        self.session = AsyncClient(base_url=self.base_url)
+        self.connected = True
+        return self
+
+    async def disconnect(self) -> None:
+        """Close the HTTP session only (no cache teardown)."""
+        self.connected = False
+        if self.session is not None:
+            await self.session.aclose()