@oneuptime/common 13.0.7 → 14.0.0

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

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "@jest/globals";
+import AIInsightEvidence, {
+  ExceptionInsightEvidence,
+  LatencyInsightEvidence,
+  LogSpikeInsightEvidence,
+  MetricDriftInsightEvidence,
+} from "../../../Types/AI/AIInsightEvidence";
+import AIInsightType from "../../../Types/AI/AIInsightType";
+import { PerformanceFindingType } from "../../../Types/AI/CodeFixTaskContext";
+
+/*
+ * AIInsightEvidence is the JSON persisted verbatim on AIInsight.evidence and
+ * rendered long after the raw ClickHouse signals have expired. It is a pure
+ * type module, so these tests pin the wire contract in the two ways that
+ * matter: every AIInsightType maps to exactly one evidence section (checked
+ * exhaustively by the compiler via Record<AIInsightType, ...>), and each
+ * section survives a JSON round trip with its real numbers intact.
+ */
+
+type EvidenceSection = keyof AIInsightEvidence;
+
+/*
+ * The compiler rejects this map if an AIInsightType is added without deciding
+ * which evidence section carries it, or if a section key is renamed.
+ */
+const SECTION_FOR_TYPE: Record<AIInsightType, EvidenceSection> = {
+  [AIInsightType.NewException]: "exception",
+  [AIInsightType.ExceptionSpike]: "exception",
+  [AIInsightType.ErrorLogSpike]: "logSpike",
+  [AIInsightType.TraceLatencyRegression]: "latency",
+  [AIInsightType.MetricDrift]: "metricDrift",
+};
+
+const ALL_SECTIONS: Array<EvidenceSection> = [
+  "exception",
+  "logSpike",
+  "latency",
+  "metricDrift",
+];
+
+const setSections: (evidence: AIInsightEvidence) => Array<string> = (
+  evidence: AIInsightEvidence,
+): Array<string> => {
+  return Object.keys(evidence).filter((key: string) => {
+    return evidence[key as EvidenceSection] !== undefined;
+  });
+};
+
+const roundTrip: (evidence: AIInsightEvidence) => AIInsightEvidence = (
+  evidence: AIInsightEvidence,
+): AIInsightEvidence => {
+  return JSON.parse(JSON.stringify(evidence)) as AIInsightEvidence;
+};
+
+const exceptionEvidence: ExceptionInsightEvidence = {
+  exceptionMessage: "Cannot read properties of undefined (reading 'id')",
+  exceptionType: "TypeError",
+  recentOccurrenceCount: 42,
+  baselineHourlyAverage: 1.5,
+  spikeMultiplier: 28,
+  totalOccurrenceCount: 1200,
+  distinctExceptionGroupCount: 3,
+  firstSeenAt: "2026-09-18T10:00:00.000Z",
+};
+
+const logSpikeEvidence: LogSpikeInsightEvidence = {
+  recentErrorCount: 900,
+  baselineHourlyAverage: 30,
+  spikeMultiplier: 30,
+  windowMinutes: 60,
+  topServices: [
+    { serviceName: "checkout", count: 700 },
+    { serviceName: "payments", count: 200 },
+  ],
+};
+
+const latencyEvidence: LatencyInsightEvidence = {
+  recentP99Ms: 2400,
+  baselineP99Ms: 300,
+  regressionMultiplier: 8,
+  operationName: "GET /orders",
+  sampleTraceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  performanceFindings: [
+    {
+      findingType: PerformanceFindingType.NPlusOneQuery,
+      headline: 'N+1: 27x "SELECT users" under "GET /orders"',
+      evidence: "27 sibling spans, 1900ms combined",
+      spanCount: 27,
+      combinedDurationMs: 1900,
+      traceDurationMs: 2400,
+      percentOfTrace: 79.2,
+      normalizedSpanName: "SELECT users",
+      parentSpanName: "GET /orders",
+      normalizedDbStatement: "SELECT * FROM users WHERE id = ?",
+      dbSystem: "postgresql",
+      implicatedSpans: [
+        { spanId: "00f067aa0ba902b7", name: "SELECT users", durationMs: 70 },
+      ],
+    },
+  ],
+  codeLocations: [
+    {
+      filePath: "src/orders/list.ts",
+      functionName: "listOrders",
+      lineNumber: 88,
+    },
+  ],
+};
+
+const metricDriftEvidence: MetricDriftInsightEvidence = {
+  metricName: "http.server.request.duration",
+  primaryEntityId: "7e6a3c1a-1111-4222-8333-944455556666",
+  recentWeekMean: 150,
+  priorWeekMean: 100,
+  relativeChangePercent: 50,
+  recentSampleCount: 10080,
+  priorSampleCount: 10080,
+};
+
+describe("AIInsightEvidence", () => {
+  test("every insight type maps to a known evidence section", () => {
+    for (const type of Object.values(AIInsightType)) {
+      expect(ALL_SECTIONS).toContain(SECTION_FOR_TYPE[type]);
+    }
+  });
+
+  test("every evidence section is used by at least one insight type", () => {
+    const used: Set<EvidenceSection> = new Set(Object.values(SECTION_FOR_TYPE));
+    expect([...used].sort()).toEqual([...ALL_SECTIONS].sort());
+  });
+
+  test("an empty evidence object is valid (all sections optional)", () => {
+    const evidence: AIInsightEvidence = {};
+    expect(setSections(evidence)).toEqual([]);
+    expect(roundTrip(evidence)).toEqual({});
+  });
+
+  test.each([
+    ["exception", { exception: exceptionEvidence }],
+    ["logSpike", { logSpike: logSpikeEvidence }],
+    ["latency", { latency: latencyEvidence }],
+    ["metricDrift", { metricDrift: metricDriftEvidence }],
+  ] as Array<[EvidenceSection, AIInsightEvidence]>)(
+    "%s evidence survives a JSON round trip with exactly one section set",
+    (section: EvidenceSection, evidence: AIInsightEvidence) => {
+      expect(setSections(evidence)).toEqual([section]);
+      const restored: AIInsightEvidence = roundTrip(evidence);
+      expect(restored).toEqual(evidence);
+      expect(setSections(restored)).toEqual([section]);
+    },
+  );
+
+  test("exception evidence fields are all optional", () => {
+    const minimal: ExceptionInsightEvidence = {};
+    expect(roundTrip({ exception: minimal })).toEqual({ exception: {} });
+  });
+
+  test("undefined optional fields are dropped by serialisation", () => {
+    const evidence: AIInsightEvidence = {
+      latency: {
+        recentP99Ms: 500,
+        baselineP99Ms: 100,
+        regressionMultiplier: 5,
+        operationName: undefined,
+        sampleTraceId: undefined,
+      },
+      exception: undefined,
+    };
+    const restored: AIInsightEvidence = roundTrip(evidence);
+    expect(Object.keys(restored)).toEqual(["latency"]);
+    expect(Object.keys(restored.latency!).sort()).toEqual([
+      "baselineP99Ms",
+      "recentP99Ms",
+      "regressionMultiplier",
+    ]);
+  });
+
+  test("the numeric fields keep their exact values through storage", () => {
+    const restored: AIInsightEvidence = roundTrip({
+      metricDrift: { ...metricDriftEvidence, relativeChangePercent: -12.345 },
+    });
+    expect(restored.metricDrift?.relativeChangePercent).toBe(-12.345);
+    expect(restored.metricDrift?.recentSampleCount).toBe(10080);
+  });
+
+  test("performance findings keep their enum discriminator as a string", () => {
+    const restored: AIInsightEvidence = roundTrip({ latency: latencyEvidence });
+    expect(restored.latency?.performanceFindings?.[0]?.findingType).toBe(
+      "NPlusOneQuery",
+    );
+    expect(restored.latency?.codeLocations?.[0]?.lineNumber).toBe(88);
+  });
+
+  test("log spike topServices preserves order", () => {
+    const restored: AIInsightEvidence = roundTrip({
+      logSpike: logSpikeEvidence,
+    });
+    expect(
+      restored.logSpike?.topServices.map(
+        (service: { serviceName: string; count: number }) => {
+          return service.serviceName;
+        },
+      ),
+    ).toEqual(["checkout", "payments"]);
+  });
+});

