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.6 KB
Raw Blame
from typing import TYPE_CHECKING

from django.db import models
from django.db.models import Q, QuerySet
from django.utils import timezone

from posthog.models.file_system.constants import DEFAULT_SURFACE
from posthog.models.file_system.file_system_mixin import FileSystemSyncMixin
from posthog.models.file_system.file_system_representation import FileSystemRepresentation
from posthog.models.scoping.root_mixin import TeamScopedRootMixin
from posthog.models.utils import UUIDModel

from products.canvas.backend.facade.enums import (
    CANVAS_BUILD_STATUS_FAILED,
    CANVAS_BUILD_STATUS_READY,
    CANVAS_KIND_COMPONENT,
    CANVAS_KIND_FREEFORM,
    CANVAS_KIND_GRID,
    CANVAS_KINDS,
    CANVAS_STATE_SCOPE_SHARED,
    CANVAS_STATE_SCOPE_USER,
    CANVAS_STATE_SCOPES,
)

if TYPE_CHECKING:
    from posthog.models.team import Team


class Canvas(FileSystemSyncMixin, TeamScopedRootMixin, UUIDModel):
    """A canvas document: an agent-built, sandboxed browser app filed in a channel.

    The document's source lives in append-only ``CanvasSourceVersion`` rows
    (content in object storage); built artifacts hang off ``CanvasBuild`` rows.
    ``current_source_version`` is the editable head (publish advances it,
    revert moves it back) and ``published_build`` is the live artifact pointer —
    it only advances when a build completes for a version that is still the head.

    ``kind`` splits the model into three shapes sharing this lifecycle:

    - ``freeform`` — a standalone app; its source project compiles to one artifact.
    - ``component`` — a reusable widget other canvases place on a grid. Same
      source/build pipeline as freeform, plus a config schema and grid size
      snapshotted onto each version. Visibility rides the channel like any
      canvas: a component in a personal channel is private, in a team channel
      it is the team's.
    - ``grid`` — a composition of components. Its "source" is a layout document
      (placements referencing component canvases), so publishing a grid
      validates and versions the layout without queuing a build.
    """

    KIND_FREEFORM = CANVAS_KIND_FREEFORM
    KIND_GRID = CANVAS_KIND_GRID
    KIND_COMPONENT = CANVAS_KIND_COMPONENT
    KINDS = CANVAS_KINDS

    SOURCE_POLICY_STANDARD = "standard"
    SOURCE_POLICY_NOTEBOOK_WIDGET = "notebook_widget"
    SOURCE_POLICIES = [SOURCE_POLICY_STANDARD, SOURCE_POLICY_NOTEBOOK_WIDGET]

    # db_constraint=False: a real FK constraint to the hot posthog_team table
    # takes a parent lock during migration; scoping is enforced app-side.
    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")
    # Channels are the tasks product's model; every canvas is filed into one.
    channel = models.ForeignKey("tasks.Channel", on_delete=models.CASCADE, db_constraint=False, related_name="+")

    name = models.CharField(max_length=400)
    kind = models.CharField(max_length=16, default=KIND_FREEFORM)
    source_policy = models.CharField(max_length=32, default=SOURCE_POLICY_STANDARD, db_default=SOURCE_POLICY_STANDARD)
    # Short prose describing what the canvas is/does. For components this is
    # the store-search text agents match against, so it should say what the
    # widget shows and what its config controls.
    description = models.TextField(blank=True, default="")
    template_id = models.CharField(max_length=64, default="freeform")
    # The task currently generating/editing this canvas. A plain UUID rather
    # than a FK: Task lives in the tasks app and a schema-level FK would chain
    # the two products' migrations together for a soft pointer.
    generation_task_id = models.UUIDField(null=True, blank=True)
    # Set when the canvas is pinned to its channel (shared across users).
    pinned_at = models.DateTimeField(null=True, blank=True)

    current_source_version = models.ForeignKey(
        "canvas.CanvasSourceVersion", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )
    published_build = models.ForeignKey(
        "canvas.CanvasBuild", on_delete=models.SET_NULL, null=True, blank=True, related_name="+"
    )
    # Single-file source carried over from the pre-relational data model. Read
    # only when a canvas has no source versions yet; the next publish creates a
    # real version and this field stops mattering.
    legacy_code = models.TextField(null=True, blank=True)

    created_by = models.ForeignKey(
        "posthog.User", on_delete=models.SET_NULL, null=True, blank=True, db_constraint=False, related_name="+"
    )
    created_at = models.DateTimeField(default=timezone.now)
    updated_at = models.DateTimeField(auto_now=True)
    deleted = models.BooleanField(default=False)

    class Meta:
        db_table = "posthog_canvas"
        indexes = [
            models.Index(fields=["channel", "-created_at"], name="canvas_channel_recency"),
            # The component store lists/searches by team + kind; freeform rows
            # (the overwhelming majority) stay out of the index.
            models.Index(
                fields=["team", "kind"],
                condition=~Q(kind="freeform"),
                name="canvas_kind_store",
            ),
        ]

    # What makes a canvas a thing a person opens from the project tree: a live, standalone freeform
    # canvas. Components and grids are widgets, and notebook widgets belong to their notebook. The
    # unfiled sweep filters on this mapping and `is_filed_analysis` compares an instance to it, so the
    # two never drift apart.
    FILED_ANALYSIS_FILTER: dict[str, object] = {
        "deleted": False,
        "kind": KIND_FREEFORM,
        "source_policy": SOURCE_POLICY_STANDARD,
    }

    @property
    def is_filed_analysis(self) -> bool:
        return all(getattr(self, field) == value for field, value in self.FILED_ANALYSIS_FILTER.items())

    @classmethod
    def get_file_system_unfiled(cls, team: "Team", surface: str = DEFAULT_SURFACE) -> QuerySet["Canvas"]:
        # The unfiled sweep runs outside a request, so the fail-closed manager needs the team spelled out.
        # `for_team` resolves an environment to its project, so the exact team keeps an environment's sweep
        # from filing the project's canvases a second time under its own id.
        base_qs = cls.objects.for_team(team.id).filter(team_id=team.id, **cls.FILED_ANALYSIS_FILTER)
        return cls._filter_unfiled_queryset(base_qs, team, type="canvas", ref_field="id", surface=surface)

    def get_file_system_representation(self) -> FileSystemRepresentation:
        return FileSystemRepresentation(
            base_folder=self._get_assigned_folder("Unfiled/Canvases"),
            type="canvas",  # sync with APIScopeObject in scopes.py
            ref=str(self.id),
            name=self.name or "Untitled",
            href=f"/canvases/{self.id}",
            meta={"created_at": str(self.created_at), "created_by": self.created_by_id},
            should_delete=not self.is_filed_analysis,
        )


