HYPERFLEET-978 - docs: change status endpoint from POST to PUT#137
HYPERFLEET-978 - docs: change status endpoint from POST to PUT#137ma-hill wants to merge 1 commit into
Conversation
|
Skipping CI for Draft Pull Request. |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis pull request updates documentation across multiple HyperFleet design, framework, API, and guide files to change the adapter status reporting HTTP method from POST to PUT. All references to adapter-reported status endpoints now use Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsGit: Failed to clone repository. Please run the Comment |
ma-hill
force-pushed
the
HYPERFLEET-978
branch
3 times, most recently
from
471dbc3 to
d6d0adf
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
hyperfleet/components/adapter/framework/adapter-integration-tests.md (1)
98-108:⚠️ Potential issue | 🟠 Major | ⚡ Quick winTest specification conflicts with actual implementation.
The integration test specification now documents
PUT /clusters/{id}/statusesfor creating/upserting statuses, but linked repository findings show the actual mock implementation still expects POST:hyperfleet-adapter repository:
test/integration/testutil/mock_api_server.go:104-105— Comment states: "POST /clusters/{id}/statuses - Store status and return success"- The mock server handler is registered for POST requests, not PUT
Impact: This test specification will not match the actual test implementation, causing test failures or misleading test results.
Recommendation: Update the mock server implementation in hyperfleet-adapter to handle PUT before merging this documentation change, or revert these test spec changes until implementation is ready.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/components/adapter/framework/adapter-integration-tests.md` around lines 98 - 108, The docs were changed to describe PUT /clusters/{clusterId}/statuses but the mock server in test/integration/testutil/mock_api_server.go still registers and handles POST for "/clusters/{id}/statuses"; update the mock to register a handler for PUT (or both PUT and POST) that performs the same store/upsert logic as the existing POST handler (where the handler function that currently stores status and returns success is registered), or revert the documentation change until the mock's route registration is updated so the test spec and implementation match.hyperfleet/components/api-service/api-service.md (2)
57-69:⚠️ Potential issue | 🟠 Major | ⚡ Quick winThis document still contains POST semantics after switching endpoints to PUT.
/statusesis now documented as PUT, but the Dependencies section still states “Adapters POST status updates” (Line 225). Update that section so the contract is internally consistent.As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
Also applies to: 112-112
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/components/api-service/api-service.md` around lines 57 - 69, The Dependencies section still says "Adapters POST status updates" while all /statuses endpoints (e.g. /api/hyperfleet/v1/clusters/{id}/statuses and /api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses) are now defined as PUT; update that prose to state that adapters PUT status updates (or "Adapters send status updates via PUT to the /statuses endpoints") so the contract matches the endpoint table, and ensure any other occurrences of "POST status updates" (e.g., the referenced Dependencies paragraph) are changed to "PUT" to keep the document consistent.
57-69:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftArchitecture docs now conflict with linked API source-of-truth artifacts.
These endpoints are documented as PUT, but linked
openshift-hyperfleet/hyperfleet-apiartifacts (OpenAPI and API docs) still describe POST for status routes. This should be reconciled before merge to prevent contract drift across repos.As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/components/api-service/api-service.md` around lines 57 - 69, The docs list the status-report endpoints as PUT but the authoritative OpenAPI/artifacts in openshift-hyperfleet/hyperfleet-api still define them as POST, causing contract drift; reconcile by choosing the correct HTTP method and making both places consistent: update the markdown lines for `/api/hyperfleet/v1/clusters/{id}/statuses` and `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` to match the OpenAPI (or update the OpenAPI to use PUT if that is the intended change), then run the API docs generation/tests and update any operationId/consumer code that depends on the method so clients remain correct. Ensure the chosen method is reflected in the OpenAPI spec, generated API docs, and this api-service.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hyperfleet/components/adapter/framework/adapter-status-contract.md`:
- Line 678: The example request path uses PUT /api/v1/clusters/{id}/statuses
which doesn't match the documented base URL contract
/api/hyperfleet/{version}/clusters/{clusterId}/statuses; update the example at
the PUT example to follow the base URL shape (include the /api/hyperfleet/
prefix and {version} segment and use {clusterId} as the path parameter) so the
example and the documented contract (the base URL string
/api/hyperfleet/{version}/clusters/{clusterId}/statuses) are consistent.
- Around line 96-98: Update the table of contents and any lingering references
titled "POST Request" and "Always Use POST" to reflect the new PUT-based
contract by renaming those TOC entries and internal anchors to "PUT Request
(Upsert ClusterStatus)" (and any variant text) so they match the actual section
heading; also update the two other occurrences mentioned (around the same
document's later instances) so all links/anchors and cross-references point to
the PUT section rather than POST. Ensure header IDs/anchors (if present) and any
inline references to the old POST wording are changed to the new PUT wording to
keep the TOC, links, and section titles consistent.
In `@hyperfleet/components/api-service/hard-delete-design.md`:
- Around line 97-103: The sequence diagrams mix POST and PUT for adapter status
updates during deletion; update every occurrence of status-update messages in
this deletion flow so they use PUT (e.g., change any "POST
/clusters/{id}/adapter_statuses" or "POST /nodepools/{id}/adapter_statuses"
messages later in the file to "PUT ...") to preserve deletion semantics; ensure
the existing payload semantics (Finalized=True, Reconciled=False and any adapter
condition details) remain unchanged and that CLAdapter, API, and NPAdapter
arrows reflect PUT consistently throughout the deletion sequence.
- Around line 51-57: The documentation uses two different endpoint paths (`PUT
/adapter_statuses` in this file vs the standardized `PUT .../statuses` used
elsewhere), creating an ambiguous API contract; update the text in
hard-delete-design.md to use the canonical `PUT .../statuses` everywhere
(replace occurrences of `PUT /adapter_statuses` and similar variants) so it
matches the rest of the PR and HyperFleet status-reporting conventions, and run
a quick grep/scan for any remaining `adapter_statuses` mentions to ensure
consistency with the standardized status endpoint naming.
In `@hyperfleet/docs/status-guide.md`:
- Around line 133-143: The guide inconsistently documents status reporting
(mixing POST/PATCH with PUT); standardize the contract to always use PUT for
adapter status reports by replacing all POST/PATCH references with PUT for the
endpoint `/v1/clusters/{clusterId}/statuses`, update the Table of Contents and
every section (including "Adapter Status Reporting Flow" and all example
request/response blocks and cURL/code snippets) to show PUT and the API's upsert
behavior, ensure the explanatory note under "Adapter Action: PUT Status Report"
clearly states the API performs upsert, and run a project-wide search for
occurrences of `/v1/clusters/*/statuses` or "status report" to confirm no stray
POST/PATCH guidance remains.
- Around line 1703-1706: The example for "Scenario 1" contradicts the documented
adapter request contract: it shows a full ClusterStatus payload (generation +
adapter_statuses) while the text says an adapter PUTs only its adapter-specific
status; update the doc to make the contract consistent by either (A) replacing
the sample request body for PUT /v1/clusters/cls-123/statuses with the
adapter-only status payload shape used elsewhere (the per-adapter status
object/fields) and mention that the server will create the ClusterStatus
resource, or (B) explicitly state that the first reporting adapter must send the
full ClusterStatus (including generation and adapter_statuses) and keep the
sample body but also align other examples to that contract; locate and update
the example body and the surrounding explanatory sentence mentioning
ClusterStatus and adapter_statuses to reflect the chosen contract (use the same
adapter-only payload shape or the full ClusterStatus shape consistently).
---
Outside diff comments:
In `@hyperfleet/components/adapter/framework/adapter-integration-tests.md`:
- Around line 98-108: The docs were changed to describe PUT
/clusters/{clusterId}/statuses but the mock server in
test/integration/testutil/mock_api_server.go still registers and handles POST
for "/clusters/{id}/statuses"; update the mock to register a handler for PUT (or
both PUT and POST) that performs the same store/upsert logic as the existing
POST handler (where the handler function that currently stores status and
returns success is registered), or revert the documentation change until the
mock's route registration is updated so the test spec and implementation match.
In `@hyperfleet/components/api-service/api-service.md`:
- Around line 57-69: The Dependencies section still says "Adapters POST status
updates" while all /statuses endpoints (e.g.
/api/hyperfleet/v1/clusters/{id}/statuses and
/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses) are now defined as
PUT; update that prose to state that adapters PUT status updates (or "Adapters
send status updates via PUT to the /statuses endpoints") so the contract matches
the endpoint table, and ensure any other occurrences of "POST status updates"
(e.g., the referenced Dependencies paragraph) are changed to "PUT" to keep the
document consistent.
- Around line 57-69: The docs list the status-report endpoints as PUT but the
authoritative OpenAPI/artifacts in openshift-hyperfleet/hyperfleet-api still
define them as POST, causing contract drift; reconcile by choosing the correct
HTTP method and making both places consistent: update the markdown lines for
`/api/hyperfleet/v1/clusters/{id}/statuses` and
`/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` to match the
OpenAPI (or update the OpenAPI to use PUT if that is the intended change), then
run the API docs generation/tests and update any operationId/consumer code that
depends on the method so clients remain correct. Ensure the chosen method is
reflected in the OpenAPI spec, generated API docs, and this api-service.md.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Central YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 9992e68e-939f-40c8-aef4-d8b168c9c132
📒 Files selected for processing (11)
hyperfleet/README.mdhyperfleet/components/adapter/framework/adapter-deletion-flow-design.mdhyperfleet/components/adapter/framework/adapter-design-decisions.mdhyperfleet/components/adapter/framework/adapter-flow-diagrams.mdhyperfleet/components/adapter/framework/adapter-frame-design.mdhyperfleet/components/adapter/framework/adapter-integration-tests.mdhyperfleet/components/adapter/framework/adapter-metrics.mdhyperfleet/components/adapter/framework/adapter-status-contract.mdhyperfleet/components/api-service/api-service.mdhyperfleet/components/api-service/hard-delete-design.mdhyperfleet/docs/status-guide.md
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
hyperfleet/components/api-service/api-service.md (2)
57-69:⚠️ Potential issue | 🟠 Major | ⚡ Quick winThis document still has a stale POST reference after the PUT migration.
Line 225 in the Dependencies table still says adapters POST status updates, which conflicts with the updated PUT contract in this file.
Suggested doc fix
-| Adapters | POST status updates to this API | +| Adapters | PUT status updates to this API |As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
Also applies to: 112-112
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/components/api-service/api-service.md` around lines 57 - 69, The Dependencies table still refers to adapters sending status updates via POST which is stale—update that entry to reflect the new PUT contract used elsewhere (e.g., change the "adapters POST status updates" wording to "adapters PUT status updates" and ensure endpoints listed match the PUT endpoints `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` and `/api/hyperfleet/v1/clusters/{id}/statuses`); search for the phrase "adapters POST status updates" (and the duplicate at lines referenced) and replace it with the correct PUT description and endpoint references so the document consistently reflects the PUT migration.
57-69:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftCross-repo API contract drift (PUT here vs POST elsewhere) needs coordination before merge.
Linked repo findings show
openshift-hyperfleet/hyperfleet-apidocs/examples andopenshift-hyperfleet/hyperfleet-adapterdocs/tests/mock server still document/enforce POST for/statuses. Merging this architecture update without synchronized updates or an explicit compatibility note leaves the platform contract ambiguous.As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/components/api-service/api-service.md` around lines 57 - 69, The API doc change flips the HTTP verb for the nodepool status endpoint from POST to PUT causing cross-repo contract drift; revert the method for `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` back to POST (or else coordinate and update all clients/servers to accept PUT), and add a compatibility note in the docs indicating the change and required upgrades in `hyperfleet-api` and `hyperfleet-adapter` so consumers are not broken; ensure the same treatment is applied to the cluster-level `/api/hyperfleet/v1/clusters/{id}/statuses` entry if intended.
♻️ Duplicate comments (3)
hyperfleet/docs/status-guide.md (1)
19-19:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winTOC anchor still points to the old POST section id.
Line 19 text was updated to “Always PUT”, but the anchor is still
#reporting-status-always-post, so the TOC link is incorrect. Update it to the PUT anchor to keep navigation working.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/docs/status-guide.md` at line 19, The TOC entry for "Reporting Status: Always PUT" still links to the old anchor "#reporting-status-always-post"; update the anchor target in the TOC so the link matches the new section id by replacing "#reporting-status-always-post" with "#reporting-status-always-put" for the "[Reporting Status: Always PUT]" TOC item to restore correct navigation.hyperfleet/components/adapter/framework/adapter-status-contract.md (2)
678-678:⚠️ Potential issue | 🟠 Major | ⚡ Quick winExample request path does not match the documented base URL contract.
Line 678 uses
PUT /api/v1/clusters/.../statuses, but Line 71 defines{hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/{clusterId}/statuses. This mismatch can lead to incorrect client implementations.As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/components/adapter/framework/adapter-status-contract.md` at line 678, The example request path currently shows the incorrect short form "PUT /api/v1/clusters/cls-123/statuses"; update the example to use the documented base URL contract by replacing that path with the full contract form "{hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/{clusterId}/statuses" (e.g., "PUT {hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/cls-123/statuses") so the example matches the contract defined earlier and avoids client implementation errors.
96-98:⚠️ Potential issue | 🟠 Major | ⚡ Quick winTOC still advertises POST sections after switching body text to PUT.
The content now uses PUT, but TOC entries at Line 16 and Line 51 still reference POST. Please align TOC labels/anchors with the updated PUT section names.
As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
Also applies to: 772-774
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@hyperfleet/components/adapter/framework/adapter-status-contract.md` around lines 96 - 98, The table of contents still references "POST" for the adapter upsert sections even though the body headings were changed to "PUT"; update the TOC entries (the ones currently pointing to the upsert/adapter-status sections referenced near the original Line 16 and Line 51 and also occurrences around 772-774) so their labels and anchor targets use "PUT" and match the exact heading text/anchor of the corresponding "PUT Request (Upsert ClusterStatus)" section(s); ensure anchor slugs are consistent with the heading text (or update headings to match TOC if you prefer) so links work and labels read "PUT Request" instead of "POST".
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hyperfleet/components/adapter/framework/adapter-design-decisions.md`:
- Line 181: Update the table of contents entry that still reads "Adapters POST
Status Updates" so it matches the section heading "Adapters PUT Status Updates":
change the TOC text to "Adapters PUT Status Updates" and update the anchor link
(if present) to match the heading slug for "Adapters PUT Status Updates" so the
TOC text and link both point to the correct section. Ensure the anchor/slug
formatting matches how other headings are generated in this document.
In `@hyperfleet/components/adapter/framework/adapter-flow-diagrams.md`:
- Around line 527-532: The diagram text still describes adapters using POST and
idempotency rules; update that section to reflect PUT semantics to match the
diagram (replace mentions of POST with PUT and adjust idempotency wording
accordingly), ensuring actors like Sub_Adapter, Res_Adapter and Sentinel are
described as using PUT for status updates and resource cleanup and that the
idempotency contract language matches PUT behavior (safe to retry/replace
existing state) so the document no longer contains conflicting guidance.
In `@hyperfleet/components/adapter/framework/adapter-frame-design.md`:
- Line 775: The document contains mixed POST/PUT guidance; update all references
to use PUT-only semantics: change the phrase "via POST requests" in the "Status
Reporter Utilities" section to "via PUT requests", update any other occurrences
that mention POST (including the example/request snippets under the "PUT status
payload to HyperFleet API endpoint" header and the content currently at lines
~975-977) so headers, prose, and sample HTTP verbs/curl examples consistently
use PUT, and ensure any code examples, function names or endpoints that indicate
POST are corrected to PUT semantics (look for the "Status Reporter Utilities"
section and the "PUT status payload to HyperFleet API endpoint" heading to
locate the places to fix).
In `@hyperfleet/components/adapter/framework/adapter-metrics.md`:
- Line 225: The example metric hyperfleet_adapter_api_requests_total shows
method="PUT" but the allowed-method enum in the metric label definition omits
PUT; update the label definition for the method enum (the allowed-method list
used for the method label in the metric documentation/instrumentation guidance)
to include "PUT" alongside existing methods so the documentation and example for
hyperfleet_adapter_api_requests_total are consistent.
In `@hyperfleet/components/adapter/framework/adapter-status-contract.md`:
- Around line 640-642: The endpoint path in the example uses "/api/{{
.hyperfleetApiVersion }}/clusters/{{ .clusterId }}/statuses" which does not
match this doc’s contract that expects
"/api/hyperfleet/{hyperfleetApiVersion}/..."; update the endpoint template (the
endpoint value using .hyperfleetApiBaseUrl and .hyperfleetApiVersion) to include
the "hyperfleet" segment so it reads "/api/hyperfleet/{{ .hyperfleetApiVersion
}}/clusters/{{ .clusterId }}/statuses" (or alternatively change the contract at
its declaration to remove the "hyperfleet" segment) so both the endpoint in this
file and the contract at the earlier declaration are identical.
In `@hyperfleet/README.md`:
- Line 146: The README now documents PUT for the /clusters/{id}/statuses
endpoint but other repos use POST; update the hyperfleet documentation and mocks
so the HTTP verb is consistent across repos: choose the agreed verb (PUT or
POST), then update hyperfleet/README.md entry ("Reports status → ...") to match
and update hyperfleet-api spec/examples and hyperfleet-adapter mock/integration
tests to use the same verb for /clusters/{id}/statuses (or explicitly add a
compatibility note in README stating both verbs are supported and describe
behavior); ensure test fixtures and API examples in hyperfleet-api and
hyperfleet-adapter reference the exact path /clusters/{id}/statuses and reflect
the chosen verb.
---
Outside diff comments:
In `@hyperfleet/components/api-service/api-service.md`:
- Around line 57-69: The Dependencies table still refers to adapters sending
status updates via POST which is stale—update that entry to reflect the new PUT
contract used elsewhere (e.g., change the "adapters POST status updates" wording
to "adapters PUT status updates" and ensure endpoints listed match the PUT
endpoints `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` and
`/api/hyperfleet/v1/clusters/{id}/statuses`); search for the phrase "adapters
POST status updates" (and the duplicate at lines referenced) and replace it with
the correct PUT description and endpoint references so the document consistently
reflects the PUT migration.
- Around line 57-69: The API doc change flips the HTTP verb for the nodepool
status endpoint from POST to PUT causing cross-repo contract drift; revert the
method for `/api/hyperfleet/v1/clusters/{id}/nodepools/{np_id}/statuses` back to
POST (or else coordinate and update all clients/servers to accept PUT), and add
a compatibility note in the docs indicating the change and required upgrades in
`hyperfleet-api` and `hyperfleet-adapter` so consumers are not broken; ensure
the same treatment is applied to the cluster-level
`/api/hyperfleet/v1/clusters/{id}/statuses` entry if intended.
---
Duplicate comments:
In `@hyperfleet/components/adapter/framework/adapter-status-contract.md`:
- Line 678: The example request path currently shows the incorrect short form
"PUT /api/v1/clusters/cls-123/statuses"; update the example to use the
documented base URL contract by replacing that path with the full contract form
"{hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/{clusterId}/statuses"
(e.g., "PUT
{hyperfleetApiBaseUrl}/api/hyperfleet/{hyperfleetApiVersion}/clusters/cls-123/statuses")
so the example matches the contract defined earlier and avoids client
implementation errors.
- Around line 96-98: The table of contents still references "POST" for the
adapter upsert sections even though the body headings were changed to "PUT";
update the TOC entries (the ones currently pointing to the upsert/adapter-status
sections referenced near the original Line 16 and Line 51 and also occurrences
around 772-774) so their labels and anchor targets use "PUT" and match the exact
heading text/anchor of the corresponding "PUT Request (Upsert ClusterStatus)"
section(s); ensure anchor slugs are consistent with the heading text (or update
headings to match TOC if you prefer) so links work and labels read "PUT Request"
instead of "POST".
In `@hyperfleet/docs/status-guide.md`:
- Line 19: The TOC entry for "Reporting Status: Always PUT" still links to the
old anchor "#reporting-status-always-post"; update the anchor target in the TOC
so the link matches the new section id by replacing
"#reporting-status-always-post" with "#reporting-status-always-put" for the
"[Reporting Status: Always PUT]" TOC item to restore correct navigation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Central YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 1d253bbf-25c9-4f29-b55b-e7abe51edf87
📒 Files selected for processing (11)
hyperfleet/README.mdhyperfleet/components/adapter/framework/adapter-deletion-flow-design.mdhyperfleet/components/adapter/framework/adapter-design-decisions.mdhyperfleet/components/adapter/framework/adapter-flow-diagrams.mdhyperfleet/components/adapter/framework/adapter-frame-design.mdhyperfleet/components/adapter/framework/adapter-integration-tests.mdhyperfleet/components/adapter/framework/adapter-metrics.mdhyperfleet/components/adapter/framework/adapter-status-contract.mdhyperfleet/components/api-service/api-service.mdhyperfleet/components/api-service/hard-delete-design.mdhyperfleet/docs/status-guide.md
| --- | ||
|
|
||
| ## 5. Adapters POST Status Updates | ||
| ## 5. Adapters PUT Status Updates |
There was a problem hiding this comment.
TOC still references POST while section now documents PUT.
The heading was updated to PUT, but the table of contents still says “Adapters POST Status Updates” (Line 26). Please sync TOC text/anchor with the new section name.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hyperfleet/components/adapter/framework/adapter-design-decisions.md` at line
181, Update the table of contents entry that still reads "Adapters POST Status
Updates" so it matches the section heading "Adapters PUT Status Updates": change
the TOC text to "Adapters PUT Status Updates" and update the anchor link (if
present) to match the heading slug for "Adapters PUT Status Updates" so the TOC
text and link both point to the correct section. Ensure the anchor/slug
formatting matches how other headings are generated in this document.
| Sub_Adapter->>API: PUT status (Applied=False, Health=True, Finalized=True) | ||
| and Resource cleanup (in parallel) | ||
| Sentinel->>Res_Adapter: CloudEvent (resource) | ||
| Res_Adapter->>Res_Adapter: Capture deleted_time, evaluate lifecycle.delete | ||
| Res_Adapter->>Res_Adapter: Clean up resource resources (per-resource ordering) | ||
| Res_Adapter->>API: POST status (Applied=False, Health=True, Finalized=True) | ||
| Res_Adapter->>API: PUT status (Applied=False, Health=True, Finalized=True) |
There was a problem hiding this comment.
Incomplete PUT migration leaves contradictory status contract in this file.
These diagram updates use PUT, but Line 269-Line 272 still says adapters use POST and describes idempotency for POST. Please update that section to PUT to avoid conflicting guidance in one document.
As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hyperfleet/components/adapter/framework/adapter-flow-diagrams.md` around
lines 527 - 532, The diagram text still describes adapters using POST and
idempotency rules; update that section to reflect PUT semantics to match the
diagram (replace mentions of POST with PUT and adjust idempotency wording
accordingly), ensuring actors like Sub_Adapter, Res_Adapter and Sentinel are
described as using PUT for status updates and resource cleanup and that the
idempotency contract language matches PUT behavior (safe to retry/replace
existing state) so the document no longer contains conflicting guidance.
| - Execute postActions (from `post.postActions`): | ||
| - Evaluate `when` condition (if specified) | ||
| - POST status payload to HyperFleet API endpoint | ||
| - PUT status payload to HyperFleet API endpoint |
There was a problem hiding this comment.
This document still contains conflicting POST guidance.
The updated flow now says PUT, but the “Status Reporter Utilities” section still says status is reported “via POST requests” (Line 637). Please normalize the file to PUT-only wording to avoid contradictory implementation guidance.
As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
Also applies to: 975-977
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hyperfleet/components/adapter/framework/adapter-frame-design.md` at line 775,
The document contains mixed POST/PUT guidance; update all references to use
PUT-only semantics: change the phrase "via POST requests" in the "Status
Reporter Utilities" section to "via PUT requests", update any other occurrences
that mention POST (including the example/request snippets under the "PUT status
payload to HyperFleet API endpoint" header and the content currently at lines
~975-977) so headers, prose, and sample HTTP verbs/curl examples consistently
use PUT, and ensure any code examples, function names or endpoints that indicate
POST are corrected to PUT semantics (look for the "Status Reporter Utilities"
section and the "PUT status payload to HyperFleet API endpoint" heading to
locate the places to fix).
| ```prometheus | ||
| hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="hyperfleet",method="GET",endpoint="/clusters/{id}",status_code="200"} 1523 | ||
| hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="hyperfleet",method="POST",endpoint="/statuses",status_code="200"} 1487 | ||
| hyperfleet_adapter_api_requests_total{component="adapter-validation",version="v1.0.0",adapter_name="validation",api="hyperfleet",method="PUT",endpoint="/statuses",status_code="200"} 1487 |
There was a problem hiding this comment.
Method label enum is now inconsistent with the example.
After switching the example to method="PUT" (Line 225), the allowed-method list still omits PUT (Line 218). Update the label definition so instrumentation guidance is internally consistent.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hyperfleet/components/adapter/framework/adapter-metrics.md` at line 225, The
example metric hyperfleet_adapter_api_requests_total shows method="PUT" but the
allowed-method enum in the metric label definition omits PUT; update the label
definition for the method enum (the allowed-method list used for the method
label in the metric documentation/instrumentation guidance) to include "PUT"
alongside existing methods so the documentation and example for
hyperfleet_adapter_api_requests_total are consistent.
| method: "PUT" | ||
| endpoint: "{{ .hyperfleetApiBaseUrl }}/api/{{ .hyperfleetApiVersion }}/clusters/{{ .clusterId }}/statuses" | ||
| headers: |
There was a problem hiding this comment.
Framework config endpoint path is inconsistent with this document’s own status endpoint contract.
Line 641 uses /api/{{ .hyperfleetApiVersion }}/clusters/.../statuses, but the contract at Line 71 includes /api/hyperfleet/{hyperfleetApiVersion}/.... Please make both path shapes consistent.
As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hyperfleet/components/adapter/framework/adapter-status-contract.md` around
lines 640 - 642, The endpoint path in the example uses "/api/{{
.hyperfleetApiVersion }}/clusters/{{ .clusterId }}/statuses" which does not
match this doc’s contract that expects
"/api/hyperfleet/{hyperfleetApiVersion}/..."; update the endpoint template (the
endpoint value using .hyperfleetApiBaseUrl and .hyperfleetApiVersion) to include
the "hyperfleet" segment so it reads "/api/hyperfleet/{{ .hyperfleetApiVersion
}}/clusters/{{ .clusterId }}/statuses" (or alternatively change the contract at
its declaration to remove the "hyperfleet" segment) so both the endpoint in this
file and the contract at the earlier declaration are identical.
| - Evaluates preconditions | ||
| - Creates Kubernetes resources if conditions met | ||
| - Reports status → POST /clusters/{id}/statuses | ||
| - Reports status → PUT /clusters/{id}/statuses |
There was a problem hiding this comment.
Cross-repo status verb contract is still inconsistent.
Line 146 now documents PUT, but linked repositories still document/test POST for the same /statuses path. Please align hyperfleet-api docs/spec/examples and hyperfleet-adapter mock/integration expectations (or explicitly document compatibility) before merging to avoid contract drift.
As per coding guidelines "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity. Validate changes against HyperFleet architecture standards from the linked architecture repository."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hyperfleet/README.md` at line 146, The README now documents PUT for the
/clusters/{id}/statuses endpoint but other repos use POST; update the hyperfleet
documentation and mocks so the HTTP verb is consistent across repos: choose the
agreed verb (PUT or POST), then update hyperfleet/README.md entry ("Reports
status → ...") to match and update hyperfleet-api spec/examples and
hyperfleet-adapter mock/integration tests to use the same verb for
/clusters/{id}/statuses (or explicitly add a compatibility note in README
stating both verbs are supported and describe behavior); ensure test fixtures
and API examples in hyperfleet-api and hyperfleet-adapter reference the exact
path /clusters/{id}/statuses and reflect the chosen verb.
1 participant
Summary
This change updates the architecture documentation to reflect that adapters use PUT instead of POST when reporting status to the HyperFleet API. This is a documentation-only change to align with the actual API implementation.
Changes made:
Test Plan
Jira Issue