src/main/protobuf/failure_details.proto

// Copyright 2020 The Bazel Authors. 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
//
//    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.

// This file's messages describe any failure(s) that occurred during Bazel's
// handling of a request. The intent is to provide more detail to a Bazel client
// than is conveyed with an exit code, to help those clients decide how to
// respond to, or classify, a failure.

syntax = "proto3";

package failure_details;

option java_package = "com.google.devtools.build.lib.server";

import "google/protobuf/descriptor.proto";

message FailureDetailMetadata {
  uint32 exit_code = 1;
}

  extend google.protobuf.EnumValueOptions {
  FailureDetailMetadata metadata = 1078;
}

// The FailureDetail message type is designed such that consumers can extract a
// basic classification of a FailureDetail message even if the consumer was
// built with a stale definition. This forward compatibility is implemented via
// conventions on FailureDetail and its submessage types, as follows.
//
// *** FailureDetail field numbers
//
// Field numbers 1 through 100 (inclusive) are reserved for generally applicable
// values. Any number of these fields may be set on a FailureDetail message.
//
// Field numbers 101 through 10,000 (inclusive) are reserved for use inside the
// "oneof" structure. Only one of these values should be set on a FailureDetail
// message.
//
// Additional fields numbers are unlikely to be needed, but, for extreme future-
// proofing purposes, field numbers 10,001 through 1,000,000 (inclusive;
// excluding protobuf's reserved range 19000 through 19999) are reserved for
// additional generally applicable values.
//
// *** FailureDetail's "oneof" submessages
//
// Each field in the "oneof" structure is a submessage corresponding to a
// category of failure.
//
// In each of these submessage types, field number 1 is an enum whose values
// correspond to a subcategory of the failure. Generally, the enum's constant
// which maps to 0 should be interpreted as "unspecified", though this is not
// required.
//
// *** Recommended forward compatibility strategy
//
// The recommended forward compatibility strategy is to reduce a FailureDetail
// message to a pair of integers.
//
// The first integer corresponds to the field number of the submessage set
// inside FailureDetail's "oneof", which corresponds with the failure's
// category.
//
// The second integer corresponds to the value of the enum at field number 1
// within that submessage, which corresponds with the failure's subcategory.
//
// WARNING: This functionality is experimental and should not be relied on at
// this time.
// TODO(mschaller): remove experimental warning
message FailureDetail {
  // A short human-readable message describing the failure, for debugging.
  //
  // This value is *not* intended to be used algorithmically.
  string message = 1;

  // Reserved for future generally applicable values. Any of these may be set.
  reserved 2 to 100;

  oneof category {
    Interrupted interrupted = 101;
    ExternalRepository external_repository = 103;
    BuildProgress build_progress = 104;
    RemoteOptions remote_options = 106;
    ClientEnvironment client_environment = 107;
    Crash crash = 108;
    SymlinkForest symlink_forest = 110;
    PackageOptions package_options = 114;
    RemoteExecution remote_execution = 115;
    Execution execution = 116;
    Workspaces workspaces = 117;
    CrashOptions crash_options = 118;
  }

  reserved 102; // For internal use
  reserved 105; // For internal use
  reserved 109; // For internal use
  reserved 111 to 113; // For internal use
}

message Interrupted {
  enum Code {
    // Interrupted at an unspecified time.
    INTERRUPTED_UNKNOWN = 0 [(metadata) = { exit_code: 8 }];

    reserved 1, 2; // For internal use

    // TODO(mschaller): Add subcategories that specify what was happening at the
    //  time of interruption.
  }

  Code code = 1;
}

message ExternalRepository {
  enum Code {
    EXTERNAL_REPOSITORY_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    OVERRIDE_DISALLOWED_MANAGED_DIRECTORIES = 1 [(metadata) = { exit_code: 2 }];
  }
  Code code = 1;
  // Additional data could include external repository names.
}

message BuildProgress {
  enum Code {
    BUILD_PROGRESS_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    OUTPUT_INITIALIZATION = 3 [(metadata) = { exit_code: 36 }];
    BES_RUNS_PER_TEST_LIMIT_UNSUPPORTED = 4 [(metadata) = { exit_code: 2 }];
    BES_LOCAL_WRITE_ERROR = 5 [(metadata) = { exit_code: 36 }];
    BES_INITIALIZATION_ERROR = 6 [(metadata) = { exit_code: 36 }];
    BES_UPLOAD_TIMEOUT_ERROR = 7 [(metadata) = { exit_code: 38 }];
    BES_FILE_WRITE_TIMEOUT = 8 [(metadata) = { exit_code: 38 }];
    BES_FILE_WRITE_IO_ERROR = 9 [(metadata) = { exit_code: 38 }];
    BES_FILE_WRITE_INTERRUPTED = 10 [(metadata) = { exit_code: 38 }];
    BES_FILE_WRITE_CANCELED = 11 [(metadata) = { exit_code: 38 }];
    BES_FILE_WRITE_UNKNOWN_ERROR = 12 [(metadata) = { exit_code: 38 }];
    BES_UPLOAD_LOCAL_FILE_ERROR = 13 [(metadata) = { exit_code: 38 }];
    BES_STREAM_NOT_RETRYING_FAILURE = 14 [(metadata) = { exit_code: 45 }];
    BES_STREAM_COMPLETED_WITH_UNACK_EVENTS_ERROR = 15
        [(metadata) = { exit_code: 45 }];
    BES_STREAM_COMPLETED_WITH_UNSENT_EVENTS_ERROR = 16
        [(metadata) = { exit_code: 45 }];
    BES_UPLOAD_RETRY_LIMIT_EXCEEDED_FAILURE = 17
        [(metadata) = { exit_code: 38 }];
    reserved 1, 2; // For internal use
  }
  Code code = 1;
  // Additional data could include the build progress upload endpoint.
}

