Files
dawnline/rules/backend.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

3.2 KiB
Raw Blame History

Backend (ucode on the router)

Read with code-standards.md. Everything here runs on a small router (2 × Cortex-A53 on the reference Cudy WR3000P): cost is part of correctness.

Layers

  • util, schema (validation) → core (model, allocation) → store (the only writer of /etc/config/dawnline) → domain modules (net, nft, fw, netifd, awg, loop, resolver, live, health, backup, …) → apply (reconciliation) → entry points (rpc/*, portal, the dawnline CLI, the agent, the updater).
  • Read models for the UI live in view; RPC modules translate arguments and call down, they hold no business logic.
  • The updater is a thin dispatcher over upd_app / upd_awg / upd_pkgs, with GitHub in github, the package manager in pkg, policy/locks/history in updates.
  • Live state: the agent's watcher owns who is online (live.PRESENCE); readers ask live.online(), never re-derive it from handshake ages. Online means the WireGuard session lives (live.ONLINE_WINDOW): traffic silence is no signal, a phone asleep is silent too.

ucode

  • 'use strict' in entry points; modules import { … } from 'fs' / 'dawnline.x'. Subdirectories map to dots (dawnline.rpc.status → dawnline/rpc/status.uc).
  • Exported functions end with }; (the compiler requires it). No destructuring. Regexes are POSIX (no (?:), \s\S classes, lazy quantifiers); anchor them.
  • Modules with export cannot be loaded with require(): imports are static and compiled on every start of the script.
  • Doc comments (/** … */) on every export: what it returns, including the null/empty case.
  • Shell out through one small helper per module (run()/sh()), with 2>&1 captured and the exit code checked.
  • nft changes load as one script (nft.load(), a transaction); tables Dawnline owns are named dawnline* and rebuilt whole (table X + delete table X + the table).

Cost on the router

  • The portal is CGI: every request starts ucode and compiles the module graph, about 140 ms of CPU before any work (a full state answer about 180 ms). No periodic polling from the portal; one request per user action.
  • rpcd keeps the admin backend loaded: LuCI RPC calls are cheap, so the admin UI may poll small methods often (rev), and the heavy ones (status) only on change or rarely.
  • Code on the agent's 1-second watcher stays in the low milliseconds: one awg show all dump (about 4 ms with process start), the model cached by the config file's mtime/inode (core.load() is about 4 ms), files written only when something changed. Slow work (geo lookups, apply) runs only on a transition.
  • Measure before and after on the router (a loop of 20–200 calls, /proc/self/stat CPU ticks, system busy from /proc/stat) when adding anything periodic.

Checks

  • scripts/lint-ucode.py and scripts/ucode-container.sh (compiles and runs tests/ucode in the OpenWrt rootfs containers; scripts/check-ucode.sh compiles on the router instead) pass before any deploy; new directories and entry points are added to lint-ucode.py and scripts/compile-ucode.sh, and executables to the mode check in .github/workflows/ci.yml.
  • Pure functions get a case in tests/ucode/<module>.test.uc; what reads the clock takes an optional ts so a test can pass one.