flagsmith-common 2.2.4__py3-none-any.whl

common/core/utils.py

@@ -0,0 +1,239 @@
+import json
+import logging
+import pathlib
+import random
+import sys
+import tempfile
+from functools import lru_cache
+from itertools import cycle
+from typing import (
+    TYPE_CHECKING,
+    Iterator,
+    Literal,
+    NotRequired,
+    TypedDict,
+    TypeVar,
+    get_args,
+)
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.db import connections
+from django.db.utils import OperationalError
+
+from common.core import ReplicaReadStrategy
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import AbstractBaseUser
+    from django.db.models.base import Model
+    from django.db.models.manager import Manager
+
+
+logger = logging.getLogger(__name__)
+
+UNKNOWN = "unknown"
+VERSIONS_INFO_FILE_LOCATION = ".versions.json"
+
+ManagerType = TypeVar("ManagerType", bound="Manager[Model]")
+
+ReplicaNamePrefix = Literal["replica_", "cross_region_replica_"]
+_replica_sequential_names_by_prefix: dict[ReplicaNamePrefix, Iterator[str]] = {}
+
+
+class SelfHostedData(TypedDict):
+    has_users: bool
+    has_logins: bool
+
+
+VersionManifest = TypedDict(
+    "VersionManifest",
+    {
+        ".": str,  # This key is used to store the version of the package itself
+    },
+)
+
+
+class VersionInfo(TypedDict):
+    ci_commit_sha: str
+    image_tag: str
+    has_email_provider: bool
+    is_enterprise: bool
+    is_saas: bool
+    self_hosted_data: SelfHostedData | None
+    package_versions: NotRequired[VersionManifest]
+
+
+@lru_cache()
+def is_enterprise() -> bool:
+    return pathlib.Path("./ENTERPRISE_VERSION").exists()
+
+
+@lru_cache()
+def is_saas() -> bool:
+    return pathlib.Path("./SAAS_DEPLOYMENT").exists()
+
+
+def is_oss() -> bool:
+    return not (is_enterprise() or is_saas())
+
+
+@lru_cache()
+def has_email_provider() -> bool:
+    match settings.EMAIL_BACKEND:
+        case "django.core.mail.backends.smtp.EmailBackend":
+            return settings.EMAIL_HOST_USER is not None
+        case "sgbackend.SendGridBackend":
+            return settings.SENDGRID_API_KEY is not None
+        case "django_ses.SESBackend":
+            return settings.AWS_SES_REGION_ENDPOINT is not None
+        case _:
+            return False
+
+
+def get_version_info() -> VersionInfo:
+    """Returns the version information for the current deployment"""
+    _is_saas = is_saas()
+    version_json: VersionInfo = {
+        "ci_commit_sha": get_file_contents("./CI_COMMIT_SHA") or UNKNOWN,
+        "image_tag": UNKNOWN,
+        "has_email_provider": has_email_provider(),
+        "is_enterprise": is_enterprise(),
+        "is_saas": _is_saas,
+        "self_hosted_data": None,
+    }
+
+    manifest_versions = get_versions_from_manifest()
+    version_json["package_versions"] = manifest_versions
+    version_json["image_tag"] = manifest_versions["."]
+
+    if not _is_saas:
+        user_objects: "Manager[AbstractBaseUser]" = getattr(get_user_model(), "objects")
+
+        version_json["self_hosted_data"] = {
+            "has_users": user_objects.exists(),
+            "has_logins": user_objects.filter(last_login__isnull=False).exists(),
+        }
+
+    return version_json
+
+
+def get_version() -> str:
+    """Return the version number of the current deployment"""
+    manifest_versions = get_versions_from_manifest()
+    return manifest_versions.get(".", UNKNOWN)
+
+
+@lru_cache()
+def get_versions_from_manifest() -> VersionManifest:
+    """Read the version info from the manifest file"""
+    raw_content = get_file_contents(VERSIONS_INFO_FILE_LOCATION)
+    if not raw_content:
+        return {".": UNKNOWN}
+
+    manifest: VersionManifest = json.loads(raw_content)
+    return manifest
+
+
+@lru_cache()
+def get_file_contents(file_path: str) -> str | None:
+    """Attempts to read a file from the filesystem and return the contents"""
+    try:
+        with open(file_path) as f:
+            return f.read().replace("\n", "")
+    except FileNotFoundError:
+        return None
+
+
+@lru_cache()
+def is_database_replica_setup() -> bool:
+    """Checks if any database replica is set up"""
+    return any(
+        name for name in connections if name.startswith(get_args(ReplicaNamePrefix))
+    )
+
+
+def using_database_replica(
+    manager: ManagerType,
+    replica_prefix: ReplicaNamePrefix = "replica_",
+) -> ManagerType:
+    """Attempts to bind a manager to a healthy database replica"""
+    local_replicas = [name for name in connections if name.startswith(replica_prefix)]
+
+    if not local_replicas:
+        logger.info("No replicas set up.")
+        return manager
+
+    chosen_replica = None
+
+    if settings.REPLICA_READ_STRATEGY == ReplicaReadStrategy.SEQUENTIAL:
+        sequence = _replica_sequential_names_by_prefix.setdefault(
+            replica_prefix, cycle(local_replicas)
+        )
+        for _ in range(len(local_replicas)):
+            attempted_replica = next(sequence)
+            try:
+                connections[attempted_replica].ensure_connection()
+                chosen_replica = attempted_replica
+                break
+            except OperationalError:
+                logger.exception(f"Replica '{attempted_replica}' is not available.")
+                continue
+
+    if settings.REPLICA_READ_STRATEGY == ReplicaReadStrategy.DISTRIBUTED:
+        for _ in range(len(local_replicas)):
+            attempted_replica = random.choice(local_replicas)
+            try:
+                connections[attempted_replica].ensure_connection()
+                chosen_replica = attempted_replica
+                break
+            except OperationalError:
+                logger.exception(f"Replica '{attempted_replica}' is not available.")
+                local_replicas.remove(attempted_replica)
+                continue
+
+    if not chosen_replica:
+        if replica_prefix == "replica_":
+            logger.warning("Falling back to cross-region replicas, if any.")
+            return using_database_replica(manager, "cross_region_replica_")
+
+        logger.warning("No replicas available.")
+        return manager
+
+    return manager.db_manager(chosen_replica)
+
+
+if sys.version_info >= (3, 12):
+    # Already has the desired behavior; re-export for uniform imports.
+    TemporaryDirectory = tempfile.TemporaryDirectory
+else:
+    import contextlib
+    from typing import ContextManager, Generator
+
+    def TemporaryDirectory(
+        suffix: str | None = None,
+        prefix: str | None = None,
+        dir: str | None = None,
+        *,
+        delete: bool = True,
+    ) -> ContextManager[str]:
+        """
+        Create a temporary directory with optional cleanup control.
+
+        This wrapper exists because Python 3.12 changed TemporaryDirectory's behavior
+        by adding a 'delete' parameter, which doesn't exist in Python 3.11. This
+        function provides a consistent API across both versions.
+
+        When delete=True, uses the stdlib's TemporaryDirectory (auto-cleanup).
+        When delete=False, creates a directory with mkdtemp that persists after
+        the context manager exits, matching Python 3.12's delete=False behavior.
+
+        See https://docs.python.org/3.12/library/tempfile.html#tempfile.TemporaryDirectory for usage details.
+        """
+        if delete:
+            return tempfile.TemporaryDirectory(suffix, prefix, dir)
+
+        @contextlib.contextmanager
+        def _tmpdir() -> Generator[str, None, None]:
+            yield tempfile.mkdtemp(suffix, prefix, dir)
+
+        return _tmpdir()

