Repository navigation
fix: list every enum value the API can return in the Swagger spec - #30122
Conversation
e8769be to
0062275
Compare
0062275 to
1a998a1
Compare
|
/coder-agents-review |
|
Chat: Review posted | View chat Review history
deep-review v0.13.0 | Round 5 | Last posted: Round 5, 26 findings (1 P2, 9 P3, 13 P4, 3 Nit), APPROVE. Review Finding inventoryFindings
Contested and acknowledgedCRF-19 (P4, codersdk/apikey.go:39) - LoginTypeOAuth2ProviderApp makes request schemas list a rejected value
Round logRound 1Netero first pass: 1 P3, 2 Note, no P0, panel proceeded. Law not run (effective additions 39). Full panel, focused (Go only): ging-go, ryosuke, melody, pariston, mafuuu, gon, leorio, mafu-san, wildcard kite. Result: 1 P2, 3 P3, 2 P4, 1 Nit posted; 4 body notes; 3 out of scope; 2 dropped. Gon P2 on comment wording downgraded to Nit (no behavior or reader impact; Leorio judged the comment accurate). Reviewed against 2255794..1a998a1. Round 2Churn guard PROCEED: CRF-1, 4, 5, 6, 7, 8, 9 author fixed in 26c3600 (claims; reviewers verified CRF-1, 4, 5, 6, 8, 9; CRF-7 partially, gaps in CRF-17, CRF-24, CRF-25). Fix round (commits only address R1 findings; no new repo files, no exported signature changes). Panel: R1 raisers whose code changed (mafuuu, pariston, melody, ryosuke, mafu-san, gon, leorio), delta specialists (ging-go, ging-ts, ging-react, nami, bisky, komugi), wildcard knov. Netero advisory: 2 P3, 2 P4, 1 Note. New: 3 P3, 2 P4, 1 Nit posted from panel; CRF-23 downgraded P2 to P3 (keep-argument: a wrong rationale on the allowlist invites bad entries; downgrade reason: consequence is reader confusion, the mechanical check is unaffected). Gon P2 enumStrings doc downgraded to Nit (style only). CRF-27 dropped. Reviewed against 2255794..26c3600. Round 3Churn guard PROCEED: CRF-17, 18, 20, 23, 24, 25, 26, 28 author fixed in 261101a; CRF-22 fixed by description update; CRF-19 contested. Dispute check-in: Netero (R2 agent resumed via message_agent) accepted the CRF-19 defense, closed 1/1; request-field narrowing recorded as CRF-33 (OOS). Netero advisory: 1 P4 (CRF-32). Fix round (delta only fixes R2 findings). Panel: raisers whose code changed (gon, leorio, knov, mafu-san), delta specialists (ging-go, ging-ts, bisky, komugi), wildcard meruem. Reviewers verified CRF-17, 18, 20, 22, 23, 24, 25, 28 fixed; Mafu-san found CRF-23 fix incomplete (CRF-40). Downgrades: Gon P2 test doc to P4 (keep-argument: doc misstates the defect class; downgrade: the failure messages name each defect, consequence is one loose clause); Gon P2 closure comment to Nit (style); Mafu-san P2 description to P3 (keep-argument: squash body permanent and implies a wire change; downgrade: same class as CRF-22 at P3, one bullet). Gon re-raise of CRF-26 dropped (CRF-36). Reviewed against 2255794..261101a. Round 4Churn guard PROCEED: CRF-32, 34, 35, 37, 38, 40 author fixed in c044dce; CRF-39 fixed by description update. Netero advisory: 1 P4 (CRF-42), 1 Nit (CRF-43). Fix round (delta changes comments and failure messages only). Panel: raisers whose code changed (gon, leorio, mafu-san), delta specialists (ging-go, bisky), wildcard chopper. Two new findings were caused by text the R3 review suggested (CRF-37/38 "enums or oneof", CRF-34 doc without the function name); this round's suggestions were checked against allowedSubsets, oneof request fields, and the Go doc convention. Gon P2 x2 dropped as churn on text already iterated (CRF-46, CRF-47; keep-argument: restating clauses; drop reason: style only, comments verified accurate by Leorio and Netero). Reviewed against 2255794..c044dce. Round 5Churn guard PROCEED: CRF-42, CRF-45 author fixed in 99dba17. Netero advisory: no findings. Fix round (delta changes one test doc comment and two failure messages). Panel: raisers (leorio, mafu-san, gon), delta specialists (ging-go, bisky), wildcard mafuuu. All reviewers: no findings; fixes verified. No open findings remain. Reviewed against 2255794..99dba17. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
There was a problem hiding this comment.
This PR removes 34 enums struct tags and two @Param enum lists so the Swagger spec uses each named type's full value list, and renames the WatchErrorCode zero value. Findings: 1 P2, 3 P3, 2 P4, 1 Nit.
Out of scope (needs a ticket or explicit acceptance by a human):
codersdk/workspacebuilds.go:43: no test compares SDK enum const blocks with their database enums (database.AllBuildReasonValues()and siblings), soBuildReasonandLoginTypedrifted from the database without a failing check, and the generated reference inherits the drift.Makefile:1505:coderd/apidoc/.gendepends on$(wildcard codersdk/*.go), which does not matchcodersdk/healthsdk/orcodersdk/workspacesdk/, so a change limited to those packages does not regenerateswagger.jsonthroughmake gen.coderd/provisionerdaemons.go:26: theidsparameter is described as job IDs but filters daemon IDs, and the handler'sofflineandmax_ageparameters have no@Paramline, so the reference misdescribes this endpoint's filters.
Notes:
codersdk/workspacesdk/workspaceagentconnwatch.go:20:WatchErrorUnspecifiedhas no references, and theWatchErrorCodedefinition still lists0, a code the server does not send.codersdk/audit.go:287: the removedCreateTestAuditLogRequest.resource_typelist containedauditable_group, which is not aResourceTypevalue, so this removal also drops a value the server would not accept.codersdk/agentsdk/agentsdk.go:674:AgentMetric.Typekeepsenums:"counter,gauge", a duplicate ofAgentMetricTypethat the description's list of kept tags does not mention. The type is not inswagger.json, so it has no effect on the spec.- PR description: it says the duplicated
statuslist breaks code generators but not how. The spec listed six statuses twice in oneenumarray, and Swagger 2.0 requiresenumitems to be unique.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
Round 2 reviews 26c3600, which fixes the round 1 findings, adds three SDK enum constants, adds TestSwaggerEnumsNotNarrowed, and attributes autodelete builds to Coder in the dashboard. Findings: 5 P3, 4 P4, 1 Nit.
All seven round 1 findings are fixed, and reviewers checked each fix against the code. TestSwaggerEnumsNotNarrowed fails against the base spec and passes at head. Four of the new findings are gaps or inaccurate comments in that test.
Out of scope (needs a ticket or explicit acceptance by a human):
coderd/provisionerdaemons.go:27: no test checks that the type in a@Paramannotation matches the type the handler parses, so a query parameter can document values the handler rejects with a 500 while the suite stays green.site/src/utils/workspace.tsx:24: a system build reason must be added in three places (thegetDisplayWorkspaceBuildInitiatedByswitch,systemBuildReasons,buildReasonLabels), and onlybuildReasonLabelsis type-checked, so a new reason can get a label but be shown as initiated by the owner.
Notes:
codersdk/provisionerdaemons.go:170:MissingTemplateParameterrepeats the string ofrunner.MissingParameterErrorCodeinstead of referencing it, as its two siblings do, so renaming one of the two strings would not cause a compile error.coderd/coderdtest/swagger_test.go:180: Swagger 2.0 query parameters carry no$ref, so the test cannot detect anenums(...)list that narrows a named type on a@Param. No such list exists at head.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
Round 3 reviews 261101a, which documents both provisioner status filters as arrays, starts WatchErrorCode at iota + 1, and extends TestSwaggerEnumsNotNarrowed to array items, values outside the type, and duplicates in every enum list. Findings: 1 P3, 5 P4, 1 Nit.
The round 2 findings on the test, the autodelete test row, the status array type, the WatchErrorCode zero value, and the description are fixed; reviewers reproduced the array and foreign-value failures against regenerated specs. The defense on LoginTypeOAuth2ProviderApp in request schemas is accepted: the response enum must list the value, and the request fields already listed rejected values before this PR. The remaining findings are wording in the test and the description.
Out of scope (needs a ticket or explicit acceptance by a human):
codersdk/users.go:173:CreateUserRequestWithOrgs.login_typeandConvertLoginRequest.to_type(codersdk/users.go:388) use the sharedLoginType, so the spec liststoken,"", andoauth2_provider_appas request values the handlers reject with 400.coderd/httpapi/queryparams.go:319:ProvisionerDaemonStatusesandp.Strings(coderd/provisionerjobs.go:109) accept any string, and the queries cast it toprovisioner_daemon_status[]andprovisioner_job_status[], so astatusvalue outside the documented enum likely returns 500 instead of a 400 validation error (inferred from the cast, not run).
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
Round 4 reviews c044dce, which changes the test's comments and failure messages and restores the WatchErrorCode comment. Findings: 2 P4.
The round 3 findings are fixed, and the description now matches the base-to-head diff. Both remaining findings come from wording the round 3 review suggested: the "enums or oneof" failure text and the test doc without the function name. The suggestions below were checked against the oneof request fields, allowedSubsets, and the Go doc convention.
Notes:
coderd/coderdtest/swagger_test.go:192: failures are keyed by Swagger definition, not by the Go struct that holds the tag, so a narrowing tag onReducedUser.Statusfails underReducedUser,User, andTemplateUser, and an intentional subset needs oneallowedSubsetskey per embedding struct.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
Round 5 reviews 99dba17, which rewords the TestSwaggerEnumsNotNarrowed doc comment and its two failure messages. No new findings.
Both round 4 findings are fixed, and no findings remain open. The test passes at head and fails with the new messages when a foreign value is added or an allowlist entry is removed. The out-of-scope items listed in earlier rounds still need a ticket or explicit acceptance by a human.
🤖 This review was automatically generated with Coder Agents.
Part of DOCS-1122. Assisted-by: AI
Document the provisioner daemon status filter with its own type, add the missing build reason, login type, and job error code values, keep representative examples, and add a test that fails when an enums tag narrows a named type or an enum list repeats a value. The dashboard labels the new autodelete build reason as a system build. Part of DOCS-1122. Assisted-by: AI
Document the provisioner status filters as lists, since both handlers accept comma-separated and repeated values. Drop the unused WatchErrorUnspecified so the spec lists only the codes the server sends. Make TestSwaggerEnumsNotNarrowed check array items, reject values a type does not have, and detect duplicates in definitions and properties. Part of DOCS-1122. Assisted-by: AI
Part of DOCS-1122. Assisted-by: AI
Part of DOCS-1122. Assisted-by: AI
Part of DOCS-1122. Assisted-by: AI
99dba17 to
5c1d07c
Compare
|
Merged with 🤖 Posted by Coder Agents on behalf of @nickvigilante. |
The API reference is generated from Swagger comments and struct tags, and several
enums:"..."tags narrowed a named enum type, so the docs omitted values the server returns. For example,User.statuslisted onlyactiveandsuspended, notdormant, andTemplateVersion.warningslistedDEPRECATED_PARAMETERS, which is not a value of the type.Remove 34
enumstags that narrow or duplicate a named type so the referenced type's full value list is used. Tags that describe an intentional subset stay: ACL role fields (which omit the""deleted sentinel used only in update requests),APIKey.scope, and plain-string fields.Template.provisionerkeeps its tag because.swaggoreplacesProvisionerTypewithstring.Also fix enum defects that break code generators:
statusquery parameters listed their enum twice (Swagger 2.0 requires uniqueenumitems) or with the wrong type. Both are now[]codersdk.ProvisionerJobStatusand[]codersdk.ProvisionerDaemonStatus, matching what each handler parses, including comma-separated values. The daemons route previously documented job statuses, which the handler rejects with a 500._zero placeholder ofWatchErrorCodewithiota + 1, so the spec no longer lists 0 orx-enum-varnames: ["_", ...]. Wire values are unchanged.Where the narrowed tag hid values the server returns, the SDK type now includes them:
LoginTypeOAuth2ProviderApp,BuildReasonAutodelete, andMissingTemplateParameterwiden the generated TypeScript unions. The dashboard attributesautodeletebuilds to Coder like other system builds.APIKey.login_typeandAuthorizationCheck.actionset explicit examples so the generated samples stay representative.TestSwaggerEnumsNotNarrowedfails when a property's enum list drops values of its named type (other than the 15 allowlisted intentional subsets), lists a value the type lacks, or repeats a value.Part of DOCS-1122, split from #30121.
🤖 Built with AI assistance.