slashpeak 0.1.0__py3-none-any.whl

slashpeak/__init__.py

@@ -0,0 +1,53 @@
+"""SlashPeak Job Router: run each warehouse job where it costs less.
+
+    pip install "slashpeak[bigquery]"
+
+    import slashpeak
+    slashpeak.install()   # hooks every supported library that is installed
+
+Reads ``SLASHPEAK_API_KEY``, ``SLASHPEAK_MODE`` (off | shadow | active),
+``SLASHPEAK_ENDPOINT`` and ``SLASHPEAK_SEND_PARAM_VALUES``. Without a key it
+does nothing. On any error, or no answer within 500 ms, jobs run unchanged.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import List, Optional
+
+from slashpeak._core.settings import Settings
+from slashpeak._version import __version__
+
+__all__ = ["__version__", "install", "uninstall", "Settings"]
+
+#: Warehouse hook → the library it needs.
+_HOOKS = {"bigquery": "google.cloud.bigquery"}
+
+
+def _has(module: str) -> bool:
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def install(settings: Optional[Settings] = None) -> List[str]:
+    """Hooks every supported library that is installed. Returns the hooks that are on."""
+    on = []
+    for name, library in _HOOKS.items():
+        if not _has(library):
+            continue
+        hook = importlib.import_module(f"slashpeak.{name}")
+        if hook.install(settings):
+            on.append(name)
+    return on
+
+
+def uninstall() -> None:
+    """Removes every hook and flushes pending events (at most 1 s)."""
+    import sys
+
+    for name in _HOOKS:
+        hook = sys.modules.get(f"slashpeak.{name}")
+        if hook is not None:
+            hook.uninstall()

slashpeak/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from slashpeak.cli import main
+
+sys.exit(main())

slashpeak/_core/mask.py

@@ -0,0 +1,85 @@
+"""PII masking before any SQL leaves the process.
+
+Same rules, same order and same split as SlashPeak's scan (which masks inside
+BigQuery with RE2): built-in email, phone and IP patterns, then the account's
+own patterns from ``/v1/config``. Backtick-quoted names are left alone.
+
+Python's ``re`` runs the patterns with ``re.ASCII``, because RE2's ``\\d``,
+``\\b`` and ``\\s`` are ASCII-only. One known gap: Python's ASCII ``\\s`` also
+matches a vertical tab, RE2's does not. The server masks again with RE2, so a
+gap can only mask more, never send more.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+#: The router's built-in rules (``spec/mask_vectors.json`` → ``builtinRules``; a test keeps them equal).
+BUILTIN_RULES: Tuple[Tuple[str, str], ...] = (
+    (r"\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b", "<email>"),
+    (
+        r"\+\d(?:[-.\s()]{0,2}\d){6,14}\b|(?:\b1[-.\s])?(?:\(\d{3}\)[-.\s]?|\b\d{3}[-.\s])\d{3}[-.\s]\d{4}\b",
+        "<phone>",
+    ),
+    (r"\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b", "<ip>"),
+    (
+        r"\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b|\b(?:[0-9a-fA-F]{1,4}:){1,6}(?::[0-9a-fA-F]{1,4}){1,6}\b"
+        r"|\b(?:[0-9a-fA-F]{1,4}:){1,7}:|::(?:[0-9a-fA-F]{1,4}:){0,6}[0-9a-fA-F]{1,4}\b",
+        "<ip>",
+    ),
+)
+CUSTOM_TOKEN = "<redacted>"
+BUILTIN_REVISION = "builtin"
+
+#: Same split as the scan's ``REGEXP_EXTRACT_ALL(text, r'`[^`]*`|[^`]+|`')``.
+_SEGMENTS = re.compile(r"`[^`]*`|[^`]+|`")
+
+
+class MaskError(ValueError):
+    """A rule does not compile. The caller then sends nothing."""
+
+
+class Masker:
+    def __init__(self, rules: Iterable[Tuple[str, str]], revision: str) -> None:
+        compiled: List[Tuple["re.Pattern[str]", str]] = []
+        for pattern, token in rules:
+            try:
+                compiled.append((re.compile(pattern, re.ASCII), token))
+            except (re.error, TypeError, ValueError) as error:
+                raise MaskError("mask rule does not compile") from error
+        self._rules = tuple(compiled)
+        self.revision = revision
+
+    def _mask_segment(self, text: str) -> str:
+        for regex, token in self._rules:
+            # A function replacement: the token is used as written, never read for backrefs.
+            text = regex.sub(lambda _match, _token=token: _token, text)
+        return text
+
+    def mask(self, text: str) -> str:
+        out = []
+        for match in _SEGMENTS.finditer(text):
+            segment = match.group(0)
+            out.append(segment if len(segment) > 1 and segment.startswith("`") else self._mask_segment(segment))
+        return "".join(out)
+
+
+def builtin_masker(owner_patterns: Sequence[str] = ()) -> Masker:
+    return Masker(list(BUILTIN_RULES) + [(p, CUSTOM_TOKEN) for p in owner_patterns], BUILTIN_REVISION)
+
+
+def masker_from_config(mask: object) -> Optional[Masker]:
+    """The masker for ``/v1/config``'s ``mask`` block; None when it is missing or malformed."""
+    if not isinstance(mask, dict):
+        return None
+    rules = mask.get("rules")
+    revision = mask.get("revision")
+    if not isinstance(rules, list) or not isinstance(revision, str):
+        return None
+    pairs = []
+    for rule in rules:
+        if not isinstance(rule, dict) or not isinstance(rule.get("pattern"), str) or not isinstance(rule.get("token"), str):
+            return None
+        pairs.append((rule["pattern"], rule["token"]))
+    return Masker(pairs, revision[:64])

