@gitpod/gitpod-protocol 0.1.5-minor-updates.0 → 0.1.5-mp-docs-wsp-phase.0

package/src/context-url.ts

@@ -0,0 +1,107 @@
+/**
+ * Copyright (c) 2020 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License-AGPL.txt in the project root for license information.
+ */
+
+import { Workspace } from ".";
+
+/**
+ * The whole point of these methods is to overcome inconsistencies in our data model.
+ * Ideally we remove it at some point once we fixed our model, as it:
+ *  - duplicates logic
+ *  - but additional burden on clients (using this, copying this to other languages!)
+ *
+ * TODO(gpl) See if we can get this into `server` code to remove the burden from clients
+ */
+export namespace ContextURL {
+  export const INCREMENTAL_PREBUILD_PREFIX = "incremental-prebuild";
+  export const PREBUILD_PREFIX = "prebuild";
+  export const IMAGEBUILD_PREFIX = "imagebuild";
+  export const SNAPSHOT_PREFIX = "snapshot";
+  export const REFERRER_PREFIX = 'referrer:';
+
+  /**
+   * This function will (try to) return the HTTP(S) URL of the context the user originally created this workspace on.
+   * Especially it will not contain any modifiers or be of different scheme than HTTP(S).
+   *
+   * Use this function if you need to provided a _working_ URL to the original context.
+   * @param ws
+   * @returns
+   */
+  export function getNormalizedURL(ws: Pick<Workspace, "context" | "contextURL"> | undefined): URL | undefined {
+    const normalized = normalize(ws);
+    if (!normalized) {
+      return undefined;
+    }
+
+    try {
+      return new URL(normalized);
+    } catch (err) {
+      console.error(`unable to parse URL from normalized contextURL: '${normalized}'`, err);
+    }
+    return undefined;
+  }
+
+  function normalize(ws: Pick<Workspace, "context" | "contextURL"> | undefined): string | undefined {
+    if (!ws) {
+      return undefined;
+    }
+    if (ws.context.normalizedContextURL) {
+      return ws.context.normalizedContextURL;
+    }
+
+    // fallback: we do not yet set normalizedContextURL on all workspaces, yet, let alone older existing workspaces
+    let fallback: string | undefined = undefined;
+    try {
+      fallback = removePrefixes(ws.contextURL);
+    } catch (err) {
+      console.error(`unable to remove prefixes from contextURL: '${ws.contextURL}'`, err);
+    }
+    return fallback;
+  }
+
+  /**
+   * The field "contextUrl" might contain prefixes like:
+   *  - envvar1=value1/...
+   *  - prebuild/...
+   * This is the analogon to the (Prefix)ContextParser structure in "server".
+   */
+  function removePrefixes(contextUrl: string | undefined): string | undefined {
+    if (contextUrl === undefined) {
+      return undefined;
+    }
+
+    const segments = contextUrl.split("/");
+    if (segments.length === 1) {
+      return segments[0];  // this might be something, we just try
+    }
+
+    const segmentsToURL = (offset: number): string => {
+      let rest = segments.slice(offset).join("/");
+      if (/^git@[^:\/]+:/.test(rest)) {
+        rest = rest.replace(/^git@([^:\/]+):/, 'https://$1/');
+      }
+      if (!rest.startsWith("http")) {
+        rest = 'https://' + rest;
+      }
+      return rest;
+    };
+
+    const firstSegment = segments[0];
+    if (firstSegment === PREBUILD_PREFIX ||
+        firstSegment === INCREMENTAL_PREBUILD_PREFIX ||
+        firstSegment === IMAGEBUILD_PREFIX ||
+        firstSegment === SNAPSHOT_PREFIX ||
+        firstSegment.startsWith(REFERRER_PREFIX)) {
+      return segmentsToURL(1);
+    }
+
+    // check for env vars
+    if (firstSegment.indexOf("=") !== -1) {
+      return segmentsToURL(1);
+    }
+
+    return segmentsToURL(0);
+  }
+}

package/src/email-protocol.ts

@@ -4,8 +4,7 @@
  * See License-AGPL.txt in the project root for license information.
  */
 
