Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

7.0 KB
Raw Blame
"""
Facade API for endpoints.

This is the ONLY module (with its facade siblings) other apps are allowed
to import.

Responsibilities:
- Call internal logic and models
- Convert Django models to contracts before returning
- Remain thin and stable

Do NOT:
- Implement business logic here
- Return ORM instances or QuerySets

Wiring that core registers crosses the boundary through the dedicated
submodules instead: ``facade.tasks`` (celery beat), ``facade.temporal``
(data-modeling workflow hooks), ``facade.models`` (model-class consumers),
``facade.enums`` (exported constants).

The service surface the product's own presentation consumes (CRUD/execution/
materialization services, request validation, OpenAPI generation) is resolved
lazily via PEP 562 — those modules pull heavy dependencies (HogQL, query
runners) that must stay off the ``django.setup()`` path.
"""

import importlib
from datetime import datetime
from typing import TYPE_CHECKING

from products.endpoints.backend import rate_limit
from products.endpoints.backend.logic.rate_limit_signal import EndpointRateLimitReason, record_endpoint_rate_limited
from products.endpoints.backend.models import Endpoint, EndpointVersion

from . import contracts

if TYPE_CHECKING:
    from products.endpoints.backend.insight_transformers import transform_materialized_insight_response
    from products.endpoints.backend.logic.crud import EndpointCrudService
    from products.endpoints.backend.logic.execution import EndpointExecutionService
    from products.endpoints.backend.logic.materialization import (
        EndpointMaterializationService,
        build_materialization_info,
    )
    from products.endpoints.backend.logic.validation import (
        validate_bucket_overrides,
        validate_endpoint_request,
        validate_update_request,
    )
    from products.endpoints.backend.materialization_transforms import build_endpoint_hogql
    from products.endpoints.backend.openapi import generate_openapi_spec

# symbol -> source module (relative to products.endpoints.backend)
_LAZY = {
    "EndpointCrudService": "logic.crud",
    "EndpointExecutionService": "logic.execution",
    "EndpointMaterializationService": "logic.materialization",
    "build_materialization_info": "logic.materialization",
    "validate_bucket_overrides": "logic.validation",
    "validate_endpoint_request": "logic.validation",
    "validate_update_request": "logic.validation",
    "generate_openapi_spec": "openapi",
    # The insight-conversion seam. Product analytics owns the runners these two reach through
    # core's dispatcher, so its tests hold the cases that prove the conversion still works.
    "build_endpoint_hogql": "materialization_transforms",
    "transform_materialized_insight_response": "insight_transformers",
}


def __getattr__(name: str):
    try:
        module_path = _LAZY[name]
    except KeyError:
        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
    module = importlib.import_module(f"products.endpoints.backend.{module_path}")
    return getattr(module, name)


def _to_endpoint_info(endpoint: Endpoint) -> contracts.EndpointInfo:
    return contracts.EndpointInfo(
        id=endpoint.id,
        team_id=endpoint.team_id,
        name=endpoint.name,
        is_active=endpoint.is_active,
        current_version=endpoint.current_version,
        derived_from_insight=endpoint.derived_from_insight,
        created_at=endpoint.created_at,
        updated_at=endpoint.updated_at,
        last_executed_at=endpoint.last_executed_at,
    )


def _to_version_info(version: EndpointVersion) -> contracts.EndpointVersionInfo:
    return contracts.EndpointVersionInfo(
        id=version.id,
        endpoint_id=version.endpoint_id,
        version=version.version,
        query=version.query,
        description=version.description,
        data_freshness_seconds=version.data_freshness_seconds,
        is_active=version.is_active,
        is_materialized=version.is_materialized,
        created_at=version.created_at,
        last_executed_at=version.last_executed_at,
    )


def list_endpoints(team_id: int) -> list[contracts.EndpointInfo]:
    endpoints = Endpoint.objects.filter(team_id=team_id, deleted=False).order_by("name")
    return [_to_endpoint_info(e) for e in endpoints]


def get_endpoint(team_id: int, name: str) -> contracts.EndpointInfo | None:
    endpoint = Endpoint.objects.filter(team_id=team_id, name=name, deleted=False).first()
    return _to_endpoint_info(endpoint) if endpoint is not None else None


def get_endpoint_version(team_id: int, name: str, version: int | None = None) -> contracts.EndpointVersionInfo | None:
    """Get a specific version's snapshot, or the current version when ``version`` is None."""
    endpoint = Endpoint.objects.filter(team_id=team_id, name=name, deleted=False).first()
    if endpoint is None:
        return None
    try:
        return _to_version_info(endpoint.get_version(version))
    except EndpointVersion.DoesNotExist:
        return None


def get_last_execution_times(team_id: int, names: list[str]) -> list[tuple[str, datetime]]:
    """Most recent execution time per endpoint, for the endpoints that have one."""
    rows = Endpoint.objects.filter(team_id=team_id, name__in=names, last_executed_at__isnull=False).values_list(
        "name", "last_executed_at"
    )
    # The isnull=False filter already excludes None, but mypy can't narrow through queryset filters.
    return [(name, ts) for name, ts in rows if ts is not None]


def is_materialization_ready(team_id: int, endpoint_name: str, version: int | None = None) -> bool:
    """Whether the targeted version (current when ``version`` is None) is ready for materialized execution."""
    return rate_limit.check_materialization_ready(team_id, endpoint_name, version)


def is_materialized_request(team_id: int, endpoint_name: str, version: int | None, request_data: object) -> bool:
    """Whether this run request will be served from the targeted version's materialized table."""
    return rate_limit.check_materialized_request(team_id, endpoint_name, version, request_data)


def record_throttled_request(
    team_id: int | None, endpoint_name: str | None, version: int | None, *, materialized: bool, scope: str
) -> None:
    """Record a run request refused by a request-rate throttle."""
    reason = EndpointRateLimitReason.MATERIALIZED_RATE if materialized else EndpointRateLimitReason.INLINE_RATE
    record_endpoint_rate_limited(
        team_id=team_id, endpoint_name=endpoint_name, version=version, reason=reason, scope=scope
    )


__all__ = [
    "EndpointCrudService",
    "EndpointExecutionService",
    "EndpointMaterializationService",
    "build_endpoint_hogql",
    "build_materialization_info",
    "generate_openapi_spec",
    "get_endpoint",
    "get_endpoint_version",
    "get_last_execution_times",
    "is_materialization_ready",
    "is_materialized_request",
    "list_endpoints",
    "record_throttled_request",
    "transform_materialized_insight_response",
    "validate_bucket_overrides",
    "validate_endpoint_request",
    "validate_update_request",
]