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.Security
HLAgentSecurityConfig: 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.
| Class | Responsibility |
|---|---|
HLAgentController | REST surface. Also contains the filesystem helpers, the docker compose runner (composeCommand, composeUpRenewingChangedImages, servicesWithChangedImage, validComposePath) and the generic runProcess used by docker ps/logs. |
HLOrgMspService | readMsp 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). |
HLChannelLifecycleService | Base 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). |
HLChannelUpdateService | addOrgToChannel: 14-step config-update pipeline (see /channel/addOrg). Extends the lifecycle service to reuse runCommand. |
HLChannelOrdererAddService | addOrderer: adds a Raft consenter to a running channel (see /channel/addOrderer). Helpers: findOrdererOrg (match by root cert), hasConsenter, withOrdererFlags, peerEnv. |
HLChaincodeLifecycleService | install, 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. |
HLNetworkDiagnosticsService | check 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.