common/core/views.py

@@ -0,0 +1,27 @@
+import logging
+
+import prometheus_client
+from django.http import HttpResponse, JsonResponse
+from rest_framework.request import Request
+
+from common.core import utils
+from common.prometheus.utils import get_registry
+
+logger = logging.getLogger(__name__)
+
+
+def liveness(request: Request) -> JsonResponse:
+    return JsonResponse({"status": "ok"})
+
+
+def version_info(request: Request) -> JsonResponse:
+    return JsonResponse(utils.get_version_info())
+
+
+def metrics(request: Request) -> HttpResponse:
+    registry = get_registry()
+    metrics_page = prometheus_client.generate_latest(registry)
+    return HttpResponse(
+        metrics_page,
+        content_type=prometheus_client.CONTENT_TYPE_LATEST,
+    )

common/environments/permissions.py

@@ -0,0 +1,15 @@
+# Maintain a list of permissions here
+VIEW_ENVIRONMENT = "VIEW_ENVIRONMENT"
+UPDATE_FEATURE_STATE = "UPDATE_FEATURE_STATE"
+MANAGE_IDENTITIES = "MANAGE_IDENTITIES"
+VIEW_IDENTITIES = "VIEW_IDENTITIES"
+CREATE_CHANGE_REQUEST = "CREATE_CHANGE_REQUEST"
+APPROVE_CHANGE_REQUEST = "APPROVE_CHANGE_REQUEST"
+MANAGE_SEGMENT_OVERRIDES = "MANAGE_SEGMENT_OVERRIDES"
+
+TAG_SUPPORTED_PERMISSIONS = [
+    UPDATE_FEATURE_STATE,
+    CREATE_CHANGE_REQUEST,
+    APPROVE_CHANGE_REQUEST,
+    MANAGE_SEGMENT_OVERRIDES,
+]

