flagsmith-common 2.2.4__py3-none-any.whl

common/core/__init__.py

@@ -0,0 +1,6 @@
+import enum
+
+
+class ReplicaReadStrategy(enum.StrEnum):
+    DISTRIBUTED = enum.auto()
+    SEQUENTIAL = enum.auto()

common/core/app.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class CoreConfig(AppConfig):
+    name = "common.core"
+    label = "common_core"

common/core/cli/healthcheck.py

@@ -0,0 +1,120 @@
+import argparse
+import socket
+import urllib.parse
+
+import requests
+
+DEFAULT_PORT = 8000
+DEFAULT_TIMEOUT_SECONDS = 1
+
+
+def get_args(
+    argv: list[str],
+    *,
+    prog: str,
+) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Perform health checks. "
+            f"If ran without subcommand, defaults to a TCP check of port {DEFAULT_PORT}."
+        ),
+        prog=prog,
+    )
+    subcommands = parser.add_subparsers(dest="subcommand")
+    tcp_parser = subcommands.add_parser(
+        "tcp",
+        help="Check if the API is able to accept local TCP connections",
+    )
+    tcp_parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        default=DEFAULT_PORT,
+        help=f"Port to check the API on (default: {DEFAULT_PORT})",
+    )
+    tcp_parser.add_argument(
+        "--timeout",
+        "-t",
+        type=int,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help=f"Socket timeout for the connection attempt in seconds (default: {DEFAULT_TIMEOUT_SECONDS})",
+    )
+    http_parser = subcommands.add_parser(
+        "http", help="Check if the API is able to serve HTTP requests"
+    )
+    http_parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        default=DEFAULT_PORT,
+        help=f"Port to check the API on (default: {DEFAULT_PORT})",
+    )
+    http_parser.add_argument(
+        "--timeout",
+        "-t",
+        type=int,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help=f"Request timeout in seconds (default: {DEFAULT_TIMEOUT_SECONDS})",
+    )
+    http_parser.add_argument(
+        "path",
+        nargs="?",
+        type=str,
+        default="/health/liveness",
+        help="Request path (default: /health/liveness)",
+    )
+    return parser.parse_args(argv)
+
+
+def check_tcp_connection(
+    port: int,
+    timeout_seconds: int,
+) -> None:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(timeout_seconds)
+    try:
+        sock.connect(("127.0.0.1", port))
+    except socket.error as e:
+        print(f"Failed: {e} {port=}")
+        exit(1)
+    else:
+        exit(0)
+    finally:
+        sock.close()
+
+
+def check_http_response(
+    port: int,
+    timeout_seconds: int,
+    path: str,
+) -> None:
+    url = urllib.parse.urljoin(f"http://127.0.0.1:{port}", path)
+    requests.get(
+        url,
+        timeout=timeout_seconds,
+    ).raise_for_status()
+
+
+def main(
+    argv: list[str],
+    *,
+    prog: str,
+) -> None:
+    args = get_args(argv, prog=prog)
+    match args.subcommand:
+        case None:
+            check_tcp_connection(
+                port=DEFAULT_PORT,
+                timeout_seconds=DEFAULT_TIMEOUT_SECONDS,
+            )
+        case "tcp":
+            check_tcp_connection(
+                port=args.port,
+                timeout_seconds=args.timeout,
+            )
+        case "http":
+            check_http_response(
+                port=args.port,
+                timeout_seconds=args.timeout,
+                path=args.path,
+            )

common/core/logging.py

@@ -0,0 +1,24 @@
+import json
+import logging
+from typing import Any
+
+
+class JsonFormatter(logging.Formatter):
+    """Custom formatter for json logs."""
+
+    def get_json_record(self, record: logging.LogRecord) -> dict[str, Any]:
+        formatted_message = record.getMessage()
+        json_record = {
+            "levelname": record.levelname,
+            "message": formatted_message,
+            "timestamp": self.formatTime(record, self.datefmt),
+            "logger_name": record.name,
+            "pid": record.process,
+            "thread_name": record.threadName,
+        }
+        if record.exc_info:
+            json_record["exc_info"] = self.formatException(record.exc_info)
+        return json_record
+
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps(self.get_json_record(record))

