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

syntax = "proto3";

package gitpod.v1;

option go_package = "github.com/gitpod-io/gitpod/public-api/v1";

import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";
import "gitpod/v1/pagination.proto";

service WorkspacesService {

    // ListWorkspaces enumerates all workspaces belonging to the authenticated user.
    rpc ListWorkspaces(ListWorkspacesRequest) returns (ListWorkspacesResponse) {}

    // GetWorkspace returns a single workspace.
    rpc GetWorkspace(GetWorkspaceRequest) returns (GetWorkspaceResponse) {}

    // GetOwnerToken returns an owner token.
    rpc GetOwnerToken(GetOwnerTokenRequest) returns (GetOwnerTokenResponse) {}

    // CreateAndStartWorkspace creates a new workspace and starts it.
    rpc CreateAndStartWorkspace(CreateAndStartWorkspaceRequest) returns (CreateAndStartWorkspaceResponse) {}

    // StartWorkspace starts an existing workspace.
    rpc StartWorkspace(StartWorkspaceRequest) returns (StartWorkspaceResponse) {}

    // GetRunningWorkspaceInstance returns the currently active instance of a workspace.
    // Errors:
    //   FAILED_PRECONDITION: if a workspace does not a currently active instance
    //
    rpc GetActiveWorkspaceInstance(GetActiveWorkspaceInstanceRequest) returns (GetActiveWorkspaceInstanceResponse) {}

    // GetWorkspaceInstanceOwnerToken returns the owner token of a workspace instance.
    // Note: the owner token is not part of the workspace instance status so that we can scope its access on the
    //       API function level.
    rpc GetWorkspaceInstanceOwnerToken(GetWorkspaceInstanceOwnerTokenRequest) returns (GetWorkspaceInstanceOwnerTokenResponse) {}

    // ListenToWorkspaceInstance listens to workspace instance updates.
    rpc ListenToWorkspaceInstance(ListenToWorkspaceInstanceRequest) returns (stream ListenToWorkspaceInstanceResponse) {}

    // ListenToImageBuildLogs streams (currently or previously) running workspace image build logs
    rpc ListenToImageBuildLogs(ListenToImageBuildLogsRequest) returns (stream ListenToImageBuildLogsResponse) {}

    // StopWorkspace stops a running workspace (instance).
    // Errors:
    //   NOT_FOUND:           the workspace_id is unkown
    //   FAILED_PRECONDITION: if there's no running instance
    rpc StopWorkspace(StopWorkspaceRequest) returns (stream StopWorkspaceResponse) {}

}

message ListWorkspacesRequest {
    Pagination pagination = 1;
    google.protobuf.FieldMask field_mask = 2;
}
message ListWorkspacesResponse {
    message WorkspaceAndInstance {
        Workspace result = 1;
        WorkspaceInstance last_active_instances = 2;
    }

    string next_page_token = 1;

    repeated WorkspaceAndInstance result = 2;
}

message GetWorkspaceRequest {
    string workspace_id = 1;
}
message GetWorkspaceResponse {
    Workspace result = 1;
}

message GetOwnerTokenRequest {
    string workspace_id = 1;
}
message GetOwnerTokenResponse {
    string token = 1;
}

message CreateAndStartWorkspaceRequest {
    string idempotency_token = 1;

    oneof source {
        string context_url = 2;
        string prebuild_id = 3;
    }

    StartWorkspaceSpec start_spec = 5;
}
message CreateAndStartWorkspaceResponse {
    string workspace_id = 1;
}

message StartWorkspaceRequest {
    string idempotency_token = 1;

    string workspace_id = 2;
    StartWorkspaceSpec spec = 3;
}
message StartWorkspaceResponse {
    string instance_id = 1;
    string workspace_url = 2;
}

message GetActiveWorkspaceInstanceRequest {
    string workspace_id = 1;
}
message GetActiveWorkspaceInstanceResponse {
    WorkspaceInstance instance = 1;
}