common/features/multivariate/serializers.py

@@ -0,0 +1,19 @@
+import typing
+
+from django.apps import apps
+from rest_framework import serializers
+
+if typing.TYPE_CHECKING:
+    from common.types import MultivariateFeatureStateValue  # noqa: F401
+
+
+class MultivariateFeatureStateValueSerializer(
+    serializers.ModelSerializer["MultivariateFeatureStateValue"]
+):
+    class Meta:
+        model = apps.get_model("multivariate", "MultivariateFeatureStateValue")
+        fields = (
+            "id",
+            "multivariate_feature_option",
+            "percentage_allocation",
+        )

common/features/serializers.py

@@ -0,0 +1,68 @@
+import typing
+
+from django.apps import apps
+from drf_writable_nested.serializers import WritableNestedModelSerializer
+from rest_framework import serializers
+
+from common.features.multivariate.serializers import (
+    MultivariateFeatureStateValueSerializer,
+)
+
+if typing.TYPE_CHECKING:
+    from common.types import FeatureSegment, FeatureStateValue  # noqa: F401
+
+
+class FeatureStateValueSerializer(serializers.ModelSerializer["FeatureStateValue"]):
+    class Meta:
+        model = apps.get_model("features", "FeatureStateValue")
+        fields = ("type", "string_value", "integer_value", "boolean_value")
+
+
+class CreateSegmentOverrideFeatureSegmentSerializer(
+    serializers.ModelSerializer["FeatureSegment"]
+):
+    class Meta:
+        model = apps.get_model("features", "FeatureSegment")
+        fields = ("id", "segment", "priority", "uuid")
+
+
+class CreateSegmentOverrideFeatureStateSerializer(WritableNestedModelSerializer):
+    feature_state_value = FeatureStateValueSerializer()
+    feature_segment = CreateSegmentOverrideFeatureSegmentSerializer(
+        required=False, allow_null=True
+    )
+    multivariate_feature_state_values = MultivariateFeatureStateValueSerializer(
+        many=True, required=False
+    )
+
+    class Meta:
+        model = apps.get_model("features", "FeatureState")
+        fields = (
+            "id",
+            "feature",
+            "enabled",
+            "feature_state_value",
+            "feature_segment",
+            "deleted_at",
+            "uuid",
+            "created_at",
+            "updated_at",
+            "live_from",
+            "environment",
+            "identity",
+            "change_request",
+            "multivariate_feature_state_values",
+        )
+
+        read_only_fields = (
+            "id",
+            "deleted_at",
+            "uuid",
+            "created_at",
+            "updated_at",
+            "live_from",
+            "environment",
+            "identity",
+            "change_request",
+            "feature",
+        )

common/features/versioning/serializers.py

@@ -0,0 +1,13 @@
+from common.features.serializers import (
+    CreateSegmentOverrideFeatureStateSerializer,
+)
+
+
+class EnvironmentFeatureVersionFeatureStateSerializer(
+    CreateSegmentOverrideFeatureStateSerializer
+):
+    class Meta(CreateSegmentOverrideFeatureStateSerializer.Meta):
+        read_only_fields = (
+            CreateSegmentOverrideFeatureStateSerializer.Meta.read_only_fields
+            + ("feature",)  # type: ignore[assignment]
+        )

