vibey-bootstrap 4.0.0__py3-none-any.whl

vibey_bootstrap/__init__.py

@@ -0,0 +1,271 @@
+"""
+vibey-bootstrap (formerly azure-bootstrap)
+
+A production-ready Azure bootstrap library that handles application initialization
+for Azure Functions, including App Configuration, Key Vault, and App Insights integration.
+
+This library solves the circular dependency between logging and configuration by:
+1. Starting with basic console logging
+2. Loading configuration from Azure App Configuration + Key Vault
+3. Upgrading to App Insights telemetry when available
+4. Loading all configs to os.environ for transparent access
+
+Quick Start:
+    from vibey_bootstrap import initialize_application, get_bootstrap_logger
+
+    # Get logger that works immediately
+    logger = get_bootstrap_logger(__name__)
+
+    # Bootstrap the application (App Config + Key Vault + App Insights)
+    config_repo = initialize_application()
+
+    # Now all configs are in os.environ
+    db_host = os.getenv("DATABASE_HOST")
+
+For detailed usage, see: https://github.com/adammatthewsteinberger/vibey-bootstrap
+"""
+
+__version__ = "4.0.0"
+__author__ = "Adam Matthew Steinberger"
+__license__ = "MIT"
+
+# ──────────────────────────────────────────────────────────────────────────
+# v2 additions (additive only — never alters the v1 surface above)
+# ──────────────────────────────────────────────────────────────────────────
+import logging as _stdlib_logging
+import os as _os
+
+# v3.0.0 additions (opt-in subpackages re-exported for convenience)
+from vibey_bootstrap.aks import build_info as build_info
+from vibey_bootstrap.audit import verify_chain as verify_chain
+from vibey_bootstrap.auth import verify_hmac_signature as verify_hmac_signature
+from vibey_bootstrap.bootstrap import bootstrap_initialized as bootstrap_initialized
+from vibey_bootstrap.bootstrap import ensure_bootstrap as ensure_bootstrap
+from vibey_bootstrap.bootstrap import load_local_settings as load_local_settings
+from vibey_bootstrap.counters import bump_counter as bump_counter
+from vibey_bootstrap.counters import counter_snapshot as counter_snapshot
+from vibey_bootstrap.db.outbox import drain_outbox as drain_outbox
+from vibey_bootstrap.email import AcsEmailSender as AcsEmailSender
+from vibey_bootstrap.exceptions import InvalidMessageError as InvalidMessageError
+from vibey_bootstrap.exceptions import NetworkError as NetworkError
+from vibey_bootstrap.exceptions import PipelineError as PipelineError
+from vibey_bootstrap.exceptions import RateLimitError as RateLimitError
+from vibey_bootstrap.exceptions import TransientError as TransientError
+from vibey_bootstrap.exceptions import UnrecoverableError as UnrecoverableError
+from vibey_bootstrap.exceptions import is_unrecoverable as is_unrecoverable
+from vibey_bootstrap.governance import budget_guard as budget_guard
+from vibey_bootstrap.governance import track_usage as track_usage
+from vibey_bootstrap.http import build_session as build_session
+from vibey_bootstrap.http import request_with_retry as request_with_retry
+from vibey_bootstrap.identity import build_tenant_credential as build_tenant_credential
+from vibey_bootstrap.identity import (
+    build_tenant_credential_cached as build_tenant_credential_cached,
+)
+from vibey_bootstrap.logging import JsonLogFormatter as JsonLogFormatter
+from vibey_bootstrap.logging import configure_logging as configure_logging
+from vibey_bootstrap.logging import correlation_scope as correlation_scope
+from vibey_bootstrap.logging import get_correlation_id as get_correlation_id
+from vibey_bootstrap.logging import mask_api_key as mask_api_key
+from vibey_bootstrap.logging import mask_bearer_token as mask_bearer_token
+from vibey_bootstrap.logging import mask_email_address as mask_email_address
+from vibey_bootstrap.logging import mask_secrets_in_dict as mask_secrets_in_dict
+from vibey_bootstrap.logging import safe_json_dumps as safe_json_dumps
+from vibey_bootstrap.logging import sanitize_for_log as sanitize_for_log
+from vibey_bootstrap.logging import set_correlation_id as set_correlation_id
+
+# Exceptions
+from vibey_bootstrap.models.exceptions import ConfigurationError as ConfigurationError
+from vibey_bootstrap.models.exceptions import KeyVaultError as KeyVaultError
+from vibey_bootstrap.models.exceptions import RepositoryError as RepositoryError
+from vibey_bootstrap.path_safety import confine_to_root as confine_to_root
+from vibey_bootstrap.path_safety import sanitize_path_segment as sanitize_path_segment
+from vibey_bootstrap.phases import PhaseResult as PhaseResult
+from vibey_bootstrap.phases import run_phase as run_phase
+from vibey_bootstrap.phases import run_phases as run_phases
+
+# Repository implementations
+from vibey_bootstrap.repositories.enhanced_config_repository import (
+    EnhancedConfigRepository as EnhancedConfigRepository,
+)
+from vibey_bootstrap.repositories.enhanced_config_repository import (
+    create_enhanced_config_repository as create_enhanced_config_repository,
+)
+from vibey_bootstrap.repositories.interfaces.enhanced_config_repository_interface import (
+    EnhancedConfigRepositoryInterface as EnhancedConfigRepositoryInterface,
+)
+from vibey_bootstrap.repositories.interfaces.secrets_repository_interface import (
+    SecretsRepositoryInterface as SecretsRepositoryInterface,
+)
+from vibey_bootstrap.repositories.secrets_repository import SecretsRepository as SecretsRepository
+from vibey_bootstrap.security import compare_secrets as compare_secrets
+
+# Core classes for advanced usage
+# Main bootstrap function - most users only need this
+from vibey_bootstrap.services.application_bootstrap import (
+    ApplicationBootstrap as ApplicationBootstrap,
+)
+from vibey_bootstrap.services.application_bootstrap import (
+    initialize_application as initialize_application,
+)
+
+# Bootstrap logging - works before configuration loaded
+from vibey_bootstrap.services.bootstrap_logging import BootstrapLogger as BootstrapLogger
+from vibey_bootstrap.services.bootstrap_logging import ExtraFieldsFormatter as ExtraFieldsFormatter
+from vibey_bootstrap.services.bootstrap_logging import (
+    ensure_bootstrap_logging as ensure_bootstrap_logging,
+)
+from vibey_bootstrap.services.bootstrap_logging import get_bootstrap_logger as get_bootstrap_logger
+
+# Interfaces for type hinting and custom implementations
+from vibey_bootstrap.services.interfaces.application_bootstrap_interface import (
+    ApplicationBootstrapInterface as ApplicationBootstrapInterface,
+)
+from vibey_bootstrap.services.interfaces.bootstrap_logger_interface import (
+    BootstrapLoggerInterface as BootstrapLoggerInterface,
+)
+from vibey_bootstrap.services.interfaces.telemetry_manager_interface import (
+    TelemetryManagerInterface as TelemetryManagerInterface,
+)
+from vibey_bootstrap.services.telemetry import TelemetryManager as TelemetryManager
+from vibey_bootstrap.services.telemetry import telemetry_manager as telemetry_manager
+from vibey_bootstrap.softfail import SoftFailResult as SoftFailResult
+from vibey_bootstrap.softfail import soft_fail as soft_fail
+from vibey_bootstrap.softfail import soft_fail_with as soft_fail_with
+from vibey_bootstrap.tracing import latency_snapshot as latency_snapshot
+from vibey_bootstrap.tracing import traced as traced
+from vibey_bootstrap.transports import configure_transports as configure_transports
+from vibey_bootstrap.transports import disable_transport as disable_transport
+from vibey_bootstrap.transports import enable_transport as enable_transport
+from vibey_bootstrap.transports import list_transports as list_transports
+from vibey_bootstrap.transports import register_transport as register_transport
+from vibey_bootstrap.validation import MessageSchema as MessageSchema
+from vibey_bootstrap.validation import queue_message_schema as queue_message_schema
+from vibey_bootstrap.validation import validate_message as validate_message
+
+
+def refresh_setting(*names: str) -> None:
+    """Re-read named settings from the cached App Configuration repo and
+    write their values into ``os.environ``.
+
+    Net-new in v2. Designed to be called from a recurring job (see
+    ``vibey_bootstrap.config_refresh.refresh_log_flags``) so ops can flip a
+    setting in App Configuration and see it take effect within seconds
+    without redeploying.
+
+    No-ops with a DEBUG log when ``initialize_application()`` has not yet
+    run. Best-effort — never raises.
+    """
+    if not names:
+        return
+    logger = _stdlib_logging.getLogger(__name__)
+    try:
+        from vibey_bootstrap.services.application_bootstrap import (
+            get_last_initialized_repo,
+        )
+    except Exception:
+        logger.debug("refresh_setting: bootstrap module unavailable")
+        return
+    repo = get_last_initialized_repo()
+    if repo is None:
+        logger.debug("refresh_setting: no cached repo (initialize_application not called)")
+        return
+    for name in names:
+        if not isinstance(name, str) or not name:
+            continue
+        try:
+            value = repo.get_value(name)
+        except Exception as exc:
+            logger.warning("refresh_setting: failed to read %s: %s", name, exc)
+            continue
+        if value is None:
+            continue
+        _os.environ[name] = str(value)
+
+
+# Public API
+__all__ = [
+    # Version
+    "__version__",
+    # Main bootstrap functions (most common usage)
+    "initialize_application",
+    "get_bootstrap_logger",
+    "create_enhanced_config_repository",
+    "ensure_bootstrap_logging",
+    # Singleton instance
+    "telemetry_manager",
+    # Core classes
+    "ApplicationBootstrap",
+    "BootstrapLogger",
+    "ExtraFieldsFormatter",
+    "TelemetryManager",
+    "EnhancedConfigRepository",
+    "SecretsRepository",
+    # Interfaces
+    "ApplicationBootstrapInterface",
+    "BootstrapLoggerInterface",
+    "TelemetryManagerInterface",
+    "EnhancedConfigRepositoryInterface",
+    "SecretsRepositoryInterface",
+    # Exceptions
+    "RepositoryError",
+    "ConfigurationError",
+    "KeyVaultError",
+    # v2 additions — Tier 1 always-on primitives
+    "bootstrap_initialized",
+    "bump_counter",
+    "configure_logging",
+    "correlation_scope",
+    "counter_snapshot",
+    "ensure_bootstrap",
+    "get_correlation_id",
+    "latency_snapshot",
+    "load_local_settings",
+    "mask_api_key",
+    "mask_bearer_token",
+    "mask_email_address",
+    "mask_secrets_in_dict",
+    "refresh_setting",
+    "safe_json_dumps",
+    "sanitize_for_log",
+    "set_correlation_id",
+    "traced",
+    # v2 Parts 2+3 — exceptions, soft-fail, phases, validation, path safety, security
+    "InvalidMessageError",
+    "MessageSchema",
+    "NetworkError",
+    "PhaseResult",
+    "PipelineError",
+    "RateLimitError",
+    "SoftFailResult",
+    "TransientError",
+    "UnrecoverableError",
+    "compare_secrets",
+    "confine_to_root",
+    "is_unrecoverable",
+    "queue_message_schema",
+    "run_phase",
+    "run_phases",
+    "sanitize_path_segment",
+    "soft_fail",
+    "soft_fail_with",
+    "validate_message",
+    # v2.1 additions — logging transport layer
+    "JsonLogFormatter",
+    "configure_transports",
+    "disable_transport",
+    "enable_transport",
+    "list_transports",
+    "register_transport",
+    # v3.0.0 — db, outbox, email, http, documentdb, aks, governance, identity, audit
+    "build_tenant_credential",
+    "build_tenant_credential_cached",
+    "verify_chain",
+    "budget_guard",
+    "track_usage",
+    "build_session",
+    "request_with_retry",
+    "build_info",
+    "drain_outbox",
+    "AcsEmailSender",
+    "verify_hmac_signature",
+]

