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: >-