message RemoteOptions {
  enum Code {
    REMOTE_OPTIONS_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    REMOTE_DEFAULT_EXEC_PROPERTIES_LOGIC_ERROR = 1
        [(metadata) = { exit_code: 2 }];
    // Credentials could not be read from the requested file/socket/process/etc.
    CREDENTIALS_READ_FAILURE = 2 [(metadata) = { exit_code: 36 }];
    // Credentials could not be written to a shared, temporary file.
    CREDENTIALS_WRITE_FAILURE = 3 [(metadata) = { exit_code: 36 }];
    DOWNLOADER_WITHOUT_GRPC_CACHE = 4 [(metadata) = { exit_code: 2 }];
    EXECUTION_WITH_INVALID_CACHE = 5 [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message ClientEnvironment {
  enum Code {
    CLIENT_ENVIRONMENT_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    CLIENT_CWD_MALFORMED = 1 [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message Crash {
  enum Code {
    CRASH_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    CRASH_OOM = 1 [(metadata) = { exit_code: 33 }];
  }

  Code code = 1;

  // The cause chain of the crash, with the outermost throwable first. Limited
  // to the outermost exception and at most 4 nested causes (so, max size of 5).
  repeated Throwable causes = 2;
}

message Throwable {
  // The class name of the java.lang.Throwable.
  string throwable_class = 1;
  // The throwable's message.
  string message = 2;
  // The result of calling toString on the deepest (i.e. closest to the
  // throwable's construction site) 1000 (or fewer) StackTraceElements.
  // Unstructured to simplify string matching.
  repeated string stack_trace = 3;
}

message SymlinkForest {
  enum Code {
    SYMLINK_FOREST_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    TOPLEVEL_OUTDIR_PACKAGE_PATH_CONFLICT = 1 [(metadata) = { exit_code: 2 }];
    TOPLEVEL_OUTDIR_USED_AS_SOURCE = 2 [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message PackageOptions {
  enum Code {
    PACKAGE_OPTIONS_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    PACKAGE_PATH_INVALID = 1 [(metadata) = { exit_code: 2 }];
    reserved 2; // For internal use
  }

  Code code = 1;
}

message RemoteExecution {
  // The association of some of these options with exit code 2, "command line
  // error", seems sketchy. Especially worth reconsidering are the channel init
  // failure modes, which can correspond to failures occurring in gRPC setup.
  // These all correspond with current Bazel behavior.
  enum Code {
    REMOTE_EXECUTION_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    CAPABILITIES_QUERY_FAILURE = 1 [(metadata) = { exit_code: 34 }];
    CREDENTIALS_INIT_FAILURE = 2 [(metadata) = { exit_code: 2 }];
    CACHE_INIT_FAILURE = 3 [(metadata) = { exit_code: 2 }];
    RPC_LOG_FAILURE = 4 [(metadata) = { exit_code: 2 }];
    EXEC_CHANNEL_INIT_FAILURE = 5 [(metadata) = { exit_code: 2 }];
    CACHE_CHANNEL_INIT_FAILURE = 6 [(metadata) = { exit_code: 2 }];
    DOWNLOADER_CHANNEL_INIT_FAILURE = 7 [(metadata) = { exit_code: 2 }];
    LOG_DIR_CLEANUP_FAILURE = 8 [(metadata) = { exit_code: 36 }];
    CLIENT_SERVER_INCOMPATIBLE = 9 [(metadata) = { exit_code: 34 }];
    DOWNLOADED_INPUTS_DELETION_FAILURE = 10 [(metadata) = { exit_code: 34 }];
    REMOTE_DOWNLOAD_OUTPUTS_MINIMAL_WITHOUT_INMEMORY_DOTD = 11
        [(metadata) = { exit_code: 2 }];
    REMOTE_DOWNLOAD_OUTPUTS_MINIMAL_WITHOUT_INMEMORY_JDEPS = 12
        [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message Execution {
  enum Code {
    EXECUTION_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    EXECUTION_LOG_INITIALIZATION_FAILURE = 1 [(metadata) = { exit_code: 2 }];
    EXECUTION_LOG_WRITE_FAILURE = 2 [(metadata) = { exit_code: 36 }];
  }

  Code code = 1;
}

message Workspaces {
  enum Code {
    WORKSPACES_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    WORKSPACES_LOG_INITIALIZATION_FAILURE = 1 [(metadata) = { exit_code: 2 }];
    WORKSPACES_LOG_WRITE_FAILURE = 2 [(metadata) = { exit_code: 36 }];
  }

  Code code = 1;
}

message CrashOptions {
  enum Code {
    CRASH_OPTIONS_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    reserved 1; // For internal use
  }

  Code code = 1;
}