@ngocsangairvds/vsaf 4.1.8 → 4.1.9

package/skills/vds-skill/vds-scripts/platform_core/src/vds_platform_core/http/retry.py

@@ -1,62 +0,0 @@
-"""HTTP retry middleware — platform_core.http.retry (TSK-7.3)."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
-
-import stamina
-
-if TYPE_CHECKING:
-    from vds_platform_core.protocols import HTTPClient, RetryPolicy
-
-
-@dataclass(frozen=True)
-class exponential_backoff:
-    """Default RetryPolicy: exponential backoff with optional jitter."""
-
-    max_attempts: int = 3
-    initial_wait: float = 0.1
-    multiplier: float = 2.0
-    max_wait: float = 5.0
-    jitter: float = 1.0
-    retryable: tuple[type[BaseException], ...] = (Exception,)
-
-    def can_retry(self, attempt: int, exc: BaseException) -> bool:
-        return isinstance(exc, self.retryable)
-
-    def wait_seconds(self, attempt: int) -> float:
-        return min(self.initial_wait * (self.multiplier**attempt), self.max_wait)
-
-
-class _RetryWrappedClient:
-    """HTTPClient proxy that retries get/post using a RetryPolicy."""
-
-    def __init__(self, client: HTTPClient, policy: RetryPolicy) -> None:
-        self._client = client
-        p = policy
-        self._caller = stamina.AsyncRetryingCaller(
-            attempts=getattr(p, "max_attempts", 3),
-            wait_initial=getattr(p, "initial_wait", 0.1),
-            wait_max=getattr(p, "max_wait", 5.0),
-            wait_jitter=getattr(p, "jitter", 1.0),
-            wait_exp_base=getattr(p, "multiplier", 2.0),
-        )
-        self._on = getattr(p, "retryable", (Exception,))
-
-    async def get(self, url: str, **kwargs: Any) -> Any:
-        return await self._caller(self._on, self._client.get, url, **kwargs)
-
-    async def post(self, url: str, **kwargs: Any) -> Any:
-        return await self._caller(self._on, self._client.post, url, **kwargs)
-
-    async def aclose(self) -> None:
-        await self._client.aclose()
-
-
-def with_retry(client: HTTPClient, policy: RetryPolicy) -> HTTPClient:
-    """Wrap *client* with retry behaviour governed by *policy*."""
-    return _RetryWrappedClient(client, policy)  # type: ignore[return-value]
-
-
-__all__ = ["exponential_backoff", "with_retry"]

package/skills/vds-skill/vds-scripts/platform_core/src/vds_platform_core/http/stack.py

@@ -1,61 +0,0 @@
-"""HTTP stack assembly — platform_core.http.stack (TSK-7.18)."""
-
-from __future__ import annotations
-
-from collections.abc import Callable, Sequence
-from typing import TYPE_CHECKING
-
-import httpx
-
-from vds_platform_core.credentials import HeaderAuthResolver
-from vds_platform_core.http.auth import with_auth
-from vds_platform_core.http.retry import with_retry
-
-if TYPE_CHECKING:
-    from vds_platform_core.config import HTTPClientSettings
-    from vds_platform_core.protocols import HTTPClient, RetryPolicy
-
-
-def vds_default_stack(
-    client: HTTPClient,
-    *,
-    resolver: HeaderAuthResolver,
-    retry_policy: RetryPolicy,
-    service: str,
-) -> HTTPClient:
-    """Standard VDS middleware stack: retry (innermost) → auth (outermost)."""
-    return with_auth(with_retry(client, retry_policy), resolver, header_name=resolver.header_name)
-
-
-def build_client(
-    *,
-    settings: HTTPClientSettings,
-    service: str,
-    base_url: str,
-    token_field: str,
-    header_name: str = "Authorization",
-    rate_limit_aware: bool = True,
-    extra_middleware: Sequence[Callable[[HTTPClient], HTTPClient]] = (),
-) -> HTTPClient:
-    """Build a fully-wired HTTPClient from *settings*.
-
-    Composes: httpx.AsyncClient → vds_default_stack (retry + auth) →
-    extra_middleware (FIFO: first entry wraps innermost).
-    """
-    raw: HTTPClient = httpx.AsyncClient(  # type: ignore[assignment]
-        base_url=base_url,
-        timeout=httpx.Timeout(
-            connect=settings.connect_timeout,
-            read=settings.read_timeout,
-            write=settings.write_timeout,
-            pool=settings.pool_timeout,
-        ),
-    )
-    resolver = HeaderAuthResolver(token_field=token_field, header_name=header_name)
-    client = vds_default_stack(raw, resolver=resolver, retry_policy=settings.to_retry_policy(), service=service)
-    for mw in extra_middleware:
-        client = mw(client)
-    return client
-
-
-__all__ = ["build_client", "vds_default_stack"]

package/skills/vds-skill/vds-scripts/platform_core/src/vds_platform_core/logging.py

@@ -1,132 +0,0 @@
-"""VDS structlog factory.
-
-Provides ``configure_structlog()`` to initialise a structlog pipeline with
-VDS-standard processors.  Supports quiet / verbose / JSON modes and optional
-file-based logging.
-
-Usage::
-
-    from vds_platform_core.logging import configure_structlog
-
-    configure_structlog()                         # INFO, ConsoleRenderer → stderr
-    configure_structlog(quiet=True)               # WARNING
-    configure_structlog(verbose=True)             # DEBUG
-    configure_structlog(json_logs=True)           # INFO + JSONRenderer
-    configure_structlog(log_file=Path("app.log")) # also write to file
-"""
-
-from __future__ import annotations
-
-import logging
-import sys
-from collections.abc import Sequence
-from pathlib import Path
-from typing import Any
-
-import structlog
-
-
-def configure_structlog(
-    *,
-    quiet: bool = False,
-    verbose: bool = False,
-    json_logs: bool = False,
-    log_file: Path | None = None,
-    custom_processors: Sequence[structlog.types.Processor] | None = None,
-    logger_factory: Any | None = None,
-    cache_logger: bool = False,
-) -> None:
-    """Configure the structlog pipeline and stdlib root logger.
-
-    Call once at application startup.  Safe to call multiple times (each call
-    reconfigures in place; extra ``FileHandler`` instances are deduplicated by
-    path).
-
-    Args:
-        quiet: Set log level to WARNING.  Overridden by ``verbose``.
-        verbose: Set log level to DEBUG.  Takes priority over ``quiet``.
-        json_logs: Use ``structlog.dev.JSONRenderer`` instead of
-            ``structlog.dev.ConsoleRenderer``.
-        log_file: Optional path for a file handler (UTF-8, append mode).
-            A new ``FileHandler`` is attached to the root logger only if no
-            handler for the same path exists yet.
-        custom_processors: Optional processors inserted before the renderer.
-        logger_factory: Optional structlog logger factory override. Defaults
-            to ``structlog.stdlib.LoggerFactory()``.
-        cache_logger: Value forwarded to ``cache_logger_on_first_use``.
-    """
-    # ------------------------------------------------------------------
-    # 1. Resolve log level
-    # ------------------------------------------------------------------
-    if verbose:
-        level = logging.DEBUG
-    elif quiet:
-        level = logging.WARNING
-    else:
-        level = logging.INFO
-
-    # ------------------------------------------------------------------
-    # 2. Configure stdlib root logger
-    # ------------------------------------------------------------------
-    formatter = logging.Formatter("%(message)s")
-    logging.basicConfig(level=level, stream=sys.stderr, format="%(message)s")
-    root = logging.getLogger()
-    root.setLevel(level)
-
-    # Ensure at least a stderr handler exists (avoid "No handlers found" noise)
-    if not any(isinstance(h, logging.StreamHandler) and h.stream is sys.stderr for h in root.handlers):
-        stderr_handler = logging.StreamHandler(sys.stderr)
-        stderr_handler.setLevel(level)
-        stderr_handler.setFormatter(formatter)
-        root.addHandler(stderr_handler)
-    else:
-        for h in root.handlers:
-            h.setLevel(level)
-            h.setFormatter(formatter)
-
-    # ------------------------------------------------------------------
-    # 3. Optional file handler (deduplicated by resolved path)
-    # ------------------------------------------------------------------
-    if log_file is not None:
-        resolved = log_file.resolve()
-        existing_paths = {Path(h.baseFilename).resolve() for h in root.handlers if isinstance(h, logging.FileHandler)}
-        if resolved not in existing_paths:
-            file_handler = logging.FileHandler(str(resolved), encoding="utf-8")
-            file_handler.setLevel(level)
-            file_handler.setFormatter(formatter)
-            root.addHandler(file_handler)
-
-    # ------------------------------------------------------------------
-    # 4. Select renderer
-    # ------------------------------------------------------------------
-    if json_logs:
-        renderer: structlog.types.Processor = structlog.processors.JSONRenderer()
-    else:
-        renderer = structlog.dev.ConsoleRenderer(colors=sys.stderr.isatty())
-
-    # ------------------------------------------------------------------
-    # 5. Build processor chain and configure structlog
-    # ------------------------------------------------------------------
-    shared_processors: list[structlog.types.Processor] = [
-        structlog.contextvars.merge_contextvars,
-        structlog.stdlib.add_log_level,
-        structlog.stdlib.add_logger_name,
-        structlog.processors.TimeStamper(fmt="iso"),
-        structlog.processors.StackInfoRenderer(),
-    ]
-
-    structlog.configure(
-        processors=[
-            *shared_processors,
-            *(custom_processors or ()),
-            structlog.processors.format_exc_info,
-            renderer,
-        ],
-        wrapper_class=structlog.make_filtering_bound_logger(level),
-        context_class=dict,
-        logger_factory=logger_factory or structlog.stdlib.LoggerFactory(),
-        cache_logger_on_first_use=cache_logger,
-    )
-
-
-__all__ = ["configure_structlog"]

package/skills/vds-skill/vds-scripts/platform_core/src/vds_platform_core/protocols.py

@@ -1,77 +0,0 @@
-"""Runtime-checkable structural protocols for VDS platform services — TSK-7.1.
-
-Defines the three core abstractions that orchestrators bind to via middleware
-(with_retry, with_auth) introduced in Phase 7 Wave 2.
-
-SyncableRepo is re-exported from vds_git_orchestrator when available (backward
-compat); if that package is not installed the symbol is absent from this module.
-"""
-
-from __future__ import annotations
-
-import contextlib
-from typing import Any, Protocol, runtime_checkable
-
-
-@runtime_checkable
-class HTTPClient(Protocol):
-    """Structural contract for an async HTTP client.
-
-    Any object exposing async get/post/aclose satisfies this protocol
-    without explicit inheritance — enabling transparent middleware wrapping.
-    """
-
-    async def get(self, url: str, **kwargs: Any) -> Any:
-        """Issue an async GET request."""
-        ...
-
-    async def post(self, url: str, **kwargs: Any) -> Any:
-        """Issue an async POST request."""
-        ...
-
-    async def aclose(self) -> None:
-        """Release underlying connections."""
-        ...
-
-
-@runtime_checkable
-class CredentialResolver(Protocol):
-    """Structural contract for a credential resolution strategy."""
-
-    def resolve(self) -> str | None:
-        """Return the resolved credential string, or None if unavailable."""
-        ...
-
-
-@runtime_checkable
-class RetryPolicy(Protocol):
-    """Structural contract for a retry decision strategy.
-
-    Decouples retry logic from the HTTP layer — policies can be swapped
-    without touching the client (exponential, linear, circuit-breaker, etc.).
-    """
-
-    def can_retry(self, attempt: int, exc: BaseException) -> bool:
-        """Return True if another attempt should be made after *exc*."""
-        ...
-
-    def wait_seconds(self, attempt: int) -> float:
-        """Return the number of seconds to wait before attempt *attempt*."""
-        ...
-
-
-# ---------------------------------------------------------------------------
-# Backward-compat re-export: SyncableRepo lives in vds_git_orchestrator but
-# is surfaced here so callers can import from a single stable location.
-# vds_git_orchestrator is NOT a hard dependency of platform_core; if it is
-# not installed this try-block is silently skipped.
-# ---------------------------------------------------------------------------
-with contextlib.suppress(ImportError):
-    pass
-
-
-__all__ = [
-    "CredentialResolver",
-    "HTTPClient",
-    "RetryPolicy",
-]

package/skills/vds-skill/vds-scripts/platform_core/src/vds_platform_core/serialization.py

@@ -1,80 +0,0 @@
-"""Safe model serialization for secret-bearing Pydantic settings (FR-6.2).
-
-Provides :func:`safe_dump` — a helper that accepts any Pydantic model and returns
-a plain dict with every ``SecretStr`` value replaced by ``"***"`` so that settings
-snapshots can be logged without leaking credentials.
-
-Usage::
-
-    from vds_platform_core.serialization import safe_dump
-
-    # Anywhere you log or serialize a Pydantic model:
-    logger.info("config_snapshot", config=safe_dump(settings))
-
-    # Also available as a mixin for settings classes:
-    from vds_platform_core.serialization import SafeDumpMixin
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from pydantic import BaseModel
-
-__all__ = ["SafeDumpMixin", "safe_dump"]
-
-
-# -----------------------------------------------------------------------
-# Sentinel class name — matching by type would require importing pydantic
-# at runtime which may not be available in all consumers.
-# -----------------------------------------------------------------------
-_SECRET_STR_CLASS = "SecretStr"
-
-
-def safe_dump(model: BaseModel) -> dict[str, Any]:
-    """Dump a Pydantic model to a plain dict, redacting all SecretStr fields.
-
-    Works regardless of Pydantic version by walking the output tree and
-    replacing any value whose class name is ``SecretStr`` with ``"***"``.
-
-    Args:
-        model: Any Pydantic model instance.
-
-    Returns:
-        Dictionary representation with all secret values replaced by ``"***"``.
-    """
-    raw = model.model_dump()
-    return _redact_secrets(raw)
-
-
-def _redact_secrets(value: Any) -> Any:
-    """Recursively replace SecretStr instances with ``"***"``."""
-    if isinstance(value, dict):
-        return {k: _redact_secrets(v) for k, v in value.items()}
-    if isinstance(value, list):
-        return [_redact_secrets(item) for item in value]
-    # Match by class name so no runtime pydantic import is needed.
-    if getattr(value, "__class__", None) and value.__class__.__name__ == _SECRET_STR_CLASS:
-        return "***"
-    return value
-
-
-class SafeDumpMixin(BaseModel):
-    """Pydantic mixin that adds a ``safe_dump`` method identical to ``model_dump``
-    but with all ``SecretStr`` fields replaced by ``"***"``.
-
-    Inherit from this instead of ``BaseModel`` when you want the convenience
-    method on the model itself::
-
-        class MySettings(SafeDumpMixin):
-            api_key: SecretStr = Field(default="")
-            host: str = "localhost"
-
-        settings = MySettings(api_key="s3cr3t", host="prod")
-        assert settings.safe_dump()["api_key"] == "***"
-        assert settings.safe_dump()["host"] == "prod"
-    """
-
-    def safe_dump(self) -> dict[str, Any]:  # type: ignore[override]
-        """Return a dict with all ``SecretStr`` fields replaced by ``"***"``."""
-        return safe_dump(self)

