@oneuptime/common 12.0.32 → 12.0.33

package/Server/Utils/OutboundUserAgent.ts

@@ -0,0 +1,152 @@
+import Dictionary from "../../Types/Dictionary";
+import { AppVersion } from "../EnvironmentConfig";
+
+/*
+ * The User-Agent this platform presents when it calls somebody else's HTTP
+ * server on a project's behalf — TAXII threat-intel feeds and the external
+ * Data Source connectors (Prometheus, Loki, Elasticsearch, REST API).
+ *
+ * This is not cosmetic. With no User-Agent of our own, axios stamps its
+ * default `axios/<version>` on every request, and a bare HTTP-library UA is
+ * a stock rule in most WAFs, CDNs and bot-management products: the operator
+ * on the far end sees an anonymous script rather than a named product, and
+ * answers 403 before the request reaches their API at all. A product token
+ * plus a URL is what makes the traffic allowlistable, and what lets the far
+ * end's logs and abuse contact attribute it to something.
+ *
+ * Shape follows RFC 9110 §10.1.5 — a product/product-version token
+ * followed by a comment:
+ *
+ *   OneUptime/8.0.1234 (+https://oneuptime.com)
+ *
+ * The version is dropped rather than printed as "unknown" when APP_VERSION
+ * is unset (development, and any deployment that does not inject it), so
+ * the UA never advertises a version that is not one.
+ */
+
+export const OUTBOUND_USER_AGENT_HEADER_NAME: string = "User-Agent";
+export const OUTBOUND_USER_AGENT_PRODUCT: string = "OneUptime";
+export const OUTBOUND_USER_AGENT_URL: string = "https://oneuptime.com";
+
+/*
+ * APP_VERSION is supplied by whoever deployed the instance, and a header
+ * value carrying CR/LF is a request-smuggling primitive, so the version is
+ * filtered down to RFC 9110 token characters instead of being trusted. The
+ * length cap keeps a junk value from becoming a multi-kilobyte header.
+ */
+const VERSION_DISALLOWED_CHARACTERS: RegExp = /[^A-Za-z0-9._+-]/g;
+const MAX_VERSION_LENGTH: number = 64;
+
+/*
+ * EnvironmentConfig's own placeholder when APP_VERSION is unset — a
+ * sentinel, not a version, so it never reaches the wire.
+ */
+const UNKNOWN_VERSION: string = "unknown";
+
+export default class OutboundUserAgent {
+  // The User-Agent for this running instance.
+  public static get(): string {
+    return this.build(AppVersion);
+  }
+
+  /*
+   * Pure builder — takes the version rather than reading it, so the format
+   * is testable without reaching into the process environment.
+   */
+  public static build(version?: string | undefined): string {
+    const sanitizedVersion: string = this.sanitizeVersion(version);
+
+    const product: string = sanitizedVersion
+      ? `${OUTBOUND_USER_AGENT_PRODUCT}/${sanitizedVersion}`
+      : OUTBOUND_USER_AGENT_PRODUCT;
+
+    return `${product} (+${OUTBOUND_USER_AGENT_URL})`;
+  }
+
+  /*
+   * A version safe to put in a header, or "" when there is nothing worth
+   * printing (unset, the "unknown" sentinel, or nothing left after
+   * filtering).
+   */
+  public static sanitizeVersion(version?: string | undefined): string {
+    const trimmed: string = (version || "").trim();
+
+    if (trimmed === "" || trimmed.toLowerCase() === UNKNOWN_VERSION) {
+      return "";
+    }
+
+    return trimmed
+      .replace(VERSION_DISALLOWED_CHARACTERS, "")
+      .substring(0, MAX_VERSION_LENGTH);
+  }
+
+  /*
+   * Whether the caller already set a User-Agent of its own. Header names
+   * are case-insensitive on the wire, so the check is too — otherwise a
+   * caller's lowercase `user-agent` would end up alongside ours rather
+   * than replacing it. A present-but-blank value counts as absent: an
+   * empty UA is the same anonymous-client problem this whole file exists
+   * to avoid.
+   */
+  public static hasUserAgent(
+    headers?: Dictionary<string> | undefined,
+  ): boolean {
+    if (!headers) {
+      return false;
+    }
+
+    for (const headerName of Object.keys(headers)) {
+      if (
+        headerName.toLowerCase() !==
+        OUTBOUND_USER_AGENT_HEADER_NAME.toLowerCase()
+      ) {
+        continue;
+      }
+
+      const value: string | undefined = headers[headerName];
+
+      if (typeof value === "string" && value.trim() !== "") {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /*
+   * The headers to send: the caller's, plus our User-Agent when the caller
+   * did not set one. An explicit User-Agent always wins — a REST API data
+   * source whose provider demands a particular UA configures it as a custom
+   * header, and that must reach the wire untouched.
+   *
+   * Returns a new dictionary; the caller's is never mutated.
+   */
+  public static withDefault(
+    headers?: Dictionary<string> | undefined,
+  ): Dictionary<string> {
+    const merged: Dictionary<string> = { ...(headers || {}) };
+
+    if (this.hasUserAgent(merged)) {
+      return merged;
+    }
+
+    /*
+     * A blank `user-agent` in any casing is dropped rather than left
+     * beside ours: two keys differing only in case are one header on the
+     * wire, and which of them survives normalization is not something to
+     * leave to the HTTP client.
+     */
+    for (const headerName of Object.keys(merged)) {
+      if (
+        headerName.toLowerCase() ===
+        OUTBOUND_USER_AGENT_HEADER_NAME.toLowerCase()
+      ) {
+        delete merged[headerName];
+      }
+    }
+
+    merged[OUTBOUND_USER_AGENT_HEADER_NAME] = this.get();
+
+    return merged;
+  }
+}

package/Server/Utils/StartServer.ts

@@ -37,6 +37,12 @@ import "./Process";
 import Response from "./Response";
 import SpanUtil from "./Telemetry/SpanUtil";
 import TelemetryContext from "./Telemetry/TelemetryContext";
+import {
+  COMPONENT_ATTRIBUTE_KEY,
+  TelemetryComponent,
+  UNIT_OF_WORK_ATTRIBUTE_KEY,
+  UnitOfWork,
+} from "../../Types/Telemetry/UnitOfWork";
 import mountVendorAssets from "./VendorAssets";
 import { api } from "@opentelemetry/sdk-node";
 import StatusCode from "../../Types/API/StatusCode";
@@ -284,13 +290,34 @@ app.use((req: ExpressRequest, _res: ExpressResponse, next: NextFunction) => {
    * ContextSpanProcessor and Logger read this ambient context, every span and
    * log produced downstream inherits it automatically.
    */
-  TelemetryContext.runWithContext({ requestId: requestId }, () => {
-    SpanUtil.addAttributesToCurrentSpan({
+  TelemetryContext.runWithContext(
+    {
       requestId: requestId,
-    });
+      /*
+       * Seed the unit of work EXPLICITLY. ErrorClassResolver honours a
+       * user-error / expected-denial classification only inside an HTTP
+       * request — everywhere else there is no client to blame, so those
+       * classes are promoted back to code-fault. runWithContext inherits the
+       * enclosing scope, so leaving this unset would let a request's marker
+       * leak into background work started from inside the request.
+       */
+      [UNIT_OF_WORK_ATTRIBUTE_KEY]: UnitOfWork.HttpRequest,
+      /*
+       * Which deployment role served this. service.name cannot answer it: the
+       * Helm chart runs the worker from the same image and entrypoint as the
+       * API, so worker pods also report service.name="api".
+       */
+      [COMPONENT_ATTRIBUTE_KEY]:
+        LocalCache.getString("app", "name") || TelemetryComponent.Api,
+    },
+    () => {
+      SpanUtil.addAttributesToCurrentSpan({
+        requestId: requestId,
+      });
 
-    next();
-  });
+      next();
+    },
+  );
 });
 
 export interface InitFuctionOptions {
@@ -509,20 +536,25 @@ export const expressErrorHandler: (
 ): void => {
   logger.error(err, getLogAttributesFromRequest(_req as OneUptimeRequest));
 
-  // Mark span as error.
-  if (err) {
-    const span: api.Span | undefined = api.trace.getSpan(api.context.active());
-    if (span) {
-      // record exception
-      span.recordException(err);
-
-      // set span status code to ERROR
-      span.setStatus({
-        code: api.SpanStatusCode.ERROR,
-        message: err.message,
-      });
-    }
-  }
+  /*
+   * Deliberately does NOT record the exception on a span.
+   *
+   * There is no HTTP instrumentation (Telemetry.init passes an empty
+   * `instrumentations` array) and nothing creates a request-scoped span, so at
+   * this point the ambient span is either absent or an already-ENDED
+   * @CaptureSpan span — and addEvent no-ops on an ended span. On the whole
+   * BaseAPI CRUD surface this emitted exactly zero events while looking like
+   * it emitted one.
+   *
+   * Where it DID fire was the handful of @CaptureSpan-decorated middleware
+   * that swallow an error and call next(err) from inside their own still-open
+   * span. There it wrote to a span the request does not own, and — because the
+   * raw error was passed to span.recordException, and the SDK reads
+   * `exception.code` before `exception.name` — it typed the event with the
+   * HTTP status ("400", "422") instead of the class name. Those middleware now
+   * rethrow instead of swallowing, so CaptureSpan's normalized recorder does
+   * the right thing on the right span.
+   */
 
   if (res.headersSent) {
     next(err);

package/Server/Utils/Telemetry/CaptureSpan.ts

@@ -4,6 +4,34 @@ import { JSONObject } from "../../../Types/JSON";
 import JSONFunctions from "../../../Types/JSONFunctions";
 import { DisableTelemetry } from "../../EnvironmentConfig";
 
+/*
+ * Mark a span OK, but never DOWNGRADE an ERROR someone else already set.
+ *
+ * The SDK's own setStatus guard only early-returns when the CURRENT status is
+ * already OK, so an OK written after an ERROR wins. That is reachable whenever
+ * a decorated method swallows an error and signals failure by another route
+ * (Express middleware calling next(err) is the classic case): the method
+ * "returns successfully" from the decorator's point of view, and the span ends
+ * up marked OK while carrying an exception event.
+ */
+function markSpanOk(span: Span): void {
+  try {
+    const currentStatus: { code?: number } | undefined = (
+      span as unknown as { status?: { code?: number } }
+    ).status;
+
+    if (currentStatus && currentStatus.code === SpanStatusCode.ERROR) {
+      return;
+    }
+  } catch {
+    // Span implementation without an observable status — set it normally.
+  }
+
+  span.setStatus({
+    code: SpanStatusCode.OK,
+  });
+}
+
 function CaptureSpan(data?: {
   name?: string;
   attributes?: JSONObject;
@@ -86,9 +114,7 @@ function CaptureSpan(data?: {
             if (result instanceof Promise) {
               return result
                 .then((res: any) => {
-                  span.setStatus({
-                    code: SpanStatusCode.OK,
-                  });
+                  markSpanOk(span);
                   return res;
                 })
                 .catch((err: Error) => {
@@ -100,12 +126,10 @@ function CaptureSpan(data?: {
                   throw err;
                 })
                 .finally(() => {
-                  span.end();
+                  Telemetry.endSpan(span);
                 });
             }
-            span.setStatus({
-              code: SpanStatusCode.OK,
-            });
+            markSpanOk(span);
             return result;
           } catch (err) {
             Telemetry.recordExceptionMarkSpanAsErrorAndEndSpan({
@@ -116,7 +140,7 @@ function CaptureSpan(data?: {
             throw err;
           } finally {
             if (!(result instanceof Promise)) {
-              span.end();
+              Telemetry.endSpan(span);
             }
           }
         },

package/Server/Utils/Telemetry/ErrorClassResolver.ts

@@ -0,0 +1,120 @@
+import ErrorClass, {
+  DeclaredErrorClass,
+  declaredErrorClass,
+  isNonActionableErrorClass,
+  toErrorClass,
+} from "../../../Types/Telemetry/ErrorClass";
+import {
+  UNIT_OF_WORK_ATTRIBUTE_KEY,
+  UnitOfWork,
+} from "../../../Types/Telemetry/UnitOfWork";
+import { TelemetryErrorClassEnabled } from "../../EnvironmentConfig";
+import TelemetryContext from "./TelemetryContext";
+
+/**
+ * Decides the fault domain of a thrown value: is this OUR bug, or a
+ * consequence of what someone asked us to do?
+ *
+ * Two rules, in order, and neither of them asks the catch site to make a
+ * judgment call.
+ *
+ * 1. UNDECLARED MEANS CODE-FAULT. A raw TypeError, a TypeORM QueryFailedError,
+ *    an axios error, a thrown string — nobody predicted it, so by definition
+ *    it is a bug. This is also what happens to an Exception subclass whose
+ *    author never overrode getErrorClass. The scheme's failure mode is
+ *    over-reporting, always.
+ *
+ * 1b. UNLESS THE SITE SAID SO ITSELF. A class declared for one specific throw
+ *    or one specific log line (Exception.asUserError(), or an `error.class`
+ *    attribute on a logger.error call) is authoritative and skips rule 2. Rule
+ *    2 exists to stop a class-level GENERALISATION being trusted in the wrong
+ *    context; it should not overrule a developer who looked at one site. This
+ *    is what lets a probe report "the endpoint we were asked to check is down"
+ *    as a non-defect even though a probe check has no request around it.
+ *
+ * 2. A USER-ERROR NEEDS A USER. user-error and expected-denial are honoured
+ *    only inside an HTTP request. In a worker job, a cron run, a probe check,
+ *    at startup, or outside any scope at all, there is no client whose request
+ *    could have been wrong — so the "bad input" was produced by our own code,
+ *    and that is a bug. They are promoted back to code-fault.
+ *
+ * code-fault and infrastructure are honoured everywhere: neither is ever
+ * suppressed, so promoting them would be meaningless.
+ *
+ * Known limitation, documented rather than papered over: a request handler
+ * that starts background work with `.catch()` after responding stays inside
+ * the http-request scope, so an invariant violation in that async tail is
+ * still labelled user-error. It still emits a `fault` span event, a WARN log
+ * and an `oneuptime.fault.count` increment, so it remains findable — see the
+ * standing review queries in the release notes.
+ */
+export default class ErrorClassResolver {
+  public static resolve(
+    error: unknown,
+    declaredOverride?: unknown,
+  ): ErrorClass {
+    if (!TelemetryErrorClassEnabled) {
+      /*
+       * Kill switch. Everything is a code-fault, which reproduces the
+       * pre-classification behaviour exactly: exception event, ERROR status,
+       * ERROR log.
+       */
+      return ErrorClass.CodeFault;
+    }
+
+    /*
+     * An explicit class handed in by the caller (e.g. the `error.class`
+     * attribute on a logger.error call) is a site-level declaration and wins
+     * outright — including over the unit-of-work promotion.
+     */
+    const override: ErrorClass | null = toErrorClass(declaredOverride);
+
+    if (override !== null) {
+      return override;
+    }
+
+    const declared: DeclaredErrorClass | null = declaredErrorClass(error);
+
+    if (declared === null) {
+      return ErrorClass.CodeFault;
+    }
+
+    if (
+      declared.authoritative ||
+      !isNonActionableErrorClass(declared.errorClass)
+    ) {
+      return declared.errorClass;
+    }
+
+    return this.isInsideHttpRequest()
+      ? declared.errorClass
+      : ErrorClass.CodeFault;
+  }
+
+  /**
+   * Whether the resolved class is one we deliberately keep out of the Issues
+   * list. Convenience so callers do not have to import both this and the
+   * predicate.
+   */
+  public static isNonActionable(
+    error: unknown,
+    declaredOverride?: unknown,
+  ): boolean {
+    return isNonActionableErrorClass(this.resolve(error, declaredOverride));
+  }
+
+  private static isInsideHttpRequest(): boolean {
+    try {
+      return (
+        TelemetryContext.getAttributes()[UNIT_OF_WORK_ATTRIBUTE_KEY] ===
+        UnitOfWork.HttpRequest
+      );
+    } catch {
+      /*
+       * No AsyncLocalStorage scope, or telemetry disabled. "Not a request" is
+       * the safe answer: it promotes toward code-fault.
+       */
+      return false;
+    }
+  }
+}

package/Server/Utils/Telemetry/SpanUtil.ts

@@ -1,6 +1,7 @@
 import { DisableTelemetry } from "../../EnvironmentConfig";
 import TelemetryContext from "./TelemetryContext";
 import OpenTelemetryAPI, { Span } from "@opentelemetry/api";
+import Telemetry from "../Telemetry";
 
 export interface SpanAttributes {
   userId?: string | undefined;
@@ -51,6 +52,38 @@ export default class SpanUtil {
     this.addAttributesToSpan({ span, attributes });
   }
 
+  /**
+   * Record a thrown value on the currently active span, without ending it.
+   *
+   * For code that CATCHES an error and signals failure by another route —
+   * Express middleware calling `next(err)` being the canonical case. The
+   * @CaptureSpan frame around such a method sees a normal return, so its own
+   * recorder never runs and the error would otherwise be invisible on that
+   * span.
+   *
+   * Always prefer this to calling `span.recordException(err)` directly: the
+   * OTel SDK types the event from `exception.code` before `exception.name`,
+   * and every OneUptime ExceptionCode is an HTTP status, so the raw call
+   * produces exception groups literally named "400" and "422". This path also
+   * applies fault classification, so a rejected API key produces a `fault`
+   * event rather than an Issue.
+   *
+   * Safe to call with no active span or with telemetry disabled.
+   */
+  public static recordExceptionOnCurrentSpan(exception: unknown): void {
+    if (DisableTelemetry) {
+      return;
+    }
+
+    const span: Span | undefined = OpenTelemetryAPI.trace.getActiveSpan();
+
+    if (!span) {
+      return;
+    }
+
+    Telemetry.recordExceptionOnSpan({ span, exception });
+  }
+
   /**
    * Add attributes to a specific span.
    */