Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Enhance session replay management and usage tracking

Bill Yangf5a5334bb158
diff --git a/server/package.json b/server/package.json
index 56ab00c65..d2c485953 100644
--- a/server/package.json
+++ b/server/package.json
@@ -25,7 +25,8 @@
"knip": "knip",
"format": "prettier --write \"src/**/*.{js,ts,json,md}\"",
"format:check": "prettier --check \"src/**/*.{js,ts,json,md}\"",
- "backfill:lite-mvs": "tsc && node dist/scripts/backfillLiteDashboardMVs.js"
+ "backfill:lite-mvs": "tsc && node dist/scripts/backfillLiteDashboardMVs.js",
+ "replays:disable-unentitled": "tsc && node dist/scripts/disableUnentitledReplays.js"
},
"dependencies": {
"@aws-sdk/client-s3": "^3.842.0",
diff --git a/server/src/api/sessionReplay/recordSessionReplay.ts b/server/src/api/sessionReplay/recordSessionReplay.ts
index bd08fc01c..b9e56ba61 100644
--- a/server/src/api/sessionReplay/recordSessionReplay.ts
+++ b/server/src/api/sessionReplay/recordSessionReplay.ts
@@ -54,6 +54,13 @@ export async function recordSessionReplay(
return reply.status(200).send("Site over monthly limit, event not tracked");
}
+ // Check if the site's plan includes session replay (e.g. it may have been
+ // enabled before a downgrade from Pro)
+ if (usageService.isSiteWithoutReplay(Number(siteId))) {
+ logger.info(`[SessionReplay] Skipping event for site ${siteId} - plan does not include session replay`);
+ return reply.status(200).send({ success: true, message: "Session replay not included in plan" });
+ }
+
const body = recordSessionReplaySchema.parse(request.body) as RecordSessionReplayRequest;
// Check if the IP should be excluded from tracking
diff --git a/server/src/api/sites/getTrackingConfig.ts b/server/src/api/sites/getTrackingConfig.ts
index 13d144661..a8af37933 100644
--- a/server/src/api/sites/getTrackingConfig.ts
+++ b/server/src/api/sites/getTrackingConfig.ts
@@ -1,5 +1,6 @@
import { FastifyReply, FastifyRequest } from "fastify";
import { siteConfig } from "../../lib/siteConfig.js";
+import { usageService } from "../../services/usageService.js";
export async function getTrackingConfig(request: FastifyRequest<{ Params: { siteId: string } }>, reply: FastifyReply) {
try {
@@ -10,11 +11,18 @@ export async function getTrackingConfig(request: FastifyRequest<{ Params: { site
return reply.status(404).send({ error: "Site not found" });
}
+ // Report replay as off when the plan doesn't include it so the tracking script
+ // never loads the recorder (replay payloads would be dropped at ingest anyway)
+ const sessionReplay =
+ config.type === "mobile"
+ ? false
+ : (config.sessionReplay && !usageService.isSiteWithoutReplay(config.siteId)) || false;
+
// Return tracking configuration
// This endpoint is public since the analytics script needs to fetch it
return reply.send({
type: config.type,
- sessionReplay: config.type === "mobile" ? false : config.sessionReplay || false,
+ sessionReplay,
webVitals: config.type === "mobile" ? false : config.webVitals || false,
trackErrors: config.trackErrors || false,
trackOutbound: config.trackOutbound ?? true,
diff --git a/server/src/api/sites/updateSiteConfig.ts b/server/src/api/sites/updateSiteConfig.ts
index ca303c79c..00fa1c8d8 100644
--- a/server/src/api/sites/updateSiteConfig.ts
+++ b/server/src/api/sites/updateSiteConfig.ts
@@ -1,10 +1,12 @@
import { FastifyReply, FastifyRequest } from "fastify";
import { z } from "zod";
import { db } from "../../db/postgres/postgres.js";
-import { sites } from "../../db/postgres/schema.js";
+import { organization, sites } from "../../db/postgres/schema.js";
import { eq } from "drizzle-orm";
+import { IS_CLOUD } from "../../lib/const.js";
import { siteConfig } from "../../lib/siteConfig.js";
import { validateIPPattern } from "../../lib/ipUtils.js";
+import { getBestSubscription, subscriptionIncludesReplay } from "../../lib/subscriptionUtils.js";
// Schema for the update request - all fields are optional but validated when present
const updateSiteConfigSchema = z.object({
@@ -111,6 +113,27 @@ export async function updateSiteConfig(
});
}
+ // Session replay is a Pro feature β€” block enabling it (turning it off is always allowed)
+ if (IS_CLOUD && updateData.sessionReplay === true) {
+ let includesReplay = false;
+ if (site.organizationId) {
+ const orgResult = await db
+ .select({ stripeCustomerId: organization.stripeCustomerId })
+ .from(organization)
+ .where(eq(organization.id, site.organizationId))
+ .limit(1);
+ const subscription = await getBestSubscription(site.organizationId, orgResult[0]?.stripeCustomerId ?? null);
+ includesReplay = subscriptionIncludesReplay(subscription);
+ }
+
+ if (!includesReplay) {
+ return reply.status(403).send({
+ success: false,
+ error: "Session replay requires a Pro plan",
+ });
+ }
+ }
+
// Additional validation for excluded IPs if provided
if (updateData.excludedIPs) {
const validationErrors: string[] = [];
diff --git a/server/src/cluster.ts b/server/src/cluster.ts
index 24cab5313..f35ca29b0 100644
--- a/server/src/cluster.ts
+++ b/server/src/cluster.ts
@@ -24,10 +24,7 @@ process.on("unhandledRejection", reason => {
// Determine worker count from environment variable
// Default to 0 (single-process mode) if not set
const requestedWorkers = process.env.CLUSTER_WORKERS;
-const workerCount =
- requestedWorkers === undefined || requestedWorkers === ""
- ? 0
- : parseInt(requestedWorkers, 10);
+const workerCount = requestedWorkers === undefined || requestedWorkers === "" ? 0 : parseInt(requestedWorkers, 10);
if (workerCount === 0) {
// Single-process mode β€” no clustering, same as running index.ts directly
@@ -53,9 +50,9 @@ if (workerCount === 0) {
reengagementService.startReengagementCron();
}
- // Broadcast sitesOverLimit to workers after each usage update
+ // Broadcast usage state (sitesOverLimit + sitesWithoutReplay) to workers after each usage update
usageService.onUsageUpdated(() => {
- broadcastSitesOverLimit();
+ broadcastUsageState();
});
// Fork workers
@@ -65,11 +62,11 @@ if (workerCount === 0) {
cluster.fork();
}
- // Send current sitesOverLimit to a worker when it comes online
- cluster.on("online", (worker) => {
+ // Send current usage state to a worker when it comes online
+ cluster.on("online", worker => {
logger.info(`Worker ${worker.process.pid} is online`);
- const siteIds = Array.from(usageService.getSitesOverLimit());
- worker.send({ type: "sites-over-limit", siteIds });
+ worker.send({ type: "sites-over-limit", siteIds: Array.from(usageService.getSitesOverLimit()) });
+ worker.send({ type: "sites-without-replay", siteIds: Array.from(usageService.getSitesWithoutReplay()) });
});
// Auto-restart crashed workers (unless shutting down)
@@ -78,24 +75,26 @@ if (workerCount === 0) {
logger.info(`Worker ${worker.process.pid} exited during shutdown`);
return;
}
- logger.warn(
- `Worker ${worker.process.pid} died (code: ${code}, signal: ${signal}). Restarting...`
- );
+ logger.warn(`Worker ${worker.process.pid} died (code: ${code}, signal: ${signal}). Restarting...`);
cluster.fork();
});
/**
- * Broadcast the current sitesOverLimit set to all alive workers via IPC
+ * Broadcast the current sitesOverLimit and sitesWithoutReplay sets to all alive workers via IPC
*/
- function broadcastSitesOverLimit() {
- const siteIds = Array.from(usageService.getSitesOverLimit());
+ function broadcastUsageState() {
+ const overLimitIds = Array.from(usageService.getSitesOverLimit());
+ const withoutReplayIds = Array.from(usageService.getSitesWithoutReplay());
for (const id in cluster.workers) {
const worker = cluster.workers[id];
if (worker && !worker.isDead()) {
- worker.send({ type: "sites-over-limit", siteIds });
+ worker.send({ type: "sites-over-limit", siteIds: overLimitIds });
+ worker.send({ type: "sites-without-replay", siteIds: withoutReplayIds });
}
}
- logger.debug(`Broadcasted ${siteIds.length} sites-over-limit to workers`);
+ logger.debug(
+ `Broadcasted ${overLimitIds.length} sites-over-limit and ${withoutReplayIds.length} sites-without-replay to workers`
+ );
}
// Graceful shutdown
@@ -130,8 +129,8 @@ if (workerCount === 0) {
);
const workerExitPromises = activeWorkers.map(
- (worker) =>
- new Promise<void>((resolve) => {
+ worker =>
+ new Promise<void>(resolve => {
worker.on("exit", () => resolve());
})
);
diff --git a/server/src/index.ts b/server/src/index.ts
index 2a85fc4c5..5179a48b7 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -492,6 +492,9 @@ const start = async () => {
if (message?.type === "sites-over-limit") {
usageService.setSitesOverLimit(new Set(message.siteIds));
server.log.debug(`Received ${message.siteIds.length} sites-over-limit from primary`);
+ } else if (message?.type === "sites-without-replay") {
+ usageService.setSitesWithoutReplay(new Set(message.siteIds));
+ server.log.debug(`Received ${message.siteIds.length} sites-without-replay from primary`);
}
});
}
diff --git a/server/src/lib/subscriptionUtils.ts b/server/src/lib/subscriptionUtils.ts
index d339f045a..8cbbd1eda 100644
--- a/server/src/lib/subscriptionUtils.ts
+++ b/server/src/lib/subscriptionUtils.ts
@@ -254,8 +254,7 @@ export async function getAllStripeSubscriptionsByCustomer(): Promise<Map<string,
limit: 100,
expand: ["data.plan.product"],
})) {
- const customerId =
- typeof subscription.customer === "string" ? subscription.customer : subscription.customer.id;
+ const customerId = typeof subscription.customer === "string" ? subscription.customer : subscription.customer.id;
const existing = byCustomer.get(customerId);
if (!existing || rankSubscription(subscription) > rankSubscription(existing)) {
byCustomer.set(customerId, subscription);
@@ -529,6 +528,32 @@ export async function getBestSubscriptionFromStripeSub(
return freeSubscription();
}
+/**
+ * Whether a subscription's plan includes session replay.
+ *
+ * Replays are a Pro feature (see pricing page / PRO_FEATURES). This mirrors the
+ * client-side gate in EnableSessionReplay/TrackingTab, including the exclusion of
+ * large (>=500k event) trials. The per-plan `limits.replays` numbers in const.ts are
+ * a volume quota, not an entitlement β€” basic/standard plans carry them but do not
+ * include the feature.
+ */
+export function subscriptionIncludesReplay(subscription: SubscriptionInfo): boolean {
+ switch (subscription.source) {
+ case "custom":
+ // Bespoke enterprise plans include everything in Pro
+ return true;
+ case "override":
+ return subscription.planName.includes("pro");
+ case "stripe": {
+ const isLargeTrial = subscription.status === "trialing" && subscription.eventLimit >= 500_000;
+ return subscription.planName.includes("pro") && !isLargeTrial;
+ }
+ case "appsumo":
+ case "free":
+ return false;
+ }
+}
+
function freeSubscription(): FreeSubscriptionInfo {
return {
source: "free",
diff --git a/server/src/scripts/disableUnentitledReplays.ts b/server/src/scripts/disableUnentitledReplays.ts
new file mode 100644
index 000000000..e50e2e0df
--- /dev/null
+++ b/server/src/scripts/disableUnentitledReplays.ts
@@ -0,0 +1,149 @@
+// Lists β€” and with --apply, disables β€” session replay for sites whose organization's
+// plan does not include it (e.g. replay was enabled on Pro, then the org downgraded).
+// Uses the same entitlement rule as the usage cron and the site-config API
+// (subscriptionIncludesReplay), so the cleanup matches live enforcement exactly.
+//
+// Orgs whose Stripe price ID is missing from const.ts resolve to "Unknown Plan" and
+// CANNOT be classified β€” they are listed for manual review and never auto-disabled.
+//
+// Usage:
+// tsc && node dist/scripts/disableUnentitledReplays.js # verify only, no writes
+// tsc && node dist/scripts/disableUnentitledReplays.js --apply # set sessionReplay = false
+
+import { eq, inArray } from "drizzle-orm";
+import { db } from "../db/postgres/postgres.js";
+import { organization, sites } from "../db/postgres/schema.js";
+import { stripe } from "../lib/stripe.js";
+import {
+ getAllStripeSubscriptionsByCustomer,
+ getBestSubscriptionFromStripeSub,
+ stripeSubscriptionInfoFromSnapshot,
+ subscriptionIncludesReplay,
+} from "../lib/subscriptionUtils.js";
+
+const apply = process.argv.includes("--apply");
+
+// How many orgs to resolve at once. Each org costs 2-3 sequential Postgres round-trips
+// (custom plan, override, possibly AppSumo), which is painfully slow one-org-at-a-time
+// over a tunnel to a remote database.
+const CONCURRENCY = 10;
+
+const startTime = Date.now();
+function log(message: string) {
+ console.log(`[${((Date.now() - startTime) / 1000).toFixed(1)}s] ${message}`);
+}
+
+if (!stripe) {
+ // Without Stripe credentials every Stripe-billed org resolves to free tier and
+ // would be wrongly flagged β€” refuse to do anything rather than produce a bad list.
+ console.error("STRIPE_SECRET_KEY is not set; refusing to run.");
+ process.exit(1);
+}
+
+log("Querying sites with session replay enabled...");
+const replaySites = await db
+ .select({
+ siteId: sites.siteId,
+ domain: sites.domain,
+ organizationId: sites.organizationId,
+ })
+ .from(sites)
+ .where(eq(sites.sessionReplay, true));
+
+log(`${replaySites.length} sites have session replay enabled.`);
+if (replaySites.length === 0) {
+ process.exit(0);
+}
+
+const orgIds = [...new Set(replaySites.map(s => s.organizationId).filter((id): id is string => id !== null))];
+log(`Loading ${orgIds.length} organizations...`);
+const orgs = orgIds.length
+ ? await db
+ .select({ id: organization.id, name: organization.name, stripeCustomerId: organization.stripeCustomerId })
+ .from(organization)
+ .where(inArray(organization.id, orgIds))
+ : [];
+const orgById = new Map(orgs.map(o => [o.id, o]));
+
+log("Fetching all Stripe subscriptions (paginated, 100/request β€” may take a while on large accounts)...");
+const stripeSnapshot = await getAllStripeSubscriptionsByCustomer();
+log(`Stripe snapshot loaded: subscriptions for ${stripeSnapshot.size} customers.`);
+
+type FlaggedSite = { siteId: number; domain: string | null; org: string; plan: string };
+
+const toDisable: FlaggedSite[] = [];
+const needsReview: FlaggedSite[] = [];
+let entitledOrgs = 0;
+
+log(`Resolving plan entitlement for ${orgIds.length} organizations (concurrency ${CONCURRENCY})...`);
+for (let i = 0; i < orgIds.length; i += CONCURRENCY) {
+ const chunk = orgIds.slice(i, i + CONCURRENCY);
+ await Promise.all(
+ chunk.map(async orgId => {
+ const org = orgById.get(orgId);
+ const stripeSub = stripeSubscriptionInfoFromSnapshot(stripeSnapshot, org?.stripeCustomerId ?? null);
+ const subscription = await getBestSubscriptionFromStripeSub(orgId, stripeSub);
+
+ // A Stripe price ID missing from const.ts resolves to "Unknown Plan" β€” we can't
+ // tell whether it's pro, so park it for manual review instead of disabling.
+ const isUnknownPlan = subscription.source === "stripe" && subscription.planName === "Unknown Plan";
+
+ if (!isUnknownPlan && subscriptionIncludesReplay(subscription)) {
+ entitledOrgs++;
+ return;
+ }
+
+ const orgSites = replaySites.filter(s => s.organizationId === orgId);
+ const plan = `${subscription.planName} (${subscription.source}, ${subscription.status})${
+ isUnknownPlan ? ` priceId=${subscription.priceId}` : ""
+ }`;
+ const target = isUnknownPlan ? needsReview : toDisable;
+ for (const site of orgSites) {
+ target.push({ siteId: site.siteId, domain: site.domain, org: org?.name ?? orgId, plan });
+ }
+ log(
+ ` ${isUnknownPlan ? "REVIEW" : "FLAGGED"}: ${org?.name ?? orgId} β€” ${plan} β€” ${orgSites.length} site(s)`
+ );
+ })
+ );
+ log(` ${Math.min(i + CONCURRENCY, orgIds.length)}/${orgIds.length} orgs resolved`);
+}
+
+// Sites with no organization have no plan at all, so they can't be entitled
+for (const site of replaySites.filter(s => s.organizationId === null)) {
+ toDisable.push({ siteId: site.siteId, domain: site.domain, org: "(no organization)", plan: "(none)" });
+}
+
+log(
+ `Done resolving: ${entitledOrgs} orgs entitled, ${toDisable.length} sites to disable, ${needsReview.length} sites need manual review.`
+);
+
+if (needsReview.length > 0) {
+ console.log("\nNeeds manual review (Stripe price ID not in const.ts β€” add it to STRIPE_PRICES, these are NOT disabled):");
+ console.table(needsReview);
+}
+
+if (toDisable.length === 0) {
+ log("No sites to disable. Nothing to do.");
+ process.exit(0);
+}
+
+console.log("\nSites with replay enabled but no plan access:");
+console.table(toDisable);
+
+const siteIds = toDisable.map(s => s.siteId);
+
+if (!apply) {
+ console.log("\nDry run β€” no changes made. Re-run with --apply to disable, or do it manually:");
+ console.log(`UPDATE sites SET "sessionReplay" = false WHERE site_id IN (${siteIds.join(", ")});`);
+ process.exit(0);
+}
+
+log(`Disabling session replay for ${siteIds.length} sites...`);
+await db
+ .update(sites)
+ .set({ sessionReplay: false, updatedAt: new Date().toISOString() })
+ .where(inArray(sites.siteId, siteIds));
+
+log(`Disabled session replay for ${siteIds.length} sites.`);
+process.exit(0);
diff --git a/server/src/services/usageService.ts b/server/src/services/usageService.ts
index b59a42bc0..a479b91f3 100644
--- a/server/src/services/usageService.ts
+++ b/server/src/services/usageService.ts
@@ -13,12 +13,17 @@ import {
getAllStripeSubscriptionsByCustomer,
getBestSubscriptionFromStripeSub,
stripeSubscriptionInfoFromSnapshot,
+ subscriptionIncludesReplay,
+ SubscriptionInfo,
} from "../lib/subscriptionUtils.js";
type UsageUpdateCallback = () => void;
class UsageService {
private sitesOverLimit = new Set<number>();
+ // Sites whose organization's plan does not include session replay. Empty until the
+ // usage cron runs (and always empty when self-hosted), so enforcement fails open.
+ private sitesWithoutReplay = new Set<number>();
private usageCheckTask: cron.ScheduledTask | null = null;
private logger = createServiceLogger("usage-checker");
private onUsageUpdatedCallbacks: UsageUpdateCallback[] = [];
@@ -32,6 +37,13 @@ class UsageService {
this.sitesOverLimit = sites;
}
+ /**
+ * Sets the sitesWithoutReplay set (used by workers receiving IPC updates from primary)
+ */
+ public setSitesWithoutReplay(sites: Set<number>): void {
+ this.sitesWithoutReplay = sites;
+ }
+
/**
* Register a callback to be invoked after usage data is updated.
* Used by the cluster primary to broadcast sitesOverLimit to workers.
@@ -76,6 +88,20 @@ class UsageService {
return this.sitesOverLimit.has(siteId);
}
+ /**
+ * Gets the set of site IDs whose plan does not include session replay
+ */
+ public getSitesWithoutReplay(): Set<number> {
+ return this.sitesWithoutReplay;
+ }
+
+ /**
+ * Checks if a site's plan excludes session replay
+ */
+ public isSiteWithoutReplay(siteId: number): boolean {
+ return this.sitesWithoutReplay.has(siteId);
+ }
+
/**
* Gets the first day of the current month in YYYY-MM-DD format using Luxon
*/
@@ -124,9 +150,7 @@ class UsageService {
}
/**
- * Gets event limit and billing period start date for an organization based on their best subscription.
- * Checks both AppSumo and Stripe subscriptions and uses the one with the higher event limit.
- * @returns [eventLimit, periodStartDate]
+ * Resolves an organization's best subscription (custom plan / override / Stripe / AppSumo / free).
*/
private async getOrganizationSubscriptionInfo(
orgData: {
@@ -136,7 +160,7 @@ class UsageService {
name: string;
},
stripeSubscriptions: Map<string, Stripe.Subscription>
- ): Promise<[number, string | null]> {
+ ): Promise<SubscriptionInfo> {
// Resolve this org's Stripe subscription from the bulk snapshot (no per-org Stripe call),
// then layer in custom plan / override / AppSumo via the same priority rules as elsewhere.
const stripeSub = stripeSubscriptionInfoFromSnapshot(stripeSubscriptions, orgData.stripeCustomerId);
@@ -155,7 +179,7 @@ class UsageService {
this.logger.info(`Organization ${orgData.name} on free tier with ${subscription.eventLimit} events/month`);
}
- return [subscription.eventLimit, subscription.periodStart];
+ return subscription;
}
/**
@@ -258,8 +282,10 @@ class UsageService {
const wasOverLimit = orgData.overMonthlyLimit ?? false;
const alreadyNotifiedApproaching = orgData.approachingLimitNotifiedPeriodStart === monthStart;
- const [eventLimit] = await this.getOrganizationSubscriptionInfo(orgData, stripeSubscriptions);
+ const subscription = await this.getOrganizationSubscriptionInfo(orgData, stripeSubscriptions);
+ const eventLimit = subscription.eventLimit;
const isOverLimit = eventCount > eventLimit;
+ const includesReplay = subscriptionIncludesReplay(subscription);
let sendApproaching = false;
if (!alreadyNotifiedApproaching && !isOverLimit && Number.isFinite(eventLimit) && daysRemaining >= 2) {
@@ -336,6 +362,16 @@ class UsageService {
}
}
+ // Track sites whose plan doesn't include session replay so ingest/config
+ // endpoints can stop recording for them (e.g. after a downgrade from Pro)
+ for (const siteId of siteIds) {
+ if (includesReplay) {
+ this.sitesWithoutReplay.delete(siteId);
+ } else {
+ this.sitesWithoutReplay.add(siteId);
+ }
+ }
+
this.logger.info(
`Updated organization ${orgData.name}: ${eventCount.toLocaleString()} events, limit ${eventLimit.toLocaleString()}`
);
@@ -344,7 +380,10 @@ class UsageService {
}
}
- this.logger.info(`Completed monthly event usage check. ${this.sitesOverLimit.size} sites are over their limit.`);
+ this.logger.info(
+ `Completed monthly event usage check. ${this.sitesOverLimit.size} sites are over their limit, ` +
+ `${this.sitesWithoutReplay.size} sites lack session replay access.`
+ );
// Notify listeners (e.g., cluster primary broadcasts to workers)
for (const callback of this.onUsageUpdatedCallbacks) {