Skip to content

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

10.3 KB
Raw Blame
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { SiteConfigData } from "../../lib/siteConfig.js";
import type { TrackingRequest } from "./trackingRequest.js";

const mocks = vi.hoisted(() => ({
  addBotEvent: vi.fn(),
  addBotObservation: vi.fn(),
  addPageview: vi.fn(),
  checkBotBlocking: vi.fn(),
  decideSiteExclusion: vi.fn(),
  isSiteOverLimit: vi.fn(),
  isSiteWithoutPlan: vi.fn(),
  updateSession: vi.fn(),
  generateUserId: vi.fn(),
  generateUserIdFromClientId: vi.fn(),
}));

vi.mock("../usageService.js", () => ({
  usageService: { isSiteOverLimit: mocks.isSiteOverLimit, isSiteWithoutPlan: mocks.isSiteWithoutPlan },
}));

vi.mock("./pageviewQueue.js", () => ({
  pageviewQueue: { add: mocks.addPageview },
}));

vi.mock("../sessions/sessionsService.js", () => ({
  sessionsService: { updateSession: mocks.updateSession },
}));

vi.mock("./botBlocking/index.js", () => ({
  checkBotBlocking: mocks.checkBotBlocking,
}));

vi.mock("./botBlocking/botEventQueue.js", () => ({
  botEventQueue: { add: mocks.addBotEvent },
  botObservationQueue: { add: mocks.addBotObservation },
}));

vi.mock("../sites/siteExclusionDecision.js", () => ({
  decideSiteExclusion: mocks.decideSiteExclusion,
}));

vi.mock("../userId/userIdService.js", () => ({
  userIdService: {
    generateUserId: mocks.generateUserId,
    generateUserIdFromClientId: mocks.generateUserIdFromClientId,
  },
}));

import { ingestEvent } from "./ingestEvent.js";

const site = {
  id: "site_abc",
  siteId: 42,
  type: "web",
  blockBots: true,
  saltUserIds: false,
  trackIp: false,
  firstPartyProxy: false,
  excludedIPs: [],
  excludedCountries: [],
  excludedPaths: [],
  excludedHostnames: [],
  excludedUserAgents: [],
  excludedASNs: [],
  excludedQueryParams: [],
} as unknown as SiteConfigData;

const lookupAsn = vi.fn(() => null);

function trackingRequest(overrides: Partial<TrackingRequest> = {}): TrackingRequest {
  return {
    payload: {
      type: "pageview",
      site_id: "site_abc",
      pathname: "/pricing",
      hostname: "example.com",
    } as TrackingRequest["payload"],
    site,
    ipAddress: "198.51.100.10",
    userAgent: "Mozilla/5.0",
    candidateIps: ["198.51.100.10"],
    trustedServerSideIngestion: false,
    headers: { "user-agent": "Mozilla/5.0" },
    lookupAsn,
    receivedAt: new Date("2026-08-14T10:38:37.000Z"),
    ...overrides,
  };
}

