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;
    Filesystem filesystem = 119;
    ExecutionOptions execution_options = 121;
    Command command = 122;
    Spawn spawn = 123;
    GrpcServer grpc_server = 124;
    CanonicalizeFlags canonicalize_flags = 125;
    BuildConfiguration build_configuration = 126;
    InfoCommand info_command = 127;
    MemoryOptions memory_options = 129;
    Query query = 130;
    LocalExecution local_execution = 132;
  }

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

message Interrupted {
  enum Code {
    // Interrupted at an unspecified time.
    INTERRUPTED_UNKNOWN = 0 [(metadata) = { exit_code: 8 }];
    BUILD = 4 [(metadata) = { exit_code: 8 }];
    BUILD_COMPLETION = 5 [(metadata) = { exit_code: 8 }];
    PACKAGE_LOADING_SYNC = 6 [(metadata) = { exit_code: 8 }];
    EXECUTOR_COMPLETION = 7 [(metadata) = { exit_code: 8 }];
    COMMAND_DISPATCH = 8 [(metadata) = { exit_code: 8 }];
    INFO_ITEM = 9 [(metadata) = { exit_code: 8 }];
    AFTER_QUERY = 10 [(metadata) = { exit_code: 8 }];
    reserved 1 to 3; // For internal use
    reserved 11 to 16; // For internal use
  }

  Code code = 1;
}

message Spawn {
  enum Code {
    SPAWN_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    // See the SpawnResult.Status Java enum for definitions of the following
    // Spawn failure codes.
    NON_ZERO_EXIT = 1 [(metadata) = { exit_code: 1 }];
    TIMEOUT = 2 [(metadata) = { exit_code: 1 }];
    // Note: Spawn OUT_OF_MEMORY leads to a BUILD_FAILURE exit_code because the
    // build tool itself did not run out of memory.
    OUT_OF_MEMORY = 3 [(metadata) = { exit_code: 1 }];
    EXECUTION_FAILED = 4 [(metadata) = { exit_code: 1 }];
    EXECUTION_DENIED = 5 [(metadata) = { exit_code: 1 }];
    REMOTE_CACHE_FAILED = 6 [(metadata) = { exit_code: 34 }];
  }
  Code code = 1;

  // For Codes describing generic failure to spawn (eg. EXECUTION_FAILED and
  // EXECUTION_DENIED) the `catastrophic` field may be set to true indicating a
  // failure that immediately terminated the entire build tool.
  bool catastrophic = 2;

  // If Code is NON_ZERO_EXIT, the `spawn_exit_code` field may be set to the
  // non-zero exit code returned by the spawned process to the OS.
  //
  // NOTE: This field must not be confused with the build tool's overall
  // exit code.
  int32 spawn_exit_code = 3;
}

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

// Failure details about Bazel's WORKSPACE features.
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 }];

    // See `managed_directories` in
    // https://docs.bazel.build/versions/master/skylark/lib/globals.html#workspace.
    ILLEGAL_WORKSPACE_FILE_SYMLINK_WITH_MANAGED_DIRECTORIES = 3
        [(metadata) = { exit_code: 1 }];
    WORKSPACE_FILE_READ_FAILURE_WITH_MANAGED_DIRECTORIES = 4
        [(metadata) = { exit_code: 1 }];
  }

  Code code = 1;
}

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

  Code code = 1;
}

