// 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.kududb.rpc";

// 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 header for the RPC request frame.
message RequestHeader {
  // A sequence number that is sent back in the Response. 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.
  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;
}

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;

    // 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;
}