@oneuptime/common 12.0.9 → 12.0.11

package/UI/Utils/NetworkAutomation/RunNetworkRule.ts

@@ -0,0 +1,122 @@
+import URL from "../../../Types/API/URL";
+import Dictionary from "../../../Types/Dictionary";
+import HTTPErrorResponse from "../../../Types/API/HTTPErrorResponse";
+import HTTPResponse from "../../../Types/API/HTTPResponse";
+import { JSONObject } from "../../../Types/JSON";
+import { RuleRunResultUtil } from "../../../Types/NetworkAutomation/RuleRunResult";
+import RuleRunSummary from "../../../Utils/NetworkAutomation/RuleRunSummary";
+import { APP_API_URL } from "../../Config";
+import API from "../API/API";
+
+/*
+ * Client for the two Network Automation "Run now" endpoints.
+ *
+ * Both rule kinds fire automatically only when a device is created (and, for
+ * site assignment, when its identity changes or on the next poll of a device
+ * with no site), so a rule written after an estate was imported never reaches
+ * it. These endpoints apply one rule to the devices that already exist —
+ * OneUptime/oneuptime#3191.
+ *
+ * The two differ only in the route they post to and in whether the run can
+ * overwrite something a person chose, so they share one client rather than
+ * two that drift.
+ */
+
+export enum NetworkRuleKind {
+  SiteAssignment = "SiteAssignment",
+  DeviceLabel = "DeviceLabel",
+}
+
+const RULE_RUN_ROUTE: Record<NetworkRuleKind, string> = {
+  [NetworkRuleKind.SiteAssignment]: "/network-site-assignment-rule",
+  [NetworkRuleKind.DeviceLabel]: "/network-device-label-rule",
+};
+
+/*
+ * What the caller shows. A failed run is not an exception here: the modal
+ * renders the same sentence either way, only in the error slot.
+ */
+export interface NetworkRuleRunOutcome {
+  isSuccess: boolean;
+  message: string;
+}
+
+export default class RunNetworkRule {
+  public static getRunRoute(data: {
+    ruleKind: NetworkRuleKind;
+    ruleId: string;
+  }): string {
+    return `${RULE_RUN_ROUTE[data.ruleKind]}/${data.ruleId}/run`;
+  }
+
+  public static async run(data: {
+    ruleKind: NetworkRuleKind;
+    ruleId: string;
+    /*
+     * Site assignment only, and only ever sent as a real boolean — the
+     * endpoint accepts nothing else, so a run cannot move devices somebody
+     * placed by hand through a stray truthy value.
+     */
+    reassignDevicesAlreadyInASite?: boolean | undefined;
+    headers?: Dictionary<string> | undefined;
+  }): Promise<NetworkRuleRunOutcome> {
+    /*
+     * Without this the request would go to `/…//run`, which matches no route
+     * and comes back as an unhelpful 404 rather than as the real problem.
+     */
+    if (!data.ruleId) {
+      return {
+        isSuccess: false,
+        message: "This rule has no id, so it cannot be run.",
+      };
+    }
+
+    const isSiteAssignment: boolean =
+      data.ruleKind === NetworkRuleKind.SiteAssignment;
+
+    try {
+      const response: HTTPResponse<JSONObject> | HTTPErrorResponse =
+        await API.post<JSONObject>({
+          url: URL.fromString(APP_API_URL.toString()).addRoute(
+            RunNetworkRule.getRunRoute({
+              ruleKind: data.ruleKind,
+              ruleId: data.ruleId,
+            }),
+          ),
+          data: isSiteAssignment
+            ? {
+                reassignDevicesAlreadyInASite: Boolean(
+                  data.reassignDevicesAlreadyInASite,
+                ),
+              }
+            : {},
+          ...(data.headers ? { headers: data.headers } : {}),
+        });
+
+      if (response.isFailure()) {
+        return {
+          isSuccess: false,
+          message: API.getFriendlyMessage(response),
+        };
+      }
+
+      const body: JSONObject = (response.data || {}) as JSONObject;
+
+      return {
+        isSuccess: true,
+        message: isSiteAssignment
+          ? RuleRunSummary.describeSiteAssignmentRun(
+              RuleRunResultUtil.parseSiteAssignmentRuleRunResult(body),
+            )
+          : RuleRunSummary.describeLabelRun(
+              RuleRunResultUtil.parseLabelRuleRunResult(body),
+            ),
+      };
+    } catch (err) {
+      return {
+        isSuccess: false,
+        message: API.getFriendlyMessage(err),
+      };
+    }
+  }
+}

