docs: support mermaid diagrams (#34)

.github/workflows/docs.yml

@@ -28,15 +28,16 @@ jobs:
       MDBOOK_VERSION: 0.4.21
     steps:
       - uses: actions/checkout@v3
-      - name: Install mdBook
-        run: |
-          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
-          rustup update
-          cargo install --version ${MDBOOK_VERSION} mdbook
+      - uses: cachix/install-nix-action@v22
+        with:
+          nix_path: nixpkgs=channel:nixos-23.05
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v3
       - name: Build with mdBook
+        # this starts a shell with all ci deps -- see /flake.nix
+        shell: nix develop ".#ci-doc" --command bash {0}
         run: mdbook build doc
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2

doc/book.toml

@@ -4,3 +4,12 @@ language = "en"
 multilingual = false
 src = "src"
 title = "leng-doc"
+
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
+git-repository-url = "https://github.com/cottand/leng"
+edit-url-template = "https://github.com/cottand/leng/edit/master/book/{path}"

doc/mermaid-init.js

@@ -0,0 +1,35 @@
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById(darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById(lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();

doc/src/Blocking.md

@@ -1,5 +0,0 @@
-There are many blocklist resources online, and by default leng is configured to use some of the more popular ones from around the internet for blocking ads and malware domains. Some services exist that will allow you to regularly get blocklist updates automatically from feeds.
-
-## Blocklists
-
-[https://github.com/StevenBlack/hosts/](https://github.com/StevenBlack/hosts/)

doc/src/DNS/Blocking.md

@@ -0,0 +1,7 @@
+# Blocking DNS
+
+There are many blocklist resources online, and by default leng is configured to use some of the more popular ones from around the internet for blocking ads and malware domains. Some services exist that will allow you to regularly get blocklist updates automatically from feeds.
+
+## Blocklists
+
+[https://github.com/StevenBlack/hosts/](https://github.com/StevenBlack/hosts/)

doc/src/CNAME‐following-DNS.md → doc/src/DNS/CNAME‐following-DNS.md

@@ -1,3 +1,5 @@
+# CNAME Following
+
 Leng implements following CNAME records as specified in [RFC-1034 section 3.6.2](https://www.rfc-editor.org/rfc/rfc1034#section-3.6.2), where it returns all necessary CNAME and A records to fully resolve the query (as opposed to just returning a synthetic A record, which is known as [CNAME flattening](https://developers.cloudflare.com/dns/cname-flattening/cname-flattening-diagram/)).
 
 > ⚠ This is the behaviour of most if not all DNS servers - Leng is only special in this in that it has to deal with cuustom DNS records, the resolvers it proxies, and blocklists. **You should not need to change its default behaviour**, but this page aims to leave it well-documented.

doc/src/Custom-DNS-Records.md → doc/src/DNS/Custom-DNS-Records.md

@@ -1,3 +1,5 @@
+# Custom DNS Records
+
 You can make leng return records of your choosing (which will take precedence over upstream DNS records) by setting `customdnsrecords` in the [[Configuration]].
 
 Custom DNS records are represented as [Resource Record](https://en.wikipedia.org/wiki/Domain_Name_System#Resource_records) strings. Class defaults to IN and TTL defaults to 3600. Full zone file syntax is supported.

doc/src/DNS/DNS.md

@@ -0,0 +1,28 @@
+# DNS (overview)
+
+
+Leng works by proxying your DNS requests to an upstream DNS server,
+and returning a useless response when the request is for a blocked
+domain.
+
+Blocked domains are those that appear on a blocklist (downloaded
+at startup). You can see which blocklists are enabled by default
+and how to change them in [Configuration](./Configuration.md).
+
+Additionally, you can also configure custom responses for
+specific domains, indepenently of the blocklists.
+See more in [Custom DNS](Custom-DNS-Records.md).
+
+```mermaid
+    
+sequenceDiagram 
+    User --> Leng: 
+    Online Blocklists -->> Leng: Download lists
+    Note over Online Blocklists,Leng: At startup
+    User->> +Leng: A google.com
+    Leng ->> Upstream DNS: A gogle.com
+    Upstream DNS ->> Leng: google.com IN A 234.213.532.12
+    Leng ->> -User: google.com IN A 234.213.532.12
+    User ->> +Leng: A adservice.google.com
+    Leng ->> -User: adservice.google.com IN A 0.0.0.0
+```

doc/src/DNS/Privacy.md

@@ -0,0 +1,50 @@
+# DNS Privacy
+
+Leng can enhance your DNS Privacy in several ways
+
+## As your DoH provider
+
+[DNS-over-HTTPS](https://www.cloudflare.com/en-gb/learning/dns/dns-over-tls/)
+allows encrypted, hard-to-block DNS. You can set up DNS-over-HTTPS
+for most major browsers ([see how here](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/encrypted-dns-browsers/)).
+
+See how to set it up for leng at [DNS-over-HTTP](DNS-over-HTTPS-(DoH).md).
+
+If all you want is to use DoH, and you do not really care about ad/tracking-blocking,
+using leng instead of an existing DoH provider directly has little
+benefit: you will be getting
+all the features of DoH, but the DNS provider will still know what you are visiting.
+There isn't an easy way around this: we need to resolve your DNS query somehow!
+
+
+
+## As a DoH proxy
+
+DoH is great, but most devices use DNS-over-UDP by default, and some can't even
+be configured otherwise.
+
+If you have your own private secure network, you can stop
+attackers from learning what websites you visit by using leng as
+a secure proxy:
+
+```mermaid
+
+graph TD
+    subgraph Secure Network
+        U("🧘 User") --> |"🔓 Insecure\nDNS-over-UDP"|L[Leng]
+    end
+    L --> |"🔒 Secure DoH"| Up[Upstream DNS]
+    A("👿 Attacker") ---> |Cannot see contents\nof DNS requests | Up
+```
+
+This way you allow 'insecure' DNS, but only inside your network,
+and your requests are private to external attackers.
+
+No configuration is required for this: leng will always try
+to resolve domains by DoH via cloudflare before falling back to
+other methods. You can choose the upstream DoH resolver in the
+[Configuration](Configuration.md).
+
+> Note that this method is only as secure as your network is!
+> Ideally set up as many devices as possible to use DoH directly
+

doc/src/Docker.md

@@ -34,4 +34,4 @@ docker run -d \
 
 ```
 
-See [Configuratin](./Configuration.md) for the full config.
+See [Configuration](./Configuration.md) for the full config.

doc/src/Home.md

@@ -1 +1,28 @@
-Here are some useful guides and resources for working with leng. Contributions welcome!
+Here are some useful guides and resources for working with leng. Contributions welcome!
+
+
+# Why Leng
+
+Reasons you would want to use Leng include:
+- **Ad-blocking at the DNS level**: this compliments misses browser adblockers
+  (they use a different approach to block ads), and is especially useful in devices where
+  ad-blockers are hard to install (like smart TVs, or non-browser apps).
+- **Blocking tracking at the DNS level**: vendors, especially your
+device's manufacturers, will often track you outside of websites (where browser ad-blockers
+are powerless). When using the right blocklists, leng will block this
+tracking for all devices that use it as their DNS provider.
+- **DNS Server for self-hosted infra**: by specifying
+your records on a config file, leng is a very easily maintanable
+custom DNS server deployment.
+- **DNS Privacy and Security**: many devices use the most basic DNS implementation, DNS over UDP.
+This is a bad idea because it is less private and less secure ([you can read here
+to understand why](https://www.cloudflare.com/en-gb/learning/dns/dns-over-tls/)). Leng can serve as a secure
+proxy so that even if your devices speak to it via UDP, it speaks to the rest
+of the internet via the more secure alternatives (like DoH or DoT).
+- **It's small and fast**
+- **There are few open-source DNS servers with the above features**:
+my motivation for forking _grimd_ and creating leng was the need for a server
+that provided blocklists (like _Blocky_) as well as decent custom DNS records
+support (like _CoreDNS_, _grimd_ was almost there).
+
+For more on leveraging leng for DNS privacy, see [DNS Privacy](Privacy.md).

doc/src/Privacy.md

@@ -0,0 +1 @@
+# DNS Privacy

doc/src/SUMMARY.md

@@ -4,10 +4,12 @@
 
 # DNS
 
-- [DNS-over-HTTP](./DNS-over-HTTPS-(DoH).md)
-- [Custom DNS Records](Custom-DNS-Records.md)
-- [CNAME following](CNAME‐following-DNS.md)
-- [Blocking DNS](Blocking.md)
+- [DNS overview](DNS/DNS.md)
+- [DNS-over-HTTP](DNS/DNS-over-HTTPS-(DoH).md)
+- [Custom DNS Records](DNS/Custom-DNS-Records.md)
+- [CNAME following](DNS/CNAME‐following-DNS.md)
+- [Blocking DNS](DNS/Blocking.md)
+- [DNS Privacy](DNS/Privacy.md)
 
 # Administration
 

flake.nix

@@ -26,11 +26,18 @@
         # Dev environment
         ## use with `nix develop`
         devShells = rec {
+          # main development shell
           leng = with pkgs; mkShell {
             packages = [ fish go_1_21 mdbook ];
             # Note that `shellHook` still uses bash syntax. This starts fish, then exists the bash shell when fish exits.
             shellHook = "fish && exit";
           };
+
+          # shell with dependencies to build docs only
+          ci-doc = with pkgs; mkShell {
+          packages = [ mdbook mdbook-mermaid ];
+          };
+
           default = leng;
         };