flagsmith-common 3.2.1__tar.gz → 3.3.0__tar.gz

{flagsmith_common-3.2.1 → flagsmith_common-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-common
-Version: 3.2.1
+Version: 3.3.0
 Summary: Flagsmith's common library
 Author: Matthew Elwell, Gagan Trivedi, Kim Gustyr, Zach Aysan, Francesco Lo Franco, Rodrigo López Dato, Evandro Myller, Wadii Zaim
 License-Expression: BSD-3-Clause
@@ -21,6 +21,7 @@ Requires-Dist: prometheus-client>=0.0.16 ; extra == 'common-core'
 Requires-Dist: psycopg2-binary>=2.9,<3 ; extra == 'common-core'
 Requires-Dist: requests ; extra == 'common-core'
 Requires-Dist: simplejson>=3,<4 ; extra == 'common-core'
+Requires-Dist: simplejson ; extra == 'flagsmith-schemas'
 Requires-Dist: typing-extensions ; extra == 'flagsmith-schemas'
 Requires-Dist: flagsmith-flag-engine>6 ; extra == 'flagsmith-schemas'
 Requires-Dist: backoff>=2.2.1,<3.0.0 ; extra == 'task-processor'

{flagsmith_common-3.2.1 → flagsmith_common-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flagsmith-common"
-version = "3.2.1"
+version = "3.3.0"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = []
@@ -26,6 +26,7 @@ optional-dependencies = { test-tools = [
     "django-health-check",
     "prometheus-client (>=0.0.16)",
 ], flagsmith-schemas = [
+    "simplejson",
     "typing_extensions",
     "flagsmith-flag-engine>6",
 ] }

{flagsmith_common-3.2.1 → flagsmith_common-3.3.0}/src/common/core/templates/docgen-metrics.md

@@ -6,7 +6,9 @@ sidebar_position: 20
 
 ## Prometheus
 
-To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`. 
+To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`.
+
+When enabled, Flagsmith serves the `/metrics` endpoint on port 9100.
 
 The metrics provided by Flagsmith are described below.
 

{flagsmith_common-3.2.1 → flagsmith_common-3.3.0}/src/common/gunicorn/conf.py

@@ -4,6 +4,7 @@ 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 os
 import typing
 
 from prometheus_client.multiprocess import mark_process_dead
@@ -13,6 +14,15 @@ if typing.TYPE_CHECKING:  # pragma: no cover
     from gunicorn.workers.base import Worker  # type: ignore[import-untyped]
 
 
-def worker_exit(server: "Arbiter", worker: "Worker") -> None:
+def when_ready(server: "Arbiter") -> None:
+    """Start the standalone Prometheus metrics server after Gunicorn is ready."""
+    prometheus_enabled = os.getenv("PROMETHEUS_ENABLED", "")
+    if prometheus_enabled.lower() == "true":  # Django settings are not available
+        from common.gunicorn.metrics_server import start_metrics_server
+
+        start_metrics_server()
+
+
+def child_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]

flagsmith_common-3.3.0/src/common/gunicorn/metrics_server.py

@@ -0,0 +1,65 @@
+"""
+Standalone Prometheus metrics HTTP server.
+
+This module provides a separate HTTP server for Prometheus metrics,
+independent of the main Gunicorn application server. This improves
+metrics reliability under high API load.
+
+The server runs in a daemon thread and serves metrics from the shared
+PROMETHEUS_MULTIPROC_DIR directory.
+"""
+
+import logging
+import os
+import threading
+
+from prometheus_client import CollectorRegistry, start_http_server
+from prometheus_client.multiprocess import MultiProcessCollector
+
+logger = logging.getLogger(__name__)
+
+METRICS_SERVER_PORT = 9100
+
+_server_started = False
+_server_lock = threading.Lock()
+
+
+def get_multiprocess_registry() -> CollectorRegistry:
+    """Create a registry configured for multiprocess metric collection."""
+    registry = CollectorRegistry()
+    MultiProcessCollector(registry)  # type: ignore[no-untyped-call]
+    return registry
+
+
+def start_metrics_server(
+    port: int = METRICS_SERVER_PORT,
+) -> None:
+    """
+    Start the standalone Prometheus metrics HTTP server.
+
+    This function is idempotent - calling it multiple times will only
+    start one server. The server runs in a daemon thread.
+
+    Args:
+        port: The port to serve metrics on. Defaults to 9100.
+    """
+    global _server_started
+
+    with _server_lock:
+        if _server_started:
+            logger.debug("Metrics server already started")
+            return
+
+        prometheus_multiproc_dir = os.environ.get("PROMETHEUS_MULTIPROC_DIR")
+        if not prometheus_multiproc_dir:
+            logger.warning("PROMETHEUS_MULTIPROC_DIR not set, skipping metrics server")
+            return
+
+        registry = get_multiprocess_registry()
+
+        try:
+            start_http_server(port=port, registry=registry)
+            _server_started = True
+            logger.info("Prometheus metrics server started on port %d", port)
+        except OSError as e:
+            logger.error("Failed to start metrics server on port %d: %s", port, e)

{flagsmith_common-3.2.1 → flagsmith_common-3.3.0}/src/flagsmith_schemas/dynamodb.py

@@ -20,6 +20,7 @@ from flagsmith_schemas.types import (
     DynamoFloat,
     DynamoInt,
     FeatureType,
+    JsonGzipped,
     UUIDStr,
 )
 
@@ -200,7 +201,7 @@ class Webhook(TypedDict):
     """Secret used to sign webhook payloads."""
 
 
-class _EnvironmentFields(TypedDict):
+class _EnvironmentBaseFields(TypedDict):
     """Common fields for Environment documents."""
 
     name: NotRequired[str]
@@ -208,11 +209,6 @@ class _EnvironmentFields(TypedDict):
     updated_at: NotRequired[DateTimeStr | None]
     """Last updated timestamp. If not set, current timestamp should be assumed."""
 
-    project: Project
-    """Project-specific data for this environment."""
-    feature_states: list[FeatureState]
-    """List of feature states representing the environment defaults."""
-
     allow_client_traits: NotRequired[bool]
     """Whether the SDK API should allow clients to set traits for this environment. Identical to project-level's `persist_trait_data` setting. Defaults to `True`."""
     hide_sensitive_data: NotRequired[bool]
@@ -240,7 +236,52 @@ class _EnvironmentFields(TypedDict):
     """Webhook configuration."""
 
 
-### Root document schemas below. Indexed fields are marked as **INDEXED** in the docstrings. ###
+class _EnvironmentV1Fields(TypedDict):
+    """Common fields for environment documents in `flagsmith_environments`."""
+
+    api_key: str
+    """Public client-side API key for the environment. **INDEXED**."""
+    id: DynamoInt
+    """Unique identifier for the environment in Core."""
+
+
+class _EnvironmentV2MetaFields(TypedDict):
+    """Common fields for environment documents in `flagsmith_environments_v2`."""
+
+    environment_id: str
+    """Unique identifier for the environment in Core. Same as `Environment.id`, but string-typed to reduce coupling with Core's type definitions **INDEXED**."""
+    environment_api_key: str
+    """Public client-side API key for the environment. **INDEXED**."""
+    document_key: Literal["_META"]
+    """The fixed document key for the environment v2 document. Always `"_META"`. **INDEXED**."""
+
+    id: DynamoInt
+    """Unique identifier for the environment in Core. Exists for compatibility with the API environment document schema."""
+
+
+class _EnvironmentBaseFieldsUncompressed(TypedDict):
+    """Common fields for uncompressed environment documents."""
+
+    project: Project
+    """Project-specific data for this environment."""
+    feature_states: list[FeatureState]
+    """List of feature states representing the environment defaults."""
+    compressed: NotRequired[Literal[False]]
+    """Either `False` or absent to indicate the data is uncompressed."""
+
+
+class _EnvironmentBaseFieldsCompressed(TypedDict):
+    """Common fields for compressed environment documents."""
+
+    project: JsonGzipped[Project]
+    """Project-specific data for this environment. **COMPRESSED**."""
+    feature_states: JsonGzipped[list[FeatureState]]
+    """List of feature states representing the environment defaults. **COMPRESSED**."""
+    compressed: Literal[True]
+    """Always `True` to indicate the data is compressed."""
+
+
+### Root document schemas below. Indexed fields are marked as **INDEXED** in the docstrings. Compressed fields are marked as **COMPRESSED**. ###
 
 
 class EnvironmentAPIKey(TypedDict):
@@ -295,33 +336,50 @@ class Identity(TypedDict):
     """Unique identifier for the identity in Core. If identity created via Core's `edge-identities` API, this can be missing or `None`."""
 
 
-class Environment(_EnvironmentFields):
+class Environment(
+    _EnvironmentBaseFieldsUncompressed,
+    _EnvironmentV1Fields,
+    _EnvironmentBaseFields,
+):
     """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
 
     **DynamoDB table**: `flagsmith_environments`
     """
 
-    api_key: str
-    """Public client-side API key for the environment. **INDEXED**."""
-    id: DynamoInt
-    """Unique identifier for the environment in Core."""
 
+class EnvironmentCompressed(
+    _EnvironmentBaseFieldsCompressed,
+    _EnvironmentV1Fields,
+    _EnvironmentBaseFields,
+):
+    """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
+    Has compressed fields.
+
+    **DynamoDB table**: `flagsmith_environments`
+    """
 
-class EnvironmentV2Meta(_EnvironmentFields):
+
+class EnvironmentV2Meta(
+    _EnvironmentBaseFieldsUncompressed,
+    _EnvironmentV2MetaFields,
+    _EnvironmentBaseFields,
+):
     """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
 
     **DynamoDB table**: `flagsmith_environments_v2`
     """
 
-    environment_id: str
-    """Unique identifier for the environment in Core. Same as `Environment.id`, but string-typed to reduce coupling with Core's type definitions **INDEXED**."""
-    environment_api_key: str
-    """Public client-side API key for the environment. **INDEXED**."""
-    document_key: Literal["_META"]
-    """The fixed document key for the environment v2 document. Always `"_META"`. **INDEXED**."""
 
-    id: DynamoInt
-    """Unique identifier for the environment in Core. Exists for compatibility with the API environment document schema."""
+class EnvironmentV2MetaCompressed(
+    _EnvironmentBaseFieldsCompressed,
+    _EnvironmentV2MetaFields,
+    _EnvironmentBaseFields,
+):
+    """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
+    Has compressed fields.
+
+    **DynamoDB table**: `flagsmith_environments_v2`
+    """
 
 
 class EnvironmentV2IdentityOverride(TypedDict):

{flagsmith_common-3.2.1 → flagsmith_common-3.3.0}/src/flagsmith_schemas/types.py

@@ -1,10 +1,25 @@
 from decimal import Decimal
-from typing import TYPE_CHECKING, Annotated, Literal, TypeAlias
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Generic,
+    Literal,
+    SupportsBytes,
+    TypeAlias,
+    TypeVar,
+    get_args,
+)
 
 from flagsmith_schemas.constants import PYDANTIC_INSTALLED
 
 if PYDANTIC_INSTALLED:
