[public-api] Draft more of the prebuild API

Author: csweichel

components/public-api/README.md

@@ -3,99 +3,4 @@
 # Example Flows
 This section gives examples how clients would use this API.
 
-## Create Workspace
-
-### Not prebuild aware
-```go
-workspaces.CreateWorkspace({
-    idempotency_token: "<random_string>",
-    context_url: "https://github.com/gitpod-io/gitpod",
-})
-```
-
-### Prebuild aware but no log support
-```go
-workspaces.CreateWorkspace({
-    idempotency_token: "<random_string>",
-    context_url: "https://github.com/gitpod-io/gitpod",
-    prebuild: {
-        if_available: true,
-    }
-})
-```
-
-### Prebuild aware with log support
-```go
-contextURL := "https://github.com/gitpod-io/gitpod"
-prb := prebuilds.GetRunningPrebuild({ context_url: contextURL })
-logs := prebuilds.ListenToPrebuild({ context_url: contextURL, prebuild_id: prb.PrebuildID })
-
-for logs.Recv() {
-    // display logs
-}
-// once logs are done, prebuild is done (errors notwithstanding)
-
-workspaces.CreateWorkspace({
-    idempotency_token: "<random_string>",
-    context_url: contextURL,
-    prebuild: {
-        prebuild_id: prb.PrebuildID,
-    }
-})
-```
-
-## Start Workspace
-
-### Ignoring image-build logs
-```Go
-// Get ahold of a workspace ID, either by finding an existing workspace
-// or creating a new one.
-workspaceID := ...
-
-// Start the workspace
-workspaces.StartWorkspace({
-    idempotency_token: "<random_string>",
-    workspace_id: workspaceID,
-})
-```
-
-### With image build log support
-```Go
-// Get ahold of a workspace ID, either by finding an existing workspace
-// or creating a new one.
-workspaceID := ...
-
-// Start the workspace
-resp := workspaces.StartWorkspace({
-    idempotency_token: "<random_string>",
-    workspace_id: workspaceID,
-})
-
-// Listen to updates for the instance we just created
-updates := workspaces.ListenToWorkspaceInstance({
-    instance_id: resp.InstanceId
-})
-var lastSeenVersion uint64
-for {
-    update := updates.Recv()
-    if lastSeenVersion == update.Version {
-        continue
-    }
-    lastSeenVersion = update.Version
-
-    switch update.Phase {
-        case ImageBuild:
-            go showImageBuildLogs(instanceID)
-        case Running:
-            // do something with this running workspace
-    }
-}
-
-func showImageBuildLogs(instanceID string) {
-    logs := workspaces.ListenToImageBuildLogs({instance_id: instanceID})
-    for {
-        resp := logs.Recv()
-        fmt.Println(resp.Line)
-    }
-}
-```
+https://github.com/gitpod-io/gitpod/blob/094dde356a04740500175e8797462a48c3153c89/components/public-api/go/v1/examples_test.go#L20-L103

components/public-api/gitpod/v1/prebuilds.proto

@@ -2,6 +2,7 @@ syntax = "proto3";
 
 package gitpod.v1;
 
+import "gitpod/v1/workspaces.proto";
 import "google/rpc/status.proto";
 
 option go_package = "github.com/gitpod-io/gitpod/public-api/v1";
@@ -10,19 +11,107 @@ option go_package = "github.com/gitpod-io/gitpod/public-api/v1";
 
 service PrebuildsService {
 
+    // GetPrebuild retrieves a single rebuild.
+    // Errors:
+    //   NOT_FOUND if the prebuild_id does not exist
+    rpc GetPrebuild(GetPrebuildRequest) returns (GetPrebuildResponse) {}
+
     // GetRunningPrebuild returns the prebuild ID of a running prebuild,
     // or NOT_FOUND if there is no prebuild running for the content_url.
     rpc GetRunningPrebuild(GetRunningPrebuildRequest) returns (GetRunningPrebuildResponse) {}
 
+    // ListenToPrebuildStatus streams status updates for a prebuild. If the prebuild is already
+    // in the Done phase, only that single status is streamed.
+    rpc ListenToPrebuildStatus(ListenToPrebuildStatusRequest) returns (stream ListenToPrebuildStatusResponse) {}
+
+    // ListenToPrebuildLogs returns the log output of a prebuild.
+    // This does NOT include an image build if one happened.
+    rpc ListenToPrebuildLogs(ListenToPrebuildLogsRequest) returns (stream ListenToPrebuildLogsResponse) {}
+
+}
+
+message GetPrebuildRequest {
+    string prebuild_id = 1;
+}
+message GetPrebuildResponse {
+    google.rpc.Status response_status = 1;
+
+    Prebuild prebuild = 2;
 }
 
 message GetRunningPrebuildRequest {
     string context_url = 1;
 }