vibey_bootstrap/aks/__init__.py

@@ -0,0 +1,84 @@
+"""AKS runtime helpers — graceful shutdown, build info, probes, pod context."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from vibey_bootstrap.counters import counter_snapshot
+
+_logger = logging.getLogger(__name__)
+
+
+def install_sigterm_handler(stop_event: threading.Event) -> None:
+    """Register SIGTERM handler that sets *stop_event* for graceful drain."""
+
+    def _handler(signum: int, frame: Any) -> None:
+        _logger.info("SIGTERM received — setting stop event")
+        stop_event.set()
+
+    signal.signal(signal.SIGTERM, _handler)
+
+
+def setup_async_sigterm_handler() -> asyncio.Event:
+    """Return an asyncio.Event set on SIGTERM."""
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+
+    def _handler() -> None:
+        _logger.info("SIGTERM received — setting async stop event")
+        stop.set()
+
+    loop.add_signal_handler(signal.SIGTERM, _handler)
+    return stop
+
+
+def build_info() -> dict[str, str | None]:
+    """Return version/build metadata from downward-API or CI env vars."""
+    return {
+        "version": os.environ.get("BUILD_VERSION") or os.environ.get("APP_VERSION"),
+        "git_sha": os.environ.get("GIT_SHA"),
+        "build_time": os.environ.get("BUILD_TIME"),
+        "image_tag": os.environ.get("IMAGE_TAG"),
+        "pod_name": os.environ.get("POD_NAME"),
+        "pod_namespace": os.environ.get("POD_NAMESPACE"),
+        "node_name": os.environ.get("NODE_NAME"),
+    }
+
+
+def keda_metric_value(name: str = "queue_depth") -> float:
+    """Scalar metric for KEDA metrics-api scaler (from counters snapshot)."""
+    snap = counter_snapshot()
+    return float(snap.get(name, 0))
+
+
+def mount_build_info_route(app: Any, path: str = "/api/version") -> None:
+    """Mount a FastAPI route returning :func:`build_info`."""
+
+    @app.get(path)
+    def _version() -> dict[str, str | None]:
+        return build_info()
+
+
+def pod_context_extra() -> dict[str, str | None]:
+    """Correlation/log extras from Kubernetes downward API env vars."""
+    return {
+        "pod_name": os.environ.get("POD_NAME"),
+        "pod_namespace": os.environ.get("POD_NAMESPACE"),
+        "node_name": os.environ.get("NODE_NAME"),
+    }
+
+
+__all__ = [
+    "build_info",
+    "install_sigterm_handler",
+    "keda_metric_value",
+    "mount_build_info_route",
+    "pod_context_extra",
+    "setup_async_sigterm_handler",
+]

vibey_bootstrap/aks/leader_election.py

@@ -0,0 +1,82 @@
+"""Generic leader election — K8s ConfigMap lock or soft no-op."""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from typing import Any
+
+_logger = logging.getLogger(__name__)
+
+
+class LeaderElection:
+    """Simple in-process leader election using a ConfigMap name env var.
+
+    When ``LEADER_ELECTION_CONFIGMAP`` is unset, :meth:`is_leader` always
+    returns ``True`` (soft no-op for single-replica dev).
+    """
+
+    def __init__(
+        self,
+        *,
+        configmap_name: str | None = None,
+        namespace: str | None = None,
+        identity: str | None = None,
+        lease_seconds: int = 30,
+    ) -> None:
+        self._configmap = configmap_name or os.environ.get("LEADER_ELECTION_CONFIGMAP")
+        self._namespace = namespace or os.environ.get("POD_NAMESPACE", "default")
+        self._identity = identity or os.environ.get("POD_NAME", "local")
+        self._lease_seconds = lease_seconds
+        self._is_leader = False
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    @property
+    def is_leader(self) -> bool:
+        if not self._configmap:
+            return True
+        with self._lock:
+            return self._is_leader
+
+    def start(self) -> None:
+        if not self._configmap:
+            self._is_leader = True
+            return
+        self._thread = threading.Thread(target=self._run, name="leader-election", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=5.0)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                acquired = self._try_acquire()
+                with self._lock:
+                    self._is_leader = acquired
+            except Exception:
+                _logger.debug("leader election cycle failed", exc_info=True)
+            self._stop.wait(self._lease_seconds / 2)
+
+    def _try_acquire(self) -> bool:
+        # Production apps use the K8s API; this stub uses env-only soft lock.
+        holder = os.environ.get("LEADER_HOLDER")
+        if holder is None or holder == self._identity:
+            os.environ["LEADER_HOLDER"] = self._identity
+            return True
+        return holder == self._identity
+
+
+def leader_election(**kwargs: Any) -> LeaderElection:
+    """Factory for :class:`LeaderElection`."""
+    le = LeaderElection(**kwargs)
+    le.start()
+    return le
+
+
+__all__ = ["LeaderElection", "leader_election"]

vibey_bootstrap/alerts/__init__.py

@@ -0,0 +1,36 @@
+"""Tier 2 tiered-alert dispatcher.
+
+Apps register a sender (any callable matching ``AlertSender``) at startup,
+then code anywhere in the app can fire ``alert_dev_team(...)`` — the
+dispatcher handles dedup, rate-limit, escalation, and HTML rendering.
+"""
+
+from vibey_bootstrap.alerts.dispatcher import (
+    AlertRecord,
+    AlertSender,
+    AlertSeverity,
+    alert_dev_team,
+    drain_pending_alerts,
+    install_global_exception_hooks,
+    register_dispatcher,
+    reset_state,
+)
+from vibey_bootstrap.alerts.render import (
+    _render_alert_html,
+    render_pending_alerts_html,
+)
+from vibey_bootstrap.counters import bump_counter, counter_snapshot
+
+__all__ = [
+    "AlertRecord",
+    "AlertSender",
+    "AlertSeverity",
+    "alert_dev_team",
+    "bump_counter",
+    "counter_snapshot",
+    "drain_pending_alerts",
+    "install_global_exception_hooks",
+    "register_dispatcher",
+    "render_pending_alerts_html",
+    "reset_state",
+]