feat(templates): caddy-proxy puts a Moshpit name in front of a local service

Author: ralyodio

examples/templates/caddy-proxy/Caddyfile

@@ -0,0 +1,36 @@
+# Caddy in front of a service already running on this box, published at a
+# Moshpit name.
+#
+# The `http://` is required and is not a style choice. A Moshpit ending is not
+# in the public DNS root, so no certificate authority will issue for it — leave
+# the scheme off and Caddy will try to provision a certificate, fail, and never
+# bring the site up. Everything served at a Moshpit name is plain HTTP.
+#
+# Nothing here resolves the name. The visitor's resolver did that; by the time a
+# request arrives Caddy has only a Host header to match on, which is why the
+# site address must be the name exactly as it is registered.
+
+http://{$MOSHPIT_NAME:foo.whatever} {
+	reverse_proxy {$APP_ADDR:127.0.0.1:8080}
+
+	log {
+		output file /var/log/caddy/moshpit-service.log
+	}
+}
+
+# Every subdomain too. This block answers only once the name publishes a
+# wildcard record — DNS Records tab in the Pit, the `*.` option with an AAAA
+# at this box — because until then `anything.foo.whatever` resolves to nothing
+# and no request reaches Caddy to match. Uncomment both together.
+#
+# The app sees which subdomain was asked for in the Host header, and Caddy
+# matches exactly one label deep: `api.foo.whatever` answers,
+# `a.b.foo.whatever` does not.
+#
+# http://*.{$MOSHPIT_NAME:foo.whatever} {
+# 	reverse_proxy {$APP_ADDR:127.0.0.1:8080}
+#
+# 	log {
+# 		output file /var/log/caddy/moshpit-service.log
+# 	}
+# }

examples/templates/caddy-proxy/README.md

@@ -0,0 +1,104 @@
+# caddy-proxy
+
+A name in front of something that is already running. No app, no database, no
+runtime to keep alive — Caddy answers the Moshpit name and hands every request
+to a local service on `127.0.0.1:8080` (or wherever `APP_ADDR` says).
+
+This is the template for "I have a thing on this box, put a name on it": a
+dev server, a dashboard, grafana, a game panel, anything that already listens
+on loopback.
+
+## The part that surprises people
+
+Three machines' worth of concerns, and they fail independently:
+
+| | needs the resolver? | what it does |
+|---|---|---|
+| the box serving the name | **no** | Caddy matches a `Host` header, nothing more |
+| the registry | — | holds the address the name points at |
+| every visitor | **yes** | `sudo moshcode dns enable`, or the name resolves to nothing |
+
+Nothing on the server ever resolves its own name. That is why there is no DNS
+software in this template.
+
+## Deploying
+
+1. **Point the name at the box.** In the Pit, set `points at` to its public
+   IPv6 address — bare, no scheme, no brackets, no port:
+
+   ```sh
+   ip -6 addr show scope global | grep inet6
+   ```
+
+   Pick the globally routable one. An `fd..`/`fc..` address is unique-local
+   (Tailscale and friends live there) and the registry refuses it, because a
+   name pointed at one resolves somewhere only you can reach.
+
+2. **Serve it.** The service stays bound to loopback — Caddy is its only
+   client, and binding it publicly publishes it on a port nothing
+   virtual-hosts.
+
+   ```sh
+   export MOSHPIT_NAME=foo.whatever
+   export APP_ADDR=127.0.0.1:8080   # the default; change only if the service differs
+   sudo cp Caddyfile /etc/caddy/Caddyfile
+   sudo systemctl reload caddy
+   sudo ufw allow 80/tcp
+   ```
+
+3. **Reach it,** on any machine that should see the name:
+
+   ```sh
+   sudo moshcode dns enable
+   sudo cp deploy/moshcode-dns.service /etc/systemd/system/   # survives reboot
+   sudo systemctl enable --now moshcode-dns
+   ```
+
+## Every subdomain at once
+
+One name covers one hostname. To answer `anything.foo.whatever` too — one
+service per subdomain, or a wildcard tenant app — do both halves, in either
+order, because neither works without the other:
+
+1. In the Pit's **DNS Records** tab, publish an **AAAA** record on the
+   `*.foo.whatever` option pointing at the same box. Until that exists the
+   subdomains resolve to nothing and no request ever reaches Caddy.
+2. Uncomment the wildcard block at the bottom of the Caddyfile and reload.
+   Caddy matches exactly one label deep, and the app reads which subdomain was
+   asked for from the `Host` header.
+
+`foo.whatever` itself is not covered by a wildcard — keep the apex block (and
+its own AAAA or `points at`) for that. This is how DNS wildcards work, not a
+choice Caddy made.
+
+## Verifying, one layer at a time
+
+A failure at any layer looks identical in a browser, so do not start there.
+
+```sh
+# Server only — no DNS involved. Proves Caddy, the firewall, and the service.
+curl -6 -H "Host: foo.whatever" http://[YOUR:V6:ADDR]/
+
+# Resolver only. Proves the registry and the bridge.
+moshcode dns resolve foo.whatever
+
+# Both.
+curl -6 http://foo.whatever/
+```
+
+If the first works and the last does not, it is DNS. If the first fails, stop
+looking at DNS.
+
+## Known limits
+
+- **No HTTPS, ever.** No CA will issue for an ending outside the DNS root. That
+  rules out secure cookies, service workers, and WebCrypto in the browser. The
+  `http://` in the Caddyfile is what stops Caddy trying and failing.
+- **Only machines running the resolver can reach the name.** Not phones, not a
+  colleague who has not installed it, not webhooks.
+  `pit.moshcode.sh/n/foo.whatever` is the URL for people who installed nothing.
+- **Subdomains are opt-in.** `foo.whatever` works out of the box;
+  `www.foo.whatever` works only with the wildcard record described above.
+- **Port 80 only** on the resolver path. A DNS record carries an address and
+  has nowhere to put a port, which is why Caddy listens on 80 and the
+  `host:port` part lives here, not in the registry.

