> [!NOTE] > Generated by Coder Agents. The branch and this description were written by an AI agent and need human review. ## Summary First of three stacked PRs for the docs IA overhaul (Proposal 1, section 3). This PR dissolves `docs/ai-coder/` into four top-level sidebar sections, in this order, where "Run AI coding agents in Coder" used to be: **Coder Agents**, **AI Governance** (with Agent Firewall and AI Gateway nested under it), **Agent Relay**, and **MCP server**. - Files move with `git mv`, so `git log --follow` keeps their history. The move includes every file in the moved folders, including pages that are not in the sidebar, such as `agent-firewall/example-policy.md`, and pages added to `main` after the first version of this PR, such as `agents/projects.md` (#30684) and `agents/acp-subagents.md` (#31430). - `docs/ai-coder/index.md`, `best-practices.md`, and `ide-agents.md` are deleted. Each has a redirect (see below). - `docs/manifest/` mirrors the new folders: `coder-agents.yml` (+ `coder-agents/`), `ai-governance.yml` (+ `ai-governance/`), `agent-relay.yml`, and `mcp-server.yml`. `ai-coder.yml` is deleted. The Projects and ACP subagents entries from `main` move with Coder Agents. - Every relative link and image path is fixed, both in the moved pages (their base directory changed) and in pages that link to them. This was done in one scripted pass from a clean `main` checkout. Every link was then checked to resolve on disk. - Commit 2, `chore: point in-product docs links at the new docs paths`, updates docs URLs outside `docs/`: `site/` `docs()` links, Go error strings and comments, `README.md`, `server.json`, templatebuilder modules, and the doc-check skill. Commit 4 reverts the unversioned `https://coder.com/docs/...` URLs among them (see below), so after this PR only these differ from `main` outside `docs/`: the `site/` `docs()` links, the versioned `cli/cliui` troubleshooting links, and repo file paths in comments and the doc-check skill's examples (`docs/coder-agents/...`, `docs/templates/...`). You can drop commit 2; the redirects cover the old URLs. - **#31646 (Templates) was squash-merged into this branch** as `98377a3a3b`. This PR now also carries the Templates move (`docs/admin/templates/**` → `docs/templates/**`, plus `template-from-scratch.md` and `testing-templates.md`) and its chore changes. Refer to #31646 for that part's move map, redirects, and review. - Commit 4, `fix: keep docs links healthy before the release`, keeps links working on the live site until a release that includes this stack becomes the default docs version: - Hand-written pages that linked to moved pages with absolute `https://coder.com/docs/...` URLs now use relative links, anchors kept. The new paths 404 on the live site today, but relative links resolve for every version and are checked locally. - Hardcoded, unversioned `https://coder.com/docs/<new path>` URLs outside `docs/` that the chore commits introduced (Go strings including the prebuilds metric help, CLI help, the `agentFallbackTroubleshootingURL` default, `README.md`, `server.json`, examples, templatebuilder files, and one `site/` constant) go back to their current paths. Then `make gen` regenerated the generated table in `docs/admin/integrations/prometheus.md`, `scripts/metricsdocgen/generated_metrics`, the CLI golden files, and `docs/reference/cli/templates/{create,edit}.md`. See "Post-release follow-up". - The `site/` `docs()` changes and the `cli/cliui` links stay, because those URLs are versioned (`/docs/@vX.Y.Z/...`) and resolve once the release ships. - Commit 5, `docs: prefix relative links in the moved pages with ./`, adds `./` to 13 relative links that the move script wrote without it, in `docs/mcp-server.md` and three Templates pages. They resolved, but every other relative link in the docs starts with `./` or `../`. - Commit 6, `docs: keep the coding agent module guidance in the templates docs`, adds an **AI agent modules** section to `docs/templates/extending-templates/modules.md`. Deleting `docs/ai-coder/index.md` removed the only instructions for adding a terminal coding agent to a template with a registry module. The example (`registry.coder.com/coder/claude-code/coder`, `version = "~> 5.2"`) passes `terraform validate`, and the Template Builder labels it cites match `site/src/pages/TemplateBuilder/ModuleSelectStep.tsx`. Stack: **this PR** (with #31646 squash-merged in) → `docs/ia-tutorials-nav` (#31647, Tutorials + nav renames) → `docs/ia-workspaces-folder` (#31650, folder rename). Refs: Linear DOCS-1154, DOCS-1179, and DOCS-1479 for the coder.com and router redirect fix. ## Move map | Old | New | | --- | --- | | `docs/ai-coder/agents/**` (25 files) | `docs/coder-agents/**` | | `docs/ai-coder/ai-governance.md` | `docs/ai-governance/index.md` | | `docs/ai-coder/agent-firewall/**` (9 files) | `docs/ai-governance/agent-firewall/**` | | `docs/ai-coder/ai-gateway/**` (26 files) | `docs/ai-governance/ai-gateway/**` | | `docs/ai-coder/agent-relay/**` (3 files) | `docs/agent-relay/**` | | `docs/ai-coder/mcp-server.md` | `docs/mcp-server.md` | | `docs/ai-coder/index.md` | deleted | | `docs/ai-coder/best-practices.md` | deleted | | `docs/ai-coder/ide-agents.md` | deleted | ## Redirects added Appended to `docs/redirects.json`, using the absolute `/docs/...` format that `main` validates today. Wildcards cover every page under each moved folder, including pages that are not in the sidebar and the pages added to `main` since the first version of this PR. | Source | Destination | | --- | --- | | `/docs/ai-coder` | `/docs/coder-agents` (deleted hub, **please confirm**) | | `/docs/ai-coder/best-practices` | `/docs/coder-agents` (deleted, **please confirm**) | | `/docs/ai-coder/ide-agents` | `/docs/user-guides/workspace-access` (deleted, **please confirm**) | | `/docs/ai-coder/ai-governance` | `/docs/ai-governance` | | `/docs/ai-coder/mcp-server` | `/docs/mcp-server` | | `/docs/ai-coder/agents/:path*` | `/docs/coder-agents/:path*` | | `/docs/ai-coder/agent-firewall/:path*` | `/docs/ai-governance/agent-firewall/:path*` | | `/docs/ai-coder/ai-gateway/:path*` | `/docs/ai-governance/ai-gateway/:path*` | | `/docs/ai-coder/agent-relay/:path*` | `/docs/agent-relay/:path*` | None of the 3 existing rules in `docs/redirects.json` points into `ai-coder/`, so no destinations needed updating. **coder.com and router static redirects.** coder.com applies its own `redirects.json` and the rules it generates from this file before it hands `/docs` to the docs-engine router, which applies its own static `redirects.json` before the page. Three older static rules in both repos send `/docs/templates`, `/docs/templates/open-in-coder`, and `/docs/templates/troubleshooting` to `/docs/admin/templates/...`, and the `/docs/admin/templates/:path*` rule here sends them back, so each loops once a release with this layout is the docs mainline. A static `/docs/workspaces` rule would also hide the new `docs/workspaces/index.md` page from #31650. coder/coder.com#1201 and coder/docs-engine#304 (draft, DOCS-1479) remove those rules; they must merge when that release becomes the mainline, not before, because the old-layout mainline still needs them. A chain simulation of every page and static source on each branch of this stack finds no other loops or hidden pages. The `/docs/ai-coder/...` and other legacy rules there still work; some now take two redirects. ## Deviations from the proposal - **Glossary "IDE agent" entry.** The proposal says to remove this link and leave plain text. I pointed it at Access your workspace (`docs/user-guides/workspace-access/index.md`) instead, the same page the `ide-agents` redirect uses, because "Refer to IDE agents." with no link reads as a dead end. The "Coding agent" entry now links to Coder Agents, as the proposal says. - **Top-level icons.** The new sections need icons. I chose `wand.svg` (Coder Agents, the old ai-coder icon), `ai_intelligence.svg` (AI Governance), `link.svg` (Agent Relay), and `plug.svg` (MCP server). - **Coding agent module guidance.** Kept on the Reuse template code page (commit 6) instead of deleted with `docs/ai-coder/index.md`. The best-practices and IDE-agent pages are deleted as proposed. - **Order relative to Administration.** In this PR the four sections sit where `ai-coder` was, after Administration. PR C moves Administration after MCP server to reach the final order. - **`docs/mcp-server.md` repo link.** A relative link to `codersdk/toolsdk/toolsdk.go`, outside `docs/`, was re-based for the new depth. - **Left unchanged on purpose:** - Database migrations and the notification `.golden` files rendered from them still contain `coder.com/docs/ai-coder/...` URLs. Existing migrations can't be edited, so those links rely on the redirects. - `aibridge/client/client.go` links to a commit-pinned GitHub permalink, which still resolves. - Test fixtures in `scripts/docsredirectscheck` and `.github/workflows/test-docs-preview-mapper.sh` use `ai-coder` as sample data. - `site/src/pages/AgentsPage/components/ChatElements/tools/Tool.stories.tsx` uses `https://coder.com/docs/ai-coder/ai-gateway` as a sample web search result. Changing it would only change a visual snapshot. ## Open questions for Nick 1. Do you agree with the three redirect targets for the deleted pages above? 2. Should the "IDE agent" glossary entry link to Access your workspace (current) or be plain text (proposal)? 3. Are the icons for the new top-level sections OK? 4. Open PRs that touch the moved files, checked with `git merge-tree` against this branch. I didn't change them. - #31169 merges cleanly: Git's rename detection carries its edit to `docs/ai-governance/ai-gateway/clients/claude-code.md`, and its new relative link still resolves at the new path. - #30262 now targets `tk/ai-gateway-responses-ws-endpoint` and conflicts with `main` in 21 files. Against this branch it conflicts in the same 21 files, with `codex.md` at its new path, so this PR doesn't add new conflicts. Its new relative links still resolve after the move. - #30805 conflicts in `docs/redirects.json`. It already conflicts with `main` there, because `main` added the `/docs/about/screenshots` and `/docs/install/cli` rules. ## Release No backport to `release/2.39` for now; Nick may apply it by hand later. A cherry-pick of this branch onto `release/2.39` conflicts in 25 files, and #31647 and #31650 would need the same treatment to keep the stack together. coder/coder.com#1201 and coder/docs-engine#304 merge when the first release line that carries this layout becomes the docs mainline (2.38 today). ## Known limitations - **CLI newer than its server.** The `cli/cliui` troubleshooting links append `/templates/troubleshooting#...` to the server's versioned docs URL. A CLI from this release against an older server prints `/docs/@v2.38.x/templates/troubleshooting#...`. The router's static `/docs/templates/:page(open-in-coder|troubleshooting)` rule redirects that to the old page today, but coder/docs-engine#304 removes that rule to fix the loop, so after the cutover that case gets the version's not-found page. ## Post-release follow-up After a release that includes this stack becomes the default docs version on coder.com, point these hardcoded URLs at the new paths. They work today and redirect after the release, so nothing breaks in the meantime. Anchors are unchanged. Rerun `make gen` afterward to update `docs/admin/integrations/prometheus.md`, `scripts/metricsdocgen/generated_metrics`, the CLI golden files, and `docs/reference/cli/templates/{create,edit}.md`. | Current (old) URL | Post-release URL | Files | | --- | --- | --- | | `https://coder.com/docs/ai-coder/agents` | `https://coder.com/docs/coder-agents` | `.claude/skills/doc-check/output.md`, `README.md` | | `https://coder.com/docs/ai-coder/agents/architecture` | `https://coder.com/docs/coder-agents/architecture` | `coderd/x/chatd/chattool/execute_test.go`, `codersdk/toolsdk/workspacetools/execute.go` | | `https://coder.com/docs/ai-coder/ai-gateway` | `https://coder.com/docs/ai-governance/ai-gateway` | `README.md`, `coderd/templatebuilder/modules/claude-code/module.json`, `coderd/templatebuilder/modules/codex/module.json` | | `https://coder.com/docs/ai-coder/mcp-server` | `https://coder.com/docs/mcp-server` | `server.json` | | `https://coder.com/docs/admin/templates` | `https://coder.com/docs/templates` | `README.md` | | `https://coder.com/docs/admin/templates/extending-templates/docker-in-workspaces` | `https://coder.com/docs/templates/extending-templates/docker-in-workspaces` | `examples/templates/docker-devcontainer/main.tf` | | `https://coder.com/docs/admin/templates/extending-templates/parameters` | `https://coder.com/docs/templates/extending-templates/parameters` | `examples/parameters-dynamic-options/README.md`, `examples/parameters/README.md`, `examples/parameters/main.tf`, `examples/templates/kubernetes-envbox/README.md`, `examples/workspace-tags/README.md` | | `https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces` | `https://coder.com/docs/templates/extending-templates/prebuilt-workspaces` | `coderd/prebuilds/api.go`, `enterprise/coderd/prebuilds/metricscollector.go` (metric help text) | | `https://coder.com/docs/admin/templates/extending-templates/workspace-tags` | `https://coder.com/docs/templates/extending-templates/workspace-tags` | `examples/workspace-tags/README.md` | | `https://coder.com/docs/admin/templates/managing-templates` | `https://coder.com/docs/templates/managing-templates` | `cli/templatecreate.go`, `cli/templateedit.go` (CLI help) | | `https://coder.com/docs/admin/templates/managing-templates/image-management` | `https://coder.com/docs/templates/managing-templates/image-management` | `coderd/templatebuilder/bases/docker/README.md`, `coderd/templatebuilder/bases/kubernetes/README.md` | | `https://coder.com/docs/admin/templates/troubleshooting` | `https://coder.com/docs/templates/troubleshooting` | `agent/agentscripts/agentscripts.go`, `coderd/render/escape_internal_test.go`, `codersdk/deployment.go` (`agentFallbackTroubleshootingURL` default) | | `https://coder.com/docs/tutorials/template-from-scratch` | `https://coder.com/docs/templates/template-from-scratch` | `site/src/pages/TemplateBuilder/TemplateAlternatives.tsx` | ## Validation run - `make gen/docs-manifest`: clean diff afterward. - `make lint/docs-manifest`, `lint/docs-redirects` (`go run ./scripts/docsredirectscheck -base origin/main`: 15 rules OK, no removed-route warning), `lint/docs-html`, `lint/emdash`: pass. - `pnpm check-docs` (markdownlint + table formatter): pass. - Vale (`vale --no-exit docs/`): the same 12 warnings and 1 error as `main`, all pre-existing. Suggestions drop from 646 to 645; the one removed was in the deleted `ide-agents.md`. - Local relative-link check over `docs/**/*.md`: 0 unresolved links or images (also 0 on `main`). - Pre-commit hook: `make pre-commit-light` on the docs commit, and the full `make pre-commit` (gen, fmt, lint/go, lint/ts, build, and others) on the chore commit. Both passed. - Targeted tests: - Go: `go test ./coderd/x/chatd/chattool/... ./codersdk/toolsdk/... ./coderd/templatebuilder/...`. - Site: Vitest for the touched directories (107 files, 1879 tests), and the story tests for `CoderAgentsProductCard`, `GroupSettingsPageView`, `GatewayKeysPageView`, and `ModelForm` (4 files, 63 tests). - Every `docs()` path and anchor in the `site/` and Go diff resolves to a page and heading in this branch. - Frontend deep review (all 8 roles) on the `site/` diff of PRs A and B: no blocking or should-fix findings. Nits on existing code that this PR only touched, not changed here: a single-use `docsLink` constant in `ChatAccessDeniedAlert.tsx`, and assertion-only `play` functions in the `GatewayKeysPageView`, `ModelForm`, `CoderAgentsProductCard`, and `GroupSettingsPageView` stories. - Page counts: `docs/**/*.md` (excluding `.style`) 490 → 487; `manifest.json` routes 495 → 492. With #31646 squash-merged in, the counts don't change, because the Templates move only moves files. - **Link health (commit 4):** - linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`, like the weekly docs job (`umbrelladocs/action-linkspector`, `reporter: local`, `filter_mode: nofilter`). I ran it locally with Chrome in `--no-sandbox` mode. - `origin/main`: 0 errors. Before the fix (`17e54ad555`): 6 errors, all `https://coder.com/docs/<new path>` 404s (`shared-workspaces.md:19`, `esr-2.24-2.29-upgrade.md:80-82`, `tasks-to-chats-migration.md:73`, `prometheus.md:298`). After the fix (`def074caab`): 0 errors. A first run after the fix also flagged a Red Hat URL in `install/server/openshift.md`. That URL is unchanged from `main`, and it passed on a rerun, so the failure was transient. - After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (15 rules OK against `origin/main`), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the relative-link check (0 unresolved in 3416 links) pass. The full `make pre-commit`, including `make gen`, passed on the commit. - Tests after the fix: - Go: `go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig'`, `./enterprise/cli -run TestEnterpriseCommandHelp`, `./coderd/render`, `./agent/agentscripts`, `./coderd/prebuilds`, `./enterprise/coderd/prebuilds`, `./coderd/x/chatd/chattool/...`, `./codersdk/toolsdk/...`, `./coderd/templatebuilder/...`. - Site: Vitest for `src/pages/TemplateBuilder` (7 files, 67 tests). - **After the rebase onto `ccf5ec74ae`** (commits 5 and 6 included): `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (15 rules OK), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and a relative-link and anchor check over the changed pages pass. The only unresolved anchor, `docs/ai-governance/ai-gateway/cost-controls.md` → `enterprise.md#list-organization-ai-spend-by-user`, is also broken on `main`. The pre-commit hook (`make pre-commit-light`, because both new commits touch only `docs/`) passed on commits 5 and 6. The rebased code commits rely on CI for Go and TypeScript checks. - **Redirect chains:** a Node simulation of coder.com's static rules, its generated rules from this branch's `docs/redirects.json`, the router's static rules, the page, then this branch's rules on a miss, over every page and exact static source, reports the 3 loops above and nothing else new; with coder/coder.com#1201 and coder/docs-engine#304 applied, 0. - **Skipped:** the docs-engine sync check, which was not available in this environment. <details> <summary>Implementation notes</summary> - Rebuilt on `main` at `ccf5ec74ae` (2026-11-03) to clear conflicts with `main`, after an earlier rebase the same day onto `1a963c628d`. The previous rebuild was on `9839406ff7` (2026-11-02), and the first version on `9b8d880d63` (2026-10-23). - Rebase conflicts with #31603, which added `target="_blank" rel="noreferrer"` to docs links: 4 `site/` files in the chore commit and 5 in the Templates commit. Each kept `main`'s version of the link with only the docs path changed. Vitest for the 7 affected page directories (233 tests) and the story tests for the 8 changed or affected stories (102 tests) pass, and every `docs()` path in `site/src` resolves except the same 13 that are unresolved on `main`. - Rebase conflict: `docs/manifest/coder-agents.yml`. `main` added `docs/ai-coder/agents/bring-your-own-mcp-servers.md`; it moves to `docs/coder-agents/` with its sidebar entry, and its `../../user-guides/` links become `../user-guides/`. - Folded into the Templates commit: a link that `main` added to `docs/user-guides/workspace-dotfiles.md` (#31606) now points at `../templates/extending-templates/environment-variables.md`. - `git range-diff` against `def074caab`, the head before both rebases, shows only those changes. - The move script reads every page from the clean `main` checkout and resolves each relative link (inline, reference-style, and HTML `src`/`href`) against the page's **old** directory. It maps the target through the move map and recomputes the link from the page's **new** directory. It runs once and refuses to run on a dirty `docs/` tree, so it can't apply the path math twice. It also rewrites absolute `coder.com/docs/...` and `github.com/coder/coder/(blob|edit|tree)/main/docs/...` URLs, and skips fenced code blocks and inline code. - Before reusing the script, I ran it on the old base and diffed the result against the old commit. The only differences were the two hand-edited glossary entries and table padding from the formatter, so the rebuild applies the same changes to the current `main`. - Afterward, `grep -r ai-coder docs/` finds matches only in `docs/redirects.json`. - Changes from the earlier version of this branch: 2 more pages move (`agents/projects.md`, `agents/acp-subagents.md`) and their sidebar entries move with them. The chore commit also updates `SessionSummaryTable.tsx` (new on `main`) and the doc-check skill's `output.md` (its examples moved there from `SKILL.md`). The `AICostControl.tsx` anchor question is gone, because `main` fixed it. </details> --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
583 lines
19 KiB
Go
583 lines
19 KiB
Go
package cliui
|
||
|
||
import (
|
||
"context"
|
||
"fmt"
|
||
"io"
|
||
"strconv"
|
||
"strings"
|
||
"time"
|
||
|
||
"github.com/google/uuid"
|
||
"golang.org/x/xerrors"
|
||
"tailscale.com/tailcfg"
|
||
|
||
"github.com/coder/coder/v2/codersdk"
|
||
"github.com/coder/coder/v2/codersdk/healthsdk"
|
||
"github.com/coder/coder/v2/codersdk/workspacesdk"
|
||
"github.com/coder/coder/v2/tailnet"
|
||
)
|
||
|
||
var errAgentShuttingDown = xerrors.New("agent is shutting down")
|
||
|
||
// fetchAgentResult is used to pass agent fetch results through channels.
|
||
type fetchAgentResult struct {
|
||
agent codersdk.WorkspaceAgent
|
||
err error
|
||
}
|
||
|
||
type AgentOptions struct {
|
||
FetchInterval time.Duration
|
||
Fetch func(ctx context.Context, agentID uuid.UUID) (codersdk.WorkspaceAgent, error)
|
||
FetchLogs func(ctx context.Context, agentID uuid.UUID, after int64, follow bool) (<-chan []codersdk.WorkspaceAgentLog, io.Closer, error)
|
||
Wait bool // If true, wait for the agent to be ready (startup script).
|
||
DocsURL string
|
||
}
|
||
|
||
// agentWaiter encapsulates the state machine for waiting on a workspace agent.
|
||
type agentWaiter struct {
|
||
opts AgentOptions
|
||
sw *stageWriter
|
||
logSources map[uuid.UUID]codersdk.WorkspaceAgentLogSource
|
||
fetchAgent func(context.Context) (codersdk.WorkspaceAgent, error)
|
||
}
|
||
|
||
// Agent displays a spinning indicator that waits for a workspace agent to connect.
|
||
func Agent(ctx context.Context, writer io.Writer, agentID uuid.UUID, opts AgentOptions) error {
|
||
ctx, cancel := context.WithCancel(ctx)
|
||
defer cancel()
|
||
|
||
if opts.FetchInterval == 0 {
|
||
opts.FetchInterval = 500 * time.Millisecond
|
||
}
|
||
if opts.FetchLogs == nil {
|
||
opts.FetchLogs = func(_ context.Context, _ uuid.UUID, _ int64, _ bool) (<-chan []codersdk.WorkspaceAgentLog, io.Closer, error) {
|
||
c := make(chan []codersdk.WorkspaceAgentLog)
|
||
close(c)
|
||
return c, closeFunc(func() error { return nil }), nil
|
||
}
|
||
}
|
||
|
||
fetchedAgent := make(chan fetchAgentResult, 1)
|
||
go func() {
|
||
t := time.NewTimer(0)
|
||
defer t.Stop()
|
||
|
||
startTime := time.Now()
|
||
baseInterval := opts.FetchInterval
|
||
|
||
for {
|
||
select {
|
||
case <-ctx.Done():
|
||
return
|
||
case <-t.C:
|
||
agent, err := opts.Fetch(ctx, agentID)
|
||
select {
|
||
case <-fetchedAgent:
|
||
default:
|
||
}
|
||
if err != nil {
|
||
fetchedAgent <- fetchAgentResult{err: xerrors.Errorf("fetch workspace agent: %w", err)}
|
||
return
|
||
}
|
||
fetchedAgent <- fetchAgentResult{agent: agent}
|
||
|
||
// Adjust the interval based on how long we've been waiting.
|
||
elapsed := time.Since(startTime)
|
||
currentInterval := GetProgressiveInterval(baseInterval, elapsed)
|
||
t.Reset(currentInterval)
|
||
}
|
||
}
|
||
}()
|
||
fetch := func(ctx context.Context) (codersdk.WorkspaceAgent, error) {
|
||
select {
|
||
case <-ctx.Done():
|
||
return codersdk.WorkspaceAgent{}, ctx.Err()
|
||
case f := <-fetchedAgent:
|
||
if f.err != nil {
|
||
return codersdk.WorkspaceAgent{}, f.err
|
||
}
|
||
return f.agent, nil
|
||
}
|
||
}
|
||
|
||
agent, err := fetch(ctx)
|
||
if err != nil {
|
||
return xerrors.Errorf("fetch: %w", err)
|
||
}
|
||
logSources := map[uuid.UUID]codersdk.WorkspaceAgentLogSource{}
|
||
for _, source := range agent.LogSources {
|
||
logSources[source.ID] = source
|
||
}
|
||
|
||
w := &agentWaiter{
|
||
opts: opts,
|
||
sw: &stageWriter{w: writer},
|
||
logSources: logSources,
|
||
fetchAgent: fetch,
|
||
}
|
||
|
||
return w.wait(ctx, agent, fetchedAgent)
|
||
}
|
||
|
||
// wait runs the main state machine loop.
|
||
func (aw *agentWaiter) wait(ctx context.Context, agent codersdk.WorkspaceAgent, fetchedAgent chan fetchAgentResult) error {
|
||
var err error
|
||
// Track whether we've gone through a wait state, which determines if we
|
||
// should show startup logs when connected.
|
||
waitedForConnection := false
|
||
|
||
for {
|
||
// It doesn't matter if we're connected or not, if the agent is
|
||
// shutting down, we don't know if it's coming back.
|
||
if agent.LifecycleState.ShuttingDown() {
|
||
return errAgentShuttingDown
|
||
}
|
||
|
||
switch agent.Status {
|
||
case codersdk.WorkspaceAgentConnecting, codersdk.WorkspaceAgentTimeout:
|
||
agent, err = aw.waitForConnection(ctx, agent)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
// Since we were waiting for the agent to connect, also show
|
||
// startup logs if applicable.
|
||
waitedForConnection = true
|
||
|
||
case codersdk.WorkspaceAgentConnected:
|
||
return aw.handleConnected(ctx, agent, waitedForConnection, fetchedAgent)
|
||
|
||
case codersdk.WorkspaceAgentDisconnected:
|
||
agent, waitedForConnection, err = aw.waitForReconnection(ctx, agent)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
// waitForConnection handles the Connecting/Timeout states.
|
||
// Returns when agent transitions to Connected or Disconnected.
|
||
func (aw *agentWaiter) waitForConnection(ctx context.Context, agent codersdk.WorkspaceAgent) (codersdk.WorkspaceAgent, error) {
|
||
stage := "Waiting for the workspace agent to connect"
|
||
aw.sw.Start(stage)
|
||
|
||
agent, err := aw.pollWhile(ctx, agent, func(agent codersdk.WorkspaceAgent) bool {
|
||
return agent.Status == codersdk.WorkspaceAgentConnecting
|
||
})
|
||
if err != nil {
|
||
return agent, err
|
||
}
|
||
|
||
if agent.Status == codersdk.WorkspaceAgentTimeout {
|
||
now := time.Now()
|
||
aw.sw.Log(now, codersdk.LogLevelInfo, "The workspace agent is having trouble connecting, wait for it to connect or restart your workspace.")
|
||
aw.sw.Log(now, codersdk.LogLevelInfo, troubleshootingMessage(agent, fmt.Sprintf("%s/templates/troubleshooting#agent-connection-issues", aw.opts.DocsURL)))
|
||
agent, err = aw.pollWhile(ctx, agent, func(agent codersdk.WorkspaceAgent) bool {
|
||
return agent.Status == codersdk.WorkspaceAgentTimeout
|
||
})
|
||
if err != nil {
|
||
return agent, err
|
||
}
|
||
}
|
||
|
||
aw.sw.Complete(stage, agent.FirstConnectedAt.Sub(agent.CreatedAt))
|
||
return agent, nil
|
||
}
|
||
|
||
// handleConnected handles the Connected state and startup script logic.
|
||
// This is a terminal state, returns nil on success or error on failure.
|
||
//
|
||
//nolint:revive // Control flag is acceptable for internal method.
|
||
func (aw *agentWaiter) handleConnected(ctx context.Context, agent codersdk.WorkspaceAgent, showStartupLogs bool, fetchedAgent chan fetchAgentResult) error {
|
||
if !showStartupLogs && agent.LifecycleState == codersdk.WorkspaceAgentLifecycleReady {
|
||
// The workspace is ready, there's nothing to do but connect.
|
||
return nil
|
||
}
|
||
|
||
// Determine if we should follow/stream logs (blocking mode).
|
||
follow := aw.opts.Wait && agent.LifecycleState.Starting()
|
||
|
||
stage := "Running workspace agent startup scripts"
|
||
if !follow {
|
||
stage += " (non-blocking)"
|
||
}
|
||
aw.sw.Start(stage)
|
||
|
||
if follow {
|
||
aw.sw.Log(time.Time{}, codersdk.LogLevelInfo, "==> ℹ︎ To connect immediately, reconnect with --wait=no or CODER_SSH_WAIT=no, see --help for more information.")
|
||
}
|
||
|
||
// In non-blocking mode (Wait=false), we don't stream logs. This prevents
|
||
// dumping a wall of logs on users who explicitly pass --wait=no. The stage
|
||
// indicator is still shown, just not the log content. See issue #13580.
|
||
if aw.opts.Wait {
|
||
var err error
|
||
agent, err = aw.streamLogs(ctx, agent, follow, fetchedAgent)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
// If we were following, wait until startup completes.
|
||
if follow {
|
||
agent, err = aw.pollWhile(ctx, agent, func(agent codersdk.WorkspaceAgent) bool {
|
||
return agent.LifecycleState.Starting()
|
||
})
|
||
if err != nil {
|
||
return err
|
||
}
|
||
}
|
||
}
|
||
|
||
// Handle final lifecycle state.
|
||
switch agent.LifecycleState {
|
||
case codersdk.WorkspaceAgentLifecycleReady:
|
||
aw.sw.Complete(stage, safeDuration(aw.sw, agent.ReadyAt, agent.StartedAt))
|
||
case codersdk.WorkspaceAgentLifecycleStartTimeout:
|
||
// Backwards compatibility: Avoid printing warning if
|
||
// coderd is old and doesn't set ReadyAt for timeouts.
|
||
if agent.ReadyAt == nil {
|
||
aw.sw.Fail(stage, 0)
|
||
} else {
|
||
aw.sw.Fail(stage, safeDuration(aw.sw, agent.ReadyAt, agent.StartedAt))
|
||
}
|
||
aw.sw.Log(time.Time{}, codersdk.LogLevelWarn, "Warning: A startup script timed out and your workspace may be incomplete.")
|
||
case codersdk.WorkspaceAgentLifecycleStartError:
|
||
aw.sw.Fail(stage, safeDuration(aw.sw, agent.ReadyAt, agent.StartedAt))
|
||
aw.sw.Log(time.Time{}, codersdk.LogLevelWarn, "Warning: A startup script exited with an error and your workspace may be incomplete.")
|
||
aw.sw.Log(time.Time{}, codersdk.LogLevelWarn, troubleshootingMessage(agent, fmt.Sprintf("%s/templates/troubleshooting#startup-script-exited-with-an-error", aw.opts.DocsURL)))
|
||
default:
|
||
switch {
|
||
case agent.LifecycleState.Starting():
|
||
aw.sw.Log(time.Time{}, codersdk.LogLevelWarn, "Notice: The startup scripts are still running and your workspace may be incomplete.")
|
||
aw.sw.Log(time.Time{}, codersdk.LogLevelWarn, troubleshootingMessage(agent, fmt.Sprintf("%s/templates/troubleshooting#your-workspace-may-be-incomplete", aw.opts.DocsURL)))
|
||
// Note: We don't complete or fail the stage here, it's
|
||
// intentionally left open to indicate this stage didn't
|
||
// complete.
|
||
case agent.LifecycleState.ShuttingDown():
|
||
// We no longer know if the startup script failed or not,
|
||
// but we need to tell the user something.
|
||
aw.sw.Complete(stage, safeDuration(aw.sw, agent.ReadyAt, agent.StartedAt))
|
||
return errAgentShuttingDown
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// streamLogs handles streaming or fetching startup logs.
|
||
//
|
||
//nolint:revive // Control flag is acceptable for internal method.
|
||
func (aw *agentWaiter) streamLogs(ctx context.Context, agent codersdk.WorkspaceAgent, follow bool, fetchedAgent chan fetchAgentResult) (codersdk.WorkspaceAgent, error) {
|
||
logStream, logsCloser, err := aw.opts.FetchLogs(ctx, agent.ID, 0, follow)
|
||
if err != nil {
|
||
return agent, xerrors.Errorf("fetch workspace agent startup logs: %w", err)
|
||
}
|
||
defer logsCloser.Close()
|
||
|
||
var lastLog codersdk.WorkspaceAgentLog
|
||
|
||
// If not following, we don't need to watch for agent state changes.
|
||
var fetchedAgentWhileFollowing chan fetchAgentResult
|
||
if follow {
|
||
fetchedAgentWhileFollowing = fetchedAgent
|
||
}
|
||
|
||
for {
|
||
select {
|
||
case <-ctx.Done():
|
||
return agent, ctx.Err()
|
||
case f := <-fetchedAgentWhileFollowing:
|
||
if f.err != nil {
|
||
return agent, xerrors.Errorf("fetch: %w", f.err)
|
||
}
|
||
agent = f.agent
|
||
|
||
// If the agent is no longer starting, stop following
|
||
// logs because FetchLogs will keep streaming forever.
|
||
// We do one last non-follow request to ensure we have
|
||
// fetched all logs.
|
||
if !agent.LifecycleState.Starting() {
|
||
_ = logsCloser.Close()
|
||
fetchedAgentWhileFollowing = nil
|
||
|
||
logStream, logsCloser, err = aw.opts.FetchLogs(ctx, agent.ID, lastLog.ID, false)
|
||
if err != nil {
|
||
return agent, xerrors.Errorf("fetch workspace agent startup logs: %w", err)
|
||
}
|
||
// Logs are already primed, so we can call close.
|
||
_ = logsCloser.Close()
|
||
}
|
||
case logs, ok := <-logStream:
|
||
if !ok {
|
||
return agent, nil
|
||
}
|
||
for _, log := range logs {
|
||
source, hasSource := aw.logSources[log.SourceID]
|
||
output := log.Output
|
||
if hasSource && source.DisplayName != "" {
|
||
output = source.DisplayName + ": " + output
|
||
}
|
||
aw.sw.Log(log.CreatedAt, log.Level, output)
|
||
lastLog = log
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
// waitForReconnection handles the Disconnected state.
|
||
// Returns when agent reconnects along with whether to show startup logs.
|
||
func (aw *agentWaiter) waitForReconnection(ctx context.Context, agent codersdk.WorkspaceAgent) (codersdk.WorkspaceAgent, bool, error) {
|
||
// If the agent was still starting during disconnect, we'll
|
||
// show startup logs.
|
||
showStartupLogs := agent.LifecycleState.Starting()
|
||
|
||
stage := "The workspace agent lost connection"
|
||
aw.sw.Start(stage)
|
||
aw.sw.Log(time.Now(), codersdk.LogLevelWarn, "Wait for it to reconnect or restart your workspace.")
|
||
aw.sw.Log(time.Now(), codersdk.LogLevelWarn, troubleshootingMessage(agent, fmt.Sprintf("%s/templates/troubleshooting#agent-connection-issues", aw.opts.DocsURL)))
|
||
|
||
disconnectedAt := agent.DisconnectedAt
|
||
agent, err := aw.pollWhile(ctx, agent, func(agent codersdk.WorkspaceAgent) bool {
|
||
return agent.Status == codersdk.WorkspaceAgentDisconnected
|
||
})
|
||
if err != nil {
|
||
return agent, showStartupLogs, err
|
||
}
|
||
aw.sw.Complete(stage, safeDuration(aw.sw, agent.LastConnectedAt, disconnectedAt))
|
||
|
||
return agent, showStartupLogs, nil
|
||
}
|
||
|
||
// pollWhile polls the agent while the condition is true. It fetches the agent
|
||
// on each iteration and returns the updated agent when the condition is false,
|
||
// the context is canceled, or an error occurs.
|
||
func (aw *agentWaiter) pollWhile(ctx context.Context, agent codersdk.WorkspaceAgent, cond func(agent codersdk.WorkspaceAgent) bool) (codersdk.WorkspaceAgent, error) {
|
||
var err error
|
||
for cond(agent) {
|
||
agent, err = aw.fetchAgent(ctx)
|
||
if err != nil {
|
||
return agent, xerrors.Errorf("fetch: %w", err)
|
||
}
|
||
}
|
||
if err = ctx.Err(); err != nil {
|
||
return agent, err
|
||
}
|
||
return agent, nil
|
||
}
|
||
|
||
func troubleshootingMessage(agent codersdk.WorkspaceAgent, url string) string {
|
||
m := "For more information and troubleshooting, see " + url
|
||
if agent.TroubleshootingURL != "" {
|
||
m += " and " + agent.TroubleshootingURL
|
||
}
|
||
return m
|
||
}
|
||
|
||
// safeDuration returns a-b. If a or b is nil, it returns 0.
|
||
// This is because we often dereference a time pointer, which can
|
||
// cause a panic. These dereferences are used to calculate durations,
|
||
// which are not critical, and therefor should not break things
|
||
// when it fails.
|
||
// A panic has been observed in a test.
|
||
func safeDuration(sw *stageWriter, a, b *time.Time) time.Duration {
|
||
if a == nil || b == nil {
|
||
if sw != nil {
|
||
// Ideally the message includes which fields are <nil>, but you can
|
||
// use the surrounding log lines to figure that out. And passing more
|
||
// params makes this unwieldy.
|
||
sw.Log(time.Now(), codersdk.LogLevelWarn, "Warning: Failed to calculate duration from a time being <nil>.")
|
||
}
|
||
return 0
|
||
}
|
||
return a.Sub(*b)
|
||
}
|
||
|
||
// GetProgressiveInterval returns an interval that increases over time.
|
||
// The interval starts at baseInterval and increases to
|
||
// a maximum of baseInterval * 16 over time.
|
||
func GetProgressiveInterval(baseInterval time.Duration, elapsed time.Duration) time.Duration {
|
||
switch {
|
||
case elapsed < 60*time.Second:
|
||
return baseInterval // 500ms for first 60 seconds
|
||
case elapsed < 2*time.Minute:
|
||
return baseInterval * 2 // 1s for next 1 minute
|
||
case elapsed < 5*time.Minute:
|
||
return baseInterval * 4 // 2s for next 3 minutes
|
||
case elapsed < 10*time.Minute:
|
||
return baseInterval * 8 // 4s for next 5 minutes
|
||
default:
|
||
return baseInterval * 16 // 8s after 10 minutes
|
||
}
|
||
}
|
||
|
||
type closeFunc func() error
|
||
|
||
func (c closeFunc) Close() error {
|
||
return c()
|
||
}
|
||
|
||
func PeerDiagnostics(w io.Writer, d tailnet.PeerDiagnostics) {
|
||
if d.PreferredDERP > 0 {
|
||
rn, ok := d.DERPRegionNames[d.PreferredDERP]
|
||
if !ok {
|
||
rn = "unknown"
|
||
}
|
||
_, _ = fmt.Fprintf(w, "✔ preferred DERP region: %d (%s)\n", d.PreferredDERP, rn)
|
||
} else {
|
||
_, _ = fmt.Fprint(w, "✘ not connected to DERP\n")
|
||
}
|
||
if d.SentNode {
|
||
_, _ = fmt.Fprint(w, "✔ sent local data to Coder networking coordinator\n")
|
||
} else {
|
||
_, _ = fmt.Fprint(w, "✘ have not sent local data to Coder networking coordinator\n")
|
||
}
|
||
if d.ReceivedNode != nil {
|
||
dp := d.ReceivedNode.DERP
|
||
dn := ""
|
||
// should be 127.3.3.40:N where N is the DERP region
|
||
ap := strings.Split(dp, ":")
|
||
if len(ap) == 2 {
|
||
dp = ap[1]
|
||
di, err := strconv.Atoi(dp)
|
||
if err == nil {
|
||
var ok bool
|
||
dn, ok = d.DERPRegionNames[di]
|
||
if ok {
|
||
dn = fmt.Sprintf("(%s)", dn)
|
||
} else {
|
||
dn = "(unknown)"
|
||
}
|
||
}
|
||
}
|
||
_, _ = fmt.Fprintf(w,
|
||
"✔ received remote agent data from Coder networking coordinator\n preferred DERP region: %s %s\n endpoints: %s\n",
|
||
dp, dn, strings.Join(d.ReceivedNode.Endpoints, ", "))
|
||
} else {
|
||
_, _ = fmt.Fprint(w, "✘ have not received remote agent data from Coder networking coordinator\n")
|
||
}
|
||
if !d.LastWireguardHandshake.IsZero() {
|
||
ago := time.Since(d.LastWireguardHandshake)
|
||
symbol := "✔"
|
||
// wireguard is supposed to refresh handshake on 5 minute intervals
|
||
if ago > 5*time.Minute {
|
||
symbol = "⚠"
|
||
}
|
||
_, _ = fmt.Fprintf(w, "%s Wireguard handshake %s ago\n", symbol, ago.Round(time.Second))
|
||
} else {
|
||
_, _ = fmt.Fprint(w, "✘ Wireguard is not connected\n")
|
||
}
|
||
}
|
||
|
||
type ConnDiags struct {
|
||
ConnInfo workspacesdk.AgentConnectionInfo
|
||
PingP2P bool
|
||
DisableDirect bool
|
||
LocalNetInfo *tailcfg.NetInfo
|
||
LocalInterfaces *healthsdk.InterfacesReport
|
||
AgentNetcheck *healthsdk.AgentNetcheckReport
|
||
ClientIPIsAWS bool
|
||
AgentIPIsAWS bool
|
||
Verbose bool
|
||
TroubleshootingURL string
|
||
}
|
||
|
||
func (d ConnDiags) Write(w io.Writer) {
|
||
_, _ = fmt.Fprintln(w, "")
|
||
general, client, agent := d.splitDiagnostics()
|
||
for _, msg := range general {
|
||
_, _ = fmt.Fprintln(w, msg)
|
||
}
|
||
if len(general) > 0 {
|
||
_, _ = fmt.Fprintln(w, "")
|
||
}
|
||
if len(client) > 0 {
|
||
_, _ = fmt.Fprint(w, "Possible client-side issues with direct connection:\n\n")
|
||
for _, msg := range client {
|
||
_, _ = fmt.Fprintf(w, " - %s\n\n", msg)
|
||
}
|
||
}
|
||
if len(agent) > 0 {
|
||
_, _ = fmt.Fprint(w, "Possible agent-side issues with direct connections:\n\n")
|
||
for _, msg := range agent {
|
||
_, _ = fmt.Fprintf(w, " - %s\n\n", msg)
|
||
}
|
||
}
|
||
}
|
||
|
||
func (d ConnDiags) splitDiagnostics() (general, client, agent []string) {
|
||
if d.AgentNetcheck != nil {
|
||
for _, msg := range d.AgentNetcheck.Interfaces.Warnings {
|
||
agent = append(agent, msg.Message)
|
||
}
|
||
if len(d.AgentNetcheck.Interfaces.Warnings) > 0 {
|
||
agent[len(agent)-1] += fmt.Sprintf("\n%s#low-mtu", d.TroubleshootingURL)
|
||
}
|
||
}
|
||
|
||
if d.LocalInterfaces != nil {
|
||
for _, msg := range d.LocalInterfaces.Warnings {
|
||
client = append(client, msg.Message)
|
||
}
|
||
if len(d.LocalInterfaces.Warnings) > 0 {
|
||
client[len(client)-1] += fmt.Sprintf("\n%s#low-mtu", d.TroubleshootingURL)
|
||
}
|
||
}
|
||
|
||
if d.PingP2P && !d.Verbose {
|
||
return general, client, agent
|
||
}
|
||
|
||
if d.DisableDirect {
|
||
general = append(general, "❗ Direct connections are disabled locally, by `--disable-direct-connections` or `CODER_DISABLE_DIRECT_CONNECTIONS`.\n"+
|
||
" They may still be established over a private network.")
|
||
if !d.Verbose {
|
||
return general, client, agent
|
||
}
|
||
}
|
||
|
||
if d.ConnInfo.DisableDirectConnections {
|
||
general = append(general,
|
||
fmt.Sprintf("❗ Your Coder administrator has blocked direct connections\n %s#disabled-deployment-wide", d.TroubleshootingURL))
|
||
if !d.Verbose {
|
||
return general, client, agent
|
||
}
|
||
}
|
||
|
||
if !d.ConnInfo.DERPMap.HasSTUN() {
|
||
general = append(general,
|
||
fmt.Sprintf("❗ The DERP map is not configured to use STUN\n %s#no-stun-servers", d.TroubleshootingURL))
|
||
} else if d.LocalNetInfo != nil && !d.LocalNetInfo.UDP {
|
||
client = append(client,
|
||
fmt.Sprintf("Client could not connect to STUN over UDP\n %s#udp-blocked", d.TroubleshootingURL))
|
||
}
|
||
|
||
if d.LocalNetInfo != nil && d.LocalNetInfo.MappingVariesByDestIP.EqualBool(true) {
|
||
client = append(client,
|
||
fmt.Sprintf("Client is potentially behind a hard NAT, as multiple endpoints were retrieved from different STUN servers\n %s#endpoint-dependent-nat-hard-nat", d.TroubleshootingURL))
|
||
}
|
||
|
||
if d.AgentNetcheck != nil && d.AgentNetcheck.NetInfo != nil {
|
||
if d.AgentNetcheck.NetInfo.MappingVariesByDestIP.EqualBool(true) {
|
||
agent = append(agent,
|
||
fmt.Sprintf("Agent is potentially behind a hard NAT, as multiple endpoints were retrieved from different STUN servers\n %s#endpoint-dependent-nat-hard-nat", d.TroubleshootingURL))
|
||
}
|
||
if !d.AgentNetcheck.NetInfo.UDP {
|
||
agent = append(agent,
|
||
fmt.Sprintf("Agent could not connect to STUN over UDP\n %s#udp-blocked", d.TroubleshootingURL))
|
||
}
|
||
}
|
||
|
||
if d.ClientIPIsAWS {
|
||
client = append(client,
|
||
fmt.Sprintf("Client IP address is within an AWS range (AWS uses hard NAT)\n %s#endpoint-dependent-nat-hard-nat", d.TroubleshootingURL))
|
||
}
|
||
|
||
if d.AgentIPIsAWS {
|
||
agent = append(agent,
|
||
fmt.Sprintf("Agent IP address is within an AWS range (AWS uses hard NAT)\n %s#endpoint-dependent-nat-hard-nat", d.TroubleshootingURL))
|
||
}
|
||
|
||
return general, client, agent
|
||
}
|