proto/step.proto

syntax = "proto3";
package proto;

import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option go_package = "../proto";

// Step is a single step invocation.
message Step {
  // Name is a unique identifier for this step.
  string name = 1;
  // Step is a reference to the step to invoke.
  Reference step = 2;
  // Env is a map of environment variable names to string values.
  map<string,string> env = 3;
  // Inputs is a map of step input names to structured values.
  map<string,google.protobuf.Value> inputs = 4;
  // Reference is a reference to a step. References can contain either a short or a full form.
  message Reference {
    // Protocol determines which step reference protocol to use when fetching the step.
    StepReferenceProtocol protocol = 1;
    // Url is the location of the referenced step.
    string url = 2;
    // Path is the location of the step spec and definition within the URL. Replaced with step_path
    repeated string path = 3 [deprecated = true];
    // Filename is the name of the file which contains the step spec and definition.
    string filename = 4;
    // Version is which version of the step to use.
    string version = 5;
    // Registry is the host and optionally port of the server hosting OCI images.
    string registry = 6;
    // Repository is the path to find an image on an OCI server.
    string repository = 7;
    // Tag is the version of the which version of the step OCI image to use.
    string tag = 8;
    // SpecDef allows the step reference to be inlined or hardcoded
    SpecDefinition specDef = 9;
    // Step Path is the path to the step
    oneof step_path {
      string path_exp = 10;
      PathParts paths = 11;
    }
  }
}

message PathParts {
  repeated string parts = 1;
}

// StepReferenceProtocol is the method of fetching the referenced step.
enum StepReferenceProtocol {
  step_reference_protocol_unspecified = 0;
  local = 1;
  git = 2;
  zip = 3;
  oci = 4;
  dist = 5;
  dynamic = 6;
  spec_def = 7;
}

// Definition is the implementation of a step.
message Definition {
  // Type is the type of this step.
  DefinitionType type = 1;
  // Exec is a command to run for the `exec` type.
  Exec exec = 2;
  // Steps is a list of sub-steps to run for the `steps` type.
  repeated Step steps = 3;
  // Exec is the details of an exec type step.
  message Exec {
    // Command are the parameters to the system exec API. It does not invoke a shell.
    repeated string command = 1;
    // WorkDir is the working directly in which `command` will be exec'ed.
    string work_dir = 2;
  }
  // Outputs are the output values for a `steps` type. They can reference the outputs of sub-steps.
  map<string,google.protobuf.Value> outputs = 4;
  // Env is a map of environment variable names to values for all steps
  map<string,string> env = 5;
  // Delegate selects a step by name which will produce the outputs for this step.
  string delegate = 6;
}

// Definition type is either exec or steps.
enum DefinitionType {
  definition_type_unspecified = 0;
  exec = 1;
  steps = 2;
}

// Spec is a document describing the interface of the step.
message Spec {
  // Content contains the inputs and outputs of the step.
  Content spec = 1;
  message Content {
    // Inputs is a map of input names to their parameters.
    map<string,Input> inputs = 1;
    // Input describes a single step input.
    message Input {
      // Type is the value type of the input.
      ValueType type = 1;
      // Default is the default input value. Its type must match `type`.
      google.protobuf.Value default = 2;
      // Sensitive implies the input is of sensitive nature and effort should be made to prevent accidental disclosure.
      bool sensitive = 3;
    }
    // Outputs is a map of output names to their parameters.
    map<string,Output> outputs = 2;
    // Output describes a single step output.
    message Output {  
      // Type is the value type of the output.
      ValueType type = 1;
      // Default is the default output value.
      google.protobuf.Value default = 2;
      // Sensitive implies the output is of sensitive nature and effort should be made to prevent accidental disclosure.
      bool sensitive = 3;
    }
    // OutputMethod selects how this step will return its outputs.
    OutputMethod output_method = 3;
  }
}

// OutputMethod is either outputs or delegate.
enum OutputMethod {
  output_method_unspecified = 0;
  outputs = 1;
  delegate = 2;
}

// SpecDefinition is the spec and definition from an exec.yml file.
message SpecDefinition {
  // Spec is the first document in the file.
  Spec spec = 1;
  // Definition is the second document in the file.
  Definition definition = 2;
}

// ValueType is an enumerations of the possible types a value can have.
enum ValueType {
  value_type_unspecified = 0;
  reserved 1;   // formally raw_string
  string = 2;
  number = 3;
  boolean = 4;
  struct = 5;
  array = 6;
}

// StepResult is the result of executing a single step.
message StepResult {
  // Step is the invocation of this step with inputs. Expressions are expanded.
  Step step = 1;
  // SpecDefinition is this step's spec and definition. Expressions are not expanded.
  SpecDefinition specDefinition = 2;
  // Status is an enumerations of the states a step can be in during execution.
  enum Status {
    unspecified = 0;
    running = 1;
    success = 2;
    failure = 3;
    cancelled = 4;
  }
  // Status is the state of this step.
  Status status = 4;
  // Outputs are the output values returned from this step.
  map<string,google.protobuf.Value> outputs = 5;
  // Exports are the environment variables exported from this step.
  map<string,string> exports = 6;
  // Env is the environment at the step definition level. Expressions are expanded.
  map<string,string> env = 7;
  // ExecResult contains the details of an exec call.
  message ExecResult {
    // Command are the exec parameters. Expressions are expanded.
    repeated string command = 1;
    // WorkDir is the exec working directory. Expressions are expanded.
    string work_dir = 2;
    // ExitCode is the exit code of the exec process.
    int32 exit_code = 3;
  }
  // ExecResult is the details of an exec type step.
  ExecResult exec_result = 8;
  // SubStepResults are the details of a steps type step.
  repeated StepResult sub_step_results = 9;
}

service StepRunner {
  rpc Run(RunRequest) returns (RunResponse);
  rpc Close(CloseRequest) returns (CloseResponse);
  rpc FollowLogs(FollowLogsRequest) returns (stream FollowLogsResponse);
  rpc Status(StatusRequest) returns (StatusResponse);
}

message Variable {
  string key = 1;
  string value = 2;
  bool file = 3;
  bool masked = 4;
}

message Job {
  repeated Variable variables = 1;
  string build_dir = 4;
}

message RunRequest {
  string id = 1;
  string work_dir = 2;
  map<string,string> env = 3;
  Job job = 5;
  string steps = 6;
}

message RunResponse {
}

message CloseRequest {
    string id = 1;
}

message CloseResponse {
}

message FollowLogsRequest {
    string id = 1;
    int64 offset = 2;
}

message FollowLogsResponse {
    bytes data = 1;
}

message Status {
    string id = 1;
    string message = 2;
    StepResult.Status status = 3;
    google.protobuf.Timestamp start_time = 5;
    google.protobuf.Timestamp end_time = 6;
}

message StatusRequest {
    string id = 1;
}

message StatusResponse {
    repeated Status jobs = 1;
}