Repository navigation
docs: document EWS03 and EIF01 health codes and guard against undocumented codes - #31808
coder[bot] wants to merge 2 commits into
Conversation
…ented codes Add remediation sections for EWS03 (unexpected WebSocket message) and EIF01 (low network interface MTU) to the health check page, and add a test that fails when a health code constant has no heading matching the anchor that health.Message.URL links to.
|
|
||
| ## Network interfaces | ||
|
|
||
| The network interface check inspects the network interfaces of the machine it runs on, not the Coder server. |
There was a problem hiding this comment.
Blocking: (Continuity Editor) the Coder server is not the canonical term for the component that serves the Coder API and dashboard; the word-choice rule bans it in favor of control plane. The same page uses control plane at line 227, so this reads inconsistently.
Rule: docs/.style/style-guide/word-choice.md#naming-coders-components
| The network interface check inspects the network interfaces of the machine it runs on, not the Coder server. | |
| The network interface check inspects the network interfaces of the machine it runs on, not the control plane. |
| A network interface that is up and has a non-link-local address has a maximum transmission unit (MTU) smaller than 1378. | ||
| Direct connections over this interface might have degraded quality or might hang entirely. | ||
| This is a warning. | ||
| Connections relayed through DERP are not affected. |
There was a problem hiding this comment.
Blocking: (Copy Editor) This is a statement, not a negative instruction, so the default contraction applies. are not should be aren't.
Rule: docs/.style/style-guide/voice-and-tone.md#contractions-are-the-default
| Connections relayed through DERP are not affected. | |
| Connections relayed through DERP aren't affected. |
| Connections relayed through DERP are not affected. | ||
|
|
||
| **Solution:** | ||
| Increase the MTU of the affected interface to 1378 or higher, or use a different network interface. |
There was a problem hiding this comment.
Blocking: (Copy Editor) A comma appears before or joining two verbs (Increase and use) that share one subject. The no-comma-in-a-short-compound-predicate rule applies. Consider splitting it.
Rule: docs/.style/style-guide/capitalization-and-punctuation.md#no-comma-in-a-short-compound-predicate
| Increase the MTU of the affected interface to 1378 or higher, or use a different network interface. | |
| Increase the MTU of the affected interface to 1378 or higher. If you can't, use a different network interface. |
|
|
||
| **Solution:** | ||
| Increase the MTU of the affected interface to 1378 or higher, or use a different network interface. | ||
| Virtual private network (VPN) tunnel interfaces often have a low MTU. |
There was a problem hiding this comment.
Blocking: (Copy Editor) often is a vague qualifier named by the weasel-words rule; it says the statement is sometimes false without saying when. Remove it and state the claim as a default.
Rule: docs/.style/style-guide/word-choice.md#avoid-weasel-words
| Virtual private network (VPN) tunnel interfaces often have a low MTU. | |
| Virtual private network (VPN) tunnel interfaces have a low MTU. |
| Virtual private network (VPN) tunnel interfaces often have a low MTU. | ||
|
|
||
| If you can't change the MTU or use another interface, you can block direct connections so that all traffic is relayed through DERP. | ||
| To do this, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane. |
There was a problem hiding this comment.
Blocking: (Copy Editor) To do this is a bare this that summarizes the preceding clause; name the thing it refers to.
Rule: docs/.style/style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent
| To do this, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane. | |
| To block direct connections, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane. |
| #### Received an unexpected WebSocket message | ||
|
|
||
| **Problem:** | ||
| Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match. |
There was a problem hiding this comment.
Blocking: (Copy Editor) This is a statement, not a negative instruction, so the default contraction applies. did not match should be didn't match.
Rule: docs/.style/style-guide/voice-and-tone.md#contractions-are-the-default
| Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match. | |
| Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply didn't match. |
| **Problem:** | ||
| Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match. | ||
| Either the reply was not a text message, or its contents differ from the message Coder sent. | ||
| This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder. |
There was a problem hiding this comment.
Blocking: (Copy Editor) This can happen uses a bare this that summarizes a whole clause; name the thing it refers to.
Rule: docs/.style/style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent
| This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder. | |
| This mismatch can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL doesn't route to Coder. |
| **Problem:** | ||
| Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match. | ||
| Either the reply was not a text message, or its contents differ from the message Coder sent. | ||
| This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder. |
There was a problem hiding this comment.
Blocking: (Copy Editor) does not route is a statement, so the default contraction applies. Should be doesn't route.
Rule: docs/.style/style-guide/voice-and-tone.md#contractions-are-the-default
| This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder. | |
| or when the Access URL doesn't route to Coder. |
| #### Network interface has a low MTU | ||
|
|
||
| **Problem:** | ||
| A network interface that is up and has a non-link-local address has a maximum transmission unit (MTU) smaller than 1378. |
There was a problem hiding this comment.
(Fact Checker) The trigger description omits the code's iface.MTU > 0 guard, so it would also describe interfaces with MTU 0 or negative (the code explicitly skips a negative MTU on Windows loopback). The guard is not pinned by a test. Suggest adding a test case in codersdk/healthsdk/interfaces_internal_test.go asserting an up interface with a non-link-local address and MTU <= 0 does not produce an EIF01 warning, and consider qualifying the doc with greater than 0.
|
|
||
| **Problem:** | ||
| Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match. | ||
| Either the reply was not a text message, or its contents differ from the message Coder sent. |
There was a problem hiding this comment.
(Fact Checker) The two conditions that produce EWS03 are pinned only by coderd/healthcheck/websocket.go:90-100; websocket_test.go never exercises the message-type or content-mismatch path. Suggest a TestWebsocket sub-test that returns a different message type or different contents, asserting CodeWebsocketMsg and SeverityError.
Documentation CheckBlocking
New documentation neededNone. Design notes
Related open PRs
Findings for agents- id: consistency-1
persona: consistency
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 208
quote: "The network interface check inspects the network interfaces of the machine it runs on, not the Coder server."
evidence:
- docs/.style/style-guide/word-choice.md:158
- docs/admin/monitoring/health-check.md:227
rule: word-choice.md#naming-coders-components
problem: The new section names the server component "the Coder server", the term the word-choice rule bans in favor of "control plane".
fix: "The network interface check inspects the network interfaces of the machine it runs on, not the control plane."
verified: true
- id: language-2
persona: language
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 220
quote: "Connections relayed through DERP are not affected."
evidence:
- docs/.style/style-guide/voice-and-tone.md:245
rule: voice-and-tone.md#contractions-are-the-default
problem: This is a statement, not a negative instruction, so the default contraction applies.
fix: "Connections relayed through DERP aren't affected."
verified: true
- id: language-3
persona: language
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 223
quote: "Increase the MTU of the affected interface to 1378 or higher, or use a different network interface."
evidence:
- docs/.style/style-guide/capitalization-and-punctuation.md:160
rule: capitalization-and-punctuation.md#no-comma-in-a-short-compound-predicate
problem: A comma appears before "or" joining two verbs that share one subject.
fix: "Increase the MTU of the affected interface to 1378 or higher. If you can't, use a different network interface."
verified: true
- id: language-4
persona: language
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 224
quote: "Virtual private network (VPN) tunnel interfaces often have a low MTU."
evidence:
- docs/.style/style-guide/word-choice.md:578
rule: word-choice.md#avoid-weasel-words
problem: "often" is a vague qualifier that says the statement is sometimes false without saying when.
fix: "Virtual private network (VPN) tunnel interfaces have a low MTU."
verified: true
- id: language-5
persona: language
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 227
quote: "To do this, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane."
evidence:
- docs/.style/style-guide/voice-and-tone.md:222
rule: voice-and-tone.md#give-each-pronoun-one-clear-referent
problem: "this" is a bare pronoun that summarizes the preceding clause.
fix: "To block direct connections, set the [`--block-direct-connections`](../../reference/cli/server/index.md#--block-direct-connections) flag or `CODER_BLOCK_DIRECT` environment variable on the control plane."
verified: true
- id: audience-1
persona: audience
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 279
quote: "Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match. Either the reply was not a text message, or its contents differ from the message Coder sent."
evidence:
- coderd/healthcheck/websocket.go:90-100
- docs/admin/monitoring/health-check.md:240
rule: docs/.style/content-guidelines.md#describe-the-current-version-for-the-end-user
problem: This narrates the internal echo-comparison mechanism, which the reader never sees, types, or acts on; the page already established the echo check at line 240.
fix: "Coder established a WebSocket connection over its own Access URL, but the message it read back did not match what it sent. This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder."
verified: true
- id: language-6
persona: language
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 279
quote: "Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply did not match."
evidence:
- docs/.style/style-guide/voice-and-tone.md:245
rule: voice-and-tone.md#contractions-are-the-default
problem: This is a statement, not a negative instruction, so the default contraction applies.
fix: "Coder established a WebSocket connection over its own Access URL and sent a text message, but the reply didn't match."
verified: true
- id: language-7
persona: language
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 281
quote: "This can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL does not route to Coder."
evidence:
- docs/.style/style-guide/voice-and-tone.md:222
rule: voice-and-tone.md#give-each-pronoun-one-clear-referent
problem: "this" is a bare pronoun that summarizes the preceding clause.
fix: "This mismatch can happen when something between Coder and its Access URL changes WebSocket traffic, or when the Access URL doesn't route to Coder."
verified: true
- id: language-8
persona: language
class: rule
blocking: true
file: docs/admin/monitoring/health-check.md
line: 281
quote: "or when the Access URL does not route to Coder."
evidence:
- docs/.style/style-guide/voice-and-tone.md:245
rule: voice-and-tone.md#contractions-are-the-default
problem: This is a statement, so the default contraction applies.
fix: "or when the Access URL doesn't route to Coder."
verified: true
- id: accuracy-1
persona: accuracy
class: suggestion
blocking: false
file: docs/admin/monitoring/health-check.md
line: 217
quote: "A network interface that is up and has a non-link-local address has a maximum transmission unit (MTU) smaller than 1378."
evidence:
- codersdk/healthsdk/interfaces.go:73
- codersdk/healthsdk/interfaces.go:71-72
- codersdk/healthsdk/interfaces.go:16
rule: null
problem: The trigger description omits the code's iface.MTU > 0 guard, so it would also describe interfaces with MTU 0 or negative that the check skips.
fix: Add a test in codersdk/healthsdk/interfaces_internal_test.go asserting an up interface with a non-link-local address and MTU <= 0 does not produce an EIF01 warning; optionally qualify with "greater than 0".
verified: true
- id: accuracy-2
persona: accuracy
class: suggestion
blocking: false
file: docs/admin/monitoring/health-check.md
line: 280
quote: "Either the reply was not a text message, or its contents differ from the message Coder sent."
evidence:
- coderd/healthcheck/websocket.go:90-100
- coderd/healthcheck/websocket_test.go:19-91
rule: null
problem: The two conditions that produce EWS03 are pinned only by websocket.go; websocket_test.go never exercises the message-type or content-mismatch path.
fix: Add a TestWebsocket sub-test returning a different message type or different contents, asserting CodeWebsocketMsg and SeverityError.
verified: trueAutomated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong. |
|
Closing and reopening under a human author, as required for this repository. |
Two health codes,
EWS03andEIF01, are emitted at runtime but had no section in the health check docs.health.Message.URLlinks toadmin/monitoring/health-check#<lowercased code>, so operators who hit either code followed a link to an anchor that did not exist.Changes:
docs/admin/monitoring/health-check.md: adds anEWS03section (the WebSocket echo reply had the wrong message type or contents) under Websocket. Adds a new "Network interfaces" section withEIF01(an interface MTU below 1378). Both use the existing### CODE/#### Title/ Problem / Solution format, and the prose is hand-written.coderd/healthcheck/health/docs_test.go: addsTestCodesDocumented. It reads everyCode*constant frommodel.go, so new codes are covered without editing the test, including untyped ones likeEIF01andESTUN01. It builds each code's link withhealth.Message{Code: ...}.URL("")and fails if the fragment does not match a heading anchor on the page. Headings inside fenced code blocks are ignored. It runs in the normal Go test suite in CI. Without the new docs sections it fails for exactlyEIF01andEWS03.Checks run:
go test ./coderd/healthcheck/health/,golangci-linton the package,make pre-commit(includes markdownlint, docs-html, docs-manifest, docs-redirects and emdash), andmake lint/prose. The remaining Vale suggestions on the page are all on lines this PR does not change.Verified against:
coderd/healthcheck/health/model.go(code constants andMessage.URLanchor construction)coderd/healthcheck/websocket.go(EWS03emission, echo against/api/v2/debug/ws)codersdk/healthsdk/interfaces.go(EIF01emission,safeMTU = 1378, filtering of interfaces that are down, have no addresses, or have only link-local addresses, warning severity)cli/ping.go,cli/netcheck.go,cli/cliui/agent.go,agent/health.go,support/support.go(where the interface report appears)docs/admin/networking/troubleshooting.md#low-mtuanddocs/reference/cli/server/index.md#--block-direct-connections(link targets)Open questions for the reviewer:
EIF01does not appear on the deployment health page. Onlycoder ping,coder netcheckand support bundles report it. I documented it on the health check page under a new "Network interfaces" section with a note explaining this, becauseMessage.URLalways links to that page. Is that placement acceptable?EWS03causes (a proxy, load balancer or traffic inspection device changing WebSocket messages, or the Access URL routing to a different service) are inferred from what the check does. No field reports confirm them. A networking SME may want to confirm or refine them.### CODEheadings. The existing#eacs03links suggest it does.Generated by Coder Agents.
Closes DOCS-910