From 4bf7b4babae8e757ece338bc5540915b8b490dcc Mon Sep 17 00:00:00 2001 From: CI Bot Date: Fri, 7 Aug 2026 22:09:17 +0000 Subject: [PATCH] feat(httpapi): publish addDependencies on the v0 surface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completes the graph write side: a batch of edges asserted as ONE transaction, or none of them, over issueops.DependencyEditor. All-or-nothing is the role's shape rather than a policy choice here. Edges asserted together describe a graph, and half a graph is a graph nobody asked for — the cycle a caller was refused for is exactly the state a partial commit would leave behind. That is batchCreateIssues' posture (fix the payload, resend unchanged), not BatchCloser's keep-the-survivors one, and it is proved where a fake role cannot prove it: a batch whose later edge closes a cycle is read back through a real `bd serve` against real Dolt and leaves zero edges. Two frozen codes, both 409, both statements about state the client cannot see without reading it — the claim's not_claimable situation, so the claim's answer: dependency_cycle covers BOTH never-makes-progress refusals, the plain scheduling cycle and the blocking edge against the issue's own ancestor or descendant. One code because they have one client recovery and no force bypass, and codes are the vocabulary of recovery. The typed distinction is not lost: the hierarchy refusal additionally carries issue_id, blocker_id and blocker_is_ancestor, read from *DependencyHierarchyConflictError inside the refusing transaction, and member PRESENCE is the discriminator. The three are enough to rebuild the typed error whole, both polarities included, which is why the boolean travels through a pointer and is emitted when false. Nothing can recover them after the fact — the conflicting hierarchy may exist only inside the batch that was rolled back. dependency_exists is a pair carrying another type, with existing_type and requested_type from *DependencyTypeConflictError's fields. The endpoint refusals PR #5415 typed are mapped to their 400 and named by finding the refused edge in the request by BOTH endpoints, which is what DependencyEndpointNotFoundError carries the whole edge for. A target may legitimately be an `external:` reference or another repository's id, so only a locally-visible absence refuses; the proxied test pins both sides of that line. A self-dependency is refused at the wire edge as a value, not a conflict: it is invalid whatever the graph holds, and answering it here is what lets the refusal name the offending edge. SkipPerEdgeCycleCheck stays unpublished — an unauthenticated surface is where a default must be the guarded one. Co-Authored-By: Claude Fable --- ...e_dependencies_proxied_integration_test.go | 203 +++++++++ cmd/bd/serve_proxied_integration_test.go | 4 +- internal/httpapi/apigen/types.gen.go | 57 ++- internal/httpapi/dependency_edit.go | 304 ++++++++++++- internal/httpapi/dependency_edit_test.go | 411 ++++++++++++++++++ internal/httpapi/problem.go | 83 +++- internal/httpapi/routes.go | 11 + internal/httpapi/server_test.go | 6 +- internal/httpapi/spec/openapi.v0.yaml | 259 ++++++++++- 9 files changed, 1315 insertions(+), 23 deletions(-) diff --git a/cmd/bd/serve_dependencies_proxied_integration_test.go b/cmd/bd/serve_dependencies_proxied_integration_test.go index ac6c11403..0a4efcd9d 100644 --- a/cmd/bd/serve_dependencies_proxied_integration_test.go +++ b/cmd/bd/serve_dependencies_proxied_integration_test.go @@ -78,6 +78,209 @@ func (sp *serveProcess) removeDependency(t *testing.T, issueID, dependsOnID, act fmt.Sprintf(`{"actor":%q,"issue_id":%q,"depends_on_id":%q}`, actor, issueID, dependsOnID)) } +func (sp *serveProcess) addDependencies(t *testing.T, actor string, edges ...string) (int, map[string]any) { + t.Helper() + return sp.postJSON(t, "/v0/beads/dependencies:add", + fmt.Sprintf(`{"actor":%q,"edges":[%s]}`, actor, strings.Join(edges, ","))) +} + +func edgeJSON(issueID, dependsOnID, edgeType string) string { + return fmt.Sprintf(`{"issue_id":%q,"depends_on_id":%q,"type":%q}`, issueID, dependsOnID, edgeType) +} + +func TestProxiedServerServeAddDependencies(t *testing.T) { + requireSharedProxiedServer(t) + t.Parallel() + bd := buildEmbeddedBD(t) + p := newSharedProxiedProject(t, bd, "srvdepadd") + sp := startServe(t, bd, p.dir, bdProxiedEnv(p.dir)) + + // THE ATOMICITY PROOF, and the thing a fake role structurally cannot own. + // A batch whose LATER edge closes a cycle is refused, and the earlier edges + // — which were individually fine and really were written inside the + // transaction — must be gone when the graph is read back. A handler that + // forwarded the batch to a role committing per edge would pass every pure + // test in internal/httpapi and leave half a graph here. + t.Run("a mid-batch refusal leaves zero edges", func(t *testing.T) { + a := bdProxiedCreate(t, bd, p.dir, "atomicity a", "-p", "1") + b := bdProxiedCreate(t, bd, p.dir, "atomicity b", "-p", "1") + c := bdProxiedCreate(t, bd, p.dir, "atomicity c", "-p", "1") + + status, body := sp.addDependencies(t, "http-agent", + edgeJSON(a.ID, b.ID, "blocks"), + edgeJSON(b.ID, c.ID, "blocks"), + // The closing edge. Nothing before it is wrong; the SET is. + edgeJSON(c.ID, a.ID, "blocks"), + ) + if status != http.StatusConflict { + t.Fatalf("status = %d, want 409: %v", status, body) + } + if body["code"] != "dependency_cycle" { + t.Fatalf("code = %v, want dependency_cycle", body["code"]) + } + if body["request_id"] == nil { + t.Error("no request_id on the problem body") + } + + for _, id := range []string{a.ID, b.ID, c.ID} { + if edges := sp.storedEdges(t, id); len(edges) != 0 { + t.Errorf("the refused batch left %d edge(s) on %s: %v — the request is all-or-nothing", len(edges), id, edges) + } + } + // And the CLI reads the same empty graph through its own path. + if out := bdProxiedDep(t, bd, p.dir, "list", a.ID); strings.Contains(out, b.ID) { + t.Errorf("`bd dep list` shows an edge from the refused batch:\n%s", out) + } + }) + + t.Run("every edge of an accepted batch lands", func(t *testing.T) { + a := bdProxiedCreate(t, bd, p.dir, "batch source", "-p", "1") + b := bdProxiedCreate(t, bd, p.dir, "batch target", "-p", "1") + c := bdProxiedCreate(t, bd, p.dir, "batch other target", "-p", "1") + + status, body := sp.addDependencies(t, "http-agent", + edgeJSON(a.ID, b.ID, "blocks"), + edgeJSON(a.ID, c.ID, "related"), + ) + if status != http.StatusOK { + t.Fatalf("status = %d, want 200: %v", status, body) + } + added, ok := body["added"].([]any) + if !ok || len(added) != 2 { + t.Fatalf("added = %#v, want the two requested edges", body["added"]) + } + + stored := map[string]string{} + for _, edge := range sp.storedEdges(t, a.ID) { + target, _ := edge["depends_on_id"].(string) + edgeType, _ := edge["type"].(string) + stored[target] = edgeType + } + if stored[b.ID] != "blocks" || stored[c.ID] != "related" { + t.Errorf("the graph holds %v, want %s->blocks and %s->related", stored, b.ID, c.ID) + } + + // A same-type re-add refuses nothing and writes nothing new. + status, body = sp.addDependencies(t, "http-agent", edgeJSON(a.ID, b.ID, "blocks")) + if status != http.StatusOK { + t.Fatalf("idempotent re-add: status = %d, want 200: %v", status, body) + } + if edges := sp.storedEdges(t, a.ID); len(edges) != 2 { + t.Errorf("the re-add changed the edge count: %v", edges) + } + }) + + // The typed 409 the wire tests drive with a fabricated error, produced by + // the real role against real Dolt: the members must arrive from the + // transaction that refused, not from a fake that was told what to say. + t.Run("a retype is dependency_exists carrying both types", func(t *testing.T) { + a := bdProxiedCreate(t, bd, p.dir, "retype source", "-p", "1") + b := bdProxiedCreate(t, bd, p.dir, "retype target", "-p", "1") + if status, body := sp.addDependencies(t, "http-agent", edgeJSON(a.ID, b.ID, "related")); status != http.StatusOK { + t.Fatalf("seed: status = %d, want 200: %v", status, body) + } + + status, body := sp.addDependencies(t, "http-agent", edgeJSON(a.ID, b.ID, "blocks")) + if status != http.StatusConflict { + t.Fatalf("status = %d, want 409: %v", status, body) + } + if body["code"] != "dependency_exists" { + t.Fatalf("code = %v, want dependency_exists", body["code"]) + } + if body["existing_type"] != "related" || body["requested_type"] != "blocks" { + t.Errorf("existing/requested = %v/%v, want related/blocks — read from the typed error, not the prose", + body["existing_type"], body["requested_type"]) + } + // The stored edge is untouched. + edges := sp.storedEdges(t, a.ID) + if len(edges) != 1 || edges[0]["type"] != "related" { + t.Errorf("the refused retype changed the graph: %v", edges) + } + }) + + // The hierarchy refusal, folded into dependency_cycle and distinguished by + // the PRESENCE of its three members. Only a real store can build the + // parent-child hierarchy the role walks. + t.Run("a blocker that is an ancestor carries the hierarchy members", func(t *testing.T) { + parent := bdProxiedCreate(t, bd, p.dir, "hierarchy parent", "-p", "1") + child := bdProxiedCreate(t, bd, p.dir, "hierarchy child", "-p", "1") + bdProxiedDep(t, bd, p.dir, "add", child.ID, parent.ID, "--type", "parent-child") + + status, body := sp.addDependencies(t, "http-agent", edgeJSON(child.ID, parent.ID, "blocks")) + if status != http.StatusConflict { + t.Fatalf("status = %d, want 409: %v", status, body) + } + if body["code"] != "dependency_cycle" { + t.Fatalf("code = %v, want dependency_cycle", body["code"]) + } + if body["issue_id"] != child.ID || body["blocker_id"] != parent.ID { + t.Errorf("issue_id/blocker_id = %v/%v, want %s/%s", body["issue_id"], body["blocker_id"], child.ID, parent.ID) + } + if body["blocker_is_ancestor"] != true { + t.Errorf("blocker_is_ancestor = %v, want true — the blocker is the parent", body["blocker_is_ancestor"]) + } + }) + + // The endpoint refusal is NARROW, and only a real database can show where + // the line falls: a target this database WOULD have held and does not is a + // 400, while an id whose prefix belongs to another repository is a + // legitimate external target and is accepted. A blanket unknown-target rule + // would break every cross-repo edge, so both halves are pinned together. + t.Run("a locally-absent target is a 400 and writes nothing", func(t *testing.T) { + a := bdProxiedCreate(t, bd, p.dir, "ghost endpoint source", "-p", "2") + b := bdProxiedCreate(t, bd, p.dir, "ghost endpoint target", "-p", "2") + + status, body := sp.addDependencies(t, "http-agent", + edgeJSON(a.ID, b.ID, "blocks"), + edgeJSON(a.ID, p.prefix+"-nosuchissue", "blocks"), + ) + if status != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %v", status, body) + } + if body["code"] != "invalid_argument" { + t.Errorf("code = %v, want invalid_argument", body["code"]) + } + // The refusal names the edge it is about, found by BOTH endpoints. + if body["param"] != "edges[1].depends_on_id" { + t.Errorf("param = %v, want edges[1].depends_on_id", body["param"]) + } + if edges := sp.storedEdges(t, a.ID); len(edges) != 0 { + t.Errorf("the refused batch left edges behind: %v", edges) + } + }) + + t.Run("a ghost source is a 400 whatever its prefix", func(t *testing.T) { + b := bdProxiedCreate(t, bd, p.dir, "ghost source target", "-p", "2") + + status, body := sp.addDependencies(t, "http-agent", edgeJSON(p.prefix+"-nosuchsource", b.ID, "blocks")) + if status != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %v", status, body) + } + if body["param"] != "edges[0].issue_id" { + t.Errorf("param = %v, want edges[0].issue_id — an edge follows its source", body["param"]) + } + }) + + t.Run("an external or foreign target is accepted", func(t *testing.T) { + a := bdProxiedCreate(t, bd, p.dir, "external target source", "-p", "2") + + status, body := sp.addDependencies(t, "http-agent", + edgeJSON(a.ID, "external:JIRA-9", "blocks"), + // Another repository's namespace: this database is not the one that + // would have held it, so its absence here is not an absence. + edgeJSON(a.ID, "otherrepo-9", "related"), + ) + if status != http.StatusOK { + t.Fatalf("status = %d, want 200: %v", status, body) + } + if edges := sp.storedEdges(t, a.ID); len(edges) != 2 { + t.Errorf("the open-set targets did not land: %v", edges) + } + }) + + sp.shutdown(t) +} + func TestProxiedServerServeRemoveDependency(t *testing.T) { requireSharedProxiedServer(t) t.Parallel() diff --git a/cmd/bd/serve_proxied_integration_test.go b/cmd/bd/serve_proxied_integration_test.go index a86743a57..a83205492 100644 --- a/cmd/bd/serve_proxied_integration_test.go +++ b/cmd/bd/serve_proxied_integration_test.go @@ -144,8 +144,8 @@ func (sp *serveProcess) url(path string) string { return "http://" + sp.addr + p // package's own gates cannot catch an expectation stored as data outside it. var servedCapabilities = []any{ "config.get", "config.list", - "dependencies.blocking", "dependencies.cycles", "dependencies.list", - "dependencies.remove", "dependencies.tree", + "dependencies.add", "dependencies.blocking", "dependencies.cycles", + "dependencies.list", "dependencies.remove", "dependencies.tree", "issues.batchCreate", "issues.claim", "issues.close", "issues.delete", "issues.get", "issues.list", "issues.query", "issues.reopen", "issues.sweep", "issues.update", diff --git a/internal/httpapi/apigen/types.gen.go b/internal/httpapi/apigen/types.gen.go index d2f575dff..a2c5acd42 100644 --- a/internal/httpapi/apigen/types.gen.go +++ b/internal/httpapi/apigen/types.gen.go @@ -124,6 +124,27 @@ func (e ListReadyWorkParamsSort) Valid() bool { } } +// AddDependenciesRequest defines model for AddDependenciesRequest. +type AddDependenciesRequest struct { + // Actor Who is asserting the edges, under `ClaimRequest.actor`'s rules and for the same reasons: the server trims it, refuses an empty result, anything longer than 256 BYTES, and any control character including newline. It is attributed on each `dependency_added` event a genuinely new edge records, and interpolated into the storage commit message. + Actor string `json:"actor"` + + // Edges The edges to assert, in the caller's order. An empty array is a `400` rather than a successful no-op: a write request that writes nothing is a client bug, and answering it cheerfully is how a client whose own list filtered to nothing silently stops wiring anything. + // + // The 100-edge cap is a bound on how long one request may hold a write transaction, not a statement about batch semantics. Split a larger graph; each request is atomic on its own — but note that splitting it changes what the cycle gate can see, since the gate runs over one request at a time. + // + // A per-edge refusal names its offender as `edges[i].member`. + Edges []DependencyEdge `json:"edges"` +} + +// AddDependenciesResponse defines model for AddDependenciesResponse. +type AddDependenciesResponse struct { + // Added The request's edges, in REQUEST ORDER. It echoes the request because all-or-nothing means it is either every edge or the call failed, so a caller reporting what landed reads the result and never has to know which of the two it is safe to read. An idempotent same-type re-add is echoed like any other edge; the response does not say which edges were genuinely new, because nothing a client does depends on that. + // + // Never null and never shorter than the request: a partial outcome does not exist on this operation. + Added []DependencyEdge `json:"added"` +} + // BatchCreateDependency defines model for BatchCreateDependency. type BatchCreateDependency struct { // TargetId The far end of the edge: an issue this workspace holds, an item created earlier in the same request, an `external:` reference, or an id whose prefix belongs to another repository. Anything else is a `400` and nothing is created. @@ -243,7 +264,7 @@ type ContextResponse struct { // BeadsDir Absolute path of the served workspace's `.beads` directory. A host path, kept because it is the single-workspace server's only workspace-identity handshake; disclosing it to network peers is part of what an operator accepts when binding beyond loopback. BeadsDir string `json:"beads_dir"` - // Capabilities The operations this server actually implements, derived from its route table. v0's vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.get`, `issues.claim`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `stats.get`, `config.list`, `config.get`, `dependencies.cycles`, `dependencies.list`, `dependencies.blocking`, `dependencies.tree`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`; it grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation — never the version string. + // Capabilities The operations this server actually implements, derived from its route table. v0's vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.get`, `issues.claim`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchCreate`, `stats.get`, `config.list`, `config.get`, `dependencies.cycles`, `dependencies.list`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`; it grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation — never the version string. Capabilities []string `json:"capabilities"` // Database Logical database name (not a host or a DSN). @@ -338,6 +359,18 @@ type DeleteIssuesResult struct { // Dependency A dependency edge between two issues. type Dependency = types.Dependency +// DependencyEdge One directed edge, as a REQUEST names it. It is not `Dependency`, which is the stored row `GET /v0/beads/dependencies` returns and carries the columns storage assigned; this is the three members a caller supplies. +type DependencyEdge struct { + // DependsOnId The edge's TARGET — the issue depended upon. An exact canonical id, an `external:` reference, or an id belonging to another repository. Only an absence this database can SEE is refused. It must differ from `issue_id`. + DependsOnId string `json:"depends_on_id"` + + // IssueId The edge's SOURCE — the issue that depends on the other end. An EXACT canonical id, and one this database holds: an edge follows its source, so a source that names nothing is a `400`. + IssueId string `json:"issue_id"` + + // Type The edge type, from the same OPEN vocabulary `Dependency.type` carries: checked for being a storable value, never for membership of a known-types list, so a workspace's own type passes. + Type string `json:"type"` +} + // DependencyEdges The stored edges of the named issues, plus the ids that named nothing. It is NOT a page: this operation has no limit and no cursor, because the number of issues asked about is what bounds it. type DependencyEdges struct { // Items Every matching edge, flattened across the named issues rather than keyed by source — the same flat array `bd dep list a b c --json` emits, so the two surfaces are one compatibility domain. Group by `issue_id` to recover the per-source view. Empty array (never null) when nothing matches. @@ -467,12 +500,26 @@ type Problem struct { // Assignee With `already_claimed`: the actor currently holding the issue. Assignee *string `json:"assignee,omitempty"` - // Code The stable machine-readable reason, and the ONLY member a client may dispatch on. v0's vocabulary: `invalid_argument` (400, also emitted by the Host-header middleware on any route), `invalid_cursor` (400), `not_found` (404), `already_claimed` (409), `not_claimable` (409), `not_closable` (409), `busy` (503), `db_unavailable` (503), `internal` (500). Renaming or removing a status+code pair is a breaking change; ADDING one is not, so clients MUST default-branch on unknown values and fall back to the status class (unknown 4xx → client bug, fail loud; unknown 503 → retry per `Retry-After`; other unknown 5xx → server fault). + // BlockerId With `dependency_cycle`, hierarchy refusal only: the ancestor or descendant the edge named as blocker. See `issue_id`. + BlockerId *string `json:"blocker_id,omitempty"` + + // BlockerIsAncestor With `dependency_cycle`, hierarchy refusal only: true when `blocker_id` is an ANCESTOR of `issue_id` (which cannot close until its descendants finish, so the gate would never clear), false when it is a DESCENDANT (blocked status cascades, so it would inherit the block and never close). Both polarities are reported; this member is never omitted to mean false. See `issue_id`. + BlockerIsAncestor *bool `json:"blocker_is_ancestor,omitempty"` + + // Code The stable machine-readable reason, and the ONLY member a client may dispatch on. v0's vocabulary: `invalid_argument` (400, also emitted by the Host-header middleware on any route), `invalid_cursor` (400), `not_found` (404), `already_claimed` (409), `not_claimable` (409), `not_closable` (409), `dependency_cycle` (409), `dependency_exists` (409), `busy` (503), `db_unavailable` (503), `internal` (500). Renaming or removing a status+code pair is a breaking change; ADDING one is not, so clients MUST default-branch on unknown values and fall back to the status class (unknown 4xx → client bug, fail loud; unknown 503 → retry per `Retry-After`; other unknown 5xx → server fault). Code string `json:"code"` // Detail Optional prose, never load-bearing. For 5xx codes it is a FIXED string per code and carries nothing about the underlying failure: driver and dial errors routinely embed the DSN, database user and host:port, and this API supports binding beyond loopback. 4xx details reflect the caller's own input back and are specific. Detail *string `json:"detail,omitempty"` + // ExistingType With `dependency_exists`: the type of the edge the pair already carries, read inside the refusing transaction. + ExistingType *string `json:"existing_type,omitempty"` + + // IssueId With `dependency_cycle`, and ONLY on the hierarchy refusal: the issue the requested blocking edge would have gated. Its PRESENCE is the discriminator — absent means a plain scheduling cycle, present means the edge pointed at the issue's own ancestor or descendant. + // + // The conflicting hierarchy may exist only inside the rolled-back batch, so no read after the fact can recover it: the refusing transaction is the only place this member can come from. + IssueId *string `json:"issue_id,omitempty"` + // IssueStatus With `already_claimed` or `not_claimable`: the issue's status at the moment of refusal. IssueStatus *string `json:"issue_status,omitempty"` @@ -490,6 +537,9 @@ type Problem struct { // RequestId Opaque correlation id for this request, echoed in the server's request log line. Never a dispatch key and never a retry key. (This server mints per-process ids that do not survive a restart; a deployment may substitute any identifier with the same log-correlation property, such as an edge trace id.) RequestId string `json:"request_id"` + // RequestedType With `dependency_exists`: the type the request asked for. Together with `existing_type` it is the whole refusal, so a client never parses either out of `detail`. + RequestedType *string `json:"requested_type,omitempty"` + // Status The HTTP status code, repeated in the body. Status int `json:"status"` @@ -1059,6 +1109,9 @@ type GetStatsParams struct { SkipBlocked *bool `form:"skip_blocked,omitempty" json:"skip_blocked,omitempty"` } +// AddDependenciesJSONRequestBody defines body for AddDependencies for application/json ContentType. +type AddDependenciesJSONRequestBody = AddDependenciesRequest + // RemoveDependencyJSONRequestBody defines body for RemoveDependency for application/json ContentType. type RemoveDependencyJSONRequestBody = RemoveDependencyRequest diff --git a/internal/httpapi/dependency_edit.go b/internal/httpapi/dependency_edit.go index b9e1bcd27..26f9682cd 100644 --- a/internal/httpapi/dependency_edit.go +++ b/internal/httpapi/dependency_edit.go @@ -2,11 +2,13 @@ package httpapi import ( "encoding/json" + "errors" "fmt" "net/http" "strings" "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) @@ -24,10 +26,304 @@ import ( // gate, the hierarchy rule, the type conflict, the endpoint existence checks, // the plane routing and the event stream — belongs to the role. -// removeDependencyMembers is the document's member list for the removal. The -// schema is additionalProperties: false, so anything else is refused BY NAME, -// which is why the body is decoded as raw members first. -var removeDependencyMembers = []string{"actor", "depends_on_id", "issue_id"} +const ( + // maxAddDependencyEdges is the document's cap on `edges`. It bounds how + // long one request may hold a write transaction — not batch semantics, + // which have no size in them. + maxAddDependencyEdges = 100 + // maxAddDependenciesBodyBytes bounds the request body. A hundred edges of + // three short strings is the shape this has to admit, so it refuses the + // absurd before any of it is parsed. + maxAddDependenciesBodyBytes = 1 << 20 +) + +// The document's member lists at each level. The schemas are +// additionalProperties: false, so anything else is refused BY NAME, which is +// why the bodies are decoded as raw members first. +var ( + removeDependencyMembers = []string{"actor", "depends_on_id", "issue_id"} + addDependenciesMembers = []string{"actor", "edges"} + dependencyEdgeMembers = []string{"depends_on_id", "issue_id", "type"} +) + +// handleAddDependencies asserts every edge in the request body, or none of +// them. +// +// The all-or-nothing transaction, the parent-child-first ordering, the +// whole-graph gate, the per-edge cycle probe, the plane routing and the whole +// refusal vocabulary belong to issueops.DependencyEditor. This function decodes +// a body, refuses the shapes the document refuses, and maps the role's TYPED +// refusals onto the frozen codes. +func (s *Server) handleAddDependencies(w http.ResponseWriter, r *http.Request) { + if !s.requireNoQuery(w, r) { + return + } + if !s.requireJSONContent(w, r) { + return + } + request, ok := s.addDependenciesRequest(w, r) + if !ok { + return + } + + editor, err := s.dependencyEditor(r) + if err != nil { + s.failAddDependencies(w, r, request, err) + return + } + result, err := editor.AddDependencies(r.Context(), request) + if err != nil { + s.failAddDependencies(w, r, request, err) + return + } + writeJSON(w, apigen.AddDependenciesResponse{Added: wireRequestedEdges(result.Added)}) +} + +// addDependenciesRequest decodes and validates the body, and reports whether +// the request may proceed. Every refusal here happens before any database work, +// which is what lets these 400s reflect the caller's own input back. +func (s *Server) addDependenciesRequest(w http.ResponseWriter, r *http.Request) (issueops.AddDependenciesRequest, bool) { + members, res := decodeJSONObject(w, r, maxAddDependenciesBodyBytes) + if res != nil { + s.fail(w, r, *res) + return issueops.AddDependenciesRequest{}, false + } + if offender, unknown := unknownMember(members, addDependenciesMembers); unknown { + s.failUnknownMember(w, r, offender, addDependenciesMembers) + return issueops.AddDependenciesRequest{}, false + } + actor, ok := s.bodyActor(w, r, members) + if !ok { + return issueops.AddDependenciesRequest{}, false + } + edges, ok := s.addDependencyEdges(w, r, members) + if !ok { + return issueops.AddDependenciesRequest{}, false + } + // SkipPerEdgeCycleCheck stays UNPUBLISHED and therefore false: it trades + // validation for speed on a trusted bulk path, and an unauthenticated HTTP + // surface is where a default must be the guarded one. + return issueops.AddDependenciesRequest{Actor: actor, Edges: edges}, true +} + +// addDependencyEdges validates `edges` and projects it onto the role's edges. +func (s *Server) addDependencyEdges(w http.ResponseWriter, r *http.Request, members map[string]json.RawMessage) ([]issueops.DependencyEdge, bool) { + raw, ok := members["edges"] + if !ok { + s.fail(w, r, InvalidArgument("edges", ReasonInvalidValue, "`edges` is required")) + return nil, false + } + var rawEdges []map[string]json.RawMessage + if err := json.Unmarshal(raw, &rawEdges); err != nil || rawEdges == nil { + s.fail(w, r, InvalidArgument("edges", ReasonInvalidValue, "`edges` must be an array of objects")) + return nil, false + } + switch { + case len(rawEdges) == 0: + s.fail(w, r, InvalidArgument("edges", ReasonInvalidValue, + "`edges` must carry at least one edge; a write that writes nothing is refused rather than answered")) + return nil, false + case len(rawEdges) > maxAddDependencyEdges: + s.fail(w, r, InvalidArgument("edges", ReasonInvalidValue, + fmt.Sprintf("`edges` carries %d edges; the limit is %d per request", len(rawEdges), maxAddDependencyEdges))) + return nil, false + } + + edges := make([]issueops.DependencyEdge, 0, len(rawEdges)) + for i, rawEdge := range rawEdges { + if rawEdge == nil { + s.fail(w, r, InvalidArgument(addEdgeParam(i, ""), ReasonInvalidValue, "an edge must be a JSON object")) + return nil, false + } + if offender, unknown := unknownMember(rawEdge, dependencyEdgeMembers); unknown { + s.failUnknownMember(w, r, addEdgeParam(i, offender), dependencyEdgeMembers) + return nil, false + } + edge, res := addDependencyEdge(i, rawEdge) + if res != nil { + s.fail(w, r, *res) + return nil, false + } + edges = append(edges, edge) + } + return edges, true +} + +// addDependencyEdge projects one decoded edge onto the role's edge, or reports +// the refusal it earned. +func addDependencyEdge(index int, raw map[string]json.RawMessage) (issueops.DependencyEdge, *Result) { + issueID, res := requiredEndpointMember(raw, "issue_id") + if res != nil { + return issueops.DependencyEdge{}, indexParam(res, index) + } + dependsOnID, res := requiredEndpointMember(raw, "depends_on_id") + if res != nil { + return issueops.DependencyEdge{}, indexParam(res, index) + } + edgeType, res := requiredEdgeType(raw) + if res != nil { + return issueops.DependencyEdge{}, indexParam(res, index) + } + // The SELF-DEPENDENCY refusal is answered here rather than left to the + // role, and it is a 400 rather than a 409 because it is request-INTRINSIC: + // an edge pointing an issue at itself is invalid whatever the graph holds, + // so it is a refusal of a value. Answering it here is also what lets the + // refusal name the offending edge, which the role's request-level sentinel + // cannot. + if issueID == dependsOnID { + res := InvalidArgument(addEdgeParam(index, "depends_on_id"), ReasonInvalidValue, + "an issue cannot depend on itself") + return issueops.DependencyEdge{}, &res + } + return issueops.DependencyEdge{ + IssueID: issueID, + DependsOnID: dependsOnID, + Type: edgeType, + }, nil +} + +// requiredEdgeType reads `type` and checks that it IS a value the column can +// hold — never that it is a member of a known-types list. The edge vocabulary +// is OPEN, so a workspace's own type passes and only an unstorable one is +// refused. +func requiredEdgeType(raw map[string]json.RawMessage) (types.DependencyType, *Result) { + refuse := func(detail string) *Result { + res := InvalidArgument("type", ReasonInvalidValue, detail) + return &res + } + member, ok := raw["type"] + if !ok { + return "", refuse("`type` is required") + } + var value *string + if err := json.Unmarshal(member, &value); err != nil || value == nil { + return "", refuse("`type` must be a string") + } + edgeType := types.DependencyType(*value) + if !edgeType.IsValid() { + return "", refuse(fmt.Sprintf("`type` must be 1 to %d characters", types.MaxDependencyTypeLen)) + } + return edgeType, nil +} + +// indexParam rewrites a per-member refusal's `param` into the `edges[i].member` +// spelling, so a client dispatching on it learns WHICH edge and WHICH member. +// The member checks are shared with the removal, which has no index to add. +func indexParam(res *Result, index int) *Result { + if res.Problem.Param != nil { + indexed := addEdgeParam(index, *res.Problem.Param) + res.Problem.Param = &indexed + } + return res +} + +// addEdgeParam spells the `param` member for a refusal inside `edges`. +func addEdgeParam(index int, member string) string { + param := fmt.Sprintf("edges[%d]", index) + if member == "" { + return param + } + return param + "." + member +} + +// wireRequestedEdges projects the role's echo onto the wire, in request order. +func wireRequestedEdges(edges []issueops.DependencyEdge) []apigen.DependencyEdge { + out := make([]apigen.DependencyEdge, 0, len(edges)) + for _, edge := range edges { + out = append(out, apigen.DependencyEdge{ + IssueId: edge.IssueID, + DependsOnId: edge.DependsOnID, + Type: string(edge.Type), + }) + } + return out +} + +// failAddDependencies answers a refused assertion, adding the extension members +// each typed 409 carries. +// +// EVERY BRANCH READS THE ROLE'S TYPED FIELDS, never its prose. The two conflict +// codes exist so a client can stop substring-matching messages, and it can only +// stop if the server never does it either — the ClaimConflictError rule, +// applied to the graph. The hierarchy members in particular have no other +// source: the conflicting hierarchy may exist only inside the batch that was +// rolled back, so the refusing transaction is the only place they can come +// from. +// +// The existence refusals are 400s rather than 404s (the request BODY is what is +// wrong; there is no id in the path to have missed) and they name the offending +// edge by finding it in the request — which is exactly why +// DependencyEndpointNotFoundError carries the whole edge and not only the +// missing id. +// +// Nothing here quotes a role message: 4xx details on this surface reflect the +// caller's own input back, and the endpoint ids they name came from the request. +func (s *Server) failAddDependencies(w http.ResponseWriter, r *http.Request, request issueops.AddDependenciesRequest, err error) { + var typeConflict *issueops.DependencyTypeConflictError + var hierarchy *issueops.DependencyHierarchyConflictError + var endpoint *issueops.DependencyEndpointNotFoundError + + switch { + case errors.As(err, &typeConflict): + s.fail(w, r, newResult(CodeDependencyExists, + "this pair already carries an edge of a different type; remove it before re-adding"). + WithDependencyTypeConflict(typeConflict.ExistingType, typeConflict.RequestedType)) + + case errors.As(err, &hierarchy): + s.fail(w, r, newResult(CodeDependencyCycle, + "a blocking edge against the issue's own ancestor or descendant would never clear"). + WithHierarchyConflict(hierarchy.IssueID, hierarchy.BlockerID, hierarchy.BlockerIsAncestor)) + + case errors.Is(err, issueops.ErrDependencyCycle): + // No extension members: this is the plain scheduling cycle, and their + // ABSENCE is what tells a client which of the two refusals it got. + s.fail(w, r, newResult(CodeDependencyCycle, + "the requested edges would create a dependency cycle; nothing was written")) + + case errors.As(err, &endpoint): + s.refusedAddDependencies(r, err) + member, detail := "issue_id", "an edge's source names no issue in this workspace; nothing was written" + if errors.Is(err, issueops.ErrDependencyTargetNotFound) { + member, detail = "depends_on_id", "an edge's target names no issue this workspace can see; nothing was written" + } + s.fail(w, r, InvalidArgument(addEdgeParam(edgeIndex(request, endpoint), member), ReasonInvalidValue, detail)) + + case errors.Is(err, issueops.ErrSelfDependency): + // Unreachable while the wire edge refuses a self-edge first, and kept + // so the role's own sentinel cannot become a 500 if the two checks ever + // disagree about what "the same id" means. + s.refusedAddDependencies(r, err) + s.fail(w, r, InvalidArgument("edges", ReasonInvalidValue, "an issue cannot depend on itself")) + + case errors.Is(err, storage.ErrValidation): + s.refusedAddDependencies(r, err) + s.fail(w, r, InvalidArgument("edges", ReasonInvalidValue, + "an edge was refused by this workspace's own validation; nothing was written")) + + default: + s.failErr(w, r, err) + } +} + +// refusedAddDependencies records the real refusal for the operator. The 4xx +// path does not log by default, and the role's message is the only place the +// underlying reason survives once the response carries the server's own words. +func (s *Server) refusedAddDependencies(r *http.Request, err error) { + s.event("request_refused", "request_id", requestInfo(r.Context()).id, "error", err.Error()) +} + +// edgeIndex finds the refused edge in the request by BOTH endpoints, which is +// the only way to name it: the refusal is the request's, and a pair is what +// identifies an edge. An edge the request does not carry cannot happen, and +// answers 0 rather than inventing an index. +func edgeIndex(request issueops.AddDependenciesRequest, refused *issueops.DependencyEndpointNotFoundError) int { + for i, edge := range request.Edges { + if edge.IssueID == refused.IssueID && edge.DependsOnID == refused.DependsOnID { + return i + } + } + return 0 +} // handleRemoveDependency removes exactly the edge the body names. // diff --git a/internal/httpapi/dependency_edit_test.go b/internal/httpapi/dependency_edit_test.go index 9e055f9ce..da2d6e346 100644 --- a/internal/httpapi/dependency_edit_test.go +++ b/internal/httpapi/dependency_edit_test.go @@ -1,13 +1,17 @@ package httpapi import ( + "encoding/json" "errors" + "fmt" "net/http" + "reflect" "strings" "testing" "github.com/go-sql-driver/mysql" + "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) @@ -226,3 +230,410 @@ func TestRemoveDependencyMapsRoleFailuresThroughTheSharedClassifier(t *testing.T }) } } + +const addDependenciesPath = "/v0/beads/dependencies:add" + +// oneEdge is the smallest well-formed body, so a case that is about something +// else does not have to spell one. +const oneEdge = `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks"}]}` + +// TestAddDependenciesPathReachesItsHandler: a LITERAL collection-level custom +// method beside :remove, so a 404 here would mean the colon spelling is being +// routed as something else. +func TestAddDependenciesPathReachesItsHandler(t *testing.T) { + editor := &roleDependencyEditor{} + ts := newDependencyServer(t, editor) + + resp := ts.claim(t, addDependenciesPath, oneEdge) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + if calls := editor.addRequests(); len(calls) != 1 { + t.Fatalf("the role was called %d times, want 1 — the path reached another handler", len(calls)) + } +} + +// TestAddDependenciesForwardsEveryEdgeInRequestOrder is the operation's central +// pin: the whole edge set reaches the role in the caller's order, with the ids +// exact and the type verbatim, and the guarded cycle check left ON. +// +// It is asserted on the REQUEST rather than on the response: an echo carrying +// the right edges says nothing about which edges the role was asked to write. +func TestAddDependenciesForwardsEveryEdgeInRequestOrder(t *testing.T) { + editor := &roleDependencyEditor{} + ts := newDependencyServer(t, editor) + + resp := ts.claim(t, addDependenciesPath, `{ + "actor": " alice ", + "edges": [ + {"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks"}, + {"issue_id":"bd-3","depends_on_id":"bd-1","type":"parent-child"}, + {"issue_id":"bd-4","depends_on_id":"external:JIRA-9","type":"workspace-specific"} + ] + }`) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + + calls := editor.addRequests() + if len(calls) != 1 { + t.Fatalf("%d assertions, want 1", len(calls)) + } + want := issueops.AddDependenciesRequest{ + Actor: "alice", + Edges: []issueops.DependencyEdge{ + {IssueID: "bd-1", DependsOnID: "bd-2", Type: "blocks"}, + {IssueID: "bd-3", DependsOnID: "bd-1", Type: "parent-child"}, + // The vocabulary is OPEN, so a workspace's own type passes + // unexamined, and an `external:` target is a legitimate far end. + {IssueID: "bd-4", DependsOnID: "external:JIRA-9", Type: "workspace-specific"}, + }, + } + if !reflect.DeepEqual(calls[0], want) { + t.Errorf("request = %+v, want %+v", calls[0], want) + } + // SkipPerEdgeCycleCheck is not published, and an unauthenticated surface is + // where a default must be the guarded one. + if calls[0].SkipPerEdgeCycleCheck { + t.Error("the handler skipped the per-edge cycle check; that flag is unpublished on this surface") + } +} + +// TestAddDependenciesEchoesTheRequestedEdges: all-or-nothing means the answer +// is either every edge or a refusal, so a caller reporting what landed reads +// the RESULT — which must therefore carry the edges, in request order. +func TestAddDependenciesEchoesTheRequestedEdges(t *testing.T) { + ts := newDependencyServer(t, &roleDependencyEditor{}) + + resp := ts.claim(t, addDependenciesPath, `{ + "actor": "alice", + "edges": [ + {"issue_id":"bd-3","depends_on_id":"bd-1","type":"blocks"}, + {"issue_id":"bd-1","depends_on_id":"bd-2","type":"related"} + ] + }`) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + var body struct { + Added []map[string]any `json:"added"` + } + if err := json.Unmarshal([]byte(readAll(t, resp)), &body); err != nil { + t.Fatalf("decode response: %v", err) + } + if body.Added == nil { + t.Fatal("`added` is null; the document promises an array") + } + want := []map[string]any{ + {"issue_id": "bd-3", "depends_on_id": "bd-1", "type": "blocks"}, + {"issue_id": "bd-1", "depends_on_id": "bd-2", "type": "related"}, + } + if !reflect.DeepEqual(body.Added, want) { + t.Errorf("added = %v, want %v — the echo is in REQUEST order", body.Added, want) + } +} + +// TestAddDependenciesRefusesTheShapesTheDocumentRefuses walks the 400 +// vocabulary. Every case also asserts the role was NOT called: each is +// decidable from the request alone, so none may buy a write transaction. +func TestAddDependenciesRefusesTheShapesTheDocumentRefuses(t *testing.T) { + longID := strings.Repeat("x", types.MaxFieldLen+1) + longType := strings.Repeat("x", types.MaxDependencyTypeLen+1) + for _, test := range []struct { + name string + body string + wantParam string + }{ + {"unknown top-level member", `{"actor":"alice","edges":[],"force":true}`, "force"}, + {"no actor", `{"edges":[{"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks"}]}`, "actor"}, + {"blank actor", `{"actor":" ","edges":[{"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks"}]}`, "actor"}, + {"no edges", `{"actor":"alice"}`, "edges"}, + {"empty edges", `{"actor":"alice","edges":[]}`, "edges"}, + {"edges is not an array", `{"actor":"alice","edges":{"issue_id":"bd-1"}}`, "edges"}, + { + "unknown edge member", + `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks","weight":3}]}`, + "edges[0].weight", + }, + {"no issue_id", `{"actor":"alice","edges":[{"depends_on_id":"bd-2","type":"blocks"}]}`, "edges[0].issue_id"}, + {"empty issue_id", `{"actor":"alice","edges":[{"issue_id":"","depends_on_id":"bd-2","type":"blocks"}]}`, "edges[0].issue_id"}, + { + "over-long depends_on_id", + `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"` + longID + `","type":"blocks"}]}`, + "edges[0].depends_on_id", + }, + {"no type", `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"bd-2"}]}`, "edges[0].type"}, + {"empty type", `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"bd-2","type":""}]}`, "edges[0].type"}, + { + "unstorable type", + `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"bd-2","type":"` + longType + `"}]}`, + "edges[0].type", + }, + // Request-INTRINSIC, so a value refusal and not a conflict: the edge is + // invalid whatever the graph holds. + { + "self dependency", + `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"bd-1","type":"blocks"}]}`, + "edges[0].depends_on_id", + }, + { + "the second edge is the bad one", + `{"actor":"alice","edges":[{"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks"},` + + `{"issue_id":"bd-3","depends_on_id":"","type":"blocks"}]}`, + "edges[1].depends_on_id", + }, + } { + t.Run(test.name, func(t *testing.T) { + editor := &roleDependencyEditor{} + ts := newDependencyServer(t, editor) + + resp := ts.claim(t, addDependenciesPath, test.body) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if body["code"] != string(CodeInvalidArgument) { + t.Errorf("code = %v, want %q", body["code"], CodeInvalidArgument) + } + if body["param"] != test.wantParam { + t.Errorf("param = %v, want %q — a client dispatches on this rather than on the detail", body["param"], test.wantParam) + } + if calls := editor.addRequests(); len(calls) != 0 { + t.Errorf("the role was called %d times for a refused request; nothing may be written", len(calls)) + } + }) + } +} + +// TestAddDependenciesRefusesAnOversizeBatch pins the one size bound this +// operation owns. It bounds how long a request may hold a write transaction, so +// it is refused before the role is reached rather than after. +func TestAddDependenciesRefusesAnOversizeBatch(t *testing.T) { + editor := &roleDependencyEditor{} + ts := newDependencyServer(t, editor) + + edges := make([]string, maxAddDependencyEdges+1) + for i := range edges { + edges[i] = fmt.Sprintf(`{"issue_id":"bd-%d","depends_on_id":"bd-target","type":"blocks"}`, i) + } + resp := ts.claim(t, addDependenciesPath, `{"actor":"alice","edges":[`+strings.Join(edges, ",")+`]}`) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + if body := decodeBody(t, resp); body["param"] != "edges" { + t.Errorf("param = %v, want edges", body["param"]) + } + if calls := editor.addRequests(); len(calls) != 0 { + t.Error("the role was called for an oversize batch") + } +} + +// TestAddDependenciesRequiresTheDocumentedMediaType: the media-type refusal is +// a CSRF control, and this is the widest write on the surface to leave open. +func TestAddDependenciesRequiresTheDocumentedMediaType(t *testing.T) { + editor := &roleDependencyEditor{} + ts := newDependencyServer(t, editor) + + resp := ts.postBody(t, addDependenciesPath, "application/x-www-form-urlencoded", oneEdge) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + if body := decodeBody(t, resp); body["param"] != "Content-Type" { + t.Errorf("param = %v, want Content-Type", body["param"]) + } + if calls := editor.addRequests(); len(calls) != 0 { + t.Error("the role was called for a request with the wrong media type") + } +} + +// TestAddDependenciesTakesNoQueryParameters: the operation is in the document's +// no-parameter list, and the key chosen here is the one an optimistic client +// would reach for — the unpublished cycle-check skip. +func TestAddDependenciesTakesNoQueryParameters(t *testing.T) { + editor := &roleDependencyEditor{} + ts := newDependencyServer(t, editor) + + resp := ts.claim(t, addDependenciesPath+"?skip_cycle_check=1", oneEdge) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if body["param"] != "skip_cycle_check" || body["reason"] != string(ReasonUnknownParameter) { + t.Errorf("param/reason = %v/%v, want skip_cycle_check/%s", body["param"], body["reason"], ReasonUnknownParameter) + } + if calls := editor.addRequests(); len(calls) != 0 { + t.Error("the role was called for a request carrying a query string") + } +} + +// TestAddDependenciesMapsTheGraphsTypedRefusals is what the two new codes exist +// for. Every expectation here is read from the role's TYPED fields; a mapping +// that parsed the sentinel's prose would satisfy the status assertions and +// break the moment a message is reworded — which is exactly the coupling a +// client adopting this endpoint is being told it can delete. +func TestAddDependenciesMapsTheGraphsTypedRefusals(t *testing.T) { + cycleEdges := `{"actor":"alice","edges":[ + {"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks"}, + {"issue_id":"bd-2","depends_on_id":"bd-1","type":"blocks"} + ]}` + + for _, test := range []struct { + name string + body string + err error + wantStatus int + wantCode Code + wantMembers map[string]any + // absentMembers are the extension members this refusal must NOT carry. + // Presence is the discriminator between the two dependency_cycle + // refusals, so an over-eager mapping is a wrong answer rather than a + // verbose one. + absentMembers []string + }{ + { + name: "a plain scheduling cycle carries no hierarchy members", + body: cycleEdges, + err: fmt.Errorf("add dependencies: %w", issueops.ErrDependencyCycle), + wantStatus: http.StatusConflict, + wantCode: CodeDependencyCycle, + // ABSENCE is the signal: a client reads "no hierarchy members" as + // "this was the plain cycle". + absentMembers: []string{"issue_id", "blocker_id", "blocker_is_ancestor"}, + }, + { + name: "a blocker that is an ANCESTOR carries all three members", + body: oneEdge, + err: &issueops.DependencyHierarchyConflictError{ + IssueID: "bd-1", BlockerID: "bd-parent", BlockerIsAncestor: true, + }, + wantStatus: http.StatusConflict, + wantCode: CodeDependencyCycle, + wantMembers: map[string]any{ + "issue_id": "bd-1", "blocker_id": "bd-parent", "blocker_is_ancestor": true, + }, + }, + { + // The other polarity, and the reason the boolean travels through a + // pointer: `false` must be ON THE WIRE. An omitted member would be + // read as the plain cycle refusal, which is a different error. + name: "a blocker that is a DESCENDANT reports the false polarity", + body: oneEdge, + err: &issueops.DependencyHierarchyConflictError{ + IssueID: "bd-1", BlockerID: "bd-child", BlockerIsAncestor: false, + }, + wantStatus: http.StatusConflict, + wantCode: CodeDependencyCycle, + wantMembers: map[string]any{ + "issue_id": "bd-1", "blocker_id": "bd-child", "blocker_is_ancestor": false, + }, + }, + { + name: "a pair carrying another type is dependency_exists with both types", + body: oneEdge, + err: &issueops.DependencyTypeConflictError{ + IssueID: "bd-1", DependsOnID: "bd-2", ExistingType: "related", RequestedType: "blocks", + }, + wantStatus: http.StatusConflict, + wantCode: CodeDependencyExists, + wantMembers: map[string]any{ + "existing_type": "related", "requested_type": "blocks", + }, + absentMembers: []string{"issue_id", "blocker_id", "blocker_is_ancestor"}, + }, + { + // A 400 and not a 404: the refusal is about the request BODY, and + // there is no id in the path to have missed. + name: "a ghost source is a 400 naming that edge's issue_id", + body: oneEdge, + err: &issueops.DependencyEndpointNotFoundError{ + IssueID: "bd-1", DependsOnID: "bd-2", MissingID: "bd-1", + Err: issueops.ErrDependencySourceNotFound, + }, + wantStatus: http.StatusBadRequest, + wantCode: CodeInvalidArgument, + wantMembers: map[string]any{"param": "edges[0].issue_id"}, + }, + { + name: "a locally-absent target is a 400 naming that edge's depends_on_id", + body: oneEdge, + err: &issueops.DependencyEndpointNotFoundError{ + IssueID: "bd-1", DependsOnID: "bd-2", MissingID: "bd-2", + Err: issueops.ErrDependencyTargetNotFound, + }, + wantStatus: http.StatusBadRequest, + wantCode: CodeInvalidArgument, + wantMembers: map[string]any{"param": "edges[0].depends_on_id"}, + }, + { + name: "the role's own validation refusal is a 400 on edges", + body: oneEdge, + err: fmt.Errorf("%w: add dependencies requires a dependency type", storage.ErrValidation), + wantStatus: http.StatusBadRequest, + wantCode: CodeInvalidArgument, + wantMembers: map[string]any{"param": "edges"}, + }, + } { + t.Run(test.name, func(t *testing.T) { + ts := newDependencyServer(t, &roleDependencyEditor{addErr: test.err}) + + resp := ts.claim(t, addDependenciesPath, test.body) + if resp.StatusCode != test.wantStatus { + t.Fatalf("status = %d, want %d: %s", resp.StatusCode, test.wantStatus, readAll(t, resp)) + } + body := decodeBody(t, resp) + if body["code"] != string(test.wantCode) { + t.Fatalf("code = %v, want %q", body["code"], test.wantCode) + } + for member, want := range test.wantMembers { + got, present := body[member] + if !present { + t.Errorf("`%s` is absent; the refusal must be rebuildable from the members, not from the prose", member) + continue + } + if got != want { + t.Errorf("%s = %v, want %v", member, got, want) + } + } + for _, member := range test.absentMembers { + if _, present := body[member]; present { + t.Errorf("`%s` is present on a refusal that does not carry it; member presence is the discriminator", member) + } + } + // The role's prose is not the wire. Its type-conflict message names + // a CLI command, which is the clearest thing a leaked message would + // drag onto an HTTP surface. + if detail, _ := body["detail"].(string); strings.Contains(detail, "bd dep") { + t.Errorf("detail quotes the role's message: %q", detail) + } + }) + } +} + +// TestAddDependenciesNamesTheRefusedEdgeByBothEndpoints is why +// DependencyEndpointNotFoundError carries the whole edge rather than only the +// missing id: the refusal is the REQUEST's, so the only way to point a client +// at one of its own edges is to find it by the pair. +func TestAddDependenciesNamesTheRefusedEdgeByBothEndpoints(t *testing.T) { + refused := &issueops.DependencyEndpointNotFoundError{ + IssueID: "bd-9", DependsOnID: "bd-ghost", MissingID: "bd-ghost", + Err: issueops.ErrDependencyTargetNotFound, + } + ts := newDependencyServer(t, &roleDependencyEditor{addErr: refused}) + + resp := ts.claim(t, addDependenciesPath, `{ + "actor": "alice", + "edges": [ + {"issue_id":"bd-1","depends_on_id":"bd-2","type":"blocks"}, + {"issue_id":"bd-9","depends_on_id":"bd-2","type":"blocks"}, + {"issue_id":"bd-9","depends_on_id":"bd-ghost","type":"blocks"} + ] + }`) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + // Index 2, not index 1: both share a source, so a match on `issue_id` alone + // would name the wrong edge. + if body := decodeBody(t, resp); body["param"] != "edges[2].depends_on_id" { + t.Errorf("param = %v, want edges[2].depends_on_id", body["param"]) + } +} diff --git a/internal/httpapi/problem.go b/internal/httpapi/problem.go index d46283d50..27ef03b58 100644 --- a/internal/httpapi/problem.go +++ b/internal/httpapi/problem.go @@ -70,6 +70,18 @@ const ( // fails on state the client cannot see without reading it. That is the // not_claimable situation and it gets the not_claimable answer. CodeNotClosable Code = "not_closable" + // CodeDependencyCycle covers BOTH never-makes-progress refusals a requested + // edge set can earn: a scheduling cycle, and a blocking edge against the + // issue's own ancestor or descendant. They are one code because they have + // one client recovery — rethink the edge, with no force bypass for either — + // and codes are the vocabulary of recovery. The typed distinction is NOT + // lost: the hierarchy refusal additionally carries `issue_id`, `blocker_id` + // and `blocker_is_ancestor`, read inside the refusing transaction, and + // member presence is the discriminator. + CodeDependencyCycle Code = "dependency_cycle" + // CodeDependencyExists is the pair that already carries an edge of a + // DIFFERENT type, with both types in `existing_type`/`requested_type`. + CodeDependencyExists Code = "dependency_exists" // CodeBusy is retryable contention: the transaction retry budget was // exhausted, or the in-flight request limit was saturated. CodeBusy Code = "busy" @@ -89,15 +101,17 @@ const codeClientClosed Code = "client_closed" // codeStatus freezes one HTTP status per code. A code that could arrive with // two different statuses would defeat the point of dispatching on it. var codeStatus = map[Code]int{ - CodeInvalidArgument: http.StatusBadRequest, - CodeInvalidCursor: http.StatusBadRequest, - CodeNotFound: http.StatusNotFound, - CodeAlreadyClaimed: http.StatusConflict, - CodeNotClaimable: http.StatusConflict, - CodeNotClosable: http.StatusConflict, - CodeBusy: http.StatusServiceUnavailable, - CodeDBUnavailable: http.StatusServiceUnavailable, - CodeInternal: http.StatusInternalServerError, + CodeInvalidArgument: http.StatusBadRequest, + CodeInvalidCursor: http.StatusBadRequest, + CodeNotFound: http.StatusNotFound, + CodeAlreadyClaimed: http.StatusConflict, + CodeNotClaimable: http.StatusConflict, + CodeNotClosable: http.StatusConflict, + CodeDependencyCycle: http.StatusConflict, + CodeDependencyExists: http.StatusConflict, + CodeBusy: http.StatusServiceUnavailable, + CodeDBUnavailable: http.StatusServiceUnavailable, + CodeInternal: http.StatusInternalServerError, } // Status returns the HTTP status frozen to c, or 0 if c is not in the v0 @@ -203,6 +217,11 @@ const ( // surface, behind issueops.DependencyEditor. It names one edge by both its // endpoints, because an edge has two and neither alone identifies it. OpRemoveDependency = "removeDependency" + // OpAddDependencies is the graph's other write: a BATCH of edges asserted + // as one transaction, or none of them. It is the operation that owns both + // new conflict codes, because both are statements about the graph a + // requested edge set would produce. + OpAddDependencies = "addDependencies" // OpSweepIssues is one of the two DESTRUCTIVE operations on this surface: // bulk clearance of closed beads from one tier, behind issueops.Sweeper. OpSweepIssues = "sweepIssues" @@ -382,6 +401,22 @@ var operationCodes = map[string][]Code{ // applied to a write. No conflict code either: the removal is idempotent, so // another caller having got there first is a success rather than a collision. OpRemoveDependency: {CodeInvalidArgument, CodeBusy, CodeDBUnavailable, CodeInternal}, + // The two conflict codes are this operation's alone, and both say the same + // kind of thing: the request is fine as a request and the GRAPH refuses it, + // which the caller cannot know without reading state it does not have. That + // is the claim's not_claimable situation and it gets the claim's answer, a + // typed 409 whose extension members are read inside the refusing + // transaction. The delete's 400-for-a-graph-refusal precedent does not + // apply: that one is about request COMPLETENESS — send cascade or force — + // and neither of these has a force to send. + // + // No 404: an endpoint that names nothing is a refusal of the request BODY, + // so it joins the 400 with every other body refusal (batchCreateIssues' + // argument). Nothing was written in any of these cases. + OpAddDependencies: { + CodeInvalidArgument, CodeDependencyCycle, CodeDependencyExists, + CodeBusy, CodeDBUnavailable, CodeInternal, + }, } // Result is a problem response ready to be written: the envelope plus the @@ -420,6 +455,36 @@ func (r Result) WithOpenChildren(n int) Result { return r } +// WithDependencyTypeConflict attaches the two `dependency_exists` extension +// members: the type the pair already carries and the type the request asked +// for. Populate them from *issueops.DependencyTypeConflictError's fields — the +// typed error the role raises inside the transaction that saw the stored edge — +// never by parsing its message. +func (r Result) WithDependencyTypeConflict(existing, requested string) Result { + r.Problem.ExistingType = &existing + r.Problem.RequestedType = &requested + return r +} + +// WithHierarchyConflict attaches the three extension members that distinguish +// the HIERARCHY refusal from a plain scheduling cycle inside the one +// `dependency_cycle` code. Their PRESENCE is the discriminator, and the three +// together are enough to rebuild +// *issueops.DependencyHierarchyConflictError whole — BlockerIsAncestor in both +// polarities included, which is why the boolean travels through a pointer and +// is emitted when false. +// +// They can only come from the refusing transaction, for the reason +// ClaimConflictError's do and more so: the conflicting hierarchy may exist only +// inside the batch that was rolled back, so no read after the fact can recover +// it. +func (r Result) WithHierarchyConflict(issueID, blockerID string, blockerIsAncestor bool) Result { + r.Problem.IssueId = &issueID + r.Problem.BlockerId = &blockerID + r.Problem.BlockerIsAncestor = &blockerIsAncestor + return r +} + // WithRequestID sets the `request_id` member, the correlation id echoed in the // request log line. It is what makes a 5xx actionable: the body carries a fixed // static detail by design, so the id is the client's only handle on the one log diff --git a/internal/httpapi/routes.go b/internal/httpapi/routes.go index c3ee4d01e..bf82a64cf 100644 --- a/internal/httpapi/routes.go +++ b/internal/httpapi/routes.go @@ -360,6 +360,17 @@ var routeTable = []route{ implemented: true, handler: (*Server).handleDelete, }, + { + op: OpAddDependencies, + method: http.MethodPost, + // A collection-level custom method beside :remove below, and a LITERAL + // for the same reason: pattern and specPath agree, so no declaration is + // needed and the router registers the documented path itself. + pattern: "/v0/beads/dependencies:add", + capability: "dependencies.add", + implemented: true, + handler: (*Server).handleAddDependencies, + }, { op: OpRemoveDependency, method: http.MethodPost, diff --git a/internal/httpapi/server_test.go b/internal/httpapi/server_test.go index 560166d8c..c0f18d7cc 100644 --- a/internal/httpapi/server_test.go +++ b/internal/httpapi/server_test.go @@ -586,9 +586,9 @@ func TestCapabilitiesAdvertiseEveryImplementedOperation(t *testing.T) { got = append(got, c.(string)) } want := []string{ - "config.get", "config.list", "dependencies.blocking", "dependencies.cycles", - "dependencies.list", "dependencies.remove", "dependencies.tree", - "issues.batchCreate", + "config.get", "config.list", "dependencies.add", "dependencies.blocking", + "dependencies.cycles", "dependencies.list", "dependencies.remove", + "dependencies.tree", "issues.batchCreate", "issues.claim", "issues.close", "issues.delete", "issues.get", "issues.list", "issues.query", "issues.reopen", "issues.sweep", "issues.update", "memories.forget", "memories.get", diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index fd43f42ef..73384189d 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -60,7 +60,7 @@ info: `POST /v0/beads/issues/{id}:close`, `POST /v0/beads/issues/{id}:reopen`, `POST /v0/beads/issues:sweep`, `POST /v0/beads/issues:delete`, `GET /v0/beads/config`, - `GET /v0/beads/config/{key}`, + `GET /v0/beads/config/{key}`, `POST /v0/beads/dependencies:add`, `POST /v0/beads/dependencies:remove`) reject every query key the same way. @@ -2166,6 +2166,126 @@ paths: '503': $ref: '#/components/responses/Unavailable' + /v0/beads/dependencies:add: + post: + operationId: addDependencies + summary: Assert dependency edges as one act + description: >- + Asserts every edge in the request, or none of them. + + + IT IS ALL-OR-NOTHING, and unlike a batch close that is not a policy + choice but the shape of the question. Edges asserted together describe a + GRAPH, and half a graph is a graph nobody asked for — the cycle a caller + was refused for is exactly the state a partial commit would leave + behind. A client that gets a 4xx knows nothing was written, and can fix + its payload and resend it unchanged. There is no per-edge outcome + because there is no outcome but the request's. + + + AN EDGE IS IDEMPOTENT AT ITS OWN TYPE. A pair that already carries an + edge of the requested type refuses nothing and is still echoed in + `added`; a pair that carries a DIFFERENT type is a `409` + `dependency_exists`, whichever of the two types was stored first. + Repetition WITHIN one request answers the same way: the second + occurrence of a pair finds the first already written, and two different + types for one pair in one request is the same `409`. + + + A TARGET NEED NOT BE AN ISSUE THIS DATABASE HOLDS. An `external:` + reference and an id belonging to another repository are legitimate + targets — the vocabulary is open — so only an absence this database can + SEE is refused. A SOURCE has no such latitude: an edge follows its + source, so a source this database holds no row for has no plane to land + in. + + + Edges are applied parent-child first regardless of request order, so the + complete planned hierarchy is visible before any blocking edge is + validated against it, and a whole-graph gate runs once at the end. Both + hold ACROSS the durable and ephemeral planes: a request may mix them, + and it is still one transaction. + + + A request that wrote no genuinely new durable edge records no history + entry, and a request made entirely of wisp-sourced edges records none + either — an edge follows its source, and the wisp plane is not + versioned. Each genuinely new edge records a `dependency_added` entry on + its source's event stream, attributed to `actor`. + + + Hooks do not fire and the per-command auto-commit machinery does not + run, exactly as for `POST /v0/beads/issues/{id}:claim`. The only durable + effect is the single storage commit the role makes in its own + transaction. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AddDependenciesRequest' + responses: + '200': + description: >- + Every edge landed. `added` echoes the request's edges in request + order. + content: + application/json: + schema: + $ref: '#/components/schemas/AddDependenciesResponse' + '400': + description: >- + Invalid request: an unknown query parameter, an unparseable or + oversized body, an unknown body member at any level, an `actor` that + is empty after trimming, longer than 256 bytes or carrying control + characters, an empty or over-long `edges` array, a blank or + over-long endpoint id, an unstorable `type`, an edge that points an + issue at ITSELF, or an edge endpoint that names nothing this + database can see. Nothing is written in any of these cases. + + + A self-dependency is a `400` rather than a `409` because it is + request-intrinsic: it is invalid whatever the graph holds, so it is + a refusal of a VALUE and not a statement about state. An endpoint + that names nothing is a `400` rather than a `404` for + `POST /v0/beads/issues:batchCreate`'s reason: the refusal is about + the request BODY, and there is no id in the path to have missed. + x-bd-codes: [invalid_argument] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '409': + description: >- + The graph refuses the requested edge set, and NOTHING WAS WRITTEN. + + + `dependency_cycle` means the set can never make progress: a + scheduling cycle, or a blocking edge against the issue's own + ancestor or descendant. The hierarchy case — and ONLY the hierarchy + case — additionally carries `issue_id`, `blocker_id` and + `blocker_is_ancestor`. Member PRESENCE is the discriminator: absent + means the plain cycle refusal, present means the hierarchy one, and + the three together are enough to rebuild the refusal whole rather + than parse it out of prose. + + + `dependency_exists` means the pair already carries an edge of a + DIFFERENT type; `existing_type` and `requested_type` carry both. + + + Neither has a force bypass. The recovery for both is to rethink the + edge, which is why they are one status and not a retry. + x-bd-codes: [dependency_cycle, dependency_exists] + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + '500': + $ref: '#/components/responses/InternalError' + '503': + $ref: '#/components/responses/Unavailable' + /v0/beads/dependencies:remove: post: operationId: removeDependency @@ -3571,7 +3691,7 @@ components: `issues.sweep`, `issues.delete`, `issues.batchCreate`, `stats.get`, `config.list`, `config.get`, `dependencies.cycles`, `dependencies.list`, `dependencies.blocking`, `dependencies.tree`, - `dependencies.remove`, + `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`; it grows additively, and an operation never @@ -4422,6 +4542,101 @@ components: items: $ref: '#/components/schemas/Issue' + AddDependenciesRequest: + type: object + additionalProperties: false + required: [actor, edges] + properties: + actor: + type: string + minLength: 1 + maxLength: 256 + pattern: '^[^\u0000-\u001F\u007F-\u009F\u2028\u2029]+$' + description: >- + Who is asserting the edges, under `ClaimRequest.actor`'s rules and + for the same reasons: the server trims it, refuses an empty result, + anything longer than 256 BYTES, and any control character including + newline. It is attributed on each `dependency_added` event a + genuinely new edge records, and interpolated into the storage commit + message. + edges: + type: array + minItems: 1 + maxItems: 100 + description: >- + The edges to assert, in the caller's order. An empty array is a + `400` rather than a successful no-op: a write request that writes + nothing is a client bug, and answering it cheerfully is how a client + whose own list filtered to nothing silently stops wiring anything. + + + The 100-edge cap is a bound on how long one request may hold a write + transaction, not a statement about batch semantics. Split a larger + graph; each request is atomic on its own — but note that splitting + it changes what the cycle gate can see, since the gate runs over one + request at a time. + + + A per-edge refusal names its offender as `edges[i].member`. + items: + $ref: '#/components/schemas/DependencyEdge' + + DependencyEdge: + type: object + additionalProperties: false + required: [issue_id, depends_on_id, type] + description: >- + One directed edge, as a REQUEST names it. It is not `Dependency`, which + is the stored row `GET /v0/beads/dependencies` returns and carries the + columns storage assigned; this is the three members a caller supplies. + properties: + issue_id: + type: string + minLength: 1 + maxLength: 255 + description: >- + The edge's SOURCE — the issue that depends on the other end. An + EXACT canonical id, and one this database holds: an edge follows its + source, so a source that names nothing is a `400`. + depends_on_id: + type: string + minLength: 1 + maxLength: 255 + description: >- + The edge's TARGET — the issue depended upon. An exact canonical id, + an `external:` reference, or an id belonging to another repository. + Only an absence this database can SEE is refused. It must differ + from `issue_id`. + type: + type: string + minLength: 1 + maxLength: 255 + description: >- + The edge type, from the same OPEN vocabulary `Dependency.type` + carries: checked for being a storable value, never for membership of + a known-types list, so a workspace's own type passes. + + AddDependenciesResponse: + type: object + required: [added] + properties: + added: + type: array + description: >- + The request's edges, in REQUEST ORDER. It echoes the request because + all-or-nothing means it is either every edge or the call failed, so + a caller reporting what landed reads the result and never has to + know which of the two it is safe to read. An idempotent same-type + re-add is echoed like any other edge; the response does not say + which edges were genuinely new, because nothing a client does + depends on that. + + + Never null and never shorter than the request: a partial outcome + does not exist on this operation. + items: + $ref: '#/components/schemas/DependencyEdge' + RemoveDependencyRequest: type: object additionalProperties: false @@ -4752,7 +4967,8 @@ components: may dispatch on. v0's vocabulary: `invalid_argument` (400, also emitted by the Host-header middleware on any route), `invalid_cursor` (400), `not_found` (404), `already_claimed` (409), - `not_claimable` (409), `not_closable` (409), `busy` (503), + `not_claimable` (409), `not_closable` (409), + `dependency_cycle` (409), `dependency_exists` (409), `busy` (503), `db_unavailable` (503), `internal` (500). Renaming or removing a status+code pair is a breaking change; ADDING one is not, so clients MUST default-branch @@ -4805,6 +5021,43 @@ components: `not_closable` refusal is a live blocker and carries no such member, so member presence — not prose — is how a client tells the two apart. Both are bypassed by `force`. + existing_type: + type: string + description: >- + With `dependency_exists`: the type of the edge the pair already + carries, read inside the refusing transaction. + requested_type: + type: string + description: >- + With `dependency_exists`: the type the request asked for. Together + with `existing_type` it is the whole refusal, so a client never + parses either out of `detail`. + issue_id: + type: string + description: >- + With `dependency_cycle`, and ONLY on the hierarchy refusal: the + issue the requested blocking edge would have gated. Its PRESENCE is + the discriminator — absent means a plain scheduling cycle, present + means the edge pointed at the issue's own ancestor or descendant. + + + The conflicting hierarchy may exist only inside the rolled-back + batch, so no read after the fact can recover it: the refusing + transaction is the only place this member can come from. + blocker_id: + type: string + description: >- + With `dependency_cycle`, hierarchy refusal only: the ancestor or + descendant the edge named as blocker. See `issue_id`. + blocker_is_ancestor: + type: boolean + description: >- + With `dependency_cycle`, hierarchy refusal only: true when + `blocker_id` is an ANCESTOR of `issue_id` (which cannot close until + its descendants finish, so the gate would never clear), false when + it is a DESCENDANT (blocked status cascades, so it would inherit the + block and never close). Both polarities are reported; this member is + never omitted to mean false. See `issue_id`. request_id: type: string description: >-