@oneuptime/common 11.6.1 → 11.7.0

package/UI/Components/ModelTable/FilterDataToQuery.ts

@@ -0,0 +1,172 @@
+import Filter from "../ModelFilter/Filter";
+import FilterData from "../Filters/Types/FilterData";
+import FieldType from "../Types/FieldType";
+import AnalyticsBaseModel from "../../../Models/AnalyticsModels/AnalyticsBaseModel/AnalyticsBaseModel";
+import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
+import Includes from "../../../Types/BaseDatabase/Includes";
+import InBetween from "../../../Types/BaseDatabase/InBetween";
+import Query from "../../../Types/BaseDatabase/Query";
+import QueryOperator from "../../../Types/BaseDatabase/QueryOperator";
+import Search from "../../../Types/BaseDatabase/Search";
+import Typeof from "../../../Types/Typeof";
+
+/**
+ * Translate the filter popup's selections into the database query the table
+ * fetches with.
+ *
+ * Lives outside `BaseModelTable` on purpose: the table needs to derive the
+ * query *synchronously during its first render* when filters are restored from
+ * the URL (otherwise the first fetch would go out unfiltered and be
+ * immediately superseded), and a pure function is the only way to do that
+ * without an effect.
+ */
+export type GetFilterKeysFunction = <
+  TBaseModel extends BaseModel | AnalyticsBaseModel,
+>(
+  filters: Array<Filter<TBaseModel>>,
+) => Array<string>;
+
+/**
+ * The model fields this table actually exposes a filter for.
+ */
+export const getFilterKeys: GetFilterKeysFunction = <
+  TBaseModel extends BaseModel | AnalyticsBaseModel,
+>(
+  filters: Array<Filter<TBaseModel>>,
+): Array<string> => {
+  const keys: Array<string> = [];
+
+  for (const filter of filters || []) {
+    const key: string | undefined = filter.field
+      ? Object.keys(filter.field)[0]
+      : undefined;
+
+    if (key) {
+      keys.push(key);
+    }
+  }
+
+  return keys;
+};
+
+export type SanitizeFilterDataFunction = <
+  TBaseModel extends BaseModel | AnalyticsBaseModel,
+>(data: {
+  filterData: FilterData<TBaseModel>;
+  filters: Array<Filter<TBaseModel>>;
+}) => FilterData<TBaseModel>;
+
+/**
+ * Drop any key that this table does not expose as a filter.
+ *
+ * The filter snapshot arrives from the URL, which anyone can edit, and the
+ * result is spread into the outgoing list query *after* the caller's own
+ * scoping query. Without this, a hand-crafted link could add a constraint on a
+ * field the table never offered — or overwrite the page's own scoping (say the
+ * `projectId` on a nested list) — just by naming it in the query string.
+ *
+ * Restricting to declared filter keys keeps a shared link to exactly what the
+ * filter UI could have produced.
+ */
+const sanitizeFilterData: SanitizeFilterDataFunction = <
+  TBaseModel extends BaseModel | AnalyticsBaseModel,
+>(data: {
+  filterData: FilterData<TBaseModel>;
+  filters: Array<Filter<TBaseModel>>;
+}): FilterData<TBaseModel> => {
+  const allowedKeys: Array<string> = getFilterKeys<TBaseModel>(data.filters);
+  const sanitized: FilterData<TBaseModel> = {};
+
+  for (const key in data.filterData || {}) {
+    if (!allowedKeys.includes(key)) {
+      continue;
+    }
+
+    const value: unknown = (data.filterData as any)[key];
+
+    if (value === undefined || value === null) {
+      continue;
+    }
+
+    (sanitized as any)[key] = value;
+  }
+
+  return sanitized;
+};
+
+export { sanitizeFilterData };
+
+export type BuildQueryFromFilterDataFunction = <
+  TBaseModel extends BaseModel | AnalyticsBaseModel,
+>(data: {
+  filterData: FilterData<TBaseModel>;
+  filters: Array<Filter<TBaseModel>>;
+}) => Query<TBaseModel>;
+
+const buildQueryFromFilterData: BuildQueryFromFilterDataFunction = <
+  TBaseModel extends BaseModel | AnalyticsBaseModel,
+>(data: {
+  filterData: FilterData<TBaseModel>;
+  filters: Array<Filter<TBaseModel>>;
+}): Query<TBaseModel> => {
+  const filterData: FilterData<TBaseModel> = data.filterData || {};
+  const filters: Array<Filter<TBaseModel>> = data.filters || [];
+
+  const query: Query<TBaseModel> = {};
+
+  for (const key in filterData) {
+    const value: unknown = filterData[key];
+
+    if (value && typeof value === Typeof.String) {
+      query[key as keyof TBaseModel] = (value || "").toString();
+    }
+
+    if (typeof value === Typeof.Boolean) {
+      query[key as keyof TBaseModel] = Boolean(value);
+    }
+
+    if (typeof value === Typeof.Number) {
+      query[key as keyof TBaseModel] = value as any;
+    }
+
+    if (value instanceof Date) {
+      query[key as keyof TBaseModel] = value as any;
+    }
+
+    if (value instanceof Search) {
+      query[key as keyof TBaseModel] = value as any;
+    }
+
+    if (value instanceof InBetween) {
+      query[key as keyof TBaseModel] = value as any;
+    }
+
+    if (
+      filters.find((f: Filter<TBaseModel>) => {
+        return f.field && (f.field as any)[key];
+      })?.type === FieldType.JSON &&
+      typeof value === Typeof.Object
+    ) {
+      query[key as keyof TBaseModel] = value as any;
+    }
+
+    if (Array.isArray(value)) {
+      query[key as keyof TBaseModel] = new Includes(
+        value as Array<string>,
+      ) as any;
+    }
+
+    /*
+     * Pass any QueryOperator instance (IncludesAll, IncludesNone, StartsWith,
+     * EndsWith, NotContains, EqualTo, NotEqual, GreaterThan, LessThan,
+     * InBetween, IsNull, NotNull, ...) through to the query as-is.
+     */
+    if (value instanceof QueryOperator) {
+      query[key as keyof TBaseModel] = value as any;
+    }
+  }
+
+  return query;
+};
+
+export default buildQueryFromFilterData;

