Class ClusterController

java.lang.Object
com.loomcache.springboot.controller.ClusterController
@RestController @Conditional(LoomServerEnabledCondition.class) @RequestMapping("/api/cluster") public class ClusterController extends Object
REST controller for cluster status, health checks, and Raft consensus information.

Endpoints: GET /api/cluster/status — full node status including Raft state GET /api/cluster/members — cluster membership GET /api/cluster/health — production health check (UP/DOWN)

  • Constructor Details

    • ClusterController

      public ClusterController(CacheNode cacheNode)
      Construct the cluster controller.
      Parameters:
      cacheNode - the cache node instance

  • Method Details

    • status

      @RolesAllowed("ADMIN") @GetMapping("/status") public org.springframework.http.ResponseEntity<Map<String,Object>> status(@RequestParam(defaultValue="0") int offset, @RequestParam(defaultValue="100") int limit)
      Get full node status including Raft consensus state.
      Parameters:
      offset - zero-based offset for the paged Raft member view
      limit - maximum number of Raft members to include
      Returns:
      response with node ID, instance, port, running state, Raft state/term/leader, cluster members, and connection count

    • changeClusterState

      @RolesAllowed("ADMIN") @PostMapping("/state") public org.springframework.http.ResponseEntity<Map<String,Object>> changeClusterState(@RequestBody @Nullable ClusterController.ClusterStateChangeRequest request)
      Change the cluster operational state.
      Parameters:
      request - requested state transition
      Returns:
      response with previous and current state details

    • changeClusterVersion

      @RolesAllowed("ADMIN") @PostMapping("/version") public org.springframework.http.ResponseEntity<Map<String,Object>> changeClusterVersion(@RequestBody @Nullable ClusterController.ClusterVersionChangeRequest request)
      Change the cluster version gate used during rolling upgrades.
      Parameters:
      request - requested cluster version
      Returns:
      response with previous and current version details

    • resetCpSubsystem

      @RolesAllowed("ADMIN") @PostMapping("/cp-subsystem/reset") public org.springframework.http.ResponseEntity<Map<String,Object>> resetCpSubsystem()
      Reset the local CP subsystem state for operator recovery.
      Returns:
      response with counts of cleared CP resources

    • listCpGroups

      @RolesAllowed("ADMIN") @GetMapping("/cp-subsystem/groups") public org.springframework.http.ResponseEntity<Map<String,Object>> listCpGroups()
      List local CP/Raft groups for operator inspection.
      Returns:
      response with group summaries

    • listCpSessions

      @RolesAllowed("ADMIN") @GetMapping("/cp-subsystem/sessions") public org.springframework.http.ResponseEntity<Map<String,Object>> listCpSessions()
      List active local CP sessions for operator inspection.
      Returns:
      response with session summaries

    • forceCloseCpSession

      @RolesAllowed("ADMIN") @PostMapping("/cp-subsystem/sessions/{sessionId}/force-close") public org.springframework.http.ResponseEntity<Map<String,Object>> forceCloseCpSession(@PathVariable String sessionId)
      Force-close a local CP session and release its tracked resources.
      Parameters:
      sessionId - session ID to close
      Returns:
      response describing whether the session was closed or not found

    • forceLeaderStepDown

      @RolesAllowed("ADMIN") @PostMapping("/raft/step-down") public org.springframework.http.ResponseEntity<Map<String,Object>> forceLeaderStepDown()
      Force the current local Raft leader to step down.
      Returns:
      response describing whether this node stepped down or was not the leader

    • members

      @RolesAllowed("ADMIN") @GetMapping("/members") public org.springframework.http.ResponseEntity<Map<String,Object>> members(@RequestParam(defaultValue="0") int offset, @RequestParam(defaultValue="100") int limit)
      Get cluster membership information.
      Parameters:
      offset - zero-based offset for the paged member view
      limit - maximum number of cluster members to include
      Returns:
      response with list of all cluster members and count of alive members

    • health

      @GetMapping("/health") public org.springframework.http.ResponseEntity<Map<String,Object>> health()
      Production health check endpoint.

      BLK-2026-04-22-008: this endpoint is intentionally unauthenticated (used by external probes). Previously it disclosed the leader field, which lets any anonymous caller enumerate cluster topology. The leader detail has been removed; the unauthenticated response is now bare UP/DOWN. Authenticated callers can use healthDetails() or /api/cluster/topology for leader information.

      Returns 200 OK with {"status":"UP"} if: - The node is running - The Raft engine is running - The node knows who the leader is (or IS the leader)

      Returns 503 Service Unavailable with {"status":"DOWN"} otherwise.

      Returns:
      response with health status (no leader / topology details)

    • healthDetails

      @GetMapping("/health/details") @RolesAllowed("ADMIN") public org.springframework.http.ResponseEntity<Map<String,Object>> healthDetails()
      Authenticated health-details endpoint.

      Returns the same UP/DOWN signal as health() but additionally exposes leader identity for authenticated administrators. Anonymous callers see the generic health() response only.