Files
dawnline/scripts/lint-ucode.py
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

167 lines
7.8 KiB
Python
Executable File

#!/usr/bin/env python3
"""Static checks for the ucode sources that need no router.
ucode resolves names where they are used: calling a function that is declared
further down the same file fails at runtime ("access to undeclared variable").
Also: calls and named imports must match what a Dawnline module exports, the
rpcd methods (dawnline.rpc.*) must match the plugin and its ACL, and regexes
stay POSIX (rules/backend.md). Imports against the module layering are
reported as notes, not failures.
Run: scripts/lint-ucode.py [package root]
"""
import glob
import json
import os
import re
import sys
root = sys.argv[1] if len(sys.argv) > 1 else os.path.join(os.path.dirname(__file__), '..', 'package', 'luci-app-dawnline', 'root')
MODDIR = f"{root}/usr/share/ucode/dawnline"
PLUGIN = f"{root}/usr/share/rpcd/ucode/luci.dawnline"
ACL = f"{root}/usr/share/rpcd/acl.d/luci-app-dawnline.json"
modules = sorted(glob.glob(f"{MODDIR}/*.uc") + glob.glob(f"{MODDIR}/rpc/*.uc"))
files = modules + [
PLUGIN,
f"{root}/usr/libexec/dawnline/agent",
f"{root}/usr/libexec/dawnline/updater",
f"{root}/usr/bin/dawnline",
f"{root}/usr/share/dawnline/portal/cgi.uc",
]
files = [f for f in files if os.path.exists(f)]
bad = 0
def problem(msg):
global bad
print(msg)
bad = 1
def strip_comments(text):
return re.sub(r'//[^\n]*|/\*.*?\*/', '', text, flags=re.S)
def blank_comments(text):
"""Comments replaced by their newlines: line numbers stay, their text goes."""
return re.sub(r'//[^\n]*|/\*.*?\*/', lambda m: '\n' * m.group(0).count('\n'), text, flags=re.S)
# A regex literal on one line: `/…/` with no slash inside, followed by flags or
# a delimiter (so a division keeps out). Good enough for how Dawnline writes them.
REGEX_LITERAL = re.compile(r'(?<![\w)\]])/((?:\\.|[^/\\\n])+)/[gis]*(?=[,);\s])')
def modname(path):
"""dawnline/rpc/people.uc → 'rpc.people' (as in import … from 'dawnline.rpc.people')."""
rel = os.path.relpath(path, MODDIR)[:-3]
return rel.replace(os.sep, '.')
for f in files:
code = strip_comments(open(f, encoding='utf-8').read())
defs = {m.group(1): m.start() for m in re.finditer(r'^(?:export )?function (\w+)\(', code, re.M)}
for name, pos in defs.items():
for m in re.finditer(r'(?<![\w.\'"`])' + name + r'\(', code[:pos]):
line = code[: m.start()].count('\n') + 1
problem(f"{f}:{line}: {name}() is used before its definition")
# In a module an exported function is an expression statement: its closing
# brace needs a semicolon ("Expecting ';'" breaks the whole module).
lines = blank_comments(open(f, encoding='utf-8').read()).split('\n')
inside = None
for n, text in enumerate(lines, 1):
if inside is None and re.match(r'^export function \w+\(', text):
inside = n
elif inside is not None and re.match(r'^}', text):
if not text.startswith('};'):
problem(f"{f}:{n}: exported function from line {inside} must end with '}};'")
inside = None
# ucode regexes are POSIX: a (?: group fails when the line runs ("Repetition
# not preceded by valid expression"), and let [a, b] = … does not compile.
if re.search(r'/[^/\n]*\(\?[:=!][^/\n]*/', text):
problem(f"{f}:{n}: ucode regexes are POSIX: no (?: (?= (?! groups")
# Lazy quantifiers (*? +? }?) and the [\s\S] class are PCRE: the C
# library's regcomp does something else with them or rejects them.
for m in REGEX_LITERAL.finditer(text):
body = m.group(1)
if re.search(r'(?<!\\)[*+}]\?', body):
problem(f"{f}:{n}: ucode regexes are POSIX: no lazy quantifiers (*? +? }}?) in /{body}/")
if re.search(r'\[\\[sS]\\[sS]\]', body):
problem(f"{f}:{n}: ucode regexes are POSIX: no [\\s\\S] class in /{body}/ (use (.|\\n) or a negated class)")
if re.match(r'\s*(let|const)\s*[\[{]', text):
problem(f"{f}:{n}: ucode has no destructuring")
# Calls into another Dawnline module (alias.fn(...)) and named imports must name
# something it exports: one removed from a module but still used elsewhere only
# fails at runtime.
exports = {}
for f in modules:
text = open(f, encoding='utf-8').read()
exports[modname(f)] = set(re.findall(r'^export (?:function|const|let) (\w+)', text, re.M))
for f in files:
code = strip_comments(open(f, encoding='utf-8').read())
for alias, mod in re.findall(r"import \* as (\w+) from 'dawnline\.([\w.]+)'", code):
if mod not in exports:
problem(f"{f}: imports dawnline.{mod}, which does not exist")
continue
# Calls, and constants (upper case: a lower-case "geo.json" in a string is no access).
for m in re.finditer(r'(?<![\w.])' + alias + r'\.(\w+\(|[A-Z][A-Z0-9_]*\b)', code):
name = m.group(1).rstrip('(')
if name not in exports[mod]:
line = code[: m.start()].count('\n') + 1
problem(f"{f}:{line}: {alias}.{name} is not exported by dawnline.{mod}")
for names, mod in re.findall(r"import \{([^}]*)\} from 'dawnline\.([\w.]+)'", code):
if mod not in exports:
problem(f"{f}: imports dawnline.{mod}, which does not exist")
continue
for name in re.split(r'\s*,\s*', names.strip()):
name = re.split(r'\s+as\s+', name)[0].strip()
if name and name not in exports[mod]:
problem(f"{f}: {name} is not exported by dawnline.{mod}")
# rpcd methods: every rpc module's `methods` is merged by the plugin, no name is
# defined twice (the later one would silently win), and the ACL's read list
# names methods that exist.
methods = {}
for f in glob.glob(f"{MODDIR}/rpc/*.uc"):
text = strip_comments(open(f, encoding='utf-8').read())
m = re.search(r'^export const methods = \{\n(.*?)^\};', text, re.M | re.S)
if not m:
continue
mod = modname(f)
if os.path.exists(PLUGIN) and f"from 'dawnline.{mod}'" not in open(PLUGIN, encoding='utf-8').read():
problem(f"{PLUGIN}: does not import dawnline.{mod}, whose methods would be missing")
for name in re.findall(r"^\t'?(\w+)'?: \{", m.group(1), re.M):
if name in methods:
problem(f"{f}: method {name} is also defined in dawnline.{methods[name]}")
methods[name] = mod
if methods and os.path.exists(ACL):
acl = json.load(open(ACL, encoding='utf-8'))['luci-app-dawnline']
for kind in ('read', 'write'):
for name in acl.get(kind, {}).get('ubus', {}).get('luci.dawnline', []):
if name != '*' and name not in methods:
problem(f"{ACL}: {kind} lists {name}, which no dawnline.rpc module defines")
if 'uci' in acl.get(kind, {}) and 'dawnline' in acl[kind]['uci']:
problem(f"{ACL}: {kind} grants uci 'dawnline' (private keys, no validation): use the rpc methods")
# Layering (rules/backend.md): util, schema → core → store → domain modules →
# apply → entry points. A module importing one from a layer above it is
# reported, not failed, until the existing edges are untangled.
LAYER = {'util': 0, 'schema': 1, 'core': 2, 'store': 3, 'apply': 5}
LAYER_NAME = {0: 'util', 1: 'schema', 2: 'core', 3: 'store', 4: 'domain', 5: 'apply'}
notes = 0
for f in modules:
mod = modname(f)
if mod.startswith('rpc.'):
continue # an entry point: may import anything
mine = LAYER.get(mod, 4)
for dep in re.findall(r"from 'dawnline\.([\w.]+)'", strip_comments(open(f, encoding='utf-8').read())):
theirs = LAYER.get(dep, 4)
if theirs > mine or (theirs == mine and mine < 4 and dep != mod):
print(f"note: {f}: {mod} ({LAYER_NAME[mine]}) imports dawnline.{dep} ({LAYER_NAME[theirs]}), a layer above it")
notes += 1
if notes:
print(f"lint-ucode: {notes} layering notes (not failures)")
print(f"lint-ucode: {len(files)} files checked" + (", problems found" if bad else ", ok"))
sys.exit(bad)