github.phpd.cn/thought-machine/please@v12.2.0+incompatible/src/follow/proto/build_event.proto

// Defines the remote streaming protocol for build events.
syntax = "proto3";

package proto.build_event;

service PlzEvents {
    // Receives information about the state of the server's configuration.
    rpc ServerConfig(ServerConfigRequest) returns (ServerConfigResponse);
    // Receives build events from the remote server.
    rpc BuildEvents(BuildEventRequest) returns (stream BuildEventResponse);
    // Receives a stream of information about the server's resource usage.
    rpc ResourceUsage(ResourceUsageRequest) returns (stream ResourceUsageResponse);
}

message ServerConfigRequest{
}

message ServerConfigResponse{
    // The total number of threads that the server is configured to run.
    int32 num_threads = 1;
    // The original targets that the server was requested to run.
    repeated BuildLabel original_targets = 2;
    // True if the server is running tests.
    bool tests = 3;
    // True if the server is running test coverage.
    bool coverage = 4;
    // The most recent event for each server thread.
    // May be shorter than num_threads since some threads may not have had an event yet.
    repeated BuildEventResponse last_events = 5;
    // The time that the build started, as nanoseconds since 1970.
    int64 start_time = 6;
}

message BuildEventRequest{
}

message BuildEventResponse{
    // Internal id of the thread (goroutine, really) that generated this event.
    // These can be used to chain together consecutive events by the same worker.
    // Ids are guaranteed to be allocated sequentially, starting from 0 and are
    // strictly less than num_threads in the corresponding ServerConfigResponse.
    // You aren't necessarily guaranteed to observe events on any or all threads
    // though.
    int32 thread_id = 1;
    // Timestamp of this event, in nanoseconds since the Unix epoch.
    int64 timestamp = 2;
    // Build label that this event relates to.
    BuildLabel build_label = 3;
    // Status of the build.
    BuildResultStatus status = 4;
    // Error, only populated for failure statuses.
    string error = 5;
    // Description of what's going on.
    string description = 6;
    // If the target was a test, this will contain the results of it.
    TestResults test_results = 7;
    // Labels of the target
    repeated string labels = 8;
    // Number of tasks that are currently "activated", i.e. to be done before the build ends.
    // These are somewhat nebulously defined but can provide a measure of progress, as long as
    // you don't mind this number increasing through the build, tasks taking wildly different
    // amounts of time, and that there isn't a 1:1 correspondence between tasks and these messages.
    int64 num_active = 9;
    // Number of tasks that have been completed so far.
    int64 num_done = 10;
}

message BuildLabel{
    string package_name = 1;
    string name = 2;
}

// A BuildResultStatus describes what has just happened in the event.
enum BuildResultStatus {
    // Build result is unknown. In normal operation this is never set.
    Unknown = 0;
    // Please is beginning to parse a package.
    PackageParsing = 1;
    // The package has been parsed successfully.
    PackageParsed = 2;
    // The package has been parsed, but it failed.
    ParseFailed = 3;
    // Please has started building a target.
    TargetBuilding = 4;
    // Please has reached a target, and the input flags requested it to stop here
    // i.e. the request was something like plz build --prepare or --shell etc
    //      which precludes continuing to actually build the target.
    //      This is not a failure state.
    TargetBuildStopped = 5;
    // The target has been successfully built.
    TargetBuilt = 6;
    // The target was built by retrieving it from the disk, remote or other cache.
    TargetCached = 7;
    // The build of the target failed.
    TargetBuildFailed = 8;
    // Please is beginning to test a target.
    TargetTesting = 9;
    // The target has finished testing and all tests passed.
    TargetTested = 10;
    // The target has finished testing but some tests failed.
    TargetTestFailed = 11;
}

message TestResults {
    // Total number of test cases in the test target.
    int32 num_tests = 1;
    // Number of tests that passed outright.
    int32 passed = 2;
    // Number of tests that failed.
    int32 failed = 3;
    // Number of tests that were expected to fail (counts as a pass, but displayed differently)
    int32 expected_failures = 4;
    // Number of tests skipped (also count as passes)
    int32 skipped = 5;
    // Number of failed attempts to run the test
    int32 flakes = 6;
    // Tests that failed, if any.
    repeated TestFailure failures = 7;
    // Names of tests that passed.
    repeated string passes = 8;
    // Combined stdout / stderr from the test.
    string output = 9;
    // Duration that the test ran for, in nanoseconds.
    int64 duration = 10;
    // True if the test results were cached (i.e. it was not actually rerun).
    bool cached = 11;
    // True if the test failed because we timed it out.
    bool timed_out = 12;
}

message TestFailure {
    // Name of the failing test.
    string name = 1;
    // Type of failure, e.g. the type of exception raised.
    string type = 2;
    // Traceback of the failure point, if applicable.
    string traceback = 3;
    // Standard output from this test case.
    string stdout = 4;
    // Standard error during test.
    string stderr = 5;
}

message ResourceUsageRequest{
}

message ResourceUsageResponse{
    // Total number of CPUs available to the system.
    int32 num_cpus = 1;
    // CPU usage that is measured as "in use", excluding I/O, as a percentage.
    double cpu_use = 2;
    // I/O wait, as a percentage of CPU time.
    double io_wait = 3;
    // Total amount of memory available
    uint64 mem_total = 4;
    // Total amount of memory in use.
    uint64 mem_used = 5;
}