@oneuptime/common 14.0.2 → 14.0.3

package/Tests/Utils/Rum/SessionTraceState.test.ts

@@ -0,0 +1,239 @@
+import {
+  ParsedSessionTraceState,
+  SESSION_TRACE_STATE_KEY,
+  buildSessionTraceStateMember,
+  parseSessionTraceState,
+} from "../../../Utils/Rum/SessionTraceState";
+
+const SESSION_ID: string = "0123456789abcdef0123456789abcdef";
+const PARENT_ID: string = "fedcba9876543210";
+
+/*
+ * The W3C / OpenTelemetry validation rules for a tracestate member, copied
+ * from @opentelemetry/core's validators. A member that fails them is
+ * dropped by the backend's propagator before any span sees it.
+ */
+const W3C_KEY_PATTERN: RegExp =
+  /^(?:[a-z][_0-9a-z\-*/]{0,255}|[a-z0-9][_0-9a-z\-*/]{0,240}@[a-z][_0-9a-z\-*/]{0,13})$/;
+const W3C_VALUE_PATTERN: RegExp = /^[ -~]{0,255}[!-~]$/;
+const W3C_VALUE_FORBIDDEN: RegExp = /,|=/;
+
+describe("SessionTraceState", () => {
+  describe("buildSessionTraceStateMember", () => {
+    it("writes the session id under the oneuptime key", () => {
+      expect(buildSessionTraceStateMember(SESSION_ID)).toBe(
+        `oneuptime=sid:${SESSION_ID}`,
+      );
+      expect(SESSION_TRACE_STATE_KEY).toBe("oneuptime");
+    });
+
+    it("adds the synthetic parent id only when one is given", () => {
+      expect(buildSessionTraceStateMember(SESSION_ID, PARENT_ID)).toBe(
+        `oneuptime=sid:${SESSION_ID};p:${PARENT_ID}`,
+      );
+      expect(buildSessionTraceStateMember(SESSION_ID, null)).toBe(
+        `oneuptime=sid:${SESSION_ID}`,
+      );
+      expect(buildSessionTraceStateMember(SESSION_ID, "")).toBe(
+        `oneuptime=sid:${SESSION_ID}`,
+      );
+    });
+
+    it("produces a member every W3C tracestate parser accepts", () => {
+      for (const member of [
+        buildSessionTraceStateMember(SESSION_ID),
+        buildSessionTraceStateMember(SESSION_ID, PARENT_ID),
+      ]) {
+        const [key, value] = member.split("=") as [string, string];
+
+        expect(W3C_KEY_PATTERN.test(key)).toBe(true);
+        expect(W3C_VALUE_PATTERN.test(value)).toBe(true);
+        expect(W3C_VALUE_FORBIDDEN.test(value)).toBe(false);
+        expect(member.length).toBeLessThanOrEqual(512);
+      }
+    });
+  });
+
+  describe("parseSessionTraceState", () => {
+    it("round-trips what the recorder writes", () => {
+      expect(
+        parseSessionTraceState(buildSessionTraceStateMember(SESSION_ID)),
+      ).toEqual({
+        sessionTraceState: {
+          sessionId: SESSION_ID,
+          syntheticParentSpanId: null,
+        },
+        remainingTraceState: "",
+      });
+
+      expect(
+        parseSessionTraceState(
+          buildSessionTraceStateMember(SESSION_ID, PARENT_ID),
+        ),
+      ).toEqual({
+        sessionTraceState: {
+          sessionId: SESSION_ID,
+          syntheticParentSpanId: PARENT_ID,
+        },
+        remainingTraceState: "",
+      });
+    });
+
+    it("finds the member among other vendors' members and strips only ours", () => {
+      const parsed: ParsedSessionTraceState = parseSessionTraceState(
+        `dd=s:1;o:rum, oneuptime=sid:${SESSION_ID} ,congo=t61rcWkgMzE,tenant@vendor=x`,
+      );
+
+      expect(parsed.sessionTraceState?.sessionId).toBe(SESSION_ID);
+      expect(parsed.remainingTraceState).toBe(
+        "dd=s:1;o:rum,congo=t61rcWkgMzE,tenant@vendor=x",
+      );
+    });
+
+    it("tolerates optional whitespace and tabs around members and fields", () => {
+      const parsed: ParsedSessionTraceState = parseSessionTraceState(
+        `\toneuptime = sid:${SESSION_ID} ; p:${PARENT_ID}\t`,
+      );
+
+      expect(parsed.sessionTraceState).toEqual({
+        sessionId: SESSION_ID,
+        syntheticParentSpanId: PARENT_ID,
+      });
+    });
+
+    it("reads fields in any order and ignores unknown ones", () => {
+      expect(
+        parseSessionTraceState(
+          `oneuptime=v:2;p:${PARENT_ID};x:y;sid:${SESSION_ID}`,
+        ).sessionTraceState,
+      ).toEqual({
+        sessionId: SESSION_ID,
+        syntheticParentSpanId: PARENT_ID,
+      });
+    });
+
+    it("lowercases hex ids", () => {
+      expect(
+        parseSessionTraceState(
+          `oneuptime=sid:${SESSION_ID.toUpperCase()};p:${PARENT_ID.toUpperCase()}`,
+        ).sessionTraceState,
+      ).toEqual({
+        sessionId: SESSION_ID,
+        syntheticParentSpanId: PARENT_ID,
+      });
+    });
+
+    it("takes the first oneuptime member and strips every one", () => {
+      const other: string = "ffffffffffffffffffffffffffffffff";
+      const parsed: ParsedSessionTraceState = parseSessionTraceState(
+        `oneuptime=sid:${SESSION_ID},a=b,oneuptime=sid:${other}`,
+      );
+
+      expect(parsed.sessionTraceState?.sessionId).toBe(SESSION_ID);
+      expect(parsed.remainingTraceState).toBe("a=b");
+    });
+
+    it("strips a malformed member of ours but yields no session", () => {
+      for (const member of [
+        "oneuptime=sid:not-hex",
+        "oneuptime=sid:0123",
+        `oneuptime=sid:${SESSION_ID}00`,
+        "oneuptime=sid:00000000000000000000000000000000",
+        "oneuptime=p:fedcba9876543210",
+        "oneuptime=",
+        "oneuptime",
+        `oneuptime=${SESSION_ID}`,
+      ]) {
+        const parsed: ParsedSessionTraceState = parseSessionTraceState(
+          `${member},keep=me`,
+        );
+
+        expect(parsed.sessionTraceState).toBeNull();
+        expect(parsed.remainingTraceState).toBe("keep=me");
+      }
+    });
+
+    it("keeps the session when only the parent id is malformed", () => {
+      for (const parent of ["xyz", "0000000000000000", "fedcba98765432", ""]) {
+        expect(
+          parseSessionTraceState(`oneuptime=sid:${SESSION_ID};p:${parent}`)
+            .sessionTraceState,
+        ).toEqual({ sessionId: SESSION_ID, syntheticParentSpanId: null });
+      }
+    });
+
+    it("does not match keys that only contain the word", () => {
+      const value: string = `acme@oneuptime=sid:${SESSION_ID},oneuptimex=sid:${SESSION_ID}`;
+      const parsed: ParsedSessionTraceState = parseSessionTraceState(value);
+
+      expect(parsed.sessionTraceState).toBeNull();
+      expect(parsed.remainingTraceState).toBe(value);
+    });
+
+    it("returns the value untouched when there is no member of ours", () => {
+      expect(parseSessionTraceState("rojo=00f067aa0ba902b7")).toEqual({
+        sessionTraceState: null,
+        remainingTraceState: "rojo=00f067aa0ba902b7",
+      });
+      expect(parseSessionTraceState("")).toEqual({
+        sessionTraceState: null,
+        remainingTraceState: "",
+      });
+    });
+
+    it("never throws on non-string input", () => {
+      for (const value of [
+        undefined,
+        null,
+        42,
+        true,
+        {},
+        [`oneuptime=sid:${SESSION_ID}`],
+      ]) {
+        expect(parseSessionTraceState(value)).toEqual({
+          sessionTraceState: null,
+          remainingTraceState: "",
+        });
+      }
+    });
+
+    it("reads no session out of oversized or over-long lists but still strips ours", () => {
+      const others: string = "a=b,".repeat(3000);
+      const huge: string = `oneuptime=sid:${SESSION_ID};p:${PARENT_ID},${others}`;
+      const parsedHuge: ParsedSessionTraceState = parseSessionTraceState(huge);
+
+      expect(parsedHuge.sessionTraceState).toBeNull();
+      expect(parsedHuge.remainingTraceState).toBe("a=b,".repeat(2999) + "a=b");
+      expect(parsedHuge.remainingTraceState).not.toContain(SESSION_ID);
+
+      const many: string = `${"k=v,".repeat(80)}oneuptime=sid:${SESSION_ID}`;
+      const parsedMany: ParsedSessionTraceState = parseSessionTraceState(many);
+
+      expect(parsedMany.sessionTraceState).toBeNull();
+      expect(parsedMany.remainingTraceState).toBe("k=v,".repeat(79) + "k=v");
+    });
+
+    it("leaves an oversized list with no member of ours untouched", () => {
+      const huge: string = "a=b,".repeat(3000);
+      expect(parseSessionTraceState(huge)).toEqual({
+        sessionTraceState: null,
+        remainingTraceState: huge,
+      });
+    });
+
+    it("accepts a long but legitimate list that ends with our member", () => {
+      const others: Array<string> = [];
+
+      for (let i: number = 0; i < 20; i++) {
+        others.push(`vendor${i}=${"x".repeat(30)}`);
+      }
+
+      const value: string = `${others.join(",")},oneuptime=sid:${SESSION_ID}`;
+      expect(value.length).toBeGreaterThan(600);
+
+      const parsed: ParsedSessionTraceState = parseSessionTraceState(value);
+      expect(parsed.sessionTraceState?.sessionId).toBe(SESSION_ID);
+      expect(parsed.remainingTraceState).toBe(others.join(","));
+    });
+  });
+});