describe("ingestEvent", () => {
  beforeEach(() => {
    vi.clearAllMocks();
    mocks.decideSiteExclusion.mockResolvedValue({ excluded: false });
    mocks.isSiteOverLimit.mockReturnValue(false);
    mocks.isSiteWithoutPlan.mockReturnValue(false);
    mocks.checkBotBlocking.mockResolvedValue(null);
    mocks.updateSession.mockResolvedValue({ sessionId: "session-alice" });
    mocks.generateUserId.mockResolvedValue("shared-fingerprint");
    mocks.addPageview.mockResolvedValue(undefined);
  });

  it("queues an accepted event with its session and resolved identity", async () => {
    const outcome = await ingestEvent(
      trackingRequest({
        payload: {
          type: "pageview",
          site_id: "site_abc",
          user_id: "employee-alice",
        } as TrackingRequest["payload"],
      })
    );

    expect(outcome).toEqual({ status: "tracked", sessionId: "session-alice" });
    expect(mocks.updateSession).toHaveBeenCalledWith({
      userId: "shared-fingerprint",
      identifiedUserId: "employee-alice",
      siteId: 42,
    });
    expect(mocks.addPageview).toHaveBeenCalledWith(
      expect.objectContaining({
        site_id: 42,
        sessionId: "session-alice",
        userId: "shared-fingerprint",
        identifiedUserId: "employee-alice",
        ipAddress: "198.51.100.10",
        timestamp: "2026-08-14T10:38:37.000Z",
      })
    );
  });

  it("passes the resolved request to the Site Exclusion Decision without re-deriving it", async () => {
    await ingestEvent(
      trackingRequest({
        ipAddress: "203.0.113.7",
        candidateIps: ["203.0.113.7", "198.51.100.10"],
        userAgent: "ServerSDK/1.0",
        payload: {
          type: "pageview",
          site_id: "site_abc",
          pathname: "/admin/users",
          querystring: "utm_source=newsletter",
          hostname: "example.com",
        } as TrackingRequest["payload"],
      })
    );

    expect(mocks.decideSiteExclusion).toHaveBeenCalledWith(site, {
      ipAddress: "203.0.113.7",
      candidateIps: ["203.0.113.7", "198.51.100.10"],
      pathname: "/admin/users",
      querystring: "utm_source=newsletter",
      hostname: "example.com",
      userAgent: "ServerSDK/1.0",
      lookupAsn,
    });
  });

  it("matches exclusions against the whole URL, and stores it cut to the column limits", async () => {
    // A query string cut first would lose `preview` and slip past its exclusion.
    const querystring = `?padding=${"x".repeat(2050)}&preview=1`;
    const pathname = `/${"p".repeat(3000)}`;

    await ingestEvent(
      trackingRequest({
        payload: { type: "pageview", site_id: "site_abc", pathname, querystring } as TrackingRequest["payload"],
      })
    );

    expect(mocks.decideSiteExclusion).toHaveBeenCalledWith(site, expect.objectContaining({ pathname, querystring }));
    expect(mocks.addPageview).toHaveBeenCalledWith(
      expect.objectContaining({ pathname: pathname.slice(0, 2048), querystring: querystring.slice(0, 2048) })
    );
  });

  // The ordering fix: exclusion used to run *after* bot detection, so a Site
  // owner's own excluded office IP still drove every anomaly counter.
  it("decides exclusion before bot detection, so excluded traffic leaves no trace", async () => {
    mocks.decideSiteExclusion.mockResolvedValue({
      excluded: true,
      reason: "path",
      label: "path",
      value: "/admin/users",
    });

    const outcome = await ingestEvent(trackingRequest());

    expect(outcome).toEqual({
      status: "excluded",
      exclusion: { excluded: true, reason: "path", label: "path", value: "/admin/users" },
    });
    expect(mocks.checkBotBlocking).not.toHaveBeenCalled();
    expect(mocks.isSiteOverLimit).not.toHaveBeenCalled();
    expect(mocks.generateUserId).not.toHaveBeenCalled();
    expect(mocks.addPageview).not.toHaveBeenCalled();
    expect(mocks.addBotEvent).not.toHaveBeenCalled();
  });

  it("stops at the monthly limit before charging bot detection a Redis round-trip", async () => {
    mocks.isSiteOverLimit.mockReturnValue(true);

    const outcome = await ingestEvent(trackingRequest());

    expect(outcome).toEqual({ status: "over_limit" });
    expect(mocks.checkBotBlocking).not.toHaveBeenCalled();
    expect(mocks.addPageview).not.toHaveBeenCalled();
  });

  it("drops every event for a site whose organization has no plan", async () => {
    mocks.isSiteWithoutPlan.mockReturnValue(true);

    const outcome = await ingestEvent(trackingRequest());

    expect(outcome).toEqual({ status: "no_plan" });
    expect(mocks.checkBotBlocking).not.toHaveBeenCalled();
    expect(mocks.generateUserId).not.toHaveBeenCalled();
    expect(mocks.addPageview).not.toHaveBeenCalled();
  });

  it("routes enforced bot detections to the bot queue instead of a session", async () => {
    mocks.checkBotBlocking.mockResolvedValue({
      enforced: true,
      eventProperties: { bot_layer: "ua_pattern" },
    });

    const outcome = await ingestEvent(trackingRequest());

    expect(outcome).toEqual({ status: "bot" });
    expect(mocks.addBotEvent).toHaveBeenCalledWith(
      expect.objectContaining({
        bot_layer: "ua_pattern",
        sessionId: "bot:shared-fingerprint",
      })
    );
    expect(mocks.updateSession).not.toHaveBeenCalled();
    expect(mocks.addPageview).not.toHaveBeenCalled();
    expect(mocks.addBotObservation).not.toHaveBeenCalled();
  });

  it("tracks an unenforced bot detection normally and records the observation", async () => {
    // A Site with bot blocking turned off. The visitor's event must reach
    // `events` exactly as it would have before detection ran for these Sites at
    // all — the detection is recorded alongside it, and changes nothing.
    mocks.checkBotBlocking.mockResolvedValue({
      enforced: false,
      eventProperties: { bot_layer: "ua_pattern" },
    });

    const outcome = await ingestEvent(trackingRequest());

    expect(outcome).toEqual({ status: "tracked", sessionId: "session-alice" });
    expect(mocks.addPageview).toHaveBeenCalledTimes(1);
    expect(mocks.addBotEvent).not.toHaveBeenCalled();
    expect(mocks.addBotObservation).toHaveBeenCalledWith(
      expect.objectContaining({
        bot_layer: "ua_pattern",
        // The real session, not a synthetic bot one: the event is in `events`.
        sessionId: "session-alice",
      })
    );
  });

  it("records no observation when nothing was detected", async () => {
    await ingestEvent(trackingRequest());

    expect(mocks.addBotObservation).not.toHaveBeenCalled();
  });

  it("hands bot detection the request's own headers and ASN resolver", async () => {
    await ingestEvent(
      trackingRequest({
        headers: { "user-agent": "Mozilla/5.0", "accept-language": "en-US" },
        trustedServerSideIngestion: true,
      })
    );

    expect(mocks.checkBotBlocking).toHaveBeenCalledWith(
      expect.objectContaining({
        headers: { "user-agent": "Mozilla/5.0", "accept-language": "en-US" },
        blockBots: true,
        trustedServerSideIngestion: true,
        isMobileSite: false,
        lookupAsn,
      })
    );
  });

  // Anomaly counters are namespaced by this id. Passing the incoming identifier
  // instead split one Site across two namespaces — the text id the UI emits and
  // the legacy numeric id still accepted — each seeing half the traffic.
  it("namespaces bot detection by the numeric Site id, not the incoming identifier", async () => {
    await ingestEvent(trackingRequest());

    expect(mocks.checkBotBlocking).toHaveBeenCalledWith(
      expect.objectContaining({
        payload: expect.objectContaining({ siteId: 42 }),
      })
    );
  });

  it("reuses the request's Site Configuration for identity instead of re-reading it", async () => {
    await ingestEvent(
      trackingRequest({
        site: { ...site, saltUserIds: true } as SiteConfigData,
      })
    );

    expect(mocks.generateUserId).toHaveBeenCalledWith("198.51.100.10", "Mozilla/5.0", 42, {
      saltUserIds: true,
      lookupAsn,
      // The event's own instant decides its salt day, not the clock at hash time.
      receivedAt: new Date("2026-08-14T10:38:37.000Z"),
    });
  });
});