feat: rules-based automatic parameterisation from pathnames

There are multiple ways to automatically parameterise pathnames. This is one approach, and generally the fastest, a set of functions each accept the pathname of an incoming request and determine which parts are parameters. At present, only UUIDs are identified. Other approaches might include custom regex strings, or custom function logic.

- Ability to automatically identify path parameters from a set of rules
- Designed to be used in conjunction with more computationally expensive methods
- Rules are functions. New functions can be added to identify path parameters from string patterns
- The only current rule is that UUIDs in pathnames will be parameterised

Author: AndrewWalsh

manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "OpenAPI DevTools",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "devtools_page": "index.html",
   "permissions": [],
   "icons": {

package-lock.json

@@ -8,7 +8,7 @@
     "test": "vitest",
     "dev": "tsc && vite build && web-ext run -s dist",
     "build": "tsc && vite build && web-ext build --overwrite-dest -s dist",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0 --fix"
+    "lint": "eslint --ext ts,tsx --fix ."
   },
   "dependencies": {
     "@chakra-ui/icons": "^2.1.1",
@@ -33,7 +33,8 @@
     "react-window": "^1.8.9",
     "redoc": "^2.1.3",
     "store2": "^2.14.2",
-    "truncate-middle": "^1.0.6"
+    "truncate-middle": "^1.0.6",
+    "validator": "^13.11.0"
   },
   "devDependencies": {
     "@crxjs/vite-plugin": "^2.0.0-beta.19",
@@ -47,6 +48,7 @@
     "@types/react-dom": "^18.2.13",
     "@types/react-window": "^1.8.7",
     "@types/truncate-middle": "^1.0.3",
+    "@types/validator": "^13.11.9",
     "@typescript-eslint/eslint-plugin": "^6.8.0",
     "@vitejs/plugin-react": "^4.1.0",
     "eslint": "^8.51.0",

package.json

@@ -250,3 +250,21 @@ it("parameterisation works after export and import", () => {
   // @ts-expect-error accessing private property
   expect(store.storeOptions).toEqual(expectedOptions);
 });
+
+it("automatically parameterises pathnames containing known path parameters such as UUIDs", () => {
+  const store = new RequestStore();
+  const req = createSimpleRequest(`${base}/1/2/a`);
+  const uuid = "7be85ff3-2785-45d4-81d0-b8b58f80dfdc";
+  const host = "http://test.com";
+  const pathname = `/v1/${uuid}/sites/${uuid}`;
+  const url = `${host}${pathname}`;
+  req.request.url = url;
+  store.insert(req, contentIntTest);
+  // The path parameters are the UUIDs in this example
+  const splitUrl = pathname.split("/").slice(1);
+  splitUrl[1] = ":param1";
+  splitUrl[3] = ":param3";
+  const expectUrl = `/${splitUrl.join("/")}`;
+  // @ts-expect-error accessing private property
+  expect(store.leafMap["test.com"]).toHaveProperty(expectUrl);
+});

src/lib/RequestStore.test.ts

@@ -5,6 +5,7 @@ import {
   upsert,
   persistOptions,
   leafMapToRouterMap,
+  fastPathParameterIndices,
 } from "./store-helpers";
 import { omit, unset } from "lodash";
 import leafMapToEndpoints from "./leafmap-to-endpoints";
@@ -103,12 +104,21 @@ export default class RequestStore {
       leaf: insertedLeaf,
       path: insertedPath,
     });
+    let pathname = insertedPath;
+    for (const idx of fastPathParameterIndices(pathname)) {
+      const newPathname = this.parameterise(idx, pathname, insertedHost);
+      if (newPathname) pathname = newPathname;
+    }
     return true;
   }
 
-  public parameterise(index: number, path: string, host: string): void {
+  public parameterise(
+    index: number,
+    path: string,
+    host: string
+  ): string | null {
     const result = parameterise({ store: this.store, index, path, host });
-    if (!result) return;
+    if (!result) return null;
     const { removedPaths, insertedPath, insertedLeaf } = result;
     const unsetLeafMap = (path: string) => unset(this.leafMap[host], path);
     removedPaths.concat([path]).forEach(unsetLeafMap);
@@ -118,6 +128,7 @@ export default class RequestStore {
       leaf: insertedLeaf,
       path: insertedPath,
     });
+    return insertedPath;
   }
 
   public setDisabledHosts(disabledHosts: Set<string>): void {

src/lib/RequestStore.ts

@@ -0,0 +1,11 @@
+import { it, expect } from "vitest";
+import { fastPathParameterIndices } from "./automatic-parameterisation";
+
+// [what is being tested, pathname, indices that should be parameterised]
+it.each([["UUIDs", "/path/7be85ff3-2785-45d4-81d0-b8b58f80dfdc", [1]]])(
+  "returns indices of path parameters that are %s in pathnames",
+  (_, path, expected) => {
+    const result = fastPathParameterIndices(path);
+    expect(result).toEqual(expected);
+  }
+);

src/lib/store-helpers/automatic-parameterisation.test.ts

@@ -0,0 +1,20 @@
+import validator from "validator";
+
+const validationRules = [validator.isUUID];
+
+/**
+ * Fast and low-effort rules-based parameterisation of pathnames alone
+ * Designed to accompany a more computationally intensive analysis
+ * Returns an array of indices of path parameters in a given pathname that matches a validation rule
+ */
+export const fastPathParameterIndices = (pathname: string): Array<number> => {
+  const indices = [];
+  const parts = pathname.split("/").slice(1);
+  for (let idx = 0; idx < parts.length; idx++) {
+    const part = parts[idx];
+    if (validationRules.some((rule) => rule(part))) {
+      indices.push(idx);
+    }
+  }
+  return indices;
+};

src/lib/store-helpers/automatic-parameterisation.ts

@@ -9,3 +9,4 @@ export { default as determineAuthFromHAR } from "./authentication";
 export { default as remove } from "./remove";
 export * from "./merge";
 export * from "./helpers";
+export * from "./automatic-parameterisation";

src/lib/store-helpers/index.ts

@@ -102,6 +102,7 @@ function Main() {
     (index, path, host) => {
       requestStore.parameterise(index, path, host);
       setSpecEndpoints();
+      return null;
     },
     []
   );

src/ui/Main.tsx

@@ -25,9 +25,9 @@ const defaultContextValue: ContextType = {
   setAllHosts: () => {},
   disabledHosts: new Set(),
   setDisabledHosts: () => {},
-  parameterise: () => {},
+  parameterise: () => null,
   import: () => false,
-  export: () => '',
+  export: () => "",
   options: () => defaultOptions,
 };