feat(site): use websocket connection for devcontainer updates #18808

DanielleMaywood · 2025-07-09T11:33:11Z

Instead of polling every 10 seconds, we instead use a WebSocket connection for more timely updates.

Copilot

Pull Request Overview

Adds real-time devcontainer updates over WebSocket instead of polling, and updates related client and server code.

Introduce useAgentContainers hook leveraging WebSockets in the frontend
Add WebSocket watch endpoints and SDK methods for container updates across site API, SDK, and agent code
Replace polling in AgentRow with the new hook and update documentation and tests accordingly

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
site/src/modules/resources/useAgentContainers.ts	New React hook subscribing to container updates via WS
site/src/modules/resources/useAgentContainers.test.tsx	Tests for the hook’s initial fetch behavior
site/src/modules/resources/AgentRow.tsx	Switched from polling to WebSocket hook
site/src/api/api.ts	Export `watchAgentContainers` for WebSocket route
docs/reference/api/agents.md	Add API reference for the new watch endpoint
codersdk/workspacesdk/agentconn.go	Add `WatchContainers` method to agent connection SDK
codersdk/workspaceagents.go	Add `WatchWorkspaceAgentContainers` to SDK client
coderd/workspaceagents.go	Implement WebSocket handler for watch endpoint
coderd/coderd.go	Register `/containers/watch` route
coderd/apidoc/swagger.json & docs.go	Document new watch route in Swagger and docs template
agent/agentcontainers/api.go	Add `watchContainers` WS handler in agent API

Comments suppressed due to low confidence (5)

docs/reference/api/agents.md:908

This endpoint upgrades to a WebSocket connection rather than a plain HTTP GET; consider updating the code sample to show a WebSocket client (e.g., wscat or JS) for clarity.

curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers/watch \

site/src/modules/resources/useAgentContainers.test.tsx:85

Tests currently cover only the initial fetch; add a test that mocks WebSocket messages and verifies that useAgentContainers updates when a message arrives.

});

site/src/modules/resources/AgentRow.tsx:75

The queryClient variable is declared but never used; consider removing this import and assignment to reduce clutter.

	const queryClient = useQueryClient();

agent/agentcontainers/api.go:585

