@oneuptime/common 12.0.32 → 12.0.33

package/Tests/Utils/Telemetry/CaptureSpanExportGating.test.ts

@@ -45,6 +45,16 @@ jest.mock("../../../Server/Utils/Telemetry", () => {
       recordExceptionMarkSpanAsErrorAndEndSpan: (data: unknown): unknown => {
         return recordExceptionMock(data);
       },
+      /*
+       * CaptureSpan ends spans through Telemetry.endSpan rather than calling
+       * span.end() directly, so that ending twice on the error path (the
+       * recorder's finally, then the decorator's) is a no-op instead of an SDK
+       * "You can only call end() on a span once" diagnostic. The real
+       * implementation guards on the span's endTime; the fake just forwards.
+       */
+      endSpan: (span: { end: () => void }): void => {
+        span.end();
+      },
     },
   };
 });
@@ -286,3 +296,138 @@ describe("Telemetry.isSpanExportEnabled (real module)", () => {
     expect(RealTelemetry.isSpanExportEnabled()).toBe(false);
   });
 });
+
+/*
+ * THE MULTI-FRAME CONTRACT.
+ *
+ * One thrown error propagates through every decorated frame on its way out,
+ * and each frame's catch calls the recorder on its OWN span. Nothing here
+ * deduplicates — the report-once marker lives inside the recorder, where it
+ * can be asserted against real exception events (see
+ * Tests/Server/Utils/Telemetry.test.ts). What this file pins is the shape the
+ * recorder depends on: N frames means N recorder calls carrying the SAME
+ * object identity, and every frame still ends its own span exactly once.
+ *
+ * Nothing covered this before, which is why the N-fold occuranceCount
+ * inflation shipped.
+ */
+describe("CaptureSpan across nested frames", () => {
+  beforeEach(() => {
+    spanExportEnabled = true;
+  });
+
+  test("an error crossing three frames reaches the recorder three times, as one object", () => {
+    const boom: Error = new Error("one failure, three frames");
+
+    const inner: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        throw boom;
+      },
+      "inner",
+    );
+    const middle: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        return inner();
+      },
+      "middle",
+    );
+    const outer: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        return middle();
+      },
+      "outer",
+    );
+
+    expect(() => {
+      return outer();
+    }).toThrow(boom);
+
+    expect(recordExceptionMock).toHaveBeenCalledTimes(3);
+
+    /*
+     * Identity, not equality. The report-once marker is a non-enumerable
+     * symbol written onto the thrown value itself, so it only works if every
+     * frame sees the very same object — a wrapped or copied error would
+     * report N times again.
+     */
+    for (const call of recordExceptionMock.mock.calls) {
+      expect((call[0] as { exception: unknown }).exception).toBe(boom);
+    }
+
+    // Three spans created, three ended. No double-end, no leak.
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(3);
+    expect(fakeSpan.end).toHaveBeenCalledTimes(3);
+  });
+
+  test("the same holds for async frames", async () => {
+    const boom: Error = new Error("async, three frames");
+
+    const inner: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<never> => {
+        throw boom;
+      },
+      "inner",
+    );
+    const middle: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<unknown> => {
+        return inner();
+      },
+      "middle",
+    );
+    const outer: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<unknown> => {
+        return middle();
+      },
+      "outer",
+    );
+
+    await expect(outer()).rejects.toBe(boom);
+
+    expect(recordExceptionMock).toHaveBeenCalledTimes(3);
+    expect(fakeSpan.end).toHaveBeenCalledTimes(3);
+  });
+
+  /*
+   * A span that already carries an ERROR must not be downgraded to OK. That is
+   * reachable whenever a decorated method swallows an error and signals
+   * failure another way — Express middleware calling next(err) is the case
+   * that actually occurs — because the decorator then sees a normal return.
+   * The SDK's own setStatus guard does not help: it only early-returns when
+   * the CURRENT status is already OK.
+   */
+  test("a success return does not overwrite an ERROR status set from inside", () => {
+    const erroredSpan: FakeSpan & { status?: { code: number } } = {
+      setStatus: jest.fn(),
+      end: jest.fn(),
+      status: { code: 2 }, // SpanStatusCode.ERROR
+    };
+
+    startActiveSpanMock.mockImplementationOnce((data: any) => {
+      return data.fn(erroredSpan);
+    });
+
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "swallowed the error and returned normally";
+    });
+
+    wrapped();
+
+    expect(erroredSpan.setStatus).not.toHaveBeenCalled();
+  });
+
+  test("a span with no observable status is still marked OK", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "fine";
+    });
+
+    wrapped();
+
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: 1 });
+  });
+});

