coder · mafredri · Nov 9, 2022 · Nov 7, 2022 · Nov 8, 2022 · Nov 8, 2022
diff --git a/cli/cliui/agent.go b/cli/cliui/agent.go
@@ -35,12 +35,11 @@ func Agent(ctx context.Context, writer io.Writer, opts AgentOptions) error {
 	if err != nil {
 		return xerrors.Errorf("fetch: %w", err)
 	}
+
 	if agent.Status == codersdk.WorkspaceAgentConnected {
 		return nil
 	}
-	if agent.Status == codersdk.WorkspaceAgentDisconnected {
-		opts.WarnInterval = 0
-	}
+
 	spin := spinner.New(spinner.CharSets[78], 100*time.Millisecond, spinner.WithColor("fgHiGreen"))
 	spin.Writer = writer
 	spin.ForceOutput = true
@@ -65,43 +64,70 @@ func Agent(ctx context.Context, writer io.Writer, opts AgentOptions) error {
 		os.Exit(1)
 	}()
 
-	ticker := time.NewTicker(opts.FetchInterval)
-	defer ticker.Stop()
-	timer := time.NewTimer(opts.WarnInterval)
-	defer timer.Stop()
-	go func() {
-		select {
-		case <-ctx.Done():
-			return
-		case <-timer.C:
-		}
+	warningShown := false
+	warnAfter := time.NewTimer(opts.WarnInterval)
+	defer warnAfter.Stop()
+	showWarning := func() {
+		warnAfter.Stop()
+
 		resourceMutex.Lock()
 		defer resourceMutex.Unlock()
-		message := "Don't panic, your workspace is booting up!"
-		if agent.Status == codersdk.WorkspaceAgentDisconnected {
-			message = "The workspace agent lost connection! Wait for it to reconnect or restart your workspace."
+		if warningShown {
+			return
 		}
+		warningShown = true
+
+		message := waitingMessage(agent)
 		// This saves the cursor position, then defers clearing from the cursor
 		// position to the end of the screen.
 		_, _ = fmt.Fprintf(writer, "\033[s\r\033[2K%s\n\n", Styles.Paragraph.Render(Styles.Prompt.String()+message))
 		defer fmt.Fprintf(writer, "\033[u\033[J")
+	}
+	go func() {
+		select {
+		case <-ctx.Done():
+		case <-warnAfter.C:
+			showWarning()
+		}
 	}()
+
+	fetchInterval := time.NewTicker(opts.FetchInterval)
+	defer fetchInterval.Stop()
 	for {
 		select {
 		case <-ctx.Done():
 			return ctx.Err()
-		case <-ticker.C:
+		case <-fetchInterval.C:
 		}
 		resourceMutex.Lock()
 		agent, err = opts.Fetch(ctx)
 		if err != nil {
-			return xerrors.Errorf("fetch: %w", err)
-		}
-		if agent.Status != codersdk.WorkspaceAgentConnected {
 			resourceMutex.Unlock()
-			continue
+			return xerrors.Errorf("fetch: %w", err)
 		}
 		resourceMutex.Unlock()
-		return nil
+		switch agent.Status {
+		case codersdk.WorkspaceAgentConnected:
+			return nil
+		case codersdk.WorkspaceAgentTimeout, codersdk.WorkspaceAgentDisconnected:
+			showWarning()
+		}
+	}
+}
+
+func waitingMessage(agent codersdk.WorkspaceAgent) string {
+	var m string
+	switch agent.Status {
+	case codersdk.WorkspaceAgentTimeout:
+		m = "The workspace agent is having trouble connecting."
+	case codersdk.WorkspaceAgentDisconnected:
+		m = "The workspace agent lost connection!"
+	default:
+		// Not a failure state, no troubleshooting necessary.
+		return "Don't panic, your workspace is booting up!"
+	}
+	if agent.TroubleshootingURL != "" {
+		return fmt.Sprintf("%s See troubleshooting instructions at: %s", m, agent.TroubleshootingURL)
 	}
+	return fmt.Sprintf("%s Wait for it to (re)connect or restart your workspace.", m)
 }
diff --git a/cli/cliui/resources.go b/cli/cliui/resources.go
@@ -127,6 +127,13 @@ func renderAgentStatus(agent codersdk.WorkspaceAgent) string {
 		since := database.Now().Sub(*agent.DisconnectedAt)
 		return Styles.Error.Render("⦾ disconnected") + " " +
 			Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]")
+	case codersdk.WorkspaceAgentTimeout:
+		since := database.Now().Sub(agent.CreatedAt)
+		return fmt.Sprintf(
+			"%s %s",
+			Styles.Warn.Render("⦾ timeout"),
+			Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]"),
+		)
 	case codersdk.WorkspaceAgentConnected:
 		return Styles.Keyword.Render("⦿ connected")
 	default:

diff --git a/cli/speedtest_test.go b/cli/speedtest_test.go
@@ -20,7 +20,7 @@ func TestSpeedtest(t *testing.T) {
 	if testing.Short() {
 		t.Skip("This test takes a minimum of 5ms per a hardcoded value in Tailscale!")
 	}
-	client, workspace, agentToken := setupWorkspaceForAgent(t)
+	client, workspace, agentToken := setupWorkspaceForAgent(t, nil)
 	agentClient := codersdk.New(client.URL)
 	agentClient.SessionToken = agentToken
 	agentCloser := agent.New(agent.Options{

diff --git a/cli/ssh_test.go b/cli/ssh_test.go
@@ -31,8 +31,13 @@ import (
 	"github.com/coder/coder/testutil"
 )
 
-func setupWorkspaceForAgent(t *testing.T) (*codersdk.Client, codersdk.Workspace, string) {
+func setupWorkspaceForAgent(t *testing.T, mutate func([]*proto.Agent) []*proto.Agent) (*codersdk.Client, codersdk.Workspace, string) {
 	t.Helper()
+	if mutate == nil {
+		mutate = func(a []*proto.Agent) []*proto.Agent {
+			return a
+		}
+	}
 	client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
 	user := coderdtest.CreateFirstUser(t, client)
 	agentToken := uuid.NewString()
@@ -45,12 +50,12 @@ func setupWorkspaceForAgent(t *testing.T) (*codersdk.Client, codersdk.Workspace,
 					Resources: []*proto.Resource{{
 						Name: "dev",
 						Type: "google_compute_instance",
-						Agents: []*proto.Agent{{
+						Agents: mutate([]*proto.Agent{{
 							Id: uuid.NewString(),
 							Auth: &proto.Agent_Token{
 								Token: agentToken,
 							},
-						}},
+						}}),
 					}},
 				},
 			},
@@ -69,7 +74,7 @@ func TestSSH(t *testing.T) {
 	t.Run("ImmediateExit", func(t *testing.T) {
 		t.Parallel()
 
-		client, workspace, agentToken := setupWorkspaceForAgent(t)
+		client, workspace, agentToken := setupWorkspaceForAgent(t, nil)
 		cmd, root := clitest.New(t, "ssh", workspace.Name)
 		clitest.SetupConfig(t, client, root)
 		pty := ptytest.New(t)
@@ -100,9 +105,38 @@ func TestSSH(t *testing.T) {
 		pty.WriteLine("exit")
 		<-cmdDone
 	})
+	t.Run("ShowTroubleshootingURLAfterTimeout", func(t *testing.T) {
+		t.Parallel()
+
+		wantURL := "https://example.com/troubleshoot"
+		client, workspace, _ := setupWorkspaceForAgent(t, func(a []*proto.Agent) []*proto.Agent {
+			// Unfortunately, one second is the lowest
+			// we can go because 0 disables the feature.
+			a[0].ConnectionTimeoutSeconds = 1
+			a[0].TroubleshootingUrl = wantURL
+			return a
+		})
+		cmd, root := clitest.New(t, "ssh", workspace.Name)
+		clitest.SetupConfig(t, client, root)
+		pty := ptytest.New(t)
+		cmd.SetIn(pty.Input())
+		cmd.SetErr(pty.Output())
+		cmd.SetOut(pty.Output())
+
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+		defer cancel()
+
+		cmdDone := tGo(t, func() {
+			err := cmd.ExecuteContext(ctx)
+			assert.ErrorIs(t, err, context.Canceled)
+		})
+		pty.ExpectMatch(wantURL)
+		cancel()
+		<-cmdDone
+	})
 	t.Run("Stdio", func(t *testing.T) {
 		t.Parallel()
-		client, workspace, agentToken := setupWorkspaceForAgent(t)
+		client, workspace, agentToken := setupWorkspaceForAgent(t, nil)
 		_, _ = tGoContext(t, func(ctx context.Context) {
 			// Run this async so the SSH command has to wait for
 			// the build and agent to connect!
@@ -171,7 +205,7 @@ func TestSSH(t *testing.T) {
 
 		t.Parallel()
 
-		client, workspace, agentToken := setupWorkspaceForAgent(t)
+		client, workspace, agentToken := setupWorkspaceForAgent(t, nil)
 
 		agentClient := codersdk.New(client.URL)
 		agentClient.SessionToken = agentToken

diff --git a/coderd/database/databasefake/databasefake.go b/coderd/database/databasefake/databasefake.go
@@ -154,6 +154,7 @@ func (q *fakeQuerier) AcquireProvisionerJob(_ context.Context, arg database.Acqu
 	}
 	return database.ProvisionerJob{}, sql.ErrNoRows
 }
+
 func (*fakeQuerier) DeleteOldAgentStats(_ context.Context) error {
 	// no-op
 	return nil
@@ -2362,20 +2363,22 @@ func (q *fakeQuerier) InsertWorkspaceAgent(_ context.Context, arg database.Inser
 	defer q.mutex.Unlock()
 
 	agent := database.WorkspaceAgent{
-		ID:                   arg.ID,
-		CreatedAt:            arg.CreatedAt,
-		UpdatedAt:            arg.UpdatedAt,
-		ResourceID:           arg.ResourceID,
-		AuthToken:            arg.AuthToken,
-		AuthInstanceID:       arg.AuthInstanceID,
-		EnvironmentVariables: arg.EnvironmentVariables,
-		Name:                 arg.Name,
-		Architecture:         arg.Architecture,
-		OperatingSystem:      arg.OperatingSystem,
-		Directory:            arg.Directory,
-		StartupScript:        arg.StartupScript,
-		InstanceMetadata:     arg.InstanceMetadata,
-		ResourceMetadata:     arg.ResourceMetadata,
+		ID:                       arg.ID,
+		CreatedAt:                arg.CreatedAt,
+		UpdatedAt:                arg.UpdatedAt,
+		ResourceID:               arg.ResourceID,
+		AuthToken:                arg.AuthToken,
+		AuthInstanceID:           arg.AuthInstanceID,
+		EnvironmentVariables:     arg.EnvironmentVariables,
+		Name:                     arg.Name,
+		Architecture:             arg.Architecture,
+		OperatingSystem:          arg.OperatingSystem,
+		Directory:                arg.Directory,
+		StartupScript:            arg.StartupScript,
+		InstanceMetadata:         arg.InstanceMetadata,
+		ResourceMetadata:         arg.ResourceMetadata,
+		ConnectionTimeoutSeconds: arg.ConnectionTimeoutSeconds,
+		TroubleshootingURL:       arg.TroubleshootingURL,
 	}
 
 	q.provisionerJobAgents = append(q.provisionerJobAgents, agent)

diff --git a/coderd/database/dump.sql b/coderd/database/dump.sql
diff --git a/.../database/migrations/000072_add_agent_connection_timeout_and_troubleshooting_url.down.sql b/.../database/migrations/000072_add_agent_connection_timeout_and_troubleshooting_url.down.sql
@@ -0,0 +1,9 @@
+BEGIN;
+
+ALTER TABLE workspace_agents
+	DROP COLUMN connection_timeout_seconds;
+
+ALTER TABLE workspace_agents
+	DROP COLUMN troubleshooting_url;
+
+COMMIT;
diff --git a/...rd/database/migrations/000072_add_agent_connection_timeout_and_troubleshooting_url.up.sql b/...rd/database/migrations/000072_add_agent_connection_timeout_and_troubleshooting_url.up.sql
@@ -0,0 +1,13 @@
+BEGIN;
+
+ALTER TABLE workspace_agents
+	ADD COLUMN connection_timeout_seconds integer NOT NULL DEFAULT 0;
+
+COMMENT ON COLUMN workspace_agents.connection_timeout_seconds IS 'Connection timeout in seconds, 0 means disabled.';
+
+ALTER TABLE workspace_agents
+	ADD COLUMN troubleshooting_url text NOT NULL DEFAULT '';
+
+COMMENT ON COLUMN workspace_agents.troubleshooting_url IS 'URL for troubleshooting the agent.';
+
+COMMIT;
diff --git a/coderd/database/models.go b/coderd/database/models.go