* Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv)
The claim has had a wire since v0 and its inverse has had none. `bd unclaim`
is a subprocess for every client of this surface, and a release-if-current has
no route at all — so the one verb that frees stranded work is the one verb an
automation client cannot reach.
`releaseIssue` publishes issueops.Releaser whole: `actor`, the
`expected_assignee` compare-and-set, and `force`. The response carries the
issue, `changed`, and `revision` — the last for `updateIssue`'s reason, and
one of its own: a release REMINTS the row's token by design, so a caller that
guarded its next write on a version read before the release would miss, and
this member is the only place the new one exists.
THE REFUSAL CODES ARE THREE, AND ONLY ONE IS NEW.
`already_claimed` is the ownership fence — an unforced, unguarded release by
an actor that is not the holder. That is `updateIssue`'s assignee-fence
situation exactly, down to having two bypasses, so it takes that operation's
code rather than a fourth spelling of "a live foreign owner refused your
write". Like there, no `assignee` member: the fence refuses without naming the
holder, so absence means re-read the row.
`precondition_failed` is the guard, inherited from the same operation and
carrying the same members for the same reason — `expected_assignee` is the
REQUEST's value, and there is no `actual_assignee` beside it, because the
refusal rolled its transaction back and ErrAssigneeMismatch is a bare sentinel
that formats the holder it saw into prose. There is no ClaimConflictError
equivalent to read, and this surface does not scrape its own messages.
`not_releasable` is minted, covering ErrNotReleasable and ErrNotClaimed.
`not_claimable` is the nearest existing code and covers a superset of the same
statuses today, but the coincidence is not a contract — the release transition
is pinned to {open, in_progress} by releasableStatus and the claim's
eligibility is a separate predicate — and for the unheld half the reuse would
be an outright lie: an open, unassigned row is the most claimable row a
workspace has. The two conditions share ONE code with no discriminating
member, which is the narrow choice rather than the convenient one: neither
sentinel carries a typed observation, and splitting later is an ADDITION the
document already tells clients to tolerate, while merging two published codes
is the removal that breaks the wire.
IT IS NOT IDEMPOTENT, and the wire says so rather than inventing an answer the
role refused to give. An unheld row is 409, never a 200 carrying
`changed: false` — that value is one no role produces (ReleaseResult.Changed
is true on every non-error answer), and it would report one answer for "I
released this twice", "a reaper beat me to it" and "nothing ever claimed it",
because the post-state is anonymous and nothing is left on the row to tell
them apart. A client for which "already released" is the ordinary path maps
the code to success in one line it writes knowingly.
`expected_assignee` disagrees with `updateIssue`'s same-named member in
exactly one place, and the schema says so: the empty string is a 400 here
rather than a guard meaning "expected unassigned". It also documents what the
comparison ACTUALLY does — separator-insensitive over runs of `.`/`_`/`-`,
per actorMatches, and nothing else forgiven — rather than repeating the role
doc's "byte for byte", which the implementation stopped being at ga-5ksp5.
failRelease matches all four sentinels TYPED and BEFORE its ErrValidation and
ErrNotFound arms. None of them is wrapped in ErrValidation on any leg, so
below a generic arm every one would have been a 500 on every leg.
The real-Dolt leg asserts the property a fake cannot: after every refusal it
reads the row back through the CLI, so "nothing was written" — and above all
the CLAIM SURVIVING a wrong-holder refusal — is a fact about the stored row.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Fix the release document's three review findings (ga-lzcuv)
The mint stands; what the review caught is that the document was written as
though `not_releasable` meant one thing, and it means two.
THE SAFETY ONE. "A caller for which 'already released' is the ordinary path
treats that code as success" was true of the sentinel it was written against
and is FALSE of the code it shipped as. `not_releasable` also covers the
status refusal, and a row parked in a status this workspace configured is
refused WHILE STILL ASSIGNED — so a reaper following that sentence books a
claim as dropped while it stands, held by an agent that is already gone, with
nothing left to free it. That is the stranding this operation resolves ids
across both planes to prevent, reintroduced through the refusal vocabulary
instead of through the id.
It now says the opposite, in the operation description and again on the 409:
on `not_releasable`, READ THE ROW. The row carries the one fact that separates
the two — an assignee, or none. One extra request on an uncommon path is the
honest price of one code rather than two, and the handler's `detail` says so
too, since that is the string an operator actually reads.
THE ACCURACY ONE. CodeNotReleasable claimed "neither refusal is typed", which
is wrong and misleads the person who eventually splits it: ErrNotClaimed and
ErrNotReleasable are two distinct typed sentinels and failRelease holds both
in one case arm, so a split is a mapping change in that arm — no archaeology
and no prose-scraping. What is genuinely unavailable typed is the OBSERVATION
each refusal made, the status seen and the emptiness of the assignee, which is
why the code carries no extension member. That is a narrower claim than the
one the comment made, and it is the true one. The merge is recorded as what it
is: a deliberate start-narrow choice, kept because adding a code later is the
reversible direction.
THE WIDENING. The 200 now states it: the transition is defined over `open` AND
`in_progress`, so a row already open that STILL HOLDS AN ASSIGNEE is released
here — the state a partial write or an out-of-band status edit leaves behind,
and one a release-if-current guarding on `in_progress` did nothing for and
reported no error about. A client porting such a guard has to know that before
it ports one.
Beside it, the code-to-outcome mapping a release-if-current client wants, so
that mapping is written against a documented fact: `not_releasable`,
`precondition_failed`, `already_claimed` and `404` all mean "no release
happened, and that is not an error" — `(false, nil)` to a client spelling it
as a pair. With the reading that pair does NOT license, stated beside it,
because it is the same reading the safety finding is about: it means no
release happened, never that the claim is gone.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
233 lines
9.8 KiB
Go
233 lines
9.8 KiB
Go
//go:build cgo
|
|
|
|
package main
|
|
|
|
import (
|
|
"encoding/json"
|
|
"io"
|
|
"net/http"
|
|
"strings"
|
|
"testing"
|
|
)
|
|
|
|
// End-to-end for the release, against real Dolt through a real `bd serve`
|
|
// subprocess. The pure tests in internal/httpapi cover the wire edge on a fake
|
|
// role; what only this level can prove is the TRANSACTION, and here that is a
|
|
// sharper claim than usual: a REFUSED release must leave the claim STANDING.
|
|
//
|
|
// A fake role cannot show that. It reports whatever error the case handed it
|
|
// and holds no row, so a handler that refused a wrong-holder release AFTER the
|
|
// row was already emptied would look identical. This test reads the row back
|
|
// through the CLI's own path after every refusal, so "nothing was written" is
|
|
// asserted against the stored row rather than against a fake's bookkeeping.
|
|
//
|
|
// The role-level transition — what the row looks like afterwards, the dropped
|
|
// lease, the recorded event — is owned against a real store by
|
|
// internal/storage/uow/releaser_contract_test.go. This test owns the
|
|
// wire-to-role seam and cites that one rather than duplicating it.
|
|
|
|
// releaseIssue posts a release for id and returns the status and decoded body.
|
|
func (sp *serveProcess) releaseIssue(t *testing.T, id, body string) (int, map[string]any) {
|
|
t.Helper()
|
|
req, err := http.NewRequest(http.MethodPost, sp.url("/v0/beads/issues/"+id+":release"), strings.NewReader(body))
|
|
if err != nil {
|
|
t.Fatalf("new release request: %v", err)
|
|
}
|
|
req.Header.Set("Content-Type", "application/json")
|
|
resp, err := sp.client.Do(req)
|
|
if err != nil {
|
|
t.Fatalf("POST release %s: %v\nstderr:\n%s", id, err, sp.stderr.String())
|
|
}
|
|
defer func() { _ = resp.Body.Close() }()
|
|
raw, err := io.ReadAll(resp.Body)
|
|
if err != nil {
|
|
t.Fatalf("read release body: %v", err)
|
|
}
|
|
var m map[string]any
|
|
if len(raw) > 0 {
|
|
if err := json.Unmarshal(raw, &m); err != nil {
|
|
t.Fatalf("decode release body %q: %v", raw, err)
|
|
}
|
|
}
|
|
return resp.StatusCode, m
|
|
}
|
|
|
|
func TestProxiedServerServeRelease(t *testing.T) {
|
|
requireSharedProxiedServer(t)
|
|
t.Parallel()
|
|
bd := buildEmbeddedBD(t)
|
|
p := newSharedProxiedProject(t, bd, "srvrel")
|
|
sp := startServe(t, bd, p.dir, bdProxiedEnv(p.dir))
|
|
|
|
// The loop this operation completes: claim it, give it back, and see the
|
|
// row available to the next taker. The post-state is the ANONYMOUS one the
|
|
// document describes, read back through the CLI rather than off the
|
|
// response the release itself composed.
|
|
t.Run("a holder releases its own claim", func(t *testing.T) {
|
|
issue := bdProxiedCreate(t, bd, p.dir, "release over http", "-p", "1")
|
|
|
|
if status, body := sp.claim(t, issue.ID, "http-agent"); status != http.StatusOK {
|
|
t.Fatalf("claim: status = %d, want 200: %v", status, body)
|
|
}
|
|
|
|
status, body := sp.releaseIssue(t, issue.ID, `{"actor":"http-agent"}`)
|
|
if status != http.StatusOK {
|
|
t.Fatalf("release: status = %d, want 200: %v", status, body)
|
|
}
|
|
if body["changed"] != true {
|
|
t.Errorf("changed = %v, want true; the role reports it true on every answer it returns without an error", body["changed"])
|
|
}
|
|
if body["revision"] == nil {
|
|
t.Errorf("the response carries no revision; a caller composing its next expected_version has nothing to read")
|
|
}
|
|
|
|
shown := bdProxiedShow(t, bd, p.dir, issue.ID)
|
|
if string(shown.Status) != "open" || shown.Assignee != "" {
|
|
t.Fatalf("bd show reports status %q assignee %q; the HTTP release did not land",
|
|
shown.Status, shown.Assignee)
|
|
}
|
|
})
|
|
|
|
// THE GUARD SATISFIED. A supervisor that can NAME the holder releases it
|
|
// without being the holder — the fence replaced rather than bypassed.
|
|
t.Run("a satisfied expected_assignee releases another actor's claim", func(t *testing.T) {
|
|
issue := bdProxiedCreate(t, bd, p.dir, "release-if-current over http", "-p", "1")
|
|
|
|
if status, body := sp.claim(t, issue.ID, "worker-a"); status != http.StatusOK {
|
|
t.Fatalf("claim: status = %d, want 200: %v", status, body)
|
|
}
|
|
|
|
status, body := sp.releaseIssue(t, issue.ID, `{"actor":"supervisor","expected_assignee":"worker-a"}`)
|
|
if status != http.StatusOK {
|
|
t.Fatalf("guarded release: status = %d, want 200: %v", status, body)
|
|
}
|
|
shown := bdProxiedShow(t, bd, p.dir, issue.ID)
|
|
if string(shown.Status) != "open" || shown.Assignee != "" {
|
|
t.Fatalf("bd show reports status %q assignee %q; the guarded release did not land",
|
|
shown.Status, shown.Assignee)
|
|
}
|
|
})
|
|
|
|
// THE PROOF THE FAKE CANNOT GIVE. Each refusal is followed by a read of the
|
|
// stored row, so "nothing was written" is asserted rather than assumed —
|
|
// and the claim SURVIVING a wrong-holder refusal is the property the whole
|
|
// ownership fence exists for.
|
|
t.Run("a refused release leaves the claim standing", func(t *testing.T) {
|
|
issue := bdProxiedCreate(t, bd, p.dir, "refused releases over http", "-p", "1")
|
|
|
|
if status, body := sp.claim(t, issue.ID, "worker-a"); status != http.StatusOK {
|
|
t.Fatalf("claim: status = %d, want 200: %v", status, body)
|
|
}
|
|
|
|
// The fence: an unforced, unguarded release by somebody else.
|
|
status, body := sp.releaseIssue(t, issue.ID, `{"actor":"mallory"}`)
|
|
if status != http.StatusConflict {
|
|
t.Fatalf("foreign release: status = %d, want 409: %v", status, body)
|
|
}
|
|
if body["code"] != "already_claimed" {
|
|
t.Errorf("code = %v, want already_claimed", body["code"])
|
|
}
|
|
assertStillHeldBy(t, bd, p.dir, issue.ID, "worker-a", "the ownership fence")
|
|
|
|
// The guard, missed. It is a precondition_failed rather than the
|
|
// fence's code, and it echoes the REQUEST's expectation with no
|
|
// observation beside it.
|
|
status, body = sp.releaseIssue(t, issue.ID, `{"actor":"supervisor","expected_assignee":"worker-b"}`)
|
|
if status != http.StatusConflict {
|
|
t.Fatalf("stale guard: status = %d, want 409: %v", status, body)
|
|
}
|
|
if body["code"] != "precondition_failed" {
|
|
t.Errorf("code = %v, want precondition_failed", body["code"])
|
|
}
|
|
if body["expected_assignee"] != "worker-b" {
|
|
t.Errorf("expected_assignee = %v, want the value the request sent", body["expected_assignee"])
|
|
}
|
|
if _, present := body["actual_assignee"]; present {
|
|
t.Errorf("actual_assignee = %v; the role reports the holder in prose only, so this member cannot be honestly filled",
|
|
body["actual_assignee"])
|
|
}
|
|
assertStillHeldBy(t, bd, p.dir, issue.ID, "worker-a", "a missed guard")
|
|
})
|
|
|
|
// NOT IDEMPOTENT, proved against a real row: the second release of a row
|
|
// the first one emptied is a refusal, not a 200. This is the case a client
|
|
// mapping the code to "already released" is written against.
|
|
t.Run("releasing an unheld row is a refusal", func(t *testing.T) {
|
|
issue := bdProxiedCreate(t, bd, p.dir, "unheld release over http", "-p", "1")
|
|
|
|
if status, body := sp.claim(t, issue.ID, "worker-a"); status != http.StatusOK {
|
|
t.Fatalf("claim: status = %d, want 200: %v", status, body)
|
|
}
|
|
if status, body := sp.releaseIssue(t, issue.ID, `{"actor":"worker-a"}`); status != http.StatusOK {
|
|
t.Fatalf("first release: status = %d, want 200: %v", status, body)
|
|
}
|
|
|
|
status, body := sp.releaseIssue(t, issue.ID, `{"actor":"worker-a"}`)
|
|
if status != http.StatusConflict {
|
|
t.Fatalf("second release: status = %d, want 409: %v", status, body)
|
|
}
|
|
if body["code"] != "not_releasable" {
|
|
t.Errorf("code = %v, want not_releasable", body["code"])
|
|
}
|
|
// A row that was never claimed at all answers the SAME way, which is
|
|
// the anonymity the non-idempotence argument rests on: there is nothing
|
|
// left on either row to tell the two situations apart.
|
|
fresh := bdProxiedCreate(t, bd, p.dir, "never claimed", "-p", "1")
|
|
status, body = sp.releaseIssue(t, fresh.ID, `{"actor":"worker-a"}`)
|
|
if status != http.StatusConflict || body["code"] != "not_releasable" {
|
|
t.Errorf("a never-claimed row answers %d/%v; it must be indistinguishable from a re-release",
|
|
status, body["code"])
|
|
}
|
|
})
|
|
|
|
// The status half of the same code, over a row the CLI closed. `force` does
|
|
// not reach it — it answers "may I release someone else's claim", and this
|
|
// is not a question about ownership.
|
|
t.Run("a closed row refuses a release, forced or not", func(t *testing.T) {
|
|
issue := bdProxiedCreate(t, bd, p.dir, "closed release over http", "-p", "1")
|
|
|
|
if status, body := sp.claim(t, issue.ID, "worker-a"); status != http.StatusOK {
|
|
t.Fatalf("claim: status = %d, want 200: %v", status, body)
|
|
}
|
|
if status, body := sp.closeIssue(t, issue.ID, `{"actor":"worker-a","force":true}`); status != http.StatusOK {
|
|
t.Fatalf("close: status = %d, want 200: %v", status, body)
|
|
}
|
|
|
|
for _, body := range []string{`{"actor":"worker-a"}`, `{"actor":"worker-a","force":true}`} {
|
|
status, decoded := sp.releaseIssue(t, issue.ID, body)
|
|
if status != http.StatusConflict {
|
|
t.Fatalf("release of a closed row with %s: status = %d, want 409: %v", body, status, decoded)
|
|
}
|
|
if decoded["code"] != "not_releasable" {
|
|
t.Errorf("release of a closed row with %s: code = %v, want not_releasable", body, decoded["code"])
|
|
}
|
|
}
|
|
})
|
|
|
|
t.Run("an id naming nothing is a 404", func(t *testing.T) {
|
|
status, body := sp.releaseIssue(t, "bd-does-not-exist", `{"actor":"worker-a"}`)
|
|
if status != http.StatusNotFound {
|
|
t.Fatalf("status = %d, want 404: %v", status, body)
|
|
}
|
|
if body["code"] != "not_found" {
|
|
t.Errorf("code = %v, want not_found", body["code"])
|
|
}
|
|
})
|
|
}
|
|
|
|
// assertStillHeldBy reads the row through the CLI and fails unless the claim is
|
|
// intact. It is the assertion this file exists for: every refusal above is
|
|
// followed by one, because a handler that emptied the row and THEN refused
|
|
// would be indistinguishable from a correct one at the wire.
|
|
func assertStillHeldBy(t *testing.T, bd, dir, id, holder, what string) {
|
|
t.Helper()
|
|
shown := bdProxiedShow(t, bd, dir, id)
|
|
if shown.Assignee != holder {
|
|
t.Fatalf("after %s refused the release, %s is held by %q, want %q: the refusal wrote to the row",
|
|
what, id, shown.Assignee, holder)
|
|
}
|
|
if string(shown.Status) != "in_progress" {
|
|
t.Fatalf("after %s refused the release, %s has status %q, want in_progress: the refusal wrote to the row",
|
|
what, id, shown.Status)
|
|
}
|
|
}
|