Skip to content

fix: document the lock-wait 503 on placement and rename routes - #262

Merged
dmccoystephenson merged 2 commits into
mainfrom
feature/document-lock-wait-503-on-writes
Nov 6, 2026
Merged

dmccoystephenson merged 2 commits into
mainfrom
feature/document-lock-wait-503-on-writes

Conversation

@dmccoystephenson

@dmccoystephenson dmccoystephenson commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

Summary

No production code is changed. GlobalExceptionHandler already answers these waits 503; 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.

Wait Evidence
Placement insert against an uncommitted placement of the same entity Reproduced on H2, CannotAcquireLockException
Rename against a row deleted in an uncommitted transaction Reproduced on H2, CannotAcquireLockException
Placement's foreign-key check against a location a move holds FOR UPDATE Not reproduced. H2's foreign-key check does not wait (the insert returned in about 1 ms). The claim rests on Postgres's documented conflict between FOR KEY SHARE and FOR UPDATE

The 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 UPDATE on a viron.location row in psql for longer than database.lockTimeoutMs, send the placement PUT, and expect 503 with Retry-After.

The rename evidence covers the entity route only; the grid and environment routes share the same DbInteractions.update path. An environment's row is the cascade's last delete, so a rename of it can only wait for a very short window. The 503 is still documented there so the guard stays a single rule.

Test plan

  • mvn -B test: 668 tests executed, 0 failures
  • The new guard failed against the unfixed spec, naming exactly the four routes, and passes with the spec change
  • LockWaitBoundTest covers both expired waits on H2 through the real repositories
  • LocationControllerTest and EntityControllerTest assert 503 with Retry-After
  • Postgres smoke test of the foreign-key wait, described above (not run)

pytest was not run locally: no Python file changed. Both clients surface a 503 on these routes the way they already do on the move route.

Backlog not picked up this cycle

docs/openapi/viron-api.json is 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

dmccoystephenson and others added 2 commits November 6, 2026 02:50
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>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric, scored against head 84d1dca with CI green on build, python-client (3.8) and python-client (3.12).

  • Scope: PASS. Six files: the spec, the README's lock-wait paragraph, and four test classes. The three PATCH routes go beyond the title of Spec omits 503 on PUT /locations/{locationId}/entity/{entityId}, which can wait on a lock the move holds #259 and are disclosed in the PR body as the same omission.
  • Tests-new: PASS. No production method was added. The new private helper in LockWaitBoundTest is exercised by both new tests.
  • Tests-fix: PASS for the guard only. routesThatDependOnExistingRowsDocumentTheLockTimeout was run against the unfixed spec and failed naming exactly the four routes, then passed. The two controller tests and two LockWaitBoundTest tests are characterization: the handling already existed, so they would pass without this PR.
  • Sibling structure: PASS. The guard follows routesWithValidatedInputDocumentTheirValidationFailure, and the controller tests follow moveEntityToLocation_LockWaitTimedOutIsServiceUnavailable.
  • Sibling renames: PASS. Nothing was renamed in production code.
  • Docs: PASS. README.md is updated. A search of docs/*.md, tickets.md and postman/ found one mention of this answer, tickets.md:260, which is a general rule and still true.
  • Issue resolution: PARTIAL. The spec change Spec omits 503 on PUT /locations/{locationId}/entity/{entityId}, which can wait on a lock the move holds #259 asked for is made, but its request to confirm the wait first is met only on H2. The foreign-key wait on Postgres stays unreproduced; see the table in the PR body.
  • CI: PASS on the head commit. CI runs on H2 only, so it does not verify the foreign-key wait.
  • DTO boundary: PASS. No controller changed.
  • Spec alignment: PASS. All four routes now reference the shared LockTimeout response, and the file parses as JSON.
  • Java/Python parallelism: PASS. Neither client changed. LocationService.addEntityToLocation turns a 503 into a ServiceException through its general catch, and add_entity_to_location raises through raise_for_status, as on the move route.
  • Override correctness: PASS. No @Override was added.

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 84d1dca.

Non-blocking notes:

  • src/test/java/preponderous/viron/config/LockWaitBoundTest.java — the new assertWaiterFailsWithinTheBound helper repeats the body of the two older tests. They were left alone to keep this PR small.
  • src/main/java/preponderous/viron/controllers/EntityController.java:103 — outside this diff: a rename that waits for a cascade delete and gets through after it commits updates no rows, and is answered 500 rather than 404. GridController and EnvironmentController have the same shape. This is unchanged here and could be its own issue.

The dev loop's merge hold applies because the diff touches docs/openapi/viron-api.json. Human review and the Postgres smoke test in the PR body are the remaining steps.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 96a96c4 into main Nov 6, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/document-lock-wait-503-on-writes branch November 6, 2026 15:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Spec omits 503 on PUT /locations/{locationId}/entity/{entityId}, which can wait on a lock the move holds

1 participant