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.

15.0 KB
Raw Blame
"""Tell the team when a model starts failing its checks.

Only the pass-to-fail edge notifies, and only for error-severity checks. A check that keeps failing
run after run is already known about; re-notifying every run is how an inbox gets ignored.
"""

from collections.abc import Sequence
from urllib.parse import quote
from uuid import UUID

import structlog

from posthog.hogql.database.database import unentitled_system_tables

from posthog.models import Team, User

from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.data_modeling.backend.facade import api as data_modeling_facade
from products.notifications.backend.facade.api import (
    NotificationData,
    NotificationType,
    Priority,
    RecipientsResolver,
    TargetType,
    create_notification,
)
from products.warehouse_sources.backend.facade import api as warehouse_facade

from ..facade.enums import CheckRunStatus, SubjectType
from ..models import DataQualityCheck, DataQualityCheckRun, DataQualitySuiteRun
from . import posthog_tables
from .checks import checks_for_subject
from .subject_access import (
    NoticeReferences,
    ReferenceGate,
    can_be_object_denied,
    notice_references,
    reference_gate,
    referenced_subject_names,
    referencing_check_types,
)
from .subjects import resolve_subject

LOGGER = structlog.get_logger(__name__)

_OBJECT_GATED_SUBJECT_TYPES = frozenset({SubjectType.TABLE, SubjectType.VIEW})


class _WarehouseSubjectResolver(RecipientsResolver):
    """Drop members who must not receive this check's warehouse metadata or its failing-row count.

    Three gates on top of the built-in resource-level `warehouse_objects` filter that
    `create_notification` runs:

    - **Object-level** access to *this* table or view. The resource-level filter only asks whether a
      member can see warehouse objects at all, so a member with general warehouse access but an
      explicit denial on the subject would still receive its name, column, check type, and count.
    - **Referenced-subject** access. A `relationships` check reads a second subject and a `custom_sql`
      check reads arbitrary tables, so a failure count is an oracle over those too. A member denied
      any of the names passed in must be dropped, matching how the run-history API gates them.
    - **Query** viewer access. The body's `failed_row_count` is a count oracle over the underlying
      warehouse rows that the run-history API gates behind query access, so a member denied `query`
      must not read it from the notification either.
    """

    def __init__(
        self,
        team: Team,
        subject_type: str,
        subject_uuid: str,
        referenced_names: list[str] | None = None,
        executed_references: Sequence[dict[str, str]] = (),
        references_unknown: bool = False,
        access_cache: dict[int, UserAccessControl] | None = None,
    ) -> None:
        self._team = team
        self._subject_type = subject_type
        self._subject_uuid = subject_uuid
        self._referenced_names = referenced_names or []
        self._executed_references = executed_references
        self._references_unknown = references_unknown
        # One access-control object per member, reused across both gates below (and the warehouse
        # database build the referenced-subject gate runs) so a single failing check doesn't rebuild
        # it -- and its membership, role, and access-control lookups -- once per pass.
        self._access: dict[int, UserAccessControl] = access_cache if access_cache is not None else {}
        self._references: NoticeReferences | None = None
        self._unentitled: frozenset[str] | None = None

    def _access_of(self, user: User) -> UserAccessControl:
        access = self._access.get(user.id)
        if access is None:
            access = UserAccessControl(user, self._team)
            self._access[user.id] = access
        return access

    def _access_controls_supported(self, user_ids: list[int]) -> bool:
        # When access controls aren't available for the org, the built-in filter lets everyone
        # through and neither gate below can deny anyone; the callers skip their per-member work.
        sample = User.objects.filter(id__in=user_ids).first()
        return sample is not None and self._access_of(sample).access_controls_supported

    def resolve(self, target_type: TargetType, target_id: str, team_id: int | None) -> list[int]:
        user_ids = super().resolve(target_type, target_id, team_id)
        return self._filter_by_subject_access(user_ids)

    def _filter_by_subject_access(self, user_ids: list[int]) -> list[int]:
        # Both gates below are per-member, so they share one member query, one access-control object
        # and one denial snapshot each rather than a pass apiece.
        if not self._access_controls_supported(user_ids):
            return user_ids

        return [user.id for user in User.objects.filter(id__in=user_ids) if self._may_receive(user)]

    def _object_gate_applies(self) -> bool:
        return SubjectType(self._subject_type) in _OBJECT_GATED_SUBJECT_TYPES

    def _reference_gate_applies(self) -> bool:
        # The declared subject isn't the only one the count depends on: a relationships check reads
        # its target and a custom_sql check reads arbitrary tables.
        return bool(self._referenced_names) or bool(self._executed_references) or self._references_unknown

    def _may_receive(self, user: User) -> bool:
        access = self._access_of(user)
        if not access.check_access_level_for_resource("query", "viewer"):
            return False
        if self._subject_type == SubjectType.METRIC and not access.check_access_level_for_resource(
            "data_catalog", "viewer"
        ):
            return False
        if self._subject_type == SubjectType.POSTHOG_TABLE and not access.check_access_level_for_resource(
            posthog_tables.RESOURCE, "viewer"
        ):
            return False
        if self._object_gate_applies() and not self._has_object_access(access):
            return False
        if not self._reference_gate_applies():
            return True
        if self._references_unknown and can_be_object_denied(access):
            return False
        return self._gate_of(user).admits(self._notice_references())

    def _has_object_access(self, access: UserAccessControl) -> bool:
        object_id = UUID(self._subject_uuid)
        allowed_ids = (
            warehouse_facade.allowed_table_ids(self._team.id, access, ids=[object_id])
            if self._subject_type == SubjectType.TABLE
            else data_modeling_facade.allowed_saved_query_ids(self._team.id, access, ids=[object_id])
        )
        return object_id in allowed_ids

    def _notice_references(self) -> NoticeReferences:
        if self._references is None:
            self._references = notice_references(
                self._team.id, executed_references=self._executed_references, names=self._referenced_names
            )
        return self._references

    def _gate_of(self, user: User) -> ReferenceGate:
        if self._unentitled is None:
            self._unentitled = unentitled_system_tables(self._team)
        return reference_gate(
            self._team,
            user,
            self._access_of(user),
            references=self._notice_references(),
            unentitled=self._unentitled,
        )


