Files
dawnline/rules/code-standards.md
T
Aemeath 29b1d7dfd7
Build packages / Version (push) Waiting to run
Dawnline 0.4.2
- Connections show up at once: the agent looks at the tunnels every
  second and, the moment a device connects or roams, writes it to the
  activity log, updates traffic and the map, and locates the new address
- A device counts as gone when its WireGuard session expires (1-3 min
  after it leaves), so a phone asleep no longer flaps between
  disconnect and connect
- The admin pages follow along within seconds: Overview, People, the
  person page and the device panel refresh when something happens, with
  a light check every 2 s instead of reloading everything every 10 s
- The personal portal no longer refreshes itself in the background:
  every request costs the router a CGI process, so it loads once and
  after the visitor's own changes
- Agent guidance and code standards (backend, frontend, shell, UI) now
  live in the repository: AGENTS.md and rules/
2026-10-16 03:52:21 +03:00

3.8 KiB
Raw Permalink Blame History

Code standards

How code in our own projects (Dawnline first, the same spirit for Tachyon, liminal and the rest) is written. This file holds what applies everywhere; per area:

  • backend.md — ucode on the router: layers, conventions, what things cost there.
  • frontend.md — TypeScript admin UI and portal: layout, live data.
  • shell.md — install, uninstall, init and CI scripts.
  • ui-design.md — how anything visible looks and how it gets approved.

Match the code around you: its naming, comment density and idiom win over personal taste.

Decomposition

  • One module, one job, named after it. A file you cannot describe in one sentence is two files. Starting points: ~300–400 lines for a ucode/TS module, ~60 lines for a function. Past that, split by responsibility, not by line count.
  • Every module opens with a header comment: what it owns, what it deliberately does not (and where that lives), and any invariant callers rely on (locks, files it writes, who may call it).
  • Layers point one way. Pure helpers and the data model know nothing about the router or the UI; orchestration calls them, never the reverse. Dawnline's layers are in backend.md.
  • No god files, no grab-bag ops/misc/kit modules. When a helper is used by one module, it stays private in that module.
  • Delete, don't deprecate. When something is replaced, move every caller and remove the old code in the same change; no shims, no commented-out blocks.

Logic and state

  • Validate at the boundary, trust inside. RPC, portal, CLI and file input are checked once (types, ranges, ids, regexes anchored with ^…$, length caps); inner code assumes valid data. Never build a shell command from unchecked input — quote with q() and prefer argument whitelists.
  • One writer per resource, under a lock. Config changes go through store.transact() (load the model inside the lock, change, commit, chmod 600). Router state changes go through apply under the apply lock. Long jobs (updates) hold a flock; "is it running" comes from the lock, never from a pid file. Do not nest locks.
  • Reconcile, don't patch. Derive router state from config and converge (idempotent: running twice changes nothing). Touch only objects you own (tagged/named dawnline), never foreign interfaces, zones or rules.
  • Fail closed. If a filter or nft load fails, access stays blocked, not open. A missing dependency (no AmneziaWG, no curl, no openssl) is a reported state with a fix, never a crash: check capabilities (awg.state(), health.needs()) and gate the feature in the backend and the UI.
  • Atomic files. Write JSON/state to a temp file and rename; keep runtime counters in tmpfs (RUN_DIR) and flush to flash (DATA_DIR) rarely.
  • Trust and downloads. APIs only directly over TLS; files may come from mirrors only when their sha256 is known from the API, and every attempt is verified. No hash → direct only, or refuse.
  • Side effects at the end. Collect restarts (network, uhttpd, re-apply) and run them once after the job, so a failure halfway never leaves half-restarted services.
  • Errors say what to do. die() / thrown messages are shown to the admin: a full sentence with the cause and, where possible, the fix. Never swallow an error silently; a catch either handles it or logs why it is ignored.
  • Time and dates come from the router (localtime, util.today()), not from the browser.

Comments, names, commits

  • Comments explain why and the contract, not what the next line does. English in code and UI copy.
  • Names say what the thing is in the product's words (people, devices, servers, circles), not implementation words.
  • Commits are reviewable pieces (one area or concern each), message says what changed and why; no push without the user's go-ahead.