KLALB/AGENTS.md

AGENTS.md

KLALB ("KLALB Decentralized SRv6 Network") — Java load-balancing/tunnel system that merges multiple WAN links into one virtual IPv6/SRv6 network. Version constant lives in src/org/kne/cloud/network/klalb/CONST.java. Protocol specs and manuals are the Chinese .docx files in the repo root.

Build & run

No Maven/Gradle. Plain Eclipse/IntelliJ project: dependencies are vendored jars in lib/, output goes to bin/ (gitignored). When adding a jar, update both .classpath and KLALB.iml.

Compile (verified; -encoding UTF-8 is mandatory — sources contain Chinese text):

& javac -encoding UTF-8 -cp "lib/*" -d bin (Get-ChildItem -Recurse src -Filter *.java | ForEach-Object FullName)

Run from the repo root — CWD matters:

• reads klalb-config.json from CWD
• loads native libs from CWD: tuntap4j.dll/.so/.dylib, wintun.dll, fastcopy.dll (TUN device support)
• classpath must include src as well as bin: i18n bundles (/klalb_*.properties) and images (/assets/*) are classpath resources that Eclipse copies to bin but manual javac does not

java --enable-native-access=ALL-UNNAMED "--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED" -cp "bin;src;lib/*" org.kne.cloud.network.klalb.KLALBMain

IDE metadata targets JDK 26 (jdk-26.0.1); the tree also compiles cleanly on JDK 25. .classpath now references the standard container JavaSE-25 — an execution-environment spec that any JDK ≥25 satisfies, so it works unchanged on JDK 26 machines too (the original named jdk-26.0.1 VM broke VS Code import on machines without it). .vscode/settings.json maps JavaSE-25 to the locally installed Adoptium JDK; register every installed JDK there when adding another one. Keep compiler compliance ≤25 (.settings pins 19) so both JDKs stay usable.

Runtime gotchas (all verified):

• On JDK 25, KNEOptimize.jar's FastLib reflects into jdk.internal.misc.Unsafe; without the two JVM flags above it throws InaccessibleObjectException at startup (app still runs).
• Creating the SRv6 TUN adapter (WintunCreateAdapter) requires an elevated shell; without admin rights it logs "创建虚拟网卡失败" and continues with only the inLoopBack interface — links/bridges still work.
• To disable TUN creation completely (e.g. for non-admin UI/routing testing), set "enableTUN": false in klalb-config.json or toggle off "启用 TUN 虚拟网卡" in GUI/Web settings.
• Routing broadcast (RouterInfo) transmits deviceName across the network, which topology and node overview panels display. deviceDescription and ExtraRoutes remain local controller configs.

Verification

No test suite, no CI. Classes named *Test* (nathole/, ntp/) are manual main() harnesses requiring real network peers. Practical check = compile succeeds + app launches.

Architecture

• Entrypoint org.kne.cloud.network.klalb.KLALBMain: load config → build KLALBProxySystem → open Swing GUI (KLALBStateGUI3) unless "nogui": true → start KLALBWebServer (if "webUI": true or web server enabled) → interactive console (help, links-state, route, kperf, ...).
• org.kne.cloud.network.klalb.web.KLALBWebServer — built-in HTTP/SSE server (JDK HttpServer):
  • API endpoints: /api/status, /api/events (SSE stream, 200ms intervals), /api/links, /api/links/action, /api/links/reconnect, /api/routes, /api/nodes (topology graph), /api/interfaces, /api/config.
  • Static file hosting / SPA fallback: serves dashboard/dist/ assets if built.
• org.kne.cloud.network — generic socket framework: VirtualSocket* hierarchy, SocketBridge port-forwarding proxies, ProtocolDetector (multi-protocol mux on one port), MultiProtocolSocketAddress = URI-style addresses (tcp://, udp://, kltp://, ntp://) dispatched through the SocketType registry.
• ...network.klalb — app core: KLALBController (the virtual SRv6 network), KLALBRemoteLink (WAN lines), *Packet wire-format classes, virtual socket implementations.
• ...network.congestion — pluggable congestion control (BBR, Vegas2, DCTCP...), chosen via "congestionAlgorithm" in config.
• ...network.kltp — custom reliable transport protocol (packets/streams).
• ...network.ipv6, ...network.srv6 — packet codecs, route table, Dijkstra path computation.
• ...network.frpc — frp client integration.
• ...klalb.ui — all Swing UI code.

Frontend (Dashboard)

Located in dashboard/:

• Stack: Vite + React 19 + TypeScript + Tailwind CSS v4 + @base-ui/react (style: base-nova, icons: lucide-react).
• Package Manager: pnpm (run all commands from dashboard/ directory).
• Component installation: Must use CLI via pnpm dlx shadcn@latest add <component> (e.g. pnpm dlx shadcn@latest add alert card badge). Never create or fake shadcn components manually.
• Commands:
  • pnpm dev — Start Vite dev server (proxies to backend or connects to API on localhost).
  • pnpm build — Typecheck and build SPA to dashboard/dist (which Java KLALBWebServer serves directly).
  • pnpm lint / pnpm typecheck — Verification.

Config

klalb-config.json is an array of items discriminated by their "Type" field. Adding a new item type requires a KLALBConfigItem subclass plus new cases in both KLALBConfigItem.getDefaultJsonDeserializer() and getDefaultJsonSerializer(); unknown types are preserved as UnknownKLALBConfigItem. Any Gson instance handling config must register these adapters via registerToGsonBuilder (see KLALBProxySystem).

Conventions

• Sources are UTF-8; comments, log/UI strings, and commit messages are largely Chinese.
• UI strings go through UIEnv.getRsb().getString(...); add keys to both src/klalb_zh_CN.properties and src/klalb_en_US.properties.
• client.cfg, server.cfg, linetable.txt at the root are example line-table/port-rule files loaded via the GUI file picker — not hardwired paths.