protobuf/appinfo.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.
 */

// LINT: ALLOW_GROUPS

syntax = "proto2";

package java.apphosting;

option cc_enable_arenas = true;

option java_package = "com.google.apphosting.base.protos";
option java_outer_classname = "AppinfoPb";

// next-id: 17
message Handler {
  // Specifies what sort of endpoint this is, which indicates how to
  // handle it. Static file and cgi-bin are good examples. Some options
  // may be language specific.
  enum HANDLERTYPE {
    STATIC = 0;
    CGI_BIN = 1;
    //    SERVLET = 2; // DEPRECATED
    SHUTDOWN = 3;
  }
  optional int32 type = 1 [default = 1];  // Not really optional.

  // might be a file or a class name
  required string path = 2;
}

// Description of an application version. In the eyes of the
// AppServer, each version is basically a different app.
//
// AppInfos are immutable--they are not to be changed once created. If you
// need to add per-version data that can be changed while the version is
// running, use PerVersionConfig.
//
// Next Tag: 107
message AppInfo {
  // When deleting fields, update this list. See
  // https://developers.google.com/protocol-buffers/docs/proto#reserved for
  // more info. Keep each field on a separate line to maintain Blame history.
  // clang-format off
  reserved
    88;
  // clang-format on

  required string app_id = 1;

  // This field encodes the version ID for this AppInfo. Due to historical
  // reasons, this field can have two different formats, depending on the
  // context. There is a storage format and a wire format. The storage format
  // is the format that is generated when the AppInfo is written to
  // storage. All subsequent reads for an already-created AppInfo use this
  // format. The wire format is used by clients wishing to commit an AppInfo
  // to persistent storage. We discuss these formats below.
  //
  // The storage format:
  // -------------------
  //
  // The storage format is of the form
  // [SERVICE_ID:]MAJOR_VERSION.MINOR_VERSION. Examples include
  // "1.370530032149909029" and "my-service:1.370530032149909029".
  //
  // SERVICE_ID is the name of the service to which this version belongs. For
  // versions that are deployed to the "default" service, SERVICE_ID is not
  // populated. Internally, services have also been referred to as modules and
  // engines.
  //
  // MAJOR_VERSION is a user-chosen string value, which happens to have some
  // common values. The common values are "1" and the current time in the form
  // YYYYMMDDthhmmss (e.g., "20170221t120140"). MAJOR_VERSION can be provided
  // in app.yaml as the "version" field, or using the --version flag in
  // "gcloud app deploy". If the version is deployed using gcloud, and no
  // version is provided, gcloud generates one based on the current time in
  // the format YYYYMMDDthhmmss. "1" happens to be a common value because our
  // getting started documents that predate gcloud suggested using "1".
  //
  // Finally, MINOR_VERSION is an unsigned 64 bit integer, represented in its
  // base-10 string form. This integer has the following properties:
  //
  //   1) Its 28 least-significant bits are randomly generated by the server
  //      committing the AppInfo to storage.
  //
  //   2) Its 36 most-significant bits represent the time around which the
  //      server committed the AppInfo to storage, in seconds since Epoch.
  //
  // The MINOR_VERSION format is *very* important. Many parts of our system
  // rely on the ordering that is produced when sorting all minor versions
  // within a major version. This ordering ensures that only the last deployed
  // minor version is served, so we should probably never change the format of
  // the minor version.
  //
  // The wire format:
  // ----------------
  //
  // The wire format is the same as the storage format minus the
  // MINOR_VERSION: [SERVICE_ID:]MAJOR_VERSION. Examples include "1" and
  // "my-service:1".
  //
  // The minor version is missing from the wire format because it is the
  // responsibility of AppConfigService implementation to generate the minor
  // version based on the current time. If a client populates the
  // MINOR_VERSION portion of version_id when creating an AppInfo, the
  // AppConfigService implementation should discard it and generate its own
  // MINOR_VERSION.
  //
  // *  *  *
  //
  // Interested in more? See http://go/app-engine-ids.
  optional string version_id = 2 [default = "1"];

  // Time at which this AppInfo was written, in microseconds. This field should
  // only be modified by the app_config_service jobs, as it is critical to
  // operation of both schedulers:
  // 1. CloneScheduler uses timestamp_usec to determine whether the AppInfo is
  // newer than the GlobalConfig or vice versa (e.g. when determining instance
  // class);
  // 2. AppMaster2 uses timestamp_usec to determine whether an AppInfo was
  // recently written (i.e. when deciding whether a config update warrants a
  // zero-load ServingState expiration extension).
  optional int64 timestamp_usec = 90;

  // Not really optional.
  optional string runtime_id = 4 [default = "python"];  // java, etc.
  // N.B.(kgibbs): Might need optional PB's for each runtime type to specify
  // things like garbage collection policies

  // Optional string that can be used to indicate a specialization within
  // the runtime_id. For example, this field can be used to specialize
  // within the runtime_id:container runtime.
  //
  // Important: This field should be populated only on consultation with
  // the appengine<internal> team.
  optional string runtime_specialization = 78;

  // Enable App Engine APIs on Second Generation go/gen2-wormhole-phase-1
  optional bool gen2_app_engine_apis = 102;

  // The instance class of this app version. Taken from version_config (for
  // frontends) or server_config (for backends). Currently populated only in
  // AppInfoLite messages (i.e. is_appinfo_lite is true) via ReduceAppInfo. This
  // field is used by Clone Scheduler when scheduling newly deployed versions.
  //
  // TODO: Consider populating this field directly, in Zeus.
  optional int32 instance_class = 91;

  // Major API version to use for this application.
  optional string api_version = 28 [default = ""];

  // This should not be specified in the app.cfg file; it is computed
  // automatically by appcfg.
  //
  // All files will live in bigtable and will be indexed by their
  // sha1_hash.  An AppServer can recreate the app's directory structure
  // from each file's 'path'.  The AppServer will copy any required
  // files from bigtable to a shared directory on the machine.  It will
  // then create a tree of symlinks to reflect the directory structure
  // that the developer created.  This common directory will allow sharing
  // of common files between apps.
  repeated group File = 6 {
    required string sha1_hash = 7;
    required string path = 8;
    required int64 file_size = 14;  // file size in bytes

    // If non-empty, we will use this as the mime type. If empty, we will derive
    // the mime type from the file extension of 'path'.
    //
    // N.B.(jonmac): This field is deprecated. Instead, static files should be
    // included in Blob below.
    optional string mime_type = 15 [default = ""];

    // The URL source where this file was fetched. This is populated
    // for versions deployed through the Admin API. See
    // http://cs/#piper///depot/google3/google/appengine/v1/deploy.proto?rcl=181115158&l=73
    // for more details.
    optional string source_url = 71;
  }

  // This should not be specified in the app.cfg file; it is computed
  // automatically by appcfg.
  //
  // All blobs will live in Blobstore. As opposed to files, they will not be
  // made available to runtimes through a shared directory on the
  // machine. Instead, blobs are for listing files that should be served as
  // static content.
  //
  // When specifying blobs here, the expected procedure is that the client
  // (e.g. appcfg) will first generate a BlobRef using AppConfigService. Then,
  // the client will include the returned BlobRef here. Garbage collection of
  // blobs will be handled by Prometheus and Blobstore. Sharing of common data
  // between blobs (e.g. duplicate blobs) will be handled by Blobstore.
  repeated group Blob = 16 {
    // Used to support matching from Handler::path().
    required string path = 18;

    // If non-empty, the mime_type of the blob.
    optional string mime_type = 35;
  }

  // The regular expressions in this list are applied in order to the request
  // URL until one matches, and then the associated handler will be used to
  // process the request.
  repeated group URLMap = 9 {
    // Either 'regex' and 'handler' must both be specified, or 'static_dir' must
    // be specified. Never all three. From app_config_service down this must
    // contain both 'regex' and 'handler'.

    optional string regex = 10;
    optional Handler handler = 11;

    // For use in app.cfg only.
    //
    // This URLMap entry will be converted to serve static files from the
    // specified directory, and we will additionally update StaticFileMap to
    // consider all files in this directory as static files. More details at:
    // http://g3doc/apphosting/g3doc/wiki-carryover/urlmap_change.md.
    optional string static_dir = 30;

    // If true, this URLMap entry does not match the request unless
    // the file referenced by the handler also exists.  If no such
    // file exists, processing will continue with the next URLMap that
    // matches the requested URL.
    //
    // This field is useful for applications that want to match a
    // static file first (with a STATIC handler), but to continue on
    // with dynamic processing if no static file matches.
    //
    // N.B.(schwardo): This functionality was added to facilitate
    // dynamic translation of web.xml files for the Java runtime, and
    // there are no plans to expose this to Python applications at
    // this time.
    optional bool require_matching_file = 36 [default = false];
  }

  // N.B.(schwardo): I wrapped this field an optional group to prevent
  // an incompatibility when Python model process has this change but
  // the Admin Console does not.  Repeated fields in Python PB's don't
  // like skew between their Python classes and swig library.
  // These values must be kept in sync with those of DerivedFile::Type.
  optional group DerivedFiles = 39 {
    enum DerivedFileType {
      // Precompiled java bytecode.
      JAVA_PRECOMPILED = 1;
      // Precompiled Python bytecode.
      PYTHON_PRECOMPILED = 2;
      // Compiled Go binary.
      GO_BINARY = 3;
    }
    repeated DerivedFileType derived_file_type = 40;
  }

  // User defined environment variables to be set in each request.
  message EnvironmentVariable {
    required string name = 1;
    required string value = 2;
  }
  repeated EnvironmentVariable environment_variable = 61;
}