@oneuptime/common 11.7.4 → 12.0.0

package/Tests/Server/Utils/SessionReplay/SessionReplayRetention.test.ts

@@ -0,0 +1,229 @@
+import {
+  getSessionReplayRetentionDate,
+  resolveSessionReplayRetentionInDays,
+} from "../../../../Server/Utils/SessionReplay/SessionReplayRetention";
+import OneUptimeDate from "../../../../Types/Date";
+import {
+  DEFAULT_SESSION_REPLAY_RETENTION_IN_DAYS,
+  SESSION_REPLAY_ALLOWED_RETENTION_DAYS,
+} from "../../../../Types/Rum/SessionReplay";
+import { resolveTelemetryRetentionInDays } from "../../../../Types/Telemetry/TelemetryRetentionConfig";
+import { describe, expect, it } from "@jest/globals";
+
+describe("resolveSessionReplayRetentionInDays", () => {
+  it("defaults to 7 days, not the 15 the other pillars use", () => {
+    expect(resolveSessionReplayRetentionInDays({})).toBe(7);
+    expect(DEFAULT_SESSION_REPLAY_RETENTION_IN_DAYS).toBe(7);
+  });
+
+  it("prefers the application's explicit replay retention", () => {
+    expect(
+      resolveSessionReplayRetentionInDays({
+        applicationRetentionInDays: 30,
+        applicationConfig: { sessionReplay: { default: 14 } },
+        projectConfig: { sessionReplay: { default: 90 } },
+      }),
+    ).toBe(30);
+  });
+
+  it("falls back to the application pillar, then the project pillar", () => {
+    expect(
+      resolveSessionReplayRetentionInDays({
+        applicationConfig: { sessionReplay: { default: 14 } },
+        projectConfig: { sessionReplay: { default: 90 } },
+      }),
+    ).toBe(14);
+
+    expect(
+      resolveSessionReplayRetentionInDays({
+        projectConfig: { sessionReplay: { default: 90 } },
+      }),
+    ).toBe(90);
+  });
+
+  it("ignores non-positive, null and undefined candidates", () => {
+    expect(
+      resolveSessionReplayRetentionInDays({
+        applicationRetentionInDays: 0,
+        applicationConfig: { sessionReplay: { default: -5 } },
+        projectConfig: { sessionReplay: { default: null } },
+      }),
+    ).toBe(7);
+
+    expect(
+      resolveSessionReplayRetentionInDays({
+        applicationRetentionInDays: null,
+        applicationConfig: null,
+        projectConfig: null,
+      }),
+    ).toBe(7);
+  });
+
+  it("does not read another pillar's retention", () => {
+    /*
+     * The whole point of the dedicated resolver: a project or application
+     * configured for long log/trace retention must not drag replay along
+     * with it.
+     */
+    expect(
+      resolveSessionReplayRetentionInDays({
+        applicationConfig: {
+          logs: { default: 90 },
+          traces: { default: 90 },
+          metrics: { default: 90 },
+          profiles: { default: 90 },
+        },
+        projectConfig: {
+          logs: { default: 90 },
+          traces: { default: 90 },
+        },
+      }),
+    ).toBe(7);
+  });
+
+  it("clamps to the allowed closed set, rounding up", () => {
+    /*
+     * Each distinct value becomes its own partition per ingest day under
+     * expiry-based partitioning, so the set has to stay closed. Rounding
+     * up never silently destroys evidence the customer asked to keep.
+     */
+    expect(SESSION_REPLAY_ALLOWED_RETENTION_DAYS).toEqual([1, 7, 14, 30, 90]);
+
+    const clamped: Array<number> = [2, 8, 15, 31, 45].map(
+      (days: number): number => {
+        return resolveSessionReplayRetentionInDays({
+          applicationRetentionInDays: days,
+        });
+      },
+    );
+
+    expect(clamped).toEqual([7, 14, 30, 90, 90]);
+  });
+
+  it("clamps a mis-set value down to the maximum instead of honouring it", () => {
+    expect(
+      resolveSessionReplayRetentionInDays({
+        applicationRetentionInDays: 900,
+      }),
+    ).toBe(90);
+  });
+
+  it("only ever returns a value from the allowed set", () => {
+    for (let days: number = -5; days <= 200; days++) {
+      const resolved: number = resolveSessionReplayRetentionInDays({
+        applicationRetentionInDays: days,
+      });
+
+      expect(SESSION_REPLAY_ALLOWED_RETENTION_DAYS).toContain(resolved);
+    }
+  });
+
+  it("differs from resolveTelemetryRetentionInDays on the case that motivated it", () => {
+    /*
+     * An application with 90-day trace retention and nothing replay-specific
+     * configured. The generic resolver hands back 90 because
+     * serviceRetentionInDays outranks the project pillar; the replay
+     * resolver hands back 7. If this assertion ever fails, someone has
+     * changed the generic candidate order and the two can be reunified.
+     */
+    expect(
+      resolveTelemetryRetentionInDays({
+        pillar: "sessionReplay",
+        serviceRetentionInDays: 90,
+      }),
+    ).toBe(90);
+
+    expect(resolveSessionReplayRetentionInDays({})).toBe(7);
+  });
+});
+
+describe("getSessionReplayRetentionDate", () => {
+  it("derives the expiry from the session start, so a session expires atomically", () => {
+    /*
+     * Chunks of one session can arrive hours apart. Deriving from the
+     * shared, server-clamped session start is what stops the same
+     * session's chunks landing in different expiry partitions and being
+     * TTL-dropped halfway through.
+     */
+    const sessionStart: Date = OneUptimeDate.fromString(
+      "2026-01-01T00:00:00.000Z",
+    );
+
+    const retentionDate: Date = getSessionReplayRetentionDate({
+      serverClampedSessionStart: sessionStart,
+      retentionInDays: 7,
+    });
+
+    expect(
+      OneUptimeDate.getDaysBetweenTwoDates(sessionStart, retentionDate),
+    ).toBe(7);
+  });
+
+  it("gives every chunk of a session the same expiry regardless of when it arrived", () => {
+    /*
+     * The arrival time is moved, not the arguments. Calling the function
+     * twice with identical arguments would only assert that it is a
+     * function; what has to hold is that the wall clock at ingest does not
+     * enter the arithmetic, because a chunk buffered offline and flushed
+     * hours later must land in the same expiry partition as the first
+     * chunk of its session.
+     */
+    const sessionStart: Date = OneUptimeDate.fromString(
+      "2026-01-01T00:00:00.000Z",
+    );
+
+    jest.useFakeTimers();
+
+    try {
+      jest.setSystemTime(
+        OneUptimeDate.fromString("2026-01-01T00:00:05.000Z").getTime(),
+      );
+
+      const firstChunk: Date = getSessionReplayRetentionDate({
+        serverClampedSessionStart: sessionStart,
+        retentionInDays: 14,
+      });
+
+      /* Same session, flushed from an offline buffer nine hours later. */
+      jest.setSystemTime(
+        OneUptimeDate.fromString("2026-01-01T09:13:00.000Z").getTime(),
+      );
+
+      const lateFlush: Date = getSessionReplayRetentionDate({
+        serverClampedSessionStart: sessionStart,
+        retentionInDays: 14,
+      });
+
+      expect(lateFlush.getTime()).toBe(firstChunk.getTime());
+
+      /* And it really is session start + 14 days, not clock + 14 days. */
+      expect(
+        OneUptimeDate.getDaysBetweenTwoDates(sessionStart, lateFlush),
+      ).toBe(14);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it("moves the expiry when the session start moves", () => {
+    /*
+     * The negative of the test above: an expiry that ignored its input
+     * entirely would pass that one too.
+     */
+    const earlier: Date = getSessionReplayRetentionDate({
+      serverClampedSessionStart: OneUptimeDate.fromString(
+        "2026-01-01T00:00:00.000Z",
+      ),
+      retentionInDays: 14,
+    });
+
+    const later: Date = getSessionReplayRetentionDate({
+      serverClampedSessionStart: OneUptimeDate.fromString(
+        "2026-01-03T00:00:00.000Z",
+      ),
+      retentionInDays: 14,
+    });
+
+    expect(OneUptimeDate.getDaysBetweenTwoDates(earlier, later)).toBe(2);
+  });
+});

package/Tests/Server/Utils/SessionReplay/SessionReplayTargeting.test.ts

@@ -0,0 +1,246 @@
+import ObjectID from "../../../../Types/ObjectID";
+import {
+  SESSION_REPLAY_MAX_USER_REF_LENGTH,
+  SESSION_REPLAY_TARGET_TTL_SECONDS,
+} from "../../../../Types/Rum/SessionReplay";
+
+/*
+ * The one-shot "record this user's next session" Redis key. Two properties
+ * carry all the weight and get most of the assertions: the key must never
+ * contain the raw end-user reference (references are routinely emails, and
+ * a Redis KEYS listing must not be a directory of the customer's users),
+ * and the hot-path consume must be un-crashable - a Redis blip degrades to
+ * "not targeted", never to a config error.
+ */
+
+const setMock: jest.Mock = jest.fn();
+const delMock: jest.Mock = jest.fn();
+const existsMock: jest.Mock = jest.fn();
+
+let isConnectedValue: boolean = true;
+let clientValue: unknown = {
+  set: setMock,
+  del: delMock,
+  exists: existsMock,
+};
+
+jest.mock("../../../../Server/Infrastructure/Redis", () => {
+  return {
+    __esModule: true,
+    default: {
+      getClient: (): unknown => {
+        return clientValue;
+      },
+      isConnected: (): boolean => {
+        return isConnectedValue;
+      },
+    },
+  };
+});
+
+jest.mock("../../../../Server/Utils/Logger", () => {
+  return {
+    __esModule: true,
+    default: {
+      debug: jest.fn(),
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn(),
+    },
+  };
+});
+
+import SessionReplayTargeting, {
+  SessionReplayTargetRef,
+} from "../../../../Server/Utils/SessionReplay/SessionReplayTargeting";
+
+const PROJECT_ID: ObjectID = ObjectID.generate();
+
+function ref(
+  overrides?: Partial<SessionReplayTargetRef>,
+): SessionReplayTargetRef {
+  return {
+    projectId: PROJECT_ID,
+    appIdentifier: "checkout-web",
+    userRef: "jane@example.com",
+    ...overrides,
+  };
+}
+
+describe("SessionReplayTargeting", (): void => {
+  beforeEach((): void => {
+    jest.clearAllMocks();
+    isConnectedValue = true;
+    clientValue = { set: setMock, del: delMock, exists: existsMock };
+  });
+
+  describe("isUsableUserRef", (): void => {
+    it("accepts a plain reference", (): void => {
+      expect(SessionReplayTargeting.isUsableUserRef("user-42")).toBe(true);
+    });
+
+    it("rejects empty, whitespace-only and non-strings", (): void => {
+      expect(SessionReplayTargeting.isUsableUserRef("")).toBe(false);
+      expect(SessionReplayTargeting.isUsableUserRef("   ")).toBe(false);
+      expect(SessionReplayTargeting.isUsableUserRef(42)).toBe(false);
+      expect(SessionReplayTargeting.isUsableUserRef(null)).toBe(false);
+      expect(SessionReplayTargeting.isUsableUserRef(undefined)).toBe(false);
+      expect(SessionReplayTargeting.isUsableUserRef({})).toBe(false);
+    });
+
+    it("enforces the shared length cap exactly", (): void => {
+      expect(
+        SessionReplayTargeting.isUsableUserRef(
+          "x".repeat(SESSION_REPLAY_MAX_USER_REF_LENGTH),
+        ),
+      ).toBe(true);
+      expect(
+        SessionReplayTargeting.isUsableUserRef(
+          "x".repeat(SESSION_REPLAY_MAX_USER_REF_LENGTH + 1),
+        ),
+      ).toBe(false);
+    });
+  });
+
+  describe("buildTargetKey", (): void => {
+    it("is deterministic and scoped by project id", (): void => {
+      const key: string = SessionReplayTargeting.buildTargetKey(ref());
+
+      expect(SessionReplayTargeting.buildTargetKey(ref())).toBe(key);
+      expect(key).toContain(PROJECT_ID.toString());
+      expect(key.startsWith("session-replay:target:")).toBe(true);
+    });
+
+    /*
+     * The privacy property the HMAC exists for: the raw reference (often
+     * an email) must be unrecoverable from the key.
+     */
+    it("never embeds the raw user reference", (): void => {
+      const key: string = SessionReplayTargeting.buildTargetKey(ref());
+
+      expect(key).not.toContain("jane");
+      expect(key).not.toContain("example.com");
+    });
+
+    it("differs across user, application and project", (): void => {
+      const base: string = SessionReplayTargeting.buildTargetKey(ref());
+
+      expect(
+        SessionReplayTargeting.buildTargetKey(ref({ userRef: "other-user" })),
+      ).not.toBe(base);
+      expect(
+        SessionReplayTargeting.buildTargetKey(
+          ref({ appIdentifier: "other-app" }),
+        ),
+      ).not.toBe(base);
+      expect(
+        SessionReplayTargeting.buildTargetKey(
+          ref({ projectId: ObjectID.generate() }),
+        ),
+      ).not.toBe(base);
+    });
+
+    /*
+     * The dashboard sends the identifier as stored; the recorder's header
+     * arrives however the customer typed it into their page. The two must
+     * meet at one key.
+     */
+    it("normalises app identifier case and whitespace, and trims the userRef", (): void => {
+      const base: string = SessionReplayTargeting.buildTargetKey(ref());
+
+      expect(
+        SessionReplayTargeting.buildTargetKey(
+          ref({ appIdentifier: "  CHECKOUT-Web  " }),
+        ),
+      ).toBe(base);
+      expect(
+        SessionReplayTargeting.buildTargetKey(
+          ref({ userRef: "  jane@example.com  " }),
+        ),
+      ).toBe(base);
+    });
+  });
+
+  describe("setTarget", (): void => {
+    it("writes the one-shot key with the 24h TTL", async (): Promise<void> => {
+      await SessionReplayTargeting.setTarget(ref());
+
+      expect(setMock).toHaveBeenCalledWith(
+        SessionReplayTargeting.buildTargetKey(ref()),
+        "1",
+        "EX",
+        SESSION_REPLAY_TARGET_TTL_SECONDS,
+      );
+    });
+
+    it("throws when Redis is unavailable, so the dashboard hears the truth", async (): Promise<void> => {
+      isConnectedValue = false;
+
+      await expect(SessionReplayTargeting.setTarget(ref())).rejects.toThrow();
+      expect(setMock).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("clearTarget / isTargetPending", (): void => {
+    it("clears by deleting the derived key", async (): Promise<void> => {
+      await SessionReplayTargeting.clearTarget(ref());
+
+      expect(delMock).toHaveBeenCalledWith(
+        SessionReplayTargeting.buildTargetKey(ref()),
+      );
+    });
+
+    it("reports pending from EXISTS", async (): Promise<void> => {
+      existsMock.mockResolvedValueOnce(1);
+      expect(await SessionReplayTargeting.isTargetPending(ref())).toBe(true);
+
+      existsMock.mockResolvedValueOnce(0);
+      expect(await SessionReplayTargeting.isTargetPending(ref())).toBe(false);
+    });
+  });
+
+  describe("consumeTarget", (): void => {
+    it("answers true exactly when the atomic DEL removed the key", async (): Promise<void> => {
+      delMock.mockResolvedValueOnce(1);
+      expect(await SessionReplayTargeting.consumeTarget(ref())).toBe(true);
+
+      /* Second take of the same key: someone else already consumed it. */
+      delMock.mockResolvedValueOnce(0);
+      expect(await SessionReplayTargeting.consumeTarget(ref())).toBe(false);
+    });
+
+    it("refuses an unusable reference before touching Redis", async (): Promise<void> => {
+      expect(
+        await SessionReplayTargeting.consumeTarget(ref({ userRef: "   " })),
+      ).toBe(false);
+      expect(
+        await SessionReplayTargeting.consumeTarget(
+          ref({
+            userRef: "x".repeat(SESSION_REPLAY_MAX_USER_REF_LENGTH + 1),
+          }),
+        ),
+      ).toBe(false);
+
+      expect(delMock).not.toHaveBeenCalled();
+    });
+
+    /*
+     * The hot-path guarantee: every failure shape answers "not targeted"
+     * rather than throwing into the config endpoint.
+     */
+    it("degrades to false on a Redis error", async (): Promise<void> => {
+      delMock.mockRejectedValueOnce(new Error("READONLY"));
+
+      expect(await SessionReplayTargeting.consumeTarget(ref())).toBe(false);
+    });
+
+    it("degrades to false when Redis is disconnected or absent", async (): Promise<void> => {
+      isConnectedValue = false;
+      expect(await SessionReplayTargeting.consumeTarget(ref())).toBe(false);
+
+      isConnectedValue = true;
+      clientValue = null;
+      expect(await SessionReplayTargeting.consumeTarget(ref())).toBe(false);
+    });
+  });
+});

package/Tests/Server/Utils/Telemetry/TelemetryFanInWriter.test.ts

@@ -1563,3 +1563,113 @@ describe("isRetryableInsertError — TransientInsertError", () => {
     expect(isRetryableInsertError(err.causeError)).toBe(true);
   });
 });
+
+/*
+ * The batcher counts ROWS, not bytes, so one global maxBatchRows cannot be
+ * right for tables whose rows differ by orders of magnitude. A session replay
+ * chunk row carries the whole decompressed rrweb payload in one column, so at
+ * the global 100,000 default a single flush would attempt a multi-hundred-MB
+ * insert.
+ */
+describe("per-table maxBatchRows override", () => {
+  test("a table with an override flushes at the override, not the global", async () => {
+    const target: TestTarget = makeTarget({ tableName: "RumSessionChunkV1" });
+
+    // maxWaitMs is huge on purpose: a timer-triggered flush would prove nothing.
+    const writer: TelemetryFanInWriter = new TelemetryFanInWriter(
+      makeOptions({
+        maxBatchRows: 100,
+        maxWaitMs: 60_000,
+        maxBatchRowsByTable: { RumSessionChunkV1: 3 },
+      }),
+    );
+
+    const result: FanInSubmitResult = await writer.submit(target, makeRows(3));
+
+    await result.flushed;
+
+    expect(target.insertJsonRows).toHaveBeenCalledTimes(1);
+    expect(rowSeqs(callRows(target, 0))).toEqual([0, 1, 2]);
+  });
+
+  test("a table without an override keeps the global maxBatchRows", async () => {
+    const target: TestTarget = makeTarget({ tableName: "SpanItem" });
+
+    const writer: TelemetryFanInWriter = new TelemetryFanInWriter(
+      makeOptions({
+        maxBatchRows: 100,
+        maxWaitMs: 25,
+        maxBatchRowsByTable: { RumSessionChunkV1: 3 },
+      }),
+    );
+
+    const result: FanInSubmitResult = await writer.submit(target, makeRows(3));
+
+    // Not size-triggered at 3 rows; only the timer gets this one out.
+    expect(target.insertJsonRows).not.toHaveBeenCalled();
+
+    await result.flushed;
+
+    expect(target.insertJsonRows).toHaveBeenCalledTimes(1);
+  });
+
+  test("a non-positive override is ignored rather than honoured", async () => {
+    const target: TestTarget = makeTarget({ tableName: "RumSessionChunkV1" });
+
+    /*
+     * A zero would make the cut loop spin, so the override is only applied
+     * when it is a positive number.
+     */
+    const writer: TelemetryFanInWriter = new TelemetryFanInWriter(
+      makeOptions({
+        maxBatchRows: 3,
+        maxWaitMs: 60_000,
+        maxBatchRowsByTable: { RumSessionChunkV1: 0 },
+      }),
+    );
+
+    const result: FanInSubmitResult = await writer.submit(target, makeRows(3));
+
+    await result.flushed;
+
+    expect(target.insertJsonRows).toHaveBeenCalledTimes(1);
+  });
+
+  test("the session replay override defaults to 2000 from the environment", () => {
+    const saved: string | undefined =
+      process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"];
+
+    delete process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"];
+
+    try {
+      const options: FanInWriterOptions = readFanInWriterOptionsFromEnv();
+
+      expect(options.maxBatchRowsByTable?.["RumSessionChunkV1"]).toBe(2000);
+    } finally {
+      if (saved === undefined) {
+        delete process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"];
+      } else {
+        process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"] = saved;
+      }
+    }
+  });
+
+  test("the session replay override is readable from the environment", () => {
+    const saved: string | undefined =
+      process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"];
+
+    process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"] = "500";
+
+    try {
+      const options: FanInWriterOptions = readFanInWriterOptionsFromEnv();
+
+      expect(options.maxBatchRowsByTable?.["RumSessionChunkV1"]).toBe(500);
+    } finally {
+      if (saved === undefined) {
+        delete process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"];
+      } else {
+        process.env["TELEMETRY_FANIN_MAX_BATCH_ROWS_SESSION_REPLAY"] = saved;
+      }
+    }
+  });
+});

package/Tests/Types/AI/AIRunStatus.test.ts

@@ -1,6 +1,31 @@
 import AIRunStatus, { AIRunStatusHelper } from "../../../Types/AI/AIRunStatus";
 
 describe("AIRunStatusHelper", () => {
+  /*
+   * Database guards spell "still live" as notIn(terminalStatuses()), so the
+   * list and the predicate must never disagree — a status missing from the
+   * list turns a finished run into a permanent dedupe block.
+   */
+  describe("terminalStatuses", () => {
+    test("lists every terminal status and nothing else", () => {
+      const terminal: Array<AIRunStatus> = Object.values(AIRunStatus).filter(
+        (status: AIRunStatus): boolean => {
+          return AIRunStatusHelper.isTerminalStatus(status);
+        },
+      );
+
+      expect(AIRunStatusHelper.terminalStatuses().sort()).toEqual(
+        terminal.sort(),
+      );
+    });
+
+    test("includes NoFixFound — a run that found no fix is over", () => {
+      expect(AIRunStatusHelper.terminalStatuses()).toContain(
+        AIRunStatus.NoFixFound,
+      );
+    });
+  });
+
   describe("isTerminalStatus", () => {
     test.each([
       AIRunStatus.Completed,