package/skills/vds-skill/vds-scripts/platform_core/src/vds_platform_core/severity.py

@@ -1,175 +0,0 @@
-"""VDS error severity and recoverability registry.
-
-Provides:
-- ``ErrorSeverity`` — StrEnum with CRITICAL / HIGH / MEDIUM / LOW levels.
-- ``ErrorRecoverability`` — StrEnum with 5-value recovery strategy taxonomy,
-  derived from production patterns across audit, sync, and provider failure
-  classification subsystems.
-- ``ErrorCodeMeta`` — frozen generic dataclass associating a code string with
-  severity, recoverability, and a human description.
-- ``ErrorCodeRegistry`` — prefix-scoped store for ``ErrorCodeMeta`` instances,
-  supporting register / lookup / enumerate operations.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Iterator
-from dataclasses import dataclass
-from enum import StrEnum
-from typing import TypeVar
-
-# ---------------------------------------------------------------------------
-# Enumerations
-# ---------------------------------------------------------------------------
-
-
-class ErrorSeverity(StrEnum):
-    """Operational severity levels for VDS errors."""
-
-    CRITICAL = "critical"
-    HIGH = "high"
-    MEDIUM = "medium"
-    LOW = "low"
-
-
-class ErrorRecoverability(StrEnum):
-    """Categorizes error recovery strategy.
-
-    Derived from production patterns across audit (3-value), sync (boolean),
-    and provider failure classification (6-value). See research RQ-severity-2026-04-16.
-
-    Mapping to existing taxonomies:
-
-    * audit ``RETRYABLE``                     → ``TRANSIENT``
-    * audit ``MANUAL``                        → ``MANUAL``
-    * audit ``NON_RECOVERABLE``               → ``PERMANENT``
-    * sync ``recoverable=True``               → ``TRANSIENT`` or ``RATE_LIMITED``
-    * sync ``recoverable=False``              → ``PERMANENT``
-    * provider ``RETRYABLE_TRANSIENT``        → ``TRANSIENT``
-    * provider ``QUOTA_OR_CAPACITY``          → ``RATE_LIMITED``
-    * provider ``PROVIDER_DEGRADED``          → ``DEGRADED``
-    * provider ``ROUTE_PROVIDER_UNAVAILABLE`` → ``DEGRADED``
-    * provider ``TERMINAL_AUTH``              → ``PERMANENT``
-    * provider ``NON_PROVIDER_BUG``           → ``PERMANENT``
-    """
-
-    TRANSIENT = "transient"
-    """Immediate retry likely to succeed (network timeout, 503)."""
-
-    RATE_LIMITED = "rate_limited"
-    """Wait then retry (429, quota exhaustion, Retry-After header)."""
-
-    DEGRADED = "degraded"
-    """Continue with reduced functionality or failover to alternate provider."""
-
-    MANUAL = "manual"
-    """Human intervention required (config error, missing resource, permission)."""
-
-    PERMANENT = "permanent"
-    """Cannot recover regardless of retry or intervention (401, validation failure)."""
-
-
-# ---------------------------------------------------------------------------
-# Generic type variables
-# ---------------------------------------------------------------------------
-
-S = TypeVar("S", bound=StrEnum)
-R = TypeVar("R", bound=StrEnum)
-
-
-# ---------------------------------------------------------------------------
-# ErrorCodeMeta
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class ErrorCodeMeta[S: StrEnum, R: StrEnum]:
-    """Immutable metadata for a single error code.
-
-    Args:
-        code: Unique error code string (e.g. ``"CLI-001"``).
-        description: Human-readable description of the error condition.
-        severity: Operational impact level.
-        recoverability: Whether the condition is expected to self-resolve.
-    """
-
-    code: str
-    description: str
-    severity: S  # type: ignore[misc]
-    recoverability: R  # type: ignore[misc]
-
-
-# ---------------------------------------------------------------------------
-# ErrorCodeRegistry
-# ---------------------------------------------------------------------------
-
-
-class ErrorCodeRegistry[S: StrEnum, R: StrEnum]:
-    """Prefix-scoped registry for :class:`ErrorCodeMeta` instances.
-
-    Error codes are grouped by *prefix* (e.g. ``"CLI"``, ``"SONAR"``).
-    Within a prefix, code strings must be unique.
-
-    Example::
-
-        registry = ErrorCodeRegistry()
-        registry.register(
-            "CLI",
-            ErrorCodeMeta("CLI-001", "Config missing", ErrorSeverity.HIGH, ErrorRecoverability.PERMANENT),
-        )
-        meta = registry.lookup("CLI-001")
-    """
-
-    def __init__(self) -> None:
-        # Map: prefix → {code → ErrorCodeMeta}
-        self._store: dict[str, dict[str, ErrorCodeMeta[S, R]]] = {}
-
-    # ------------------------------------------------------------------
-    # Mutation
-    # ------------------------------------------------------------------
-
-    def register(self, prefix: str, meta: ErrorCodeMeta[S, R]) -> None:
-        """Register *meta* under *prefix*.
-
-        Raises:
-            ValueError: If a ``meta`` with the same ``code`` already exists
-                under *prefix*.
-        """
-        bucket = self._store.setdefault(prefix, {})
-        if meta.code in bucket:
-            raise ValueError(
-                f"Error code {meta.code!r} is already registered under prefix {prefix!r}. "
-                "Use a unique code or remove the existing registration first."
-            )
-        bucket[meta.code] = meta
-
-    # ------------------------------------------------------------------
-    # Query
-    # ------------------------------------------------------------------
-
-    def lookup(self, code: str) -> ErrorCodeMeta[S, R] | None:
-        """Return the ``ErrorCodeMeta`` for *code*, or ``None`` if not found."""
-        for bucket in self._store.values():
-            if code in bucket:
-                return bucket[code]
-        return None
-
-    def all_codes(self, *, prefix: str | None = None) -> Iterator[ErrorCodeMeta[S, R]]:
-        """Yield all registered ``ErrorCodeMeta`` instances.
-
-        Args:
-            prefix: When supplied, restrict results to that prefix only.
-        """
-        if prefix is not None:
-            yield from self._store.get(prefix, {}).values()
-        else:
-            for bucket in self._store.values():
-                yield from bucket.values()
-
-
-__all__ = [
-    "ErrorCodeMeta",
-    "ErrorCodeRegistry",
-    "ErrorRecoverability",
-    "ErrorSeverity",
-]

package/skills/vds-skill/vds-scripts/platform_core/tests/conftest.py

@@ -1 +0,0 @@
-"""Shared pytest fixtures for vds_platform_core tests."""