package/Utils/API.ts

@@ -51,6 +51,28 @@ export interface RequestOutcome {
 export interface RequestOptions {
   retries?: number | undefined;
   exponentialBackoff?: boolean | undefined;
+  /*
+   * Ceiling on any single backoff sleep. Doubling is unbounded by
+   * definition, so without a cap a double-digit retry budget spends nearly
+   * all of its wall clock asleep — the tenth wait alone is over seventeen
+   * minutes. Defaults to DEFAULT_MAX_BACKOFF_IN_MS, which is far above what
+   * a handful of retries can reach, so short retry budgets are unaffected.
+   */
+  maxBackoffInMs?: number | undefined;
+  /*
+   * Spend retries only on failures that repeating could plausibly fix —
+   * see isRetryableError. Off by default: callers that have always retried
+   * every error keep doing so until they opt in.
+   */
+  retryOnlyOnRetryableErrors?: boolean | undefined;
+  /*
+   * Wall-clock budget for the whole call, every attempt and backoff
+   * included. No attempt is started that the budget cannot pay for, so N
+   * retries of a request that times out can no longer take N x timeout and
+   * outlive whatever is waiting on the answer. It does not abort an attempt
+   * already in flight — the per-attempt `timeout` is what bounds that.
+   */
+  totalTimeoutInMs?: number | undefined;
   timeout?: number | undefined;
   doNotFollowRedirects?: boolean | undefined;
   // Per-request proxy agent support (Probe supplies these instead of mutating global axios defaults)
@@ -97,6 +119,25 @@ export interface AuthRetryContext {
 }
 
 export default class API {
+  /*
+   * Backstop ceiling for a single backoff sleep when the caller names none.
+   * Set well above what a small retry budget can reach (three retries top out
+   * at eight seconds), so it only ever bites on the long budgets that need it.
+   */
+  public static readonly DEFAULT_MAX_BACKOFF_IN_MS: number = 60 * 1000;
+
+  /*
+   * 4xx responses are the server saying the request itself is wrong, and
+   * resending it byte-for-byte gets the same answer — except for these three,
+   * which say "not now" rather than "not ever".
+   */
+  private static readonly RETRYABLE_CLIENT_ERROR_STATUS_CODES: Set<number> =
+    new Set([
+      408, // Request Timeout
+      425, // Too Early
+      429, // Too Many Requests
+    ]);
+
   private _protocol: Protocol = Protocol.HTTPS;
   public get protocol(): Protocol {
     return this._protocol;
@@ -417,57 +458,88 @@ export default class API {
         finalBody = new URLSearchParams(data as Dictionary<string>);
       }
 
-      let currentRetry: number = 0;
-      const maxRetries: number = options?.retries || 0;
+      /*
+       * Negative budgets are clamped rather than trusted: `while (0 <= -1)`
+       * used to skip the request entirely and report the misleading "No
+       * response received from server" for a request never sent.
+       */
+      const maxRetries: number = Math.max(0, options?.retries || 0);
       const exponentialBackoff: boolean = options?.exponentialBackoff || false;
 
-      let result: AxiosResponse | null = null;
+      // Identical on every attempt, so build it once.
+      const axiosOptions: AxiosRequestConfig = {
+        method: method,
+        url: url.toString(),
+        headers: finalHeaders,
+        data: finalBody,
+      };
 
-      while (currentRetry <= maxRetries) {
-        currentRetry++;
-        attempts++;
-        try {
-          const axiosOptions: AxiosRequestConfig = {
-            method: method,
-            url: url.toString(),
-            headers: finalHeaders,
-            data: finalBody,
-          };
+      if (options?.timeout) {
+        axiosOptions.timeout = options.timeout;
+      }
 
-          if (options?.timeout) {
-            axiosOptions.timeout = options.timeout;
-          }
+      if (options?.doNotFollowRedirects) {
+        axiosOptions.maxRedirects = 0;
+      }
 
-          if (options?.doNotFollowRedirects) {
-            axiosOptions.maxRedirects = 0;
-          }
+      // Attach proxy agents per request if provided (avoids global side-effects)
+      if (options?.httpAgent) {
+        axiosOptions.httpAgent = options.httpAgent;
+      }
+      if (options?.httpsAgent) {
+        axiosOptions.httpsAgent = options.httpsAgent;
+      }
 
-          // Attach proxy agents per request if provided (avoids global side-effects)
-          if (options?.httpAgent) {
-            (axiosOptions as AxiosRequestConfig).httpAgent = options.httpAgent;
-          }
-          if (options?.httpsAgent) {
-            (axiosOptions as AxiosRequestConfig).httpsAgent =
-              options.httpsAgent;
-          }
+      if (options?.onUploadProgress) {
+        axiosOptions.onUploadProgress = options.onUploadProgress;
+      }
 
-          if (options?.onUploadProgress) {
-            axiosOptions.onUploadProgress = options.onUploadProgress;
-          }
+      let result: AxiosResponse | null = null;
 
+      for (let attempt: number = 0; attempt <= maxRetries; attempt++) {
+        attempts++;
+
+        try {
           result = await axios(axiosOptions);
 
           break;
         } catch (e) {
-          if (currentRetry <= maxRetries) {
-            if (exponentialBackoff) {
-              await Sleep.sleep(2 ** currentRetry * 1000);
-            }
+          if (attempt >= maxRetries) {
+            throw e;
+          }
+
+          /*
+           * A rejected request stays rejected. Failing now surfaces the
+           * provider's own explanation immediately instead of after a full
+           * ladder of backoffs that cannot change the answer.
+           */
+          if (options?.retryOnlyOnRetryableErrors && !API.isRetryableError(e)) {
+            throw e;
+          }
 
-            continue;
-          } else {
+          const delayInMs: number = API.getRetryDelayInMs({
+            attempt: attempt,
+            error: e,
+            exponentialBackoff: exponentialBackoff,
+            maxBackoffInMs: options?.maxBackoffInMs,
+          });
+
+          /*
+           * Check the budget against the point the next attempt would START,
+           * not the point we are at now: sleeping out the remainder and then
+           * giving up would waste the wait for nothing.
+           */
+          if (
+            options?.totalTimeoutInMs !== undefined &&
+            Date.now() - requestStartedAtInMs + delayInMs >=
+              options.totalTimeoutInMs
+          ) {
             throw e;
           }
+
+          if (delayInMs > 0) {
+            await Sleep.sleep(delayInMs);
+          }
         }
       }
 
@@ -620,6 +692,141 @@ export default class API {
     }
   }
 
+  /**
+   * Is repeating this request worth an attempt?
+   *
+   * Retries exist for failures the network or the server may not repeat: a
+   * dropped connection, a timeout, an overloaded backend, a rate limit that
+   * lapses. Everything else — a malformed body, a bad key, an unknown route —
+   * fails identically every time, and retrying it only delays the error the
+   * operator needs to read.
+   */
+  public static isRetryableError(error: unknown): boolean {
+    if (!axios.isAxiosError(error)) {
+      /*
+       * Not a transport failure at all: the request could not even be built,
+       * or an interceptor threw. Nothing about resending changes that.
+       */
+      return false;
+    }
+
+    const axiosError: AxiosError = error;
+
+    // The caller pulled the plug on purpose.
+    if (axiosError.code === "ERR_CANCELED") {
+      return false;
+    }
+
+    const statusCode: number | undefined = axiosError.response?.status;
+
+    /*
+     * No response at all — timeout, DNS failure, refused or reset connection.
+     * These are exactly what a retry is for.
+     */
+    if (statusCode === undefined) {
+      return true;
+    }
+
+    // The server broke, not the request.
+    if (statusCode >= 500) {
+      return true;
+    }
+
+    return API.RETRYABLE_CLIENT_ERROR_STATUS_CODES.has(statusCode);
+  }
+
+  /**
+   * How long to wait before the attempt that follows `attempt` (0-based).
+   */
+  private static getRetryDelayInMs(data: {
+    attempt: number;
+    error: unknown;
+    exponentialBackoff: boolean;
+    maxBackoffInMs?: number | undefined;
+  }): number {
+    const ceilingInMs: number =
+      data.maxBackoffInMs ?? API.DEFAULT_MAX_BACKOFF_IN_MS;
+
+    /*
+     * A server that says when to come back knows better than any formula we
+     * could pick — coming back early just spends another attempt on the same
+     * 429. Still capped: the caller's budget is what bounds the total wait,
+     * and an unbounded Retry-After would hand that control to the server.
+     */
+    const retryAfterInMs: number | undefined = API.getRetryAfterInMs(
+      data.error,
+    );
+
+    if (retryAfterInMs !== undefined) {
+      return Math.min(retryAfterInMs, ceilingInMs);
+    }
+
+    if (!data.exponentialBackoff) {
+      return 0;
+    }
+
+    const backoffInMs: number = Math.min(
+      2 ** (data.attempt + 1) * 1000,
+      ceilingInMs,
+    );
+
+    /*
+     * Equal jitter. Everything that failed together — every chat turn behind
+     * one provider outage, every probe behind one flapping host — otherwise
+     * comes back at the very same millisecond and knocks the recovering
+     * server straight back over. Half the delay stays fixed so a retry is
+     * never effectively immediate, and half is spread at random.
+     */
+    return Math.round(backoffInMs / 2 + Math.random() * (backoffInMs / 2));
+  }
+
+  /**
+   * Read a Retry-After header off a failed response. Returns undefined unless
+   * the header is present and names a sane, non-negative wait.
+   */
+  private static getRetryAfterInMs(error: unknown): number | undefined {
+    if (!axios.isAxiosError(error)) {
+      return undefined;
+    }
+
+    const headers: unknown = error.response?.headers;
+
+    if (!headers || typeof headers !== "object") {
+      return undefined;
+    }
+
+    const rawHeader: unknown =
+      (headers as Dictionary<unknown>)["retry-after"] ??
+      (headers as Dictionary<unknown>)["Retry-After"];
+
+    if (rawHeader === undefined || rawHeader === null) {
+      return undefined;
+    }
+
+    const headerValue: string = String(rawHeader).trim();
+
+    if (!headerValue) {
+      return undefined;
+    }
+
+    // Form 1: delta-seconds.
+    const deltaSecondsRegex: RegExp = /^\d+$/;
+
+    if (deltaSecondsRegex.test(headerValue)) {
+      return Number(headerValue) * 1000;
+    }
+
+    // Form 2: an HTTP-date to wait until.
+    const retryAtInMs: number = Date.parse(headerValue);
+
+    if (Number.isNaN(retryAtInMs)) {
+      return undefined;
+    }
+
+    // A date already in the past means "retry now", not "retry in the past".
+    return Math.max(0, retryAtInMs - Date.now());
+  }
+
   private static getErrorResponse(error: AxiosError): HTTPErrorResponse {
     if (error.response) {
       return new HTTPErrorResponse(

package/Utils/Monitor/NetworkDeviceRoleUtil.ts

@@ -531,3 +531,48 @@ export function labelForDeviceRole(
   }
   return DEVICE_ROLE_LABELS[role] || DEVICE_ROLE_LABELS.unknown;
 }
+
+/**
+ * Read an operator's stored role override off a NetworkDevice row.
+ *
+ * The classifier above is evidence-driven, and its evidence is SNMP: a
+ * device nothing walks — a ping-only device imported by discovery, say —
+ * offers it a hostname and nothing else, so it comes back "unknown" and
+ * stays there forever. `NetworkDevice.deviceRole` is the operator saying
+ * what the box actually is, and it is the only statement about a role that
+ * is not an inference, so it outranks everything the classifier can find.
+ *
+ * Undefined means "no override" — NOT "unknown". The two are different
+ * answers and the difference decides whether the classifier gets to run at
+ * all, which is why an unrecognised or empty column reads as undefined
+ * rather than falling back to a role. "unknown" is itself refused as an
+ * override for the same reason: storing it would silently disable the
+ * classifier on a device the operator was only declining to classify.
+ */
+export function parseDeviceRoleOverride(
+  value: string | undefined | null,
+): NetworkTopologyDeviceRole | undefined {
+  const normalized: string = (value || "").trim().toLowerCase();
+  if (!normalized) {
+    return undefined;
+  }
+  return DEVICE_ROLES_IN_LEGEND_ORDER.find(
+    (role: NetworkTopologyDeviceRole) => {
+      return role.toLowerCase() === normalized;
+    },
+  );
+}
+
+/**
+ * The role to draw a managed device with: the operator's override when
+ * there is one, otherwise whatever the evidence supports.
+ *
+ * One function so the topology builder, the forms and the tests cannot
+ * drift about which of the two wins.
+ */
+export function resolveDeviceRole(
+  roleOverride: string | undefined | null,
+  signals: DeviceRoleSignals,
+): NetworkTopologyDeviceRole {
+  return parseDeviceRoleOverride(roleOverride) ?? classifyDeviceRole(signals);
+}

package/Utils/Monitor/NetworkTopologyUtil.ts

@@ -11,6 +11,7 @@ import { normalizeMac } from "./EndpointAttachmentUtil";
 import {
   classifyDeviceRole,
   classifyEndpointRole,
+  resolveDeviceRole,
 } from "./NetworkDeviceRoleUtil";
 
 export interface TopologyDeviceInput {
@@ -29,6 +30,14 @@ export interface TopologyDeviceInput {
    */
   sysDescr?: string | undefined;
   sysObjectId?: string | undefined;
+  /*
+   * The operator's own answer to what this device is, when they gave one.
+   * Outranks the classifier below, because it is the only statement about
+   * the role that is not an inference — and on a device nothing walks it
+   * is the ONLY statement available at all, the classifier having nothing
+   * but a hostname to go on.
+   */
+  deviceRole?: string | undefined;
   /*
    * ENTITY-MIB chassis serial. Not rendered — it is here because LLDP
    * chassis-id subtype 7 ("locally assigned") is very often exactly this
@@ -109,6 +118,13 @@ export interface TopologyManualLinkInput {
   toPortName?: string | undefined;
   // Health from a bound Monitor, already reduced by the caller.
   monitorStatus?: "up" | "down" | undefined;
+  /*
+   * Whichever end the operator declared the parent, when they declared
+   * one. Must be `fromDeviceId` or `toDeviceId`; anything else is dropped
+   * rather than drawn, because a parent that is not on the link cannot be
+   * rendered as one and a wrong hierarchy is worse than an inferred one.
+   */
+  parentDeviceId?: string | undefined;
 }
 
 /*
@@ -232,7 +248,10 @@ export default class NetworkTopologyUtil {
    * alias are one unmanaged node, however many switches saw it. Edges are
    * undirected and deduplicated — a link reported from both ends, or by
    * both protocols, appears once with the union of what each report knew
-   * (ports, protocols, per-end interface state). When `interfaces` rows are
+   * (ports, protocols, per-end interface state). Undirected in the sense
+   * that neither end is privileged by how the edge was discovered: an edge
+   * carries a direction only where an operator declared one, as
+   * `parentNodeId`. When `interfaces` rows are
    * provided, each edge end whose interface is identifiable carries its
    * operational state (up/down, utilization, rates). When `endpoints` rows
    * are provided, each one that attaches to a device in the graph becomes an
@@ -306,7 +325,7 @@ export default class NetworkTopologyUtil {
         name: device.name,
         isManaged: true,
         kind: "device",
-        role: classifyDeviceRole({
+        role: resolveDeviceRole(device.deviceRole, {
           sysDescr: device.sysDescr,
           sysObjectId: device.sysObjectId,
           vendor: device.vendor,
@@ -520,6 +539,18 @@ export default class NetworkTopologyUtil {
         continue;
       }
 
+      /*
+       * A declared parent is only meaningful if it is one of the two ends.
+       * The service refuses anything else at write time, so this is a
+       * second line rather than the only one — it also covers rule-derived
+       * links, which never pass through that service.
+       */
+      const declaredParentId: string | undefined =
+        link.parentDeviceId === link.fromDeviceId ||
+        link.parentDeviceId === link.toDeviceId
+          ? link.parentDeviceId
+          : undefined;
+
       const edgeKey: string = [link.fromDeviceId, link.toDeviceId]
         .sort()
         .join("::");
@@ -534,6 +565,7 @@ export default class NetworkTopologyUtil {
           protocols: ["manual"],
           monitorState: link.monitorStatus,
           name: link.name,
+          parentNodeId: declaredParentId,
         });
         continue;
       }
@@ -557,6 +589,14 @@ export default class NetworkTopologyUtil {
       }
       existing.name = existing.name || link.name;
       existing.monitorState = existing.monitorState ?? link.monitorStatus;
+      /*
+       * First declaration wins, matching the ordering the caller already
+       * relies on: explicit links are merged before rule-derived ones, so
+       * a hierarchy somebody set on the link itself beats a rule that
+       * happens to cover the same pair. The specific statement beats the
+       * general one — the same precedence the ports and the name use.
+       */
+      existing.parentNodeId = existing.parentNodeId || declaredParentId;
     }
 
     const edges: Array<NetworkTopologyEdge> = Array.from(edgeByKey.values());