Invisible proxy (#157)

* Add mermaid

* Add proxying reference

* Add concept invisible proxying

* Optimised images with calibre/image-actions

* Refactor reference in concept and guide

* Fix dead link

* Improve documentation with new invisible flag

* Optimised images with calibre/image-actions

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: Sytten

.vitepress/components/Mermaid.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from "vue";
+import type { MermaidConfig } from "mermaid";
+import mermaid from "mermaid";
+
+const props = defineProps({
+  graph: {
+    type: String,
+    required: true,
+  },
+  id: {
+    type: String,
+    required: true,
+  },
+});
+
+const svg = ref("");
+const code = ref(decodeURIComponent(props.graph));
+
+let mut: MutationObserver | null = null;
+
+onMounted(async () => {
+  mut = new MutationObserver(() => {
+    renderChart();
+  });
+  mut.observe(document.documentElement, { attributes: true });
+
+  await renderChart();
+
+  //refresh images on first render
+  const hasImages = (/<img([\w\W]+?)>/.exec(code.value)?.length ?? 0) > 0;
+  if (hasImages)
+    setTimeout(() => {
+      let imgElements = document.getElementsByTagName("img");
+      let imgs = Array.from(imgElements);
+      if (imgs.length) {
+        Promise.all(
+          imgs
+            .filter((img) => !img.complete)
+            .map(
+              (img) =>
+                new Promise((resolve) => {
+                  img.onload = img.onerror = resolve;
+                }),
+            ),
+        ).then(() => {
+          renderChart();
+        });
+      }
+    }, 100);
+});
+
+onUnmounted(() => mut?.disconnect());
+
+const renderChart = async () => {
+  const mermaidConfig: MermaidConfig = {
+    securityLevel: "loose",
+    startOnLoad: false,
+    theme: "dark",
+  };
+  mermaid.initialize(mermaidConfig);
+  const render = await mermaid.render(props.id, code.value);
+  // This is a hack to force v-html to re-render, otherwise the diagram disappears
+  // when **switching themes** or **reloading the page**.
+  // The cause is that the diagram is deleted during rendering (out of Vue's knowledge).
+  // Because svgCode does NOT change, v-html does not re-render.
+  // This is not required for all diagrams, but it is required for c4c, mindmap and zenuml.
+  const salt = Math.random().toString(36).substring(7);
+  svg.value = `${render.svg} <span style="display: none">${salt}</span>`;
+};
+</script>
+
+<template>
+  <!-- eslint-disable-next-line vue/no-v-html -->
+  <div v-html="svg" />
+</template>

.vitepress/config.mts

@@ -7,6 +7,7 @@ import {
   referenceSidebar,
   tutorialsSidebar,
 } from "./sidebars";
+import MermaidExample from "./mermaid";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -34,6 +35,12 @@ export default defineConfig({
   ],
   ignoreDeadLinks: "localhostLinks",
 
+  markdown: {
+    config: (md) => {
+      MermaidExample(md);
+    },
+  },
+
   themeConfig: {
     logo: {
       src: "/logo.png",

.vitepress/mermaid.ts

@@ -0,0 +1,32 @@
+import type { MarkdownRenderer } from "vitepress";
+
+const MermaidExample = (md: MarkdownRenderer) => {
+  const defaultRenderer = md.renderer.rules.fence;
+
+  if (!defaultRenderer) {
+    throw new Error("defaultRenderer is undefined");
+  }
+
+  md.renderer.rules.fence = (tokens, index, options, env, slf) => {
+    const token = tokens[index]!;
+    const language = token.info.trim();
+    if (language.startsWith("mermaid")) {
+      const key = index;
+      return `
+      <Suspense>
+        <template #default>
+          <Mermaid id="mermaid-${key}" graph="${encodeURIComponent(token.content)}" />
+        </template>
+        <!-- loading state via #fallback slot -->
+        <template #fallback>
+          Loading...
+        </template>
+      </Suspense>
+`;
+    }
+
+    return defaultRenderer(tokens, index, options, env, slf);
+  };
+};
+
+export default MermaidExample;

.vitepress/sidebars/concepts.ts

@@ -30,6 +30,19 @@ export const conceptsSidebar: DefaultTheme.SidebarItem[] = [
       },
     ],
   },
+  {
+    text: "Proxying",
+    items: [
+      {
+        text: "Traffic splitting",
+        link: "/concepts/proxying/traffic_splitting",
+      },
+      {
+        text: "Invisible Proxying",
+        link: "/concepts/proxying/invisible",
+      },
+    ],
+  },
   {
     text: "Workflows",
     items: [

.vitepress/sidebars/guides.ts

@@ -50,6 +50,10 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [
             text: "Upstream to Another Proxy",
             link: "/guides/upstream",
           },
+          {
+            text: "Enabling invisible proxying",
+            link: "/guides/invisible_proxying",
+          },
         ],
       },
       {

.vitepress/theme/index.ts

@@ -2,11 +2,13 @@ import DefaultTheme from "vitepress/theme";
 import "./custom.css";
 
 import ProContainer from "../components/Pro.vue";
+import Mermaid from "../components/Mermaid.vue";
 import type { Theme } from "vitepress";
 
 export default {
   extends: DefaultTheme,
   enhanceApp({ app }) {
     app.component("ProContainer", ProContainer);
+    app.component("Mermaid", Mermaid);
   },
 } satisfies Theme;

package.json

@@ -19,9 +19,11 @@
     "eslint-plugin-prettier": "5.2.1",
     "eslint-plugin-vue": "9.27.0",
     "markdownlint-cli2": "0.14.0",
+    "mermaid": "11.4.1",
     "typescript": "5.6.2",
     "typescript-eslint": "8.5.0",
     "vitepress": "1.2.2",
+    "vue": "3.4.27",
     "vue-eslint-parser": "9.4.3"
   }
 }