package/Tests/Types/API/HostnameFromAuthority.test.ts

@@ -12,8 +12,10 @@ import { describe, expect, test } from "@jest/globals";
  * consumer, which is why a monitor on a non-443 port could never connect —
  * see https://github.com/OneUptime/oneuptime/issues/3225.
  *
- * fromString() is NOT a substitute: it splits on the FIRST colon, which
- * mangles every IPv6 literal.
+ * fromString() used not to be a substitute: it split on the FIRST colon,
+ * which mangled every IPv6 literal. It now delegates IPv6 authorities here
+ * instead, so the two agree on addresses; they still differ on a DNS host,
+ * where fromString keeps its own splitting and its own userinfo handling.
  */
 describe("Hostname.fromAuthority", () => {
   describe("host and port", () => {
@@ -141,18 +143,26 @@ describe("Hostname.fromAuthority", () => {
   });
 
   describe("contrast with fromString", () => {
-    test("fromString rejects an IPv6 literal that fromAuthority handles", () => {
+    test("fromString now agrees with fromAuthority on an IPv6 literal", () => {
       /*
-       * Pinned deliberately: it documents WHY fromAuthority exists, and
-       * guards against someone 'simplifying' one into the other.
+       * This case used to be pinned the other way round: fromString split on
+       * the FIRST colon, so "[::1]:8443" became a host of "[" and the setter
+       * threw. Worse, the unbracketed spelling did NOT throw -- it returned
+       * host "2001" / port 518 for "2001:518:2800:9::2" and a monitor was
+       * saved pointing at a host nobody typed.
        *
-       * fromString splits on the FIRST colon, so "[::1]:8443" becomes a
-       * host of "[" - which the Hostname setter rejects outright.
+       * fromString delegates IPv6 authorities to fromAuthority now, so the
+       * two agree. Kept as a contrast test so a future 'simplification' that
+       * reintroduces the split fails here.
        */
       expect(Hostname.fromAuthority("[::1]:8443").hostname).toBe("[::1]");
-      expect(() => {
-        return Hostname.fromString("[::1]:8443");
-      }).toThrow();
+      expect(Hostname.fromString("[::1]:8443").hostname).toBe("[::1]");
+      expect(Hostname.fromString("[::1]:8443").port?.toNumber()).toBe(8443);
+
+      expect(Hostname.fromString("2001:518:2800:9::2").hostname).toBe(
+        "2001:518:2800:9::2",
+      );
+      expect(Hostname.fromString("2001:518:2800:9::2").port).toBeUndefined();
     });
 
     test("both agree on the simple host:port case", () => {

package/Tests/Types/API/HostnameIPv6.test.ts

@@ -0,0 +1,149 @@
+import Hostname from "../../../Types/API/Hostname";
+import URL from "../../../Types/API/URL";
+import { describe, expect, test } from "@jest/globals";
+import net from "net";
+
+/*
+ * Hostname's handling of IPv6 literals.
+ *
+ * fromString used to split on the FIRST colon, which is meaningless for an
+ * address made of colons. The damage was silent rather than loud: for the
+ * customer address reported below it
+ * returned host "2001" with port 518 — both legal — so nothing threw and the
+ * value the operator typed was simply gone.
+ */
+
+const CUSTOMER_ADDRESS: string = "2001:518:2800:9::2";
+
+describe("Hostname.fromString with an IPv6 literal", () => {
+  test("keeps the whole address instead of its first two groups", () => {
+    const hostname: Hostname = Hostname.fromString(CUSTOMER_ADDRESS);
+
+    expect(hostname.hostname).toBe(CUSTOMER_ADDRESS);
+    expect(hostname.port).toBeUndefined();
+    expect(hostname.toString()).toBe(CUSTOMER_ADDRESS);
+  });
+
+  test("specifically, it is not 2001 port 518", () => {
+    const hostname: Hostname = Hostname.fromString(CUSTOMER_ADDRESS);
+
+    expect(hostname.hostname).not.toBe("2001");
+    expect(hostname.port?.toNumber()).not.toBe(518);
+  });
+
+  test("trims, so a pasted address keeps working", () => {
+    expect(Hostname.fromString(`  ${CUSTOMER_ADDRESS}\n`).hostname).toBe(
+      CUSTOMER_ADDRESS,
+    );
+  });
+
+  test.each([
+    "::1",
+    "::",
+    "2001:db8::",
+    "::ffff:192.0.2.1",
+    "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
+  ])("survives the compressed form %s", (address: string) => {
+    expect(Hostname.fromString(address).hostname).toBe(address);
+  });
+
+  test("a bracketed literal keeps its brackets and gives up its port", () => {
+    const hostname: Hostname = Hostname.fromString(`[${CUSTOMER_ADDRESS}]:179`);
+
+    expect(hostname.hostname).toBe(`[${CUSTOMER_ADDRESS}]`);
+    expect(hostname.port?.toNumber()).toBe(179);
+  });
+
+  test("a value with two colons that is NOT an address is rejected rather than silently split", () => {
+    expect(() => {
+      return Hostname.fromString("example.com:80:90");
+    }).toThrow();
+  });
+});
+
+describe("Hostname.fromString — IPv4 and DNS are unchanged", () => {
+  test.each([
+    ["example.com", "example.com", undefined],
+    ["example.com:8443", "example.com", 8443],
+    ["192.0.2.1", "192.0.2.1", undefined],
+    ["192.0.2.1:179", "192.0.2.1", 179],
+    ["localhost:3000", "localhost", 3000],
+  ])(
+    "%s parses to host %s",
+    (value: string, expectedHost: string, expectedPort?: number) => {
+      const hostname: Hostname = Hostname.fromString(value);
+
+      expect(hostname.hostname).toBe(expectedHost);
+      expect(hostname.port?.toNumber()).toBe(expectedPort);
+    },
+  );
+});
+
+describe("Hostname.toString with a port", () => {
+  test("brackets an IPv6 host, because the unbracketed form is a different address", () => {
+    const hostname: Hostname = new Hostname(CUSTOMER_ADDRESS, 179);
+
+    expect(hostname.toString()).toBe(`[${CUSTOMER_ADDRESS}]:179`);
+
+    // What it used to produce, and why that was not merely ugly:
+    expect(net.isIP(`${CUSTOMER_ADDRESS}:179`)).toBe(6);
+    expect(hostname.toString()).not.toBe(`${CUSTOMER_ADDRESS}:179`);
+  });
+
+  test("the bracketed form re-parses to the same host and port", () => {
+    const roundTripped: Hostname = Hostname.fromString(
+      new Hostname(CUSTOMER_ADDRESS, 179).toString(),
+    );
+
+    expect(roundTripped.hostname).toBe(`[${CUSTOMER_ADDRESS}]`);
+    expect(roundTripped.port?.toNumber()).toBe(179);
+  });
+
+  test("an IPv4 or DNS host keeps the conventional spelling", () => {
+    expect(new Hostname("192.0.2.1", 179).toString()).toBe("192.0.2.1:179");
+    expect(new Hostname("example.com", 8443).toString()).toBe(
+      "example.com:8443",
+    );
+  });
+
+  test("without a port the host is returned exactly as held", () => {
+    expect(new Hostname(CUSTOMER_ADDRESS).toString()).toBe(CUSTOMER_ADDRESS);
+    expect(Hostname.fromAuthority("[::1]").toString()).toBe("[::1]");
+  });
+});
+
+describe("Hostname.isValid validates the address, not just its characters", () => {
+  test.each([CUSTOMER_ADDRESS, "::1", "[::1]", "[::1]:8080", "2001:db8::"])(
+    "accepts %s",
+    (value: string) => {
+      expect(Hostname.isValid(value)).toBe(true);
+    },
+  );
+
+  test.each([
+    "::::",
+    "2001:db8:::1",
+    "[not-an-address]",
+    "gggg::1",
+    "2001:db8::1::2",
+  ])(
+    "rejects %s, which the old character allowlist let through",
+    (value: string) => {
+      expect(Hostname.isValid(value)).toBe(false);
+    },
+  );
+});
+
+describe("URL.toString still emits a valid authority for an IPv6 host", () => {
+  test("brackets survive a round trip", () => {
+    expect(
+      URL.fromString(`https://[${CUSTOMER_ADDRESS}]/health`).toString(),
+    ).toBe(`https://[${CUSTOMER_ADDRESS}]/health`);
+  });
+
+  test("a bracketed host with a port survives a round trip", () => {
+    expect(
+      URL.fromString(`https://[${CUSTOMER_ADDRESS}]:8443/x`).toString(),
+    ).toBe(`https://[${CUSTOMER_ADDRESS}]:8443/x`);
+  });
+});

package/Tests/Types/BaseDatabase/DatabaseCommonInteractionPropsUtilAnonymous.test.ts

@@ -0,0 +1,144 @@
+import DatabaseCommonInteractionProps from "../../../Types/BaseDatabase/DatabaseCommonInteractionProps";
+import DatabaseCommonInteractionPropsUtil from "../../../Types/BaseDatabase/DatabaseCommonInteractionPropsUtil";
+import Exception from "../../../Types/Exception/Exception";
+import ExceptionCode from "../../../Types/Exception/ExceptionCode";
+import NotAuthenticatedException from "../../../Types/Exception/NotAuthenticatedException";
+import NotAuthorizedException from "../../../Types/Exception/NotAuthorizedException";
+import ObjectID from "../../../Types/ObjectID";
+import UserType from "../../../Types/UserType";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * "No credentials at all" is the one refusal the browser client can recover
+ * from. The dashboard's access-token cookie expires with the 15-minute JWT
+ * inside it, so an idle tab's next request arrives with no user and no key,
+ * and the client refreshes the session and replays the request only when the
+ * answer is a 401. isAnonymous decides who is in that bucket and
+ * assertCredentialsPresent turns it into the 401; both are shared by
+ * CommonAPI, the AI privacy filters and ModelPermission, so a mistake here
+ * shows up as a bogus 422 (or a wrongly refreshed API key) everywhere at once.
+ */
+
+type PropsCase = [string, DatabaseCommonInteractionProps];
+
+const anonymousCases: Array<PropsCase> = [
+  ["no props at all", {}],
+  ["a tenant but no user", { tenantId: ObjectID.generate() }],
+  ["an explicitly Public caller", { userType: UserType.Public }],
+  [
+    "a Public caller with a tenant",
+    { tenantId: ObjectID.generate(), userType: UserType.Public },
+  ],
+  /*
+   * userType User without a userId cannot happen through getUserMiddleware,
+   * but if it did there is still nobody to scope to.
+   */
+  ["userType User but no userId", { userType: UserType.User }],
+];
+
+const credentialedCases: Array<PropsCase> = [
+  ["a signed-in user", { userId: ObjectID.generate() }],
+  [
+    "a signed-in user with userType User",
+    { userId: ObjectID.generate(), userType: UserType.User },
+  ],
+  /*
+   * A user id wins even over a Public userType: the caller named a user, so
+   * this is not an expired session.
+   */
+  [
+    "a user id with a Public userType",
+    { userId: ObjectID.generate(), userType: UserType.Public },
+  ],
+  // A project API key: credentials, but no user.
+  [
+    "a project API key",
+    { tenantId: ObjectID.generate(), userType: UserType.API },
+  ],
+  // A master API key / master-admin session with no userId on the props.
+  ["a master admin userType", { userType: UserType.MasterAdmin }],
+];
+
+describe("DatabaseCommonInteractionPropsUtil.AUTHENTICATION_REQUIRED_MESSAGE", () => {
+  test("is the shared login-required sentence", () => {
+    expect(
+      DatabaseCommonInteractionPropsUtil.AUTHENTICATION_REQUIRED_MESSAGE,
+    ).toBe("Authentication required. Please log in to access this resource.");
+  });
+});
+
+describe("DatabaseCommonInteractionPropsUtil.isAnonymous", () => {
+  test.each(anonymousCases)(
+    "is true for %s",
+    (_label: string, props: DatabaseCommonInteractionProps) => {
+      expect(DatabaseCommonInteractionPropsUtil.isAnonymous(props)).toBe(true);
+    },
+  );
+
+  test.each(credentialedCases)(
+    "is false for %s",
+    (_label: string, props: DatabaseCommonInteractionProps) => {
+      expect(DatabaseCommonInteractionPropsUtil.isAnonymous(props)).toBe(false);
+    },
+  );
+
+  /*
+   * isRoot / isMasterAdmin are NOT part of this question - callers that bypass
+   * permissions check those themselves before asking. Pinned so nobody folds
+   * them in and silently changes every caller's ordering.
+   */
+  test("does not look at isRoot or isMasterAdmin", () => {
+    expect(
+      DatabaseCommonInteractionPropsUtil.isAnonymous({ isRoot: true }),
+    ).toBe(true);
+    expect(
+      DatabaseCommonInteractionPropsUtil.isAnonymous({ isMasterAdmin: true }),
+    ).toBe(true);
+  });
+});
+
+describe("DatabaseCommonInteractionPropsUtil.assertCredentialsPresent", () => {
+  test.each(anonymousCases)(
+    "throws a 401 NotAuthenticatedException for %s",
+    (_label: string, props: DatabaseCommonInteractionProps) => {
+      let thrown: unknown = undefined;
+
+      try {
+        DatabaseCommonInteractionPropsUtil.assertCredentialsPresent(props);
+      } catch (error) {
+        thrown = error;
+      }
+
+      expect(thrown).toBeInstanceOf(NotAuthenticatedException);
+      expect(thrown).not.toBeInstanceOf(NotAuthorizedException);
+      expect((thrown as Exception).code).toBe(
+        ExceptionCode.NotAuthenticatedException,
+      );
+      expect((thrown as Exception).code).toBe(401);
+      expect((thrown as Exception).message).toBe(
+        DatabaseCommonInteractionPropsUtil.AUTHENTICATION_REQUIRED_MESSAGE,
+      );
+    },
+  );
+
+  test.each(credentialedCases)(
+    "does not throw for %s",
+    (_label: string, props: DatabaseCommonInteractionProps) => {
+      expect(() => {
+        DatabaseCommonInteractionPropsUtil.assertCredentialsPresent(props);
+      }).not.toThrow();
+    },
+  );
+
+  test("does not mutate the props it is given", () => {
+    const props: DatabaseCommonInteractionProps = {
+      tenantId: ObjectID.generate(),
+      userType: UserType.API,
+    };
+    const before: string = JSON.stringify(props);
+
+    DatabaseCommonInteractionPropsUtil.assertCredentialsPresent(props);
+
+    expect(JSON.stringify(props)).toBe(before);
+  });
+});