- Access rules fail closed: when the table cannot load, no device is loaded into the tunnels (the firewall alone would let every loaded device reach everything); an older table that survived a failed rebuild keeps its rules and a revoked device still leaves. The agent re-syncs within a minute when the table is gone - A change the router saved but could not put into effect (access rules that did not load, a server that refused its devices) is said in the admin UI instead of a plain "Saved" - The guard judges every packet, not only a connection's first: a change of access, a pause or a limit now cuts open connections too - Each server's home networks are its own: with several servers, "all home" on one no longer reaches the other's networks where firewall zones overlap - People limited to some home networks reach the router only on the addresses in those networks (LuCI and SSH on the main LAN stay closed) - Internet-only people can open their personal portal with the VPN on - Tunnel DNS reaches the resolver and the LAN's DNS from servers that do not forward to those zones on their own (Home-only names on servers without "like a home device", LAN DNS on servers with no home network) - A new personal link offers to remove the devices added through the old one, so a leaked link is really contained - Import and restore refuse an inconsistent file (devices with addresses outside their server, shared addresses, malformed keys, broken references); Health reports one, and the sync leaves such a device out instead of failing its server. A config write that did not reach flash is an error, not a silent success - Backups are kept per kind (nightly ones no longer push out manual or pre-delete ones), nightly and pre-change backups hold the config only, archives are written whole or not at all, and a failed nightly backup is logged. A restore no longer has its history overwritten by the agent's in-memory counters - Settings defaults and ranges come from one place (dawnline.schema) - Portal: anything not shaped like a personal link is answered by a shell before ucode starts (a scan on the root costs nothing); 4 portal processes at once instead of 16; a link may make 40 changes a quarter hour; over plain HTTP the page shows but configurations, new devices and new keys are refused with the HTTPS twin of the link; the connect sheet polls only while the first connection is awaited, with backoff, and stops once the link stopped working - Updates: after Dawnline's own package changes, a shell checks that LuCI reaches it and the agent runs, and puts the kept previous version back when they do not (automatic runs always keep it); the AmneziaWG module reload verifies rmmod and modprobe; installs check free space; on apk a reinstall that changed nothing is an error; uninstall.sh hands the update lock to the removal it calls; an upgrade restarts the service only where it was enabled; the release workflow pins the SDK images by digest and the actions by commit - AmneziaWG: features count only when both the tools and the kernel module have them; a server whose disguise this build cannot run (a 3.1 preset after a rollback to 2.0) is kept down and reported; Components tells 1.0 builds from 2.0 ones; `awg show dump` is parsed by shape; Maximum's DNS-shaped signature packets are made for each server and its keep-alive is a 25-35 s range - CI compiles every ucode file and runs the new tests/ucode unit tests (54 tests on the real libuci) in OpenWrt 24.10 and 25.12 rootfs containers; scripts/compile-ucode.sh does the same wherever ucode runs and scripts/ucode-container.sh locally with docker; lint-ucode checks POSIX regexes and module layering; a tag builds only after CI passes
4.0 KiB
4.0 KiB
AGENTS.md — Dawnline
Guidance for coding agents working in this repository (tickcount/luci-app-dawnline): an AmneziaWG access server for OpenWrt with a LuCI admin UI and a personal portal. CLAUDE.md points here.
Rules
rules/code-standards.md— how all code is written: decomposition, one locked writer, fail closed, validation at the boundary, comments and commits.rules/backend.md— ucode on the router: module layers, conventions, what things cost there (CGI portal, rpcd, the agent's watcher).rules/frontend.md— TypeScript admin UI and portal: layout ofweb/src, pollers and the live revision.rules/shell.md— install, uninstall, init and CI scripts.rules/ui-design.md— how the admin UI and the portal look: modern product quality, mock first from the real CSS and components, verified in the browser.
This repo usually sits inside the router-admin workspace (../AGENTS.md). Its rules apply to anything that touches the router: read-only first, backup before mutating, router shell as a literal stdin heredoc over SSH (../rules/).
Layout
package/luci-app-dawnline/root/— what lands on the router: ucode modules inusr/share/ucode/dawnline/(rpc/for the LuCI backend), the agent and updater inusr/libexec/dawnline/, the portal inusr/share/dawnline/portal/, the init script, rpcd ACL.web/— TypeScript sources of the admin UI (src/admin) and the portal (src/portal), shared code insrc/shared; the built bundles are committed underpackage/.install.sh,uninstall.sh— the standalone installer and uninstaller (both have--dry-run).scripts/—lint-ucode.py,compile-ucode.sh(compiles every ucode file of a tree wherever ucode runs),check-ucode.sh(the same on the router, without installing),ucode-container.sh(compile and unit tests in the OpenWrt rootfs containers CI uses),deploy.sh(dev deploy over SSH),build-packages.sh,build-release.sh,release-notes.sh.tests/ucode/— unit tests of the ucode modules (run.ucruns every*.test.uc; fixtures for/etc/configand a stand-inawg), run in a container byrun.sh.
Checks before a commit or deploy
python3 scripts/lint-ucode.py(use before definition, exports, POSIX regexes, rpcd methods; layering notes are informational).scripts/ucode-container.sh(needs docker): compiles every ucode file and runstests/ucodeon OpenWrt 24.10 and 25.12, exactly what CI does.scripts/check-ucode.shcompiles on the router instead when there is no docker. New ucode entry points are added to the compile list inscripts/compile-ucode.sh, tolint-ucode.py, and to the executables list in.github/workflows/ci.yml; a pure function gets a case intests/ucode/<module>.test.uc.- In
web/:npm run format:check,npm run typecheck(sources and tests),npm test,npm run build— and commit the rebuilt bundles (CI fails on a changed or new file underpackage/). shellcheck -S warningfor the shell scripts (CI finds them by shebang).- A tag builds only after CI passes on it (
build.ymlcallsci.yml).
Releases
- A release is one commit on
maintitledDawnline X.Y.Z; its body is-points, which become the GitHub release notes and the Components "What's new". Work from a branch is squashed into that one commit. - Bump the version in
package/luci-app-dawnline/Makefile(PKG_VERSION),util.uc(VERSION),web/package.jsonandweb/package-lock.json(CI checks they agree). - No
Co-Authored-Byor other agent attribution in commits. - Push
main, then an annotated tagvX.Y.Z("Dawnline X.Y.Z"); the "Build packages" workflow publishes the.ipk,.apkandsha256sums.txt. - Re-cutting a release (fixes before anyone installs) rewrites
main: force-push,gh release delete vX.Y.Z --cleanup-tag, cancel a running build of the old tag, tag again. Only with the user's go-ahead. - On the router, install a release the way Components does:
/usr/libexec/dawnline/updater install app@vX.Y.Z(verified against the release's sha256).