progress.proto

syntax = "proto3";
package progrock;

option go_package = "github.com/vito/progrock";

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/any.proto";

// StatusUpdate contains a snapshot of state updates for the graph.
message StatusUpdate {
  // Vertexes contains the set of vertex updates.
  repeated Vertex vertexes = 1;
  // Tasks contains the set of tasks updates.
  repeated VertexTask tasks = 2;
  // Logs contains the set of new log output.
  repeated VertexLog logs = 3;
  // Metas contains a set of vertex metadata.
  repeated VertexMeta metas = 9;
  // Groups contains a set of groups updates.
  repeated Group groups = 4;
  // Memberships contains a set of group membership updates.
  repeated Membership memberships = 5;
  // Children contains a set of parent-child vertex updates.
  repeated Children children = 10;
  // Messages contains global messages to show to the user.
  repeated Message messages = 6;
  // Sent is an optional timestamp that the status update was emitted.
  optional google.protobuf.Timestamp sent = 7;
  // Received is an optional timestamp that the status update was received.
  optional google.protobuf.Timestamp received = 8;
};

// Membership declares a set of vertexes to be members of a group.
message Membership {
  // Group is the ID of the group.
  string group = 1;
  // Vertexes is the set of vertex IDs that are members of the group.
  repeated string vertexes = 2;
};

// Children declares a set of vertexes to be children of another vertex.
message Children {
  // Vertex is the ID of the parent.
  string vertex = 1;
  // Vertexes is the set of vertex IDs that are children of the parent.
  repeated string vertexes = 2;
};

// Group is used to group related vertexes.
message Group {
  // ID is an arbitrary identifier for the group.
  string id = 1;
  // Parent is the ID of a parent group.
  optional string parent = 2;
  // Name is a name for this group, relative to its parent.
  string name = 3;
  // Labels contains a series of name/value pairs.
  repeated Label labels = 4;
  // Started is the timestamp that the group started.
  google.protobuf.Timestamp started = 5;
  // Completed is the timestamp that the group completed.
  optional google.protobuf.Timestamp completed = 6;
  // Weak indicates that the group should not be considered equal to non-weak
  // groups. Weak groups may be used to group together vertexes that correspond
  // to a single API (e.g. a Dockerfile build), as opposed to "strong" groups
  // explicitly configured by the user (e.g. "test", "build", etc).
  bool weak = 7;
};

// Label is a name/value pair used for annotation.
message Label {
  // Name is the name of the label.
  //
  // Domain prefixes are a convention for disambiguation, such as
  // progrock.io/foo.
  string name = 1;
  // Value is the value of the label.
  string value = 2;
};

// Vertex is a node in the graph of work to be done.
message Vertex {
  // ID is a unique identifier for the vertex, such as a digest.
  string id = 1;
  // Name is a user-visible name for the vertex.
  string name = 2;
  // Inputs contains IDs of vertices that this vertex depends on.
  repeated string inputs = 3;
  // Outputs contains IDs of vertices that this vertex created.
  //
  // The intention is to allow a vertex to express that it created other
  // vertexes which may not maintain an input relationship to its creator, for
  // example an API request that created an object that may have otherwise been
  // created in some other way.
  repeated string outputs = 4;
  // Started is the time that the vertex started evaluating.
  optional google.protobuf.Timestamp started = 5;
  // Completed is the time that the vertex finished evaluating.
  optional google.protobuf.Timestamp completed = 6;
  // Cached indicates whether the vertex resulted in a cache hit.
  bool cached = 7;
  // Error is the error message, if any, that occurred while evaluating the
  // vertex.
  optional string error = 8;
  // Canceled indicates whether the vertex was interrupted.
  bool canceled = 9;
  // Internal indicates that the vertex should not visible to the user by
  // default, but may be revealed with a flag.
  bool internal = 10;
  // Focused indicates that the vertex is more important than other vertices,
  // and should perhaps be displayed more prominently. For example, this might
  // be used to mark the command that actually "does the thing" - runs the
  // tests, does a build, whatever.
  bool focused = 11;
  // Zoomed indicates that this vertex should take up as much
  // screen real estate as possible. For example, this might
  // be used for running an interactive shell, or running
  // anything where there is a single primary output.
  bool zoomed = 12;
  // Labels contains a series of name/value pairs.
  repeated Label labels = 13;
}

// VertexTask is a task that a vertex is performing.
message VertexTask {
  // Vertex is the ID of the vertex that is performing the task.
  string vertex = 1;
  // Name is the user-visible name of the task.
  string name = 2;
  // Total is the total number of units of work to be done, such as the number
  // of bytes to be downloaded.
  int64 total = 3;
  // Current is the number of units of work that have been completed.
  int64 current = 4;
  // Started is the time that the task started.
  optional google.protobuf.Timestamp started = 5;
  // Completed is the time that the task finished.
  optional google.protobuf.Timestamp completed = 6;
}

// VertexLog is a log message from a vertex.
message VertexLog {
  // Vertex is the ID of the vertex that emitted the log message.
  string vertex = 1;
  // Stream is the stream that the log message was emitted to.
  LogStream stream = 2;
  // Data is the chunk of log output.
  bytes data = 3;
  // Timestamp is the time that the log message was emitted.
  google.protobuf.Timestamp timestamp = 4;
}

// VertexMeta is a message for associated arbitrary data with a vertex.
//
// This is primarily used to help UIs.
message VertexMeta {
  // Vertex is the ID of the vertex that the payload pertains to.
  string vertex = 1;
  // Name is a simple word that describes the payload.
  string name = 2;
  // Data is an optional payload of arbitrary data.
  optional google.protobuf.Any data = 3;
}

// LogStream is the standard stream that a log message was emitted to.
enum LogStream {
  // STDIN is /dev/stdin.
  STDIN = 0;
  // STDOUT is /dev/stdout.
  STDOUT = 1;
  // STDOUT is /dev/stderr.
  STDERR = 2;
}

// Message is a message to display to the user at a global level.
message Message {
  // Message is the human-readable content of the message.
  string message = 1;
  // Level indicates the severity of the message.
  MessageLevel level = 2;
  // Code is an optional machine-readable name for the message, such as an
  // error code. It may be included for i10n.
  optional string code = 3;
  // Labels contains a series of name/value pairs.
  repeated Label labels = 4;
}

// MessageLevel indicates the severity of a message.
//
// Note that there isn't an INFO level as Messages aren't meant to be used for
// general-purpose logging or updates; those should go through the regular
// vertex status update flow instead. Nevertheless, room has been left for more
// levels in the future, and the enum values are aligned with Go's log/slog
// package.
enum MessageLevel {
  // INVALID is not a valid message level. Protobuf requires the first enum
  // value to be 0, so here we are.
  //
  // In the future this _may_ become INFO, which would match Go's log/slog
  // package convention, but no promises!
  INVALID = 0;
  // DEBUG indicates that the message should only be shown if debugging is
  // enabled.
  DEBUG = -4;
  // WARNING indicates that the message should be shown to the user at all
  // times, but that execution of the program can continue as normal.
  WARNING = 4;
  // ERROR indicates that the message should be shown to the user, and that
  // executation of the program cannot continue.
  ERROR = 8;
}

// ProgressService is a service that allows clients to stream updates to a
// remote server.
service ProgressService {
  rpc WriteUpdates(stream StatusUpdate) returns (google.protobuf.Empty);
};