class CanvasSourceVersion(TeamScopedRootMixin, UUIDModel):
    """One immutable published source project of a canvas.

    The project content itself lives in object storage (private, content
    addressed); this row is the control-plane record: pointers, hashes,
    attribution, and lineage. Rows are append-only — a publish never rewrites
    an existing version.
    """

    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")
    canvas = models.ForeignKey(Canvas, on_delete=models.CASCADE, related_name="source_versions")
    parent_version = models.ForeignKey("self", on_delete=models.SET_NULL, null=True, blank=True, related_name="+")

    # Verifiable content address: hex SHA-256 of the canonical serialized project.
    source_hash = models.CharField(max_length=64)
    # Immutable object-storage key of the serialized project (private namespace).
    source_object_key = models.TextField()
    # Size in bytes of the canonical (uncompressed) serialization.
    source_size = models.PositiveIntegerField()

    # Attribution: the task/run that published this version, when one did.
    task_id = models.UUIDField(null=True, blank=True)
    task_run_id = models.UUIDField(null=True, blank=True)
    prompt = models.TextField(null=True, blank=True)

    # Snapshot of the project's declared capabilities manifest, denormalized
    # from the stored source so capability changes can be diffed and audited
    # without reading object storage. Null for versions that predate it.
    capabilities = models.JSONField(null=True, blank=True)

    # For component-kind canvases: the version's placement contract (config
    # schema, grid size), denormalized from the stored source so the store and
    # layout validation can read it without hitting object storage. Null for
    # freeform/grid versions and component versions that predate it.
    component_meta = models.JSONField(null=True, blank=True)

    # True while the version is a staged draft: stored and built like any other
    # version, but never the canvas head, so its build can't go live. Promoting
    # clears the flag; after that the version is indistinguishable from a publish.
    draft = models.BooleanField(default=False)

    created_by = models.ForeignKey(
        "posthog.User", on_delete=models.SET_NULL, null=True, blank=True, db_constraint=False, related_name="+"
    )
    created_at = models.DateTimeField(default=timezone.now)

    class Meta:
        db_table = "posthog_canvas_source_version"
        indexes = [models.Index(fields=["canvas", "-created_at"], name="canvas_source_version_recency")]


