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.
- litestar_feedback/__init__.py +7 -0
- litestar_feedback/_sqltypes.py +41 -0
- litestar_feedback/caller.py +48 -0
- litestar_feedback/py.typed +0 -0
- litestar_feedback/replay/__init__.py +45 -0
- litestar_feedback/replay/adapter.py +101 -0
- litestar_feedback/replay/events.py +159 -0
- litestar_feedback/replay/migration.py +114 -0
- litestar_feedback/replay/models.py +100 -0
- litestar_feedback/replay/plugin.py +66 -0
- litestar_feedback/replay/routes.py +257 -0
- litestar_feedback/replay/service.py +411 -0
- litestar_feedback/support/__init__.py +52 -0
- litestar_feedback/support/adapter.py +109 -0
- litestar_feedback/support/contract.py +579 -0
- litestar_feedback/support/migration.py +129 -0
- litestar_feedback/support/models.py +160 -0
- litestar_feedback/support/plugin.py +43 -0
- litestar_feedback/support/pytest_plugin.py +63 -0
- litestar_feedback/support/routes.py +455 -0
- litestar_feedback/support/schemas.py +135 -0
- litestar_feedback/support/service.py +792 -0
- litestar_feedback-0.2.1.dist-info/METADATA +299 -0
- litestar_feedback-0.2.1.dist-info/RECORD +27 -0
- litestar_feedback-0.2.1.dist-info/WHEEL +4 -0
- litestar_feedback-0.2.1.dist-info/entry_points.txt +2 -0
- litestar_feedback-0.2.1.dist-info/licenses/LICENSE +21 -0
|
@@ -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)
|