Repository navigation
fix: document the lock-wait 503 on placement and rename routes - #262
Merged
Merged
Conversation
PUT /locations/{locationId}/entity/{entityId} and the three PATCH .../name
routes can wait on a row another request holds and be answered 503 by the
handling from #253, but the contract listed that answer only on the move and
delete routes.
Adds the shared LockTimeout response to those four operations, a spec guard
requiring it on every PUT, PATCH and DELETE, and tests of the expired wait.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A placement inserts a new row rather than writing to an existing one, and the reason POST is excluded is that it references only rows it created. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Member
Author
|
Self-review rubric, scored against head
Finding fixed before this review: the guard first said these routes "write to an existing row", which is untrue of a placement. It was renamed and reworded in Non-blocking notes:
The dev loop's merge hold applies because the diff touches This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener). drafted by Claude on behalf of Daniel Stephenson |
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
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.
Summary
503(#/components/responses/LockTimeout) is added toPUT /api/v1/locations/{locationId}/entity/{entityId}, as Spec omits 503 on PUT /locations/{locationId}/entity/{entityId}, which can wait on a lock the move holds #259 asked.PATCH /api/v1/entities/{id}/name,/environments/{id}/nameand/grids/{id}/name. These were not named in Spec omits 503 on PUT /locations/{locationId}/entity/{entityId}, which can wait on a lock the move holds #259 and were found while checking it: a rename waits on a row an environment delete has removed but not committed. No separate tracking issue was filed for them.OpenApiSpecDriftTest.routesThatDependOnExistingRowsDocumentTheLockTimeoutnow requires the503on everyPUT,PATCHandDELETE, so a new write route cannot omit it silently.POSTis excluded because its inserts take ids from sequences and reference only rows the same request created.No production code is changed.
GlobalExceptionHandleralready answers these waits503; only the contract was behind.Closes #259
What was and was not confirmed
#259 asked for the wait to be confirmed before the spec changed. That was done only in part, because no Postgres server is available in the session sandbox.
CannotAcquireLockExceptionCannotAcquireLockExceptionFOR UPDATEFOR KEY SHAREandFOR UPDATEThe foreign-key path is the one that matters most in production, because a placement commits as soon as its insert finishes, so the first row of the table can only last a moment outside the test's held transaction. A compose smoke test on real Postgres is recommended before merge: hold
SELECT ... FOR UPDATEon aviron.locationrow inpsqlfor longer thandatabase.lockTimeoutMs, send the placementPUT, and expect503withRetry-After.The rename evidence covers the entity route only; the grid and environment routes share the same
DbInteractions.updatepath. An environment's row is the cascade's last delete, so a rename of it can only wait for a very short window. The503is still documented there so the guard stays a single rule.Test plan
mvn -B test: 668 tests executed, 0 failuresLockWaitBoundTestcovers both expired waits on H2 through the real repositoriesLocationControllerTestandEntityControllerTestassert503withRetry-Afterpytestwas not run locally: no Python file changed. Both clients surface a503on these routes the way they already do on the move route.Backlog not picked up this cycle
pom.xmlbuild pipeline and exceeds a single-cycle scope ceiling.docs/openapi/viron-api.jsonis on the dev loop's do-not-auto-merge list, so this PR is left for human review.This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).
🤖 Generated with Claude Code
drafted by Claude on behalf of Daniel Stephenson