common/core/main.py

@@ -0,0 +1,105 @@
+import contextlib
+import logging
+import os
+import sys
+import typing
+
+from django.core.management import (
+    execute_from_command_line as django_execute_from_command_line,
+)
+from environs import Env
+
+from common.core.cli import healthcheck
+from common.core.utils import TemporaryDirectory
+
+logger = logging.getLogger(__name__)
+
+
+@contextlib.contextmanager
+def ensure_cli_env() -> typing.Generator[None, None, None]:
+    """
+    Set up the environment for the main entry point of the application
+    and clean up after it's done.
+
+    Add environment-related code that needs to happen before and after Django is involved
+    to here.
+
+    Use as a context manager, e.g.:
+
+    ```python
+    with ensure_cli_env():
+        main()
+    ```
+    """
+    env = Env()
+    ctx = contextlib.ExitStack()
+
+    # TODO @khvn26 Move logging setup to here
+
+    # Currently we don't install Flagsmith modules as a package, so we need to add
+    # $CWD to the Python path to be able to import them
+    sys.path.append(os.getcwd())
+
+    # TODO @khvn26 We should find a better way to pre-set the Django settings module
+    # without resorting to it being set outside of the application
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.dev")
+
+    # Set up Prometheus' multiprocess mode
+    if not env.str("PROMETHEUS_MULTIPROC_DIR", ""):
+        delete = not env.bool("PROMETHEUS_MULTIPROC_DIR_KEEP", False)
+        prometheus_multiproc_dir_name = ctx.enter_context(
+            TemporaryDirectory(delete=delete)
+        )
+        logger.info(
+            "Created %s for Prometheus multi-process mode",
+            prometheus_multiproc_dir_name,
+        )
+        os.environ["PROMETHEUS_MULTIPROC_DIR"] = prometheus_multiproc_dir_name
+
+    if "docgen" in sys.argv:
+        os.environ["DOCGEN_MODE"] = "true"
+
+    if "task-processor" in sys.argv:
+        # A hacky way to signal we're not running the API
+        os.environ["RUN_BY_PROCESSOR"] = "true"
+
+    with ctx:
+        yield
+
+
+def execute_from_command_line(argv: list[str]) -> None:
+    try:
+        subcommand = argv[1]
+        subcommand_main = {
+            "healthcheck": healthcheck.main,
+            # Backwards compatibility for task-processor health checks
+            # See https://github.com/Flagsmith/flagsmith-task-processor/issues/24
+            "checktaskprocessorthreadhealth": healthcheck.main,
+        }[subcommand]
+    except (IndexError, KeyError):
+        django_execute_from_command_line(argv)
+    else:
+        subcommand_main(
+            argv[2:],
+            prog=f"{os.path.basename(argv[0])} {subcommand}",
+        )
+
+
+def main(argv: list[str] = sys.argv) -> None:
+    """
+    The main entry point to the Flagsmith application.
+
+    An equivalent to Django's `manage.py` script, this module is used to run management commands.
+
+    It's installed as the `flagsmith` command.
+
+    Everything that needs to be run before Django is started should be done here.
+
+    The end goal is to eventually replace Core API's `run-docker.sh` with this.
+
+    Usage:
+    `flagsmith <command> [options]`
+    """
+    with ensure_cli_env():
+        # Run own commands and Django
+        execute_from_command_line(argv)

common/core/management/commands/docgen.py