message Filesystem {
  enum Code {
    FILESYSTEM_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    DEFAULT_DIGEST_HASH_FUNCTION_CHANGED = 1 [(metadata) = { exit_code: 37 }];
    DEFAULT_DIGEST_HASH_FUNCTION_NOT_SET = 2 [(metadata) = { exit_code: 37 }];
    EMBEDDED_BINARIES_ENUMERATION_FAILURE = 3 [(metadata) = { exit_code: 36 }];
    SERVER_PID_TXT_FILE_READ_FAILURE = 4 [(metadata) = { exit_code: 1 }];
    SERVER_FILE_WRITE_FAILURE = 5 [(metadata) = { exit_code: 1 }];
    DEFAULT_DIGEST_HASH_FUNCTION_INVALID_VALUE = 6
        [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message ExecutionOptions {
  enum Code {
    EXECUTION_OPTIONS_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    reserved 1, 2; // For internal use
  }

  Code code = 1;
}

message Command {
  enum Code {
    // The name "COMMAND_UNKNOWN" might reasonably be interpreted as "command
    // not found". The enum's default value should represent a lack of knowledge
    // about the failure instead.
    COMMAND_FAILURE_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    COMMAND_NOT_FOUND = 1 [(metadata) = { exit_code: 2 }];
    ANOTHER_COMMAND_RUNNING = 2 [(metadata) = { exit_code: 9 }];
    PREVIOUSLY_SHUTDOWN = 3 [(metadata) = { exit_code: 36 }];
    STARLARK_CPU_PROFILE_FILE_INITIALIZATION_FAILURE = 4
        [(metadata) = { exit_code: 36 }];
    STARLARK_CPU_PROFILING_INITIALIZATION_FAILURE = 5
        [(metadata) = { exit_code: 36 }];
    STARLARK_CPU_PROFILE_FILE_WRITE_FAILURE = 6
        [(metadata) = { exit_code: 36 }];
    INVOCATION_POLICY_PARSE_FAILURE = 7 [(metadata) = { exit_code: 2 }];
    INVOCATION_POLICY_INVALID = 8 [(metadata) = { exit_code: 2 }];
    OPTIONS_PARSE_FAILURE = 9 [(metadata) = { exit_code: 2 }];
    STARLARK_OPTIONS_PARSE_FAILURE = 10 [(metadata) = { exit_code: 2 }];
    ARGUMENTS_NOT_RECOGNIZED = 11 [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message GrpcServer {
  enum Code {
    GRPC_SERVER_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    GRPC_SERVER_NOT_COMPILED_IN = 1 [(metadata) = { exit_code: 37 }];
    SERVER_BIND_FAILURE = 2 [(metadata) = { exit_code: 1 }];
    BAD_COOKIE = 3 [(metadata) = { exit_code: 36 }];
    NO_CLIENT_DESCRIPTION = 4 [(metadata) = { exit_code: 36 }];
    reserved 5; // For internal use
  }

  Code code = 1;
}

message CanonicalizeFlags {
  enum Code {
    CANONICALIZE_FLAGS_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    FOR_COMMAND_INVALID = 1 [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

// Failure modes described by this category pertain to the Bazel invocation
// configuration consumed by Bazel's analysis phase. This category is not
// intended as a grab-bag for all Bazel flag value constraint violations, which
// instead generally belong in the category for the subsystem whose flag values
// participate in the constraint.
message BuildConfiguration {
  // TODO(mschaller): many more codes should be added to represent different
  // configuration-related failure modes. See InvalidConfigurationException.
  enum Code {
    BUILD_CONFIGURATION_UNKNOWN = 0 [(metadata) = { exit_code: 2 }];
    PLATFORM_MAPPING_EVALUATION_FAILURE = 1 [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message InfoCommand {
  // The distinction between a failure to write a single info item and a failure
  // to write them all seems sketchy. Why do they have different exit codes?
  // This reflects current Bazel behavior, but deserves more thought.
  enum Code {
    INFO_COMMAND_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    TOO_MANY_KEYS = 1 [(metadata) = { exit_code: 2 }];
    KEY_NOT_RECOGNIZED = 2 [(metadata) = { exit_code: 2 }];
    INFO_BLOCK_WRITE_FAILURE = 3 [(metadata) = { exit_code: 7 }];
    ALL_INFO_WRITE_FAILURE = 4 [(metadata) = { exit_code: 36 }];
  }

  Code code = 1;
}

message MemoryOptions {
  enum Code {
    MEMORY_OPTIONS_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    EXPERIMENTAL_OOM_MORE_EAGERLY_THRESHOLD_INVALID_VALUE = 1
        [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}

message Query {
  enum Code {
    QUERY_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    QUERY_FILE_WITH_COMMAND_LINE_EXPRESSION = 1 [(metadata) = { exit_code: 2 }];
    QUERY_FILE_READ_FAILURE = 2 [(metadata) = { exit_code: 2 }];
    COMMAND_LINE_EXPRESSION_MISSING = 3 [(metadata) = { exit_code: 2 }];
    OUTPUT_FORMAT_INVALID = 4 [(metadata) = { exit_code: 2 }];
    GRAPHLESS_PREREQ_UNMET = 5 [(metadata) = { exit_code: 2 }];
    QUERY_OUTPUT_WRITE_FAILURE = 6 [(metadata) = { exit_code: 36 }];
    QUERY_STDOUT_FLUSH_FAILURE = 13 [(metadata) = { exit_code: 36 }];
    ANALYSIS_QUERY_PREREQ_UNMET = 14 [(metadata) = { exit_code: 2 }];

    reserved 7 to 12; // For internal use
  }

  Code code = 1;
}

message LocalExecution {
  enum Code {
    LOCAL_EXECUTION_UNKNOWN = 0 [(metadata) = { exit_code: 37 }];
    LOCKFREE_OUTPUT_PREREQ_UNMET = 1 [(metadata) = { exit_code: 2 }];
  }

  Code code = 1;
}