Repository navigation
fix: document WebSocket routes as 101 responses in the Swagger spec - #30125
Conversation
Part of DOCS-1122. Assisted-by: AI
eec236d to
41f1fce
Compare
|
/coder-agents-review |
|
Chat: Review posted | View chat Review historydeep-review v0.13.0 | Round 4 | Last posted: Round 4, 9 findings (1 P3, 5 P4, 3 Nit), APPROVE. Review Finding inventoryFindings
Contested and acknowledgedRound logRound 1Full panel (round 1). Netero first pass: 1 P4, no P0. Panel: ging-go, melody, pariston, mafuuu, leorio, gon, chopper, razor, kite (wildcard, random from distilled set). Focused size target 6-8; 8 selected plus wildcard. 1 P3, 3 P4, 1 Nit posted; 3 dropped (CRF-7, CRF-8, CRF-9); 5 out of scope. Reviewed against 2255794..41f1fce. Drop gate notes:
Round 2Fix round: a53ea9f only rewrites and moves the PR's own @description lines (no added files, no signature changes, same title, effective LOC unchanged). Churn guard PROCEED: CRF-1, CRF-4, CRF-5, CRF-6, CRF-10 addressed. Panel verified CRF-1, CRF-4, CRF-5, CRF-6 fixed. Netero re-raised the remaining CRF-10 instance at templateversions.go:1108. Panel: melody, pariston, mafuuu, leorio, chopper, razor (raised findings whose code changed), gon (raised CRF-10; comments touched), ging-go (.go files), zoro (wildcard, random from distilled set). New: 2 P4, 2 Nit; 1 out of scope. CRF-15 fix also removes the line CRF-10 flags. Inventory validation: CRF-7, CRF-8, CRF-9 dispositions unaffected by a53ea9f (Gon R2 confirmed no new evidence). Reviewed against 2255794..a53ea9f. Round 3 updateBLOCKED. CRF-10 silent: no author reply to the R2 re-raise, and b1e53f2 leaves Round 4Fix round: d23267b moves one About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
There was a problem hiding this comment.
This PR changes six WebSocket routes from @Success 200 to @Success 101, adds a message-framing description to each, and documents the 204 case of the previous template version route. The status codes and framing claims match the handlers, and regenerating the spec produced no diff. Findings: 1 P3, 3 P4, 1 Nit. The P3 and P4 findings are parts of each route's message contract that the new descriptions leave out.
Out of scope (needs a ticket or explicit acceptance by a human):
coderd/workspaceagents.go:807:containers/watchcallswebsocket.Acceptbut is still documented@Success 200, so the reference shows 200 for a WebSocket route.coderd/inboxnotifications.go:122:notifications/inbox/watchcallswebsocket.Acceptbut is still documented@Success 200, same consequence.coderd/debug.go:299:debug/wsis a WebSocket echo server documented as@Success 201 {object} codersdk.Response.coderd/workspaceagents.go:386:logs?follow=trueupgrades to a WebSocket but only 200 is documented; the same applies atcoderd/workspacebuilds.go:1034,coderd/templateversions.go:696,coderd/templateversions.go:1978, andcoderd/deprecated.go:41. Spec consumers see no 101 for follow mode.coderd/coderdtest/swaggerparser.go:306: no check ties a handler that upgrades to WebSocket to@Success 101, so new WebSocket routes can declare 200 and pass, as the routes above did.
🤖 This review was automatically generated with Coder Agents.
Document client messages, event payloads, and delta semantics for the WebSocket routes, and place each @description directly after @summary. Part of DOCS-1122. Assisted-by: AI
|
/coder-agents-review |
There was a problem hiding this comment.
a53ea9f fixes the stream/parts control message, the stream/git message types, and the watch-ws and watch-metadata-ws payloads; each new sentence matches its handler, and regenerating the spec produced no diff. The @Description move covered the six WebSocket routes but not the previous template version route. New findings: 2 P4, 2 Nit.
Out of scope (needs a ticket or explicit acceptance by a human):
coderd/workspaces.go:2259: whenconvertWorkspacefails,sendUpdatesends anerrorevent and then, with noreturn, adataevent holding a zero-valuecodersdk.Workspace, so clients receive the payload this PR now documents but with empty fields.
🤖 This review was automatically generated with Coder Agents.
Document that the chat watch and stream routes close on client messages, use one wording for event framing, wrap literals in backticks, and move the 204 condition for the previous template version route into its @success annotation. Part of DOCS-1122. Assisted-by: AI
|
/coder-agents-review |
There was a problem hiding this comment.
b1e53f2 addresses the chat-route close sentence, the 204 condition, the backticks, and the one-event-per-message wording. One finding has no response: the @Description placement re-raised in the previous review. coderd/templateversions.go:1108 still sits after @ID (line 1107) instead of directly after @Summary (line 1106), and the re-raise reply has no answer. Your reply on the 204 finding explains why the @Description line stays, so the fix is to move it up one line, not delete it. Further review is blocked until you move the line or reply on that thread explaining why it should stay where it is.
🤖 This review was automatically generated with Coder Agents.
Part of DOCS-1122. Assisted-by: AI
|
/coder-agents-review |
There was a problem hiding this comment.
d23267b moves the previous template version @Description directly after @Summary, so all seven added descriptions are placed consistently. The fixes from b1e53f2 are verified against the handlers: the close-on-client-message sentence on chats/watch and chats/{chat}/stream, the 204 condition in the @Success 204 string, backticks on wire literals, and the one-event-per-message wording. Regenerating the spec produced no diff. No open findings remain.
The out-of-scope items listed in the earlier reviews still need a ticket or explicit acceptance by a human.
Notes:
coderd/templateversions.go:1107: if you want the description exact,GetPreviousTemplateVersionreturns the most recently created version of the same template that was created before the named version.
🤖 This review was automatically generated with Coder Agents.
| } | ||
|
|
||
| // @Summary Watch chat workspace git state via WebSockets | ||
| // @Description Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan. |
There was a problem hiding this comment.
Blocking: since marks time here, and the word-choice rule maps time to after or starting in (Copy Editor)
The sentence reads "a delta of repository changes since the previous message", so a reader cannot tell whether since means time or cause. Rule: docs/.style/style-guide/word-choice.md#choose-words-that-have-one-meaning. This line generates the Description for docs/reference/api/chats.md, so regenerate the API docs after the fix.
| // @Description Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan. | |
| // @Description Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes after the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan. |
|
|
||
| `GET /api/v2/chats/{chat}/stream/git` | ||
|
|
||
| Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan. |
There was a problem hiding this comment.
(Copy Editor) The sentence runs about 32 words, and it packs three message types and a client action into one sentence. Rule: docs/.style/style-guide/voice-and-tone.md#keep-sentences-and-paragraphs-short (a target, not a limit). Split it in the source at coderd/exp_chats.go:2349, and use after as in the blocking comment above:
"Upgrades to a WebSocket. Each server message is either a changes message or an error message. A changes message holds a delta of repository changes after the previous message. You can send {"type": "refresh"} to request an immediate re-scan."
| } | ||
|
|
||
| // @Summary Stream chat events via WebSockets | ||
| // @Description Upgrades to a WebSocket and sends each message as a JSON array holding a batch of one or more events. The server closes the connection if you send a message. |
There was a problem hiding this comment.
(Continuity Editor, Reader Advocate) The JSON array framing is stated twice. The next line, Each WebSocket message is a JSON array of events., already states it, so this clause repeats it. Rule: docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs. Also, message here names a WebSocket frame, while the same page uses message for a chat message.
| // @Description Upgrades to a WebSocket and sends each message as a JSON array holding a batch of one or more events. The server closes the connection if you send a message. | |
| // @Description Upgrades to a WebSocket. The server closes the connection if you send a message. |
| // @Param templateversionname path string true "Template version name" | ||
| // @Success 200 {object} codersdk.TemplateVersion | ||
| // @Success 204 | ||
| // @Success 204 "The template version has no previous version" |
There was a problem hiding this comment.
(Continuity Editor) The Description cell for this 204 row reads "The template version has no previous version", but every other 204 row in docs/reference/ reads "No Content", for example docs/reference/api/chats.md, docs/reference/api/users.md, and docs/reference/api/workspaces.md. A reader comparing responses sees one inconsistent label. Make the Description pattern deliberate across all 204 rows. Do not change only this row. Reverting this row to "No Content" would undo the earlier thread on this line, which moved the reason here on purpose.
Documentation CheckBlocking
Findings for agents- id: language-1
persona: language
class: rule
blocking: true
file: docs/reference/api/chats.md
line: 4654
quote: "a delta of repository changes since the previous message"
evidence:
- coderd/exp_chats.go:2349
rule: docs/.style/style-guide/word-choice.md#choose-words-that-have-one-meaning
problem: "`since` marks time here, which the rule maps to `after`."
fix: "Change `since` to `after` at coderd/exp_chats.go:2349 and regenerate the API docs."
verified: true
- id: language-2
persona: language
class: suggestion
blocking: false
file: docs/reference/api/chats.md
line: 4654
quote: "Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message"
evidence:
- docs/.style/style-guide/voice-and-tone.md#keep-sentences-and-paragraphs-short
rule: docs/.style/style-guide/voice-and-tone.md#keep-sentences-and-paragraphs-short
problem: "The sentence runs about 32 words and packs three message types and a client action."
fix: "Split the sentence at coderd/exp_chats.go:2349."
verified: true
- id: consistency-1
persona: consistency
class: suggestion
blocking: false
file: docs/reference/api/chats.md
line: 4214
quote: "Upgrades to a WebSocket and sends each message as a JSON array holding a batch of one or more events."
evidence:
- docs/reference/api/chats.md:4216 "Each WebSocket message is a JSON array of events."
rule: docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs
problem: "The JSON array framing is stated twice, and `message` names a frame here but a chat message elsewhere on the page."
fix: "Drop the JSON array clause at coderd/exp_chats.go:3946."
verified: true
- id: consistency-2
persona: consistency
class: suggestion
blocking: false
file: docs/reference/api/templates.md
line: 664
quote: "The template version has no previous version"
evidence:
- docs/reference/api/chats.md:948
- docs/reference/api/users.md:1023
- docs/reference/api/workspaces.md:1760
rule: null
problem: "This is the only 204 row in docs/reference/ whose Description differs from \"No Content\"."
fix: "Make the Description pattern deliberate across all 204 rows. Do not change only this row."
verified: trueAutomated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong. |
|
I have read the CLA Document and I hereby sign the CLA 1 out of 2 committers have signed the CLA. |
Six WebSocket routes were documented as
200responses:chats/watch,chats/{chat}/stream,chats/{chat}/stream/git,chats/{chat}/stream/parts,workspaces/{workspace}/watch-ws, andworkspaceagents/{workspaceagent}/watch-metadata-ws.Mark them
@Success 101, matching the other WebSocket routes, and describe each message.chats/{chat}/streamandstream/partssend a JSON array batch of events per message, so they keep{array}; the others send one event per message.Also document that the previous template version route returns
204with no body when there is no previous version.Part of DOCS-1122, split from #30121.
CI flakes unrelated to this change
On
d23267b7c3, two checks failed in code this PR does not touch.TestChatTurnStopsAtStepLimit/Defaultincoderd/x/chatd(test-go-pg, ubuntu): this PR changes only Swagger comment annotations and generated docs, and does not touch thechatdpackage.updateWorkspace.spec.ts:76(test-e2e): this PR changes no UI code, and the test exercises workspace parameter updates.🤖 Built with AI assistance.