common/gunicorn/conf.py

@@ -0,0 +1,18 @@
+"""
+This module is used as a default configuration file for Gunicorn.
+
+It is used to correctly support Prometheus metrics in a multi-process environment.
+"""
+
+import typing
+
+from prometheus_client.multiprocess import mark_process_dead
+
+if typing.TYPE_CHECKING:  # pragma: no cover
+    from gunicorn.arbiter import Arbiter  # type: ignore[import-untyped]
+    from gunicorn.workers.base import Worker  # type: ignore[import-untyped]
+
+
+def worker_exit(server: "Arbiter", worker: "Worker") -> None:
+    """Detach the process Prometheus metrics collector when a worker exits."""
+    mark_process_dead(worker.pid)  # type: ignore[no-untyped-call]

common/gunicorn/constants.py

@@ -0,0 +1,23 @@
+import re
+
+WSGI_EXTRA_PREFIX = "flagsmith."
+WSGI_EXTRA_SUFFIX_TO_CATEGORY = {
+    "i": "request_headers",
+    "o": "response_headers",
+    "e": "environ_variables",
+}
+HTTP_SERVER_RESPONSE_SIZE_DEFAULT_BUCKETS = (
+    # 1 kB, 10 kB, 100 kB, 500 kB, 1 MB, 5 MB, 10 MB
+    1 * 1024,
+    10 * 1024,
+    100 * 1024,
+    500 * 1024,
+    1 * 1024 * 1024,
+    5 * 1024 * 1024,
+    10 * 1024 * 1024,
+    float("inf"),
+)
+
+wsgi_extra_key_regex = re.compile(
+    r"^{(?P<key>[^}]+)}(?P<suffix>[%s])$" % "".join(WSGI_EXTRA_SUFFIX_TO_CATEGORY)
+)

common/gunicorn/logging.py

