[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/README.md

@@ -0,0 +1,101 @@
+# Public-API
+
+# 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)
+    }
+}
+```

components/public-api/buf.yaml

@@ -0,0 +1,7 @@
+version: v1
+breaking:
+  use:
+    - FILE
+lint:
+  use:
+    - DEFAULT

components/public-api/generate.sh

@@ -0,0 +1,27 @@
+#!/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
+
+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,26 @@
+syntax = "proto3";
+
+package gitpod.v1;
+
+option go_package = "github.com/gitpod-io/gitpod/public-api/v1";
+
+// import "gitpod/v1/pagination.proto";
+
+service PrebuildsService {
+
+    // 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) {}
+
+}
+
+message GetRunningPrebuildRequest {
+    string context_url = 1;
+}
+
+message GetRunningPrebuildResponse {
+    // Status status = 1;
+
+    string prebuild_id = 2;
+}
+