diff --git a/hbase-protocol/src/main/protobuf/RPC.proto b/hbase-protocol/src/main/protobuf/RPC.proto index 90ec7ce..69c46e4 100644 --- a/hbase-protocol/src/main/protobuf/RPC.proto +++ b/hbase-protocol/src/main/protobuf/RPC.proto @@ -15,123 +15,325 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - -/** - * Specification of (unsecure) HBase RPC: - * - * Client needs to set up a connection first to a server serving a certain - * HBase protocol (like ClientProtocol). Once the connection is set up, the - * client and server communicates on that channel for RPC requests/responses. - * The sections below describe the flow. - * - * As part of setting up a connection to a server, the client needs to send - * the ConnectionHeader header. At the data level, this looks like - * <"hrpc"-bytearray><'5'[byte]> - * - * For every RPC that the client makes it needs to send the following - * RpcRequestHeader and the RpcRequestBody. At the data level this looks like: - * - * - * - * - * On a success, the server's protobuf response looks like - * - * - * On a failure, the server's protobuf response looks like - * - * - * - * There is one special message that's sent from client to server - - * the Ping message. At the data level, this is just the bytes corresponding - * to integer -1. - */ - import "Tracing.proto"; +import "Client.proto"; +import "Admin.proto"; +import "Master.proto"; +import "Authentication.proto"; +import "AccessControl.proto"; +import "MasterMonitor.proto"; +import "MasterAdmin.proto"; +import "RegionServerStatus.proto"; option java_package = "org.apache.hadoop.hbase.protobuf.generated"; option java_outer_classname = "RPCProtos"; option java_generate_equals_and_hash = true; option optimize_for = SPEED; + +// See https://issues.apache.org/jira/browse/HBASE-7533 for RPC +// specification. On connection setup, the client sends a few bytes of +// preamble -- a four byte magic, a byte of version, and a byte of +// authentication type -- followed by a protobuf of user information +// and the 'protocol' or 'service' that is to be run over this +// connection. + message UserInformation { required string effectiveUser = 1; optional string realUser = 2; } +// This is sent on connection setup after connection preamble. message ConnectionHeader { - /** User Info beyond what is established at connection establishment - * (applies to secure HBase setup) - */ + // User information is not used much. If the connection is secure, then we + // use the user gleaned from the secure connection setup. This user here is + // just for logging owner on insecure connections. optional UserInformation userInfo = 1; - /** Protocol name for next rpc layer - * the client created a proxy with this protocol name - */ + // Do we have to specify a protocol? Both sides will have supported protocols. + // Could do lookup. We are passing method name in Request. Could pass instead + // a MethodDescriptor. A MD has the Service/Protocol included. optional string protocol = 2 [default = "org.apache.hadoop.hbase.client.ClientProtocol"]; + // TODO: What DataBlockEncoding we can accept + // TODO: What connection compressions we can do; i.e. netty gzip'ing of all comm. } +// Metadata on EncodedDataBlock +message EncodedDataBlockMeta { + // TODO: size, type +} -/** - * The RPC request header - */ -message RpcRequestHeader { - /** Monotonically increasing callId, mostly to keep track of RPCs */ - required uint32 callId = 1; - optional RPCTInfo tinfo = 2; +// At the RPC layer, this message is used to indicate +// the server side exception to the RPC client. +message ExceptionResponse { + /** Class name of the exception thrown from the server */ + optional string exceptionClassName = 1; + optional string message = 2; + /** Exception stack trace from the server side */ + optional string stackTrace = 3; } -/** - * The RPC request body - */ -message RpcRequestBody { - /** Name of the RPC method */ - required string methodName = 1; - - /** Bytes corresponding to the client protobuf request. This is the actual - * bytes corresponding to the RPC request argument. - */ - optional bytes request = 2; - - /** Some metainfo about the request. Helps us to treat RPCs with - * different priorities. For now this is just the classname of the request - * proto object. - */ - optional string requestClassName = 4; + +// Making a union message type to hold one of the request types. +// Will do same for the response types. Following the pattern outlined here: +// https://developers.google.com/protocol-buffers/docs/techniques#union + +// First, lets make up a typing that can be used on request and response. +message Type { + enum Type { + // There is not enum in position '1'. + EXCEPTION = 2; + + // Client Service/Protocol + GET = 3; + MUTATE = 4; + SCAN = 5; + LOCK = 6; + UNLOCK = 7; + BULK_LOAD = 8; + COPROCESSOR_EXEC = 9; + MULTI = 10; + + // Admin Service/Protocol + REGIONINFO = 11; + STOREFILE = 12; + ONLINE_REGIONS = 13; + OPEN_REGION = 14; + CLOSE_REGION = 15; + FLUSH_REGION = 16; + SPLIT_REGION = 17; + COMPACT_REGION = 17; + REPLICATE_WAL = 18; + ROLL_WAL = 20; + SERVERINFO= 21; + STOP = 22; + + // Access control Service/Protocol + GRANT = 23; + REVOKE = 24; + USER_PERMISSION = 25; + CHECK_PERMISSION = 26; + + // Authentication + TOKEN = 27; + WHOAMI = 28; + + // Master + IS_RUNNING = 29; + + // Master Admin + ADD_COLUMN = 30; + DELETE_COLUMN = 31; + MODIFY_COLUMN = 32; + MOVE_REGION = 33; + ASSIGN_REGION = 34; + UNASSIGN_REGION = 35; + OFFLINE_REGION = 36; + DELETE_TABLE = 37; + ENABLE_TABLE = 38; + DISABLE_TABLE = 39; + MODIFY_TABLE = 40; + CREATE_TABLE = 41; + SHUTDOWN = 42; + STOP_MASTER = 43; + BALANCE = 44; + SET_BALANCER_RUNNING = 45; + CATALOG_SCAN = 46; + ENABLE_CATALOG_JANITOR = 47; + IS_CATALOG_JANITOR_ENABLED = 48; + // This is defined above for client already. + // COPROCESSOR_SERVICE = 49; + + // Master Monitor + SCHEMA_ALTER_STATUS = 50; + TABLE_DESCRIPTORS = 51; + CLUSTER_STATUS = 52; + + // Regionserver + REGIONSERVER_START = 53; + REGIONSERVER_REPORT = 54; + REGIONSERVER_FATAL = 55; + LAST_SEQID = 56; + ;} + required Type type = 1; } -/** - * The RPC response header - */ -message RpcResponseHeader { - /** Echo back the callId the client sent */ - required uint32 callId = 1; - /** Did the RPC execution encounter an error at the server */ - enum Status { - SUCCESS = 0; - ERROR = 1; - FATAL = 2; - } - required Status status = 2; +// A union that holds all possible requests. Responses must have +// 'answers' for all request items listed here. Only one request +// allowed in this 'union'. You pick one. The type saying which +// it is helps coding this stuff up. +message Request { + required Type type = 1; + // There is no #2 in request. + // Client Service/Protocol + optional GetRequest getRequest = 3; + optional MutateRequest mutateRequest = 4; + optional ScanRequest scanRequest = 5; + optional LockRowRequest lockRowRequest = 6; + optional UnlockRowRequest unlockRowRequest = 7; + optional BulkLoadHFileRequest bulkLoadHFileRequest = 8; + optional CoprocessorServiceRequest coprocessorServiceRequest = 9; + optional MultiRequest multiRequest = 10; + + // Admin Service/Protocol + optional GetRegionInfoRequest getRegionInfoRequest = 11; + optional GetStoreFileRequest getStoreFileRequest = 12; + optional GetOnlineRegionRequest getOnlineRegionRequest = 13; + optional OpenRegionRequest openRegionRequest = 14; + optional CloseRegionRequest closeRegionRequest = 15; + optional FlushRegionRequest flushRegionRequest = 16; + optional SplitRegionRequest splitRegionRequest = 17; + optional CompactRegionRequest compactRegionRequest = 18; + optional ReplicateWALEntryRequest replicateWALEntryRequest = 19; + optional RollWALWriterRequest rollWALWriterRequest = 20; + optional GetServerInfoRequest getServerInfoRequest = 21; + optional StopServerRequest stopServerRequest = 22; + + // Access control Service/Protocol + optional GrantRequest grantRequest = 23; + optional RevokeRequest revokeRequest = 24; + optional UserPermissionsRequest userPermissionsRequest = 25; + optional CheckPermissionsRequest checkPermissionsRequest = 26; + + // Authentication + optional TokenRequest tokenRequest = 27; + optional WhoAmIRequest whoAmIRequest = 28; + + // Master + optional IsMasterRunningRequest isMasterRunningRequest = 29; + + // Master Admin + optional AddColumnRequest addColumnRequest = 30; + optional DeleteColumnRequest deleteColumnRequest = 31; + optional ModifyColumnRequest modifyColumnRequest = 32; + optional MoveRegionRequest moveRegionRequest = 33; + optional AssignRegionRequest assignRegionRequest = 34; + optional UnassignRegionRequest unassignRegionRequest = 35; + optional OfflineRegionRequest offlineRegionRequest = 36; + optional DeleteTableRequest deleteTableRequest = 37; + optional EnableTableRequest enableTableRequest = 38; + optional DisableTableRequest disableTableRequest = 39; + optional ModifyTableRequest modifyTableRequest = 40; + optional CreateTableRequest createTableRequest = 41; + optional ShutdownRequest shutdownRequest = 42; + optional StopMasterRequest stopMasterRequest = 43; + optional BalanceRequest balanceRequest = 44; + optional SetBalancerRunningRequest setBalancerRunningRequest = 45; + optional CatalogScanRequest catalogScanRequest = 46; + optional EnableCatalogJanitorRequest enableCatalogJanitorRequest = 47; + optional IsCatalogJanitorEnabledRequest isCatalogJanitorEnabledRequest = 48; + // The below is already defined above for Client + // optional CoprocessorServiceRequest coprocessorServiceRequest = 49; + + // Master Monitor + optional GetSchemaAlterStatusRequest getSchemaAlterStatusRequest = 50; + optional GetTableDescriptorsRequest getTableDescriptorsRequest = 51; + optional GetClusterStatusRequest getClusterStatusRequest = 52; + + // Regionserver + optional RegionServerStartupRequest regionServerStartupRequest = 53; + optional RegionServerReportRequest regionServerReportRequest = 54; + optional ReportRSFatalErrorRequest reportRSFatalErrorRequest = 55; + optional GetLastFlushedSequenceIdRequest getLastFlushedSequenceIdRequest = 56; } -/** - * The RPC response body - */ -message RpcResponseBody { - /** Optional response bytes. This is the actual bytes corresponding to the - * return value of the invoked RPC. - */ - optional bytes response = 1; + +// Now all the request types. +message Response { + required Type type = 1; + optional ExceptionResponse getException = 2; + // Client Service/Protocol + optional GetResponse getResponse = 3; + optional MutateResponse mutateResponse = 4; + optional ScanResponse scanResponse = 5; + optional LockRowResponse lockRowResponse = 6; + optional UnlockRowResponse unlockRowResponse = 7; + optional BulkLoadHFileResponse bulkLoadHFileResponse = 8; + optional CoprocessorServiceResponse coprocessorServiceResponse = 9; + optional MultiResponse multiResponse = 10; + + // Admin Service/Protocol + optional GetRegionInfoResponse getRegionInfoResponse = 11; + optional GetStoreFileResponse getStoreFileResponse = 12; + optional GetOnlineRegionResponse getOnlineRegionResponse = 13; + optional OpenRegionResponse openRegionResponse = 14; + optional CloseRegionResponse closeRegionResponse = 15; + optional FlushRegionResponse flushRegionResponse = 16; + optional SplitRegionResponse splitRegionResponse = 17; + optional CompactRegionResponse compactRegionResponse = 18; + optional ReplicateWALEntryResponse replicateWALEntryResponse = 19; + optional RollWALWriterResponse rollWALWriterResponse = 20; + optional GetServerInfoResponse getServerInfoResponse = 21; + optional StopServerResponse stopServerResponse = 22; + + // Access control Service/Protocol + optional GrantResponse grantResponse = 23; + optional RevokeResponse revokeResponse = 24; + optional UserPermissionsResponse userPermissionsResponse = 25; + optional CheckPermissionsResponse checkPermissionsResponse = 26; + + // Authentication + optional TokenResponse tokenResponse = 27; + optional WhoAmIResponse whoAmIResponse = 28; + + // Master + optional IsMasterRunningResponse isMasterRunningResponse = 29; + + // Master Admin + optional AddColumnResponse addColumnResponse = 30; + optional DeleteColumnResponse deleteColumnResponse = 31; + optional ModifyColumnResponse modifyColumnResponse = 32; + optional MoveRegionResponse moveRegionResponse = 33; + optional AssignRegionResponse assignRegionResponse = 34; + optional UnassignRegionResponse unassignRegionResponse = 35; + optional OfflineRegionResponse offlineRegionResponse = 36; + optional DeleteTableResponse deleteTableResponse = 37; + optional EnableTableResponse enableTableResponse = 38; + optional DisableTableResponse disableTableResponse = 39; + optional ModifyTableResponse modifyTableResponse = 40; + optional CreateTableResponse createTableResponse = 41; + optional ShutdownResponse shutdownResponse = 42; + optional StopMasterResponse stopMasterResponse = 43; + optional BalanceResponse BalanceResponse = 44; + optional SetBalancerRunningResponse SetBalancerRunningResponse = 45; + optional CatalogScanResponse CatalogScanResponse = 46; + optional EnableCatalogJanitorResponse EnableCatalogJanitorResponse = 47; + optional IsCatalogJanitorEnabledResponse IsCatalogJanitorEnabledResponse = 48; + // The below is already defined above for Client + // optional CoprocessorServiceResponse CoprocessorServiceResponse = 49; + + // Master Monitor + optional GetSchemaAlterStatusResponse getSchemaAlterStatusResponse = 50; + optional GetTableDescriptorsResponse getTableDescriptorsResponse = 51; + optional GetClusterStatusResponse getClusterStatusResponse = 52; + + // Regionserver + optional RegionServerStartupResponse regionServerStartupResponse = 53; + optional RegionServerReportResponse regionServerReportResponse = 54; + optional ReportRSFatalErrorResponse reportRSFatalErrorResponse = 55; + optional GetLastFlushedSequenceIdResponse getLastFlushedSequenceIdResponse = 56; } -/** - * At the RPC layer, this message is used to indicate - * the server side exception to the RPC client. - * - * HBase RPC client throws an exception indicated - * by exceptionName with the stackTrace. - */ -message RpcException { - /** Class name of the exception thrown from the server */ - required string exceptionName = 1; - /** Exception stack trace from the server side */ - optional string stackTrace = 2; +// An RPC Request +message RpcRequest { + // Monotonically increasing callId to keep track of RPC requests and their response + optional uint64 callId = 1; + // If present, then an encoded data block follows. + optional EncodedDataBlockMeta encodedDataMeta = 2; + + optional Request request = 3; + + optional RPCTInfo traceInfo = 4; + + // TODO: If we go the pb Service route, we might want to carry + // a MethodDescriptor rather than method name + optional string methodName = 5; + + optional uint32 priority = 6; +} + +// RPC Response +message RpcResponse { + optional uint64 callId = 1; + // If present, then an encoded data block follows. + optional EncodedDataBlockMeta encodedDataMeta = 2; + + optional Response response = 3; }