Skip to content

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

Refactor session replay tracking to utilize site exclusion decision logic

Bill Yangf6092c2498d1
diff --git a/CONTEXT.md b/CONTEXT.md
index feaf2959a..05c06620a 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -12,6 +12,10 @@ _Avoid_: Website, property
The mutable identity, visibility, tracking, exclusion, and feature settings attached to a Site.
_Avoid_: Site settings, tracking config
+**Site Exclusion Decision**:
+The ordered determination that an ingestion request should not be recorded because it matches a Site Configuration exclusion rule.
+_Avoid_: Filter result, blocked event
+
**Public Website Target**:
A caller-supplied HTTP or HTTPS location that resolves only to public network addresses and can be inspected by Rybbit's free analytics tools.
_Avoid_: External URL, safe URL, validated URL
diff --git a/server/src/api/sessionReplay/recordSessionReplay.test.ts b/server/src/api/sessionReplay/recordSessionReplay.test.ts
index 71a9b9e66..5b4d45385 100644
--- a/server/src/api/sessionReplay/recordSessionReplay.test.ts
+++ b/server/src/api/sessionReplay/recordSessionReplay.test.ts
@@ -5,14 +5,9 @@ import { recordSessionReplay } from "./recordSessionReplay.js";
const mocks = vi.hoisted(() => ({
getConfig: vi.fn(),
- isIPExcluded: vi.fn(),
- isCountryExcluded: vi.fn(),
- isPathExcluded: vi.fn(),
- isHostnameExcluded: vi.fn(),
- isUserAgentExcluded: vi.fn(),
+ decideSiteExclusion: vi.fn(),
isSiteOverLimit: vi.fn(),
isSiteWithoutReplay: vi.fn(),
- getLocation: vi.fn(),
recordEvents: vi.fn(),
loggerInfo: vi.fn(),
loggerError: vi.fn(),
@@ -21,14 +16,13 @@ const mocks = vi.hoisted(() => ({
vi.mock("../../lib/siteConfig.js", () => ({
siteConfig: {
getConfig: mocks.getConfig,
- isIPExcluded: mocks.isIPExcluded,
- isCountryExcluded: mocks.isCountryExcluded,
- isPathExcluded: mocks.isPathExcluded,
- isHostnameExcluded: mocks.isHostnameExcluded,
- isUserAgentExcluded: mocks.isUserAgentExcluded,
},
}));
+vi.mock("../../services/sites/siteExclusionDecision.js", () => ({
+ decideSiteExclusion: mocks.decideSiteExclusion,
+}));
+
vi.mock("../../services/usageService.js", () => ({
usageService: {
isSiteOverLimit: mocks.isSiteOverLimit,
@@ -36,10 +30,6 @@ vi.mock("../../services/usageService.js", () => ({
},
}));
-vi.mock("../../db/geolocation/geolocation.js", () => ({
- getLocation: mocks.getLocation,
-}));
-
vi.mock("../../services/replay/sessionReplayIngestService.js", () => ({
SessionReplayIngestService: vi.fn().mockImplementation(() => ({
recordEvents: mocks.recordEvents,
@@ -127,28 +117,51 @@ describe("recordSessionReplay exclusions", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.getConfig.mockResolvedValue(baseConfig);
- mocks.isIPExcluded.mockResolvedValue(false);
- mocks.isCountryExcluded.mockResolvedValue(false);
- mocks.isPathExcluded.mockResolvedValue(false);
- mocks.isHostnameExcluded.mockResolvedValue(false);
- mocks.isUserAgentExcluded.mockResolvedValue(false);
+ mocks.decideSiteExclusion.mockResolvedValue({ excluded: false });
mocks.isSiteOverLimit.mockReturnValue(false);
mocks.isSiteWithoutReplay.mockReturnValue(false);
- mocks.getLocation.mockResolvedValue({});
mocks.recordEvents.mockResolvedValue(undefined);
});
- it("uses the shared IP exclusion matcher before recording replay batches", async () => {
+ it("records the replay when the Site Exclusion Decision accepts the request", async () => {
+ const reply = createReply();
+
+ await recordSessionReplay(createRequest(), reply);
+
+ expect(mocks.decideSiteExclusion).toHaveBeenCalledOnce();
+ expect(mocks.recordEvents).toHaveBeenCalledWith(42, baseBody, {
+ userAgent: "Mozilla/5.0 HeadlessChrome/120",
+ ipAddress: "198.51.100.10",
+ origin: "https://example.com",
+ referrer: "https://example.com/admin/users",
+ });
+ expect(reply.sentPayload).toEqual({ success: true });
+ });
+
+ it("maps an IP Site Exclusion Decision to the replay skip response", async () => {
mocks.getConfig.mockResolvedValue({
...baseConfig,
excludedIPs: ["198.51.100.0/24"],
});
- mocks.isIPExcluded.mockResolvedValue(true);
+ mocks.decideSiteExclusion.mockResolvedValue({
+ excluded: true,
+ reason: "ip",
+ label: "IP",
+ value: "198.51.100.10",
+ });
const reply = createReply();
await recordSessionReplay(createRequest(), reply);
- expect(mocks.isIPExcluded).toHaveBeenCalledWith("198.51.100.10", "site_abc");
+ expect(mocks.decideSiteExclusion).toHaveBeenCalledWith(
+ expect.objectContaining({ siteId: 42, excludedIPs: ["198.51.100.0/24"] }),
+ {
+ ipAddress: "198.51.100.10",
+ pathname: "/admin/users",
+ hostname: "example.com",
+ userAgent: "Mozilla/5.0 HeadlessChrome/120",
+ }
+ );
expect(mocks.recordEvents).not.toHaveBeenCalled();
expect(reply.sentPayload).toEqual({
success: true,
@@ -161,12 +174,20 @@ describe("recordSessionReplay exclusions", () => {
...baseConfig,
excludedPaths: ["/admin/*"],
});
- mocks.isPathExcluded.mockResolvedValue(true);
+ mocks.decideSiteExclusion.mockResolvedValue({
+ excluded: true,
+ reason: "path",
+ label: "path",
+ value: "/admin/users",
+ });
const reply = createReply();
await recordSessionReplay(createRequest(), reply);
- expect(mocks.isPathExcluded).toHaveBeenCalledWith("/admin/users", "site_abc");
+ expect(mocks.decideSiteExclusion).toHaveBeenCalledWith(
+ expect.objectContaining({ excludedPaths: ["/admin/*"] }),
+ expect.objectContaining({ pathname: "/admin/users" })
+ );
expect(mocks.recordEvents).not.toHaveBeenCalled();
expect(reply.status).toHaveBeenCalledWith(200);
expect(reply.sentPayload).toEqual({
@@ -180,7 +201,12 @@ describe("recordSessionReplay exclusions", () => {
...baseConfig,
excludedHostnames: ["*.vercel.app"],
});
- mocks.isHostnameExcluded.mockResolvedValue(true);
+ mocks.decideSiteExclusion.mockResolvedValue({
+ excluded: true,
+ reason: "hostname",
+ label: "hostname",
+ value: "preview.vercel.app",
+ });
const reply = createReply();
await recordSessionReplay(
@@ -195,7 +221,10 @@ describe("recordSessionReplay exclusions", () => {
reply
);
- expect(mocks.isHostnameExcluded).toHaveBeenCalledWith("preview.vercel.app", "site_abc");
+ expect(mocks.decideSiteExclusion).toHaveBeenCalledWith(
+ expect.objectContaining({ excludedHostnames: ["*.vercel.app"] }),
+ expect.objectContaining({ hostname: "preview.vercel.app", pathname: "/app" })
+ );
expect(mocks.recordEvents).not.toHaveBeenCalled();
expect(reply.sentPayload).toEqual({
success: true,
@@ -208,12 +237,20 @@ describe("recordSessionReplay exclusions", () => {
...baseConfig,
excludedUserAgents: ["HeadlessChrome"],
});
- mocks.isUserAgentExcluded.mockResolvedValue(true);
+ mocks.decideSiteExclusion.mockResolvedValue({
+ excluded: true,
+ reason: "user_agent",
+ label: "user agent",
+ value: "Mozilla/5.0 HeadlessChrome/120",
+ });
const reply = createReply();
await recordSessionReplay(createRequest(), reply);
- expect(mocks.isUserAgentExcluded).toHaveBeenCalledWith("Mozilla/5.0 HeadlessChrome/120", "site_abc");
+ expect(mocks.decideSiteExclusion).toHaveBeenCalledWith(
+ expect.objectContaining({ excludedUserAgents: ["HeadlessChrome"] }),
+ expect.objectContaining({ userAgent: "Mozilla/5.0 HeadlessChrome/120" })
+ );
expect(mocks.recordEvents).not.toHaveBeenCalled();
expect(reply.sentPayload).toEqual({
success: true,
diff --git a/server/src/api/sessionReplay/recordSessionReplay.ts b/server/src/api/sessionReplay/recordSessionReplay.ts
index 93b58a555..bcd8da560 100644
--- a/server/src/api/sessionReplay/recordSessionReplay.ts
+++ b/server/src/api/sessionReplay/recordSessionReplay.ts
@@ -6,7 +6,7 @@ import { usageService } from "../../services/usageService.js";
import { RecordSessionReplayRequest } from "../../types/sessionReplay.js";
import { resolveClientIp } from "../../services/tracker/resolveClientIp.js";
import { logger } from "../../lib/logger/logger.js";
-import { getLocation } from "../../db/geolocation/geolocation.js";
+import { decideSiteExclusion } from "../../services/sites/siteExclusionDecision.js";
const recordSessionReplaySchema = z.object({
userId: z.string(),
@@ -58,15 +58,8 @@ export async function recordSessionReplay(
) {
try {
// Get the site configuration to get the numeric siteId
- const {
- siteId,
- excludedIPs,
- excludedCountries,
- excludedPaths,
- excludedHostnames,
- excludedUserAgents,
- sessionReplay,
- } = (await siteConfig.getConfig(request.params.siteId)) ?? {};
+ const siteConfiguration = await siteConfig.getConfig(request.params.siteId);
+ const { siteId, sessionReplay } = siteConfiguration ?? {};
if (!sessionReplay) {
logger.info(`[SessionReplay] Skipping event for site ${siteId} - session replay not enabled`);
@@ -77,6 +70,10 @@ export async function recordSessionReplay(
throw new Error(`Site not found: ${request.params.siteId}`);
}
+ if (!siteConfiguration) {
+ throw new Error(`Site configuration not found: ${request.params.siteId}`);
+ }
+
// Check if the site has exceeded its monthly limit
if (usageService.isSiteOverLimit(Number(siteId))) {
logger.info(`[SessionReplay] Skipping event for site ${siteId} - over monthly limit`);
@@ -92,83 +89,32 @@ export async function recordSessionReplay(
const body = recordSessionReplaySchema.parse(request.body) as RecordSessionReplayRequest;
- // Check if the IP should be excluded from tracking
const requestIP = resolveClientIp(request);
+ const { hostname, pathname } = parseReplayPageUrl(body.metadata?.pageUrl);
+ const userAgent = request.headers["user-agent"] || "";
- if (excludedIPs && excludedIPs.length > 0 && (await siteConfig.isIPExcluded(requestIP, request.params.siteId))) {
- logger.info(`[SessionReplay] IP ${requestIP} excluded from tracking for site ${siteId}`);
+ const exclusionDecision = await decideSiteExclusion(siteConfiguration, {
+ ipAddress: requestIP,
+ pathname,
+ hostname,
+ userAgent: String(userAgent),
+ });
+
+ if (exclusionDecision.excluded) {
+ logger.info(`[SessionReplay] ${exclusionDecision.label} excluded from tracking for site ${siteId}`);
return reply.status(200).send({
success: true,
- message: "Session replay not recorded - IP excluded",
+ message: `Session replay not recorded - ${exclusionDecision.label} excluded`,
});
}
- // Check if the country should be excluded from tracking
- if (excludedCountries && excludedCountries.length > 0) {
- const locationResults = await getLocation([requestIP]);
- const locationData = locationResults[requestIP];
-
- if (locationData?.countryIso) {
- const isCountryExcluded = await siteConfig.isCountryExcluded(locationData.countryIso, request.params.siteId);
- if (isCountryExcluded) {
- logger.info(`[SessionReplay] Country ${locationData.countryIso} excluded from tracking for site ${siteId}`);
- return reply.status(200).send({
- success: true,
- message: "Session replay not recorded - country excluded",
- });
- }
- }
- }
-
- const { hostname, pathname } = parseReplayPageUrl(body.metadata?.pageUrl);
-
- // Check if the pathname should be excluded from tracking
- if (excludedPaths && excludedPaths.length > 0) {
- const isPathExcluded = await siteConfig.isPathExcluded(pathname, request.params.siteId);
- if (isPathExcluded) {
- logger.info(`[SessionReplay] Path ${pathname} excluded from tracking for site ${siteId}`);
- return reply.status(200).send({
- success: true,
- message: "Session replay not recorded - path excluded",
- });
- }
- }
-
- // Check if the hostname should be excluded from tracking
- if (excludedHostnames && excludedHostnames.length > 0) {
- const isHostnameExcluded = await siteConfig.isHostnameExcluded(hostname, request.params.siteId);
- if (isHostnameExcluded) {
- logger.info(`[SessionReplay] Hostname ${hostname} excluded from tracking for site ${siteId}`);
- return reply.status(200).send({
- success: true,
- message: "Session replay not recorded - hostname excluded",
- });
- }
- }
-
- // Extract request metadata for tracking
- const userAgent = request.headers["user-agent"] || "";
-
- // Check if the user agent should be excluded from tracking
- if (excludedUserAgents && excludedUserAgents.length > 0) {
- const isUserAgentExcluded = await siteConfig.isUserAgentExcluded(String(userAgent), request.params.siteId);
- if (isUserAgentExcluded) {
- logger.info(`[SessionReplay] User agent excluded from tracking for site ${siteId}`);
- return reply.status(200).send({
- success: true,
- message: "Session replay not recorded - user agent excluded",
- });
- }
- }
-
- const ipAddress = resolveClientIp(request);
const origin = request.headers.origin || "";
const referrer = request.headers.referer || "";
const sessionReplayService = new SessionReplayIngestService();
await sessionReplayService.recordEvents(siteId, body, {
userAgent,
- ipAddress,
+ ipAddress: requestIP,
origin,
referrer,
});
diff --git a/server/src/lib/siteConfig.test.ts b/server/src/lib/siteConfig.test.ts
index fcfe8650f..fb711edbb 100644
--- a/server/src/lib/siteConfig.test.ts
+++ b/server/src/lib/siteConfig.test.ts
@@ -201,57 +201,3 @@ describe("siteConfig.getConfig", () => {
expect(dbMock.queries).toHaveLength(queriesBeforeInvalidation + 4);
});
});
-
-describe("siteConfig exclusion matchers", () => {
- it("matches excluded paths with glob wildcards, case-insensitively", async () => {
- dbMock.rows.push(createSiteRow({ siteId: 1, excludedPaths: ["/admin/*", "/preview"] }));
-
- expect(await siteConfig.isPathExcluded("/admin/users", 1)).toBe(true);
- expect(await siteConfig.isPathExcluded("/ADMIN/users", 1)).toBe(true);
- expect(await siteConfig.isPathExcluded("/preview", 1)).toBe(true);
- expect(await siteConfig.isPathExcluded("/admin", 1)).toBe(false); // no trailing segment
- expect(await siteConfig.isPathExcluded("/blog", 1)).toBe(false);
- expect(await siteConfig.isPathExcluded(undefined, 1)).toBe(false);
- });
-
- it("matches patterns with multiple and consecutive wildcards, bounded against backtracking", async () => {
- dbMock.rows.push(
- createSiteRow({ siteId: 5, excludedPaths: ["/a/*/b/*", "/x**y"] }),
- createSiteRow({ siteId: 6, excludedPaths: ["/" + "*a".repeat(30) + "b"] })
- );
-
- expect(await siteConfig.isPathExcluded("/a/1/b/2", 5)).toBe(true);
- expect(await siteConfig.isPathExcluded("/a//b/", 5)).toBe(true); // wildcards may match empty
- expect(await siteConfig.isPathExcluded("/a/1/c/2", 5)).toBe(false);
- expect(await siteConfig.isPathExcluded("/xANYTHINGy", 5)).toBe(true); // consecutive wildcards
-
- // A pathological pattern must still resolve promptly (no catastrophic backtracking).
- expect(await siteConfig.isPathExcluded("/" + "a".repeat(2000), 6)).toBe(false);
- });
-
- it("matches excluded hostnames with glob wildcards", async () => {
- dbMock.rows.push(createSiteRow({ siteId: 2, excludedHostnames: ["localhost", "*.vercel.app"] }));
-
- expect(await siteConfig.isHostnameExcluded("localhost", 2)).toBe(true);
- expect(await siteConfig.isHostnameExcluded("my-app.vercel.app", 2)).toBe(true);
- expect(await siteConfig.isHostnameExcluded("vercel.app", 2)).toBe(false);
- expect(await siteConfig.isHostnameExcluded("example.com", 2)).toBe(false);
- });
-
- it("matches excluded user agents as case-insensitive substrings", async () => {
- dbMock.rows.push(createSiteRow({ siteId: 3, excludedUserAgents: ["HeadlessChrome", "MyMonitor"] }));
-
- expect(await siteConfig.isUserAgentExcluded("Mozilla/5.0 HeadlessChrome/120", 3)).toBe(true);
- expect(await siteConfig.isUserAgentExcluded("mozilla/5.0 headlesschrome/120", 3)).toBe(true);
- expect(await siteConfig.isUserAgentExcluded("Mozilla/5.0 (real browser)", 3)).toBe(false);
- expect(await siteConfig.isUserAgentExcluded(undefined, 3)).toBe(false);
- });
-
- it("returns false when no exclusions are configured", async () => {
- dbMock.rows.push(createSiteRow({ siteId: 4 }));
-
- expect(await siteConfig.isPathExcluded("/admin", 4)).toBe(false);
- expect(await siteConfig.isHostnameExcluded("localhost", 4)).toBe(false);
- expect(await siteConfig.isUserAgentExcluded("HeadlessChrome", 4)).toBe(false);
- });
-});
diff --git a/server/src/lib/siteConfig.ts b/server/src/lib/siteConfig.ts
index a63987d01..c69160ebb 100644
--- a/server/src/lib/siteConfig.ts
+++ b/server/src/lib/siteConfig.ts
@@ -1,7 +1,6 @@
import { eq, type SQL } from "drizzle-orm";
import { db } from "../db/postgres/postgres.js";
import { sites } from "../db/postgres/schema.js";
-import { matchesCIDR, matchesRange } from "./ipUtils.js";
import { logger } from "./logger/logger.js";
// Site configuration interface
@@ -150,166 +149,6 @@ class SiteConfig {
}
}
}
-
- /**
- * Check if an IP address matches any of the excluded IPs/ranges
- */
- async isIPExcluded(ipAddress: string, siteIdOrId?: string | number): Promise<boolean> {
- if (!siteIdOrId) return false; // If no site specified, don't exclude any IPs
- const config = await this.getSiteByAnyId(siteIdOrId);
- const excludedIPs = config?.excludedIPs || [];
- if (!excludedIPs || excludedIPs.length === 0) {
- return false;
- }
-
- for (const excludedPattern of excludedIPs) {
- if (this.matchesIPPattern(ipAddress, excludedPattern)) {
- return true;
- }
- }
-
- return false;
- }
-
- /**
- * Check if a country code is in the excluded countries list
- * @param countryIso - ISO country code (e.g., "US", "GB", "CN")
- * @param siteIdOrId - Site identifier
- * @returns true if country should be excluded
- */
- async isCountryExcluded(countryIso: string | undefined, siteIdOrId?: string | number): Promise<boolean> {
- if (!siteIdOrId || !countryIso) return false;
- const config = await this.getSiteByAnyId(siteIdOrId);
- const excludedCountries = config?.excludedCountries || [];
- if (!excludedCountries || excludedCountries.length === 0) {
- return false;
- }
-
- // Convert to uppercase for case-insensitive comparison
- const normalizedCountry = countryIso.toUpperCase();
- return excludedCountries.some(country => country.toUpperCase() === normalizedCountry);
- }
-
- /**
- * Check if a pathname matches any of the excluded path glob patterns.
- * Patterns support `*` as a wildcard (e.g. "/admin/*", "/preview"). Matching is case-insensitive.
- */
- async isPathExcluded(pathname: string | undefined, siteIdOrId?: string | number): Promise<boolean> {
- if (!siteIdOrId || !pathname) return false;
- const config = await this.getSiteByAnyId(siteIdOrId);
- const excludedPaths = config?.excludedPaths || [];
- return excludedPaths.some(pattern => this.matchesGlob(pathname, pattern));
- }
-
- /**
- * Check if a hostname matches any of the excluded hostname glob patterns.
- * Patterns support `*` as a wildcard (e.g. "localhost", "*.vercel.app"). Matching is case-insensitive.
- */
- async isHostnameExcluded(hostname: string | undefined, siteIdOrId?: string | number): Promise<boolean> {
- if (!siteIdOrId || !hostname) return false;
- const config = await this.getSiteByAnyId(siteIdOrId);
- const excludedHostnames = config?.excludedHostnames || [];
- return excludedHostnames.some(pattern => this.matchesGlob(hostname, pattern));
- }
-
- /**
- * Check if a user-agent string contains any of the excluded substrings.
- * Matching is a case-insensitive substring test (e.g. "HeadlessChrome").
- */
- async isUserAgentExcluded(userAgent: string | undefined, siteIdOrId?: string | number): Promise<boolean> {
- if (!siteIdOrId || !userAgent) return false;
- const config = await this.getSiteByAnyId(siteIdOrId);
- const excludedUserAgents = config?.excludedUserAgents || [];
- const normalizedUserAgent = userAgent.toLowerCase();
- return excludedUserAgents.some(substring => {
- const trimmed = substring.trim().toLowerCase();
- return trimmed.length > 0 && normalizedUserAgent.includes(trimmed);
- });
- }
-
- /**
- * Case-insensitive glob match where `*` matches any sequence of characters
- * (including the empty string). A pattern with no wildcards must match the
- * whole value exactly.
- *
- * Implemented as a linear two-pointer scan rather than a compiled RegExp so
- * that, on the hot ingestion path, we (1) never recompile a pattern per event
- * and (2) can't trigger catastrophic backtracking — matching is bounded to
- * O(value.length * pattern.length) regardless of how many wildcards a pattern
- * contains. Every character other than `*` is treated as a literal.
- */
- private matchesGlob(value: string, pattern: string): boolean {
- const glob = pattern.trim().toLowerCase();
- if (!glob) return false;
-
- const text = value.toLowerCase();
-
- let textIdx = 0;
- let globIdx = 0;
- let lastStarGlobIdx = -1;
- let textIdxAfterStar = 0;
-
- while (textIdx < text.length) {
- if (globIdx < glob.length && glob[globIdx] === text[textIdx]) {
- // Literal character match — advance both pointers.
- textIdx++;
- globIdx++;
- } else if (globIdx < glob.length && glob[globIdx] === "*") {
- // Record this star and tentatively let it match nothing.
- lastStarGlobIdx = globIdx;
- textIdxAfterStar = textIdx;
- globIdx++;
- } else if (lastStarGlobIdx !== -1) {
- // Mismatch, but the most recent star can absorb one more character.
- globIdx = lastStarGlobIdx + 1;
- textIdxAfterStar++;
- textIdx = textIdxAfterStar;
- } else {
- return false;
- }
- }
-
- // The value is consumed; the match holds only if the rest of the pattern is
- // entirely trailing stars.
- while (globIdx < glob.length && glob[globIdx] === "*") {
- globIdx++;
- }
-
- return globIdx === glob.length;
- }
-
- /**
- * Check if an IP address matches a specific pattern
- * Supports:
- * - Single IP: 192.168.1.1, 2001:db8::1
- * - CIDR notation: 192.168.1.0/24, 2001:db8::/32
- * - Range notation: 192.168.1.1-192.168.1.10 (IPv4 only, IPv6 ranges not supported)
- */
- private matchesIPPattern(ipAddress: string, pattern: string): boolean {
- try {
- const trimmedPattern = pattern.trim();
-
- // Single IP match
- if (!trimmedPattern.includes("/") && !trimmedPattern.includes("-")) {
- return ipAddress === trimmedPattern;
- }
-
- // CIDR notation
- if (trimmedPattern.includes("/")) {
- return matchesCIDR(ipAddress, trimmedPattern);
- }
-
- // Range notation
- if (trimmedPattern.includes("-")) {
- return matchesRange(ipAddress, trimmedPattern);
- }
-
- return false;
- } catch (error) {
- logger.warn(error as Error, `Invalid IP pattern: ${pattern}`);
- return false;
- }
- }
}
// Singleton instance
diff --git a/server/src/services/sites/siteExclusionDecision.test.ts b/server/src/services/sites/siteExclusionDecision.test.ts
new file mode 100644
index 000000000..8da5872a8
--- /dev/null
+++ b/server/src/services/sites/siteExclusionDecision.test.ts
@@ -0,0 +1,178 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ getLocation: vi.fn(),
+ loggerWarn: vi.fn(),
+}));
+
+vi.mock("../../db/geolocation/geolocation.js", () => ({
+ getLocation: mocks.getLocation,
+}));
+
+vi.mock("../../lib/logger/logger.js", () => ({
+ logger: { warn: mocks.loggerWarn },
+}));
+
+import { decideSiteExclusion } from "./siteExclusionDecision.js";
+
+function configuration(overrides: Partial<Parameters<typeof decideSiteExclusion>[0]> = {}) {
+ return {
+ excludedIPs: [],
+ excludedCountries: [],
+ excludedPaths: [],
+ excludedHostnames: [],
+ excludedUserAgents: [],
+ ...overrides,
+ };
+}
+
+const request = {
+ ipAddress: "198.51.100.10",
+ pathname: "/admin/users",
+ hostname: "preview.vercel.app",
+ userAgent: "Mozilla/5.0 HeadlessChrome/120",
+};
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.getLocation.mockResolvedValue({});
+});
+
+describe("decideSiteExclusion", () => {
+ it("accepts a request when no exclusion matches without resolving geolocation", async () => {
+ await expect(decideSiteExclusion(configuration(), request)).resolves.toEqual({ excluded: false });
+ expect(mocks.getLocation).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ ["single address", "198.51.100.10"],
+ ["CIDR", "198.51.100.0/24"],
+ ["range", "198.51.100.1-198.51.100.20"],
+ ])("matches an excluded IP using a %s rule", async (_description, pattern) => {
+ await expect(decideSiteExclusion(configuration({ excludedIPs: [pattern] }), request)).resolves.toMatchObject({
+ excluded: true,
+ reason: "ip",
+ label: "IP",
+ value: "198.51.100.10",
+ });
+ });
+
+ it("resolves geolocation only when country rules exist", async () => {
+ mocks.getLocation.mockResolvedValue({
+ "198.51.100.10": { countryIso: "us" },
+ });
+
+ await expect(decideSiteExclusion(configuration({ excludedCountries: ["US", "GB"] }), request)).resolves.toEqual({
+ excluded: true,
+ reason: "country",
+ label: "country",
+ value: "us",
+ });
+ expect(mocks.getLocation).toHaveBeenCalledOnce();
+ expect(mocks.getLocation).toHaveBeenCalledWith(["198.51.100.10"]);
+ });
+
+ it("matches path globs case-insensitively", async () => {
+ const rules = configuration({ excludedPaths: ["/admin/*", "/preview"] });
+
+ await expect(decideSiteExclusion(rules, { ...request, pathname: "/ADMIN/users" })).resolves.toMatchObject({
+ excluded: true,
+ reason: "path",
+ });
+ await expect(decideSiteExclusion(rules, { ...request, pathname: "/preview" })).resolves.toMatchObject({
+ excluded: true,
+ reason: "path",
+ });
+ await expect(decideSiteExclusion(rules, { ...request, pathname: "/admin" })).resolves.toEqual({
+ excluded: false,
+ });
+ });
+
+ it("handles multiple and consecutive wildcards without regex backtracking", async () => {
+ const rules = configuration({ excludedPaths: ["/a/*/b/*", "/x**y", "/" + "*a".repeat(30) + "b"] });
+
+ await expect(decideSiteExclusion(rules, { ...request, pathname: "/a/1/b/2" })).resolves.toMatchObject({
+ excluded: true,
+ reason: "path",
+ });
+ await expect(decideSiteExclusion(rules, { ...request, pathname: "/a//b/" })).resolves.toMatchObject({
+ excluded: true,
+ reason: "path",
+ });
+ await expect(decideSiteExclusion(rules, { ...request, pathname: "/xANYTHINGy" })).resolves.toMatchObject({
+ excluded: true,
+ reason: "path",
+ });
+ await expect(decideSiteExclusion(rules, { ...request, pathname: "/" + "a".repeat(2000) })).resolves.toEqual({
+ excluded: false,
+ });
+ });
+
+ it("matches hostname globs", async () => {
+ const rules = configuration({ excludedHostnames: ["localhost", "*.vercel.app"] });
+
+ await expect(decideSiteExclusion(rules, request)).resolves.toMatchObject({
+ excluded: true,
+ reason: "hostname",
+ });
+ await expect(decideSiteExclusion(rules, { ...request, hostname: "vercel.app" })).resolves.toEqual({
+ excluded: false,
+ });
+ });
+
+ it("matches user-agent substrings case-insensitively and ignores blank rules", async () => {
+ const rules = configuration({ excludedUserAgents: [" ", "headlesschrome"] });
+
+ await expect(decideSiteExclusion(rules, request)).resolves.toMatchObject({
+ excluded: true,
+ reason: "user_agent",
+ });
+ await expect(decideSiteExclusion(rules, { ...request, userAgent: "Mozilla/5.0 (real browser)" })).resolves.toEqual({
+ excluded: false,
+ });
+ });
+
+ it("returns the first exclusion in the fixed ordering and short-circuits later work", async () => {
+ mocks.getLocation.mockResolvedValue({
+ "198.51.100.10": { countryIso: "US" },
+ });
+ const rules = configuration({
+ excludedIPs: ["198.51.100.0/24"],
+ excludedCountries: ["US"],
+ excludedPaths: ["/admin/*"],
+ excludedHostnames: ["*.vercel.app"],
+ excludedUserAgents: ["HeadlessChrome"],
+ });
+
+ await expect(decideSiteExclusion(rules, request)).resolves.toMatchObject({
+ excluded: true,
+ reason: "ip",
+ });
+ expect(mocks.getLocation).not.toHaveBeenCalled();
+ });
+
+ it("lets country exclusion preempt matching request metadata", async () => {
+ mocks.getLocation.mockResolvedValue({
+ "198.51.100.10": { countryIso: "US" },
+ });
+ const rules = configuration({
+ excludedCountries: ["US"],
+ excludedPaths: ["/admin/*"],
+ excludedHostnames: ["*.vercel.app"],
+ excludedUserAgents: ["HeadlessChrome"],
+ });
+
+ await expect(decideSiteExclusion(rules, request)).resolves.toMatchObject({
+ excluded: true,
+ reason: "country",
+ });
+ });
+
+ it("propagates geolocation failures", async () => {
+ mocks.getLocation.mockRejectedValue(new Error("geolocation unavailable"));
+
+ await expect(decideSiteExclusion(configuration({ excludedCountries: ["US"] }), request)).rejects.toThrow(
+ "geolocation unavailable"
+ );
+ });
+});
diff --git a/server/src/services/sites/siteExclusionDecision.ts b/server/src/services/sites/siteExclusionDecision.ts
new file mode 100644
index 000000000..bb0335f57
--- /dev/null
+++ b/server/src/services/sites/siteExclusionDecision.ts
@@ -0,0 +1,146 @@
+import { getLocation } from "../../db/geolocation/geolocation.js";
+import { matchesCIDR, matchesRange } from "../../lib/ipUtils.js";
+import { logger } from "../../lib/logger/logger.js";
+import type { SiteConfigData } from "../../lib/siteConfig.js";
+
+type SiteExclusionConfiguration = Pick<
+ SiteConfigData,
+ "excludedIPs" | "excludedCountries" | "excludedPaths" | "excludedHostnames" | "excludedUserAgents"
+>;
+
+export type SiteExclusionRequest = {
+ ipAddress: string;
+ pathname?: string;
+ hostname?: string;
+ userAgent?: string;
+};
+
+export type SiteExclusionReason = "ip" | "country" | "path" | "hostname" | "user_agent";
+
+export type SiteExclusionDecision =
+ | { excluded: false }
+ | {
+ excluded: true;
+ reason: SiteExclusionReason;
+ label: "IP" | "country" | "path" | "hostname" | "user agent";
+ value: string;
+ };
+
+const ACCEPTED: SiteExclusionDecision = { excluded: false };
+
+function excluded(
+ reason: SiteExclusionReason,
+ label: "IP" | "country" | "path" | "hostname" | "user agent",
+ value: string
+): SiteExclusionDecision {
+ return { excluded: true, reason, label, value };
+}
+
+function matchesGlob(value: string, pattern: string): boolean {
+ const glob = pattern.trim().toLowerCase();
+ if (!glob) return false;
+
+ const text = value.toLowerCase();
+ let textIndex = 0;
+ let globIndex = 0;
+ let lastStarGlobIndex = -1;
+ let textIndexAfterStar = 0;
+
+ while (textIndex < text.length) {
+ if (globIndex < glob.length && glob[globIndex] === text[textIndex]) {
+ textIndex++;
+ globIndex++;
+ } else if (globIndex < glob.length && glob[globIndex] === "*") {
+ lastStarGlobIndex = globIndex;
+ textIndexAfterStar = textIndex;
+ globIndex++;
+ } else if (lastStarGlobIndex !== -1) {
+ globIndex = lastStarGlobIndex + 1;
+ textIndexAfterStar++;
+ textIndex = textIndexAfterStar;
+ } else {
+ return false;
+ }
+ }
+
+ while (globIndex < glob.length && glob[globIndex] === "*") {
+ globIndex++;
+ }
+
+ return globIndex === glob.length;
+}
+
+function matchesIPPattern(ipAddress: string, pattern: string): boolean {
+ try {
+ const trimmedPattern = pattern.trim();
+
+ if (!trimmedPattern.includes("/") && !trimmedPattern.includes("-")) {
+ return ipAddress === trimmedPattern;
+ }
+
+ if (trimmedPattern.includes("/")) {
+ return matchesCIDR(ipAddress, trimmedPattern);
+ }
+
+ if (trimmedPattern.includes("-")) {
+ return matchesRange(ipAddress, trimmedPattern);
+ }
+
+ return false;
+ } catch (error) {
+ logger.warn(error as Error, `Invalid IP pattern: ${pattern}`);
+ return false;
+ }
+}
+
+/**
+ * Returns the first Site Configuration exclusion matched in this fixed order:
+ * IP, country, path, hostname, then user agent.
+ *
+ * Geolocation is resolved only when country exclusions exist and no earlier
+ * exclusion matched. Lookup failures from the geolocation adapter propagate.
+ */
+export async function decideSiteExclusion(
+ configuration: SiteExclusionConfiguration,
+ request: SiteExclusionRequest
+): Promise<SiteExclusionDecision> {
+ if (configuration.excludedIPs.some(pattern => matchesIPPattern(request.ipAddress, pattern))) {
+ return excluded("ip", "IP", request.ipAddress);
+ }
+
+ if (configuration.excludedCountries.length > 0) {
+ const locations = await getLocation([request.ipAddress]);
+ const countryIso = locations[request.ipAddress]?.countryIso;
+
+ if (
+ countryIso &&
+ configuration.excludedCountries.some(country => country.toUpperCase() === countryIso.toUpperCase())
+ ) {
+ return excluded("country", "country", countryIso);
+ }
+ }
+
+ const { pathname, hostname, userAgent } = request;
+
+ if (pathname && configuration.excludedPaths.some(pattern => matchesGlob(pathname, pattern))) {
+ return excluded("path", "path", pathname);
+ }
+
+ if (hostname && configuration.excludedHostnames.some(pattern => matchesGlob(hostname, pattern))) {
+ return excluded("hostname", "hostname", hostname);
+ }
+
+ if (userAgent) {
+ const normalizedUserAgent = userAgent.toLowerCase();
+ const matchesUserAgent = configuration.excludedUserAgents.some(substring => {
+ const trimmed = substring.trim().toLowerCase();
+ return trimmed.length > 0 && normalizedUserAgent.includes(trimmed);
+ });
+
+ if (matchesUserAgent) {
+ return excluded("user_agent", "user agent", userAgent);
+ }
+ }
+
+ return ACCEPTED;
+}
diff --git a/server/src/services/tracker/trackEvent.test.ts b/server/src/services/tracker/trackEvent.test.ts
index fb6c64102..311ea77e7 100644
--- a/server/src/services/tracker/trackEvent.test.ts
+++ b/server/src/services/tracker/trackEvent.test.ts
@@ -6,6 +6,7 @@ const mocks = vi.hoisted(() => ({
addPageview: vi.fn(),
checkBotBlocking: vi.fn(),
createBasePayload: vi.fn(),
+ decideSiteExclusion: vi.fn(),
getConfig: vi.fn(),
isSiteOverLimit: vi.fn(),
updateSession: vi.fn(),
@@ -53,6 +54,10 @@ vi.mock("./utils.js", () => ({
createBasePayload: mocks.createBasePayload,
}));
+vi.mock("../sites/siteExclusionDecision.js", () => ({
+ decideSiteExclusion: mocks.decideSiteExclusion,
+}));
+
import { trackEvent } from "./trackEvent.js";
const siteConfiguration = {
@@ -85,6 +90,7 @@ describe("trackEvent session identity", () => {
mocks.getConfig.mockResolvedValue(siteConfiguration);
mocks.isSiteOverLimit.mockReturnValue(false);
mocks.checkBotBlocking.mockResolvedValue(null);
+ mocks.decideSiteExclusion.mockResolvedValue({ excluded: false });
mocks.createBasePayload.mockResolvedValue({
site_id: 42,
userId: "shared-fingerprint",
@@ -119,4 +125,38 @@ describe("trackEvent session identity", () => {
})
);
});
+
+ it("maps a Site Exclusion Decision to the event skip response", async () => {
+ mocks.decideSiteExclusion.mockResolvedValue({
+ excluded: true,
+ reason: "path",
+ label: "path",
+ value: "/admin/users",
+ });
+ const request = {
+ body: {
+ type: "pageview",
+ site_id: "site_abc",
+ pathname: "/admin/users",
+ hostname: "example.com",
+ },
+ headers: { "user-agent": "Mozilla/5.0" },
+ ip: "198.51.100.10",
+ } as unknown as FastifyRequest;
+ const reply = replyStub();
+
+ await trackEvent(request, reply);
+
+ expect(mocks.decideSiteExclusion).toHaveBeenCalledWith(siteConfiguration, {
+ ipAddress: "198.51.100.10",
+ pathname: "/admin/users",
+ hostname: "example.com",
+ userAgent: "Mozilla/5.0",
+ });
+ expect(reply.send).toHaveBeenCalledWith({
+ success: true,
+ message: "Event not tracked - path excluded",
+ });
+ expect(mocks.createBasePayload).not.toHaveBeenCalled();
+ });
});
diff --git a/server/src/services/tracker/trackEvent.ts b/server/src/services/tracker/trackEvent.ts
index a100e53f7..7d6559e95 100644
--- a/server/src/services/tracker/trackEvent.ts
+++ b/server/src/services/tracker/trackEvent.ts
@@ -6,12 +6,12 @@ import { sessionsService } from "../sessions/sessionsService.js";
import { usageService } from "../usageService.js";
import { pageviewQueue } from "./pageviewQueue.js";
import { createBasePayload } from "./utils.js";
-import { getLocation } from "../../db/geolocation/geolocation.js";
import { checkApiKey } from "../../lib/auth-utils.js";
import { hasScope } from "../../lib/scopes.js";
import { botEventQueue } from "./botBlocking/botEventQueue.js";
import { checkBotBlocking } from "./botBlocking/index.js";
import { resolveTrackingIdentity } from "./requestIdentity.js";
+import { decideSiteExclusion } from "../sites/siteExclusionDecision.js";
// Shared fields for all event types
const baseEventFields = {
@@ -317,84 +317,22 @@ export async function trackEvent(request: FastifyRequest, reply: FastifyReply) {
return reply.status(200).send("Site over monthly limit, event not tracked");
}
- // Check if the IP should be excluded from tracking
- if (siteConfiguration.excludedIPs && siteConfiguration.excludedIPs.length > 0) {
- const isExcluded = await siteConfig.isIPExcluded(requestIP, validatedPayload.site_id);
- if (isExcluded) {
- logger.info({ siteId: validatedPayload.site_id, ip: requestIP }, "IP excluded from tracking");
- return reply.status(200).send({
- success: true,
- message: "Event not tracked - IP excluded",
- });
- }
- }
-
- // Check if the country should be excluded from tracking
- if (siteConfiguration.excludedCountries && siteConfiguration.excludedCountries.length > 0) {
- const locationResults = await getLocation([requestIP]);
- const locationData = locationResults[requestIP];
-
- if (locationData?.countryIso) {
- const isCountryExcluded = await siteConfig.isCountryExcluded(locationData.countryIso, validatedPayload.site_id);
- if (isCountryExcluded) {
- logger.info(
- { siteId: validatedPayload.site_id, country: locationData.countryIso },
- "Country excluded from tracking"
- );
- return reply.status(200).send({
- success: true,
- message: "Event not tracked - country excluded",
- });
- }
- }
- }
-
- // Check if the pathname should be excluded from tracking
- if (siteConfiguration.excludedPaths && siteConfiguration.excludedPaths.length > 0) {
- const isPathExcluded = await siteConfig.isPathExcluded(validatedPayload.pathname, validatedPayload.site_id);
- if (isPathExcluded) {
- logger.info(
- { siteId: validatedPayload.site_id, pathname: validatedPayload.pathname },
- "Path excluded from tracking"
- );
- return reply.status(200).send({
- success: true,
- message: "Event not tracked - path excluded",
- });
- }
- }
-
- // Check if the hostname should be excluded from tracking
- if (siteConfiguration.excludedHostnames && siteConfiguration.excludedHostnames.length > 0) {
- const isHostnameExcluded = await siteConfig.isHostnameExcluded(
- validatedPayload.hostname,
- validatedPayload.site_id
- );
- if (isHostnameExcluded) {
- logger.info(
- { siteId: validatedPayload.site_id, hostname: validatedPayload.hostname },
- "Hostname excluded from tracking"
- );
- return reply.status(200).send({
- success: true,
- message: "Event not tracked - hostname excluded",
- });
- }
- }
+ const exclusionDecision = await decideSiteExclusion(siteConfiguration, {
+ ipAddress: requestIP,
+ pathname: validatedPayload.pathname,
+ hostname: validatedPayload.hostname,
+ userAgent: trackingIdentity.userAgent,
+ });
- // Check if the user agent should be excluded from tracking
- if (siteConfiguration.excludedUserAgents && siteConfiguration.excludedUserAgents.length > 0) {
- const isUserAgentExcluded = await siteConfig.isUserAgentExcluded(
- trackingIdentity.userAgent,
- validatedPayload.site_id
+ if (exclusionDecision.excluded) {
+ logger.info(
+ { siteId: validatedPayload.site_id, exclusionReason: exclusionDecision.reason },
+ "Site exclusion matched"
);
- if (isUserAgentExcluded) {
- logger.info({ siteId: validatedPayload.site_id }, "User agent excluded from tracking");
- return reply.status(200).send({
- success: true,
- message: "Event not tracked - user agent excluded",
- });
- }
+ return reply.status(200).send({
+ success: true,
+ message: `Event not tracked - ${exclusionDecision.label} excluded`,
+ });
}
// Create base payload for the event using validated data