KLALB Agent Guide

KLALB is a Java SRv6/WAN load-balancing system. KLALBMain loads klalb-config.json from the current directory, builds KLALBProxySystem, optionally opens a desktop UI, optionally starts the web UI, and always binds the virtual server to [::]:4564.

Java Build And Run

This is a plain Java project: vendored dependencies are in lib/, bin/ is generated, and sources/resources are in src/. There is no Maven, Gradle, test suite, or CI.
VSCode is configured for C:\Program Files\Zulu\zulu-25. javac is not on PATH; source files require UTF-8 and now reference JavaFX modules.

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

The documented ThreadTool varargs and deprecated-API warnings are pre-existing; compilation succeeds with exit code 0. Restart a debugged JVM after compiling because it keeps old classes.
Run from the repository root. src must stay on the runtime classpath after manual compilation because it contains klalb_*.properties and /assets/* resources.
Use KLALB JavaFX Preview (bin) in VSCode for the opt-in --javafx UI. Default startup remains Swing. The preview configuration supplies required JavaFX modules, native-access flags, and java.library.path.
Native files are expected in the repository root. fastcopy.dll is currently absent, so FastLib logs a recoverable UnsatisfiedLinkError; restore the matching binary before testing native acceleration. Set enableTUN: false for non-admin UI testing; otherwise TUN creation requires elevation.

Architecture And UI

Keep KLALBController and networking work off UI threads. The current JavaFX layer is src/org/kne/cloud/network/klalb/ui/fx/, starts only with --javafx, and exposes immutable snapshots/typed commands through KLALBJavaFXGateway; do not leak controller or link objects into JavaFX views.
Swing remains in ...klalb.ui. Do not assume feature parity: Overview and Connections are migrated; routing, topology, settings, and detailed monitor views remain Swing/placeholder workspaces.
UI strings use the active UIEnv bundle. Add every new key to both src/klalb_zh_CN.properties and src/klalb_en_US.properties; keep them on the runtime classpath.

Config, APIs, And Protocols

klalb-config.json is a Type-discriminated list. New item types need a KLALBConfigItem subclass plus both default Gson serializer/deserializer registrations; unknown items must remain preservable.
Config saves use canonical keys but reads and /api/config accept legacy aliases. Keep aliases in KLALBConfigItem and field-by-field KLALBWebServer.handleConfig parsing when changing controller settings; whole-object Gson mapping breaks polymorphic address lists.
Gson is vendored version 2.1. For a runtime JsonElement, use JsonElement.toString() rather than gson.toJson(Object); old Gson serializes subclasses incorrectly. Keep the existing guard in sendJsonResponse.
SRv6 JSON datagrams have a two-byte UTF-8 payload length; keep encoded messages below 64 KiB.
The web dashboard is served from dashboard/dist when webUI is enabled (normally :4665); without it, the backend serves fallback HTML.

Dashboard Submodule

dashboard/ is a separate Git repository. Commit frontend work there first, then update the parent submodule pointer.
Run frontend commands inside dashboard/: pnpm dev, pnpm build, pnpm lint, and pnpm typecheck. Vite proxies /api to http://127.0.0.1:4665.
Install shadcn components only with pnpm dlx shadcn@latest add <component>; use pnpm add for other dependencies. The dashboard README's npx instruction is stale.

Verification

Practical Java verification is the full compile command above plus a controlled launch. Existing *Test* classes are manual harnesses that need real network peers.
For dashboard changes, run pnpm lint, pnpm typecheck, and pnpm build.

4.0 KiB Raw Permalink Blame History