def _source_url(team_id: int, subject_type: str, subject_name: str) -> str:
    if subject_type == SubjectType.METRIC:
        return f"/project/{team_id}/data-catalog/metrics/{quote(subject_name, safe='')}?tab=data-quality"
    if subject_type == SubjectType.POSTHOG_TABLE:
        return f"/project/{team_id}/models?tab=data-quality"
    return ""


def notify_check_started_failing(
    check: DataQualityCheck,
    failed_row_count: int | None,
    *,
    executed_references: Sequence[dict[str, str]] | None = (),
    idempotency_key: str | None = None,
    access_cache: dict[int, UserAccessControl] | None = None,
) -> int:
    """How many members were told. Best-effort: a failure here must never fail the run behind it."""
    try:
        if check.subject_uuid is None:
            return 0
        team = Team.objects.get(id=check.team_id)
        subject = resolve_subject(team.id, check.subject_type, check.subject_uuid)
        if not subject.exists:
            return 0
        is_metric = check.subject_type == SubjectType.METRIC
        is_posthog_table = check.subject_type == SubjectType.POSTHOG_TABLE
        subject_name = subject.name if is_metric or is_posthog_table else check.subject_name
        event = create_notification(
            NotificationData(
                team_id=check.team_id,
                notification_type=NotificationType.DATA_QUALITY_CHECK_FAILURE,
                priority=Priority.NORMAL,
                title=f"Data quality check failed on {subject_name}",
                body=_body(check, failed_row_count),
                target_type=TargetType.TEAM,
                target_id=str(check.team_id),
                # The body names a warehouse table or view and one of its columns, so it points at
                # the subject object (not the check) and the resolver filters recipients down to
                # members with object-level access to it, plus query access for the count.
                resource_type="data_catalog" if is_metric else "warehouse_objects",
                resource_id=str(check.subject_uuid),
                source_url=_source_url(team.id, check.subject_type, subject_name),
                idempotency_key=idempotency_key,
                resolver=_WarehouseSubjectResolver(
                    team,
                    check.subject_type,
                    str(check.subject_uuid),
                    referenced_names=referenced_subject_names(team.id, check.check_type, check.config, subject=subject),
                    executed_references=executed_references or (),
                    references_unknown=executed_references is None,
                    access_cache=access_cache,
                ),
            )
        )
        return len(event.resolved_user_ids) if event is not None else 0
    except Exception:
        LOGGER.exception("Could not send a data quality failure notification", check_id=str(check.id))
        return 0