The slices package is referenced here but not imported, causing a compile error. Add import "slices" or reference the correct package.

		api.updateChans = slices.DeleteFunc(api.updateChans, func(ch chan struct{}) bool {

site/src/modules/resources/useAgentContainers.ts:28

Calling invalidateQueries after setQueryData will trigger an extra network request on each WebSocket message. You can remove the invalidation to prevent unnecessary refetches.

			await queryClient.invalidateQueries({ queryKey });

johnstcn

Backend changes LGTM 👍

mafredri

Pointed out a few gotchas but otherwise looks good, nice work!

mafredri · 2025-07-10T11:01:48Z

agent/agentcontainers/api.go

+	updateCh := make(chan struct{}, 1)
+	defer func() {
+		api.mu.Lock()
+		close(updateCh)


It'd make sense to move this to the defer below to keep the related code close to each other.

Addressed in 6ce5c19

mafredri · 2025-07-10T11:07:20Z

agent/agentcontainers/api.go

+		return
+	}
+
+	ctx = api.ctx


We could do this here instead:

ctx, wsNetConn := codersdk.WebsocketNetConn(ctx, conn, websocket.MessageBinary) defer wsNetConn.Close()

Note that we're not passing api.ctx to WebsocketNetConn but that's OK because of the final select (see below).

Then a few important changes following:

Heartbeat doesn't change (needs Ping from conn)

We can omit conn.Close (handled via wsNetConn.Close)

Encoder uses wsNetConn

Final select has one entry for api.ctx and another for ctx

This follows practice we use elsewhere in the code-base.

Is this possible? wsjson.NewEncoder requires a *websocket.Conn but wsNetConn is a net.Conn

wsjson.NewEncoder is a tiny wrapper, i'll just write the underlying logic using wsNetConn

Addressed in 04a92a4

Oh I see, I hadn't actually seen/used wsjson.NewEncoder before. The CloseRead it calls would be ideal to retain.

Have re-added this in 😄 096a85e

mafredri · 2025-07-10T11:11:43Z

agent/agentcontainers/api.go

@@ -583,8 +647,32 @@ func (api *API) updateContainers(ctx context.Context) error {
 	api.mu.Lock()
 	defer api.mu.Unlock()

+	var knownDevcontainers map[string]codersdk.WorkspaceAgentDevcontainer


Suggestion: Naming so nobody accidentally updates this map rather than api.knownDevcontainers. Perhaps knownDevcontainersBackup or something along those lines those lines.

Addressed in cd0c2d5

mafredri · 2025-07-10T11:13:09Z

coderd/workspaceagents.go

+		return
+	}
+
+	ctx = api.ctx


See related comments on api.go.

Addressed in 04a92a4

mafredri · 2025-07-10T11:19:18Z

codersdk/workspacesdk/agentconn.go

+		defer res.Body.Close()
+	}
+
+	d := wsjson.NewDecoder[codersdk.WorkspaceAgentListContainersResponse](conn, websocket.MessageText, slog.Logger{})


What's the repercussion of passing slog.Logger here, unstructured output on stdout?

If it's required, perhaps we should require it as a WatchContainers parameter if we can't put it on the AgentConn struct.

I completely forgot to update this when I was tinkering 🤦‍♀️ Will resolve this

Addressed in 3e50965

mafredri · 2025-07-10T11:21:16Z

site/src/modules/resources/useAgentContainers.ts

+		socket.addEventListener("message", (event) => {
+			if (event.parseError) {
+				displayError(
+					"Unable to process latest data from the server. Please try refreshing the page.",


Could this message be more specific? I.e. mention what operation failed?

Possibly although I'm just following existing logic here. I'm not sure what context about the error exists to make this more useful.

I know that you are just following the existing logic, but I see this as an opportunity to do better with those messages, having in mind they are displayed to the users.

The displayError function accepts a message and a description, so to make this error better to the user I think we can make the message shorter and tell to the user what is the impact of it, instead of the techinical reason, and give it an way to possible solve the problem as you already put in the message.

displayError( "Failed to update containers", "Please try refreshing the page" )

Wdyt?

mafredri · 2025-07-10T11:22:12Z

site/src/modules/resources/useAgentContainers.ts

+
+		socket.addEventListener("error", () => {
+			displayError(
+				"Unable to get workspace containers. Connection has been closed.",


Do we just give up here? Is there precedent for trying to reconnect later?

For the frontend changes I was following logic I found elsewhere.

Same as my previous comment.

displayError( "Failed to load containers", "Please try refreshing the page" )

mafredri · 2025-07-10T11:25:20Z

codersdk/workspaceagents.go

+		d.WorkspaceFolder == other.WorkspaceFolder &&
+		d.Status == other.Status &&
+		d.Dirty == other.Dirty &&
+		d.Error == other.Error


We should also check container and agent, so something like this?

Suggested change

d.Error == other.Error

d.Error == other.Error &&

(d.Container == nil && other.Container == nil || (d.Container != nil && other.Continer != nil && d.Container.ID == other.Container.ID)) &&

(d.Agent == nil && ... d.Agent.ID == ...

Addressed in 001ccda

I don't see d.Agent checked? IMO we should propagate changes to it as well since that's how the frontend associates the sub agent.

Oh silly me I only read half the sentence 🤦‍♀️

Addressed again in 971f9d6 😅

mafredri · 2025-07-10T11:29:04Z

coderd/workspaceagents.go

+
+	// If the agent is unreachable, the request will hang. Assume that if we
+	// don't get a response after 30s that the agent is unreachable.
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)


Suggestion: call this dialCtx to avoid re-use. I believe we will always have a disconnect after 30s currently?

Addressed in 04a92a4

BrunoQuaresma

@DanielleMaywood I'm missing some screenshots in the PR description showing the errors being displayed since we don't have stories in Storybook for that. Could you please add that? 🙏

I left a few comments related to the error messages.

BrunoQuaresma · 2025-07-10T13:44:01Z

site/src/modules/resources/useAgentContainers.ts

+		socket.addEventListener("message", (event) => {
+			if (event.parseError) {
+				displayError(
+					"Unable to process latest data from the server. Please try refreshing the page.",


I know that you are just following the existing logic, but I see this as an opportunity to do better with those messages, having in mind they are displayed to the users.

The displayError function accepts a message and a description, so to make this error better to the user I think we can make the message shorter and tell to the user what is the impact of it, instead of the techinical reason, and give it an way to possible solve the problem as you already put in the message.

displayError( "Failed to update containers", "Please try refreshing the page" )

Wdyt?

BrunoQuaresma · 2025-07-10T13:46:53Z

site/src/modules/resources/useAgentContainers.ts

+
+		socket.addEventListener("error", () => {
+			displayError(
+				"Unable to get workspace containers. Connection has been closed.",


Same as my previous comment.

displayError( "Failed to load containers", "Please try refreshing the page" )

BrunoQuaresma · 2025-07-10T13:51:13Z

site/src/modules/resources/useAgentContainers.test.tsx

+			expect(result.current).toBeUndefined();
+		});
+	});
+});


I think it would be a plus to have tests to verify:

Parsing error

Socket error

I know how annoying it can be to have this setup working properly without causing any flakes, so I wanted to let you know in case you are curious about, but it is not a blocket at all.

I've tried to add those.

I just want to give a fair warning: These tests are mostly written by Claude Sonnet 4 as my frontend testing experience is lacking. Please let me know if it has made any obvious blunders 🙏

mafredri · 2025-07-11T09:25:32Z

I tried out this branch and it looks like there's still XHR fetches happening in addition to the websocket pushing data. It'd be great if we could stop the XHR from happening and only rely on the websocket.

See:

There's no polling though, which is great.

(Cleared network history so websocket isn't visible here, but it's still there and sending data as well.)

mafredri

Approving BE with minor suggestions, as per my earlier comment FE XHR might still need some love.

agent/agentcontainers/api.go

DanielleMaywood · 2025-07-14T10:43:14Z

I tried out this branch and it looks like there's still XHR fetches happening in addition to the websocket pushing data. It'd be great if we could stop the XHR from happening and only rely on the websocket.

See:
There's no polling though, which is great.
(Cleared network history so websocket isn't visible here, but it's still there and sending data as well.)

I've removed the query invalidation logic. This should reduce the number of XHR requests now. The only area left to handle is the /recreate flow. I'm not sure I want to tackle that in this PR though, so will leave that as a follow up.

I've attempted to reduce as many XHR requests as possible without entirely removing them.

DanielleMaywood added 7 commits July 3, 2025 11:44

feat(site): use websocket connection for devcontainer updates

487ee95

Instead of polling every 10 seconds, we instead use a WebSocket connection for more timely updates.

fix: some issues

cc42018

Merge branch 'main' into danielle/container-push

fa46517

Merge branch 'main' into danielle/container-push

5aef560

chore: fix disconnect bug and add agentcontainers test

975ef8b

Merge branch 'main' into danielle/container-push

8fdeca3

test: add coderd/ test

6da941f

github-actions bot assigned DanielleMaywood Jul 9, 2025

DanielleMaywood added 2 commits July 9, 2025 11:35

chore: appease formatter

ff5725e

chore: feedback

178507c

DanielleMaywood requested a review from Copilot July 9, 2025 12:06

This comment was marked as outdated.

Sign in to view

chore: fix nil exception

367b87d

DanielleMaywood marked this pull request as ready for review July 9, 2025 13:39

DanielleMaywood marked this pull request as draft July 9, 2025 13:50

DanielleMaywood added 5 commits July 9, 2025 13:58

chore: make gen

34b17c4

fix: docs

8f12460

Merge branch 'main' into danielle/container-push

81022fa

fix: only send when there are updates

1768f7b

chore: lint and format

8240663

DanielleMaywood marked this pull request as ready for review July 10, 2025 08:21

DanielleMaywood added 2 commits July 10, 2025 08:21

Merge branch 'main' into danielle/container-push

6d97960

chore: test useAgentContainers

88a611d

DanielleMaywood requested a review from Copilot July 10, 2025 09:07

Copilot AI reviewed Jul 10, 2025

View reviewed changes

DanielleMaywood requested review from mafredri, BrunoQuaresma and johnstcn July 10, 2025 10:35

johnstcn approved these changes Jul 10, 2025

View reviewed changes

mafredri reviewed Jul 10, 2025

View reviewed changes

DanielleMaywood added 7 commits July 10, 2025 12:23

chore: check container ids match in Equals function

001ccda

chore: add logger to WatchContainers

3e50965

chore: reposition close of update channel

6ce5c19

chore: rename knownDevcontainers

cd0c2d5

chore: use WebsocketNetConn

04a92a4

chore: steal CloseRead

096a85e

chore: check agents match

971f9d6

BrunoQuaresma reviewed Jul 10, 2025

View reviewed changes

DanielleMaywood added 2 commits July 10, 2025 14:46

test: parsing error and socket error

f24401f

chore: lint and format

64d9252

mafredri approved these changes Jul 11, 2025

View reviewed changes

agent/agentcontainers/api.go Outdated Show resolved Hide resolved

agent/agentcontainers/api.go Outdated Show resolved Hide resolved

DanielleMaywood added 5 commits July 14, 2025 09:05

chore: give comment some love

40c3fd9

chore: re-use json encoder instead of recreating every time

1cda455

fix: push initial dev container state in websocket

2ded15f

fix: do not invalidateQuery + fix bad types

a87f388

chore: appease linter

2de01f5

chore: broadcast updates in more places, add staleTime: Infinity

00fdae6

DanielleMaywood requested a review from BrunoQuaresma July 14, 2025 15:20

BrunoQuaresma approved these changes Jul 14, 2025

View reviewed changes

chore: appease linter

a4a4bb2

DanielleMaywood merged commit 43b0bb7 into main Jul 14, 2025
33 of 35 checks passed

DanielleMaywood deleted the danielle/container-push branch July 14, 2025 20:35

github-actions bot locked and limited conversation to collaborators Jul 14, 2025

-		d.Error == other.Error
+		d.Error == other.Error &&
+		(d.Container == nil && other.Container == nil || (d.Container != nil && other.Continer != nil && d.Container.ID == other.Container.ID)) &&
+		(d.Agent == nil && ... d.Agent.ID == ...

feat(site): use websocket connection for devcontainer updates #18808

feat(site): use websocket connection for devcontainer updates #18808

Uh oh!

Conversation

DanielleMaywood commented Jul 9, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

johnstcn left a comment

Choose a reason for hiding this comment

Uh oh!

mafredri left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BrunoQuaresma left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielleMaywood commented Jul 14, 2025 •

edited

Loading