message GetWorkspaceInstanceOwnerTokenRequest {
    string instance_id = 1;
}
message GetWorkspaceInstanceOwnerTokenResponse {
    string owner_token = 1;
}

message ListenToWorkspaceInstanceRequest {
    string instance_id = 1;
}
message ListenToWorkspaceInstanceResponse {
    WorkspaceInstanceStatus instance_status = 1;
}

message ListenToImageBuildLogsRequest {
    string instance_id = 1;
}
message ListenToImageBuildLogsResponse {
    string line = 1;
}

message StopWorkspaceRequest {
    string idempotency_token = 1;

    string workspace_id = 2;
}
message StopWorkspaceResponse {}

////////////////////////////////
// Shared messages come here
////////////////////////////////

// Workspace describes a single workspace
message Workspace {
    // workspace_id is the ID of the workspace
    string workspace_id = 1;

    // owner_id is the ID of the user who created this workspace
    string owner_id = 2;

    // project_id is the ID of the project which this workspace belongs to
    string project_id = 3;

    // context reports the original context the workspace was created from
    WorkspaceContext context = 4;

    // description is a human readable description of the workspace
    string description = 5;
}

// WorkspaceContext describes the context a workspace was created from
message WorkspaceContext {
    // Explicit Git context
    message Git {
        string normalized_context_url = 1;
        string commit = 2;
    }

    // Workspace was created from a prebuild
    message Prebuild {
        // original_context is the Git context which lead to the selection
        // of a prebuild.
        Git original_context = 1;

        // prebuild_id is the ID of the prebuild which was used to create this workspace
        string prebuild_id = 2;
    }

    // Snapshot context points to the snapshot which the workspace was created from
    message Snapshot {
        string snapshot_id = 1;
    }

    // All workspace context originates from a URL - this is the context URL
    // which led to the creation of a workspace.
    string context_url = 1;

    oneof details {
        Git git = 2;
        Prebuild prebuild = 3;
        Snapshot snapshot = 4;
    }
}

// WorkspaceInstance describes a single workspace instance
message WorkspaceInstance {
    // Instance ID is the unique identifier of the workspace instance
    string instance_id = 1;

    // Worksapce ID is the unique identifier of the workspace this instance belongs to
    string workspace_id = 2;

    google.protobuf.Timestamp created_at = 3;

    WorkspaceInstanceStatus status = 4;
}

// 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
    // as a timestemp), but it can be used to impose a partial order.
    // If a.status_version < b.status_version then a was the status before b.
    uint64 status_version = 1;

    // the phase of a workspace is a simple, high-level summary of where the workspace instance is in its lifecycle
    Phase phase = 2;

    // conditions detail the current state of the workspace instance
    Conditions conditions = 3;

    // message is an optional human-readable message detailing the current phase
    string message = 4;

    // URL contains the endpoint at which the workspace instance is available
    string url = 5;

    // Admission describes who can access a workspace instance and its ports.
    AdmissionLevel admission = 6;

    // repo details the Git working copy status of the workspace.
    // Note: this is a best-effort field and more often than not will not be present. Its absence does not
    // indicate the absence of a working copy.
    // contentservice.GitStatus repo = 7;
}

// Admission level describes who can access a workspace instance and its ports.
enum AdmissionLevel {
    ADMISSION_LEVEL_UNSPECIFIED = 0;

    // ADMISSION_LEVEL_OWNER_ONLY means the workspace can only be accessed using the owner token
    ADMISSION_LEVEL_OWNER_ONLY = 1;

    // ADMISSION_LEVEL_EVERYONE means the workspace (including ports) can be accessed by everyone.
    ADMISSION_LEVEL_EVERYONE = 2;
}

// StartWorkspaceSpec influences the workspace start
message StartWorkspaceSpec {
    // future per-workspace-start fields, e.g. region
}