-
 message GetRunningPrebuildResponse {
     google.rpc.Status response_status = 1;
 
-    string prebuild_id = 2;
+    Prebuild prebuild = 2;
+}
+
+message ListenToPrebuildStatusRequest{
+    string prebuild_id = 1;
 }
+message ListenToPrebuildStatusResponse {
+    google.rpc.Status response_status = 1;
 
+    PrebuildStatus status = 2;
+}
+
+message ListenToPrebuildLogsRequest {
+    string prebuild_id = 1;
+}
+message ListenToPrebuildLogsResponse {
+    google.rpc.Status response_status = 1;
+
+    string line = 2;
+}
+
+////////////////////////////////
+// Shared messages come here
+////////////////////////////////
+
+// Prebuild describes a prebuild
+message Prebuild {
+    string prebuild_id = 1;
+    PrebuildSpec spec = 2;
+    PrebuildStatus status = 3;
+}
+
+// PrebuildSpec specifies the prebuild input.
+message PrebuildSpec {
+    WorkspaceContext context = 1;
+
+    // Incremental prebuilds are based on other prebuilds. If this field is true,
+    // expect the context detail to point to another prebuild.
+    bool incremental = 2;
+}
+
+// PrebuildStatus describes the prebuild status.
+message PrebuildStatus {
+    enum Phase {
+        PHASE_UNSPECIFIED = 0;
+        PHASE_PENDING = 1;
+        PHASE_RUNNING = 2;
+        PHASE_DONE = 3;
+    }
+    enum Result {
+        RESULT_UNSPECIFIED = 0;
+        RESULT_SUCCESS = 1;
+        RESULT_USER_CANCELED = 2;
+        RESULT_SYSTEM_FAILURE = 3;
+        RESULT_TASK_FAILURE = 4;
+    }
+
+    // Phase is the prebuild phase we're in
+    Phase phase = 1;
+
+    // Result indicates what result the prebuild produced, i.e. if it ran
+    // successfully or failed for some reason. If phase != done, this field
+    // will have RESULT_UNSPECIFIED as value.
+    Result result = 2;
+
+    // result_message contains a human readable message describing the prebuild
+    // result. E.g. if teh result is SYSTEM_FAILURE, the message describes what
+    // that failure was.
+    string result_message = 3;
+}

components/public-api/gitpod/v1/workspaces.proto

