VOVHL/TOOLS
REFERENCE / AGENT

hlFabricAgent services.

The agent is the per-node gateway of the hl console. It runs on every machine of the Fabric network and turns REST calls from the admin backend into filesystem work, docker compose commands, Fabric CA calls, Fabric CLI invocations (peer, osnadmin, configtxgen, configtxlator) and Gateway transactions.

Overview

Spring Boot app py.com.hlwizard.agent.HLAgentApp · port 8282 (SERVER_PORT) · context /hlAgent · all endpoints under /api/agent · Swagger UI at /hlAgent/swagger-ui.html

LayersOne controller (HLAgentController, 38 endpoints) delegates to five agent services plus shared services from hlFabricServices.
Shelling outThe image bundles no Fabric binaries. CLIs come from the host's /var/hyperledger/fabric/bin (fabric_bin_path) with FABRIC_CFG_PATH=/var/hyperledger/fabric/config; docker.sock is used for compose.
SecurityHLAgentSecurityConfig: stateless, CSRF off, CORS open to all origins, every request permitted — no authentication. Protect it at the network level.
ResponsesWrapped in HLHttpResponse<T> (responseObject or error{code,message}). Domain errors (HLException) go through HLHttpExceptionResponse, which returns HTTP 200 with the error in the body; plain failures return 500.
Admin backend ──HTTP──► HLAgentController ─┬─► Files / NIO                    (filesystem, MSP)
 (hlFabricAdmin)                          ├─► docker compose / docker ps/logs (containers)
                                          ├─► HLOrganizationsService ─► Fabric CA (register/enroll/delete)
                                          ├─► HLConfigtxService      ─► configtx.yaml (generate/save)
                                          ├─► HLChannel*Service      ─► configtxgen, osnadmin, peer, configtxlator
                                          ├─► HLChaincodeLifecycleService ─► peer lifecycle chaincode …
                                          ├─► HLGatewayService       ─► Fabric Gateway SDK (invoke/query)
                                          └─► HLNetworkDiagnosticsService ─► sockets / ICMP / TLS

Internals: the service classes

What each backing class does, independent of the HTTP layer.

ClassResponsibility
HLAgentControllerREST surface. Also contains the filesystem helpers, the docker compose runner (composeCommand, composeUpRenewingChangedImages, servicesWithChangedImage, validComposePath) and the generic runProcess used by docker ps/logs.
HLOrgMspServicereadMsp reads msp/cacerts/ca.pem, msp/tlscacerts/ca.pem, msp/config.yaml. saveMsp writes the same three files under a target directory (skips blank values).
HLChannelLifecycleServiceBase class for CLI work. createChannel (configtxgen), joinOrderer / removeOrderer (osnadmin per orderer), joinChannel (peer channel join per peer), runPackage (peer lifecycle chaincode package), prepareOrdererMsp (copies orderer CA/TLS certs next to configtx.yaml), writeNodeOUsConfig, resolveBin (fabricBinPath + tool), and runCommand (ProcessBuilder, merged stdout/stderr, async reader to avoid pipe deadlock, 120 s timeout).
HLChannelUpdateServiceaddOrgToChannel: 14-step config-update pipeline (see /channel/addOrg). Extends the lifecycle service to reuse runCommand.
HLChannelOrdererAddServiceaddOrderer: adds a Raft consenter to a running channel (see /channel/addOrderer). Helpers: findOrdererOrg (match by root cert), hasConsenter, withOrdererFlags, peerEnv.
HLChaincodeLifecycleServiceinstall, approve, commit, queryInstalled, queryApproved, checkCommitReadiness. Builds the peer env (buildPeerEnv), adds orderer flags with routable-host support (addOrdererFlags), injects /etc/hosts aliases for cross-node peers (injectHostAliases), and writes the collections config to a temp file.
HLNetworkDiagnosticsServicecheck runs three probes per target with a 5 s timeout: checkPort (TCP connect), checkHostAlive (InetAddress.isReachable), checkTls (handshake with a trust-all factory — it proves reachability, not certificate validity).
Shared (hlFabricServices)HLOrganizationsService (Fabric CA: register / enroll / enrollTls / deleteIdentity, via the legacy fabric-sdk-java HFCAClient), HLConfigtxService (generate / save / generateAndSave configtx.yaml), HLGatewayService (Fabric Gateway SDK 1.10: submitTransaction / evaluateTransaction).
Path safety: filesystem endpoints reject any path containing ..; container log names must match [A-Za-z0-9_.-]+; zip entries that escape the target dir raise a SecurityException. Absolute paths are otherwise unrestricted, so the agent trusts its caller.
Process timeouts: compose commands 180 s, CLI commands 120 s, docker ps/logs 60 s, compose config/ps probes 60 s.