Files
coder/cli/ping_test.go
Atif Ali ae6b1faea3 fix: make SSH connection hints consistent across CLI, dashboard and docs (#31188)
SSH hints across the CLI, dashboard and docs used different, sometimes
broken, workspace names. This makes them consistent with minimal,
non-breaking changes and no new syntax:

- Plain `ssh` hostnames: `<agent>.<workspace>.<owner>.<suffix>` (or
`<workspace>.<suffix>` for single-agent workspaces). Works with
`config-ssh` (with or without `--no-wildcard`) and Coder Connect.
- `coder` CLI arguments: `[<owner>/]<workspace>[.<agent>]`, with the
owner unless the workspace was given by its bare name.

Built on #31192, which is now merged into `main`.

## Changes

- **`coder ping` multi-agent error**: now suggests `coder ping
<workspace>.<agent>` instead of listing agents without a runnable
command. Owner-qualified and UUID inputs retain `<owner>/<workspace>`.
JSON-mode errors leave stdout empty, and ping still does not autostart
stopped workspaces.
- **`coder ssh` multi-agent error**: when run directly (no
`--ssh-host-prefix`/`--hostname-suffix`), it suggested `ssh
coder.dogfood.matifali`, which never resolves without a matching SSH
config entry or Coder Connect. For an agent named `dev`, it now suggests
`coder ssh dogfood.dev`, or `coder ssh bob/dogfood.dev` if the workspace
was given as `owner/name` or by ID. Here `.dev` selects the agent; it is
not an SSH hostname suffix. The ProxyCommand path used by `config-ssh`
and the IDE plugins still suggests the full hostname.
- **`coder show` / `coder create`**: the access column dropped the
owner, so `coder show bob/dogfood` or `coder show <id>` suggested `coder
ssh dogfood.dev`. It now keeps the owner unless the workspace was given
by its bare name.
- **`coder config-ssh`**: the example `ssh <workspace>.coder` is
ambiguous for multi-agent workspaces. It now names an agent, `ssh
<agent>.<workspace>.<owner>.coder`, reading a stopped workspace’s known
agents from its latest successful start using the same template version.
With `--no-wildcard`, the hint reuses the workspace snapshot and
resources used to write the Host entries.
- **Dashboard "Connect via SSH"**: rendered `...<owner>.undefined` when
the deployment has no hostname suffix. It now falls back to `coder ssh
<owner>/<workspace>` for single-agent workspaces, or `coder ssh
<owner>/<workspace>.<agent>` otherwise. With a hostname suffix, owned
single-agent workspaces show `ssh <workspace>.<suffix>` unless that
hostname collides with the deployment’s legacy prefix block. Prefix
collisions, shared workspaces and multi-agent workspaces retain the full
agent/workspace/owner hostname. The count includes agents across all
resources and devcontainers. Commands remain undefined while the SSH
config loads, with a spinner instead of a premature fallback. If the
initial load fails, it displays the error while keeping the CLI command
available.
- **Docs**: workspace access docs said `config-ssh` prints `ssh
coder.<workspace>`; it prints `ssh <workspace>.coder`. Added the
multi-agent hostname, noted it in the Desktop docs, and updated the
Gateway host and the networking page to `<workspace>.coder`.

## Before / after

```console
$ coder ssh dogfood
error: multiple agents found, please specify the agent name, available agents: [coder dev]
Try running:
         $ ssh dev.dogfood.matifali       # before: does not resolve
         $ coder ssh dogfood.dev          # after: dev is the agent name
```

## Compatibility

Hostname parsing (`findWorkspaceAndAgentByHostname`,
`normalizeWorkspaceInput`) is unchanged, so every hostname that resolves
today still does. The VS Code, JetBrains Gateway and Toolbox plugins
write their own `Host` entries and run `coder ssh --stdio
--ssh-host-prefix <prefix>`, so they don't reach the changed hints.
`TestSSH_AgentHostnames` connects with their
`<prefix>--<owner>--<workspace>.<agent>` form, and with the
`<agent>.<workspace>.<owner>` forms used by `config-ssh` and the
dashboard.

## Verification

CLI/resource race tests pass, including the complete original `TestSSH`
suite and the new agent-hostname round trips. `TestConfigSSH_Example`
checks running two-agent and stopped one-/two-agent workspaces whose
import defaults differ, with and without `--no-wildcard`. It verifies
the hint has a matching generated Host entry and reuses workspace
history once per stopped workspace. `TestShow` covers bare names,
owner-qualified names and UUIDs; `TestCreate/CreateForOtherUser` checks
the owner-qualified preview. Mutation checks confirmed the new
assertions fail when the protected behavior is removed.

`TestPing_AgentSuggestions` covers bare names, owner-qualified names,
UUIDs and JSON-mode errors with a shared fixture. The tests fail without
the new hints; an owner-omission control also fails the qualified/UUID
cases. The original network-heavy `TestPing` suite remains unchanged and
passes its normal race run.

Normal and strict new-code Go lint, frontend checks/lint/typechecking,
all eleven SSHButton stories, and docs checks pass. Browser checks
verified copied SSH/CLI commands and keyboard dismissal; screenshots
were visually inspected. The single-agent follow-up adds 25 command-copy
cases covering ownership, agents across resources, subagents, and
zero/unknown counts. All 53 affected SSHButton, AgentRow, and
AgentDevcontainerCard stories pass, with browser validation of both real
callers and regression/mutation controls for the command-selection
guards.

<details>
<summary>CI follow-up and validation commands</summary>

After #31192 merged, the parent commits were dropped and the remaining
eleven commits were rebased onto the merge commit `fb6d287528`.
Range-diff and full-tree comparisons confirm no implementation changes.
Revalidated the complete SSH/ping/config race suite and strict lint
after that rebase.

Latest rebase preserves the implementation and carries the docs edits to
main’s renamed `docs/workspaces/` paths. The SSHButton documentation
links and preview URL use the new routes. Revalidated the full
SSH/ping/config CLI race suite, strict lint, 25 frontend tests, 53
stories, and docs/manifest/redirect checks. The local shell’s Oh My Zsh
update prompt interrupted the first race run; the unchanged suite passed
with `DISABLE_AUTO_UPDATE=true` scoped to the test process.

Latest review follow-up: connection commands remain undefined during
initial loading, and each instruction is gated on its own command. A
cached SSH suffix remains usable after a failed refetch; a story
captures that state. Rebased directly onto `main` at `fb6d287528` after
#31192 merged. The P2 follow-up preserves native hostnames that collide
with legacy prefix blocks, uses workspace-specific history for stopped
agents, and retains safe precreated devcontainer names.

Earlier stress runs of the unmodified `TestSSH` suite exceeded the 6,144
MiB guard under 35-repeat stress. Its existing scenarios remain
unchanged. The three added agent-qualified hostname cases have
independent full SSH round-trip coverage in `TestSSH_AgentHostnames`,
with a shared fixture. The current top-PR changed-test selector chooses
seven tests without the unrelated `TestSSH` scenarios, and the complete
selected set passes 35 repetitions at parallelism 16 with the same
memory guard. No test cases, repetitions, parallelism or memory checks
were removed.

```sh
go test -race -tags=testsmallbatch ./cli ./cli/cliui -run '^TestSSH$|^TestSSH_AgentHostnames$|TestPing|TestConfigSSH|TestShow|TestCreate|Test_agentSSHSuggestion|Test_suggestWithOwner|TestWorkspaceResources|Test_noWildcardHostNames|Test_previousStartResources|TestCommandHelp' -count=1 -parallel=4
GOMEMLIMIT=6GiB golangci-lint run --allow-serial-runners --concurrency=4 --new-from-rev=origin/main ./cli/...
GOMEMLIMIT=6GiB make lint/go/new-code GO_LINT_CONCURRENCY=4
CODER_TEST_MEMORY_LIMIT_MIB=6144 TS_DEBUG_DISCO=true TS_DEBUG_DERP=true go test -tags=testsmallbatch -p=4 -count=35 -parallel=16 -shuffle=1 -timeout=10m -run '^(TestConfigSSH_Example|TestCreate|TestPing_AgentSuggestions|TestSSH_AgentHostnames|TestShow|Test_agentSSHSuggestion|Test_suggestWithOwner)(/.*)?$' ./cli
cd site
pnpm check
pnpm lint
pnpm test src/modules/resources/SSHButton/SSHButton.test.tsx
pnpm test:storybook src/modules/resources/SSHButton/SSHButton.stories.tsx src/modules/resources/AgentRow.stories.tsx src/modules/resources/AgentDevcontainerCard.stories.tsx --run
```

</details>

Follow-up to #19943. Tracks
[CLI-67](https://linear.app/codercom/issue/CLI-67/fix-coder-ssh-suggestions-for-multi-agent-workspaces).

Preview:
https://coder.com/docs/@fix%2Fssh-multi-agent-hint/workspaces/workspace-access

> 🤖 This PR was created with the help of Coder Agents, and has been
reviewed by my human. 🧑💻
2026-11-05 10:19:38 +05:00

224 lines
6.4 KiB
Go

package cli_test
import (
"bytes"
"context"
"encoding/json"
"testing"
"github.com/google/uuid"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/coder/coder/v2/agent/agenttest"
"github.com/coder/coder/v2/cli"
"github.com/coder/coder/v2/cli/clitest"
"github.com/coder/coder/v2/coderd/coderdtest"
sdkproto "github.com/coder/coder/v2/provisionersdk/proto"
"github.com/coder/coder/v2/testutil"
"github.com/coder/coder/v2/testutil/expecter"
)
func TestPing_AgentSuggestions(t *testing.T) {
t.Parallel()
client, workspace, _ := setupWorkspaceForAgent(t, func(agents []*sdkproto.Agent) []*sdkproto.Agent {
agents[0].Name = "coder"
return append(agents, &sdkproto.Agent{
Id: uuid.NewString(),
Name: "dev",
Auth: &sdkproto.Agent_Token{Token: uuid.NewString()},
})
})
qualifiedName := "myuser/" + workspace.Name
for _, tc := range []struct {
name string
input string
want string
json bool
}{
{name: "Name", input: workspace.Name, want: workspace.Name},
{name: "OwnerAndName", input: qualifiedName, want: qualifiedName},
{name: "UUID", input: workspace.ID.String(), want: qualifiedName},
{name: "JSON", input: workspace.Name, want: workspace.Name, json: true},
} {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
args := []string{"ping", tc.input}
if tc.json {
args = append(args, "--num", "1", "--output", "json")
}
inv, root := clitest.New(t, args...)
clitest.SetupConfig(t, client, root)
var stdout bytes.Buffer
inv.Stdout = &stdout
err := inv.WithContext(testutil.Context(t, testutil.WaitLong)).Run()
require.ErrorContains(t, err, "multiple agents found")
require.ErrorContains(t, err, "Try running:")
assert.Contains(t, err.Error(), "$ coder ping "+tc.want+".coder")
assert.Contains(t, err.Error(), "$ coder ping "+tc.want+".dev")
assert.NotContains(t, err.Error(), "$ ssh ")
assert.Empty(t, stdout.String())
})
}
}
func TestPing(t *testing.T) {
t.Parallel()
t.Run("OK", func(t *testing.T) {
t.Parallel()
client, workspace, agentToken := setupWorkspaceForAgent(t)
inv, root := clitest.New(t, "ping", workspace.Name)
clitest.SetupConfig(t, client, root)
stdout := expecter.NewAttachedToInvocation(t, inv)
_ = agenttest.New(t, client.URL, agentToken)
_ = coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
cmdDone := tGo(t, func() {
err := inv.WithContext(ctx).Run()
assert.NoError(t, err)
})
stdout.ExpectMatch(ctx, "pong from "+workspace.Name)
cancel()
<-cmdDone
})
t.Run("1Ping", func(t *testing.T) {
t.Parallel()
client, workspace, agentToken := setupWorkspaceForAgent(t)
inv, root := clitest.New(t, "ping", "-n", "1", workspace.Name)
clitest.SetupConfig(t, client, root)
stdout := expecter.NewAttachedToInvocation(t, inv)
_ = agenttest.New(t, client.URL, agentToken)
_ = coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
cmdDone := tGo(t, func() {
err := inv.WithContext(ctx).Run()
assert.NoError(t, err)
})
stdout.ExpectMatch(ctx, "pong from "+workspace.Name)
// The default table output prints the summary after the last ping.
stdout.ExpectRegexMatch(ctx, `(?i)successful`)
cancel()
<-cmdDone
})
t.Run("1PingWithTime", func(t *testing.T) {
t.Parallel()
tests := []struct {
name string
utc bool
}{
{name: "LocalTime"}, // --time renders the pong response time.
{name: "UTC", utc: true}, // --utc implies --time, so we expect it to also contain the pong time.
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
client, workspace, agentToken := setupWorkspaceForAgent(t)
args := []string{"ping", "-n", "1", workspace.Name, "--time"}
if tc.utc {
args = append(args, "--utc")
}
inv, root := clitest.New(t, args...)
clitest.SetupConfig(t, client, root)
stdout := expecter.NewAttachedToInvocation(t, inv)
_ = agenttest.New(t, client.URL, agentToken)
_ = coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
cmdDone := tGo(t, func() {
err := inv.WithContext(ctx).Run()
assert.NoError(t, err)
})
// RFC3339 is the format used to render the pong times.
rfc3339 := `\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?`
// Validate that dates are rendered as specified.
if tc.utc {
rfc3339 += `Z`
} else {
rfc3339 += `(?:Z|[+-]\d{2}:\d{2})`
}
stdout.ExpectRegexMatch(ctx, `\[`+rfc3339+`\] pong from `+workspace.Name)
cancel()
<-cmdDone
})
}
})
t.Run("JSON", func(t *testing.T) {
t.Parallel()
client, workspace, agentToken := setupWorkspaceForAgent(t)
inv, root := clitest.New(t, "ping", "-n", "1", "-o", "json", workspace.Name)
clitest.SetupConfig(t, client, root)
out := bytes.NewBuffer(nil)
inv.Stdout = out
_ = agenttest.New(t, client.URL, agentToken)
_ = coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
err := inv.WithContext(ctx).Run()
require.NoError(t, err)
// stdout must contain nothing but the JSON document; diagnostic
// and per-attempt lines are redirected to stderr in JSON mode.
var result cli.PingJSONOutput
require.NoError(t, json.Unmarshal(out.Bytes(), &result))
assert.Equal(t, workspace.Name, result.Workspace)
require.Len(t, result.Pongs, 1)
assert.Equal(t, 1, result.Pongs[0].Sequence)
assert.Empty(t, result.Pongs[0].Error)
require.NotNil(t, result.Pongs[0].LatencyMS)
require.NotNil(t, result.Pongs[0].Direct)
assert.Equal(t, 1, result.Summary.Total)
assert.Equal(t, 1, result.Summary.Successful)
require.NotNil(t, result.Summary.MinMS)
require.NotNil(t, result.Summary.AvgMS)
require.NotNil(t, result.Summary.MaxMS)
})
t.Run("JSONRequiresNum", func(t *testing.T) {
t.Parallel()
for _, args := range [][]string{
{"ping", "-o", "json", "my-workspace"},
{"ping", "-n", "0", "-o", "json", "my-workspace"},
} {
inv, _ := clitest.New(t, args...)
out := bytes.NewBuffer(nil)
inv.Stdout = out
err := inv.Run()
require.ErrorContains(t, err, "--output json requires --num")
assert.Empty(t, out.String())
}
})
}