@@ -77,14 +77,9 @@ message GetWorkspaceResponse {
 message CreateAndStartWorkspaceRequest {
     string idempotency_token = 1;
 
-    string context_url = 2;
-
-    oneof prebuild {
-        // if true, and there's a prebuild available (not running), use that prebuild
-        bool if_available = 3;
-        // uses a particular prebuild - the prebuild ID is scoped by the context URL.
-        // Use the PrebuildService to get ahold of the prebuild_id.
-        string prebuild_id = 4;
+    oneof source {
+        string context_url = 2;
+        string prebuild_id = 3;
     }
 
     StartWorkspaceSpec start_spec = 5;
@@ -224,6 +219,64 @@ message WorkspaceInstance {
 
 // WorkspaceStatus describes a workspace status
 message WorkspaceInstanceStatus {
+    // Phase is a simple, high-level summary of where the workspace instance is in its lifecycle.
+    // The phase is not intended to be a comprehensive rollup of observations of the workspace state,
+    // nor is it intended to be a comprehensive state machine.
+    // (based on  https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-phase)
+    enum Phase {
+        // Unknown indicates an issue within the workspace manager in that it cannot determine the actual phase of
+        // a workspace. This phase is usually accompanied by an error.
+        PHASE_UNSPECIFIED = 0;
+
+        // ImageBuild indicates that there's an image build running for this workspace.
+        PHASE_IMAGEBUILD = 1;
+
+        // Pending means the workspace does not yet consume resources in the cluster, but rather is looking for
+        // some space within the cluster. If for example the cluster needs to scale up to accomodate the
+        // workspace, the workspace will be in Pending state until that happened.
+        PHASE_PENDING = 2;
+
+        // Creating means the workspace is currently being created. That includes downloading the images required
+        // to run the workspace over the network. The time spent in this phase varies widely and depends on the current
+        // network speed, image size and cache states.
+        PHASE_CREATING = 3;
+
+        // Initializing is the phase in which the workspace is executing the appropriate workspace initializer (e.g. Git
+        // clone or backup download). After this phase one can expect the workspace to either be Running or Failed.
+        PHASE_INITIALIZING = 4;
+
+        // Running means the workspace is able to actively perform work, either by serving a user through Theia,
+        // or as a headless workspace.
+        PHASE_RUNNING = 5;
+
+        // Interrupted is an exceptional state where the container should be running but is temporarily unavailable.
+        // When in this state, we expect it to become running or stopping anytime soon.
+        PHASE_INTERRUPTED = 6;
+
+        // Stopping means that the workspace is currently shutting down. It could go to stopped every moment.
+        PHASE_STOPPING = 7;
+
+        // Stopped means the workspace ended regularly because it was shut down.
+        PHASE_STOPPED = 8;
+    }
+
+    // Conditions gives more detailed information as to the state of the workspace. Which condition actually
+    // has a value depends on the phase the workspace is in.
+    message Conditions {
+        // failed contains the reason the workspace failed to operate. If this field is empty, the workspace has not failed.
+        // This field is filled exclusively when caused by system errors.
+        string failed = 1;
+
+        // timeout contains the reason the workspace has timed out. If this field is empty, the workspace has not timed out.
+        string timeout = 2;
+
+        // first_user_activity is the time when MarkActive was first called on the workspace
+        google.protobuf.Timestamp first_user_activity = 9;
+
+        // stopped_by_request is true if the workspace was stopped using a StopWorkspace call
+        optional bool stopped_by_request = 11;
+    }
+
     // version of the status update. Workspace instances themselves are unversioned,
     // but their statuus has different versions.
     // The value of this field has no semantic meaning (e.g. don't interpret it as
@@ -232,10 +285,10 @@ message WorkspaceInstanceStatus {
     uint64 status_version = 1;
 
     // the phase of a workspace is a simple, high-level summary of where the workspace instance is in its lifecycle
-    WorkspaceInstancePhase phase = 2;
+    Phase phase = 2;
 
     // conditions detail the current state of the workspace instance
-    WorkspaceInstanceConditions conditions = 3;
+    Conditions conditions = 3;
 
     // message is an optional human-readable message detailing the current phase
     string message = 4;
@@ -252,65 +305,6 @@ message WorkspaceInstanceStatus {
     // contentservice.GitStatus repo = 7;
 }
 
-
-// WorkspaceInstancePhase is a simple, high-level summary of where the workspace instance is in its lifecycle.
-// The phase is not intended to be a comprehensive rollup of observations of the workspace state,
-// nor is it intended to be a comprehensive state machine.
-// (based on  https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-phase)
-enum WorkspaceInstancePhase {
-    // Unknown indicates an issue within the workspace manager in that it cannot determine the actual phase of
-    // a workspace. This phase is usually accompanied by an error.
-    WORKSPACE_INSTANCE_PHASE_UNSPECIFIED = 0;
-
-    // This will become IMAGE_BUILD
-    reserved 1;
-
-    // Pending means the workspace does not yet consume resources in the cluster, but rather is looking for
-    // some space within the cluster. If for example the cluster needs to scale up to accomodate the
-    // workspace, the workspace will be in Pending state until that happened.
-    WORKSPACE_INSTANCE_PHASE_PENDING = 2;
-
-    // Creating means the workspace is currently being created. That includes downloading the images required
-    // to run the workspace over the network. The time spent in this phase varies widely and depends on the current
-    // network speed, image size and cache states.
-    WORKSPACE_INSTANCE_PHASE_CREATING = 3;
-
-    // Initializing is the phase in which the workspace is executing the appropriate workspace initializer (e.g. Git
-    // clone or backup download). After this phase one can expect the workspace to either be Running or Failed.
-    WORKSPACE_INSTANCE_PHASE_INITIALIZING = 4;
-
-    // Running means the workspace is able to actively perform work, either by serving a user through Theia,
-    // or as a headless workspace.
-    WORKSPACE_INSTANCE_PHASE_RUNNING = 5;
-
-    // Interrupted is an exceptional state where the container should be running but is temporarily unavailable.
-    // When in this state, we expect it to become running or stopping anytime soon.
-    WORKSPACE_INSTANCE_PHASE_INTERRUPTED = 6;
-
-    // Stopping means that the workspace is currently shutting down. It could go to stopped every moment.
-    WORKSPACE_INSTANCE_PHASE_STOPPING = 7;
-
-    // Stopped means the workspace ended regularly because it was shut down.
-    WORKSPACE_INSTANCE_PHASE_STOPPED = 8;
-}
-
-// WorkspaceInstanceConditions gives more detailed information as to the state of the workspace. Which condition actually
-// has a value depends on the phase the workspace is in.
-message WorkspaceInstanceConditions {
-    // failed contains the reason the workspace failed to operate. If this field is empty, the workspace has not failed.
-    // This field is filled exclusively when caused by system errors.
-    string failed = 1;
-
-    // timeout contains the reason the workspace has timed out. If this field is empty, the workspace has not timed out.
-    string timeout = 2;
-
-    // first_user_activity is the time when MarkActive was first called on the workspace
-    google.protobuf.Timestamp first_user_activity = 9;
-
-    // stopped_by_request is true if the workspace was stopped using a StopWorkspace call
-    optional bool stopped_by_request = 11;
-}
-
 // Admission level describes who can access a workspace instance and its ports.
 enum AdmissionLevel {
     ADMISSION_LEVEL_UNSPECIFIED = 0;