Transform meta redirect tags (#25766)

* Add TechDocs support for the mkdocs-redirects plugin.
---------

Signed-off-by: Sydney Achinger <sydneynicoleachinger@spotify.com>

plugins/techdocs/src/reader/components/TechDocsReaderPageContent/dom.tsx

@@ -46,6 +46,7 @@ import {
   useStylesTransformer,
 } from '../../transformers';
 import { useNavigateUrl } from './useNavigateUrl';
+import { handleMetaRedirects } from '../../transformers/handleMetaRedirects';
 
 const MOBILE_MEDIA_QUERY = 'screen and (max-width: 76.1875em)';
 
@@ -186,6 +187,7 @@ export const useTechDocsReaderDom = (
   const postRender = useCallback(
     async (transformedElement: Element) =>
       transformer(transformedElement, [
+        handleMetaRedirects(navigate, entityRef.name),
         scrollIntoNavigation(),
         copyToClipboard(theme),
         addLinkClickListener({
@@ -243,7 +245,7 @@ export const useTechDocsReaderDom = (
           onLoaded: () => {},
         }),
       ]),
-    [theme, navigate, analytics],
+    [theme, navigate, analytics, entityRef.name],
   );
 
   useEffect(() => {

plugins/techdocs/src/reader/transformers/handleMetaRedirects.test.ts

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { handleMetaRedirects } from './handleMetaRedirects';
+import { createTestShadowDom } from '../../test-utils';
+
+describe('handleMetaRedirects', () => {
+  const navigate = jest.fn();
+
+  const setUpNewTestShadowDom = async (
+    html: string,
+    rootHref: string,
+    rootPath: string,
+  ) => {
+    const entityName = 'testEntity';
+    // Mock window.location.href for each test
+    Object.defineProperty(window, 'location', {
+      value: {
+        href: rootHref,
+        pathname: rootPath,
+        hostname: 'localhost',
+      },
+      writable: true,
+    });
+
+    return await createTestShadowDom(html, {
+      preTransformers: [],
+      postTransformers: [handleMetaRedirects(navigate, entityName)],
+    });
+  };
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should navigate to relative URL if meta redirect tag is present', async () => {
+    await setUpNewTestShadowDom(
+      `<meta http-equiv="refresh" content="0; url=../anotherPage">`,
+      'http://localhost/docs/default/component/testEntity/subpath',
+      '/docs/default/component/testEntity/subpath',
+    );
+    expect(navigate).toHaveBeenCalledWith(
+      'http://localhost/docs/default/component/testEntity/anotherPage',
+    );
+  });
+
+  it('should navigate to site home if meta redirect tag is present and external', async () => {
+    await setUpNewTestShadowDom(
+      `<meta http-equiv="refresh" content="0; url=http://external.com/test">`,
+      'http://localhost/docs/default/component/testEntity/subpath',
+      '/docs/default/component/testEntity/subpath',
+    );
+    expect(navigate).toHaveBeenCalledWith('/docs/default/component/testEntity');
+  });
+
+  it('should navigate to absolute URL if meta redirect tag is present and not external', async () => {
+    await setUpNewTestShadowDom(
+      `<meta http-equiv="refresh" content="0; url=http://localhost/test">`,
+      'http://localhost/docs/default/component/testEntity/subpath',
+      '/docs/default/component/testEntity/subpath',
+    );
+    expect(navigate).toHaveBeenCalledWith('http://localhost/test');
+  });
+
+  it('should not navigate if meta redirect tag is not present', async () => {
+    await setUpNewTestShadowDom(
+      `<meta name="keywords" content="TechDocs, Example">`,
+      'http://localhost/docs/default/component/testEntity/subpath',
+      '/docs/default/component/testEntity/subpath',
+    );
+    expect(navigate).not.toHaveBeenCalled();
+  });
+});

plugins/techdocs/src/reader/transformers/handleMetaRedirects.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Transformer } from './transformer';
+import { normalizeUrl } from './rewriteDocLinks';
+
+export const handleMetaRedirects = (
+  navigate: (to: string) => void,
+  entityName: string,
+): Transformer => {
+  return dom => {
+    for (const elem of Array.from(dom.querySelectorAll('meta'))) {
+      if (elem.getAttribute('http-equiv') === 'refresh') {
+        const metaContentParameters = elem
+          .getAttribute('content')
+          ?.split('url=');
+        if (!metaContentParameters || metaContentParameters.length < 2) {
+          continue;
+        }
+
+        const metaUrl = metaContentParameters[1];
+        const normalizedCurrentUrl = normalizeUrl(window.location.href);
+        // If metaUrl is relative, it will be resolved with base href. If it is absolute, it will replace the base href when creating URL object.
+        const absoluteRedirectObj = new URL(metaUrl, normalizedCurrentUrl);
+        const isExternalRedirect =
+          absoluteRedirectObj.hostname !== window.location.hostname;
+
+        if (isExternalRedirect) {
+          // If the redirect is external, navigate to the documentation site home instead of the external url.
+          const currentTechDocPath = window.location.pathname;
+          const indexOfSiteHome = currentTechDocPath.indexOf(entityName);
+          const siteHomePath = currentTechDocPath.slice(
+            0,
+            indexOfSiteHome + entityName.length,
+          );
+          navigate(siteHomePath);
+        } else {
+          // The navigate function from dom.tsx is a wrapper around react-router navigate function that helps absolute url redirects.
+          navigate(absoluteRedirectObj.href);
+        }
+        return dom;
+      }
+    }
+    return dom;
+  };
+};

plugins/techdocs/src/reader/transformers/html/transformer.test.tsx

@@ -81,4 +81,44 @@ describe('Transformers > Html', () => {
     expect(iframes).toHaveLength(1);
     expect(iframes[0].src).toMatch('docs.google.com');
   });
+
+  it('should return a function that allows refresh meta tags', async () => {
+    const { result } = renderHook(() => useSanitizerTransformer(), { wrapper });
+
+    const dirtyDom = document.createElement('html');
+    dirtyDom.innerHTML = `
+        <body>
+         <meta http-equiv="refresh" content="0;url=https://test.com">
+        </body>
+      `;
+    const cleanDom = await result.current(dirtyDom); // calling html transformer
+
+    const metaTags = Array.from(
+      cleanDom.querySelectorAll<HTMLMetaElement>('meta'),
+    );
+
+    expect(metaTags).toHaveLength(1);
+    expect(metaTags[0].getAttribute('http-equiv')).toEqual('refresh');
+    expect(metaTags[0].getAttribute('content')).toEqual(
+      '0;url=https://test.com',
+    );
+  });
+
+  it('should return a function that does not allow non-refresh meta tags', async () => {
+    const { result } = renderHook(() => useSanitizerTransformer(), { wrapper });
+
+    const dirtyDom = document.createElement('html');
+    dirtyDom.innerHTML = `
+        <body>
+         <meta name="keywords" content="TechDocs, Example">
+        </body>
+      `;
+    const cleanDom = await result.current(dirtyDom); // calling html transformer
+
+    const metaTags = Array.from(
+      cleanDom.querySelectorAll<HTMLMetaElement>('meta'),
+    );
+
+    expect(metaTags).toHaveLength(0);
+  });
 });