-import { Without } from "./util/without";
-import uuidv4 = require("uuid/v4");
+import { v4 as uuidv4 } from 'uuid';
 
 export type EMailState = "scheduledInternal"
     | "scheduledSendgrid";
@@ -59,7 +58,7 @@ export type EMail = {
 } & EMailStatus;
 
 export namespace EMail {
-    export const create = (ts: Without<EMail, 'uid'>): EMail => {
+    export const create = (ts: Omit<EMail, 'uid'>): EMail => {
         const withId = ts as EMail;
         withId.uid = uuidv4();
         return withId;

package/src/env.ts

@@ -13,18 +13,18 @@ const legacyStagenameTranslation: { [key: string]: KubeStage } = {
     "dev": "dev"
 }
 
+export function translateLegacyStagename(kubeStage: string): KubeStage {
+    const stage = legacyStagenameTranslation[kubeStage];
+    if (!stage) {
+        throw new Error(`Invalid KUBE_STAGE: ${kubeStage}`);
+    }
+
+    return stage;
+}
+
 @injectable()
 export abstract class AbstractComponentEnv {
-    readonly kubeStage: KubeStage = getEnvVarParsed('KUBE_STAGE', (kubeStage) => {
-        const stage = legacyStagenameTranslation[kubeStage];
-        if (!stage) {
-            throw new Error(`Environment variable invalid: KUBE_STAGE=${kubeStage}`);
-        }
-
-        return stage;
-    });
-    readonly kubeNamespace: string = getEnvVar('KUBE_NAMESPACE');
-    readonly version: string = getEnvVar('VERSION');
+    readonly kubeStage: KubeStage = getEnvVarParsed('KUBE_STAGE', translateLegacyStagename);
 
     readonly installationLongname: string = getEnvVar("GITPOD_INSTALLATION_LONGNAME")
     readonly installationShortname: string = getEnvVar("GITPOD_INSTALLATION_SHORTNAME")

package/src/gitpod-service.ts

@@ -5,14 +5,19 @@
  */
 
 import {
-    User, WorkspaceInfo, WorkspaceCreationResult, UserMessage, WorkspaceInstanceUser,
-    WhitelistedRepository, WorkspaceImageBuild, AuthProviderInfo, Branding, CreateWorkspaceMode,
-    Token, UserEnvVarValue, ResolvePluginsParams, PreparePluginUploadParams, Terms,
-    ResolvedPlugins, Configuration, InstallPluginsParams, UninstallPluginParams, UserInfo, GitpodTokenType, GitpodToken, AuthProviderEntry
+    User, WorkspaceInfo, WorkspaceCreationResult, WorkspaceInstanceUser,
+    WhitelistedRepository, WorkspaceImageBuild, AuthProviderInfo, CreateWorkspaceMode,
+    Token, UserEnvVarValue, Terms,
+    Configuration, UserInfo, GitpodTokenType,
+    GitpodToken, AuthProviderEntry, GuessGitTokenScopesParams, GuessedGitTokenScopes, ProjectEnvVar
 } from './protocol';
+import {
+    Team, TeamMemberInfo,
+    TeamMembershipInvite, Project, TeamMemberRole, PrebuildWithStatus, StartPrebuildResult, PartialProject
+} from './teams-projects-protocol';
 import { JsonRpcProxy, JsonRpcServer } from './messaging/proxy-factory';
 import { Disposable, CancellationTokenSource } from 'vscode-jsonrpc';
-import { HeadlessLogEvent } from './headless-workspace-log';
+import { HeadlessLogUrls } from './headless-workspace-log';
 import { WorkspaceInstance, WorkspaceInstancePort, WorkspaceInstancePhase } from './workspace-instance';
 import { AdminServer } from './admin-protocol';
 import { GitpodHostUrl } from './util/gitpod-host-url';
@@ -23,11 +28,15 @@ import { Emitter } from './util/event';
 import { AccountStatement, CreditAlert } from './accounting-protocol';
 import { GithubUpgradeURL, PlanCoupon } from './payment-protocol';
 import { TeamSubscription, TeamSubscriptionSlot, TeamSubscriptionSlotResolved } from './team-subscription-protocol';
+import { RemotePageMessage, RemoteTrackMessage, RemoteIdentifyMessage } from './analytics';
+import { IDEServer } from './ide-protocol';
+import { InstallationAdminSettings, TelemetryData } from './installation-admin-protocol';
 
 export interface GitpodClient {
     onInstanceUpdate(instance: WorkspaceInstance): void;
     onWorkspaceImageBuildLogs: WorkspaceImageBuild.LogCallback;
-    onHeadlessWorkspaceLogs(evt: HeadlessLogEvent): void;
+
+    onPrebuildUpdate(update: PrebuildWithStatus): void;
 
     onCreditAlert(creditAlert: CreditAlert): void;
 
@@ -38,18 +47,18 @@ export interface GitpodClient {
 }
 
 export const GitpodServer = Symbol('GitpodServer');
-export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer, LicenseService {
+export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer, LicenseService, IDEServer {
     // User related API
     getLoggedInUser(): Promise<User>;
     getTerms(): Promise<Terms>;
     updateLoggedInUser(user: Partial<User>): Promise<User>;
     getAuthProviders(): Promise<AuthProviderInfo[]>;
     getOwnAuthProviders(): Promise<AuthProviderEntry[]>;
-    updateOwnAuthProvider(params: GitpodServer.UpdateOwnAuthProviderParams): Promise<void>;
+    updateOwnAuthProvider(params: GitpodServer.UpdateOwnAuthProviderParams): Promise<AuthProviderEntry>;
     deleteOwnAuthProvider(params: GitpodServer.DeleteOwnAuthProviderParams): Promise<void>;
-    getBranding(): Promise<Branding>;
     getConfiguration(): Promise<Configuration>;
     getToken(query: GitpodServer.GetTokenSearchOptions): Promise<Token | undefined>;
+    getGitpodTokenScopes(tokenHash: string): Promise<string[]>;
     /**
      * @deprecated
      */
@@ -63,8 +72,15 @@ export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer,
     getWorkspaceOwner(workspaceId: string): Promise<UserInfo | undefined>;
     getWorkspaceUsers(workspaceId: string): Promise<WorkspaceInstanceUser[]>;
     getFeaturedRepositories(): Promise<WhitelistedRepository[]>;
+    getSuggestedContextURLs(): Promise<string[]>;
+    /**
+     * **Security:**
+     * Sensitive information like an owner token is erased, since it allows access for all team members.
+     * If you need to access an owner token use `getOwnerToken` instead.
+     */
     getWorkspace(id: string): Promise<WorkspaceInfo>;
     isWorkspaceOwner(workspaceId: string): Promise<boolean>;
+    getOwnerToken(workspaceId: string): Promise<string>;
 
     /**
      * Creates and starts a workspace for the given context URL.
@@ -81,8 +97,8 @@ export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer,
     updateWorkspaceUserPin(id: string, action: GitpodServer.PinAction): Promise<void>;
     sendHeartBeat(options: GitpodServer.SendHeartBeatOptions): Promise<void>;
     watchWorkspaceImageBuildLogs(workspaceId: string): Promise<void>;
-    watchHeadlessWorkspaceLogs(workspaceId: string): Promise<void>;
     isPrebuildDone(pwsid: string): Promise<boolean>;
+    getHeadlessLog(instanceId: string): Promise<HeadlessLogUrls>;
 
     // Workspace timeout
     setWorkspaceTimeout(workspaceId: string, duration: WorkspaceTimeoutDuration): Promise<SetWorkspaceTimeoutResult>;
@@ -96,19 +112,52 @@ export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer,
     openPort(workspaceId: string, port: WorkspaceInstancePort): Promise<WorkspaceInstancePort | undefined>;
     closePort(workspaceId: string, port: number): Promise<void>;
 
-    // User messages
-    getUserMessages(options: GitpodServer.GetUserMessagesOptions): Promise<UserMessage[]>;
-    updateUserMessages(options: GitpodServer.UpdateUserMessagesOptions): Promise<void>;
-
     // User storage
     getUserStorageResource(options: GitpodServer.GetUserStorageResourceOptions): Promise<string>;
     updateUserStorageResource(options: GitpodServer.UpdateUserStorageResourceOptions): Promise<void>;
 
-    // user env vars
+    // User env vars
     getEnvVars(): Promise<UserEnvVarValue[]>;
+    getAllEnvVars(): Promise<UserEnvVarValue[]>;
     setEnvVar(variable: UserEnvVarValue): Promise<void>;
     deleteEnvVar(variable: UserEnvVarValue): Promise<void>;
 
+    // Teams
+    getTeams(): Promise<Team[]>;
+    getTeamMembers(teamId: string): Promise<TeamMemberInfo[]>;
+    createTeam(name: string): Promise<Team>;
+    joinTeam(inviteId: string): Promise<Team>;
+    setTeamMemberRole(teamId: string, userId: string, role: TeamMemberRole): Promise<void>;
+    removeTeamMember(teamId: string, userId: string): Promise<void>;
+    getGenericInvite(teamId: string): Promise<TeamMembershipInvite>;
+    resetGenericInvite(inviteId: string): Promise<TeamMembershipInvite>;
+    deleteTeam(teamId: string, userId: string): Promise<void>;
+
+    // Admin Settings
+    adminGetSettings(): Promise<InstallationAdminSettings>;
+    adminUpdateSettings(settings: InstallationAdminSettings): Promise<void>;
+    adminGetTelemetryData(): Promise<TelemetryData>;
+
+    // Projects
+    getProviderRepositoriesForUser(params: GetProviderRepositoriesParams): Promise<ProviderRepository[]>;
+    createProject(params: CreateProjectParams): Promise<Project>;
+    deleteProject(projectId: string): Promise<void>;
+    getTeamProjects(teamId: string): Promise<Project[]>;
+    getUserProjects(): Promise<Project[]>;
+    getProjectOverview(projectId: string): Promise<Project.Overview | undefined>;
+    findPrebuilds(params: FindPrebuildsParams): Promise<PrebuildWithStatus[]>;
+    triggerPrebuild(projectId: string, branchName: string | null): Promise<StartPrebuildResult>;
+    cancelPrebuild(projectId: string, prebuildId: string): Promise<void>;
+    fetchProjectRepositoryConfiguration(projectId: string): Promise<string | undefined>;
+    guessProjectConfiguration(projectId: string): Promise<string | undefined>;
+    fetchRepositoryConfiguration(cloneUrl: string): Promise<string | undefined>;
+    guessRepositoryConfiguration(cloneUrl: string): Promise<string | undefined>;
+    setProjectConfiguration(projectId: string, configString: string): Promise<void>;
+    updateProjectPartial(partialProject: PartialProject): Promise<void>;
+    setProjectEnvironmentVariable(projectId: string, name: string, value: string, censored: boolean): Promise<void>;
+    getProjectEnvironmentVariables(projectId: string): Promise<ProjectEnvVar[]>;
+    deleteProjectEnvironmentVariable(variableId: string): Promise<void>;
+
     // content service
     getContentBlobUploadUrl(name: string): Promise<string>
     getContentBlobDownloadUrl(name: string): Promise<string>
@@ -123,10 +172,15 @@ export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer,
     registerGithubApp(installationId: string): Promise<void>;
 
     /**
-     * Stores a new snapshot for the given workspace and bucketId
+     * Stores a new snapshot for the given workspace and bucketId. Returns _before_ the actual snapshot is done. To wait for that, use `waitForSnapshot`.
      * @return the snapshot id
      */
     takeSnapshot(options: GitpodServer.TakeSnapshotOptions): Promise<string>;
+    /**
+     *
+     * @param snapshotId
+     */
+    waitForSnapshot(snapshotId: string): Promise<void>;
 
     /**
      * Returns the list of snapshots that exist for a workspace.
@@ -143,29 +197,20 @@ export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer,
      */
     getLayout(workspaceId: string): Promise<string | undefined>;
 
-    /**
-     * @param params
-     * @returns promise resolves to an URL to be used for the upload
-     */
-    preparePluginUpload(params: PreparePluginUploadParams): Promise<string>
-    resolvePlugins(workspaceId: string, params: ResolvePluginsParams): Promise<ResolvedPlugins>;
-    installUserPlugins(params: InstallPluginsParams): Promise<boolean>;
-    uninstallUserPlugin(params: UninstallPluginParams): Promise<boolean>;
+    guessGitTokenScopes(params: GuessGitTokenScopesParams): Promise<GuessedGitTokenScopes>;
 
     /**
      * gitpod.io concerns
      */
     isStudent(): Promise<boolean>;
-    getPrivateRepoTrialEndDate(): Promise<string | undefined>;
-
     /**
-     * 
+     *
      */
     getAccountStatement(options: GitpodServer.GetAccountStatementOptions): Promise<AccountStatement | undefined>;
     getRemainingUsageHours(): Promise<number>;
 
     /**
-     * 
+     *
      */
     getChargebeeSiteId(): Promise<string>;
     createPortalSession(): Promise<{}>;
@@ -175,7 +220,6 @@ export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer,
 
     getShowPaymentUI(): Promise<boolean>;
     isChargebeeCustomer(): Promise<boolean>;
-    mayAccessPrivateRepo(): Promise<boolean>;
 
     subscriptionUpgradeTo(subscriptionId: string, chargebeePlanId: string): Promise<void>;
     subscriptionDowngradeTo(subscriptionId: string, chargebeePlanId: string): Promise<void>;
@@ -186,13 +230,71 @@ export interface GitpodServer extends JsonRpcServer<GitpodClient>, AdminServer,
     tsGetSlots(): Promise<TeamSubscriptionSlotResolved[]>;
     tsGetUnassignedSlot(teamSubscriptionId: string): Promise<TeamSubscriptionSlot | undefined>
     tsAddSlots(teamSubscriptionId: string, quantity: number): Promise<void>;
-    tsAssignSlot(teamSubscriptionId: string, teamSubscriptionSlotId: string, identityStr: string|undefined): Promise<void>
+    tsAssignSlot(teamSubscriptionId: string, teamSubscriptionSlotId: string, identityStr: string | undefined): Promise<void>
     tsReassignSlot(teamSubscriptionId: string, teamSubscriptionSlotId: string, newIdentityStr: string): Promise<void>;
     tsDeactivateSlot(teamSubscriptionId: string, teamSubscriptionSlotId: string): Promise<void>;
     tsReactivateSlot(teamSubscriptionId: string, teamSubscriptionSlotId: string): Promise<void>;
 
     getGithubUpgradeUrls(): Promise<GithubUpgradeURL[]>;
 
+    /**
+     * Analytics
+     */
+    trackEvent(event: RemoteTrackMessage): Promise<void>;
+    trackLocation(event: RemotePageMessage): Promise<void>;
+    identifyUser(event: RemoteIdentifyMessage): Promise<void>;
+}
+
+export interface RateLimiterError {
+    method?: string,
+
+    /**
+     * Retry after this many seconds, earliest.
+     * cmp.: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
+     */
+    retryAfter: number,
+}
+
+export interface CreateProjectParams {
+    name: string;
+    slug?: string;
+    account: string;
+    provider: string;
+    cloneUrl: string;
+    teamId?: string;
+    userId?: string;
+    appInstallationId: string;
+}
+export interface FindPrebuildsParams {
+    projectId: string;
+    branch?: string;
+    latest?: boolean;
+    prebuildId?: string;
+    // default: 30
+    limit?: number;
+}
+export interface GetProviderRepositoriesParams {
+    provider: string;
+    hints?: { installationId: string } | object;
+}
+export interface ProviderRepository {
+    name: string;
+    path?: string;
+    account: string;
+    accountAvatarUrl: string;
+    cloneUrl: string;
+    updatedAt: string;
+    installationId?: number;
+    installationUpdatedAt?: string;
+
+    inUse?: { userName: string };
+}
+
+export interface ClientHeaderFields {
+    ip?: string;
+    userAgent?: string;
+    dnt?: string;
+    clientRegion?: string;
 }
 
 export const WorkspaceTimeoutValues = ["30m", "60m", "180m"] as const;
@@ -205,6 +307,7 @@ export const createServerMock = function <C extends GitpodClient, S extends Gitp
     methods.setClient = methods.setClient || (() => { });
     methods.dispose = methods.dispose || (() => { });
     return new Proxy<JsonRpcProxy<S>>(methods as any as JsonRpcProxy<S>, {
+        // @ts-ignore
         get: (target: S, property: keyof S) => {
             const result = target[property];
             if (!result) {
@@ -237,6 +340,8 @@ export namespace GitpodServer {
         limit?: number;
         searchString?: string;
         pinnedOnly?: boolean;
+        projectId?: string | string[];
+        includeWithoutProject?: boolean;
     }
     export interface GetAccountStatementOptions {
         date?: string;
@@ -244,6 +349,7 @@ export namespace GitpodServer {
     export interface CreateWorkspaceOptions {
         contextUrl: string;
         mode?: CreateWorkspaceMode;
+        forceDefaultConfig?: boolean;
     }
     export interface StartWorkspaceOptions {
         forceDefaultImage: boolean;
@@ -251,13 +357,8 @@ export namespace GitpodServer {
     export interface TakeSnapshotOptions {
         workspaceId: string;
         layoutData?: string;
-    }
-    export interface GetUserMessagesOptions {
-        readonly releaseNotes?: boolean;
-        readonly workspaceInstanceId: string;
-    }
-    export interface UpdateUserMessagesOptions {
-        readonly messageIds: string[];
+        /* this is here to enable backwards-compatibility and untangling rollout between workspace, IDE and meta */
+        dontWait?: boolean;
     }
     export interface GetUserStorageResourceOptions {
         readonly uri: string;
@@ -299,10 +400,12 @@ export class GitpodCompositeClient<Client extends GitpodClient> implements Gitpo
 
     public registerClient(client: Partial<Client>): Disposable {
         this.clients.push(client);
-        const index = this.clients.length;
         return {
             dispose: () => {
-                this.clients.slice(index, 1);
+                const index = this.clients.indexOf(client);
+                if (index > -1) {
+                    this.clients.splice(index, 1);
+                }
             }
         }
     }
@@ -319,11 +422,11 @@ export class GitpodCompositeClient<Client extends GitpodClient> implements Gitpo
         }
     }
 
-    onWorkspaceImageBuildLogs(info: WorkspaceImageBuild.StateInfo, content: WorkspaceImageBuild.LogContent | undefined): void {
+    onPrebuildUpdate(update: PrebuildWithStatus): void {
         for (const client of this.clients) {
-            if (client.onWorkspaceImageBuildLogs) {
+            if (client.onPrebuildUpdate) {
                 try {
-                    client.onWorkspaceImageBuildLogs(info, content);
+                    client.onPrebuildUpdate(update);
                 } catch (error) {
                     console.error(error)
                 }
@@ -331,11 +434,11 @@ export class GitpodCompositeClient<Client extends GitpodClient> implements Gitpo
         }
     }
 
-    onHeadlessWorkspaceLogs(evt: HeadlessLogEvent): void {
+    onWorkspaceImageBuildLogs(info: WorkspaceImageBuild.StateInfo, content: WorkspaceImageBuild.LogContent | undefined): void {
         for (const client of this.clients) {
-            if (client.onHeadlessWorkspaceLogs) {
+            if (client.onWorkspaceImageBuildLogs) {
                 try {
-                    client.onHeadlessWorkspaceLogs(evt);
+                    client.onWorkspaceImageBuildLogs(info, content);
                 } catch (error) {
                     console.error(error)
                 }
@@ -399,7 +502,7 @@ export class WorkspaceInstanceUpdateListener {
     private readonly onDidChangeEmitter = new Emitter<void>();
     readonly onDidChange = this.onDidChangeEmitter.event;
 
-    private source: 'sync' | 'update' = 'sync';
+    private source: 'sync' | 'update' = 'sync';
 
     get info(): WorkspaceInfo {
         return this._info;
@@ -491,11 +594,15 @@ export class WorkspaceInstanceUpdateListener {
 
 }
 
+export interface GitpodServiceOptions {
+    onReconnect?: () => (void | Promise<void>)
+}
+
 export class GitpodServiceImpl<Client extends GitpodClient, Server extends GitpodServer> {
 
     private readonly compositeClient = new GitpodCompositeClient<Client>();
 
-    constructor(public readonly server: JsonRpcProxy<Server>) {
+    constructor(public readonly server: JsonRpcProxy<Server>, private options?: GitpodServiceOptions) {
         server.setClient(this.compositeClient);
         server.onDidOpenConnection(() => this.compositeClient.notifyDidOpenConnection());
         server.onDidCloseConnection(() => this.compositeClient.notifyDidCloseConnection());
@@ -515,13 +622,34 @@ export class GitpodServiceImpl<Client extends GitpodClient, Server extends Gitpo
         this.instanceListeners.set(workspaceId, listener);
         return listener;
     }
+
+    async reconnect(): Promise<void> {
+        if (this.options?.onReconnect) {
+            await this.options.onReconnect();
+        }
+    }
 }
 
-export function createGitpodService<C extends GitpodClient, S extends GitpodServer>(serverUrl: string) {
-    const url = new GitpodHostUrl(serverUrl)
-        .asWebsocket()
-        .withApi({ pathname: GitpodServerPath });
+export function createGitpodService<C extends GitpodClient, S extends GitpodServer>(serverUrl: string | Promise<string>) {
+    const toWsUrl = (serverUrl: string) => {
+        return new GitpodHostUrl(serverUrl)
+            .asWebsocket()
+            .withApi({ pathname: GitpodServerPath })
+            .toString();
+    };
+    let url: string | Promise<string>;
+    if (typeof serverUrl === "string") {
+        url = toWsUrl(serverUrl);
+    } else {
+        url = serverUrl.then(url => toWsUrl(url));
+    }
+
     const connectionProvider = new WebSocketConnectionProvider();
-    const gitpodServer = connectionProvider.createProxy<S>(url.toString());
-    return new GitpodServiceImpl<C, S>(gitpodServer);
+    let onReconnect = () => { };
+    const gitpodServer = connectionProvider.createProxy<S>(url, undefined, {
+        onListening: socket => {
+            onReconnect = () => socket.reconnect();
+        }
+    });
+    return new GitpodServiceImpl<C, S>(gitpodServer, { onReconnect });
 }

package/src/headless-workspace-log.ts

@@ -11,6 +11,7 @@ export enum HeadlessWorkspaceEventType {
     FinishedButFailed = "finish-fail",
     AbortedTimedOut = "aborted-timeout",
     Aborted = "aborted",
+    Failed = "failed",
     Started = "started"
 }
 export namespace HeadlessWorkspaceEventType {
@@ -22,21 +23,17 @@ export namespace HeadlessWorkspaceEventType {
     }
 }
 
-export interface HeadlessLogEvent {
+export interface HeadlessWorkspaceEvent {
     workspaceID: string;
     text: string;
     type: HeadlessWorkspaceEventType;
 }
 
-export enum TheiaHeadlessLogType {
-    TaskLogLabel = "workspaceTaskOutput",
-    TaskFailedLabel = "workspaceTaskFailed",
-    TaskSuccessfulLabel = "workspaceTaskDone"
+export interface HeadlessLogUrls {
+    // A map of id to URL
+    streams: { [streamID: string]: string };
 }
 
-export interface TheiaHeadlessLogMessage {
-    type: TheiaHeadlessLogType;
-    data?: string;
-    error?: string;
-    snapshotURL?: string;
-}
+/** cmp. @const HEADLESS_LOG_STREAM_STATUS_CODE_REGEX */
+export const HEADLESS_LOG_STREAM_STATUS_CODE = "X-LogStream-StatusCode";
+export const HEADLESS_LOG_STREAM_STATUS_CODE_REGEX = /X-LogStream-StatusCode: ([0-9]{3})/;

package/src/ide-frontend-service.ts

@@ -7,7 +7,7 @@
 import { Event } from "./util/event";
 import { Disposable } from "./util/disposable";
 
-export type IDEFrontendState = 'init' | 'ready' | 'terminated';
+export type IDEFrontendState = 'init' | 'ready' | 'terminated';
 
 export interface IDEFrontendService {
     readonly state: IDEFrontendState;