session replays (#1187)

https://www.loom.com/share/3b7c9288149e4f878693281778c9d7e0




## Todos (future PRs)
- Fix pre-login recording
- Better session search (filters, cmd-k, etc)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Analytics → Replays: session recording & multi-tab replay with
timeline, speed, seek, and playback settings; dashboard UI for listing
and viewing replays.

* **Admin APIs**
* Admin endpoints to list recordings, list chunks, fetch chunk events,
and retrieve all events (paginated).

* **Client**
* Client-side rrweb recording with batching, deduplication, upload API
and a send-batch client method.

* **Configuration**
  * New STACK_S3_PRIVATE_BUCKET for private session storage.

* **Tests**
* Extensive unit and end-to-end tests for replay logic, streams,
playback, and APIs.

* **Chores**
  * Removed an E2E API test GitHub Actions workflow.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: BilalG1

CLAUDE.md

@@ -67,6 +67,7 @@ STACK_S3_REGION=
 STACK_S3_ACCESS_KEY_ID=
 STACK_S3_SECRET_ACCESS_KEY=
 STACK_S3_BUCKET=
+STACK_S3_PRIVATE_BUCKET=
 
 # AWS configuration
 STACK_AWS_REGION=

apps/backend/.env

@@ -74,6 +74,7 @@ STACK_S3_REGION=us-east-1
 STACK_S3_ACCESS_KEY_ID=s3mockroot
 STACK_S3_SECRET_ACCESS_KEY=s3mockroot
 STACK_S3_BUCKET=stack-storage
+STACK_S3_PRIVATE_BUCKET=stack-storage-private
 
 # AWS region defaults to LocalStack
 STACK_AWS_REGION=us-east-1

apps/backend/.env.development

@@ -0,0 +1,60 @@
+-- Session recording MVP: store session metadata in Postgres and rrweb events in S3.
+
+CREATE TABLE "SessionRecording" (
+  "id" UUID NOT NULL,
+  "tenancyId" UUID NOT NULL,
+  "projectUserId" UUID NOT NULL,
+  "refreshTokenId" UUID NOT NULL,
+  "startedAt" TIMESTAMP(3) NOT NULL,
+  "lastEventAt" TIMESTAMP(3) NOT NULL,
+  "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt" TIMESTAMP(3) NOT NULL,
+  CONSTRAINT "SessionRecording_pkey" PRIMARY KEY ("tenancyId","id")
+);
+
+CREATE TABLE "SessionRecordingChunk" (
+  "id" UUID NOT NULL,
+  "tenancyId" UUID NOT NULL,
+  "sessionRecordingId" UUID NOT NULL,
+  "batchId" UUID NOT NULL,
+  "tabId" TEXT NOT NULL,
+  "browserSessionId" TEXT NOT NULL,
+  "s3Key" TEXT NOT NULL,
+  "eventCount" INTEGER NOT NULL,
+  "byteLength" INTEGER NOT NULL,
+  "firstEventAt" TIMESTAMP(3) NOT NULL,
+  "lastEventAt" TIMESTAMP(3) NOT NULL,
+  "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "SessionRecordingChunk_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "SessionRecording"
+  ADD CONSTRAINT "SessionRecording_tenancyId_fkey"
+  FOREIGN KEY ("tenancyId") REFERENCES "Tenancy"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "SessionRecording"
+  ADD CONSTRAINT "SessionRecording_tenancyId_projectUserId_fkey"
+  FOREIGN KEY ("tenancyId", "projectUserId") REFERENCES "ProjectUser"("tenancyId", "projectUserId") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "SessionRecordingChunk"
+  ADD CONSTRAINT "SessionRecordingChunk_tenancyId_fkey"
+  FOREIGN KEY ("tenancyId") REFERENCES "Tenancy"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "SessionRecordingChunk"
+  ADD CONSTRAINT "SessionRecordingChunk_tenancyId_sessionRecordingId_fkey"
+  FOREIGN KEY ("tenancyId","sessionRecordingId") REFERENCES "SessionRecording"("tenancyId","id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+CREATE INDEX "SessionRecording_tenancyId_projectUserId_startedAt_idx"
+  ON "SessionRecording"("tenancyId", "projectUserId", "startedAt");
+
+CREATE INDEX "SessionRecording_tenancyId_lastEventAt_idx"
+  ON "SessionRecording"("tenancyId", "lastEventAt");
+
+CREATE INDEX "SessionRecording_tenancyId_refreshTokenId_updatedAt_idx"
+  ON "SessionRecording"("tenancyId", "refreshTokenId", "updatedAt");
+
+CREATE UNIQUE INDEX "SessionRecordingChunk_tenancyId_sessionRecordingId_batchId_key"
+  ON "SessionRecordingChunk"("tenancyId", "sessionRecordingId", "batchId");
+
+CREATE INDEX "SessionRecordingChunk_tenancyId_sessionRecordingId_createdA_idx"
+  ON "SessionRecordingChunk"("tenancyId", "sessionRecordingId", "createdAt");

apps/backend/prisma/migrations/20260210120000_session_recordings_mvp/migration.sql

@@ -60,6 +60,8 @@ model Tenancy {
   organizationId    String?       @db.Uuid
   hasNoOrganization BooleanTrue?
   emailOutboxes     EmailOutbox[]
+  sessionRecordings SessionRecording[]
+  sessionRecordingChunks SessionRecordingChunk[]
 
   @@unique([projectId, branchId, organizationId])
   @@unique([projectId, branchId, hasNoOrganization])
@@ -234,6 +236,7 @@ model ProjectUser {
   Project                    Project?                      @relation(fields: [projectId], references: [id])
   projectId                  String?
   userNotificationPreference UserNotificationPreference[]
+  sessionRecordings          SessionRecording[]
 
   @@id([tenancyId, projectUserId])
   @@unique([mirroredProjectId, mirroredBranchId, projectUserId])
@@ -277,6 +280,62 @@ model ProjectUserOAuthAccount {
   @@index([tenancyId, projectUserId])
 }
 
+model SessionRecording {
+  id String @db.Uuid
+
+  tenancyId      String @db.Uuid
+  projectUserId  String @db.Uuid
+  refreshTokenId String @db.Uuid
+
+  startedAt   DateTime
+  lastEventAt DateTime
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  projectUser ProjectUser @relation(fields: [tenancyId, projectUserId], references: [tenancyId, projectUserId], onDelete: Cascade)
+  tenancy     Tenancy     @relation(fields: [tenancyId], references: [id], onDelete: Cascade)
+
+  chunks SessionRecordingChunk[]
+
+  @@id([tenancyId, id])
+  @@index([tenancyId, projectUserId, startedAt])
+  @@index([tenancyId, lastEventAt])
+  // index by updatedAt instead of lastEventAt because event timing can be spoofed
+  @@index([tenancyId, refreshTokenId, updatedAt])
+}
+
+model SessionRecordingChunk {
+  id String @id @default(uuid()) @db.Uuid
+
+  tenancyId          String @db.Uuid
+  sessionRecordingId String @db.Uuid
+
+  // Unique per uploaded batch for a given session id.
+  batchId String @db.Uuid
+
+  // Ephemeral in-memory id generated by the client. Stored for future tab separation if needed.
+  tabId String
+
+  // Client-generated session id from localStorage, stored as metadata.
+  browserSessionId String
+
+  s3Key      String
+  eventCount Int
+  byteLength Int
+
+  firstEventAt DateTime
+  lastEventAt  DateTime
+
+  createdAt DateTime @default(now())
+
+  sessionRecording SessionRecording @relation(fields: [tenancyId, sessionRecordingId], references: [tenancyId, id], onDelete: Cascade)
+  tenancy         Tenancy          @relation(fields: [tenancyId], references: [id], onDelete: Cascade)
+
+  @@unique([tenancyId, sessionRecordingId, batchId])
+  @@index([tenancyId, sessionRecordingId, createdAt])
+}
+
 enum ContactChannelType {
   EMAIL
   // PHONE

apps/backend/prisma/schema.prisma

@@ -1118,6 +1118,13 @@ async function seedDummyProject(options: DummyProjectSeedOptions) {
     userEmailToId,
   });
 
+  await seedDummySessionRecordings({
+    prisma: dummyPrisma,
+    tenancyId: dummyTenancy.id,
+    userEmailToId,
+    targetSessionRecordingCount: 75
+  });
+
   console.log('Seeded dummy project data');
 }
 
@@ -1765,3 +1772,65 @@ async function seedDummySessionActivityEvents(options: SessionActivityEventSeedO
 
   console.log('Finished seeding session activity events');
 }
+
+type SessionRecordingSeedOptions = {
+  prisma: PrismaClientTransaction,
+  tenancyId: string,
+  userEmailToId: Map<string, string>,
+  targetSessionRecordingCount?: number,
+};
+
+async function seedDummySessionRecordings(options: SessionRecordingSeedOptions) {
+  const {
+    prisma,
+    tenancyId,
+    userEmailToId,
+    targetSessionRecordingCount = 250,
+  } = options;
+
+  const existingCount = await prisma.sessionRecording.count({
+    where: {
+      tenancyId,
+    },
+  });
+
+  if (existingCount >= targetSessionRecordingCount) {
+    console.log(`Dummy project already has ${existingCount} session recordings, skipping seeding`);
+    return;
+  }
+
+  const toCreate = targetSessionRecordingCount - existingCount;
+  const userIds = Array.from(userEmailToId.values());
+  if (userIds.length === 0) {
+    throw new Error('Cannot seed session recordings: no dummy project users exist');
+  }
+
+  const now = new Date();
+  const twoWeeksAgo = new Date(now);
+  twoWeeksAgo.setDate(twoWeeksAgo.getDate() - 14);
+
+  const seeds: Prisma.SessionRecordingCreateManyInput[] = [];
+  for (let i = 0; i < toCreate; i++) {
+    const startedAt = new Date(
+      twoWeeksAgo.getTime() + Math.random() * (now.getTime() - twoWeeksAgo.getTime()),
+    );
+    const durationMs = 10_000 + Math.floor(Math.random() * (20 * 60 * 1000)); // 10s..20m
+    const lastEventAt = new Date(startedAt.getTime() + durationMs);
+    const projectUserId = userIds[Math.floor(Math.random() * userIds.length)]!;
+
+    seeds.push({
+      tenancyId,
+      refreshTokenId: generateUuid(),
+      projectUserId,
+      id: generateUuid(),
+      startedAt,
+      lastEventAt,
+    });
+  }
+
+  await prisma.sessionRecording.createMany({
+    data: seeds,
+  });
+
+  console.log(`Seeded ${toCreate} session recordings`);
+}

apps/backend/prisma/seed.ts

@@ -0,0 +1,91 @@
+import { getPrismaClientForTenancy } from "@/prisma-client";
+import { downloadBytes } from "@/s3";
+import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { KnownErrors } from "@stackframe/stack-shared";
+import { StackAssertionError } from "@stackframe/stack-shared/dist/utils/errors";
+import { adaptSchema, adminAuthTypeSchema, yupArray, yupMixed, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
+import { promisify } from "node:util";
+import { gunzip as gunzipCb } from "node:zlib";
+
+const gunzip = promisify(gunzipCb);
+
+export const GET = createSmartRouteHandler({
+  metadata: { hidden: true },
+  request: yupObject({
+    auth: yupObject({
+      type: adminAuthTypeSchema.defined(),
+      tenancy: adaptSchema.defined(),
+    }).defined(),
+    params: yupObject({
+      session_recording_id: yupString().defined(),
+      chunk_id: yupString().defined(),
+    }).defined(),
+  }),
+  response: yupObject({
+    statusCode: yupNumber().oneOf([200]).defined(),
+    bodyType: yupString().oneOf(["json"]).defined(),
+    body: yupObject({
+      events: yupArray(yupMixed().defined()).defined(),
+    }).defined(),
+  }),
+  async handler({ auth, params }) {
+    const prisma = await getPrismaClientForTenancy(auth.tenancy);
+
+    const sessionRecordingId = params.session_recording_id;
+    const chunkId = params.chunk_id;
+
+    const chunk = await prisma.sessionRecordingChunk.findFirst({
+      where: {
+        tenancyId: auth.tenancy.id,
+        sessionRecordingId,
+        id: chunkId,
+      },
+      select: {
+        s3Key: true,
+      },
+    });
+    if (!chunk) {
+      throw new KnownErrors.ItemNotFound(chunkId);
+    }
+
+    let bytes: Uint8Array;
+    try {
+      bytes = await downloadBytes({ key: chunk.s3Key, private: true });
+    } catch (e: any) {
+      const status = e?.$metadata?.httpStatusCode;
+      if (status === 404) {
+        throw new KnownErrors.ItemNotFound(chunkId);
+      }
+      throw e;
+    }
+    const unzipped = new Uint8Array(await gunzip(bytes));
+
+    let parsed: any;
+    try {
+      parsed = JSON.parse(new TextDecoder().decode(unzipped));
+    } catch (e) {
+      throw new StackAssertionError("Failed to decode session recording chunk JSON", { cause: e });
+    }
+
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new StackAssertionError("Decoded session recording chunk is not an object");
+    }
+    if (parsed.session_recording_id !== sessionRecordingId) {
+      throw new StackAssertionError("Decoded session recording chunk session_recording_id mismatch", {
+        expected: sessionRecordingId,
+        actual: parsed.session_recording_id,
+      });
+    }
+    if (!Array.isArray(parsed.events)) {
+      throw new StackAssertionError("Decoded session recording chunk events is not an array");
+    }
+
+    return {
+      statusCode: 200,
+      bodyType: "json",
+      body: {
+        events: parsed.events,
+      },
+    };
+  },
+});