plugins/techdocs/src/reader/transformers/html/transformer.ts

@@ -44,17 +44,39 @@ export const useSanitizerTransformer = (): Transformer => {
       const hosts = config?.getOptionalStringArray('allowedIframeHosts');
 
       DOMPurify.addHook('beforeSanitizeElements', removeUnsafeLinks);
-      const tags = ['link'];
+      const tags = ['link', 'meta'];
 
       if (hosts) {
         tags.push('iframe');
         DOMPurify.addHook('beforeSanitizeElements', removeUnsafeIframes(hosts));
       }
 
+      // Only allow meta tags if they are used for refreshing the page. They are required for the redirect feature.
+      DOMPurify.addHook('uponSanitizeElement', (currNode, data) => {
+        if (data.tagName === 'meta') {
+          const isMetaRefreshTag =
+            currNode.getAttribute('http-equiv') === 'refresh' &&
+            currNode.getAttribute('content')?.includes('url=');
+          if (!isMetaRefreshTag) {
+            currNode.parentNode?.removeChild(currNode);
+          }
+        }
+      });
+
+      // Only allow http-equiv and content attributes on meta tags. They are required for the redirect feature.
+      DOMPurify.addHook('uponSanitizeAttribute', (currNode, data) => {
+        if (currNode.tagName !== 'meta') {
+          if (data.attrName === 'http-equiv' || data.attrName === 'content') {
+            currNode.removeAttribute(data.attrName);
+          }
+        }
+      });
+
       // using outerHTML as we want to preserve the html tag attributes (lang)
       return DOMPurify.sanitize(dom.outerHTML, {
         ADD_TAGS: tags,
         FORBID_TAGS: ['style'],
+        ADD_ATTR: ['http-equiv', 'content'],
         WHOLE_DOCUMENT: true,
         RETURN_DOM: true,
       });