package/Types/Incident/IncidentAlertLink.ts

@@ -0,0 +1,38 @@
+/*
+ * Shared between the dashboard and the server for linking alerts to incidents
+ * (the IncidentAlert model).
+ */
+
+/*
+ * Declaring an incident from alerts sends the alert ids along with the
+ * incident as `miscDataProps[INCIDENT_ALERT_IDS_TO_LINK_KEY]` (an array of id
+ * strings). IncidentService validates them before the incident is created and
+ * links them once it exists, so API clients get the same one-request flow as
+ * the dashboard.
+ */
+export const INCIDENT_ALERT_IDS_TO_LINK_KEY: string = "alertIdsToLink";
+
+/*
+ * The create-incident page reads the alerts to declare an incident from out of
+ * this query string parameter, as a comma separated list of alert ids.
+ */
+export const INCIDENT_CREATE_ALERT_IDS_QUERY_PARAM: string = "alertIds";
+
+/*
+ * The most alerts one action can link to an incident: declaring an incident
+ * from alerts, or linking a selection of alerts from the alerts table. Every
+ * link writes a feed entry on the incident and the alert, and the incident's
+ * entry is posted to its Slack / Microsoft Teams channels, so an unbounded
+ * "select all" would flood both. It also keeps the alert ids within what a URL
+ * can carry.
+ */
+export const MAX_ALERTS_PER_INCIDENT_LINK_ACTION: number = 50;
+
+/*
+ * What linking a pair that is already linked answers with - whether the
+ * duplicate is caught by the model's unique-together check or, when two
+ * requests race past it, by the unique index itself. The dashboard counts a
+ * link that fails with this message as done.
+ */
+export const INCIDENT_ALERT_ALREADY_LINKED_MESSAGE: string =
+  "This alert is already linked to this incident.";

