kstlib 2.2.0__tar.gz → 2.3.0__tar.gz

{kstlib-2.2.0/src/kstlib.egg-info → kstlib-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 2.2.0
+Version: 2.3.0
 Summary: Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)
 Author-email: Michel TRUONG <michel.truong@gmail.com>
 Maintainer-email: Michel TRUONG <michel.truong@gmail.com>
@@ -42,7 +42,7 @@ Requires-Dist: websockets<16,>=15.0
 Requires-Dist: jinja2<4,>=3.1.5
 Requires-Dist: humanize<5,>=4.11
 Requires-Dist: httpx<1,>=0.28
-Requires-Dist: authlib<2,>=1.6.9
+Requires-Dist: authlib<2,>=1.6.11
 Requires-Dist: pendulum<4,>=3.0
 Requires-Dist: cryptography>=46.0.7
 Requires-Dist: requests>=2.33.0

{kstlib-2.2.0 → kstlib-2.3.0}/pyproject.toml

@@ -56,7 +56,7 @@ dependencies = [
 
     # --- HTTP Client & Auth ---
     "httpx>=0.28,<1",  # Modern async HTTP client (OAuth2/OIDC flows)
-    "authlib>=1.6.9,<2", # OAuth2/OIDC client + JWT signature verification
+    "authlib>=1.6.11,<2", # OAuth2/OIDC client + JWT signature verification (GHSA-jj8c-mmj3-mmgv: CSRF in cache-backed OAuth state)
 
     # --- Time & Scheduling ---
     "pendulum>=3.0,<4", # Modern datetime library with timezone support

{kstlib-2.2.0 → kstlib-2.3.0}/src/kstlib/__init__.py

@@ -69,6 +69,7 @@ __all__ = [
     "ops",
     "pipeline",
     "rapi",
+    "reload_config",
     "require_config",
     "resilience",
     "secrets",
@@ -117,6 +118,7 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "load_config": ("kstlib.config.loader", "load_config"),
     "load_from_env": ("kstlib.config.loader", "load_from_env"),
     "load_from_file": ("kstlib.config.loader", "load_from_file"),
+    "reload_config": ("kstlib.config.loader", "reload_config"),
     "require_config": ("kstlib.config.loader", "require_config"),
     # Logging
     "LogManager": ("kstlib.logging", "LogManager"),
@@ -250,6 +252,9 @@ if TYPE_CHECKING:
     from kstlib.config.loader import (
         load_from_file as load_from_file,
     )
+    from kstlib.config.loader import (
+        reload_config as reload_config,
+    )
     from kstlib.config.loader import (
         require_config as require_config,
     )

{kstlib-2.2.0 → kstlib-2.3.0}/src/kstlib/config/__init__.py

@@ -34,6 +34,7 @@ from kstlib.config.loader import (
     load_config,
     load_from_env,
     load_from_file,
+    reload_config,
     require_config,
 )
 from kstlib.config.sops import (
@@ -71,6 +72,7 @@ __all__ = [
     "load_config",
     "load_from_env",
     "load_from_file",
+    "reload_config",
     "require_config",
     "reset_decryptor",
 ]

{kstlib-2.2.0 → kstlib-2.3.0}/src/kstlib/config/loader.py

@@ -1064,6 +1064,47 @@ def clear_config() -> None:
     _default_loader.cache = None
 
 
+def reload_config(filename: str = CONFIG_FILENAME) -> Box:
+    """Force-reload the singleton configuration from disk.
+
+    Equivalent to ``clear_config()`` followed by ``get_config()``, but explicit
+    and discoverable in a single import. Designed for interactive sessions
+    (Jupyter, REPL) where the underlying YAML files have been edited and the
+    cached config needs to be refreshed without restarting the kernel.
+
+    Args:
+        filename: Config filename to search for. Defaults to
+            ``kstlib.conf.yml``.
+
+    Returns:
+        Freshly loaded ``Box`` configuration object. The singleton cache is
+        updated in-place, so subsequent ``get_config()`` calls return the same
+        fresh object.
+
+    Raises:
+        ConfigFileNotFoundError: If no configuration file is found in any
+            search location.
+
+    Note:
+        When to use which:
+
+        - ``reload_config()``: explicit one-shot refresh (Jupyter/REPL).
+        - ``get_config(force_reload=True)``: same effect, but the intent is
+          hidden in a kwarg.
+        - ``clear_config()``: only flushes the cache; the next
+          ``get_config()`` call triggers the actual reload. Useful in tests
+          that want to isolate the cache boundary.
+
+    Examples:
+        >>> from kstlib.config import reload_config
+        >>> cfg = reload_config()  # doctest: +SKIP
+        >>> cfg.mail.default  # doctest: +SKIP
+        'corporate'
+
+    """
+    return get_config(filename=filename, force_reload=True)
+
+
 __all__ = [
     "AutoDiscoveryConfig",
     "ConfigLoader",
@@ -1072,5 +1113,6 @@ __all__ = [
     "load_config",
     "load_from_env",
     "load_from_file",
+    "reload_config",
     "require_config",
 ]

{kstlib-2.2.0 → kstlib-2.3.0}/src/kstlib/kstlib.conf.yml

@@ -358,6 +358,21 @@ mail:
   # Leave null to force callers to pass transport= or preset= explicitly.
   default: null
 
+  # SSL/TLS configuration for mail transports.
+  #
+  # Values here override the root ``ssl:`` section (bottom of this file)
+  # for mail only, and are themselves overridden by ``ssl_verify`` and
+  # ``ssl_ca_bundle`` keys set inside an individual preset. Each key
+  # cascades independently: you can set ``verify: false`` here and still
+  # provide ``ssl_ca_bundle`` at the preset level.
+  #
+  # Security: setting ``verify: false`` at any level emits a WARNING log
+  # at transport build time. Prefer ``ca_bundle: /path/to/private-ca.pem``
+  # for internal PKI rather than disabling verification outright.
+  ssl:
+    verify: true
+    ca_bundle: null
+
   # Named transport presets. Each preset declares a "transport" field
   # (smtp or resend) and backend-specific parameters. Define your own
   # presets here and reference them via MailBuilder(preset="name").
@@ -368,11 +383,18 @@ mail:
   #   transport: smtp
   #   host: smtp-secure.corp.local
   #   port: 25
-  #   login: svc_user
+  #   login: svc_mail
   #   password: "secret"
   #   starttls: false
   #   ssl: false
   #   timeout: 30
+  #   # Optional SSL overrides for this preset (highest priority in the cascade):
+  #   ssl_verify: false
+  #   ssl_ca_bundle: /etc/ssl/certs/corp-ca.pem
+  #   # Optional envelope defaults (sender / reply_to only, never to/cc/bcc):
+  #   defaults:
+  #     sender: "Service Notifications <notify@corp.local>"
+  #     reply_to: "Service Notifications <notify@corp.local>"
   #
   # transactional:
   #   transport: resend

{kstlib-2.2.0 → kstlib-2.3.0}/src/kstlib/limits.py

@@ -200,6 +200,18 @@ HARD_MAX_WS_RECONNECT_CHECK = 60.0
 HARD_MIN_WS_DISCONNECT_MARGIN = 60.0
 HARD_MAX_WS_DISCONNECT_MARGIN = 3600.0
 
+#: WebSocket stable connection time bounds (seconds) - delay before resetting reconnect counter.
+HARD_MIN_WS_STABLE_CONNECTION_TIME = 10.0
+HARD_MAX_WS_STABLE_CONNECTION_TIME = 300.0
+
+#: WebSocket server unavailable (code 1013) backoff bounds (seconds).
+HARD_MIN_WS_SERVER_UNAVAILABLE_DELAY = 10.0
+HARD_MAX_WS_SERVER_UNAVAILABLE_DELAY = 300.0
+
+#: WebSocket disconnect alert interval bounds (seconds) - throttle window for alerts.
+HARD_MIN_WS_DISCONNECT_ALERT_INTERVAL = 30.0
+HARD_MAX_WS_DISCONNECT_ALERT_INTERVAL = 3600.0
+
 #: Maximum endpoint reference length (api.endpoint format) - protects against DoS.
 HARD_MAX_ENDPOINT_REF_LENGTH = 256
 
@@ -272,6 +284,9 @@ DEFAULT_WS_QUEUE_SIZE = 1000  # messages
 DEFAULT_WS_DISCONNECT_CHECK = 10.0  # seconds
 DEFAULT_WS_RECONNECT_CHECK = 5.0  # seconds
 DEFAULT_WS_DISCONNECT_MARGIN = 300.0  # seconds (5 minutes before 24h limit)
+DEFAULT_WS_STABLE_CONNECTION_TIME = 60.0  # seconds before resetting reconnect counter
+DEFAULT_WS_SERVER_UNAVAILABLE_DELAY = 30.0  # seconds to wait on code 1013
+DEFAULT_WS_DISCONNECT_ALERT_INTERVAL = 300.0  # seconds between throttled alerts
 
 DEFAULT_PIPELINE_TIMEOUT = 300.0  # seconds (5 minutes)
 DEFAULT_PIPELINE_ON_ERROR = "fail_fast"
@@ -925,6 +940,9 @@ class WebSocketLimits:
         disconnect_check_interval: Seconds between should_disconnect checks.
         reconnect_check_interval: Seconds between should_reconnect checks.
         disconnect_margin: Seconds before platform limit to disconnect.
+        stable_connection_time: Seconds of stable connection before resetting reconnect counter.
+        server_unavailable_delay: Seconds to wait on server code 1013 before reconnect.
+        disconnect_alert_interval: Seconds between throttled disconnect alerts.
 
     """
 
@@ -938,6 +956,9 @@ class WebSocketLimits:
     disconnect_check_interval: float
     reconnect_check_interval: float
     disconnect_margin: float
+    stable_connection_time: float
+    server_unavailable_delay: float
+    disconnect_alert_interval: float
 
 
 def get_websocket_limits(
@@ -1023,6 +1044,24 @@ def get_websocket_limits(
             HARD_MIN_WS_DISCONNECT_MARGIN,
             HARD_MAX_WS_DISCONNECT_MARGIN,
         ),
+        stable_connection_time=_parse_float_config(
+            _get_nested(config, "websocket", "reconnect", "stable_connection_time"),
+            DEFAULT_WS_STABLE_CONNECTION_TIME,
+            HARD_MIN_WS_STABLE_CONNECTION_TIME,
+            HARD_MAX_WS_STABLE_CONNECTION_TIME,
+        ),
+        server_unavailable_delay=_parse_float_config(
+            _get_nested(config, "websocket", "reconnect", "server_unavailable_delay"),
+            DEFAULT_WS_SERVER_UNAVAILABLE_DELAY,
+            HARD_MIN_WS_SERVER_UNAVAILABLE_DELAY,
+            HARD_MAX_WS_SERVER_UNAVAILABLE_DELAY,
+        ),
+        disconnect_alert_interval=_parse_float_config(
+            _get_nested(config, "websocket", "alert", "disconnect_interval"),
+            DEFAULT_WS_DISCONNECT_ALERT_INTERVAL,
+            HARD_MIN_WS_DISCONNECT_ALERT_INTERVAL,
+            HARD_MAX_WS_DISCONNECT_ALERT_INTERVAL,
+        ),
     )