configdirector-server-sdk 0.2.0__py3-none-any.whl

configdirector/__init__.py

@@ -0,0 +1,83 @@
+"""ConfigDirector Python server SDK.
+
+ConfigDirector is a remote configuration and feature flag service.
+
+Example::
+
+    from configdirector import Context, Metadata, create_client
+
+    client = create_client(
+        "YOUR-SERVER-SDK-KEY",
+        metadata=Metadata(app_name="my-awesome-app", app_version="1.0.0"),
+    )
+    client.initialize()
+
+    if client.get_value("new-checkout", False, Context(id="user-123")):
+        ...
+"""
+
+from ._version import __version__
+from .client import create_client
+from .errors import (
+    ConfigDirectorConnectionError,
+    ConfigDirectorError,
+    ConfigDirectorInitializationError,
+    ConfigDirectorTypeError,
+    ConfigDirectorValidationError,
+)
+from .types import (
+    ClientEvent,
+    ClientHooks,
+    ClientReadyEvent,
+    ClientReadyHandler,
+    ConfigDirectorClient,
+    ConfigDirectorLogger,
+    ConfigEvaluatedEvent,
+    ConfigEvaluatedHandler,
+    ConfigEvaluation,
+    ConfigState,
+    ConfigsUpdatedEvent,
+    ConfigsUpdatedHandler,
+    ConfigType,
+    ConfigValue,
+    ConnectionMode,
+    ConnectionOptions,
+    Context,
+    EvaluationReason,
+    Metadata,
+    Subscription,
+    TelemetryOptions,
+    WatchHandler,
+)
+
+__all__ = [
+    "ClientEvent",
+    "ClientHooks",
+    "ClientReadyEvent",
+    "ClientReadyHandler",
+    "ConfigDirectorClient",
+    "ConfigDirectorConnectionError",
+    "ConfigDirectorError",
+    "ConfigDirectorInitializationError",
+    "ConfigDirectorLogger",
+    "ConfigDirectorTypeError",
+    "ConfigDirectorValidationError",
+    "ConfigEvaluatedEvent",
+    "ConfigEvaluatedHandler",
+    "ConfigEvaluation",
+    "ConfigState",
+    "ConfigType",
+    "ConfigValue",
+    "ConfigsUpdatedEvent",
+    "ConfigsUpdatedHandler",
+    "ConnectionMode",
+    "ConnectionOptions",
+    "Context",
+    "EvaluationReason",
+    "Metadata",
+    "Subscription",
+    "TelemetryOptions",
+    "WatchHandler",
+    "__version__",
+    "create_client",
+]

