- 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/
This commit is contained in:
1 parent
6444722d14
commit
29b1d7dfd7
26 files changed
+419
-104
No files matched your search
@@ -0,0 +1,30 @@
|
||||
# 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/check-ucode.sh` (compiles on the router) pass before any deploy; new directories and entry points are added to both, and executables to the mode check in `.github/workflows/ci.yml`.
|
||||
@@ -0,0 +1,36 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,19 @@
|
||||
# Frontend (TypeScript: admin UI and portal)
|
||||
|
||||
Read with `code-standards.md` and, for anything visible, `ui-design.md`.
|
||||
|
||||
## Code
|
||||
|
||||
- Strict TS, no `any` without a comment; types for RPC answers live in `shared/types.ts` / `admin/api.ts` and mirror the backend's shapes.
|
||||
- Layout of `web/src/admin`: `ui/` generic components (button, menu, modal, drawer, tooltip, toast, controls), `widgets/` composite house widgets, `state/` polling and scoping, `events/` the activity vocabulary (model without DOM, render separate), `updater/` the Components data layer, `cores/` per-protocol bits, `pages/<page>/` one folder per page split by section, `styles/*.css` one file per feature joined in `styles/index.ts`. Shared with the portal: `src/shared/`.
|
||||
- Pages build from `ui/` and `widgets/`; a page never defines a generic component. Logic that does not touch the DOM (formatting, models, CSV, sorting) lives outside the render code and gets tests.
|
||||
|
||||
## Live data
|
||||
|
||||
- Admin pages use `createPoller` (`state/poller.ts`): newest answer wins, no repaint of a region that holds focus, every RPC failure shows a toast or an inline error, never a blank section.
|
||||
- Changes reach open pages through the revision (`state/live.ts`): one small `rev` call every 2 s while the page is visible; pollers that opt in (`live: true`) refresh when it moves. Their own `every` stays as a slow fallback.
|
||||
- The portal does not poll (each request is a CGI process on the router, see `backend.md`): it loads once, after the visitor's own changes, and while it waits for a new device's first connection.
|
||||
|
||||
## Checks
|
||||
|
||||
- In `web/`: `npm run format:check`, `npm run typecheck`, `npm test`, `npm run build`; the rebuilt bundles under `package/` are committed (CI fails otherwise).
|
||||
@@ -0,0 +1,7 @@
|
||||
# Shell (install, uninstall, init, CI)
|
||||
|
||||
Read with `code-standards.md`. Anything run on the router by hand follows the workspace's `../rules/router-shell.md` (a literal stdin heredoc over SSH).
|
||||
|
||||
- POSIX `sh` (BusyBox ash), `set -eu` where the script allows; quote every expansion; `shellcheck -S warning` clean (CI runs it).
|
||||
- Every mutating script has a `--dry-run` that prints what it would do; uninstall removes everything install created (cron, nft, firewall, routing, packages it added, files) and nothing else — including what older versions created (e.g. the priority-90 reply rules up to 0.4.0).
|
||||
- BusyBox lacks GNU options (`ls -e`, `pkill`, `time` on shell functions): check on the router before relying on a flag.
|
||||
@@ -0,0 +1,32 @@
|
||||
# UI design (Dawnline admin, portal and other panels)
|
||||
|
||||
The bar is a modern product UI (Linear / Vercel / Raycast level), not a "native" LuCI form. A plain label + input row, a bare radio list, three columns of check marks or a text dump is a first draft, never the result.
|
||||
|
||||
## Approach
|
||||
|
||||
- **Mock first.** Any visible change beyond a one-line fix: show a mockup (2–4 genuinely different options when the direction is open) with a recommendation, then build the chosen one. Do not start coding a layout the user has not seen.
|
||||
- **Think past the obvious.** When an option is rejected as "not it", propose new concepts, not variations of the same layout.
|
||||
- **Structure over text.** Tiles, segmented controls, pills, round icon buttons, inline status, folded "Advanced" sections. Summaries first ("All 6 checks passed"), details on demand.
|
||||
- **No duplication.** One place per fact (usage, device count, links). Remove what is repeated elsewhere on the page.
|
||||
- **Reuse the house patterns** before inventing new ones: `dl-params` folded details with a rotating chevron, `dl-tile2` tiles, round icon buttons with tooltips, `⋯` menus (destructive and Pause inside, Pause in warn colour, "Delete" without an ellipsis), bottom toasts instead of LuCI banners, the same tiles on server and person pages.
|
||||
- **Alignment and spacing are part of the design.** Shared margins and edges, equal heights in a row, controls pinned consistently (top, not centred, when the user says so), nothing clipped or overflowing, single-line labels where they fit.
|
||||
- **No ellipsis on buttons or menu items** ("Remove", not "Remove…"), even when they open a dialog. "…" only for progress ("Loading…") and truncated values.
|
||||
- **Colour means something:** ok = green, warn/pause = orange, danger = red, accent = blue. Icons for states instead of words where obvious.
|
||||
- **Honest warnings** belong in the UI (e.g. plain HTTP, Cloudflare throttling), shown where the choice is made.
|
||||
|
||||
## Mocks look like the real product
|
||||
|
||||
A mock is judged against the page it will live on, so it must already look like it. Hand-drawn look-alikes with invented styles get rejected ("выбивается из дизайна").
|
||||
|
||||
- **Study the existing pages first** (the section being changed and its neighbours) and build only from their components: `dl-setsec` cards with `dl-setsec-foot`, `dl-setrow` rows with a `dl-need-ic` icon tile and `dl-switch`, `dl-seg` (`sm`, `wide`), `dl-chip` / `dl-chipbtn`, `dl-list` + `dl-row`, `dl-table`, `dl-checks` (the Health check list), `dl-tile2` tiles, `dl-panel`. A new class only when nothing fits, and then in the same tokens (`--dl-*`).
|
||||
- **Buttons are `cbi-button`**: actions like Edit, Change, Rescan are `neutral` pills (as "Edit in Settings", "+ Add device"); Save and Install are `positive`. No blue text links for actions.
|
||||
- **Show only what changes.** Do not add existing, unrelated controls (e.g. Devices or Access ends tiles) to a mock; say in the caption that the rest of the page stays.
|
||||
- **Build it from the real code and CSS**, not from a copy:
|
||||
- theme: `scp root@outline.lan:/www/luci-static/outline/{main.css,geist-*.woff2}` into the mock folder, strip `/luci-static/outline/` from the font URLs, `<html data-darkmode="true">`;
|
||||
- Dawnline CSS: the files in `web/src/admin/styles/*.css` concatenated in the order of `styles/index.ts` into `dl.css`;
|
||||
- markup: a small `mock.ts` that imports the real `admin/e`, `shared/icons`, `admin/ui/*` and `admin/widgets/*` (stub the LuCI globals `window.E`, `dom.content`, `L.url`), bundled with `web/node_modules/.bin/esbuild --bundle --format=iife`.
|
||||
- Keep mocks outside the product repo, serve them with `python3 -m http.server` started from Bash (the preview server cannot read `~/Documents` on macOS), open them in the built-in browser, and delete the folder when the feature ships.
|
||||
|
||||
## Done means seen
|
||||
|
||||
Deploy, then look at it in the browser (desktop width, and narrow when layout changes) before reporting. Check modals and drawers stack correctly and long values do not overflow.
|
||||
Reference in new issue
Block a user