package/Types/AI/ExceptionAIClassification.ts

@@ -1,27 +1,13 @@
 /*
- * AI triage verdict for a telemetry exception group. Decides how the
- * automatic fix lane treats the group:
+ * The AI triage verdict and the fault domain declared by the throwing code are
+ * the SAME vocabulary, so they are the same enum. It lives in
+ * Common/Types/Telemetry/ErrorClass.ts, which is importable from the emit path
+ * (Types-only, no server dependencies) as well as from the AI lane.
  *
- * - CodeFault: a defect in the monitored code — the only class the
- *   automatic lane opens fix pull requests for.
- * - UserError: expected consequence of invalid end-user input (bad
- *   parameters, malformed values). The right change, if any, is earlier
- *   validation and clearer error UX — routed to a human, never auto-fixed.
- * - ExpectedDenial: an intentional check doing its job (auth failure,
- *   plan/paywall denial, scanner/fuzzer probe tripping validation).
- *   Never auto-fixed; optionally auto-archived.
- * - Infrastructure: environmental conditions (timeouts, connection
- *   resets, resource exhaustion) where a code "fix" is usually tuning —
- *   routed to a human.
- * - Unknown: triage could not decide — treated conservatively (no
- *   automatic fix).
+ * This path is kept so the triage runner, the insight scanner and their tests
+ * keep compiling — and because "the AI's verdict" is a genuinely useful name
+ * at those call sites. It is one SOURCE of the field, not a separate concept:
+ * a class declared by the throwing code outranks it, and a human's click
+ * outranks both.
  */
-enum ExceptionAIClassification {
-  CodeFault = "code-fault",
-  UserError = "user-error",
-  ExpectedDenial = "expected-denial",
-  Infrastructure = "infrastructure",
-  Unknown = "unknown",
-}
-
-export default ExceptionAIClassification;
+export { default } from "../Telemetry/ErrorClass";

package/Types/Email/EmailTemplateType.ts

@@ -99,6 +99,8 @@ enum EmailTemplateType {
 
   EnterpriseLicenseUserLimitBreach = "EnterpriseLicenseUserLimitBreach.hbs",
   EnterpriseLicenseExpiryReminder = "EnterpriseLicenseExpiryReminder.hbs",
+
+  NotificationRollup = "NotificationRollup.hbs",
 }
 
 export default EmailTemplateType;

package/Types/EnterpriseLicense/EnterpriseLicenseInstanceSummary.ts

