📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
import { spawn } from 'child_process'
import { createHash, randomUUID } from 'crypto'
import { createReadStream } from 'fs'
import * as fs from 'fs/promises'
import * as os from 'os'
import * as path from 'path'
import {
BadRequestException,
Injectable,
Logger,
NotFoundException,
PayloadTooLargeException,
ServiceUnavailableException,
StreamableFile,
} from '@nestjs/common'
import { InjectQueue } from '@nestjs/bullmq'
import { Queue } from 'bullmq'
import type { Response } from 'express'
import { redis } from '../common/constants'
import { hash } from '../common/utils'
import { AnalyticsService } from './analytics.service'
import { SessionReplayS3Service } from './session-replay-s3.service'
export const SESSION_REPLAY_EXPORT_QUEUE = 'session-replay-export'
type SessionReplayExportStatus =
| 'queued'
| 'processing'
| 'ready'
| 'failed'
| 'expired'
export interface SessionReplayExportResponse {
exportId: string
status: SessionReplayExportStatus
progress: number
filename: string
expiresAt: string
error?: string
}
export type SessionReplayExportJobData =
| {
type: 'export'
exportId: string
pid: string
psid: string
replayId?: string
}
| {
type: 'cleanup'
exportId: string
expiresAt: string
}
export interface SessionReplayExportState extends SessionReplayExportResponse {
pid: string
psid: string
replayId?: string
objectKey?: string
createdAt: string
updatedAt: string
}
type RrvideoEvent = Record<string, unknown> & {
type: number
timestamp: number
data: Record<string, unknown>
}
const DEFAULT_MAX_DURATION_MS = 30 * 60 * 1000
const DEFAULT_MAX_EVENTS = 100000
const DEFAULT_MAX_INPUT_BYTES = 150 * 1024 * 1024
const DEFAULT_MAX_OUTPUT_BYTES = 500 * 1024 * 1024
const DEFAULT_TTL_SECONDS = 24 * 60 * 60
const DEFAULT_RENDER_TIMEOUT_MS = 60 * 60 * 1000
const DEFAULT_VIEWPORT = { width: 1280, height: 720 }
const TMP_DIR = path.resolve(os.tmpdir(), 'swetrix-session-replay-exports')
const EXPORT_RENDERER_VERSION = 3
const RRWEB_EVENT_TYPE_FULL_SNAPSHOT = 2
const RRWEB_EVENT_TYPE_INCREMENTAL_SNAPSHOT = 3
const RRWEB_EVENT_TYPE_META = 4
const RRWEB_INCREMENTAL_SOURCE_VIEWPORT_RESIZE = 4
const getPositiveEnvNumber = (key: string, fallback: number) => {
const value = Number(process.env[key])
return Number.isFinite(value) && value > 0 ? value : fallback
}
const getExportStateKey = (exportId: string) =>
`session-replay:export:${exportId}`
@Injectable()
export class SessionReplayExportService {
private readonly logger = new Logger(SessionReplayExportService.name)
private readonly maxDurationMs = getPositiveEnvNumber(
'SESSION_REPLAY_EXPORT_MAX_DURATION_MS',
DEFAULT_MAX_DURATION_MS,
)
private readonly maxEvents = getPositiveEnvNumber(
'SESSION_REPLAY_EXPORT_MAX_EVENTS',
DEFAULT_MAX_EVENTS,
)
private readonly maxInputBytes = getPositiveEnvNumber(
'SESSION_REPLAY_EXPORT_MAX_INPUT_BYTES',
DEFAULT_MAX_INPUT_BYTES,
)
private readonly maxOutputBytes = getPositiveEnvNumber(
'SESSION_REPLAY_EXPORT_MAX_OUTPUT_BYTES',
DEFAULT_MAX_OUTPUT_BYTES,
)
private readonly ttlSeconds = getPositiveEnvNumber(
'SESSION_REPLAY_EXPORT_TTL_SECONDS',
DEFAULT_TTL_SECONDS,
)
private readonly renderTimeoutMs = getPositiveEnvNumber(
'SESSION_REPLAY_EXPORT_RENDER_TIMEOUT_MS',
DEFAULT_RENDER_TIMEOUT_MS,
)
constructor(
private readonly analyticsService: AnalyticsService,
private readonly sessionReplayStorage: SessionReplayS3Service,
@InjectQueue(SESSION_REPLAY_EXPORT_QUEUE)
private readonly exportQueue: Queue<SessionReplayExportJobData>,
) {}
async startExport(
pid: string,
psid: string,
replayId?: string,
): Promise<SessionReplayExportResponse> {
if (!this.sessionReplayStorage.isConfigured()) {
throw new ServiceUnavailableException(
'Session replay storage is not configured',
)
}
const replay = await this.analyticsService.getSessionReplaySummary(
pid,
psid,
replayId,
)
if (!replay?.hasReplay) {
throw new BadRequestException('Replay is no longer available')
}
this.validateReplayMetadata(replay.eventCount, replay.replayDuration)
const resolvedReplayId = replay.replayId || replayId
const exportReplayId = resolvedReplayId || 'session'
const exportId = hash(
`${EXPORT_RENDERER_VERSION}:${pid}:${psid}:${exportReplayId}:${replay.eventCount}:${replay.replayDuration}`,
)
const existing = await this.getState(exportId)
if (existing && !this.shouldStartNewExport(existing)) {
return this.toResponse(existing)
}
if (existing?.objectKey) {
await this.sessionReplayStorage
.deleteObject(existing.objectKey)
.catch((reason) =>
this.logger.warn(
`Failed to delete stale session replay export ${exportId}: ${
reason instanceof Error ? reason.message : String(reason)
}`,
),
)
}
const now = new Date()
const state: SessionReplayExportState = {
exportId,
pid,
psid,
replayId: resolvedReplayId,
status: 'queued',
progress: 0,
filename: this.getFilename(psid),
expiresAt: new Date(now.getTime() + this.ttlSeconds * 1000).toISOString(),
createdAt: now.toISOString(),
updatedAt: now.toISOString(),
}
await this.saveState(state)
try {
await this.exportQueue.add(
'export-session-replay',
{
type: 'export',
exportId,
pid,
psid,
replayId: resolvedReplayId,
},
{
jobId: exportId,
attempts: 1,
removeOnComplete: true,
removeOnFail: true,
},
)
} catch (reason) {
await this.markFailed(state, reason)
throw new ServiceUnavailableException('Failed to start export')
}
return this.toResponse(state)
}
async getExport(exportId: string): Promise<SessionReplayExportResponse> {
const state = await this.getState(exportId)
if (!state) {
throw new NotFoundException('Export not found')
}
if (this.isExpired(state) && state.status !== 'expired') {
await this.expireState(state)
return this.toResponse({
...state,
status: 'expired',
objectKey: undefined,
})
}
return this.toResponse(state)
}
async downloadExport(
exportId: string,
response: Response,
): Promise<StreamableFile> {
const state = await this.getState(exportId)
if (!state || this.isExpired(state) || state.status === 'expired') {
throw new NotFoundException('Export not found')
}
if (state.status !== 'ready' || !state.objectKey) {
throw new BadRequestException('Export is not ready')
}
const object = await this.sessionReplayStorage.getObjectStream(
state.objectKey,
)
if (!object) {
await this.markFailed(state, new Error('Export file is missing'))
throw new NotFoundException('Export file not found')
}
response.setHeader('Content-Type', object.contentType || 'video/mp4')
response.setHeader(
'Content-Disposition',
`attachment; filename="${state.filename}"`,
)
response.setHeader('Cache-Control', 'private, no-store')
if (object.contentLength) {
response.setHeader('Content-Length', object.contentLength)
}
return new StreamableFile(object.body)
}
async assertExportAccess(
exportId: string,
): Promise<SessionReplayExportState> {
const state = await this.getState(exportId)
if (!state) {
throw new NotFoundException('Export not found')
}
return state
}
async processExportJob(
data: Extract<SessionReplayExportJobData, { type: 'export' }>,
) {
const existing = await this.getState(data.exportId)
const state =
existing ||
({
exportId: data.exportId,
pid: data.pid,
psid: data.psid,
replayId: data.replayId,
status: 'queued',
progress: 0,
filename: this.getFilename(data.psid),
expiresAt: new Date(Date.now() + this.ttlSeconds * 1000).toISOString(),
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
} satisfies SessionReplayExportState)
let workDir: string | null = null
try {
await this.updateState(state, { status: 'processing', progress: 5 })
const { replay, events } = await this.analyticsService.getSessionReplay(
data.pid,
data.psid,
data.replayId,
)
if (!replay?.hasReplay || !events.length) {
throw new Error('Replay is no longer available')
}
this.validateReplayMetadata(replay.eventCount, replay.replayDuration)
const exportEvents = this.prepareEventsForRrvideo(events)
const durationMs = this.getReplayDurationMs(
exportEvents,
replay.replayDuration,
)
this.validateReplayDuration(durationMs)
const serializedEvents = JSON.stringify(exportEvents)
const inputBytes = Buffer.byteLength(serializedEvents)
if (inputBytes > this.maxInputBytes) {
throw new Error('Replay is too large to export')
}
workDir = path.join(TMP_DIR, `${data.exportId}-${randomUUID()}`)
await fs.mkdir(workDir, { recursive: true, mode: 0o700 })
const inputPath = path.join(workDir, 'events.json')
const configPath = path.join(workDir, 'rrvideo.config.json')
const webmPath = path.join(workDir, 'replay.webm')
const mp4Path = path.join(workDir, 'replay.mp4')
await fs.writeFile(inputPath, serializedEvents, { mode: 0o600 })
await fs.writeFile(
configPath,
JSON.stringify(this.getRrvideoConfig(exportEvents)),
{ mode: 0o600 },
)
await this.updateState(state, { status: 'processing', progress: 20 })
await this.runCommand(
this.getRrvideoBin(),
['--input', inputPath, '--output', webmPath, '--config', configPath],
{
cwd: workDir,
rejectOutput: /Error initializing replayer|Failed to transform/i,
},
)
await this.updateState(state, { status: 'processing', progress: 70 })
await this.runCommand(
this.getFfmpegBin(),
[
'-y',
'-i',
webmPath,
'-c:v',
'libx264',
'-pix_fmt',
'yuv420p',
'-movflags',
'+faststart',
mp4Path,
],
{ cwd: workDir },
)
const outputStat = await fs.stat(mp4Path)
if (outputStat.size > this.maxOutputBytes) {
throw new Error('Replay export is too large to download')
}
await this.updateState(state, { status: 'processing', progress: 90 })
const objectKey = this.getObjectKey(data.pid, data.psid, data.exportId)
const outputHash = await this.hashFile(mp4Path)
await this.sessionReplayStorage.putObject(
objectKey,
createReadStream(mp4Path),
'video/mp4',
{
contentLength: outputStat.size,
payloadHash: outputHash,
},
)
await this.updateState(state, {
status: 'ready',
progress: 100,
objectKey,
error: undefined,
})
try {
await this.exportQueue.add(
'cleanup-session-replay-export',
{
type: 'cleanup',
exportId: data.exportId,
expiresAt: state.expiresAt,
},
{
jobId: `${data.exportId}:cleanup:${hash(state.expiresAt)}`,
delay: this.ttlSeconds * 1000,
attempts: 3,
removeOnComplete: true,
removeOnFail: true,
},
)
} catch (reason) {
this.logger.warn(
`Failed to schedule session replay export cleanup ${data.exportId}: ${
reason instanceof Error ? reason.message : String(reason)
}`,
)
}
} catch (reason) {
await this.markFailed(state, reason)
throw reason
} finally {
if (workDir) {
await fs.rm(workDir, { recursive: true, force: true }).catch(() => null)
}
}
}
async cleanupExportJob(
data: Extract<SessionReplayExportJobData, { type: 'cleanup' }>,
) {
const state = await this.getState(data.exportId)
if (!state) return
if (state.expiresAt !== data.expiresAt) return
if (state.objectKey) {
try {
await this.sessionReplayStorage.deleteObject(state.objectKey)
} catch (reason) {
this.logger.warn(
`Failed to delete session replay export ${data.exportId}: ${
reason instanceof Error ? reason.message : String(reason)
}`,
)
throw reason
}
}
await this.expireState(state)
}
private validateReplayMetadata(eventCount: number, durationSeconds: number) {
if (eventCount > this.maxEvents) {
throw new PayloadTooLargeException('Replay has too many events to export')
}
this.validateReplayDuration(durationSeconds * 1000)
}
private validateReplayDuration(durationMs: number) {
if (durationMs > this.maxDurationMs) {
throw new PayloadTooLargeException('Replay is too long to export')
}
}
private prepareEventsForRrvideo(events: Record<string, unknown>[]) {
const normalised: Array<{ event: RrvideoEvent; index: number }> = []
events.forEach((event, index) => {
const normalisedEvent = this.normaliseReplayEvent(event)
if (normalisedEvent) {
normalised.push({ event: normalisedEvent, index })
}
})
normalised.sort(
(a, b) => a.event.timestamp - b.event.timestamp || a.index - b.index,
)
if (!normalised.length) {
throw new Error('Replay is no longer available')
}
const prepared = normalised.map(({ event }) => event)
if (
!prepared.some((event) => event.type === RRWEB_EVENT_TYPE_FULL_SNAPSHOT)
) {
throw new Error('Replay is missing a full snapshot')
}
const viewport = this.getReplayViewport(prepared)
const href = this.getReplayHref(prepared)
let hasMeta = false
const withMeta = prepared.map((event) => {
if (event.type !== RRWEB_EVENT_TYPE_META) return event
hasMeta = true
return {
...event,
data: {
...this.getEventData(event),
href,
width: viewport.width,
height: viewport.height,
},
}
})
if (!hasMeta) {
withMeta.unshift({
type: RRWEB_EVENT_TYPE_META,
timestamp: withMeta[0].timestamp,
data: {
href,
width: viewport.width,
height: viewport.height,
},
})
}
return withMeta
}
private normaliseReplayEvent(
event: Record<string, unknown>,
): RrvideoEvent | null {
const timestamp = Number(event.timestamp)
const type = this.normaliseEventType(event.type)
if (!Number.isFinite(timestamp) || type === null) {
return null
}
return {
...event,
type,
timestamp,
data: this.getEventData(event),
}
}
private normaliseEventType(value: unknown) {
const numeric = Number(value)
if (Number.isInteger(numeric)) return numeric
if (typeof value !== 'string') return null
const eventTypes: Record<string, number> = {
DomContentLoaded: 0,
Load: 1,
FullSnapshot: RRWEB_EVENT_TYPE_FULL_SNAPSHOT,
IncrementalSnapshot: RRWEB_EVENT_TYPE_INCREMENTAL_SNAPSHOT,
Meta: RRWEB_EVENT_TYPE_META,
Custom: 5,
Plugin: 6,
Asset: 7,
}
return eventTypes[value] ?? null
}
private getEventData(event: Record<string, unknown>) {
return event.data && typeof event.data === 'object'
? (event.data as Record<string, unknown>)
: {}
}
private getReplayDurationMs(
events: Record<string, unknown>[],
fallbackDurationSeconds: number,
) {
let minTimestamp = Infinity
let maxTimestamp = -Infinity
for (const event of events) {
const timestamp = Number(event.timestamp)
if (!Number.isFinite(timestamp)) continue
minTimestamp = Math.min(minTimestamp, timestamp)
maxTimestamp = Math.max(maxTimestamp, timestamp)
}
if (!Number.isFinite(minTimestamp) || !Number.isFinite(maxTimestamp)) {
return fallbackDurationSeconds * 1000
}
return Math.max(fallbackDurationSeconds * 1000, maxTimestamp - minTimestamp)
}
private getRrvideoConfig(events: Record<string, unknown>[]) {
const viewport = this.getReplayViewport(events)
return {
width: viewport.width,
height: viewport.height,
speed: 1,
skipInactive: false,
mouseTail: true,
}
}
private getReplayViewport(events: Record<string, unknown>[]) {
let maxWidth = 0
let maxHeight = 0
for (const event of events) {
const data = this.getEventData(event)
const isViewportEvent =
Number(event.type) === RRWEB_EVENT_TYPE_META ||
(Number(event.type) === RRWEB_EVENT_TYPE_INCREMENTAL_SNAPSHOT &&
Number(data.source) === RRWEB_INCREMENTAL_SOURCE_VIEWPORT_RESIZE)
if (!isViewportEvent) continue
const viewport = this.getViewportCandidate(data)
if (!viewport) continue
maxWidth = Math.max(maxWidth, viewport.width)
maxHeight = Math.max(maxHeight, viewport.height)
}
if (!maxWidth || !maxHeight) {
return DEFAULT_VIEWPORT
}
return this.clampViewport({ width: maxWidth, height: maxHeight })
}
private getViewportCandidate(data: Record<string, unknown>) {
const width = Number(data.width)
const height = Number(data.height)
if (
!Number.isFinite(width) ||
!Number.isFinite(height) ||
width <= 0 ||
height <= 0
) {
return null
}
return {
width: Math.round(width),
height: Math.round(height),
}
}
private clampViewport(viewport: { width: number; height: number }) {
return {
width: Math.min(1920, Math.max(320, viewport.width)),
height: Math.min(1080, Math.max(240, viewport.height)),
}
}
private getReplayHref(events: Record<string, unknown>[]) {
for (const event of events) {
if (Number(event.type) !== RRWEB_EVENT_TYPE_META) continue
const href = this.getEventData(event).href
if (typeof href === 'string' && href) {
return this.getSafeReplayHref(href)
}
}
return 'about:blank'
}
private getSafeReplayHref(href: string) {
try {
const url = new URL(href)
if (url.protocol === 'https:' || url.protocol === 'http:') {
return url.toString()
}
} catch {
return 'about:blank'
}
return 'about:blank'
}
private async hashFile(filePath: string) {
const digest = createHash('sha256')
await new Promise<void>((resolve, reject) => {
const stream = createReadStream(filePath)
stream.on('data', (chunk) => digest.update(chunk))
stream.on('error', reject)
stream.on('end', resolve)
})
return digest.digest('hex')
}
private async runCommand(
command: string,
args: string[],
options: { cwd?: string; rejectOutput?: RegExp } = {},
) {
await new Promise<void>((resolve, reject) => {
let settled = false
let output = ''
const child = spawn(command, args, {
cwd: options.cwd,
stdio: ['ignore', 'pipe', 'pipe'],
})
const timeout = setTimeout(() => {
if (settled) return
settled = true
child.kill('SIGKILL')
reject(new Error(`${path.basename(command)} timed out`))
}, this.renderTimeoutMs)
const captureOutput = (chunk: Buffer) => {
output = `${output}${chunk.toString()}`
if (output.length > 8000) {
output = output.slice(-8000)
}
}
child.stdout.on('data', captureOutput)
child.stderr.on('data', captureOutput)
child.on('error', (reason) => {
if (settled) return
settled = true
clearTimeout(timeout)
reject(reason)
})
child.on('close', (code) => {
if (settled) return
settled = true
clearTimeout(timeout)
if (code === 0) {
if (options.rejectOutput?.test(output)) {
reject(
new Error(
`${path.basename(command)} reported a renderer error: ${output}`,
),
)
return
}
resolve()
return
}
reject(
new Error(
`${path.basename(command)} failed with status ${code}: ${output}`,
),
)
})
})
}
private getRrvideoBin() {
return (
process.env.RRVIDEO_BIN ||
path.join(
process.cwd(),
'node_modules',
'.bin',
process.platform === 'win32' ? 'rrvideo.cmd' : 'rrvideo',
)
)
}
private getFfmpegBin() {
return process.env.FFMPEG_BIN || 'ffmpeg'
}
private getObjectKey(pid: string, psid: string, exportId: string) {
return ['session-replay-exports', pid, psid, `${exportId}.mp4`].join('/')
}
private getFilename(psid: string) {
const safePsid = psid.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 80)
return `swetrix-replay-${safePsid || 'session'}.mp4`
}
private async getState(
exportId: string,
): Promise<SessionReplayExportState | null> {
const raw = await redis.get(getExportStateKey(exportId))
if (!raw) return null
try {
return JSON.parse(raw) as SessionReplayExportState
} catch {
return null
}
}
private async saveState(state: SessionReplayExportState) {
await redis.set(
getExportStateKey(state.exportId),
JSON.stringify(state),
'EX',
this.ttlSeconds + 24 * 60 * 60,
)
}
private async updateState(
state: SessionReplayExportState,
update: Partial<SessionReplayExportState>,
) {
const next = {
...state,
...update,
updatedAt: new Date().toISOString(),
}
Object.assign(state, next)
await this.saveState(next)
return next
}
private async markFailed(state: SessionReplayExportState, reason: unknown) {
this.logger.error(
`Session replay export ${state.exportId} failed: ${this.getDetailedError(
reason,
)}`,
)
await this.updateState(state, {
status: 'failed',
progress: 100,
error: this.getPublicError(reason),
objectKey: undefined,
})
}
private async expireState(state: SessionReplayExportState) {
await this.updateState(state, {
status: 'expired',
progress: 100,
objectKey: undefined,
error: undefined,
})
}
private isExpired(state: SessionReplayExportState) {
return Date.parse(state.expiresAt) <= Date.now()
}
private shouldStartNewExport(state: SessionReplayExportState) {
return (
this.isExpired(state) ||
state.status === 'expired' ||
state.status === 'failed'
)
}
private getPublicError(reason: unknown) {
const message = this.getDetailedError(reason)
if (message.includes('Replay is no longer available')) {
return 'Replay is no longer available'
}
if (
message.includes('too large') ||
message.includes('too long') ||
message.includes('too many events')
) {
return 'Replay is too large to export'
}
return 'Could not export replay to MP4'
}
private getDetailedError(reason: unknown) {
return reason instanceof Error
? reason.stack || reason.message
: String(reason)
}
private toResponse(
state: SessionReplayExportState,
): SessionReplayExportResponse {
return {
exportId: state.exportId,
status: state.status,
progress: state.progress,
filename: state.filename,
expiresAt: state.expiresAt,
...(state.error ? { error: state.error } : {}),
}
}
}