@@ -0,0 +1,63 @@
+from operator import itemgetter
+from typing import Any, Callable
+
+import prometheus_client
+from django.core.management import BaseCommand, CommandParser
+from django.template.loader import get_template
+from django.utils.module_loading import autodiscover_modules
+from prometheus_client.metrics import MetricWrapperBase
+
+
+class Command(BaseCommand):
+    help = "Generate documentation for the Flagsmith codebase."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        subparsers = parser.add_subparsers(
+            title="sub-commands",
+            required=True,
+        )
+
+        metric_parser = subparsers.add_parser(
+            "metrics",
+            help="Generate metrics documentation.",
+        )
+        metric_parser.set_defaults(handle_method=self.handle_metrics)
+
+    def initialise(self) -> None:
+        from common.gunicorn import metrics  # noqa: F401
+
+        autodiscover_modules(
+            "metrics",
+        )
+
+    def handle(
+        self,
+        *args: Any,
+        handle_method: Callable[..., None],
+        **options: Any,
+    ) -> None:
+        self.initialise()
+        handle_method(*args, **options)
+
+    def handle_metrics(self, *args: Any, **options: Any) -> None:
+        template = get_template("docgen-metrics.md")
+
+        flagsmith_metrics = sorted(
+            (
+                {
+                    "name": collector._name,
+                    "documentation": collector._documentation,
+                    "labels": collector._labelnames,
+                    "type": collector._type,
+                }
+                for collector in prometheus_client.REGISTRY._collector_to_names
+                if isinstance(collector, MetricWrapperBase)
+            ),
+            key=itemgetter("name"),
+        )
+
+        self.stdout.write(
+            template.render(
+                context={"flagsmith_metrics": flagsmith_metrics},
+            )
+        )

common/core/management/commands/start.py

@@ -0,0 +1,61 @@
+from typing import Any, Callable
+
+from django.core.management import BaseCommand, CommandParser
+from django.utils.module_loading import autodiscover_modules
+
+from common.gunicorn.utils import add_arguments as add_gunicorn_arguments
+from common.gunicorn.utils import run_server
+from task_processor.utils import add_arguments as add_task_processor_arguments
+from task_processor.utils import start_task_processor
+
+
+class Command(BaseCommand):
+    help = "Start the Flagsmith application."
+
+    def create_parser(self, *args: Any, **kwargs: Any) -> CommandParser:
+        return super().create_parser(*args, conflict_handler="resolve", **kwargs)
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        add_gunicorn_arguments(parser)
+
+        subparsers = parser.add_subparsers(
+            title="sub-commands",
+            required=True,
+        )
+
+        api_parser = subparsers.add_parser(
+            "api",
+            help="Start the Core API.",
+        )
+        api_parser.set_defaults(handle_method=self.handle_api)
+
+        task_processor_parser = subparsers.add_parser(
+            "task-processor",
+            help="Start the Task Processor.",
+        )
+        task_processor_parser.set_defaults(handle_method=self.handle_task_processor)
+        add_task_processor_arguments(task_processor_parser)
+
+    def initialise(self) -> None:
+        autodiscover_modules(
+            "metrics",
+            "tasks",
+        )
+
+    def handle(
+        self,
+        *args: Any,
+        handle_method: Callable[..., None],
+        **options: Any,
+    ) -> None:
+        self.initialise()
+        handle_method(*args, **options)
+
+    def handle_api(self, *args: Any, **options: Any) -> None:
+        run_server(options)
+
+    def handle_task_processor(self, *args: Any, **options: Any) -> None:
+        with start_task_processor(options):
+            # Delegate signal handling to Gunicorn.
+            # The task processor will finalise once Gunicorn is shut down.
+            run_server(options)

common/core/management/commands/waitfordb.py