-    from pydantic import WithJsonSchema
+    from pydantic import (
+        GetCoreSchemaHandler,
+        TypeAdapter,
+        WithJsonSchema,
+    )
+    from pydantic_core import core_schema
 
     from flagsmith_schemas.pydantic_types import (
         ValidateDecimalAsFloat,
@@ -13,6 +28,7 @@ if PYDANTIC_INSTALLED:
         ValidateStrAsISODateTime,
         ValidateStrAsUUID,
     )
+    from flagsmith_schemas.utils import json_gzip
 elif not TYPE_CHECKING:
     # This code runs at runtime when Pydantic is not installed.
     # We could use PEP 649 strings with `Annotated`, but Pydantic is inconsistent in how it parses them.
@@ -26,6 +42,39 @@ elif not TYPE_CHECKING:
     ValidateStrAsISODateTime = ...
     ValidateStrAsUUID = ...
 
+T = TypeVar("T")
+
+
+class DynamoBinary(SupportsBytes):
+    """boto3's wrapper type for bytes stored in DynamoDB."""
+
+    value: bytes | bytearray
+
+
+class JsonGzipped(DynamoBinary, Generic[T]):
+    """A gzipped JSON blob representing a value of type `T`."""
+
+    if PYDANTIC_INSTALLED:
+
+        @classmethod
+        def __get_pydantic_core_schema__(
+            cls,
+            source_type: "type[JsonGzipped[T]]",
+            handler: GetCoreSchemaHandler,
+        ) -> core_schema.CoreSchema:
+            _adapter: TypeAdapter[T] = TypeAdapter(get_args(source_type)[0])
+
+            def _validate_json_gzipped(data: Any) -> bytes:
+                return json_gzip(_adapter.validate_python(data))
+
+            # We're returning bytes here for two reasons:
+            # 1. boto3.dynamodb seems to expect bytes as input for Binary columns.
+            # 2. We want to avoid having boto3 as a dependency.
+            return core_schema.no_info_before_validator_function(
+                _validate_json_gzipped,
+                core_schema.bytes_schema(strict=False),
+            )
+
 
 DynamoInt: TypeAlias = Annotated[Decimal, ValidateDecimalAsInt]
 """An integer value stored in DynamoDB.

flagsmith_common-3.3.0/src/flagsmith_schemas/utils.py

@@ -0,0 +1,15 @@
+import gzip
+import typing
+
+import simplejson as json
+
+
+def json_gzip(value: typing.Any) -> bytes:
+    return gzip.compress(
+        json.dumps(
+            value,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("utf-8"),
+        mtime=0,
+    )