protobuf/api/urlfetch_service.proto

/*
 * Copyright 2021 Google LLC
 *
 * 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.
 */

// Copyright 2007 Google Inc.
// All Rights Reserved.
//
// The URLFetch service downloads external HTTP URLs using Harpoon and some
// internal URLs using HTTPOverRpc.
// See:
//   https://cloud.google.com/appengine/docs/python/urlfetch/
//   <internal15>

syntax = "proto2";

// Some generic_services option(s) added automatically.
// See:  http://go/proto2-generic-services-default
package java.apphosting;

option java_generic_services = true;  // auto-added
option java_package = "com.google.appengine.api.urlfetch";
option java_outer_classname = "URLFetchServicePb";

message URLFetchServiceError {
  enum ErrorCode {
    OK = 0;
    INVALID_URL = 1;
    FETCH_ERROR = 2;
    UNSPECIFIED_ERROR = 3;
    RESPONSE_TOO_LARGE = 4;
    DEADLINE_EXCEEDED = 5;
    SSL_CERTIFICATE_ERROR = 6;
    DNS_ERROR = 7;
    CLOSED = 8;
    INTERNAL_TRANSIENT_ERROR = 9;
    TOO_MANY_REDIRECTS = 10;
    MALFORMED_REPLY = 11;
    CONNECTION_ERROR = 12;
    PAYLOAD_TOO_LARGE = 13;
  }
}

message URLFetchRequest {
  enum RequestMethod {
    GET = 1;
    POST = 2;
    HEAD = 3;
    PUT = 4;
    DELETE = 5;
    PATCH = 6;
  }
  required RequestMethod Method = 1;
  required string Url = 2;
  repeated group Header = 3 {
    required string Key = 4;
    required string Value = 5;
  }
  // Only specify a payload for POST, PUT and PATCH requests
  optional bytes Payload = 6 [ctype = CORD];

  // If false, Fastnet will return the real HTTP redirect status code.
  // (this is required for e.g. OpenID RP implementations).  By
  // default, or when this is true, Prometheus sets this to something
  // like 5, but hides the redirect chain from the end user and any
  // eventual successful fetch results in a 200 OK.
  //
  // NOTE: For historical reasons this must be set to false to permit
  // the use of HttpOverRpc back to App Engine. b/22785370
  optional bool FollowRedirects = 7 [default = true];

  // The timeout for the request in seconds.
  optional double Deadline = 8;

  // If true, Harpoon will drop the connection and fail the request if it
  // encounters an invalid certificate.
  // WARNING: Do not rely on the default value of this field for certificate
  // validation. There is an appserver flag that applies if the default value
  // is used (urlfetch_harpoon_failonsslcertificateerror_default) which is
  // currently (as of August 2015) set to false. If you want certificate
  // validation then always set the value of this field to true. b/1829826
  optional bool MustValidateServerCertificate = 9 [default = true];
}

message URLFetchResponse {
  optional bytes Content = 1;
  required int32 StatusCode = 2;
  repeated group Header = 3 {
    // Keys are not guaranteed to be unique across all Headers belonging
    // to a single URLFetchResponse. There could be multiple Headers with
    // the same name.
    required string Key = 4;
    required string Value = 5;
  }
  optional bool ContentWasTruncated = 6 [default = false];
  optional int64 ExternalBytesSent = 7;
  optional int64 ExternalBytesReceived = 8;

  // The final URL retrieved, if any redirects were followed. Will not
  // be present if the retrieved URL matches the requested URL (or redirects
  // are not followed).
  optional string FinalUrl = 9;

  // Quota used by the recipient app in fulfilling an api request.
  optional int64 ApiCpuMilliseconds = 10 [default = 0];
  optional int64 ApiBytesSent = 11 [default = 0];
  optional int64 ApiBytesReceived = 12 [default = 0];
}