@@ -0,0 +1,87 @@
+import logging
+import time
+from argparse import ArgumentParser
+from typing import Any
+
+from django.core.management import BaseCommand, CommandError
+from django.db import OperationalError, connections
+from django.db.migrations.executor import MigrationExecutor
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        parser.add_argument(
+            "--waitfor",
+            type=int,
+            dest="wait_for",
+            help="Number of seconds to wait for db to become available.",
+            default=5,
+        )
+        parser.add_argument(
+            "--migrations",
+            action="store_true",
+            dest="should_wait_for_migrations",
+            help="Whether to wait until all migrations are applied.",
+            default=False,
+        )
+        parser.add_argument(
+            "--database",
+            type=str,
+            dest="database",
+            help=(
+                'The database to wait for ("default", "analytics").'
+                'Defaults to the "default" database.'
+            ),
+            default="default",
+        )
+
+    def handle(
+        self,
+        *args: Any,
+        wait_for: int,
+        should_wait_for_migrations: bool,
+        database: str,
+        **options: Any,
+    ) -> None:
+        start = time.monotonic()
+        wait_between_checks = 0.25
+
+        logger.info("Checking if database is ready for connections.")
+
+        while True:
+            if time.monotonic() - start > wait_for:
+                msg = f"Failed to connect to DB within {wait_for} seconds."
+                logger.error(msg)
+                raise CommandError(msg)
+
+            conn = connections.create_connection(database)
+            try:
+                with conn.temporary_connection() as cursor:
+                    cursor.execute("SELECT 1")
+                logger.info("Successfully connected to the database.")
+                break
+            except OperationalError as e:
+                logger.warning("Database not yet ready for connections.")
+                logger.warning("Error was: %s: %s", e.__class__.__name__, e)
+
+            time.sleep(wait_between_checks)
+
+        if should_wait_for_migrations:
+            logger.info("Checking for applied migrations.")
+
+            while True:
+                if time.monotonic() - start > wait_for:
+                    msg = f"Didn't detect applied migrations for {wait_for} seconds."
+                    logger.error(msg)
+                    raise CommandError(msg)
+
+                conn = connections[database]
+                executor = MigrationExecutor(conn)
+                if not executor.migration_plan(executor.loader.graph.leaf_nodes()):
+                    logger.info("No pending migrations detected, good to go.")
+                    return
+
+                logger.warning("Migrations not yet applied.")
+                time.sleep(wait_between_checks)

common/core/metrics.py

@@ -0,0 +1,25 @@
+import prometheus_client
+from django.conf import settings
+
+from common.core.utils import get_version_info
+
+flagsmith_build_info = prometheus_client.Gauge(
+    "flagsmith_build_info",
+    "Flagsmith version and build information.",
+    ["ci_commit_sha", "version"],
+    multiprocess_mode="livemax",
+)
+
+
+def advertise() -> None:
+    # Advertise Flagsmith build info.
+    version_info = get_version_info()
+
+    flagsmith_build_info.labels(
+        ci_commit_sha=version_info["ci_commit_sha"],
+        version=version_info.get("package_versions", {}).get(".") or "unknown",
+    ).set(1)
+
+
+if not settings.DOCGEN_MODE:
+    advertise()

common/core/middleware.py

@@ -0,0 +1,22 @@
+from typing import Callable
+
+from django.http import HttpRequest, HttpResponse
+
+from common.core.utils import get_version
+
+
+class APIResponseVersionHeaderMiddleware:
+    """
+    Middleware to add the API version to the response headers
+    """
+
+    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)
+        response.headers["Flagsmith-Version"] = get_version()
+        return response

common/core/templates/docgen-metrics.md

@@ -0,0 +1,22 @@
+---
+title: Metrics
+sidebar_label: Metrics
+sidebar_position: 20
+---
+
+## Prometheus
+
+To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`. 
+
+The metrics provided by Flagsmith are described below.
+
+{% for metric in flagsmith_metrics %}
+### `{{ metric.name }}`
+
+{{ metric.type|title }}.
+
+{{ metric.documentation }}
+
+Labels:
+{% for label in metric.labels %} - `{{ label }}`
+{% endfor %}{% endfor %}

common/core/urls.py

@@ -0,0 +1,17 @@
+from django.conf import settings
+from django.urls import include, path, re_path
+
+from common.core import views
+
+urlpatterns = [
+    path("version/", views.version_info),
+    path("health/liveness/", views.liveness),
+    path("health/readiness/", include("health_check.urls", namespace="health")),
+    re_path(r"^health", include("health_check.urls", namespace="health-deprecated")),
+    # Aptible health checks must be on /healthcheck and cannot redirect
+    # see https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks
+    re_path(r"^healthcheck", include("health_check.urls", namespace="health-aptible")),
+]
+
+if settings.PROMETHEUS_ENABLED:
+    urlpatterns += [path("metrics/", views.metrics)]