configdirector/_bundle.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+
+from ._evaluation._json_value import to_json_string
+from ._evaluation.types import (
+    Condition,
+    ConditionalRule,
+    Config,
+    EnumTypeConstraints,
+    NumericTypeConstraints,
+    Percentage,
+    PercentageRule,
+    Rule,
+    RuleValue,
+    TargetingRules,
+    Variation,
+)
+from .types import ConfigDirectorLogger, ConfigType
+
+__all__ = ["BundleKind", "ConfigBundle", "parse_bundle"]
+
+BundleKind = Literal["full", "delta"]
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigBundle:
+    configs: dict[str, Config] = field(default_factory=dict)
+    kind: BundleKind = "full"
+    environment_id: str | None = None
+    project_id: str | None = None
+    # Echoed back on the next poll so the server can answer with a delta. The server may omit
+    # it, in which case every poll returns a full bundle.
+    timestamp: str | None = None
+
+
+def parse_bundle(payload: str, logger: ConfigDirectorLogger) -> ConfigBundle:
+    document = json.loads(payload)
+    if not isinstance(document, dict):
+        raise ValueError(f"Expected the config bundle to be a JSON object, got {type(document).__name__}")
+
+    return ConfigBundle(
+        configs=_parse_configs(document.get("configs"), logger),
+        kind="delta" if document.get("kind") == "delta" else "full",
+        environment_id=_optional_string(document.get("environmentId")),
+        project_id=_optional_string(document.get("projectId")),
+        timestamp=_optional_string(document.get("timestamp")),
+    )
+
+
+def _parse_configs(raw: Any, logger: ConfigDirectorLogger) -> dict[str, Config]:
+    if not isinstance(raw, dict):
+        return {}
+
+    configs: dict[str, Config] = {}
+    for key, definition in raw.items():
+        try:
+            configs[str(key)] = _parse_config(definition)
+        except (AttributeError, KeyError, TypeError, ValueError) as error:
+            # One unreadable config must not cost the application every other config in the
+            # bundle. It keeps whatever definition it already had, or falls back to defaults.
+            logger.warning("Skipping the config %r, its definition could not be read: %r", key, error)
+    return configs
+
+
+def _parse_config(raw: Any) -> Config:
+    target = raw["target"]
+    return Config(
+        id=str(raw["id"]),
+        key=str(raw["key"]),
+        type=cast(ConfigType, raw["type"]),
+        target=TargetingRules(
+            default_value=_as_string(target.get("defaultValue")),
+            rules=[_parse_rule(rule) for rule in target.get("rules") or []],
+            default_value_id=_optional_string(target.get("defaultValueId")),
+        ),
+        variations=[_parse_variation(variation) for variation in raw.get("variations") or []],
+        type_constraints=_parse_type_constraints(raw.get("typeConstraints")),
+    )
+
+
+def _parse_rule(raw: Any) -> Rule:
+    kind = raw.get("type")
+    percentages = [_parse_percentage(percentage) for percentage in raw.get("percentages") or []]
+
+    if kind == "percentage":
+        return PercentageRule(
+            id=str(raw["id"]),
+            order=_optional_int(raw.get("order")),
+            percentages=percentages,
+        )
+
+    # Anything that is not a percentage rule is carried as a conditional rule with its wire type
+    # intact. A rule kind this SDK version predates is then skipped during evaluation rather than
+    # discarded here, which keeps the reason for the skip visible in one place.
+    return ConditionalRule(
+        id=str(raw["id"]),
+        order=_optional_int(raw.get("order")),
+        value=_rule_value(raw.get("value")),
+        conditions=[_parse_condition(condition) for condition in raw.get("conditions") or []],
+        percentages=percentages,
+        target=str(raw.get("target") or "value"),
+        type=str(kind) if kind is not None else "conditional",
+        value_id=_optional_string(raw.get("valueId")),
+    )
+
+
+def _parse_condition(raw: Any) -> Condition:
+    return Condition(
+        id=str(raw["id"]),
+        attribute=str(raw["attribute"]),
+        operator=str(raw["operator"]),
+        target_type=str(raw["targetType"]),
+        target_values=[_as_string(value) for value in raw.get("targetValues") or []],
+        trait=_optional_string(raw.get("trait")),
+    )
+
+
+def _parse_percentage(raw: Any) -> Percentage:
+    return Percentage(
+        id=str(raw["id"]),
+        percentage=float(raw["percentage"]),
+        value=_rule_value(raw.get("value")),
+        value_id=_optional_string(raw.get("valueId")),
+    )
+
+
+def _parse_variation(raw: Any) -> Variation:
+    value = raw.get("value")
+    return Variation(
+        value=value if isinstance(value, (str, int, float, bool)) else _as_string(value),
+        name=_optional_string(raw.get("name")),
+    )
+
+
+def _parse_type_constraints(raw: Any) -> NumericTypeConstraints | EnumTypeConstraints | None:
+    if not isinstance(raw, dict):
+        return None
+    if "valueType" in raw:
+        return EnumTypeConstraints(
+            value_type="number" if raw.get("valueType") == "number" else "string",
+            values=[_as_string(value) for value in raw.get("values") or []],
+        )
+    return NumericTypeConstraints(min=raw.get("min"), max=raw.get("max"))
+
+
+def _rule_value(value: Any) -> RuleValue:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    # A structured value reaches the application as the JSON text it was sent as.
+    return json.dumps(value, separators=(",", ":"))
+
+
+def _as_string(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return ""
+    if isinstance(value, (int, float, bool)):
+        # Rendered the way every other ConfigDirector SDK renders it, so that a rule written
+        # against `true` or `26` compares the same everywhere.
+        return to_json_string(value)
+    return json.dumps(value, separators=(",", ":"))
+
+
+def _optional_string(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _optional_int(value: Any) -> int | None:
+    # Rules without a usable order evaluate last, in the order the server sent them.
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return int(value)

configdirector/_evaluation/__init__.py

@@ -0,0 +1,47 @@
+from .array_comparison import compare_array
+from .condition_evaluator import evaluate_condition
+from .config_evaluator import ConfigEvaluator
+from .date_comparison import compare_date
+from .numeric_comparison import compare_numeric
+from .percent_hashing import assign_percentage
+from .semver_comparison import compare_semver
+from .text_comparison import compare_text
+from .types import (
+    Condition,
+    ConditionalRule,
+    Config,
+    EnumTypeConstraints,
+    EvaluationContext,
+    NumericTypeConstraints,
+    Percentage,
+    PercentageRule,
+    Rule,
+    Target,
+    TargetingRules,
+    TargetType,
+    Variation,
+)
+
+__all__ = [
+    "Condition",
+    "ConditionalRule",
+    "Config",
+    "ConfigEvaluator",
+    "EnumTypeConstraints",
+    "EvaluationContext",
+    "NumericTypeConstraints",
+    "Percentage",
+    "PercentageRule",
+    "Rule",
+    "Target",
+    "TargetType",
+    "TargetingRules",
+    "Variation",
+    "assign_percentage",
+    "compare_array",
+    "compare_date",
+    "compare_numeric",
+    "compare_semver",
+    "compare_text",
+    "evaluate_condition",
+]

configdirector/_evaluation/_json_pointer.py

@@ -0,0 +1,40 @@
+"""Minimal RFC 6901 JSON Pointer resolution, used to read nested context traits."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["find_by_pointer"]
+
+_MISSING = object()
+
+
+def find_by_pointer(pointer: str, document: Any) -> Any:
+    if not pointer.startswith("/"):
+        # Includes the empty pointer, which RFC 6901 defines as the whole document. Callers
+        # treat an empty trait path as "no trait", so it never reaches here.
+        return None
+
+    current = document
+    for raw_token in pointer[1:].split("/"):
+        # Unescape in this order: ~1 before ~0, so that "~01" resolves to "~1" and not "/".
+        token = raw_token.replace("~1", "/").replace("~0", "~")
+        current = _step(current, token)
+        if current is _MISSING:
+            return None
+    return current
+
+
+def _step(current: Any, token: str) -> Any:
+    if isinstance(current, dict):
+        return current.get(token, _MISSING)
+    if isinstance(current, (list, tuple)):
+        try:
+            index = int(token)
+        except ValueError:
+            return _MISSING
+        # RFC 6901 array indexes are unsigned; Python's negative indexing must not leak in.
+        if index < 0 or index >= len(current):
+            return _MISSING
+        return current[index]
+    return _MISSING

configdirector/_evaluation/_json_value.py

@@ -0,0 +1,28 @@
+"""Rendering config values to strings the way the other ConfigDirector SDKs do.
+
+Config values arrive as JSON and are handed back to the client as strings, so a boolean must
+render as ``true`` rather than Python's ``True``, and a whole number as ``26`` rather than
+``26.0``. Getting this wrong would make the same config resolve to different text depending on
+which SDK read it.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+__all__ = ["to_json_string"]
+
+
+def to_json_string(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "NaN"
+        if math.isinf(value):
+            return "Infinity" if value > 0 else "-Infinity"
+        # JSON numbers have no int/float distinction, so 26.0 must render as "26".
+        if value.is_integer() and abs(value) < 1e21:
+            return str(int(value))
+    return str(value)

configdirector/_evaluation/_rapidhash.py

@@ -0,0 +1,115 @@
+"""A pure-Python port of rapidhash v3.0 ("fast" variant).
+
+Percentage rollouts bucket users by hashing, so every ConfigDirector SDK must produce the exact
+same 64-bit value for the same input or the same user would land in different buckets depending
+on which SDK evaluated the config.
+
+Do not "clean up" the arithmetic here. Every mask and shift is load-bearing.
+"""
+
+from __future__ import annotations
+
+__all__ = ["rapidhash"]
+
+_MASK64 = 0xFFFFFFFFFFFFFFFF
+
+_SECRET = (
+    0x2D358DCCAA6C78A5,
+    0x8BB84B93962EACC9,
+    0x4B33A62ED433D4A3,
+    0x4D5A2DA51DE1AA47,
+    0xA0761D6478BD642F,
+    0xE7037ED1A0B428DB,
+    0x90ED1765281C388C,
+    0xAAAAAAAAAAAAAAAA,
+)
+
+
+def _mix(a: int, b: int) -> int:
+    m = a * b
+    return (m & _MASK64) ^ (m >> 64)
+
+
+def _read64(data: bytes, offset: int) -> int:
+    return int.from_bytes(data[offset : offset + 8], "little")
+
+
+def _read32(data: bytes, offset: int) -> int:
+    return int.from_bytes(data[offset : offset + 4], "little")
+
+
+def _read_small(data: bytes, length: int) -> int:
+    v = data[0]
+    return data[length - 1] | (((v << 5) & 0xFF) << 40) | ((v >> 3) << 48)
+
+
+def _epilogue(a: int, b: int, i: int) -> int:
+    m0 = a * b
+    m1 = ((m0 & _MASK64) ^ _SECRET[7]) * (((m0 >> 64) ^ _SECRET[1] ^ i) & _MASK64)
+    return (m1 & _MASK64) ^ (m1 >> 64)
+
+
+def rapidhash(data: bytes, seed: int = 0) -> int:
+    length = len(data)
+    seed ^= _mix(seed ^ _SECRET[2], _SECRET[1])
+    i = length
+
+    if length <= 16:
+        bi = length
+        if length >= 4:
+            seed ^= length
+            if length >= 8:
+                a = _read64(data, 0)
+                b = _read64(data, length - 8)
+            else:
+                a = _read32(data, 0)
+                b = _read32(data, length - 4)
+        elif length > 0:
+            a = _read_small(data, length)
+            b = data[length >> 1]
+        else:
+            a = 0
+            b = 0
+    else:
+        p = 0
+        if i > 112:
+            see1 = see2 = see3 = see4 = see5 = see6 = seed
+            while True:
+                seed = _mix(_read64(data, p) ^ _SECRET[0], _read64(data, p + 8) ^ seed)
+                see1 = _mix(_read64(data, p + 16) ^ _SECRET[1], _read64(data, p + 24) ^ see1)
+                see2 = _mix(_read64(data, p + 32) ^ _SECRET[2], _read64(data, p + 40) ^ see2)
+                see3 = _mix(_read64(data, p + 48) ^ _SECRET[3], _read64(data, p + 56) ^ see3)
+                see4 = _mix(_read64(data, p + 64) ^ _SECRET[4], _read64(data, p + 72) ^ see4)
+                see5 = _mix(_read64(data, p + 80) ^ _SECRET[5], _read64(data, p + 88) ^ see5)
+                see6 = _mix(_read64(data, p + 96) ^ _SECRET[6], _read64(data, p + 104) ^ see6)
+                p += 112
+                i -= 112
+                if i <= 112:
+                    break
+            seed ^= see1
+            see2 ^= see3
+            see4 ^= see5
+            seed ^= see6
+            see2 ^= see4
+            seed ^= see2
+
+        bi = i
+        if i > 16:
+            seed = _mix(_read64(data, p) ^ _SECRET[2], _read64(data, p + 8) ^ seed)
+            if i > 32:
+                seed = _mix(_read64(data, p + 16) ^ _SECRET[2], _read64(data, p + 24) ^ seed)
+                if i > 48:
+                    seed = _mix(_read64(data, p + 32) ^ _SECRET[1], _read64(data, p + 40) ^ seed)
+                    if i > 64:
+                        seed = _mix(_read64(data, p + 48) ^ _SECRET[1], _read64(data, p + 56) ^ seed)
+                        if i > 80:
+                            seed = _mix(_read64(data, p + 64) ^ _SECRET[2], _read64(data, p + 72) ^ seed)
+                            if i > 96:
+                                seed = _mix(_read64(data, p + 80) ^ _SECRET[1], _read64(data, p + 88) ^ seed)
+
+        a = _read64(data, p + i - 16) ^ bi
+        b = _read64(data, p + i - 8)
+
+    a ^= _SECRET[1]
+    b ^= seed
+    return _epilogue(a, b, bi)

configdirector/_evaluation/array_comparison.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._json_value import to_json_string
+
+__all__ = ["compare_array"]
+
+
+def compare_array(value: Any, operator: str, target_values: list[str]) -> bool:
+    lowercase_operator = operator.lower()
+    if not isinstance(value, list):
+        return lowercase_operator == "does not contain any of"
+
+    # Nested arrays, objects, and nulls have no text form, so they are dropped rather than
+    # matching an empty target value.
+    elements = [to_json_string(item) for item in value if isinstance(item, (str, int, float, bool))]
+
+    match lowercase_operator:
+        case "contains any of":
+            return any(element in target_values for element in elements)
+        case "does not contain any of":
+            return not any(element in target_values for element in elements)
+        case _:
+            return False

configdirector/_evaluation/condition_evaluator.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import Context, Metadata
+from ._json_pointer import find_by_pointer
+from ._json_value import to_json_string
+from .array_comparison import compare_array
+from .date_comparison import compare_date
+from .numeric_comparison import compare_numeric
+from .semver_comparison import compare_semver
+from .text_comparison import compare_text
+from .types import Condition, EvaluationContext
+
+__all__ = ["evaluate_condition"]
+
+# The context does not carry this attribute. It is compared as "" rather than skipped, so that a
+# negative operator such as "does NOT equal" can still match.
+_ABSENT = object()
+
+# The condition names an attribute this SDK version does not know about. Unlike an absent value,
+# it is not compared at all — there is no sensible thing to compare.
+_UNKNOWN_ATTRIBUTE = object()
+
+_EMPTY_CONTEXT = Context()
+_EMPTY_METADATA = Metadata()
+
+
+def evaluate_condition(condition: Condition, context: EvaluationContext | None = None) -> bool:
+    value = _resolve(condition, context)
+    if value is _UNKNOWN_ATTRIBUTE:
+        return False
+
+    targets = condition.target_values or []
+
+    match condition.target_type:
+        case "text":
+            return compare_text(_render(value), condition.operator, targets)
+        case "number":
+            return compare_numeric(_unwrap(value), condition.operator, targets)
+        case "datetime":
+            return compare_date(_render(value), condition.operator, targets)
+        case "semver":
+            return compare_semver(_render(value), condition.operator, targets)
+        case "array":
+            return compare_array(_unwrap(value), condition.operator, targets)
+        case _:
+            return False
+
+
+def _resolve(condition: Condition, context: EvaluationContext | None) -> Any:
+    match condition.attribute:
+        case "identifier":
+            return _or_absent(_context_of(context).id)
+        case "name":
+            return _or_absent(_context_of(context).name)
+        case "appName":
+            return _or_absent(_metadata_of(context).app_name)
+        case "appVersion":
+            return _or_absent(_metadata_of(context).app_version)
+        case "traits":
+            if not condition.trait:
+                return _ABSENT
+            return _or_absent(find_by_pointer(condition.trait, _context_of(context).traits))
+        case _:
+            return _UNKNOWN_ATTRIBUTE
+
+
+def _context_of(context: EvaluationContext | None) -> Context:
+    if context is None or context.context is None:
+        return _EMPTY_CONTEXT
+    return context.context
+
+
+def _metadata_of(context: EvaluationContext | None) -> Metadata:
+    if context is None or context.metadata is None:
+        return _EMPTY_METADATA
+    return context.metadata
+
+
+def _or_absent(value: Any) -> Any:
+    return _ABSENT if value is None else value
+
+
+def _unwrap(value: Any) -> Any:
+    return None if value is _ABSENT else value
+
+
+def _render(value: Any) -> str:
+    if value is _ABSENT or value is None:
+        return ""
+    if isinstance(value, (str, int, float, bool)):
+        return to_json_string(value)
+    return ""  # arrays and objects