examples/templates/caddy-proxy/deploy/moshcode-dns.service

@@ -0,0 +1,39 @@
+# The Moshpit resolver, kept running across reboots.
+#
+# `moshcode dns enable` sets up two halves: a systemd-resolved drop-in that
+# routes Moshpit endings at the bridge, and the bridge process itself. The
+# drop-in is a file and survives a reboot on its own. The process does not —
+# so after a restart the routing still points at a port with nothing behind it,
+# and every Moshpit name stops resolving with no obvious cause. This unit is
+# the missing half.
+#
+#   sudo cp deploy/moshcode-dns.service /etc/systemd/system/
+#   sudo systemctl enable --now moshcode-dns
+#
+# Install this on machines that need to REACH Moshpit names. A box that only
+# serves one does not need it — Caddy answers whatever Host header arrives and
+# never resolves its own name.
+
+[Unit]
+Description=Moshpit DNS bridge
+After=network-online.target
+Wants=network-online.target
+Before=systemd-resolved.service
+
+[Service]
+Type=simple
+# Port 5354 is unprivileged, so this does not need root. The trade-off is that
+# the parking responder cannot take port 80 and falls back to the public
+# parking address — which only affects names that point nowhere yet.
+ExecStart=/usr/bin/env moshcode dns start --port 5354
+Restart=always
+RestartSec=2
+
+DynamicUser=yes
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+
+[Install]
+WantedBy=multi-user.target

examples/templates/caddy-proxy/template.json

@@ -0,0 +1,8 @@
+{
+  "name": "caddy-proxy",
+  "description": "Caddy proxying a Moshpit name to a service already running on the box — no app, no database, just the name in front",
+  "vars": {
+    "MOSHPIT_NAME": "the registered name to serve, e.g. foo.whatever",
+    "APP_ADDR": "where the local service listens, loopback only (default 127.0.0.1:8080)"
+  }
+}