KLALB/AGENTS.md

KLALB Repository Guide

KLALB is a Java SRv6/load-balancing system. The executable entrypoint is org.kne.cloud.network.klalb.KLALBMain; runtime configuration is klalb-config.json in the repository root.

Build And Run

• This is a plain Eclipse/IntelliJ Java project: sources are src/, vendored dependencies are lib/, and output is bin/. There is no Maven or Gradle.
• .classpath targets JavaSE-25. Sources contain Chinese text, so manual compilation must use UTF-8:

& "C:\Program Files\Zulu\zulu-25\bin\javac.exe" -encoding UTF-8 -cp "lib/*" -d bin (Get-ChildItem -Recurse src -Filter *.java | ForEach-Object FullName)

• Run from the repository root. Manual javac does not copy resources, so keep src on the runtime classpath:

& "C:\Program Files\Zulu\zulu-25\bin\java.exe" --enable-native-access=ALL-UNNAMED "--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED" -cp "bin;src;lib/*" org.kne.cloud.network.klalb.KLALBMain

• The native libraries and klalb-config.json are resolved from the current directory. Restart a running JVM after recompiling.
• TUN creation normally needs elevation. For non-admin UI/routing checks, set "enableTUN": false.
• Current full compilation emits 11 pre-existing varargs/deprecation warnings; exit code 0 is success.

Dashboard

• dashboard/ is a Git submodule. Commit dashboard changes inside it, then update the parent repository's submodule pointer.
• Run frontend commands from dashboard/ with pnpm:

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm build
pnpm dev

• pnpm build runs tsc -b then Vite and writes dashboard/dist, which the Java web server hosts. Vite development proxies /api to http://127.0.0.1:4665.
• Add shadcn components through pnpm dlx shadcn@latest add <component>; do not hand-create replacements for installed shadcn primitives.

Verification

• There is no CI or automated test suite. *Test* classes are manual harnesses that require real network peers.
• For Java changes, compile and launch the app. For dashboard changes, run pnpm typecheck and pnpm build.

Important Boundaries

• KLALBConfigItem is a polymorphic JSON array keyed by Type. Adding a type requires a subclass and cases in both default config serializer and deserializer; unknown types must remain preserved.
• /api/config is field-by-field parsing, not whole-object Gson mapping. Keep legacy key aliases in sync with new fields.
• Vendored Gson is 2.1: HTTP responses that are JsonElement instances must be serialized with JsonElement.toString(), not reflective gson.toJson(Object); configuration files must use the configured pretty-print Gson path rather than JsonElement.toString().
• UI strings use UIEnv.getRsb(); add keys to both src/klalb_zh_CN.properties and src/klalb_en_US.properties.
• Web and Swing configuration writes must use KLALBProxySystem's revisioned detached-candidate commit/event path; do not mutate the canonical config object directly.
• KLALBController.PublishedNodeInfo is the thread-safe source for Tiny/Full node-info responses. Publish name, description, external endpoints, and Extra Routes through the controller method so snapshots and Tiny/Full update flags stay consistent.
• RouterInfo no longer carries a device name. Its wire format retains an empty legacy UTF slot and RouterInfoPacket has optional Tiny/Full invalidation flags. Treat codec changes as compatibility work: preserve old-reader behavior and review a whole-mesh rollout.
• Full node-info carries extraRoutes separately from the endpoint data list. Keep absent fields compatible with older peers.