class CanvasBuild(TeamScopedRootMixin, UUIDModel):
    """Lifecycle record of one build of a canvas source version.

    A failed build records diagnostics but never replaces the canvas's
    last-known-good artifact; the live pointer (``Canvas.published_build``)
    only advances when a build completes and its source version is still the
    canvas's current head.
    """

    STATUS_QUEUED = "queued"
    STATUS_BUILDING = "building"
    STATUS_READY = CANVAS_BUILD_STATUS_READY
    STATUS_FAILED = CANVAS_BUILD_STATUS_FAILED
    ACTIVE_STATUSES = [STATUS_QUEUED, STATUS_BUILDING]

    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")
    canvas = models.ForeignKey(Canvas, on_delete=models.CASCADE, related_name="builds")
    source_version = models.ForeignKey(CanvasSourceVersion, on_delete=models.CASCADE, related_name="builds")

    status = models.CharField(max_length=16, default=STATUS_QUEUED)
    # Object-storage prefix the immutable artifact files live under (set when ready).
    artifact_object_prefix = models.TextField(null=True, blank=True)
    # Hex SHA-256 over the artifact manifest — the integrity anchor for loaders.
    integrity = models.CharField(max_length=64, null=True, blank=True)
    # Bounded structured diagnostics (full logs belong in log storage, not here).
    diagnostics = models.JSONField(default=list, blank=True)
    # The frozen artifact manifest (entry, assets, versions, capabilities).
    manifest = models.JSONField(null=True, blank=True)
    # Pinned builds are retained for the lifetime of the canvas.
    pinned = models.BooleanField(default=False)
    attempt_count = models.PositiveIntegerField(default=0)
    lease_expires_at = models.DateTimeField(null=True, blank=True)
    # Set every time the build is handed to the worker queue. The stuck-build
    # sweeper keys redelivery staleness off this (not created_at), so a retry of
    # an old failed build isn't mistaken for a lost enqueue.
    enqueued_at = models.DateTimeField(default=timezone.now)

    created_at = models.DateTimeField(default=timezone.now)
    finished_at = models.DateTimeField(null=True, blank=True)

    class Meta:
        db_table = "posthog_canvas_build"
        indexes = [
            models.Index(fields=["canvas", "-created_at"], name="canvas_build_recency"),
            # The team build cap and the stuck-build sweeper both scan only
            # in-flight rows, which are a tiny fraction of the table.
            models.Index(
                fields=["team", "status"],
                condition=Q(status__in=["queued", "building"]),
                name="canvas_build_active",
            ),
            # The retention sweep scans only prunable rows (unpinned, artifacts
            # still present) by age.
            models.Index(
                fields=["finished_at"],
                condition=Q(pinned=False, artifact_object_prefix__isnull=False),
                name="canvas_build_retention",
            ),
        ]


class CanvasHomePreference(TeamScopedRootMixin, UUIDModel):
    """One user's home-canvas selection within a team.

    Home is a pointer to an ordinary canvas (normally a grid canvas in the
    user's personal channel), not a flag on the canvas itself — a canvas-side
    marker was tried before (``is_home``) and retired because it entangled
    canvas lifecycle with surface lifecycle. The FK cascade only clears the
    pointer on a hard delete of the team or channel; the canvas delete endpoint
    is a soft delete (``deleted=True``), so a pointer at a soft-deleted canvas
    survives. The home reader must treat a pointer whose canvas is deleted as no
    home set — filter ``canvas__deleted=False`` — and re-provision on next open.
    """

    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")
    user = models.ForeignKey("posthog.User", on_delete=models.CASCADE, db_constraint=False, related_name="+")
    canvas = models.ForeignKey(Canvas, on_delete=models.CASCADE, related_name="+")

    created_at = models.DateTimeField(default=timezone.now)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = "posthog_canvas_home_preference"
        constraints = [
            models.UniqueConstraint(fields=["team", "user"], name="canvas_home_one_per_user_team"),
        ]


class CanvasState(TeamScopedRootMixin, UUIDModel):
    """One key of a canvas's runtime key-value store (the ``ph.state`` verb).

    ``user`` rows belong to one viewer; ``shared`` rows to the canvas itself.
    Values are application data written from viewer sessions — never secrets —
    and bounded at write time (value size, keys per scope), which keeps every
    access a point lookup and table growth capped by canvas count.
    """

    SCOPE_USER = CANVAS_STATE_SCOPE_USER
    SCOPE_SHARED = CANVAS_STATE_SCOPE_SHARED
    SCOPES = CANVAS_STATE_SCOPES

    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")
    canvas = models.ForeignKey(Canvas, on_delete=models.CASCADE, related_name="state_entries")
    scope = models.CharField(max_length=8)
    # The owning viewer for user-scoped rows; always null for shared rows.
    user = models.ForeignKey(
        "posthog.User", on_delete=models.CASCADE, null=True, blank=True, db_constraint=False, related_name="+"
    )
    key = models.CharField(max_length=200)
    value = models.JSONField()
    created_at = models.DateTimeField(default=timezone.now)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = "posthog_canvas_state"
        constraints = [
            # Postgres treats NULLs as distinct, so shared rows (user NULL) get
            # their own uniqueness arm instead of one four-column constraint.
            models.UniqueConstraint(
                fields=["canvas", "scope", "user", "key"],
                condition=Q(user__isnull=False),
                name="canvas_state_user_key",
            ),
            models.UniqueConstraint(
                fields=["canvas", "scope", "key"],
                condition=Q(user__isnull=True),
                name="canvas_state_shared_key",
            ),
        ]