CEP-38: Management API MVP Implementation [CASSANDRA-19476]

[Mmuzaf]

CEP-38: Management API MVP Implementation

Summary

This PR implements the mvp of CEP-38, enabling server-side execution of ops commands via a native management transport and CQL interface. This eliminates the need for external JMX connections.

See: https://cwiki.apache.org/confluence/display/CASSANDRA/CEP-38%3A+CQL+Management+API

Key Features

1. Management API Infrastructure

• CommandInvokerService: Central service managing command registry lifecycle and execution
• Command Registry: Hierarchical command registry supporting nested commands
• Command Metadata: Structured metadata for commands, options, and parameters
• Execution Context: Server-side execution context with NodeProbe integration for in-process MBean access

2. Native Management Transport

• NativeTransportManagementService: Separate native transport server on port 11211 (configurable via native_transport_management_port)
• Dedicated Executor: Management connections use a separate thread pool (managementExecutor) for isolation and prioritization
• Connection Flagging: Management connections are flagged at connection setup and routed to the management executor
• Request Validation: Only COMMAND statements are allowed on management connections; other CQL operations are rejected

3. CQL Command Execution

• ExecuteCommandStatement: New CQL statement syntax: COMMAND <commandName> [WITH key1 = value1 AND key2 = value2]
• Result Format: Commands return a result set with execution_id (UUID) and output (String) columns
• Argument Parsing: Supports CQL string literals, lists, and proper escaping
• Error Handling: Structured exceptions for validation, authorization, and execution errors

4. Picocli Integration

• PicocliCommandsProvider: Automatically discovers and registers all nodetool commands
• Command Adapters: PicocliCommandAdapter and PicocliCommandRegistryAdapter bridge picocli commands to the management API
• Metadata Extraction: Automatic extraction of command metadata from picocli annotations
• Argument Conversion: Bidirectional conversion between picocli command objects and CommandExecutionArgs

5. Server-Side Execution

• InternalNodeMBeanAccessor: In-process MBean accessor eliminating JMX/RMI overhead
• Direct Instance Access: Direct access to singleton instances
• Performance Benefits: No serialization/deserialization, no network overhead, better performance
• NodeProbe Integration: NodeProbe supports remote jmx and server-side in-process execution modes

6. JMX/Dynamic MBean Support

• CommandMBean: Each command is exposed as an dynamic MBean for JMX access and for auditing exections
• MBean Registration: Commands are automatically registered as MBeans under org.apache.cassandra.management:type=Command,name=<commandName>

7. Nodetool Integration

• CqlCommandExecutionStrategy: New execution strategy allowing nodetool to execute commands via CQL
• Protocol-Aware Execution: Nodetool can choose between JMX, CQL, or other protocols based on connection configuration
• Seamless Integration: Existing nodetool commands work without modification

Configuration

• start_native_management_transport: Enable/disable management transport (default disabled - false)
• native_transport_management_port: Port for management transport (default: 11211)
• native_transport_management_max_threads: Thread pool size for management operations

Limitations

• Authentication: Currently only supported with AllowAllAuthenticator (authentication disabled). Full authentication and authorization support is planned for future releases.
• CQL Commands: DESCRIBE COMMAND will be introduces later
• Virtual Tables: Visibility will be introduced later

Related

• CEP-38: https://cwiki.apache.org/confluence/display/CASSANDRA/CEP-38%3A+CQL+Management+API
• Builds on existing nodetool command infrastructure
• Integrates with existing native transport and CQL infrastructure

Example Usage

 > ./nodetool -Dcassandra.cli.execution.protocol=cql status
Connecting to 127.0.0.1:11211 via CQL...
Datacenter: datacenter1
=======================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
--  Address    Load        Tokens  Owns (effective)  Host ID                               Rack 
UN  127.0.0.1  189,06 KiB  16      100,0%            6d194555-f6eb-41d0-c000-000000000001  rack1


Command execution id: 44bea459-d884-4433-9da3-ad14b42ca942

-- Execute a command via CQL
COMMAND status;

-- Execute a command with parameters
COMMAND forcecompact WITH "keyspace" = 'mykeyspace' AND "table" = 'mytable' AND keys = ['key1', 'key2'];