package/UI/Components/Navbar/NavBar.tsx

@@ -33,6 +33,21 @@ export interface MoreMenuItem {
   iconColor?: string; // Tailwind color name like "blue", "purple", "amber"
   category?: string; // Category for grouping items (e.g., "Essentials", "Observability")
   activeRoute?: Route | undefined; // Route to check for active state
+  additionalActiveRoutes?: Array<Route> | undefined; // Extra routes that also mark this item active
+}
+
+/*
+ * One menu item can own several route prefixes (e.g. a merged "Network" item
+ * spanning /network-devices and /network-sites) — check them all.
+ */
+export function isMoreMenuItemActive(item: MoreMenuItem): boolean {
+  const routesToCheck: Array<Route> = [
+    item.activeRoute || item.route,
+    ...(item.additionalActiveRoutes || []),
+  ];
+  return routesToCheck.some((route: Route) => {
+    return Navigation.isStartWith(route);
+  });
 }
 
 export interface ComponentProps {
@@ -254,8 +269,7 @@ const Navbar: FunctionComponent<ComponentProps> = (
   // Find active item in more menu items (needed for breadcrumb)
   const activeMoreItem: MoreMenuItem | undefined = props.moreMenuItems?.find(
     (item: MoreMenuItem) => {
-      const routeToCheck: Route = item.activeRoute || item.route;
-      return Navigation.isStartWith(routeToCheck);
+      return isMoreMenuItemActive(item);
     },
   );
 

package/UI/Components/Navbar/NavBarMenuModal.tsx

@@ -3,7 +3,7 @@ import Link from "../Link/Link";
 import Navigation from "../../Utils/Navigation";
 import IconProp from "../../../Types/Icon/IconProp";
 import URL from "../../../Types/API/URL";
-import type { MoreMenuItem } from "./NavBar";
+import { isMoreMenuItemActive, type MoreMenuItem } from "./NavBar";
 import React, {
   FunctionComponent,
   ReactElement,
@@ -209,7 +209,7 @@ const NavBarMenuModal: FunctionComponent<ComponentProps> = (
     const resolved: MoreMenuItem[] = [];
     recentRoutes.forEach((route: string) => {
       const item: MoreMenuItem | undefined = itemByRoute.get(route);
-      if (item && !Navigation.isStartWith(item.activeRoute || item.route)) {
+      if (item && !isMoreMenuItemActive(item)) {
         resolved.push(item);
       }
     });
@@ -269,7 +269,7 @@ const NavBarMenuModal: FunctionComponent<ComponentProps> = (
   // Index of the product matching the current page (the "you are here" item).
   const currentFlatIndex: number = useMemo(() => {
     return flatItems.findIndex((item: MoreMenuItem) => {
-      return Navigation.isStartWith(item.activeRoute || item.route);
+      return isMoreMenuItemActive(item);
     });
   }, [flatItems]);
 

package/UI/Utils/Navigation.ts

@@ -52,6 +52,16 @@ abstract class Navigation {
     return pathes?.[0]?.route.path || "";
   }
 
+  /**
+   * The raw query string of the current URL, including the leading "?" when
+   * non-empty (i.e. exactly `window.location.search`). Reading it through
+   * Navigation keeps callers testable and consistent with
+   * {@link setQueryString}, which also works off `window.location`.
+   */
+  public static getQueryString(): string {
+    return window.location.search;
+  }
+
   public static getQueryStringByName(paramName: string): string | null {
     const urlSearchParams: URLSearchParams = new URLSearchParams(
       window.location.search,

package/UI/Utils/TableFilterUrlState.ts

@@ -1,28 +1,126 @@
 import Navigation from "./Navigation";
+import Dictionary from "../../Types/Dictionary";
 import { JSONObject } from "../../Types/JSON";
 import JSONFunctions from "../../Types/JSONFunctions";
+import { Logger } from "./Logger";
+import { VoidFunction } from "../../Types/FunctionTypes";
 
-export type TableFilterUrlStateKind = "facets" | "filter";
+/**
+ * The three independent slices of a table's view state. Each is stored under
+ * its own `<tableId>-<kind>` query param so a change to one never has to
+ * re-serialize the others.
+ *
+ *  - `filter` — the classic column-filter popup selections (`FilterData`).
+ *  - `facets` — the chip/facet bar selections (see `useResourceOwners`).
+ *  - `view`   — search text, label chips, sort and pagination.
+ */
+export type TableFilterUrlStateKind = "facets" | "filter" | "view";
+
+export const TableFilterUrlStateKinds: Array<TableFilterUrlStateKind> = [
+  "filter",
+  "facets",
+  "view",
+];
 
 /**
- * Persists a table's filter/facet selections in the URL query string so they:
+ * Persists a table's filter / facet / view selections in the URL query string
+ * so they:
  *  - survive navigating to a detail page and clicking the browser "Back" button
  *    (the list page remounts with the params still on the URL), and
  *  - are shareable/bookmarkable (the URL fully describes the filtered view).
  *
  * The snapshot is run through {@link JSONFunctions} so OneUptime's typed query
  * values (Search, Includes, InBetween, ...) round-trip as real class instances
- * rather than plain objects. Params are namespaced by `tableId` so two tables on
- * the same route don't clobber each other.
+ * rather than plain objects. Params are namespaced by `tableId` so several
+ * tables on the same route each keep their own state.
  */
 export default class TableFilterUrlState {
-  private static getParamName(
+  /**
+   * Upper bound on the whole query string we are willing to produce.
+   *
+   * nginx's default `large_client_header_buffers` gives ~8KB for the entire
+   * request line, and that budget is shared with the path and every other
+   * table on the page. We stay well under it: past this point the table keeps
+   * working from React state, it just stops mirroring the offending slice into
+   * the URL (so the link degrades to "unshared" rather than the page failing
+   * to load on refresh).
+   */
+  public static readonly MaxQueryStringLength: number = 4000;
+
+  public static getParamName(
     tableId: string,
     kind: TableFilterUrlStateKind,
   ): string {
     return `${tableId}-${kind}`;
   }
 
+  /**
+   * Keys currently claimed by mounted tables, so a duplicate can be reported.
+   * Not used to change behaviour — two tables sharing a key would already have
+   * shared their `userPreferencesKey` page-size preference, so the fix always
+   * belongs at the call site.
+   */
+  private static claimedKeys: Map<string, number> = new Map<string, number>();
+
+  /**
+   * Register a mounted table's URL namespace. Returns a release function to
+   * call on unmount.
+   *
+   * Two tables on one route claiming the same key would read and write the
+   * same params — paging one would repaginate the other, and a reload would
+   * restore whichever wrote last. That is always a call-site bug (give the
+   * tables distinct `userPreferencesKey`/`urlStateKey` values), so this warns
+   * loudly rather than silently renaming a key that may already be in
+   * someone's bookmarks.
+   */
+  public static claimKey(tableId: string | undefined): VoidFunction {
+    if (!tableId) {
+      return () => {
+        // nothing claimed
+      };
+    }
+
+    const claims: number = (this.claimedKeys.get(tableId) || 0) + 1;
+    this.claimedKeys.set(tableId, claims);
+
+    if (claims > 1) {
+      Logger.warn(
+        `TableFilterUrlState: ${claims} tables on this page share the URL state key "${tableId}". ` +
+          `They will overwrite each other's filters, sort and pagination in the URL. ` +
+          `Give each table a distinct "userPreferencesKey" (or pass "urlStateKey").`,
+      );
+    }
+
+    return () => {
+      const remaining: number = (this.claimedKeys.get(tableId) || 1) - 1;
+
+      if (remaining <= 0) {
+        this.claimedKeys.delete(tableId);
+        return;
+      }
+
+      this.claimedKeys.set(tableId, remaining);
+    };
+  }
+
+  /**
+   * Test seam — drops every claim so one test's mounted tables don't leak into
+   * the next.
+   */
+  public static resetClaimedKeys(): void {
+    this.claimedKeys.clear();
+  }
+
+  /**
+   * Every param name this table could own. Used to clear a table's state and
+   * by tests.
+   */
+  public static getAllParamNames(tableId: string): Array<string> {
+    return TableFilterUrlStateKinds.map((kind: TableFilterUrlStateKind) => {
+      return this.getParamName(tableId, kind);
+    });
+  }
+
   /*
    * Read a previously-persisted snapshot from the URL. Returns null when absent,
    * empty, or unparseable (e.g. a hand-edited param) so callers fall back to
@@ -67,26 +165,115 @@ export default class TableFilterUrlState {
     tableId: string | undefined,
     kind: TableFilterUrlStateKind,
     state: JSONObject | null,
+  ): void {
+    this.writeMany(tableId, { [kind]: state });
+  }
+
+  /**
+   * Write several slices in one `history.replaceState` call. Passing a kind
+   * with a `null`/empty value removes that param; omitting a kind leaves
+   * whatever is already on the URL untouched.
+   */
+  public static writeMany(
+    tableId: string | undefined,
+    states: Partial<Record<TableFilterUrlStateKind, JSONObject | null>>,
   ): void {
     if (!tableId) {
       return;
     }
 
-    try {
-      const hasState: boolean = Boolean(state && Object.keys(state).length > 0);
+    const params: Dictionary<string | null> = {};
+
+    /*
+     * Track the query string as it would look after each param is applied, so
+     * the size check accounts for the other params in this same batch — not
+     * just the URL as it was before the batch started.
+     */
+    const projected: URLSearchParams = this.getCurrentSearchParams();
+
+    for (const kind of Object.keys(states) as Array<TableFilterUrlStateKind>) {
+      const state: JSONObject | null | undefined = states[kind];
+      const paramName: string = this.getParamName(tableId, kind);
+
+      let value: string | null = null;
+
+      try {
+        const hasState: boolean = Boolean(
+          state && Object.keys(state).length > 0,
+        );
 
-      const value: string | null = hasState
-        ? JSON.stringify(JSONFunctions.serialize(state as JSONObject))
-        : null;
+        value = hasState
+          ? JSON.stringify(JSONFunctions.serialize(state as JSONObject))
+          : null;
+      } catch (err) {
+        /*
+         * Serialization failure (shouldn't happen for filter data) — drop the
+         * param rather than break the table, and leave a breadcrumb.
+         */
+        Logger.warn(
+          `TableFilterUrlState: could not serialize "${paramName}": ${err}`,
+        );
+        value = null;
+      }
+
+      if (value === null) {
+        projected.delete(paramName);
+      } else {
+        const previous: string | null = projected.get(paramName);
+        projected.set(paramName, value);
+
+        if (projected.toString().length > this.MaxQueryStringLength) {
+          /*
+           * Too big to share. Drop the param so a page refresh doesn't hit an
+           * over-long request line — React state remains the source of truth
+           * for this session.
+           */
+          Logger.warn(
+            `TableFilterUrlState: "${paramName}" is too large for the URL (${value.length} chars) and was not persisted.`,
+          );
+          value = null;
+
+          if (previous === null) {
+            projected.delete(paramName);
+          } else {
+            projected.set(paramName, previous);
+          }
+        }
+      }
+
+      params[paramName] = value;
+    }
 
-      Navigation.setQueryString({
-        [this.getParamName(tableId, kind)]: value,
-      });
+    Navigation.setQueryString(params);
+  }
+
+  /**
+   * Remove every param this table owns from the URL.
+   */
+  public static clear(tableId: string | undefined): void {
+    if (!tableId) {
+      return;
+    }
+
+    const params: Dictionary<string | null> = {};
+
+    for (const paramName of this.getAllParamNames(tableId)) {
+      params[paramName] = null;
+    }
+
+    Navigation.setQueryString(params);
+  }
+
+  /**
+   * The current query string as a mutable `URLSearchParams`. Size checks
+   * measure `toString()` on this — the *encoded* length, because that is what
+   * actually travels on the wire.
+   */
+  private static getCurrentSearchParams(): URLSearchParams {
+    try {
+      return new URLSearchParams(Navigation.getQueryString());
     } catch {
-      /*
-       * Serialization failure (shouldn't happen for filter data) — skip the
-       * URL sync rather than break the table.
-       */
+      return new URLSearchParams();
     }
   }
 }

package/UI/Utils/TableViewUrlState.ts

@@ -0,0 +1,165 @@
+import { JSONObject } from "../../Types/JSON";
+import SortOrder from "../../Types/BaseDatabase/SortOrder";
+import LIMIT_MAX from "../../Types/Database/LimitMax";
+
+/**
+ * The "everything that isn't a column filter or a facet" slice of a table's
+ * view: the search box, the label chips next to it, the active sort and where
+ * in the pagination the user is.
+ *
+ * Kept deliberately primitive (strings / numbers / string arrays) so the URL
+ * param stays short and human-readable, and so a hand-edited link can never
+ * smuggle a typed object into the table's query.
+ */
+export interface TableViewUrlStateData {
+  search?: string | undefined;
+  labels?: Array<string> | undefined;
+  sortBy?: string | undefined;
+  sortOrder?: SortOrder | undefined;
+  page?: number | undefined;
+  itemsOnPage?: number | undefined;
+}
+
+/**
+ * The values a slice is compared against before being written. Anything equal
+ * to its default is left out of the URL, so a table the user hasn't touched
+ * contributes no query params at all.
+ */
+export interface TableViewUrlStateDefaults {
+  sortBy?: string | undefined;
+  sortOrder?: SortOrder | undefined;
+}
+
+/**
+ * Hard ceiling on a restored page size. Anything above this is a hand-edited
+ * URL trying to make the table ask the API for an unbounded page.
+ */
+export const MaxItemsOnPage: number = 1000;
+
+export default class TableViewUrlState {
+  /**
+   * Serialize to the plain object that goes in the URL, omitting every value
+   * that matches its default. Returns `null` when nothing is worth persisting
+   * so the caller can drop the param entirely.
+   */
+  public static toJSON(
+    state: TableViewUrlStateData,
+    defaults?: TableViewUrlStateDefaults | undefined,
+  ): JSONObject | null {
+    const json: JSONObject = {};
+
+    const search: string = (state.search || "").trim();
+    if (search.length > 0) {
+      json["search"] = search;
+    }
+
+    const labels: Array<string> = (state.labels || []).filter((l: string) => {
+      return Boolean(l);
+    });
+    if (labels.length > 0) {
+      json["labels"] = labels;
+    }
+
+    /*
+     * Sort is only worth persisting when it differs from the sort the table
+     * was mounted with — otherwise every table on the page would carry a
+     * redundant param.
+     */
+    const sortIsDefault: boolean =
+      (state.sortBy || null) === (defaults?.sortBy || null) &&
+      (state.sortOrder || null) === (defaults?.sortOrder || null);
+
+    if (state.sortBy && !sortIsDefault) {
+      json["sortBy"] = state.sortBy;
+      json["sortOrder"] = state.sortOrder || SortOrder.Ascending;
+    }
+
+    if (state.page && state.page > 1) {
+      json["page"] = state.page;
+    }
+
+    if (state.itemsOnPage && state.itemsOnPage > 0) {
+      json["itemsOnPage"] = state.itemsOnPage;
+    }
+
+    if (Object.keys(json).length === 0) {
+      return null;
+    }
+
+    return json;
+  }
+
+  /**
+   * Rebuild the view state from a URL param. Every field is validated
+   * independently: a bad `page` doesn't discard a good `search`, and an
+   * unrecognised value is dropped rather than passed through to the query.
+   */
+  public static fromJSON(
+    json: JSONObject | null | undefined,
+  ): TableViewUrlStateData {
+    const state: TableViewUrlStateData = {};
+
+    if (!json || typeof json !== "object") {
+      return state;
+    }
+
+    if (typeof json["search"] === "string" && json["search"].trim() !== "") {
+      state.search = json["search"];
+    }
+
+    if (Array.isArray(json["labels"])) {
+      const labels: Array<string> = (json["labels"] as Array<unknown>)
+        .filter((l: unknown) => {
+          return typeof l === "string" && l.trim() !== "";
+        })
+        .map((l: unknown) => {
+          return l as string;
+        });
+
+      if (labels.length > 0) {
+        state.labels = labels;
+      }
+    }
+
+    if (typeof json["sortBy"] === "string" && json["sortBy"].trim() !== "") {
+      state.sortBy = json["sortBy"];
+
+      state.sortOrder =
+        json["sortOrder"] === SortOrder.Descending
+          ? SortOrder.Descending
+          : SortOrder.Ascending;
+    }
+
+    const page: number | null = this.toPositiveInteger(json["page"]);
+    if (page !== null && page >= 1) {
+      state.page = page;
+    }
+
+    const itemsOnPage: number | null = this.toPositiveInteger(
+      json["itemsOnPage"],
+    );
+    if (
+      itemsOnPage !== null &&
+      itemsOnPage >= 1 &&
+      itemsOnPage <= MaxItemsOnPage
+    ) {
+      state.itemsOnPage = itemsOnPage;
+    }
+
+    return state;
+  }
+
+  private static toPositiveInteger(value: unknown): number | null {
+    if (typeof value !== "number" || !isFinite(value)) {
+      return null;
+    }
+
+    const asInteger: number = Math.floor(value);
+
+    if (asInteger < 1 || asInteger > LIMIT_MAX) {
+      return null;
+    }
+
+    return asInteger;
+  }
+}