@oneuptime/common 12.0.34 → 13.0.0

package/Tests/Server/Utils/Monitor/NetworkInventoryUtil.test.ts

@@ -20,6 +20,8 @@ import SnmpVendorTemplateUtil, {
 import NetworkDeviceMonitoringMethod from "../../../../Types/NetworkDevice/NetworkDeviceMonitoringMethod";
 import { NetworkDevicePollMode } from "../../../../Server/Utils/Monitor/NetworkDeviceHydrationUtil";
 import logger from "../../../../Server/Utils/Logger";
+import { JSONObject } from "../../../../Types/JSON";
+import { FindOperator } from "typeorm";
 
 /*
  * NetworkInventoryUtil.updateFromWalk is the single writer that keeps the
@@ -47,6 +49,8 @@ let deviceUpdateSpy: jest.SpyInstance;
 let interfaceFindSpy: jest.SpyInstance;
 let interfaceUpsertSpy: jest.SpyInstance;
 let endpointUpsertSpy: jest.SpyInstance;
+let deviceLookupSpy: jest.SpyInstance;
+let macWriteSpy: jest.SpyInstance;
 
 function mockServices(
   existingInterfaces: Array<NetworkInterface> = [],
@@ -119,6 +123,19 @@ function mockServices(
   endpointUpsertSpy = jest
     .spyOn(NetworkEndpointService, "upsertDiscoveredEndpoints")
     .mockResolvedValue(undefined as never);
+  /*
+   * Device MAC learning follows the endpoint upsert on any walk that
+   * carried ARP bindings: one findBy for the devices registered at the
+   * bound addresses, then a hook-free compare-and-set write per device the
+   * planner picked. Stubbed here so the ARP cases never reach a database;
+   * the learning block seeds findBy with real rows where it matters.
+   */
+  deviceLookupSpy = jest
+    .spyOn(NetworkDeviceService, "findBy")
+    .mockResolvedValue([]);
+  macWriteSpy = jest
+    .spyOn(NetworkDeviceService, "updateColumnsByIdWithoutHooks")
+    .mockResolvedValue(undefined);
 }
 
 function deviceUpdatePayload(): DeviceUpdatePayload {
@@ -1101,6 +1118,306 @@ describe("NetworkInventoryUtil.updateFromWalk — endpoint discovery", () => {
   });
 });
 
