UGOS 1.0.0__py3-none-any.whl

ugos/_client_helpers.py

@@ -0,0 +1,217 @@
+"""Internal helpers shared by the client implementation."""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import re
+from collections.abc import Collection, Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .exceptions import DownloadError
+
+_VERIFY_FALSE = frozenset({"0", "false", "no", "off"})
+_VERIFY_TRUE = frozenset({"1", "true", "yes", "on"})
+
+
+def _parse_verify(value: str) -> bool | str:
+    lowered = value.strip().lower()
+    if lowered in _VERIFY_FALSE:
+        return False
+    if lowered in _VERIFY_TRUE:
+        return True
+    return value
+
+
+@dataclasses.dataclass
+class _RetryState:
+    csrf: int = 0
+    reauth: int = 0
+
+
+@dataclasses.dataclass
+class _DownloadSpec:
+    controller: str
+    action: str
+    path: str
+    method: str
+    params: Mapping[str, Any]
+    json_fields: Collection[str]
+    timeout: Any
+    chunk_size: int
+    limit: int | None
+    dest: str | Path | None
+    filename: str | None
+    overwrite: bool
+
+
+def _retry_allowed(action: str, idempotent: bool, exc: Exception) -> bool:
+    """Allow automatic replay only for explicitly idempotent actions."""
+    del action, exc
+    return idempotent
+
+
+def _merge_params(payload: Mapping[str, Any] | None, params: Mapping[str, Any]) -> dict[str, Any]:
+    merged = dict(payload or {})
+    overlap = set(merged) & set(params)
+    if overlap:
+        names = ", ".join(sorted(overlap))
+        raise TypeError(f"duplicate parameters: {names}")
+    merged.update(params)
+    return merged
+
+
+def _multipart_fields(pairs: list[tuple[str, str]]) -> dict[str, Any]:
+    fields: dict[str, Any] = {}
+    for key, value in pairs:
+        if key not in fields:
+            fields[key] = value
+        elif isinstance(fields[key], list):
+            fields[key].append(value)
+        else:
+            fields[key] = [fields[key], value]
+    return fields
+
+
+def _raise_if_too_large(
+    total: int,
+    limit: int | None,
+    controller: str,
+    action: str,
+) -> None:
+    if limit is None or total <= limit:
+        return
+    raise DownloadError(
+        f"download exceeds {limit} bytes",
+        controller=controller,
+        action=action,
+    )
+
+
+def _limited_chunks(
+    first: bytes,
+    chunks: Iterator[bytes],
+    *,
+    limit: int | None,
+    controller: str,
+    action: str,
+) -> Iterator[bytes]:
+    total = len(first)
+    _raise_if_too_large(total, limit, controller, action)
+    if first:
+        yield first
+    for chunk in chunks:
+        total += len(chunk)
+        _raise_if_too_large(total, limit, controller, action)
+        if chunk:
+            yield chunk
+
+
+def _is_file_tuple(value: Any) -> bool:
+    if not isinstance(value, (list, tuple)) or len(value) < 2:
+        return False
+    if not isinstance(value[0], (str, bytes)):
+        return False
+    return callable(getattr(value[1], "read", None))
+
+
+def _iter_file_objects(value: Any) -> Iterator[Any]:
+    if isinstance(value, (list, tuple)):
+        if _is_file_tuple(value):
+            yield value[1]
+            return
+        for item in value:
+            yield from _iter_file_objects(item)
+        return
+    if callable(getattr(value, "read", None)):
+        yield value
+
+
+def _file_position(file_object: Any) -> int | object:
+    tell = getattr(file_object, "tell", None)
+    seek = getattr(file_object, "seek", None)
+    if not callable(tell) or not callable(seek):
+        return _NO_POSITION
+    try:
+        return int(tell())
+    except (OSError, ValueError):
+        return _NO_POSITION
+
+
+def _capture_file_positions(
+    files: Mapping[str, Any],
+) -> list[tuple[Any, int]] | None:
+    positions: list[tuple[Any, int]] = []
+    for value in files.values():
+        for file_object in _iter_file_objects(value):
+            position = _file_position(file_object)
+            if position is _NO_POSITION:
+                return None
+            positions.append((file_object, position))  # type: ignore[arg-type]
+    return positions
+
+
+def _restore_file_positions(positions: list[tuple[Any, int]]) -> None:
+    for file_object, position in positions:
+        file_object.seek(position)
+
+
+def _filename_from_response(response: httpx.Response, path: str) -> str:
+    disposition = response.headers.get("content-disposition", "")
+    if disposition:
+        match = re.search(r"filename\*=UTF-8''([^;]+)", disposition, re.IGNORECASE)
+        if match:
+            from urllib.parse import unquote
+
+            return unquote(match.group(1).strip().strip('"'))
+        match = re.search(r'filename="?([^";]+)"?', disposition, re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+    return Path(path).name or "download.bin"
+
+
+def _is_directory_destination(text: str, path: Path) -> bool:
+    if path.is_dir():
+        return True
+    if text.endswith(("/", os.sep)):
+        return True
+    altsep = os.altsep
+    return altsep is not None and text.endswith(altsep)
+
+
+_ERROR_BODY_LIMIT = 2 * 1024 * 1024
+
+_NO_POSITION = object()
+
+_WINDOWS_RESERVED = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{i}" for i in range(1, 10)),
+    *(f"LPT{i}" for i in range(1, 10)),
+}
+
+
+def _error_body_limit(limit: int | None) -> int:
+    return _ERROR_BODY_LIMIT if limit is None else min(limit, _ERROR_BODY_LIMIT)
+
+
+def _sanitize_filename(name: str) -> str:
+    clean = Path(name.replace("\\", "/")).name
+    clean = re.sub(r"[\x00-\x1f]", "", clean)
+    clean = clean.replace(":", "_").strip().rstrip(" .")
+    if clean in {"", ".", ".."} or clean.split(".")[0].upper() in _WINDOWS_RESERVED:
+        return "download.bin"
+    return clean[:255]
+
+
+def _resolve_destination(dest: str | Path, filename: str) -> Path:
+    text = str(dest)
+    path = Path(dest)
+    if _is_directory_destination(text, path):
+        return path / filename
+    return path