@@ -0,0 +1,120 @@
+import logging
+import sys
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+from gunicorn.config import Config  # type: ignore[import-untyped]
+from gunicorn.http.message import Request  # type: ignore[import-untyped]
+from gunicorn.http.wsgi import Response  # type: ignore[import-untyped]
+from gunicorn.instrument.statsd import (  # type: ignore[import-untyped]
+    Statsd as StatsdGunicornLogger,
+)
+
+from common.core.logging import JsonFormatter
+from common.gunicorn import metrics
+from common.gunicorn.constants import (
+    WSGI_EXTRA_PREFIX,
+    WSGI_EXTRA_SUFFIX_TO_CATEGORY,
+    wsgi_extra_key_regex,
+)
+from common.gunicorn.utils import get_extra
+
+
+class GunicornAccessLogJsonFormatter(JsonFormatter):
+    def _get_extra(self, record_args: dict[str, Any]) -> dict[str, Any]:
+        ret: dict[str, dict[str, Any]] = {}
+
+        extra_items_to_log: list[str] | None
+        if extra_items_to_log := getattr(settings, "ACCESS_LOG_EXTRA_ITEMS", None):
+            # We expect the extra items to be in the form of
+            # Gunicorn's access log format string for
+            # request headers, response headers and environ variables
+            # without the % prefix, e.g. "{origin}i" or "{flagsmith.environment_id}e"
+            # https://docs.gunicorn.org/en/stable/settings.html#access-log-format
+            for extra_key in extra_items_to_log:
+                extra_key_lower = extra_key.lower()
+                if (
+                    (extra_value := record_args.get(extra_key_lower))
+                    and (re_match := wsgi_extra_key_regex.match(extra_key_lower))
+                    and (
+                        extra_category := WSGI_EXTRA_SUFFIX_TO_CATEGORY.get(
+                            re_match.group("suffix")
+                        )
+                    )
+                ):
+                    ret.setdefault(extra_category, {})[re_match.group("key")] = (
+                        extra_value
+                    )
+
+        return ret
+
+    def get_json_record(self, record: logging.LogRecord) -> dict[str, Any]:
+        args = record.args
+
+        if TYPE_CHECKING:
+            assert isinstance(args, dict)
+
+        url = args["U"]
+        if q := args["q"]:
+            url += f"?{q}"
+
+        return {
+            **super().get_json_record(record),
+            "time": datetime.strptime(args["t"], "[%d/%b/%Y:%H:%M:%S %z]").isoformat(),
+            "path": url,
+            "remote_ip": args["h"],
+            "route": args.get(f"{{{WSGI_EXTRA_PREFIX}route}}e") or "",
+            "method": args["m"],
+            "status": str(args["s"]),
+            "user_agent": args["a"],
+            "duration_in_ms": args["M"],
+            "response_size_in_bytes": args["B"] or 0,
+            **self._get_extra(args),
+        }
+
+
+class PrometheusGunicornLogger(StatsdGunicornLogger):  # type: ignore[misc]
+    def access(
+        self,
+        resp: Response,
+        req: Request,
+        environ: dict[str, Any],
+        request_time: timedelta,
+    ) -> None:
+        super().access(resp, req, environ, request_time)
+        duration_seconds = (
+            request_time.seconds + float(request_time.microseconds) / 10**6
+        )
+        labels = {
+            # To avoid cardinality explosion, we use a resolved Django route
+            # instead of raw path.
+            # The Django route is set by `RouteLoggerMiddleware`.
+            "route": get_extra(environ=environ, key="route") or "",
+            "method": environ.get("REQUEST_METHOD") or "",
+            "response_status": resp.status_code,
+        }
+        metrics.flagsmith_http_server_request_duration_seconds.labels(**labels).observe(
+            duration_seconds
+        )
+        metrics.flagsmith_http_server_requests_total.labels(**labels).inc()
+        metrics.flagsmith_http_server_response_size_bytes.labels(**labels).observe(
+            getattr(resp, "sent", 0),
+        )
+
+
+class GunicornJsonCapableLogger(PrometheusGunicornLogger):
+    def setup(self, cfg: Config) -> None:
+        super().setup(cfg)
+        if getattr(settings, "LOG_FORMAT", None) == "json":
+            self._set_handler(
+                self.error_log,
+                cfg.errorlog,
+                JsonFormatter(),
+            )
+            self._set_handler(
+                self.access_log,
+                cfg.accesslog,
+                GunicornAccessLogJsonFormatter(),
+                stream=sys.stdout,
+            )

common/gunicorn/metrics.py

@@ -0,0 +1,26 @@
+import prometheus_client
+from django.conf import settings
+
+from common.gunicorn.constants import HTTP_SERVER_RESPONSE_SIZE_DEFAULT_BUCKETS
+from common.prometheus import Histogram
+
+flagsmith_http_server_requests_total = prometheus_client.Counter(
+    "flagsmith_http_server_requests_total",
+    "Total number of HTTP requests.",
+    ["route", "method", "response_status"],
+)
+flagsmith_http_server_request_duration_seconds = Histogram(
+    "flagsmith_http_server_request_duration_seconds",
+    "HTTP request duration in seconds.",
+    ["route", "method", "response_status"],
+)
+flagsmith_http_server_response_size_bytes = Histogram(
+    "flagsmith_http_server_response_size_bytes",
+    "HTTP response size in bytes.",
+    ["route", "method", "response_status"],
+    buckets=getattr(
+        settings,
+        "PROMETHEUS_HTTP_SERVER_RESPONSE_SIZE_HISTOGRAM_BUCKETS",
+        HTTP_SERVER_RESPONSE_SIZE_DEFAULT_BUCKETS,
+    ),
+)

common/gunicorn/middleware.py

@@ -0,0 +1,30 @@
+from typing import Callable
+
+from django.http import HttpRequest, HttpResponse
+
+from common.gunicorn.utils import get_route_template, log_extra
+
+
+class RouteLoggerMiddleware:
+    """
+    Make the resolved Django route available to the WSGI server
+    (e.g. Gunicorn) for logging purposes.
+    """
+
+    def __init__(
+        self,
+        get_response: Callable[[HttpRequest], HttpResponse],
+    ) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        response = self.get_response(request)
+
+        if resolver_match := request.resolver_match:
+            log_extra(
+                request=request,
+                key="route",
+                value=get_route_template(resolver_match.route),
+            )
+
+        return response