def notify_materialization_blocked(
    team_id: int, saved_query_id: str, view_name: str, blocking_failures: int, job_id: str
) -> None:
    """Tell the team a refresh was not published because its checks failed. Best-effort."""
    try:
        team = Team.objects.get(id=team_id)
        checks = "check" if blocking_failures == 1 else "checks"
        create_notification(
            NotificationData(
                team_id=team_id,
                notification_type=NotificationType.DATA_QUALITY_CHECK_FAILURE,
                priority=Priority.NORMAL,
                title=f"Materialization of {view_name} was not published",
                body=f"{blocking_failures} data quality {checks} failed, so the previous version keeps "
                "serving. Fix the data or the checks, then materialize again.",
                target_type=TargetType.TEAM,
                target_id=str(team_id),
                resource_type="warehouse_objects",
                resource_id=saved_query_id,
                # Keyed on the blocked materialization job: the block activity can run twice when a
                # slow attempt hits its start-to-close timeout, and the unique constraint behind this
                # key collapses the retry to one notice while a genuinely new block notifies again.
                idempotency_key=f"matview-blocked-{job_id}",
                resolver=_WarehouseSubjectResolver(
                    team,
                    SubjectType.VIEW,
                    saved_query_id,
                    referenced_names=_blocking_referenced_names(team_id, saved_query_id, job_id),
                ),
            )
        )
    except Exception:
        LOGGER.exception("Could not send a materialization-blocked notification", saved_query_id=saved_query_id)


def _blocking_referenced_names(team_id: int, saved_query_id: str, job_id: str) -> list[str]:
    """Every further subject the checks behind a blocked materialization read.

    The body's failure count aggregates those checks, so it is an oracle over everything they read,
    not just over the view the recipient is already allowed to see.

    Read off the suite's persisted check runs, not the definitions' current state. ``enabled``,
    ``severity``, ``last_status`` and ``deleted`` are all writable by anyone who can edit the view --
    including a member denied a subject the check reads, since the write path only authorizes the
    declared subject. Selecting on them would let that member edit their own denial out of this
    filter in the window between the suite finishing and this notice being written, while the count
    still counts their check. A run row is immutable, so it cannot be edited out of the set it
    belongs to. The suite is the one the blocked job triggered, so the names and the count come from
    the same batch, across every subject the batch covered.
    """
    names: set[str] = set()
    runs = (
        DataQualityCheckRun.objects.for_team(team_id)
        .filter(
            suite_run__data_modeling_job_id=job_id,
            status=CheckRunStatus.FAILED,
            # No severity on the run row, so this takes warn-severity failures too. They did not
            # block, so the set is wider than the count -- which over-filters rather than leaks.
            check_type__in=referencing_check_types(),
        )
        .select_related("quality_check")
    )
    # A run records which check ran, never the config it ran with. A definition that has since been
    # hard-deleted or re-pointed at other tables leaves nothing to enumerate, and so does a suite
    # retention already swept. Widen to every referencing check on the subject: wider than this
    # block, but it can only drop more recipients, never admit one the count would leak to.
    unbindable = not DataQualitySuiteRun.objects.for_team(team_id).filter(data_modeling_job_id=job_id).exists()
    for run in runs:
        check = run.quality_check
        if check is None or check.fingerprint != run.check_fingerprint:
            unbindable = True
            continue
        names.update(referenced_subject_names(team_id, check.check_type, check.config))
    if unbindable:
        for check in checks_for_subject(team_id, SubjectType.VIEW, saved_query_id, include_deleted=True).filter(
            check_type__in=referencing_check_types()
        ):
            names.update(referenced_subject_names(team_id, check.check_type, check.config))
    return sorted(names)


def _body(check: DataQualityCheck, failed_row_count: int | None) -> str:
    subject = f"{check.check_type} check"
    if check.column_name:
        subject = f"{check.check_type} check on {check.subject_name}.{check.column_name}"

    if failed_row_count:
        rows = "row" if failed_row_count == 1 else "rows"
        return f"The {subject} found {failed_row_count} failing {rows}. It was passing on the previous run."
    return f"The {subject} started failing. It was passing on the previous run."