remote_api.proto

// Copyright 2008 Google Inc. All Rights Reserved.
//
// Licensed 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
//
//     https://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.
//

//
// Container types for App Engine's public rpc-over-http interface.
//
// These containers are used for at least three different purposes, which are
// not always compatible:
// 1. Interfacing remotely with the AppEngine APIs (from e.g. a user's desktop)
//    by going through a special handler on the app. See
//    https://developers.google.com/appengine/articles/remote_api
// 2. In the devappserver to make API calls from the app to the local API
//    server.
// 3. Issuing API calls from a VM runtime to a proxy endpoint on the
//    appserver. Also in the near-ish future, some API calls might go to a
//    local API server on the VM.
//
// Once gRPC takes shape, that protocol will likely replace most of this file.

syntax = "proto2";


package apphosting.ext.remote_api;
option java_package = "com.google.apphosting.utils.remoteapi";
option java_outer_classname = "RemoteApiPb";
option go_package = "remote_api";

message Request {
  required string service_name = 2;
  required string method = 3;
  // Contains the serialized service-specific protobuf
  required bytes request = 4;
  optional string request_id = 5;
}

message ApplicationError {
  required int32 code = 1;
  required string detail = 2;
}

// Transport-level RPC errors adapted from runtime.proto
message RpcError {
  enum ErrorCode {
    UNKNOWN = 0;
    CALL_NOT_FOUND = 1;
    PARSE_ERROR = 2;
    SECURITY_VIOLATION = 3;
    OVER_QUOTA = 4;
    REQUEST_TOO_LARGE = 5;
    CAPABILITY_DISABLED = 6;
    FEATURE_DISABLED = 7;
    BAD_REQUEST = 8;
    RESPONSE_TOO_LARGE = 9;
    CANCELLED = 10;
    REPLAY_ERROR = 11;
    DEADLINE_EXCEEDED = 12;
  }
  required int32 code = 1;  // Should contain an ErrorCode
  optional string detail = 2;
}

message Response {
  // Exactly one of the fields 'response', 'exception', 'java_exception' and
  // 'rpc_error' should be set. If 'exception' or 'java_exception' is set,
  // 'application_error' will also be set if the exception was generated due to
  // RPC::ApplicationError being set.
  //
  // The remote access feature described above (1) and the devappserver (2)
  // use 'exception' and 'java_exception' to specify error responses.
  // 'exception' is a pickled python exception object. 'java_exception' is a
  // serialized java exception object. Remote access (1) also uses
  // 'application_error' for datastore errors.
  //
  // For VM runtimes (3), transport-layer errors are passed in 'rpc_error' and
  // application-layer errors in 'application_error'. The 'exception' and
  // 'java_exception' fields are unused in this context.
  //
  // For cross-language maintainability, it is probably best to avoid
  // using 'exception' and 'java_exception' in new code.
  optional bytes response = 1;
  optional bytes exception = 2;
  optional ApplicationError application_error = 3;
  optional bytes java_exception = 4;
  optional RpcError rpc_error = 5;
}

option optimize_for = LITE_RUNTIME;