Repository navigation
feat(ipa): add IPA-132 long-running operation initiation rules - #1448
Merged
Merged
Conversation
julius-jogela
force-pushed
the
feat-ipa-132-lro-initiation
branch
2 times, most recently
from
August 24, 2026 15:11
1fdf810 to
d0e4202
Compare
Add the three rules validating how a long-running operation is initiated. The rules select on the declared 202 response through a single isCompliantLongRunningOperation helper: the x-xgen-long-running-operation extension is derived from the 202 during the merge step, so selecting on the 202 gives the same result on the federated spec while also working on the per-service source specs the merge step has not processed. Legacy operations that predate IPA-132 are excluded, whether marked legacy: true by the merge step or matched by the shared legacy operationId list. The shared list becomes a plain JavaScript module the rules import directly, replacing the JSON file: Spectral bundles rule functions with a rollup that cannot import JSON. go generate now extracts the Go copy from that module instead. - xgen-IPA-132-lro-initiation-must-return-202-accepted-with-location: the 202 response must declare a Location header, compared case-insensitively. - xgen-IPA-132-lro-must-not-return-success-status-code-other-than-202: no other 2xx response may be declared, including wildcard codes such as 2XX. - xgen-IPA-132-lro-202-response-must-not-include-content: no media type of the 202 response may declare a schema; media types carrying only versioning metadata are allowed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
julius-jogela
force-pushed
the
feat-ipa-132-lro-initiation
branch
from
August 24, 2026 15:48
d0e4202 to
ed4d06d
Compare
Rename isCompliantLongRunningOperation to isNonLegacyLongRunningOperation: the predicate selects operations in scope for IPA-132, it does not assert that they already follow the contract. Require the canonical Location casing on the 202 response instead of matching header names case-insensitively, with a distinct message when a case variant is declared. The spec has no Location response header today and existing headers already use canonical casing, so this adds no findings.
julius-jogela
marked this pull request as ready for review
August 28, 2026 08:24
julius-jogela
requested review from
andreaangiolillo,
chrysanthi-m,
drinkbird,
lovisaberggren,
maks-m-mongo-leaf,
saisundar and
wtrocki
August 28, 2026 08:25
2 tasks done
yelizhenden-mdb
approved these changes
Aug 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed changes
This PR adds the three IPA-132 rules validating how a long-running operation is initiated: 202 Accepted with a Location header carrying the operation handle, no other success status code, and no response body.
Jira ticket: CLOUDP-435358
Rules added
All at
warnseverity, given$.paths[*][post,put,patch,delete]:xgen-IPA-132-lro-initiation-must-return-202-accepted-with-locationLocationheader, using that exact casingxgen-IPA-132-lro-must-not-return-success-status-code-other-than-2022XX— blocks the "200 if fast, 202 if slow" patternxgen-IPA-132-lro-202-response-must-not-include-contentx-xgen-version) are allowed, consistent with the IPA-108 delete-response precedentHow long-running operations are selected
The rules select on the declared 202 response, through a single
isNonLegacyLongRunningOperationhelper. Thex-xgen-long-running-operationextension is derived from the 202 during the merge step, so selecting on the 202 gives identical results on the federated spec — while also working on the raw per-service specs, where the extension does not exist and where the validation feedback reaches API authors. Legacy operations that predate IPA-132 are excluded, whether markedlegacy: trueby the merge step or matched by the shared legacy operationId list from #1447.The shared list becomes a plain JavaScript module (
legacyLroOperationIds.js) that the rules import directly, replacing #1447's JSON file: Spectral bundles rule functions with a rollup that cannot import JSON, so a data module is the only bundler-safe carrier.go generateextracts the Go copy from that module instead; the existing Go-side drift test keeps the two in sync.Testing
legacy: truemarking and the shared operationId list. Unit tests forisNonLegacyLongRunningOperationand the shared-list wiring.gen-ipa-docs, prettier and eslint clean.spectral lint openapi/.raw/v2.yamlwith the full ruleset: 0xgen-IPA-132-*findings — all 17 legacy 202 operations are excluded by the shared list on the untagged spec.go build,go test -race, golangci-lint (v2.10.1) clean; both generator outputs verified idempotent.Checklist