litestar-feedback 0.2.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,7 @@
1
+ """Litestar plugins for an in-app customer support inbox and session replay.
2
+
3
+ Import each plugin from its subpackage: ``litestar_feedback.support`` or
4
+ ``litestar_feedback.replay``. This module only holds the version.
5
+ """
6
+
7
+ __version__ = "0.2.1"
@@ -0,0 +1,41 @@
1
+ """Column types both plugins share."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import UTC, datetime
6
+ from typing import Any
7
+
8
+ from sqlalchemy import JSON, DateTime, Dialect
9
+ from sqlalchemy.dialects.postgresql import JSONB
10
+ from sqlalchemy.types import TypeDecorator
11
+
12
+
13
+ class UTCDateTime(TypeDecorator[datetime]):
14
+ """A timezone-aware timestamp that always loads as UTC.
15
+
16
+ SQLite drops the offset on the way back. This type puts UTC back, so comparisons with
17
+ ``datetime.now(UTC)`` work on every backend. Naive values are refused on write.
18
+ """
19
+
20
+ impl = DateTime(timezone=True)
21
+ cache_ok = True
22
+
23
+ def process_bind_param(self, value: datetime | None, dialect: Dialect) -> datetime | None:
24
+ """Refuse naive datetimes and convert aware ones to UTC."""
25
+ if value is None:
26
+ return None
27
+ if value.tzinfo is None:
28
+ raise ValueError("naive datetime: pass a timezone-aware value")
29
+ return value.astimezone(UTC)
30
+
31
+ def process_result_value(self, value: datetime | None, dialect: Dialect) -> datetime | None:
32
+ """Attach UTC to values the driver returns without an offset."""
33
+ if value is None:
34
+ return None
35
+ if value.tzinfo is None:
36
+ return value.replace(tzinfo=UTC)
37
+ return value.astimezone(UTC)
38
+
39
+
40
+ JSONColumn: Any = JSON().with_variant(JSONB(), "postgresql")
41
+ """JSON on SQLite, JSONB on Postgres."""
@@ -0,0 +1,48 @@
1
+ """Who is calling, and how to open a database session for them.
2
+
3
+ Both plugins use these types. Neither plugin imports the other.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Awaitable, Callable
9
+ from contextlib import AbstractAsyncContextManager
10
+ from dataclasses import dataclass
11
+ from typing import Any
12
+
13
+ from litestar import Request
14
+ from sqlalchemy.ext.asyncio import AsyncSession
15
+
16
+
17
+ @dataclass(frozen=True, slots=True)
18
+ class Caller:
19
+ """The authenticated user of one request, as the plugins see it.
20
+
21
+ ``scope_id`` is the product's tenancy key: crm ``tenant_id``, accounting ``company_id``,
22
+ tyko ``reporter_user_id``. Rows the plugins write carry it, and customer routes only
23
+ return rows with the caller's ``scope_id``.
24
+
25
+ Both ids are strings so that UUID keys (crm, tyko) and integer keys (accounting) fit the
26
+ same columns. Pass ``str(user.tenant_id)``. Row-level security policies then compare text.
27
+
28
+ ``actor`` is the label written on events, usually the user's email.
29
+
30
+ ``is_operator`` opens the ``/admin`` routes, which read across all scopes.
31
+ """
32
+
33
+ scope_id: str
34
+ user_id: str | None
35
+ actor: str
36
+ is_operator: bool = False
37
+
38
+
39
+ CallerResolver = Callable[[Request[Any, Any, Any]], Awaitable[Caller]]
40
+ """Return the ``Caller`` for a request. Raise ``NotAuthorizedException`` when nobody is signed in."""
41
+
42
+ SessionOpener = Callable[[Caller], AbstractAsyncContextManager[AsyncSession]]
43
+ """Open a session for one request, inside a transaction that commits on exit.
44
+
45
+ The plugin passes the ``Caller`` so the host can prepare the session for it, for example
46
+ ``SET LOCAL app.tenant_id`` for row-level security, or a session that bypasses row-level
47
+ security when ``caller.is_operator`` is true. An exception inside the block must roll back.
48
+ """
File without changes
@@ -0,0 +1,45 @@
1
+ """Session replay for Litestar: chunked rrweb ingest, playback from an offset, click heatmaps.
2
+
3
+ The browser recorder is not part of this package. See the README for the ingest API.
4
+ """
5
+
6
+ from litestar_feedback.caller import Caller, CallerResolver, SessionOpener
7
+ from litestar_feedback.replay.adapter import (
8
+ ChunkStore,
9
+ ConsentCheck,
10
+ ProtectedSessions,
11
+ ReplayAdapter,
12
+ ReplayConfig,
13
+ )
14
+ from litestar_feedback.replay.models import ReplayBase, ReplayChunk, ReplayClick, ReplaySession
15
+ from litestar_feedback.replay.plugin import ReplayPlugin
16
+ from litestar_feedback.replay.service import (
17
+ Heatmap,
18
+ HeatmapCell,
19
+ HeatmapPage,
20
+ Playback,
21
+ PruneResult,
22
+ ReplayService,
23
+ )
24
+
25
+ __all__ = [
26
+ "Caller",
27
+ "CallerResolver",
28
+ "ChunkStore",
29
+ "ConsentCheck",
30
+ "Heatmap",
31
+ "HeatmapCell",
32
+ "HeatmapPage",
33
+ "Playback",
34
+ "ProtectedSessions",
35
+ "PruneResult",
36
+ "ReplayAdapter",
37
+ "ReplayBase",
38
+ "ReplayChunk",
39
+ "ReplayClick",
40
+ "ReplayConfig",
41
+ "ReplayPlugin",
42
+ "ReplayService",
43
+ "ReplaySession",
44
+ "SessionOpener",
45
+ ]
@@ -0,0 +1,101 @@
1
+ """What the host product provides to ``ReplayPlugin``, and the limits it can tune."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import uuid
6
+ from collections.abc import Awaitable, Callable
7
+ from dataclasses import dataclass, field
8
+ from datetime import UTC, datetime
9
+ from typing import Any, Protocol
10
+
11
+ from litestar import Request
12
+ from sqlalchemy.ext.asyncio import AsyncSession
13
+
14
+ from litestar_feedback.caller import Caller, CallerResolver, SessionOpener
15
+
16
+
17
+ class ChunkStore(Protocol):
18
+ """Async blob store for chunk bodies. Without one, chunks are stored in the database."""
19
+
20
+ async def put(self, *, key: str, data: bytes) -> None:
21
+ """Store ``data`` under ``key``."""
22
+ ...
23
+
24
+ async def get(self, *, key: str) -> bytes:
25
+ """Return the bytes stored under ``key``."""
26
+ ...
27
+
28
+ async def delete(self, *, key: str) -> None:
29
+ """Remove ``key``. A missing key is not an error."""
30
+ ...
31
+
32
+
33
+ ConsentCheck = Callable[[Caller, Request[Any, Any, Any]], Awaitable[bool]]
34
+ """Return True when this caller agreed to be recorded."""
35
+
36
+ ProtectedSessions = Callable[[AsyncSession], Awaitable[set[uuid.UUID]]]
37
+ """Return replay session ids that prune and user deletion must keep.
38
+
39
+ Pass ``litestar_feedback.support.referenced_replay_sessions`` to keep sessions that live
40
+ support issues point to.
41
+ """
42
+
43
+
44
+ @dataclass(frozen=True, slots=True)
45
+ class ReplayAdapter:
46
+ """The product-specific parts of session replay.
47
+
48
+ Attributes:
49
+ caller: Maps a request to a ``Caller``. Operators can play back and see heatmaps.
50
+ session: Opens a transaction for that caller. Set row-level security here.
51
+ chunk_store: Blob store for chunk bodies. None stores them in ``replay_chunks.events``.
52
+ retention_days: ``prune`` deletes sessions whose last event is older. 0 keeps all.
53
+ consent: Called before every ingest. False answers 403 and stores nothing. None
54
+ means the host checks consent before it starts the recorder.
55
+ protected_sessions: Session ids that prune and user deletion keep.
56
+ """
57
+
58
+ caller: CallerResolver
59
+ session: SessionOpener
60
+ chunk_store: ChunkStore | None = None
61
+ retention_days: int = 30
62
+ consent: ConsentCheck | None = None
63
+ protected_sessions: ProtectedSessions | None = None
64
+
65
+
66
+ def _utcnow() -> datetime:
67
+ return datetime.now(UTC)
68
+
69
+
70
+ @dataclass(frozen=True, slots=True)
71
+ class ReplayConfig:
72
+ """Ingest limits and heatmap buckets.
73
+
74
+ Attributes:
75
+ path: Prefix for every route, for example ``"/v1"``.
76
+ max_chunk_bytes: Largest accepted chunk, as JSON bytes. Bigger is 413.
77
+ max_session_bytes: Total JSON bytes one session may store. A chunk that would pass it
78
+ is 413. 0 turns the cap off.
79
+ max_chunk_events: Most events in one chunk. More is 413.
80
+ viewport_buckets: Lower bounds of the viewport width buckets for heatmaps. A click at
81
+ width 900 with buckets ``(0, 640, 1024)`` falls in bucket 640.
82
+ heatmap_columns: Columns of the heatmap grid across the viewport width.
83
+ heatmap_row_px: Height of one heatmap row in pixels.
84
+ list_limit: Default and maximum page size of the session list.
85
+ clock: Returns the current time. Tests replace it.
86
+ """
87
+
88
+ path: str = "/"
89
+ max_chunk_bytes: int = 1024 * 1024
90
+ max_session_bytes: int = 20 * 1024 * 1024
91
+ max_chunk_events: int = 5_000
92
+ viewport_buckets: tuple[int, ...] = (0, 640, 1024, 1440)
93
+ heatmap_columns: int = 20
94
+ heatmap_row_px: int = 50
95
+ list_limit: int = 200
96
+ clock: Callable[[], datetime] = field(default=_utcnow)
97
+
98
+ def bucket(self, width: int) -> int:
99
+ """Return the bucket lower bound for a viewport width."""
100
+ fitting = [b for b in self.viewport_buckets if b <= width]
101
+ return max(fitting) if fitting else min(self.viewport_buckets)
@@ -0,0 +1,159 @@
1
+ """Reading rrweb events: what one chunk says about time, activity, snapshots and clicks.
2
+
3
+ Pure functions. The numbers are rrweb's ``EventType`` and ``IncrementalSource`` enums.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping, Sequence
9
+ from dataclasses import dataclass
10
+ from itertools import pairwise
11
+ from typing import Any
12
+ from urllib.parse import urlsplit
13
+
14
+ FULL_SNAPSHOT = 2
15
+ INCREMENTAL_SNAPSHOT = 3
16
+ META = 4
17
+
18
+ SOURCE_MOUSE_INTERACTION = 2
19
+ SOURCE_VIEWPORT_RESIZE = 4
20
+ MOUSE_CLICK = 2
21
+
22
+ USER_INPUT_SOURCES = frozenset({1, 2, 3, 5, 6})
23
+ """Mouse move, mouse interaction, scroll, input, touch move: things a person causes."""
24
+
25
+ ACTIVE_GAP_MS = 60_000
26
+ """Gaps between inputs up to this long count as active time (same rule as crm)."""
27
+
28
+ Event = Mapping[str, Any]
29
+
30
+
31
+ class InvalidEvent(ValueError):
32
+ """An event without an integer ``type`` and ``timestamp``."""
33
+
34
+
35
+ @dataclass(frozen=True, slots=True)
36
+ class Click:
37
+ """One click, with ``x`` as a fraction of the viewport width and ``y`` in viewport pixels."""
38
+
39
+ path: str
40
+ viewport_w: int
41
+ x_ratio: float
42
+ y_px: int
43
+ at_ms: int
44
+
45
+
46
+ @dataclass(frozen=True, slots=True)
47
+ class PageState:
48
+ """The page and viewport width in effect at a point of the recording."""
49
+
50
+ path: str | None
51
+ viewport_w: int | None
52
+
53
+
54
+ @dataclass(frozen=True, slots=True)
55
+ class ChunkFacts:
56
+ """What the plugin stores about a chunk besides its events."""
57
+
58
+ first_ms: int
59
+ last_ms: int
60
+ snapshot_ms: int | None
61
+ input_ms: tuple[int, ...]
62
+ clicks: tuple[Click, ...]
63
+ end_state: PageState
64
+
65
+
66
+ def _int(value: Any) -> int | None:
67
+ if isinstance(value, bool) or not isinstance(value, int | float):
68
+ return None
69
+ return int(value)
70
+
71
+
72
+ def validate(events: Sequence[Any]) -> None:
73
+ """Raise ``InvalidEvent`` unless every event is an object with integer type and timestamp."""
74
+ for i, event in enumerate(events):
75
+ if not isinstance(event, Mapping):
76
+ raise InvalidEvent(f"event {i} is not an object")
77
+ typed: Mapping[str, Any] = event # pyright: ignore[reportUnknownVariableType]
78
+ if _int(typed.get("type")) is None or _int(typed.get("timestamp")) is None:
79
+ raise InvalidEvent(f"event {i} needs integer 'type' and 'timestamp'")
80
+
81
+
82
+ def path_of(href: str) -> str:
83
+ """Return the path of a URL, ``/`` when empty."""
84
+ return urlsplit(href).path or "/"
85
+
86
+
87
+ def facts(events: Sequence[Event], start: PageState) -> ChunkFacts:
88
+ """Read one validated, non-empty chunk.
89
+
90
+ ``start`` is the page state after the previous chunk. Meta events change the path and
91
+ width, viewport resize events change the width. Clicks before the first known page and
92
+ width are dropped.
93
+ """
94
+ path, width = start.path, start.viewport_w
95
+ stamps: list[int] = []
96
+ inputs: list[int] = []
97
+ clicks: list[Click] = []
98
+ snapshot: int | None = None
99
+ for event in events:
100
+ ts = int(event["timestamp"])
101
+ kind = int(event["type"])
102
+ stamps.append(ts)
103
+ data: Mapping[str, Any] = event.get("data") or {}
104
+ if kind == META:
105
+ href = data.get("href")
106
+ if isinstance(href, str):
107
+ path = path_of(href)
108
+ width = _int(data.get("width")) or width
109
+ elif kind == FULL_SNAPSHOT:
110
+ snapshot = ts if snapshot is None else max(snapshot, ts)
111
+ elif kind == INCREMENTAL_SNAPSHOT:
112
+ source = data.get("source")
113
+ if source in USER_INPUT_SOURCES:
114
+ inputs.append(ts)
115
+ if source == SOURCE_VIEWPORT_RESIZE:
116
+ width = _int(data.get("width")) or width
117
+ elif source == SOURCE_MOUSE_INTERACTION and data.get("type") == MOUSE_CLICK:
118
+ x, y = _int(data.get("x")), _int(data.get("y"))
119
+ if path is not None and width and x is not None and y is not None:
120
+ ratio = min(1.0, max(0.0, x / width))
121
+ clicks.append(Click(path, width, ratio, max(0, y), ts))
122
+ return ChunkFacts(
123
+ first_ms=min(stamps),
124
+ last_ms=max(stamps),
125
+ snapshot_ms=snapshot,
126
+ input_ms=tuple(sorted(inputs)),
127
+ clicks=tuple(clicks),
128
+ end_state=PageState(path=path, viewport_w=width),
129
+ )
130
+
131
+
132
+ def active_ms(inputs: Sequence[int], *, previous_input_ms: int | None) -> int:
133
+ """Return active time in ``inputs``, plus the gap from ``previous_input_ms`` when short."""
134
+ total = sum(b - a for a, b in pairwise(inputs) if b - a <= ACTIVE_GAP_MS)
135
+ if inputs and previous_input_ms is not None:
136
+ gap = inputs[0] - previous_input_ms
137
+ if 0 <= gap <= ACTIVE_GAP_MS:
138
+ total += gap
139
+ return total
140
+
141
+
142
+ def play_from(events: Sequence[Event], target_ms: int) -> list[Event]:
143
+ """Return the events a player needs to start at ``target_ms``.
144
+
145
+ rrweb rebuilds the page from a full snapshot and the meta event before it. Keep events from
146
+ the last meta event before the last full snapshot at or before ``target_ms``. With no such
147
+ snapshot, keep everything.
148
+ """
149
+ start = 0
150
+ for i, event in enumerate(events):
151
+ if int(event["timestamp"]) > target_ms:
152
+ break
153
+ if int(event["type"]) == FULL_SNAPSHOT:
154
+ start = i
155
+ for j in range(i - 1, -1, -1):
156
+ if int(events[j]["type"]) == META:
157
+ start = j
158
+ break
159
+ return list(events[start:])
@@ -0,0 +1,114 @@
1
+ """Alembic helpers that create and drop the replay tables.
2
+
3
+ The table definitions are written out here, not read from the models, so a migration you
4
+ wrote today creates the same tables after a package upgrade.
5
+
6
+ ```python
7
+ from alembic import op
8
+ from litestar_feedback.replay.migration import create_tables, drop_tables
9
+
10
+
11
+ def upgrade() -> None:
12
+ create_tables(op)
13
+
14
+
15
+ def downgrade() -> None:
16
+ drop_tables(op)
17
+ ```
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ from typing import Any
23
+
24
+ import sqlalchemy as sa
25
+ from sqlalchemy.dialects.postgresql import JSONB
26
+
27
+ from litestar_feedback.replay.models import KEY_LENGTH
28
+
29
+
30
+ def _ts(name: str, *, nullable: bool = False) -> sa.Column[Any]:
31
+ return sa.Column(name, sa.DateTime(timezone=True), nullable=nullable)
32
+
33
+
34
+ def _session_fk() -> sa.Column[Any]:
35
+ return sa.Column(
36
+ "session_id",
37
+ sa.Uuid(),
38
+ sa.ForeignKey("replay_sessions.id", ondelete="CASCADE"),
39
+ nullable=False,
40
+ )
41
+
42
+
43
+ def create_tables(op: Any) -> None:
44
+ """Create ``replay_sessions``, ``replay_chunks`` and ``replay_clicks`` with their indexes.
45
+
46
+ Args:
47
+ op: Alembic's ``op`` (``alembic.operations.Operations``).
48
+ """
49
+ key = sa.String(KEY_LENGTH)
50
+ op.create_table(
51
+ "replay_sessions",
52
+ sa.Column("id", sa.Uuid(), primary_key=True),
53
+ sa.Column("scope_id", key, nullable=False),
54
+ sa.Column("user_id", key, nullable=True),
55
+ _ts("started_at"),
56
+ _ts("last_event_at"),
57
+ sa.Column("entry_url", sa.String(500), nullable=True),
58
+ sa.Column("user_agent", sa.String(500), nullable=True),
59
+ sa.Column("current_path", sa.String(500), nullable=True),
60
+ sa.Column("viewport_w", sa.Integer(), nullable=True),
61
+ sa.Column("viewport_h", sa.Integer(), nullable=True),
62
+ sa.Column("event_count", sa.Integer(), nullable=False),
63
+ sa.Column("chunk_count", sa.Integer(), nullable=False),
64
+ sa.Column("byte_count", sa.BigInteger(), nullable=False),
65
+ sa.Column("active_ms", sa.BigInteger(), nullable=False),
66
+ sa.Column("last_input_ms", sa.BigInteger(), nullable=True),
67
+ _ts("created_at"),
68
+ )
69
+ op.create_index(
70
+ "ix_replay_sessions_scope_started", "replay_sessions", ["scope_id", "started_at"]
71
+ )
72
+ op.create_index("ix_replay_sessions_last_event_at", "replay_sessions", ["last_event_at"])
73
+ op.create_index("ix_replay_sessions_user_id", "replay_sessions", ["user_id"])
74
+
75
+ op.create_table(
76
+ "replay_chunks",
77
+ sa.Column("id", sa.Uuid(), primary_key=True),
78
+ _session_fk(),
79
+ sa.Column("scope_id", key, nullable=False),
80
+ sa.Column("seq", sa.Integer(), nullable=False),
81
+ sa.Column("first_ms", sa.BigInteger(), nullable=False),
82
+ sa.Column("last_ms", sa.BigInteger(), nullable=False),
83
+ sa.Column("snapshot_ms", sa.BigInteger(), nullable=True),
84
+ sa.Column("event_count", sa.Integer(), nullable=False),
85
+ sa.Column("byte_size", sa.Integer(), nullable=False),
86
+ sa.Column("events", sa.JSON().with_variant(JSONB(), "postgresql"), nullable=True),
87
+ sa.Column("blob_key", sa.String(512), nullable=True),
88
+ _ts("created_at"),
89
+ sa.UniqueConstraint("session_id", "seq", name="uq_replay_chunks_session_seq"),
90
+ )
91
+ op.create_index("ix_replay_chunks_session_id", "replay_chunks", ["session_id"])
92
+ op.create_index("ix_replay_chunks_scope_id", "replay_chunks", ["scope_id"])
93
+
94
+ op.create_table(
95
+ "replay_clicks",
96
+ sa.Column("id", sa.Uuid(), primary_key=True),
97
+ _session_fk(),
98
+ sa.Column("scope_id", key, nullable=False),
99
+ sa.Column("path", sa.String(500), nullable=False),
100
+ sa.Column("viewport_bucket", sa.Integer(), nullable=False),
101
+ sa.Column("x_ratio", sa.Float(), nullable=False),
102
+ sa.Column("y_px", sa.Integer(), nullable=False),
103
+ _ts("at"),
104
+ )
105
+ op.create_index("ix_replay_clicks_session_id", "replay_clicks", ["session_id"])
106
+ op.create_index("ix_replay_clicks_scope_id", "replay_clicks", ["scope_id"])
107
+ op.create_index("ix_replay_clicks_path_bucket", "replay_clicks", ["path", "viewport_bucket"])
108
+
109
+
110
+ def drop_tables(op: Any) -> None:
111
+ """Drop the three replay tables, children first."""
112
+ op.drop_table("replay_clicks")
113
+ op.drop_table("replay_chunks")
114
+ op.drop_table("replay_sessions")
@@ -0,0 +1,100 @@
1
+ """The replay tables: ``replay_sessions``, ``replay_chunks``, ``replay_clicks``.
2
+
3
+ They hang off their own ``ReplayBase`` metadata. Create them with
4
+ ``litestar_feedback.replay.migration.create_tables``.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import uuid
10
+ from datetime import datetime
11
+ from typing import Any
12
+
13
+ from sqlalchemy import BigInteger, Float, ForeignKey, Index, Integer, String, UniqueConstraint
14
+ from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
15
+
16
+ from litestar_feedback._sqltypes import JSONColumn, UTCDateTime
17
+
18
+ KEY_LENGTH = 64
19
+ """Width of the ``scope_id`` and ``user_id`` columns. Fits a UUID or a big integer as text."""
20
+
21
+
22
+ class ReplayBase(DeclarativeBase):
23
+ """Declarative base that owns the replay tables' metadata."""
24
+
25
+
26
+ class ReplaySession(ReplayBase):
27
+ """One recording: one page load of the app, with an id the browser picks.
28
+
29
+ ``byte_count`` is the JSON size of every stored chunk, so the session cap needs no sum.
30
+ ``current_path`` and ``viewport_w`` carry the page state from one chunk to the next, for
31
+ click extraction. ``active_ms`` adds up gaps of 60 s or less between user inputs.
32
+ """
33
+
34
+ __tablename__ = "replay_sessions"
35
+ __table_args__ = (
36
+ Index("ix_replay_sessions_scope_started", "scope_id", "started_at"),
37
+ Index("ix_replay_sessions_last_event_at", "last_event_at"),
38
+ )
39
+
40
+ id: Mapped[uuid.UUID] = mapped_column(primary_key=True)
41
+ scope_id: Mapped[str] = mapped_column(String(KEY_LENGTH))
42
+ user_id: Mapped[str | None] = mapped_column(String(KEY_LENGTH), index=True)
43
+ started_at: Mapped[datetime] = mapped_column(UTCDateTime)
44
+ last_event_at: Mapped[datetime] = mapped_column(UTCDateTime)
45
+ entry_url: Mapped[str | None] = mapped_column(String(500))
46
+ user_agent: Mapped[str | None] = mapped_column(String(500))
47
+ current_path: Mapped[str | None] = mapped_column(String(500))
48
+ viewport_w: Mapped[int | None] = mapped_column(Integer)
49
+ viewport_h: Mapped[int | None] = mapped_column(Integer)
50
+ event_count: Mapped[int] = mapped_column(Integer)
51
+ chunk_count: Mapped[int] = mapped_column(Integer)
52
+ byte_count: Mapped[int] = mapped_column(BigInteger)
53
+ active_ms: Mapped[int] = mapped_column(BigInteger)
54
+ last_input_ms: Mapped[int | None] = mapped_column(BigInteger)
55
+ created_at: Mapped[datetime] = mapped_column(UTCDateTime)
56
+
57
+
58
+ class ReplayChunk(ReplayBase):
59
+ """One batch of rrweb events, numbered by the browser with ``seq``.
60
+
61
+ Exactly one of ``events`` (database storage) and ``blob_key`` (``ChunkStore``) is set.
62
+ ``first_ms``, ``last_ms`` and ``snapshot_ms`` are rrweb timestamps. Playback from an offset
63
+ starts at the last chunk whose ``snapshot_ms`` is at or before the target.
64
+ """
65
+
66
+ __tablename__ = "replay_chunks"
67
+ __table_args__ = (UniqueConstraint("session_id", "seq", name="uq_replay_chunks_session_seq"),)
68
+
69
+ id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
70
+ session_id: Mapped[uuid.UUID] = mapped_column(
71
+ ForeignKey("replay_sessions.id", ondelete="CASCADE"), index=True
72
+ )
73
+ scope_id: Mapped[str] = mapped_column(String(KEY_LENGTH), index=True)
74
+ seq: Mapped[int] = mapped_column(Integer)
75
+ first_ms: Mapped[int] = mapped_column(BigInteger)
76
+ last_ms: Mapped[int] = mapped_column(BigInteger)
77
+ snapshot_ms: Mapped[int | None] = mapped_column(BigInteger)
78
+ event_count: Mapped[int] = mapped_column(Integer)
79
+ byte_size: Mapped[int] = mapped_column(Integer)
80
+ events: Mapped[list[dict[str, Any]] | None] = mapped_column(JSONColumn)
81
+ blob_key: Mapped[str | None] = mapped_column(String(512))
82
+ created_at: Mapped[datetime] = mapped_column(UTCDateTime)
83
+
84
+
85
+ class ReplayClick(ReplayBase):
86
+ """One click, kept for heatmaps. Deleted with its session."""
87
+
88
+ __tablename__ = "replay_clicks"
89
+ __table_args__ = (Index("ix_replay_clicks_path_bucket", "path", "viewport_bucket"),)
90
+
91
+ id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
92
+ session_id: Mapped[uuid.UUID] = mapped_column(
93
+ ForeignKey("replay_sessions.id", ondelete="CASCADE"), index=True
94
+ )
95
+ scope_id: Mapped[str] = mapped_column(String(KEY_LENGTH), index=True)
96
+ path: Mapped[str] = mapped_column(String(500))
97
+ viewport_bucket: Mapped[int] = mapped_column(Integer)
98
+ x_ratio: Mapped[float] = mapped_column(Float)
99
+ y_px: Mapped[int] = mapped_column(Integer)
100
+ at: Mapped[datetime] = mapped_column(UTCDateTime)