slashpeak/_core/router.py

@@ -0,0 +1,379 @@
+"""The SDK's view of the router: decide (with breaker and cache), config poll, events.
+
+Everything here fails open. Any doubt means "no decision", and the job runs as
+the caller wrote it.
+"""
+
+from __future__ import annotations
+
+import atexit
+import hashlib
+import logging
+import math
+import os
+import queue
+import random
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from slashpeak._version import __version__
+from slashpeak._core.mask import Masker, MaskError, builtin_masker, masker_from_config
+from slashpeak._core.settings import Settings, stricter_mode
+from slashpeak._core.transport import Reply, Transport
+
+logger = logging.getLogger("slashpeak")
+
+BREAKER_FAILURES = 5
+BREAKER_OPEN_S = 30.0
+CACHE_MAX = 2048
+EVENT_BATCH = 100
+EVENT_INTERVAL_S = 2.0
+EVENT_QUEUE_MAX = 5000
+EXIT_FLUSH_S = 1.0
+POLL_MIN_S = 10.0
+POLL_MAX_S = 600.0
+DEFAULT_TTL_S = 60.0
+
+
+def _positive_number(value: Any) -> Optional[float]:
+    """A finite number above 0, else None. JSON from Python's parser may carry NaN or Infinity."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    number = float(value)
+    return number if math.isfinite(number) and number > 0 else None
+
+
+def _version_tuple(value: str) -> Tuple[int, int, int]:
+    parts = []
+    for piece in value.replace("+", ".").replace("-", ".").split(".")[:3]:
+        digits = "".join(ch for ch in piece if ch.isdigit())
+        parts.append(int(digits) if digits else 0)
+    while len(parts) < 3:
+        parts.append(0)
+    return parts[0], parts[1], parts[2]
+
+
+def client_at_least(version: str, minimum: Optional[str]) -> bool:
+    """Same rule as the server's ``clientAtLeast``."""
+    return not minimum or _version_tuple(version) >= _version_tuple(minimum)
+
+
+class Breaker:
+    """5 failures in a row → open 30 s → one probe. A good probe closes it."""
+
+    def __init__(self, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._failures = 0
+        self._opened_at: Optional[float] = None
+        self._probing = False
+
+    def allow(self) -> bool:
+        with self._lock:
+            if self._opened_at is None:
+                return True
+            if self._probing or self._clock() - self._opened_at < BREAKER_OPEN_S:
+                return False
+            self._probing = True
+            return True
+
+    def record(self, ok: bool) -> None:
+        with self._lock:
+            if ok:
+                self._failures = 0
+                self._opened_at = None
+            else:
+                self._failures += 1
+                if self._probing or self._failures >= BREAKER_FAILURES:
+                    self._opened_at = self._clock()
+            self._probing = False
+
+
+class _Flight:
+    __slots__ = ("done", "value")
+
+    def __init__(self) -> None:
+        self.done = threading.Event()
+        self.value: Optional[Dict[str, Any]] = None
+
+
+class DecisionCache:
+    """Per-process cache of decisions, key = sha256(project, location, SQL). Single-flight per key."""
+
+    def __init__(self, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._entries: "OrderedDict[str, Tuple[float, Dict[str, Any]]]" = OrderedDict()
+        self._flights: Dict[str, _Flight] = {}
+
+    @staticmethod
+    def key(project: str, location: Optional[str], sql: str) -> str:
+        return hashlib.sha256("\x00".join((project, location or "", sql)).encode("utf-8")).hexdigest()
+
+    def get_or_fetch(self, key: str, fetch: Callable[[], Optional[Dict[str, Any]]], ttl_cap_s: float, wait_s: float) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            hit = self._entries.get(key)
+            if hit is not None:
+                if hit[0] > self._clock():
+                    self._entries.move_to_end(key)
+                    return hit[1]
+                del self._entries[key]
+            flight = self._flights.get(key)
+            leader = flight is None
+            if leader:
+                flight = _Flight()
+                self._flights[key] = flight
+        assert flight is not None
+        if not leader:
+            # Another thread is asking for the same query: wait for its answer, within our deadline.
+            return flight.value if flight.done.wait(wait_s) else None
+        value: Optional[Dict[str, Any]] = None
+        try:
+            value = fetch()
+        finally:
+            with self._lock:
+                self._flights.pop(key, None)
+                ttl = _cache_ttl(value, ttl_cap_s)
+                if value is not None and ttl > 0:
+                    self._entries[key] = (self._clock() + ttl, value)
+                    while len(self._entries) > CACHE_MAX:
+                        self._entries.popitem(last=False)
+            flight.value = value
+            flight.done.set()
+        return value
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+            self._flights.clear()
+
+
+def _cache_ttl(decision: Optional[Dict[str, Any]], cap_s: float) -> float:
+    if not decision or decision.get("cacheScope") != "sql":
+        return 0.0
+    ttl = _positive_number(decision.get("ttlSeconds"))
+    return min(ttl, cap_s) if ttl is not None else 0.0
+
+
+class Router:
+    """Process-wide router state. Thread-safe; ``after_fork_in_child`` rebuilds it in a child."""
+
+    def __init__(self, settings: Settings, transport: Optional[Transport] = None, clock: Callable[[], float] = time.monotonic) -> None:
+        self.settings = settings
+        self._clock = clock
+        self.transport = transport or Transport(settings.endpoint, settings.api_key or "")
+        self.breaker = Breaker(clock)
+        self.cache = DecisionCache(clock)
+        self._config: Optional[Dict[str, Any]] = None
+        self._etag: Optional[str] = None
+        self._masker: Optional[Masker] = builtin_masker()
+        self._state_lock = threading.Lock()
+        self._events: "queue.Queue[Dict[str, Any]]" = queue.Queue(maxsize=EVENT_QUEUE_MAX)
+        self._stop = threading.Event()
+        self._threads_pid = -1
+        self._threads_lock = threading.Lock()
+        self._closed = False
+
+    # -- background threads ----------------------------------------------------------------
+    def start(self) -> None:
+        """Starts the config and event threads once per process (again in a forked child)."""
+        if self._threads_pid == os.getpid() or self._closed:
+            return
+        with self._threads_lock:
+            if self._threads_pid == os.getpid():
+                return
+            self._threads_pid = os.getpid()
+            self._stop = threading.Event()
+            threading.Thread(target=self._config_loop, name="slashpeak-config", daemon=True).start()
+            threading.Thread(target=self._event_loop, name="slashpeak-events", daemon=True).start()
+
+    def after_fork_in_child(self) -> None:
+        # Locks held by another thread at fork time stay locked forever in the child: make new ones.
+        self._state_lock = threading.Lock()
+        self._threads_lock = threading.Lock()
+        self.breaker = Breaker(self._clock)
+        self.cache = DecisionCache(self._clock)
+        self._events = queue.Queue(maxsize=EVENT_QUEUE_MAX)
+        self._threads_pid = -1
+        self.transport.after_fork_in_child()
+
+    def close(self, flush_s: float = EXIT_FLUSH_S) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._stop.set()
+        if self._threads_pid == os.getpid():
+            self.flush_events(deadline_s=flush_s)
+        self.transport.close()
+
+    # -- config ----------------------------------------------------------------------------
+    def poll_config(self) -> bool:
+        """One ``GET /v1/config`` with ETag. True when the call worked (200 or 304)."""
+        headers = {"If-None-Match": self._etag} if self._etag else None
+        try:
+            reply = self.transport.request("GET", "/v1/config", headers=headers)
+        except Exception:  # noqa: BLE001
+            logger.debug("slashpeak config fetch failed", extra={"code": "network"})
+            return False
+        if reply.status == 304:
+            return True
+        if reply.status != 200 or reply.body is None:
+            logger.debug("slashpeak config fetch failed", extra={"code": f"http_{reply.status}"})
+            return False
+        self._apply_config(reply)
+        return True
+
+    def _apply_config(self, reply: Reply) -> None:
+        config = reply.body or {}
+        masker: Optional[Masker]
+        try:
+            masker = masker_from_config(config.get("mask"))
+        except MaskError:
+            masker = None  # A rule Python cannot compile: send nothing until it changes.
+        else:
+            if masker is None:
+                masker = builtin_masker()
+        with self._state_lock:
+            self._config = config
+            self._etag = reply.etag
+            self._masker = masker
+
+    def _poll_seconds(self) -> float:
+        config = self._config or {}
+        value = config.get("pollSeconds")
+        if isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value):
+            return max(POLL_MIN_S, min(POLL_MAX_S, float(value)))
+        return 60.0
+
+    def _config_loop(self) -> None:
+        while not self._stop.is_set():
+            ok = self.poll_config()
+            wait = self._poll_seconds() if ok else POLL_MIN_S
+            # Jitter, so a fleet of workers started together does not poll together.
+            self._stop.wait(wait * random.uniform(0.9, 1.1))
+
+    def masker(self) -> Optional[Masker]:
+        return self._masker
+
+    def config(self) -> Optional[Dict[str, Any]]:
+        return self._config
+
+    # -- gating ----------------------------------------------------------------------------
+    def _policies_for(self, project: str) -> Optional[List[Dict[str, Any]]]:
+        """Policies that may cover ``project``; None when no config has arrived yet."""
+        config = self._config
+        if config is None:
+            return None
+        policies = [p for p in config.get("policies") or [] if isinstance(p, dict)]
+        out = []
+        for policy in policies:
+            projects = policy.get("projects") or []
+            # An empty list covers every project of that connection (the server's rule).
+            if not projects or project in projects:
+                out.append(policy)
+        return out
+
+    def may_decide(self, project: str) -> bool:
+        if self._closed or not self.settings.usable:
+            return False
+        config = self._config
+        if config is None:
+            return True  # First calls before the config arrives: the server still applies every rule.
+        if config.get("killSwitch") is True:
+            return False
+        minimum = (config.get("minClient") or {}).get("python") if isinstance(config.get("minClient"), dict) else None
+        if not client_at_least(__version__, minimum):
+            return False
+        policies = self._policies_for(project) or []
+        return any(stricter_mode(self.settings.mode, p.get("mode")) != "off" for p in policies)
+
+    def send_param_values(self, project: str) -> bool:
+        if not self.settings.send_param_values:
+            return False
+        policies = self._policies_for(project)
+        # Off if any policy that may cover the project says off.
+        return all(p.get("sendParamValues") is not False for p in policies or [])
+
+    def ttl_cap_s(self) -> float:
+        value = _positive_number((self._config or {}).get("decisionTtlSeconds"))
+        return value if value is not None else DEFAULT_TTL_S
+
+    # -- decide ----------------------------------------------------------------------------
+    def decide(self, cache_key: str, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        self.start()
+        return self.cache.get_or_fetch(cache_key, lambda: self._decide_call(request), self.ttl_cap_s(), wait_s=0.5)
+
+    def _decide_call(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        if not self.breaker.allow():
+            return None
+        reply = self.transport.request_with_deadline("POST", "/v1/decide", request)
+        ok = reply is not None and reply.status == 200 and isinstance(reply.body, dict)
+        self.breaker.record(ok)
+        if not ok:
+            logger.debug("slashpeak decide skipped", extra={"code": "timeout" if reply is None else f"http_{reply.status}"})
+            return None
+        return reply.body
+
+    # -- events ----------------------------------------------------------------------------
+    def emit(self, event: Dict[str, Any]) -> None:
+        if not event.get("decisionId") or self._closed:
+            return
+        self.start()
+        try:
+            self._events.put_nowait(event)
+        except queue.Full:
+            pass  # Bounded: events are best effort and never slow a job.
+
+    def _drain(self, limit: int) -> List[Dict[str, Any]]:
+        batch: List[Dict[str, Any]] = []
+        while len(batch) < limit:
+            try:
+                batch.append(self._events.get_nowait())
+            except queue.Empty:
+                break
+        return batch
+
+    def _send_events(self, batch: List[Dict[str, Any]], timeout: Tuple[float, float]) -> None:
+        if not batch:
+            return
+        try:
+            self.transport.request("POST", "/v1/events", {"events": batch}, timeout=timeout)
+        except Exception:  # noqa: BLE001
+            logger.debug("slashpeak events dropped", extra={"code": "network", "count": len(batch)})
+
+    def _event_loop(self) -> None:
+        while not self._stop.wait(EVENT_INTERVAL_S):
+            while True:
+                batch = self._drain(EVENT_BATCH)
+                self._send_events(batch, (2.0, 5.0))
+                if len(batch) < EVENT_BATCH:
+                    break
+
+    def flush_events(self, deadline_s: float = EXIT_FLUSH_S) -> None:
+        end = time.monotonic() + deadline_s
+        while time.monotonic() < end:
+            batch = self._drain(EVENT_BATCH)
+            if not batch:
+                return
+            left = max(0.05, end - time.monotonic())
+            self._send_events(batch, (min(0.5, left), left))
+
+
+_EXIT_HOOKED = False
+
+
+def register_exit(router_getter: Callable[[], Optional[Router]]) -> None:
+    """Flush events for at most 1 s at interpreter exit."""
+    global _EXIT_HOOKED
+    if _EXIT_HOOKED:
+        return
+    _EXIT_HOOKED = True
+
+    def _on_exit() -> None:
+        router = router_getter()
+        if router is not None:
+            router.close()
+
+    atexit.register(_on_exit)

slashpeak/_core/runtime.py

@@ -0,0 +1,69 @@
+"""The one router per process, shared by every warehouse hook.
+
+A process that uses BigQuery and Snowflake keeps one key, one connection pool,
+one config poll and one event queue.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Callable, List, Optional, Set
+
+from slashpeak._core.router import Router, register_exit
+from slashpeak._core.settings import Settings, load_settings
+
+_lock = threading.Lock()
+_router: Optional[Router] = None
+_users: Set[str] = set()
+_fork_callbacks: List[Callable[[], None]] = []
+_fork_hooked = False
+
+
+def current() -> Optional[Router]:
+    return _router
+
+
+def _after_fork_in_child() -> None:
+    global _lock
+    # A lock held by another thread at fork time stays locked in the child: rebuild every one.
+    _lock = threading.Lock()
+    for callback in list(_fork_callbacks):
+        callback()
+    router = _router
+    if router is not None:
+        router.after_fork_in_child()
+
+
+def on_fork(callback: Callable[[], None]) -> None:
+    """Runs ``callback`` in a forked child, before the router resets."""
+    if callback not in _fork_callbacks:
+        _fork_callbacks.append(callback)
+
+
+def acquire(user: str, settings: Optional[Settings] = None) -> Router:
+    """The process router for one hook (``bigquery``, …). New settings replace the router."""
+    global _router, _fork_hooked
+    with _lock:
+        # Same settings from a second hook keep the router (one pool, one poll, one queue).
+        if _router is None or (settings is not None and settings != _router.settings):
+            if _router is not None:
+                _router.close(flush_s=0.0)
+            _router = Router(settings or load_settings())
+            register_exit(current)
+        if not _fork_hooked and hasattr(os, "register_at_fork"):
+            os.register_at_fork(after_in_child=_after_fork_in_child)
+            _fork_hooked = True
+        _users.add(user)
+        return _router
+
+
+def release(user: str) -> None:
+    """Closes the router (flushing events, at most 1 s) when its last hook goes."""
+    global _router
+    with _lock:
+        _users.discard(user)
+        if _users or _router is None:
+            return
+        router, _router = _router, None
+    router.close()

slashpeak/_core/settings.py

@@ -0,0 +1,61 @@
+"""SDK settings, read once from the environment (or passed to ``install``)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping, Optional
+from urllib.parse import urlsplit
+
+MODES = ("off", "shadow", "active")
+DEFAULT_ENDPOINT = "https://router.slashpeak.com"
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_key: Optional[str]
+    endpoint: str = DEFAULT_ENDPOINT
+    #: The SDK's own ceiling. The stricter of this and the server's mode wins.
+    mode: str = "active"
+    #: Send query parameter values (masked first). Off if the SDK or the server says off.
+    send_param_values: bool = True
+
+    @property
+    def usable(self) -> bool:
+        """A key, a mode other than off, and an endpoint the key may be sent to."""
+        return bool(self.api_key) and self.mode != "off" and endpoint_is_safe(self.endpoint)
+
+
+def endpoint_is_safe(endpoint: str) -> bool:
+    """HTTPS only. Plain HTTP is allowed for a local test server, never for a remote host."""
+    try:
+        parts = urlsplit(endpoint)
+    except ValueError:
+        return False
+    if parts.scheme == "https" and parts.hostname:
+        return True
+    return parts.scheme == "http" and (parts.hostname or "") in _LOCAL_HOSTS
+
+
+def _flag(value: Optional[str], default: bool) -> bool:
+    if value is None or value.strip() == "":
+        return default
+    return value.strip().lower() not in ("0", "false", "off", "no")
+
+
+def load_settings(env: Mapping[str, str] = os.environ) -> Settings:
+    mode = (env.get("SLASHPEAK_MODE") or "active").strip().lower()
+    return Settings(
+        api_key=(env.get("SLASHPEAK_API_KEY") or "").strip() or None,
+        endpoint=(env.get("SLASHPEAK_ENDPOINT") or DEFAULT_ENDPOINT).strip().rstrip("/"),
+        # An unknown mode is a typo: do nothing rather than guess.
+        mode=mode if mode in MODES else "off",
+        send_param_values=_flag(env.get("SLASHPEAK_SEND_PARAM_VALUES"), True),
+    )
+
+
+def stricter_mode(a: Optional[str], b: Optional[str]) -> str:
+    """off < shadow < active; an unknown value counts as off."""
+    rank = {mode: i for i, mode in enumerate(MODES)}
+    return MODES[min(rank.get(a or "off", 0), rank.get(b or "off", 0))]