0
# Command Interface
1

2
The command interface provides HTTP endpoints for runtime configuration and monitoring of cluster client settings. These handlers enable dynamic reconfiguration and status queries without restarting the application.
3

4
## Capabilities
5

6
### Modify Cluster Client Configuration
7

8
HTTP command handler for dynamically updating cluster client configuration including server assignments and timeout settings.
9

10
```java { .api }
11
/**
12
 * Command handler for modifying cluster client configuration
13
 * Endpoint: cluster/client/modifyConfig
14
 */
15
@CommandMapping(name = "cluster/client/modifyConfig", desc = "modify cluster client config")
16
public class ModifyClusterClientConfigHandler implements CommandHandler<String> {
17
    /**
18
     * Handle configuration modification request
19
     * @param request command request with URL-encoded JSON data parameter
20
     * @return success message or error response
21
     */
22
    public CommandResponse<String> handle(CommandRequest request);
23
}
24
```
25

26
**Usage Examples:**
27

28
```java
29
// The handler expects a "data" parameter with URL-encoded JSON
30
// POST /cluster/client/modifyConfig?data=<encoded-json>
31

32
// Example JSON payload (before URL encoding):
33
{
34
    "serverHost": "new-cluster-server.example.com",
35
    "serverPort": 8719,
36
    "requestTimeout": 5000,
37
    "clientState": 2
38
}
39

40
// The handler will:
41
// 1. URL decode the data parameter
42
// 2. Parse JSON into ClusterClientStateEntity
43
// 3. Apply configuration via ClusterClientConfigManager
44
// 4. Return success or error response
45
```
46

47
### Fetch Cluster Client Configuration
48

49
HTTP command handler for retrieving current cluster client configuration and state information.
50

51
```java { .api }
52
/**
53
 * Command handler for fetching cluster client configuration
54
 * Endpoint: cluster/client/fetchConfig
55
 */
56
@CommandMapping(name = "cluster/client/fetchConfig", desc = "get cluster client config")
57
public class FetchClusterClientConfigHandler implements CommandHandler<String> {
58
    /**
59
     * Handle configuration fetch request
60
     * @param request command request (no parameters required)
61
     * @return JSON string containing current client state and configuration
62
     */
63
    public CommandResponse<String> handle(CommandRequest request);
64
}
65
```
66

67
**Usage Examples:**
68

69
```java
70
// GET /cluster/client/fetchConfig
71
// Returns JSON response with current configuration:
72

73
{
74
    "serverHost": "cluster-server.example.com",
75
    "serverPort": 8719,
76
    "requestTimeout": 3000,
77
    "clientState": 2
78
}
79

80
// Client states:
81
// 0 = CLIENT_STATUS_OFF
82
// 1 = CLIENT_STATUS_PENDING  
83
// 2 = CLIENT_STATUS_STARTED
84
```
85

86
### Configuration State Entity
87

88
Data transfer object for command interface operations that bridges HTTP requests and internal configuration classes.
89

90
```java { .api }
91
/**
92
 * Entity for transferring cluster client state via command interface
93
 */
94
public class ClusterClientStateEntity {
95
    /**
96
     * Get server hostname or IP address
97
     * @return server host string
98
     */
99
    public String getServerHost();
100
    
101
    /**
102
     * Set server hostname or IP address
103
     * @param serverHost hostname or IP
104
     * @return this entity for fluent chaining
105
     */
106
    public ClusterClientStateEntity setServerHost(String serverHost);
107
    
108
    /**
109
     * Get server port number
110
     * @return server port
111
     */
112
    public Integer getServerPort();
113
    
114
    /**
115
     * Set server port number
116
     * @param serverPort port number (1-65535)
117
     * @return this entity for fluent chaining
118
     */
119
    public ClusterClientStateEntity setServerPort(Integer serverPort);
120
    
121
    /**
122
     * Get current client state
123
     * @return client state constant
124
     */
125
    public Integer getClientState();
126
    
127
    /**
128
     * Set client state
129
     * @param clientState state constant (OFF/PENDING/STARTED)
130
     * @return this entity for fluent chaining
131
     */
132
    public ClusterClientStateEntity setClientState(Integer clientState);
133
    
134
    /**
135
     * Get request timeout setting
136
     * @return timeout in milliseconds
137
     */
138
    public Integer getRequestTimeout();
139
    
140
    /**
141
     * Set request timeout
142
     * @param requestTimeout timeout in milliseconds
143
     * @return this entity for fluent chaining
144
     */
145
    public ClusterClientStateEntity setRequestTimeout(Integer requestTimeout);
146
    
147
    /**
148
     * Convert to internal client configuration object
149
     * @return ClusterClientConfig with timeout settings
150
     */
151
    public ClusterClientConfig toClientConfig();
152
    
153
    /**
154
     * Convert to internal server assignment configuration
155
     * @return ClusterClientAssignConfig with server details
156
     */
157
    public ClusterClientAssignConfig toAssignConfig();
158
}
159
```
160

161
**Usage Examples:**
162

163
```java
164
import com.alibaba.csp.sentinel.command.entity.ClusterClientStateEntity;
165

166
// Create configuration entity
167
ClusterClientStateEntity entity = new ClusterClientStateEntity()
168
    .setServerHost("new-server.example.com")  
169
    .setServerPort(8719)
170
    .setRequestTimeout(5000)
171
    .setClientState(ClientConstants.CLIENT_STATUS_STARTED);
172

173
// Convert to internal configuration objects
174
ClusterClientConfig clientConfig = entity.toClientConfig();
175
ClusterClientAssignConfig assignConfig = entity.toAssignConfig();
176

177
// Apply configurations
178
ClusterClientConfigManager.applyNewConfig(clientConfig);
179
ClusterClientConfigManager.applyNewAssignConfig(assignConfig);
180
```
181

182
## Command Integration
183

184
The command handlers integrate with Sentinel's HTTP command system and are automatically registered via the `@CommandMapping` annotation.
185

186
**Command Registration:**
187

188
```java
189
// Handlers are automatically discovered and registered by Sentinel
190
// Access via HTTP endpoints:
191

192
// Modify configuration:
193
// POST http://host:port/cluster/client/modifyConfig?data=<url-encoded-json>
194

195
// Fetch configuration:  
196
// GET http://host:port/cluster/client/fetchConfig
197
```
198

199
**Error Handling:**
200

201
```java
202
// Command responses include success/failure status
203
CommandResponse<String> response = handler.handle(request);
204

205
if (response.isSuccess()) {
206
    String result = response.getResult();
207
    System.out.println("Command succeeded: " + result);
208
} else {
209
    Exception exception = response.getException();
210
    System.err.println("Command failed: " + exception.getMessage());
211
}
212
```
213

214
## JSON Serialization
215

216
The command interface uses FastJSON for JSON serialization and deserialization of configuration data.
217

218
**Required Dependencies:**
219

220
```java
221
import com.alibaba.fastjson.JSON;
222

223
// Serialization
224
String json = JSON.toJSONString(stateEntity);
225

226
// Deserialization  
227
ClusterClientStateEntity entity = JSON.parseObject(json, ClusterClientStateEntity.class);
228
```
229

230
## Thread Safety
231

232
All command handlers are stateless and thread-safe. Multiple concurrent command requests can be processed safely. The underlying configuration manager handles synchronization of configuration updates.
233

234
## Security Considerations
235

236
Command handlers should be protected with appropriate authentication and authorization mechanisms when deployed in production environments. The modify configuration endpoint can change critical cluster settings and should be restricted to authorized administrators.