KLALB/AGENTS.md

KLALB Repository Guide

KLALB is a Java SRv6/load-balancing system. Start at org.kne.cloud.network.klalb.KLALBMain; runtime configuration is root-relative klalb-config.json.

Build And Run

• This is an Eclipse Java project, not Maven or Gradle: src/ contains sources, lib/ vendored dependencies, and bin/ compiled output. .classpath targets Java 25.
• Source files contain Chinese text, so compile with UTF-8 from the repository root:

& "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. src must stay on the classpath because manual compilation does not copy resource bundles:

& "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

• Native libraries and klalb-config.json are resolved from the current directory; restart the JVM after recompiling. TUN creation requires elevation, so use "enableTUN": false for non-admin checks.

Dashboard

• dashboard/ is a Git submodule. Commit dashboard changes in that repository, then update the parent submodule pointer.
• Run frontend commands from dashboard/: pnpm install --frozen-lockfile, pnpm lint, pnpm typecheck, and pnpm build. The build is tsc -b && vite build and produces dashboard/dist, which the Java server hosts.
• Vite proxies /api to http://127.0.0.1:4665; use pnpm dev only with the Java API running there.

Verification

• No repository test runner or CI workflow is configured. 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 case-sensitive Type. New types need serializer and deserializer support; preserve unknown items' raw JSON.
• /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: responses that are JsonElement instances must be serialized with JsonElement.toString(), not reflective gson.toJson(Object).
• UI strings use UIEnv.getRsb(); add keys to both src/klalb_zh_CN.properties and src/klalb_en_US.properties.
• KLALBController.PublishedNodeInfo is the thread-safe node-info source. Publish profile, effective external endpoints, and extra routes through the controller so snapshots and update flags remain coherent. Peer queries are separate profile, endpoint, and extra-route requests; use NodeInfoQueryCoordinator when a consumer needs an aggregate detail result.
• RouterInfo retains an empty legacy UTF slot. RouterInfoPacket appends optional update flags behind a marker; treat binary codec changes as mesh-compatibility work and preserve old-reader behavior.