@@ -11,6 +11,11 @@ type EnterpriseLicenseInstanceSummary = {
   instanceId: string;
   host: string | null;
   userCount: number | null;
+  /*
+   * Whether this row contributed to currentUserCount at the server's cutoff.
+   * Optional so installations remain compatible with older license servers.
+   */
+  isCountedTowardsUsage?: boolean | undefined;
   // ISO date string of the most recent usage report from this instance.
   lastReportedAt: string | null;
   /*

package/Types/EnterpriseLicense/EnterpriseLicenseUsageSnapshot.ts

@@ -0,0 +1,13 @@
+/*
+ * A point-in-time, privacy-preserving view of enterprise license usage for
+ * the Admin Dashboard. Email hashes stay on the server; instance ids are
+ * enough to render statuses from the exact same cutoff as the aggregate.
+ */
+export default interface EnterpriseLicenseUsageSnapshot {
+  currentUserCount: number | null;
+  activeInstanceIds: Array<string>;
+  masterAdminEmails: Array<string>;
+  calculatedAt: string;
+  lastUsageReportedAt: string | null;
+  nextInstanceStatusChangeAt: string | null;
+}

package/Types/EnterpriseLicense/EnterpriseLicenseUserCountSource.ts

@@ -0,0 +1,6 @@
+enum EnterpriseLicenseUserCountSource {
+  Instance = "instance",
+  Legacy = "legacy",
+}
+
+export default EnterpriseLicenseUserCountSource;

package/Types/Exception/ApiException.ts

@@ -1,5 +1,6 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class APIException extends Exception {
   private _error: Error | null = null;
@@ -16,4 +17,13 @@ export default class APIException extends Exception {
       this.error = error;
     }
   }
+
+  /*
+   * The environment failed, not our code and not the caller. Stays an
+   * Issue: it is a real failure worth a human, it is just never something the
+   * automatic fix lane should open a pull request for.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.Infrastructure;
+  }
 }

package/Types/Exception/BadDataException.ts

@@ -1,8 +1,19 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class BadDataException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.BadDataException, message);
   }
+
+  /*
+   * The caller sent something we cannot accept. Nothing is broken; the
+   * request was. Promoted back to CodeFault by ErrorClassResolver when it is
+   * raised outside an HTTP request, because a background job has no client to
+   * blame — see Common/Server/Utils/Telemetry/ErrorClassResolver.ts.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.UserError;
+  }
 }

package/Types/Exception/BadRequestException.ts

@@ -1,8 +1,19 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class BadRequestException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.BadDataException, message);
   }
+
+  /*
+   * The caller sent something we cannot accept. Nothing is broken; the
+   * request was. Promoted back to CodeFault by ErrorClassResolver when it is
+   * raised outside an HTTP request, because a background job has no client to
+   * blame — see Common/Server/Utils/Telemetry/ErrorClassResolver.ts.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.UserError;
+  }
 }

package/Types/Exception/Exception.ts

@@ -1,4 +1,8 @@
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass, {
+  tagErrorClass,
+  tagErrorClassAuthoritative,
+} from "../Telemetry/ErrorClass";
 
 export default class Exception extends Error {
   private _code: ExceptionCode = ExceptionCode.GeneralException;
@@ -14,6 +18,67 @@ export default class Exception extends Error {
   public constructor(code: ExceptionCode, message: string) {
     super(message);
     this.code = code;
+
+    /*
+     * Tag the fault domain at construction. Calling a prototype method from
+     * the base constructor dispatches to the subclass override (prototypes are
+     * wired before the constructor body runs), so each subclass answers for
+     * itself. getErrorClass must therefore never read subclass FIELDS — those
+     * initialize after super() returns — which is why every override returns a
+     * constant.
+     */
+    tagErrorClass(this, this.getErrorClass());
+  }
+
+  /*
+   * The fault domain for this exception class.
+   *
+   * CODE-FAULT IS THE BASE DEFAULT ON PURPOSE. A new subclass added without an
+   * override, or an exception whose author never thought about this, stays
+   * NOISY. The failure mode of the whole classification scheme must be
+   * over-reporting — there is no configuration in which silence is the
+   * default.
+   *
+   * This is deliberately keyed on the CLASS, not on `code`: BadDataException
+   * and BadRequestException are both 400, ServerException and
+   * DatabaseNotConnectedException are both 500, and five ExceptionCode members
+   * (NotImplemented=0, General=1, API=2, BadOperation=5, WebRequest=6) are not
+   * HTTP statuses at all.
+   *
+   * Note that declaring a class here is not the last word: a user-error or
+   * expected-denial raised OUTSIDE an HTTP request is promoted back to
+   * code-fault by ErrorClassResolver, because a background job has no client
+   * to blame.
+   */
+  protected getErrorClass(): ErrorClass {
+    return ErrorClass.CodeFault;
+  }
+
+  /**
+   * Override the declared fault domain for one particular throw, where the
+   * class-level default is wrong at a specific site. Chainable:
+   * `throw new BadDataException(msg).asCodeFault()`.
+   *
+   * These are AUTHORITATIVE: a developer looked at this one site and said what
+   * it is, so unlike the class-level default they are exempt from the
+   * unit-of-work promotion. Use them when the surrounding context genuinely
+   * changes the answer — e.g. a probe reporting that the endpoint it was asked
+   * to check is down, which is the product working, not a defect.
+   */
+  public asCodeFault(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.CodeFault);
+  }
+
+  public asUserError(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.UserError);
+  }
+
+  public asExpectedDenial(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.ExpectedDenial);
+  }
+
+  public asInfrastructure(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.Infrastructure);
   }
 
   public getMessage(): string {

package/Types/Exception/ForbiddenException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class ForbiddenException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.ForbiddenException, message);
   }
