Files
dawnline/AGENTS.md
T
Aemeath 31a2065f05 Dawnline 0.6.0
- 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
2026-10-18 15:32:27 +03:00

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 of web/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 in usr/share/ucode/dawnline/ (rpc/ for the LuCI backend), the agent and updater in usr/libexec/dawnline/, the portal in usr/share/dawnline/portal/, the init script, rpcd ACL.
  • web/ — TypeScript sources of the admin UI (src/admin) and the portal (src/portal), shared code in src/shared; the built bundles are committed under package/.
  • 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.uc runs every *.test.uc; fixtures for /etc/config and a stand-in awg), run in a container by run.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 runs tests/ucode on OpenWrt 24.10 and 25.12, exactly what CI does. scripts/check-ucode.sh compiles on the router instead when there is no docker. New ucode entry points are added to the compile list in scripts/compile-ucode.sh, to lint-ucode.py, and to the executables list in .github/workflows/ci.yml; a pure function gets a case in tests/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 under package/).
  • shellcheck -S warning for the shell scripts (CI finds them by shebang).
  • A tag builds only after CI passes on it (build.yml calls ci.yml).

Releases

  • A release is one commit on main titled Dawnline 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.json and web/package-lock.json (CI checks they agree).
  • No Co-Authored-By or other agent attribution in commits.
  • Push main, then an annotated tag vX.Y.Z ("Dawnline X.Y.Z"); the "Build packages" workflow publishes the .ipk, .apk and sha256sums.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).