Files
dawnline/rules/code-standards.md
T
Aemeath 2f2aaf6c34
Build packages / CI (push) Blocked by required conditions
Build packages / Version (push) Waiting to run
CI / Web (format, types, tests, bundles) (push) Blocked by required conditions
CI / ShellCheck (push) Blocked by required conditions
CI / ucode static checks (push) Blocked by required conditions
CI / ucode compiles and tests pass (OpenWrt 24.10) (push) Blocked by required conditions
CI / ucode compiles and tests pass (OpenWrt 25.12) (push) Blocked by required conditions
Dawnline 0.11.0
- Russian translation. The admin pages, the LuCI menu and the router's
  messages (errors, Health checks, update steps, the service log) come in
  Russian with the new luci-i18n-dawnline-ru package, released beside the
  app. LuCI shows it when its language is Russian, or "auto" with a Russian
  browser
- The translation installs with install.sh when LuCI is in Russian (or with
  --lang ru), follows every Dawnline update and rollback, and can be added
  or removed in Components → Dawnline → Translation
- The portal speaks the visitor's language: it opens in the system's
  language and switches between English and Russian in place, from the
  language pill beside its QR code. It carries its own translation and needs
  no package
- Set-up steps quote the apps' own menus word for word, in Russian too:
  AmneziaVPN is "+ → Insert → Continue" (it has no "Add server"), and the
  Mac and Windows menus of WireGuard and AmneziaWG have their real names
- Questions in the portal (Reconnect, Remove) read from the left edge and
  close with Cancel, without ×
- Numbers, sizes and dates follow the page's language. A server that can't
  start says why in one sentence; event details and service log lines read
  as whole sentences
- README in Russian (README_ru.md). rules/i18n.md: how strings are written
  and translated; CI checks the catalogs (npm run i18n:check)
2026-10-20 19:33:52 +03:00

3.9 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. The same goes for its strings: new text is translated in the same change, removed text leaves the catalogs (i18n.md).

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.