+
+  /*
+   * A check we deliberately wrote, doing exactly its job. Denying this
+   * request IS the correct behaviour, so it is not an Issue. Promoted back to
+   * CodeFault outside an HTTP request — see ErrorClassResolver.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.ExpectedDenial;
+  }
 }

package/Types/Exception/NotAuthenticatedException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class NotAuthenticatedException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.NotAuthenticatedException, message);
   }
+
+  /*
+   * A check we deliberately wrote, doing exactly its job. Denying this
+   * request IS the correct behaviour, so it is not an Issue. Promoted back to
+   * CodeFault outside an HTTP request — see ErrorClassResolver.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.ExpectedDenial;
+  }
 }

package/Types/Exception/NotAuthorizedException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class NotAuthorizedException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.NotAuthorizedException, message);
   }
+
+  /*
+   * A check we deliberately wrote, doing exactly its job. Denying this
+   * request IS the correct behaviour, so it is not an Issue. Promoted back to
+   * CodeFault outside an HTTP request — see ErrorClassResolver.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.ExpectedDenial;
+  }
 }

package/Types/Exception/NotFoundException.ts

@@ -1,8 +1,19 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class NotFoundException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.NotFoundException, message);
   }
+
+  /*
+   * The caller sent something we cannot accept. Nothing is broken; the
+   * request was. Promoted back to CodeFault by ErrorClassResolver when it is
+   * raised outside an HTTP request, because a background job has no client to
+   * blame — see Common/Server/Utils/Telemetry/ErrorClassResolver.ts.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.UserError;
+  }
 }

package/Types/Exception/PayloadTooLargeException.ts

@@ -1,8 +1,19 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class PayloadTooLargeException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.PayloadTooLargeException, message);
   }
+
+  /*
+   * The caller sent something we cannot accept. Nothing is broken; the
+   * request was. Promoted back to CodeFault by ErrorClassResolver when it is
+   * raised outside an HTTP request, because a background job has no client to
+   * blame — see Common/Server/Utils/Telemetry/ErrorClassResolver.ts.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.UserError;
+  }
 }

package/Types/Exception/PaymentRequiredException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class PaymentRequiredException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.PaymentRequiredException, message);
   }
+
+  /*
+   * A check we deliberately wrote, doing exactly its job. Denying this
+   * request IS the correct behaviour, so it is not an Issue. Promoted back to
+   * CodeFault outside an HTTP request — see ErrorClassResolver.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.ExpectedDenial;
+  }
 }

package/Types/Exception/ServiceUnavailableException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class ServiceUnavailableException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.ServiceUnavailableException, message);
   }
+
+  /*
+   * The environment failed, not our code and not the caller. Stays an
+   * Issue: it is a real failure worth a human, it is just never something the
+   * automatic fix lane should open a pull request for.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.Infrastructure;
+  }
 }

package/Types/Exception/SsoAuthorizationException.ts

@@ -1,5 +1,6 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class SSOAuthorizationException extends Exception {
   private static message: string = "SSO Authorization Required";
@@ -14,4 +15,13 @@ export default class SSOAuthorizationException extends Exception {
   public static isException(errorMessage: string): boolean {
     return errorMessage === SSOAuthorizationException.message;
   }
+
+  /*
+   * A check we deliberately wrote, doing exactly its job. Denying this
+   * request IS the correct behaviour, so it is not an Issue. Promoted back to
+   * CodeFault outside an HTTP request — see ErrorClassResolver.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.ExpectedDenial;
+  }
 }

package/Types/Exception/TenantNotFoundException.ts

@@ -1,8 +1,19 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class TenantNotFoundException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.TenantNotFoundException, message);
   }
+
+  /*
+   * The caller sent something we cannot accept. Nothing is broken; the
+   * request was. Promoted back to CodeFault by ErrorClassResolver when it is
+   * raised outside an HTTP request, because a background job has no client to
+   * blame — see Common/Server/Utils/Telemetry/ErrorClassResolver.ts.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.UserError;
+  }
 }

package/Types/Exception/TimeoutException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class TimeoutException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.TimeoutException, message);
   }
+
+  /*
+   * The environment failed, not our code and not the caller. Stays an
+   * Issue: it is a real failure worth a human, it is just never something the
+   * automatic fix lane should open a pull request for.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.Infrastructure;
+  }
 }

package/Types/Exception/TooManyRequestsException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class TooManyRequestsException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.TooManyRequestsException, message);
   }
+
+  /*
+   * A check we deliberately wrote, doing exactly its job. Denying this
+   * request IS the correct behaviour, so it is not an Issue. Promoted back to
+   * CodeFault outside an HTTP request — see ErrorClassResolver.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.ExpectedDenial;
+  }
 }

package/Types/Exception/UnableToReachServer.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class UnableToReachServer extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.UnabletoReachServerException, message);
   }
+
+  /*
+   * The environment failed, not our code and not the caller. Stays an
+   * Issue: it is a real failure worth a human, it is just never something the
+   * automatic fix lane should open a pull request for.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.Infrastructure;
+  }
 }

package/Types/Exception/WebsiteRequestException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class WebsiteRequestException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.WebRequestException, message);
   }
+
+  /*
+   * The environment failed, not our code and not the caller. Stays an
+   * Issue: it is a real failure worth a human, it is just never something the
+   * automatic fix lane should open a pull request for.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.Infrastructure;
+  }
 }