🐸 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.mdindex feaf2959a..05c06620a 100644--- a/CONTEXT.md+++ b/CONTEXT.md@@ -12,6 +12,10 @@ _Avoid_: Website, propertyThe 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 URLdiff --git a/server/src/api/sessionReplay/recordSessionReplay.test.ts b/server/src/api/sessionReplay/recordSessionReplay.test.tsindex 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.tsindex 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 limitif (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 trackingconst 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.tsindex 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.tsindex 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 instancediff --git a/server/src/services/sites/siteExclusionDecision.test.ts b/server/src/services/sites/siteExclusionDecision.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 typesconst 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