[public-api] Initial scaffolding and draft

.github/CODEOWNERS

@@ -52,6 +52,7 @@
 /components/local-app @gitpod-io/engineering-ide
 /components/openvsx-proxy @gitpod-io/engineering-ide
 /components/proxy @gitpod-io/engineering-webapp
+/components/public-api @csweichel @akosyakov @geropl
 /components/registry-facade-api @csweichel @aledbf
 /components/registry-facade @gitpod-io/engineering-workspace
 /components/server @gitpod-io/engineering-webapp

components/public-api/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+    "protoc": {
+        "compile_on_save": false,
+        "options": [
+            "--proto_path=.",
+            "--proto_path=${workspaceRoot}/components/public-api"
+        ]
+    }
+}

components/public-api/BUILD.yaml

@@ -0,0 +1,9 @@
+scripts:
+  - name: lint
+    deps:
+      - components/public-api/hack/protoc-gen-gplint:app
+    script: |
+      protoc \
+        -I /usr/lib/protoc/include -I. \
+        --gplint_out=. \
+        gitpod/v1/*.proto

components/public-api/README.md

@@ -0,0 +1,6 @@
+# Public-API
+
+# Example Flows
+This section gives examples how clients would use this API.
+
+https://github.com/gitpod-io/gitpod/blob/094dde356a04740500175e8797462a48c3153c89/components/public-api/go/v1/examples_test.go#L20-L103

components/public-api/buf.yaml

@@ -0,0 +1,9 @@
+version: v1
+breaking:
+  use:
+    - FILE
+lint:
+  use:
+    - DEFAULT
+  ignore:
+    - google

components/public-api/generate.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+
+
+if [ -n "$DEBUG" ]; then
+  set -x
+fi
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../../
+COMPONENTS_DIR="$ROOT_DIR"/components
+
+# include protoc bash functions
+# shellcheck disable=SC1090,SC1091
+source "$ROOT_DIR"/scripts/protoc-generator.sh
+
+lint
+leeway run .:lint
+
+install_dependencies
+go_protoc "$COMPONENTS_DIR" "gitpod/v1"
+mkdir -p go/v1
+mv go/gitpod/v1/*.pb.go go/v1
+rm -rf go/gitpod
+typescript_protoc "$COMPONENTS_DIR" "gitpod/v1"
+
+update_license

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

@@ -0,0 +1,13 @@
+syntax = "proto3";
+
+package gitpod.v1;
+
+option go_package = "github.com/gitpod-io/gitpod/public-api/v1";
+
+message Pagination {
+    // page_size is the maximum number of results we expect
+    int32 page_size = 1;
+
+    // page_token points to a specific page of the results
+    string page_token = 2;
+}

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

@@ -0,0 +1,117 @@
+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";
+
+// import "gitpod/v1/pagination.proto";
+
+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;
+
+    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;
+}