package/Types/Permission.ts

@@ -1851,6 +1851,12 @@ enum Permission {
   EditIncidentEpisodeMember = "EditIncidentEpisodeMember",
   ReadIncidentEpisodeMember = "ReadIncidentEpisodeMember",
 
+  // Incident Alert (alerts linked to an incident) Permissions
+  CreateIncidentAlert = "CreateIncidentAlert",
+  DeleteIncidentAlert = "DeleteIncidentAlert",
+  EditIncidentAlert = "EditIncidentAlert",
+  ReadIncidentAlert = "ReadIncidentAlert",
+
   // Incident Episode State Timeline Permissions
   CreateIncidentEpisodeStateTimeline = "CreateIncidentEpisodeStateTimeline",
   DeleteIncidentEpisodeStateTimeline = "DeleteIncidentEpisodeStateTimeline",
@@ -15015,6 +15021,48 @@ export class PermissionHelper {
         group: PermissionGroup.Incident,
       },
 
+      // Incident Alert (alerts linked to an incident) Permissions
+      {
+        permission: Permission.CreateIncidentAlert,
+        title: "Create Incident Alert",
+        description:
+          "This permission can link alerts to incidents in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Incident,
+      },
+      {
+        permission: Permission.DeleteIncidentAlert,
+        title: "Delete Incident Alert",
+        description:
+          "This permission can unlink alerts from incidents in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Incident,
+      },
+      {
+        permission: Permission.EditIncidentAlert,
+        title: "Edit Incident Alert",
+        description:
+          "This permission can edit the links between alerts and incidents in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Incident,
+      },
+      {
+        permission: Permission.ReadIncidentAlert,
+        title: "Read Incident Alert",
+        description:
+          "This permission can read which alerts are linked to which incidents in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Incident,
+      },
+
       // Incident Episode State Timeline Permissions
       {
         permission: Permission.CreateIncidentEpisodeStateTimeline,

package/Types/Rum/SessionReplay.ts

@@ -851,19 +851,38 @@ export interface SessionReplayConfigResponse {
    */
 
   /*
-   * Origins the recorder may inject a W3C traceparent header into, so a
-   * recording links to the backend trace of the request that failed —
-   * with NO OTel browser instrumentation on the customer's page.
+   * CROSS-origin APIs the recorder may inject a W3C traceparent header
+   * into, so a recording links to the backend trace of the request that
+   * failed — with NO OTel browser instrumentation on the customer's page.
+   * Listed origins get traceparent only, never the session id. The page's
+   * own origin needs no entry: see sameOriginTracePropagation.
    *
-   * Empty means never inject, and that default is the safety mechanism:
-   * adding a request header turns a simple cross-origin request into a
-   * preflighted one, and an API that does not allow traceparent in
+   * Empty means no cross-origin injection, and that default is the safety
+   * mechanism: adding a request header turns a simple cross-origin request
+   * into a preflighted one, and an API that does not allow traceparent in
    * Access-Control-Allow-Headers would start failing because a RUM
    * script was installed. Each listed origin is an explicit statement
    * that its API accepts the header.
    */
   tracePropagationOrigins?: Array<string>;
 
+  /*
+   * RumApplication.sessionReplaySameOriginTracePropagation. When true, the
+   * recorder adds a traceparent (unless the request or an inner tracing
+   * instrumentation already sets one) and a tracestate member carrying the
+   * replay session id (`oneuptime=sid:<id>`, see Utils/Rum/SessionTraceState)
+   * to fetch/XHR requests to the page's OWN origin, and only while the
+   * session is uploading with consent. Span ingest reads the member back,
+   * so backend spans link to the recording with no customer code.
+   *
+   * A same-origin request is never preflighted, so this needs no origin
+   * list and defaults on; the switch turns it off per application without
+   * a customer redeploy. The server always sends an explicit boolean (false
+   * on every disabled response) and the recorder reads anything but `true`
+   * as off, so an older server or a cached stub never turns it on.
+   */
+  sameOriginTracePropagation?: boolean;
+
   /*
    * Performance capture budgets, milliseconds; 0 disables that trigger.
    * Exceeding a budget fires the Performance capture trigger, so slow

package/Types/Rum/WebVitals.ts

@@ -1,6 +1,12 @@
 export interface WebVitalDefinition {
   key: string;
   label: string;
+  /*
+   * What the vital measures, in words a non-specialist can act on. The
+   * Good / Poor limits are not repeated here - describeWebVitalThresholds
+   * derives them from `thresholds`, so the two cannot disagree.
+   */
+  description: string;
   unit: "ms" | "score";
   thresholds: { warn: number; danger: number };
   names: Array<string>;
@@ -11,6 +17,8 @@ export const WebVitalDefinitions: Array<WebVitalDefinition> = [
   {
     key: "lcp",
     label: "Largest Contentful Paint",
+    description:
+      "How long until the biggest image or block of text on screen has rendered - roughly when the page looks loaded to the visitor.",
     unit: "ms",
     thresholds: { warn: 2500, danger: 4000 },
     names: [
@@ -23,6 +31,8 @@ export const WebVitalDefinitions: Array<WebVitalDefinition> = [
   {
     key: "inp",
     label: "Interaction to Next Paint",
+    description:
+      "How quickly the page reacts to clicks, taps and key presses: the delay before the screen visibly updates, for close to the slowest interaction on the page.",
     unit: "ms",
     thresholds: { warn: 200, danger: 500 },
     names: [
@@ -35,6 +45,8 @@ export const WebVitalDefinitions: Array<WebVitalDefinition> = [
   {
     key: "cls",
     label: "Cumulative Layout Shift",
+    description:
+      "How much the page jumps around while it loads - content moving under the visitor's cursor or finger. A score, not a time: lower is better and 0 means nothing moved.",
     unit: "score",
     thresholds: { warn: 0.1, danger: 0.25 },
     names: [
@@ -47,6 +59,8 @@ export const WebVitalDefinitions: Array<WebVitalDefinition> = [
   {
     key: "fcp",
     label: "First Contentful Paint",
+    description:
+      "How long until the first text or image appears, so the visitor can see the page has started loading.",
     unit: "ms",
     thresholds: { warn: 1800, danger: 3000 },
     names: [
@@ -59,6 +73,8 @@ export const WebVitalDefinitions: Array<WebVitalDefinition> = [
   {
     key: "ttfb",
     label: "Time to First Byte",
+    description:
+      "How long the browser waited for the first byte of the page from your server, including redirects, looking up the address and connecting.",
     unit: "ms",
     thresholds: { warn: 800, danger: 1800 },
     names: [
@@ -69,3 +85,39 @@ export const WebVitalDefinitions: Array<WebVitalDefinition> = [
     ],
   },
 ];
+
+// A threshold the way a person would say it: "2.5 s", "800 ms", "0.1".
+export function formatWebVitalThreshold(
+  value: number,
+  unit: WebVitalDefinition["unit"],
+): string {
+  if (unit === "score") {
+    return String(value);
+  }
+
+  if (value < 1000) {
+    return `${value} ms`;
+  }
+
+  return `${Number((value / 1000).toFixed(2))} s`;
+}
+
+/*
+ * The Good / Poor limits in words, matching how the overview rates a value:
+ * below `warn` is Good, at or above `danger` is Poor, and anything between
+ * needs work.
+ */
+export function describeWebVitalThresholds(
+  definition: Pick<WebVitalDefinition, "unit" | "thresholds">,
+): string {
+  const warn: string = formatWebVitalThreshold(
+    definition.thresholds.warn,
+    definition.unit,
+  );
+  const danger: string = formatWebVitalThreshold(
+    definition.thresholds.danger,
+    definition.unit,
+  );
+
+  return `Good below ${warn}; poor at ${danger} or more.`;
+}

package/UI/Components/Detail/FieldLabel.tsx

@@ -1,6 +1,7 @@
 import Link from "../Link/Link";
 import { DetailSideLink } from "./Field";
 import useTranslateValue from "../../Utils/Translation";
+import InfoTooltip from "../Tooltip/InfoTooltip";
 import React, { FunctionComponent, ReactElement } from "react";
 
 export enum Size {
@@ -16,6 +17,8 @@ export interface ComponentProps {
   sideLink?: DetailSideLink | undefined;
   size?: Size | undefined;
   isCardStyle?: boolean | undefined;
+  // What the field means, shown in an (i) tooltip beside the title.
+  tooltip?: string | undefined;
 }
 
 const FieldLabelElement: FunctionComponent<ComponentProps> = (
@@ -40,6 +43,11 @@ const FieldLabelElement: FunctionComponent<ComponentProps> = (
         >
           <span className={`${props.alignClassName} flex items-center gap-1.5`}>
             {translatedTitle}
+            <InfoTooltip
+              label={translatedTitle}
+              text={props.tooltip}
+              className="relative z-10 normal-case tracking-normal"
+            />
             <span className="w-1 h-1 rounded-full bg-gray-300"></span>
           </span>
           {props.sideLink && translatedSideLinkText && props.sideLink?.url && (

package/UI/Components/InfoCard/InfoCard.tsx

@@ -20,6 +20,8 @@ export interface ComponentProps {
   isSelected?: boolean | undefined;
   // Announced in place of the title when the card is clickable.
   ariaLabel?: string | undefined;
+  // What the value means, shown in an (i) tooltip beside the title.
+  tooltip?: string | undefined;
 }
 
 const InfoCard: FunctionComponent<ComponentProps> = (
@@ -37,6 +39,50 @@ const InfoCard: FunctionComponent<ComponentProps> = (
       ? "border-indigo-500 ring-1 ring-indigo-500"
       : "border-gray-200";
 
+  /*
+   * A clickable card with a tooltip cannot stay a role="button" div: the (i)
+   * is a button of its own, and a button's children are presentational, so
+   * screen readers would never reach it. The card becomes a plain container
+   * with a real button laid over it, and the (i) sits above that button
+   * (FieldLabel lifts it with relative z-10). Cards without a tooltip keep
+   * the markup below, unchanged.
+   */
+  if (isClickable && props.tooltip?.trim()) {
+    return (
+      <div
+        className={`relative rounded-xl bg-white border ${borderClassName} shadow-sm hover:shadow-md transition-shadow duration-200 p-5 ${props.className || ""}`}
+      >
+        <button
+          type="button"
+          onClick={props.onClick}
+          aria-pressed={
+            props.isSelected !== undefined
+              ? Boolean(props.isSelected)
+              : undefined
+          }
+          /*
+           * Named like the old role="button" card, which read its title and
+           * value - unless the value is an element, which has no text to
+           * borrow here.
+           */
+          aria-label={
+            props.ariaLabel ||
+            (typeof props.value === "string"
+              ? `${props.title} ${props.value}`
+              : props.title)
+          }
+          className="absolute inset-0 rounded-xl cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-2"
+        />
+        <div className="mb-2">
+          <FieldLabelElement title={props.title} tooltip={props.tooltip} />
+        </div>
+        <div className={props.textClassName || "text-gray-900"}>
+          {props.value}
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div
       onClick={props.onClick}
@@ -75,7 +121,7 @@ const InfoCard: FunctionComponent<ComponentProps> = (
       className={`rounded-xl bg-white border ${borderClassName} shadow-sm hover:shadow-md transition-shadow duration-200 p-5 ${isClickable ? "cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-2" : ""} ${props.className || ""}`}
     >
       <div className="mb-2">
-        <FieldLabelElement title={props.title} />
+        <FieldLabelElement title={props.title} tooltip={props.tooltip} />
       </div>
       <div className={props.textClassName || "text-gray-900"}>
         {props.value}