| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| |
| option optimize_for = SPEED; |
| |
| package kudu.rpc; |
| |
| option java_package = "org.apache.kudu.rpc"; |
| |
| import "google/protobuf/descriptor.proto"; |
| |
| // The Kudu RPC protocol is similar to the RPC protocol of Hadoop and HBase. |
| // See the following for reference on those other protocols: |
| // - https://issues.apache.org/jira/browse/HBASE-7898 |
| // - https://issues.apache.org/jira/browse/HADOOP-8990 |
| // |
| // For a description of the Kudu protocol, see 'README' in this directory. |
| |
| // User Information proto. Included in ConnectionContextPB on connection setup. |
| message UserInformationPB { |
| optional string effective_user = 1; |
| required string real_user = 2; |
| } |
| |
| /** |
| * The connection context is sent as part of the connection establishment. |
| * It establishes the context for ALL RPC calls within the connection. |
| * This is sent on connection setup after the connection preamble is sent |
| * and SASL has been negotiated. |
| * No response is sent from the server to the client. |
| */ |
| message ConnectionContextPB { |
| // UserInfo beyond what is determined as part of security handshake |
| // at connection time (kerberos, tokens etc). |
| optional UserInformationPB user_info = 2; |
| } |
| |
| // Features supported by the RPC system itself. |
| // |
| // Note that this should be used to evolve the RPC _system_, not the semantics |
| // or compatibility of individual calls. |
| // |
| // For example, if we were to add a feature like call or response wire |
| // compression in the future, we could add a flag here to indicate that the |
| // client or server supports that feature. Optional features which may safely be |
| // ignored by the receiver do not need a feature flag, instead the optional |
| // field feature of ProtoBuf may be utilized. |
| enum RpcFeatureFlag { |
| UNKNOWN = 0; |
| |
| // The RPC system is required to support application feature flags in the |
| // request and response headers. |
| APPLICATION_FEATURE_FLAGS = 1; |
| }; |
| |
| // Message type passed back & forth for the SASL negotiation. |
| message SaslMessagePB { |
| enum SaslState { |
| UNKNOWN = 999; |
| SUCCESS = 0; |
| NEGOTIATE = 1; |
| INITIATE = 2; |
| CHALLENGE = 3; |
| RESPONSE = 4; |
| } |
| |
| message SaslAuth { |
| optional string method = 1; // Deprecated, but was 'required' in Kudu 0.5.0 and 0.6.0. |
| required string mechanism = 2; // Standard SASL mechanism, i.e. ANONYMOUS, PLAIN, GSSAPI. |
| |
| // SASL challenge token from server, if the client chooses to use this method. |
| // Only used when the server is piggy-backing a challenge on a NEGOTIATE response. |
| // Otherwise, SaslMessagePB::token is used as the challenge token. |
| optional bytes challenge = 5; |
| } |
| |
| // When the client sends its first NEGOTIATE message, it sends its set of supported |
| // RPC system features. In the response to this message, the server sends back its own. |
| // This allows the two peers to agree on whether newer extensions of the |
| // RPC system may be used on this connection. We use a list of features rather than |
| // a simple version number to make it easier for the Java and C++ clients to implement |
| // features in different orders while still maintaining compatibility, as well as |
| // to simplify backporting of features out-of-order. |
| repeated RpcFeatureFlag supported_features = 1; |
| |
| required SaslState state = 2; // RPC system SASL state. |
| optional bytes token = 3; |
| repeated SaslAuth auths = 4; |
| } |
| |
| message RemoteMethodPB { |
| // Service name for the RPC layer. |
| // The client created a proxy with this service name. |
| // Example: kudu.rpc_test.CalculatorService |
| required string service_name = 1; |
| |
| // Name of the RPC method. |
| required string method_name = 2; |
| }; |
| |
| // The Id of a retriable RPC, whose results should be tracked on the server (see result_tracker.h). |
| // This also includes some information that is useful for execution/garbage collection. |
| message RequestIdPB { |
| // The (globally unique) id of the client performing this RPC. |
| required string client_id = 1; |
| |
| // The (per-client unique) sequence number of this RPC. |
| required int64 seq_no = 2; |
| |
| // The sequence number of the first RPC that has not been marked as completed by the client. |
| // Unset if there isn't an incomplete RPC. |
| required int64 first_incomplete_seq_no = 3; |
| |
| // The number of times this RPC has been tried. |
| // Set to 1 in the first attempt. |
| required int64 attempt_no = 4; |
| } |
| |
| // The header for the RPC request frame. |
| message RequestHeader { |
| // A sequence number that uniquely identifies a call to a single remote server. This number is |
| // sent back in the Response and allows to match it to the original Request. |
| // Hadoop specifies a uint32 and casts it to a signed int. That is counterintuitive, so we use an |
| // int32 instead. Allowed values (inherited from Hadoop): |
| // 0 through INT32_MAX: Regular RPC call IDs. |
| // -2: Invalid call ID. |
| // -3: Connection context call ID. |
| // -33: SASL negotiation call ID. |
| // |
| // NOTE: these calls must be increasing but may have gaps. |
| required int32 call_id = 3; |
| |
| // RPC method being invoked. |
| // Not used for "connection setup" calls. |
| optional RemoteMethodPB remote_method = 6; |
| |
| // Propagate the timeout as specified by the user. Note that, since there is some |
| // transit time between the client and server, if you wait exactly this amount of |
| // time and then respond, you are likely to cause a timeout on the client. |
| optional uint32 timeout_millis = 10; |
| |
| // Feature flags that the service must support in order to properly interpret this |
| // request. The client can pass any set of flags, and if the server doesn't |
| // support any of them, then it will fail the request. |
| // |
| // NOTE: these are for evolving features at the level of the application, not |
| // the RPC framework. Hence, we have to use a generic int type rather than a |
| // particular enum. |
| // NOTE: the server will only interpret this field if it supports the |
| // APPLICATION_FEATURE_FLAGS flag. |
| repeated uint32 required_feature_flags = 11; |
| |
| // The unique id of this request, if it's retriable and if the results are to be tracked. |
| // The request id is unique per logical request, i.e. retries of the same RPC must have the |
| // same request id. |
| // Note that this is different from 'call_id' in that a call_id is unique to a server while a |
| // request_id is unique to a logical request (i.e. the request_id remains the same when a request |
| // is retried on a different server). |
| // Optional for requests that are naturally idempotent or to maintain compatibility with |
| // older clients for requests that are not. |
| optional RequestIdPB request_id = 15; |
| } |
| |
| message ResponseHeader { |
| required int32 call_id = 1; |
| |
| // If this is set, then this is an error response and the |
| // response message will be of type ErrorStatusPB instead of |
| // the expected response type. |
| optional bool is_error = 2 [ default = false ]; |
| |
| // Byte offsets for side cars in the main body of the response message. |
| // These offsets are counted AFTER the message header, i.e., offset 0 |
| // is the first byte after the bytes for this protobuf. |
| repeated uint32 sidecar_offsets = 3; |
| |
| } |
| |
| // Sent as response when is_error == true. |
| message ErrorStatusPB { |
| |
| // These codes have all been inherited from Hadoop's RPC mechanism. |
| enum RpcErrorCodePB { |
| FATAL_UNKNOWN = 10; |
| |
| // Non-fatal RPC errors. Connection should be left open for future RPC calls. |
| //------------------------------------------------------------ |
| // The application generated an error status. See the message field for |
| // more details. |
| ERROR_APPLICATION = 1; |
| |
| // The specified method was not valid. |
| ERROR_NO_SUCH_METHOD = 2; |
| |
| // The specified service was not valid. |
| ERROR_NO_SUCH_SERVICE = 3; |
| |
| // The server is overloaded - the client should try again shortly. |
| ERROR_SERVER_TOO_BUSY = 4; |
| |
| // The request parameter was not parseable, was missing required fields, |
| // or the server does not support the required feature flags. |
| ERROR_INVALID_REQUEST = 5; |
| |
| // The server might have previously received this request but its response is no |
| // longer cached. It's unknown whether the request was executed or not. |
| ERROR_REQUEST_STALE = 6; |
| |
| // FATAL_* errors indicate that the client should shut down the connection. |
| //------------------------------------------------------------ |
| // The RPC server is already shutting down. |
| FATAL_SERVER_SHUTTING_DOWN = 11; |
| // Fields of RpcHeader are invalid. |
| FATAL_INVALID_RPC_HEADER = 12; |
| // Could not deserialize RPC request. |
| FATAL_DESERIALIZING_REQUEST = 13; |
| // IPC Layer version mismatch. |
| FATAL_VERSION_MISMATCH = 14; |
| // Auth failed. |
| FATAL_UNAUTHORIZED = 15; |
| } |
| |
| required string message = 1; |
| |
| // TODO: Make code required? |
| optional RpcErrorCodePB code = 2; // Specific error identifier. |
| |
| // If the request is failed due to an unsupported feature flag, the particular |
| // flag(s) that were not supported will be sent back to the client. |
| repeated uint32 unsupported_feature_flags = 3; |
| |
| // Allow extensions. When the RPC returns ERROR_APPLICATION, the server |
| // should also fill in exactly one of these extension fields, which contains |
| // more details on the service-specific error. |
| extensions 100 to max; |
| } |
| |
| // An option for RPC methods that allows to set whether that method's |
| // RPC results should be tracked with a ResultTracker. |
| extend google.protobuf.MethodOptions { |
| optional bool track_rpc_result = 50006 [default=false]; |
| } |