+/*
+ * A walked router's ARP table binds the address a managed device is
+ * registered at to the MAC the switches learned - the one fact a ping-only
+ * register or handset never reports about itself. After the endpoint
+ * inventory is written, the walk hands those bindings to
+ * NetworkDeviceMacLearningUtil, which stamps the MAC on the device row while
+ * its column is still empty. The planner's rules are pinned in
+ * Tests/Utils/Monitor/DeviceMacLearningUtil.test.ts and the database contract
+ * in Tests/Server/Utils/Monitor/NetworkDeviceMacLearningUtil.test.ts; what is
+ * pinned HERE is the hand-off from the walk: when learning runs, what it is
+ * scoped by, and that a failure in it stays in it.
+ */
+describe("NetworkInventoryUtil.updateFromWalk — device MAC learning", () => {
+  const SITE_ID: ObjectID = new ObjectID(
+    "5a5a5a5a-0000-4000-8000-00000000000a",
+  );
+  const OTHER_SITE_ID: ObjectID = new ObjectID(
+    "5b5b5b5b-0000-4000-8000-00000000000b",
+  );
+  const REGISTER_ID: string = "8f2c1f0e-0000-4000-8000-0000000000bb";
+  const HANDSET_ID: string = "8f2c1f0e-0000-4000-8000-0000000000cc";
+  const REGISTER_IP: string = "10.0.0.5";
+  const REGISTER_MAC: string = "aa:bb:cc:00:11:22";
+
+  // A managed, ping-only device registered at the address the router bound.
+  function registeredDevice(
+    id: string,
+    overrides?: { siteId?: ObjectID; macAddress?: string },
+  ): NetworkDevice {
+    const row: NetworkDevice = new NetworkDevice();
+    row.id = new ObjectID(id);
+    row.hostname = REGISTER_IP;
+    if (overrides?.siteId) {
+      row.siteId = overrides.siteId;
+    }
+    if (overrides?.macAddress !== undefined) {
+      row.macAddress = overrides.macAddress;
+    }
+    return row;
+  }
+
+  // The ARP table spelling differs from the column's: learning normalizes.
+  function arpWalk(): Partial<SnmpMonitorResponse> {
+    return {
+      arpEntries: [
+        {
+          ipAddress: REGISTER_IP,
+          macAddress: "AA-BB-CC-00-11-22",
+          interfaceIndex: 3,
+          entryType: "dynamic",
+        },
+      ],
+    };
+  }
+
+  /*
+   * The addresses the device lookup asked about. QueryHelper.any renders
+   * them into a TypeORM Raw operator with a RANDOM parameter name, so the
+   * list is recovered from the operator's parameters.
+   */
+  function addressesLookedUp(): Array<string> {
+    const query: JSONObject = (deviceLookupSpy.mock.calls[0]![0] as JSONObject)[
+      "query"
+    ] as JSONObject;
+    const operator: FindOperator<string> = query[
+      "hostname"
+    ] as unknown as FindOperator<string>;
+    const parameters: Record<string, unknown> =
+      (operator.objectLiteralParameters || {}) as Record<string, unknown>;
+    const values: Array<unknown> =
+      (Object.values(parameters)[0] as Array<unknown>) || [];
+    return values.map((value: unknown): string => {
+      return String(value);
+    });
+  }
+
+  function spyError(): jest.SpyInstance {
+    return jest.spyOn(logger, "error").mockImplementation(() => {
+      return undefined;
+    });
+  }
+
+  test("a walk carrying an ARP entry looks up the devices at the bound address, in the walked device's project", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+
+    const query: JSONObject = (deviceLookupSpy.mock.calls[0]![0] as JSONObject)[
+      "query"
+    ] as JSONObject;
+
+    expect((query["projectId"] as ObjectID).toString()).toBe(PROJECT_ID);
+    expect(addressesLookedUp()).toEqual([REGISTER_IP]);
+  });
+
+  test("a device with an empty MAC in the router's site is stamped through the hook-free compare-and-set write", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    expect(macWriteSpy).toHaveBeenCalledTimes(1);
+
+    const write: JSONObject = macWriteSpy.mock.calls[0]![0] as JSONObject;
+
+    expect((write["id"] as ObjectID).toString()).toBe(REGISTER_ID);
+    expect(write["data"]).toEqual({
+      macAddress: REGISTER_MAC,
+      isMacAddressLearned: true,
+    });
+    expect(write["expectedData"]).toEqual({
+      macAddress: null,
+      deletedAt: null,
+    });
+    // The walked router's own row is untouched by learning.
+    expect(deviceUpdateSpy).toHaveBeenCalledTimes(1);
+    expect(deviceUpdatePayload()).not.toHaveProperty("macAddress");
+  });
+
+  test("learning runs after the endpoint inventory has been written", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk(arpWalk());
+
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+    expect(endpointUpsertSpy.mock.invocationCallOrder[0]!).toBeLessThan(
+      deviceLookupSpy.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  test("a walk with FDB entries only never looks devices up", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk({
+      interfaces: [walkedInterface({ interfaceIndex: 5, name: "Gi0/5" })],
+      fdbEntries: [
+        {
+          macAddress: REGISTER_MAC,
+          bridgePort: 5,
+          interfaceIndex: 5,
+          status: "learned",
+        },
+      ],
+    });
+
+    // The attachment was still written; only the ARP half was absent.
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(deviceLookupSpy).not.toHaveBeenCalled();
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("a walk without endpoint arrays at all never looks devices up", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk({ interfaces: [walkedInterface()] });
+
+    expect(deviceLookupSpy).not.toHaveBeenCalled();
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  /*
+   * Learning keys off the bindings the attachment pass KEPT, not the raw
+   * ARP rows: an entry for the router's own interface MAC is dropped there
+   * and must not come back as a lookup here.
+   */
+  test("an ARP entry the attachment pass discards never reaches learning", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk({
+      interfaces: [
+        walkedInterface({ interfaceIndex: 3, macAddress: REGISTER_MAC }),
+      ],
+      ...arpWalk(),
+    });
+
+    expect(endpointUpsertSpy).not.toHaveBeenCalled();
+    expect(deviceLookupSpy).not.toHaveBeenCalled();
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("a failure in the learning step is logged and does not prevent the walk from completing", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockRejectedValue(new Error("connection reset"));
+    const error: jest.SpyInstance = spyError();
+
+    const snmpResponse: SnmpMonitorResponse = await runWalk(arpWalk());
+
+    // Nothing escaped, and everything before the learning step landed.
+    expect(snmpResponse).toBeDefined();
+    expect(deviceUpdateSpy).toHaveBeenCalledTimes(1);
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(macWriteSpy).not.toHaveBeenCalled();
+
+    const messages: Array<string> = error.mock.calls.map(
+      (call: Array<unknown>) => {
+        return String(call[0]);
+      },
+    );
+
+    /*
+     * Its OWN catch, naming the device - never the outer "failed to update
+     * network inventory" line, which would read as the endpoint upsert
+     * having failed too.
+     */
+    expect(
+      messages.some((message: string) => {
+        return message.includes("MAC") && message.includes(DEVICE_ID);
+      }),
+    ).toBe(true);
+    expect(
+      messages.some((message: string) => {
+        return message.includes("Failed to update network inventory");
+      }),
+    ).toBe(false);
+  });
+
+  test("a failing MAC write is contained the same way", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+    macWriteSpy.mockRejectedValue(new Error("deadlock detected"));
+    const error: jest.SpyInstance = spyError();
+
+    await expect(runWalk(arpWalk())).resolves.toBeDefined();
+
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(error).toHaveBeenCalled();
+  });
+
+  test("the observing device's site scopes the match: a device in another site is not stamped", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: OTHER_SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    // Looked up - the read is project-wide by design - but refused.
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("an observing device with no site stamps only a device with no site", async () => {
+    // The default device carries no siteId: a project without sites.
+    mockServices();
+    const siteless: NetworkDevice = registeredDevice(HANDSET_ID);
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+    expect(macWriteSpy).not.toHaveBeenCalled();
+
+    deviceLookupSpy.mockResolvedValue([siteless]);
+
+    await runWalk(arpWalk());
+    expect(macWriteSpy).toHaveBeenCalledTimes(1);
+    expect(
+      (
+        (macWriteSpy.mock.calls[0]![0] as JSONObject)["id"] as ObjectID
+      ).toString(),
+    ).toBe(HANDSET_ID);
+  });
+
+  test("a device that already carries a MAC is left alone", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, {
+        siteId: SITE_ID,
+        macAddress: "00:11:22:33:44:55",
+      }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("selects siteId on the device read, or learning could never scope by site", async () => {
+    mockServices();
+
+    await runWalk();
+
+    const findArgs: { select?: Record<string, boolean> } = deviceFindSpy.mock
+      .calls[0]![0] as unknown as { select?: Record<string, boolean> };
+
+    expect(findArgs.select?.["siteId"]).toBe(true);
+  });
+});
+
 describe("NetworkInventoryUtil.updateFromWalk — vendor health template auto-apply", () => {
   /*
    * The automatic counterpart of the dashboard's vendor-template banner:

package/Tests/Server/Utils/Telemetry/ContextSpanProcessor.test.ts

@@ -0,0 +1,281 @@
+import { afterEach, describe, expect, jest, test } from "@jest/globals";
+import type { Context } from "@opentelemetry/api";
+import type { ReadableSpan, Span } from "@opentelemetry/sdk-trace-base";
+import ContextSpanProcessor from "../../../../Server/Utils/Telemetry/ContextSpanProcessor";
+import TelemetryContext from "../../../../Server/Utils/Telemetry/TelemetryContext";
+
+/*
+ * This processor runs on the creation of EVERY span in every OneUptime
+ * process. That is what makes it useful - it is how projectId and userId
+ * reach the ~1958 attribute-less @CaptureSpan spans without touching any of
+ * those call sites - and it is also what makes it dangerous.
+ *
+ * Two properties follow.
+ *
+ *   IT MUST NEVER THROW. onStart sits inside the OpenTelemetry SDK's tracer,
+ *   on the hot path of every traced operation in the product. An exception
+ *   escaping it does not lose a span, it fails the OPERATION the span was
+ *   describing - telemetry taking down the thing it was watching. The
+ *   swallow-everything catch is the point of the file, so the tests drive it
+ *   with a context that throws and a span that throws.
+ *
+ *   IT MUST NOT WRITE undefined. A context attribute that is absent has to
+ *   stay absent rather than being stamped as a literal `undefined`, which is
+ *   both a wasted attribute slot on every span and a value that reads, on a
+ *   dashboard, as though the identifier were known to be empty.
+ */
+
+interface RecordedAttribute {
+  key: string;
+  value: unknown;
+}
+
+interface FakeSpan {
+  attributes: Array<RecordedAttribute>;
+}
+
+type BuildSpanFunction = (options?: { throwOnSet?: boolean }) => {
+  span: Span;
+  recorded: Array<RecordedAttribute>;
+};
+
+const buildSpan: BuildSpanFunction = (options?: {
+  throwOnSet?: boolean;
+}): { span: Span; recorded: Array<RecordedAttribute> } => {
+  const recorded: Array<RecordedAttribute> = [];
+
+  const span: FakeSpan & {
+    setAttribute: (key: string, value: unknown) => void;
+  } = {
+    attributes: recorded,
+    setAttribute: (key: string, value: unknown): void => {
+      if (options?.throwOnSet) {
+        throw new Error("span is already ended");
+      }
+      recorded.push({ key: key, value: value });
+    },
+  };
+
+  return { span: span as unknown as Span, recorded: recorded };
+};
+
+const EMPTY_CONTEXT: Context = {} as Context;
+
+type StartInContextFunction = (
+  attributes: Record<string, string | number | boolean>,
+  options?: { throwOnSet?: boolean },
+) => Array<RecordedAttribute>;
+
+const startInContext: StartInContextFunction = (
+  attributes: Record<string, string | number | boolean>,
+  options?: { throwOnSet?: boolean },
+): Array<RecordedAttribute> => {
+  const built: { span: Span; recorded: Array<RecordedAttribute> } =
+    buildSpan(options);
+
+  TelemetryContext.runWithContext(attributes, (): void => {
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+  });
+
+  return built.recorded;
+};
+
+describe("the ambient context is stamped onto every span", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test("copies the tenant identifiers of the enclosing scope", () => {
+    const recorded: Array<RecordedAttribute> = startInContext({
+      projectId: "project-1",
+      userId: "user-1",
+    });
+
+    expect(recorded).toEqual(
+      expect.arrayContaining([
+        { key: "projectId", value: "project-1" },
+        { key: "userId", value: "user-1" },
+      ]),
+    );
+  });
+
+  test("copies numbers and booleans without coercing them to strings", () => {
+    const recorded: Array<RecordedAttribute> = startInContext({
+      retryCount: 3,
+      isRetry: true,
+    });
+
+    expect(recorded).toEqual(
+      expect.arrayContaining([
+        { key: "retryCount", value: 3 },
+        { key: "isRetry", value: true },
+      ]),
+    );
+  });
+
+  /*
+   * Zero and false are real values. A truthiness check instead of an
+   * undefined check would silently drop exactly the attributes an operator
+   * most wants to filter on - "the runs where retryCount is 0".
+   */
+  test("copies zero and false, which a truthiness check would have dropped", () => {
+    const recorded: Array<RecordedAttribute> = startInContext({
+      retryCount: 0,
+      isRetry: false,
+      emptyLabel: "",
+    });
+
+    expect(recorded).toEqual(
+      expect.arrayContaining([
+        { key: "retryCount", value: 0 },
+        { key: "isRetry", value: false },
+        { key: "emptyLabel", value: "" },
+      ]),
+    );
+  });
+
+  test("writes nothing at all when there is no ambient scope", () => {
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+
+    expect(built.recorded).toEqual([]);
+  });
+
+  test("writes nothing when the scope is empty", () => {
+    expect(startInContext({})).toEqual([]);
+  });
+
+  /*
+   * An absent identifier must stay absent. Stamping a literal `undefined`
+   * wastes an attribute slot on every span and, on a dashboard, reads as
+   * though the identifier were known to be empty.
+   */
+  test("never stamps an undefined value", () => {
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    jest.spyOn(TelemetryContext, "getAttributes").mockReturnValue({
+      projectId: "project-1",
+      monitorId: undefined,
+      incidentId: null,
+    } as unknown as Record<string, string | number | boolean>);
+
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+
+    expect(
+      built.recorded.map((attribute: RecordedAttribute) => {
+        return attribute.key;
+      }),
+    ).toEqual(["projectId"]);
+  });
+
+  test("a nested scope stamps the identifiers of both levels", () => {
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    TelemetryContext.runWithContext({ projectId: "project-1" }, (): void => {
+      TelemetryContext.runWithContext({ monitorId: "monitor-1" }, (): void => {
+        new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+      });
+    });
+
+    expect(built.recorded).toEqual(
+      expect.arrayContaining([
+        { key: "projectId", value: "project-1" },
+        { key: "monitorId", value: "monitor-1" },
+      ]),
+    );
+  });
+
+  test("the scope does not leak out of the run it was seeded for", () => {
+    TelemetryContext.runWithContext({ projectId: "project-1" }, (): void => {
+      // seeded and immediately left
+    });
+
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+
+    expect(built.recorded).toEqual([]);
+  });
+});
+
+describe("telemetry never takes down the operation it is watching", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  /*
+   * onStart runs inside the SDK's tracer, on the hot path of every traced
+   * operation. An exception escaping it does not lose a span - it fails the
+   * work the span was describing.
+   */
+  test("swallows a span that refuses attributes", () => {
+    expect(() => {
+      return startInContext({ projectId: "project-1" }, { throwOnSet: true });
+    }).not.toThrow();
+  });
+
+  test("swallows a context that throws while being read", () => {
+    jest.spyOn(TelemetryContext, "getAttributes").mockImplementation(() => {
+      throw new Error("async local storage is unhappy");
+    });
+
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    expect(() => {
+      return new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+    }).not.toThrow();
+  });
+
+  test("swallows a context that is not an object at all", () => {
+    jest
+      .spyOn(TelemetryContext, "getAttributes")
+      .mockReturnValue(null as unknown as Record<string, string>);
+
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    expect(() => {
+      return new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+    }).not.toThrow();
+  });
+});
+
+describe("the rest of the SpanProcessor contract", () => {
+  /*
+   * Enrichment happens entirely at creation, so onEnd is deliberately inert.
+   * Doing anything to an ended span here would be both useless and a way to
+   * throw on the export path.
+   */
+  test("onEnd does nothing and does not throw", () => {
+    expect(() => {
+      return new ContextSpanProcessor().onEnd({} as ReadableSpan);
+    }).not.toThrow();
+  });
+
+  test("shutdown resolves, so the SDK's teardown is never blocked", async () => {
+    await expect(
+      new ContextSpanProcessor().shutdown(),
+    ).resolves.toBeUndefined();
+  });
+
+  test("forceFlush resolves, so a flush before exit never hangs", async () => {
+    await expect(
+      new ContextSpanProcessor().forceFlush(),
+    ).resolves.toBeUndefined();
+  });
+
+  test("shutdown and forceFlush stay resolvable after an enrichment failure", async () => {
+    const processor: ContextSpanProcessor = new ContextSpanProcessor();
+
+    processor.onStart(buildSpan({ throwOnSet: true }).span, EMPTY_CONTEXT);
+
+    await expect(processor.forceFlush()).resolves.toBeUndefined();
+    await expect(processor.shutdown()).resolves.toBeUndefined();
+  });
+});