ugos/_client_lifecycle.py

@@ -0,0 +1,144 @@
+"""Client lifecycle, environment and session methods."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from .__about__ import SUPPORTED_MAJOR_VERSION
+from ._client_base import _ClientBase
+from ._client_helpers import _parse_verify
+from ._config import DEFAULT_TIMEOUT
+from .catalog import Catalog
+from .exceptions import ConfigurationError
+from .models.common import SessionInfo
+
+if TYPE_CHECKING:
+    from .client import UGOSClient
+
+
+def _major_version(version: str | None) -> int | None:
+    if not version:
+        return None
+    head = version.strip().lstrip("vV").split(".", 1)[0]
+    try:
+        return int(head)
+    except ValueError:
+        return None
+
+
+class _LifecycleMixin(_ClientBase):
+    @staticmethod
+    def _env_verify(overrides: dict[str, Any]) -> bool | str | Path:
+        if "verify" in overrides:
+            return overrides.pop("verify")
+        ca_bundle = os.getenv("UGOS_CA_BUNDLE")
+        if ca_bundle:
+            return ca_bundle
+        verify_env = os.getenv("UGOS_VERIFY")
+        if not verify_env:
+            return True
+        return _parse_verify(verify_env)
+
+    @staticmethod
+    def _env_timeout(overrides: dict[str, Any]) -> float | None:
+        if "timeout" in overrides:
+            return overrides.pop("timeout")
+        timeout_env = os.getenv("UGOS_TIMEOUT")
+        if not timeout_env:
+            return DEFAULT_TIMEOUT
+        try:
+            return float(timeout_env)
+        except ValueError as exc:
+            raise ConfigurationError("UGOS_TIMEOUT must be a number") from exc
+
+    @staticmethod
+    def _env_insecure(overrides: dict[str, Any]) -> None:
+        if "allow_insecure_http" in overrides:
+            return
+        insecure = os.getenv("UGOS_ALLOW_INSECURE_HTTP", "").strip().lower()
+        overrides["allow_insecure_http"] = insecure in {"1", "true", "yes", "on"}
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> UGOSClient:
+        """Create a client from ``UGOS_*`` environment variables."""
+
+        base_url = overrides.pop("base_url", None) or os.getenv("UGOS_URL")
+        if not base_url:
+            raise ConfigurationError("UGOS_URL or base_url is required")
+        username = overrides.pop("username", None) or os.getenv("UGOS_USERNAME")
+        password = overrides.pop("password", None) or os.getenv("UGOS_PASSWORD")
+        verify = cls._env_verify(overrides)
+        timeout = cls._env_timeout(overrides)
+        cls._env_insecure(overrides)
+        return cast("type[UGOSClient]", cls)(
+            base_url=base_url,
+            username=username,
+            password=password,
+            verify=verify,
+            timeout=timeout,
+            **overrides,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    @property
+    def session(self) -> SessionInfo | None:
+        return self._auth.session
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._auth.authenticated
+
+    @property
+    def catalog(self) -> Catalog:
+        return self._catalog
+
+    def login(
+        self,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        force: bool = False,
+    ) -> SessionInfo:
+        with self._lock:
+            if username is not None:
+                self._auth._username = username
+            if password is not None:
+                self._auth._password = password
+            session = self._auth.login(force=force)
+            major = _major_version(session.version)
+            if session.version and major != SUPPORTED_MAJOR_VERSION:
+                warnings.warn(
+                    f"NGFW version {session.version} is outside the supported major version "
+                    f"{SUPPORTED_MAJOR_VERSION}",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+            return session
+
+    def logout(self, *, best_effort: bool = True) -> bool:
+        with self._lock:
+            return self._auth.logout(best_effort=best_effort)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> UGOSClient:
+        return cast("UGOSClient", self)
+
+    def __exit__(self, _exc_type: Any, _exc: Any, _tb: Any) -> None:
+        if self._logout_on_exit and self._auth.authenticated:
+            self.logout(best_effort=True)
+        self.close()
+
+    def __repr__(self) -> str:
+        username = self._auth.session.username if self._auth.session else None
+        return (
+            f"UGOSClient(base_url={self.base_url!r}, username={username!r}, "
+            f"password='***', session='***')"
+        )

ugos/_client_resources.py

@@ -0,0 +1,192 @@
+"""Typed and dynamic controller resource access."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._client_base import _T, _ClientBase
+from ._client_base import CONTROLLER_RE as _CONTROLLER_RE
+from ._dynamic import ControllerProxy
+from .exceptions import ConfigurationError, UnknownControllerError
+from .resources.administrators import AdministratorsResource
+from .resources.application import ApplicationResource
+from .resources.certificates import CertificatesResource
+from .resources.contentrules import ContentRulesResource
+from .resources.contenttypes import ContentTypesResource
+from .resources.fwrules import FirewallRulesResource
+from .resources.generic_controllers import GENERIC_RESOURCES
+from .resources.groups import GroupsResource
+from .resources.icap import IcapResource
+from .resources.idps import IdpsResource
+from .resources.interfaces import InterfacesResource
+from .resources.l7 import L7Resource
+from .resources.licensing import LicensingResource
+from .resources.mailsecurity import MailSecurityResource
+from .resources.networks import NetworksResource
+from .resources.netzones import NetzonesResource
+from .resources.overridedomains import OverrideDomainsResource
+from .resources.overrides import TYPED_OVERRIDES
+from .resources.pcap import PcapResource
+from .resources.registry import TYPED_RESOURCES
+from .resources.settings import SettingsResource
+from .resources.sysinfo import SysinfoResource
+from .resources.twofa import TwoFactorResource
+from .resources.urlcategory import UrlCategoryResource
+from .resources.urlfiltering import UrlFilteringResource
+from .resources.urllists import UrlListsResource
+from .resources.users import UsersResource
+
+
+class _ResourcesMixin(_ClientBase):
+    @staticmethod
+    def _resource_class(name: str) -> Any:
+        return TYPED_RESOURCES.get(name) or TYPED_OVERRIDES.get(name) or GENERIC_RESOURCES.get(name)
+
+    def _dynamic_controller(self, name: str, strict: bool | None) -> ControllerProxy:
+        with self._lock:
+            cached = self._resources.get(name)
+            if cached is None:
+                cached = ControllerProxy(self, name, strict=strict)
+                self._resources[name] = cached
+            elif strict is not None:
+                cached._strict = strict
+        return cached
+
+    def controller(self, name: str, *, strict: bool | None = None) -> ControllerProxy:
+        if not _CONTROLLER_RE.match(name):
+            raise ConfigurationError(f"invalid controller name: {name!r}")
+        resource_cls = self._resource_class(name)
+        if resource_cls is not None:
+            return self._resource(name, resource_cls, strict=strict)
+        return self._dynamic_controller(name, strict)
+
+    def available_actions(self, controller: str) -> frozenset[str]:
+        return self._catalog.actions(controller)
+
+    def has_action(self, controller: str, action: str) -> bool:
+        return self._catalog.has_action(controller, action)
+
+    def list_actions(self, controller: str) -> frozenset[str]:
+        try:
+            return self._catalog.actions(controller)
+        except UnknownControllerError:
+            return frozenset()
+
+    def __getattr__(self, name: str) -> ControllerProxy:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        if self._catalog_check and not self._catalog.has_controller(name):
+            raise AttributeError(f"unknown controller: {name}")
+        return self.controller(name)
+
+    @property
+    def administrators(self) -> AdministratorsResource:
+        return self._resource("administrators", AdministratorsResource)
+
+    @property
+    def users(self) -> UsersResource:
+        return self._resource("users", UsersResource)
+
+    @property
+    def groups(self) -> GroupsResource:
+        return self._resource("groups", GroupsResource)
+
+    @property
+    def fwrules(self) -> FirewallRulesResource:
+        return self._resource("fwrules", FirewallRulesResource)
+
+    @property
+    def netzones(self) -> NetzonesResource:
+        return self._resource("netzones", NetzonesResource)
+
+    @property
+    def interfaces(self) -> InterfacesResource:
+        return self._resource("interfaces", InterfacesResource)
+
+    @property
+    def networks(self) -> NetworksResource:
+        return self._resource("networks", NetworksResource)
+
+    @property
+    def settings(self) -> SettingsResource:
+        return self._resource("settings", SettingsResource)
+
+    @property
+    def certificates(self) -> CertificatesResource:
+        return self._resource("certificate", CertificatesResource)
+
+    @property
+    def licensing(self) -> LicensingResource:
+        return self._resource("utm", LicensingResource)
+
+    @property
+    def sysinfo(self) -> SysinfoResource:
+        return self._resource("sysinfo", SysinfoResource)
+
+    @property
+    def pcap(self) -> PcapResource:
+        return self._resource("pcap", PcapResource)
+
+    @property
+    def twofa(self) -> TwoFactorResource:
+        return self._resource("2fa", TwoFactorResource)
+
+    @property
+    def contentrules(self) -> ContentRulesResource:
+        return self._resource("contentrules", ContentRulesResource)
+
+    @property
+    def contenttypes(self) -> ContentTypesResource:
+        return self._resource("contenttypes", ContentTypesResource)
+
+    @property
+    def urlcategory(self) -> UrlCategoryResource:
+        return self._resource("urlcategory", UrlCategoryResource)
+
+    @property
+    def urlfiltering(self) -> UrlFilteringResource:
+        return self._resource("urlfiltering", UrlFilteringResource)
+
+    @property
+    def urllists(self) -> UrlListsResource:
+        return self._resource("urllists", UrlListsResource)
+
+    @property
+    def application(self) -> ApplicationResource:
+        return self._resource("application", ApplicationResource)
+
+    @property
+    def l7(self) -> L7Resource:
+        return self._resource("l7", L7Resource)
+
+    @property
+    def idps(self) -> IdpsResource:
+        return self._resource("idps", IdpsResource)
+
+    @property
+    def icap(self) -> IcapResource:
+        return self._resource("icap", IcapResource)
+
+    @property
+    def mailsecurity(self) -> MailSecurityResource:
+        return self._resource("mailsecurity", MailSecurityResource)
+
+    @property
+    def overridedomains(self) -> OverrideDomainsResource:
+        return self._resource("overridedomains", OverrideDomainsResource)
+
+    def _resource(
+        self,
+        key: str,
+        factory: type[_T],
+        *,
+        strict: bool | None = None,
+    ) -> _T:
+        with self._lock:
+            cached = self._resources.get(key)
+            if cached is None or not isinstance(cached, factory):
+                cached = factory(self, strict=strict)
+                self._resources[key] = cached
+            elif strict is not None:
+                cached._strict = strict
+        return cached