* feat(list): bd list --no-assignee, --title and --id over http behind per-parameter tokens (S15b) Over http `bd list --no-assignee`, `--title` and `--id` refused: the list encoder had no listIssues parameter for ListRequest.NoAssignee, TitleSearch or IDFilter (B3 #11). All three are maintainer-city cutover blockers: gc's default on_boot hook runs `bd list --no-assignee --status=in_progress ...` on every agent boot, the PR-intake formula lists by `--title "$SUBJECT"`, and the pr-review skill by `--id <ids>`. The library entry is unchanged: issueops.Reader.List, whose bodies already apply all three through workapi.BuildListFilter, the same entry the local route reads through. - Server: GET /v0/beads/issues decodes `no_assignee`, `title` and `id` into those ListRequest members (`id` handed over as written; the role splits, trims and de-duplicates, as countIssues already does). Each is behind its own new behavior token, issues.list.noAssignee, issues.list.title and issues.list.id (additive, wire_revision stays 2): each is a separate caller's dependency, and a refusal names exactly the one it needed. The spec parameters cite their tokens; apigen and the wire-shape golden are regenerated. - Client: the encoder maps the three members to their parameters, and httpReader.List refuses a request carrying one BEFORE dialing, with ErrUnsupported{Capability: <token>}, unless the handshake advertises that token (refuseUnservedSearch generalised to one table, tokenedListFilters, with bd search's `q`). Never a round trip an older server answers unknown_parameter, never a wider listing. - ErrHTTPUnsupported's text names the capability when it has one, as the portable sentinel does, so `bd list` says which token the server lacks. - The three E-ListRequest ledger rows retire; the ledger is re-rendered. The id scope unparks the served Reader contract: the sixteen cases parked on E-ListRequest.IDFilter now run against the in-process server. Twelve pass as written; four still park, each now on the member it actually needs (Offset twice, PinnedFlag, ExcludeTypes). The served refusal sweep asserts SpecPrefix where it asserted IDFilter. Tests (failing first): handler test that each parameter reaches the storage filter; client tests that each member rides its parameter behind its token and refuses pre-dial, zero dials, naming its token, against a server lacking it; round-trip and vocabulary gates; capability lists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(backend/http): the four maintainer-city list shapes end to end; corpus marks relabelled SRV-1 (S15b) TestE2E_ListScopeFiltersOverHTTP runs the corpus shapes gc-list-on-boot, gc-list-on-boot-workflow, mc-list-title and mc-list-id through the real bd against the in-process server (which advertises the three new tokens) and requires each to answer an embedded workspace's rows and exactly the rows it names: --no-assignee leaves out an assigned in-progress row on the same lane, --title is case-insensitive, --id lists a closed id under --all. Against the MC production server's handshake shape each shape exits non-zero naming its token and never dials listIssues. The corpus suite masks the served side to reference_server.json, the deployed bd 1.3.0 surface, which advertises none of the tokens, so the four shapes now get the named pre-dial refusal there. Their marks move from S6c+S15b to SRV-1 with that reason, like mc-search. With a scratch profile that adds the three tokens and parameters (not committed) exactly these four shapes report "now passes; remove the pending mark" and nothing else changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(list): adopt bd-enterprise's listIssues `id` contract: repeatable, issues.list.ids (S15b) bd-enterprise already publishes listIssues `id` (E9-S2): a REPEATABLE parameter, one id per value, behind `issues.list.ids`, with its client sending IDFilter split into one value per member. The first cut of S15b took ONE comma-separated `id` behind `issues.list.id`, so the same parameter name had two incompatible meanings: an OSS client's "a,b" is a 400 on an enterprise server, and the enterprise rebase onto main would collide. OSS now publishes enterprise's contract unchanged: - Server: listIDFilter (ported verbatim) decodes the repeated `id` into ListRequest.IDFilter's comma set; more than 200 values, an empty value, a comma, leading or trailing whitespace, a control character or an over-long id is a 400 `invalid_argument` on `id`. The spec parameter is enterprise's (array, maxItems 200); apigen and the wireshape golden are regenerated. - Token: CapListIDs = "issues.list.ids", the enterprise spelling and name on both sides. - Client: the encoder splits the set the way the role does (splitIDSet) and sends one `id` per member; the pre-dial gate fires only when the set names an id. - Tests: list_ids_test.go is enterprise's id cases (the exact set reaches storage, the 200 bound is served, every refusal beside its control, the spec bound matches the constant); the handler, client, round-trip and e2e cases move to the repeated shape and the new token. `no_assignee` and `title` are unchanged. Served tier, http e2e (including TestE2E_ListScopeFiltersOverHTTP) and corpus_served_test pass; with a scratch reference profile advertising the three tokens exactly the four S15b shapes report "now passes". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
718 lines
28 KiB
Go
718 lines
28 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"fmt"
|
|
"net/http"
|
|
"strings"
|
|
|
|
"github.com/steveyegge/beads/internal/httpapi/apigen"
|
|
"github.com/steveyegge/beads/internal/types"
|
|
"github.com/steveyegge/beads/issueops"
|
|
)
|
|
|
|
// The issue-collection reads. Each one decodes its parameters, hands the whole
|
|
// request to a role, and shapes the answer onto the wire. Three are on
|
|
// issueops.Reader (ready, list, detail); the count and the query are on
|
|
// ReadyCounter and Querier, siblings reached the same way through the same
|
|
// provider accessors. What follows is about the Reader three, and holds for
|
|
// the other two in every respect but which role they name.
|
|
//
|
|
// WHAT IS NOT HERE IS THE POINT. No filter is built, no ConfigSource is wired,
|
|
// no default limit is applied, no status exclusion is chosen, no wisp fallback
|
|
// is arranged: all of that is inside issueops.Reader's implementation, which
|
|
// `bd show --json` reaches through the same accessor. A handler that skipped a
|
|
// step of that construction — which is exactly how a hosted viewer once shipped
|
|
// a bare IssueFilter and silently served in_progress rows as "ready" — is not
|
|
// writable from here.
|
|
//
|
|
// That is a MACHINE claim, not a convention, and it takes two rules because
|
|
// there are two ways to build a filter. The depguard rule
|
|
// httpapi-transport-boundary denies internal/workapi from this package's
|
|
// non-test files, so the builders are not importable here at all. That alone
|
|
// would leave the door the hosted viewer actually walked through: it did not
|
|
// misuse a builder, it hand-rolled `IssueFilter{}` — and internal/types is
|
|
// reachable from here, for CheckFieldLen and IssueWithCounts below. So the
|
|
// forbidigo rule in .golangci.yml denies NAMING types.IssueFilter or
|
|
// types.WorkFilter in this package at all — every file of it, so a file added
|
|
// here tomorrow is covered the moment it exists. Both rules run in
|
|
// `make ci-pr-lint`, which the PR workflow runs on every pull request and
|
|
// aggregates into its ci-gate job; what that gate is and is not worth as
|
|
// enforcement is stated once, in doc.go.
|
|
//
|
|
// `bd ready` and `bd list` still call the builders directly, for the reasons
|
|
// issueops.Reader's doc comment sets out. They are not unguarded for it: they
|
|
// build from the same request types through the same builders, and they run
|
|
// the same workapi.FinishPage epilogue the reader below runs — `bd list` in
|
|
// every mode but the hierarchical --parent tree, `bd ready` on its proxied
|
|
// route only. Where both hold, what a CLI listing and one of these bodies can
|
|
// differ by is presentation, not the query and not the page. `bd show --json`
|
|
// is on the role outright, on both its routes.
|
|
//
|
|
// What DOES stay here is transport: parameter decoding, the opaque cursor
|
|
// codec, the bind-mode refusal of an unlimited read, and the wire envelopes.
|
|
|
|
// handleReady answers GET /v0/beads/ready.
|
|
func (s *Server) handleReady(w http.ResponseWriter, r *http.Request) {
|
|
q := newQuery(r.URL.Query())
|
|
|
|
req := readyFilters(q)
|
|
|
|
// EXPLICIT, always. The storage layer maps an EMPTY sort policy to hybrid,
|
|
// and forwarding an absent `sort` as "" would silently adopt that fallback
|
|
// while the document still read `default: priority`. It is not a cosmetic
|
|
// difference: hybrid demotes older high-priority work, so the item SET
|
|
// changes as soon as `limit` truncates — and only for the clients this API
|
|
// exists to migrate off `bd ready`, whose flag registers a concrete default
|
|
// and never sends empty.
|
|
req.Sort = q.oneOf("sort", readySortDefault, "hybrid", "priority", "oldest")
|
|
req.Limit = q.limit()
|
|
// Decoded here and not in readyFilters, which is the vocabulary the count
|
|
// shares: this is a projection of the rows a page returns, in the same
|
|
// class as the two lines above it, and the count returns no rows to project.
|
|
req.Brief = q.boolean("brief")
|
|
|
|
if !s.acceptQuery(w, r, q) {
|
|
return
|
|
}
|
|
if !s.allowUnlimited(w, r, req.Limit) {
|
|
return
|
|
}
|
|
|
|
rd, err := s.reader(r)
|
|
if err != nil {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
page, err := rd.Ready(r.Context(), req)
|
|
if err != nil {
|
|
s.failReadErr(w, r, err)
|
|
return
|
|
}
|
|
writeJSON(w, apigen.ReadyPage{
|
|
Items: wireItems(page.Items),
|
|
HasMore: page.HasMore,
|
|
})
|
|
}
|
|
|
|
// readyFilters decodes the ready-work filter vocabulary the two ready
|
|
// operations share — everything except the PAGE, which only the listing has,
|
|
// and the ORDER, which only the listing needs.
|
|
//
|
|
// It is one function because the two operations must admit exactly the same
|
|
// filters: countReadyWork answers with the size of the set listReadyWork
|
|
// returns, and a parameter one of them decoded and the other did not would
|
|
// make that identity false for any client that sent it.
|
|
func readyFilters(q *query) issueops.ReadyRequest {
|
|
return issueops.ReadyRequest{
|
|
Assignee: q.str("assignee"),
|
|
Unassigned: q.boolean("unassigned"),
|
|
IssueType: q.str("type"),
|
|
ExcludeTypes: q.list("exclude_type"),
|
|
|
|
Labels: q.list("label"),
|
|
LabelsAny: q.list("label_any"),
|
|
ExcludeLabels: q.list("exclude_label"),
|
|
LabelPattern: q.str("label_pattern"),
|
|
LabelRegex: q.str("label_regex"),
|
|
|
|
Priority: q.integer("priority"),
|
|
ParentID: q.str("parent"),
|
|
|
|
MetadataFields: q.metadataFields("metadata_field"),
|
|
HasMetadataKey: q.str("has_metadata_key"),
|
|
|
|
IncludeEphemeral: q.boolean("include_ephemeral"),
|
|
IncludeDeferred: q.boolean("include_deferred"),
|
|
}
|
|
}
|
|
|
|
// handleCountReady answers GET /v0/beads/ready:count.
|
|
//
|
|
// THE REQUEST IS THE LISTING'S REQUEST with the page taken off, which is what
|
|
// makes the answer the size of the page the listing would return. It is not
|
|
// assembled here beyond that: the role refuses a Limit and an Offset itself
|
|
// (issueops.ReadyCounter.CountReady), so this handler could not smuggle a
|
|
// bounded count past it even if a parameter for one existed.
|
|
//
|
|
// THE SORT IS SENT ANYWAY, and the operation publishes no parameter for it. A
|
|
// count has no order, but the request still has to be one the builder accepts,
|
|
// and sending "" would adopt the storage layer's hybrid fallback that no front
|
|
// door relies on.
|
|
func (s *Server) handleCountReady(w http.ResponseWriter, r *http.Request) {
|
|
q := newQuery(r.URL.Query())
|
|
|
|
req := readyFilters(q)
|
|
req.Sort = readySortDefault
|
|
|
|
if !s.acceptQuery(w, r, q) {
|
|
return
|
|
}
|
|
|
|
counter, err := s.readyCounter(r)
|
|
if err != nil {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
result, err := counter.CountReady(r.Context(), req)
|
|
if err != nil {
|
|
s.failReadErr(w, r, err)
|
|
return
|
|
}
|
|
writeJSON(w, apigen.ReadyCount{Total: result.Total})
|
|
}
|
|
|
|
// readySortDefault is the ordering this operation applies when `sort` is
|
|
// absent. It is the same value `bd ready --sort` registers.
|
|
//
|
|
// Three things have to agree: the frozen document, the CLI flag, and this.
|
|
// TestDefaultsMatchCLIFlags compares all three against each other and
|
|
// TestReadyForwardsAnExplicitSortPolicy asserts the LITERAL "priority" on the
|
|
// filter the handler built — deliberately not this constant, because an
|
|
// assertion against the value the handler itself read would hold for every
|
|
// value it could take.
|
|
const readySortDefault = "priority"
|
|
|
|
// countFilters decodes the count's predicate: every filter the role publishes
|
|
// and nothing about a page, an order or a bucket.
|
|
//
|
|
// It is a function of its own for readyFilters' reason turned inside out. That
|
|
// one is shared because two operations must admit the same parameters; this one
|
|
// has a single caller, and it is split off so a test can drive it over an empty
|
|
// query and read back the EXACT set of names this handler asks for
|
|
// (query.read). That is what makes the parameter-parity check mechanical rather
|
|
// than a second hand-rolled list beside the document's.
|
|
func countFilters(q *query) issueops.CountRequest {
|
|
return issueops.CountRequest{
|
|
// ONE status, not the listing's comma-separated OR set. The role says so
|
|
// and the document says so; reading it with q.csv here would publish a
|
|
// set the role would answer 0 for.
|
|
Status: q.str("status"),
|
|
IssueType: q.str("type"),
|
|
Assignee: q.str("assignee"),
|
|
|
|
Priority: q.integer("priority"),
|
|
PriorityMin: q.integer("priority_min"),
|
|
PriorityMax: q.integer("priority_max"),
|
|
|
|
Labels: q.list("label"),
|
|
LabelsAny: q.list("label_any"),
|
|
|
|
TitleSearch: q.str("title"),
|
|
// A COMMA-SEPARATED string, handed over as written: the role splits,
|
|
// trims and de-duplicates it, and a handler that pre-split it would be
|
|
// deciding what an id set means.
|
|
IDFilter: q.str("id"),
|
|
|
|
TitleContains: q.str("title_contains"),
|
|
DescContains: q.str("desc_contains"),
|
|
NotesContains: q.str("notes_contains"),
|
|
|
|
CreatedAfter: q.timestamp("created_after"),
|
|
CreatedBefore: q.timestamp("created_before"),
|
|
UpdatedAfter: q.timestamp("updated_after"),
|
|
UpdatedBefore: q.timestamp("updated_before"),
|
|
ClosedAfter: q.timestamp("closed_after"),
|
|
ClosedBefore: q.timestamp("closed_before"),
|
|
|
|
EmptyDesc: q.boolean("empty_description"),
|
|
NoAssignee: q.boolean("no_assignee"),
|
|
NoLabels: q.boolean("no_labels"),
|
|
MetadataFields: q.metadataFields("metadata_field"),
|
|
HasMetadataKey: q.str("has_metadata_key"),
|
|
|
|
// The plane switches, each forwarded as the boolean the caller sent.
|
|
// What include_infra MEANS — merge the wisps tier, drop templates, drop
|
|
// gates, and route an infra type to the ephemeral tier — is four
|
|
// decisions the role makes from the WORKSPACE's own infra vocabulary,
|
|
// which is a config load this handler must never perform.
|
|
IncludeInfra: q.boolean("include_infra"),
|
|
// include_ephemeral is the first of those four and none of the rest, so
|
|
// it reaches the role as its own field and never as IncludeInfra: folded
|
|
// into it, a plane-only count would also lose its templates and gates.
|
|
IncludeEphemeral: q.boolean("include_ephemeral"),
|
|
|
|
// The four scope fields behind `issues.count.scope` (S8): ParentID and
|
|
// ExcludeTypes are read exactly as the listing reads them (q.str("parent"),
|
|
// q.list("exclude_type")), because the role documents its own ParentID and
|
|
// ExcludeTypes as spelling ListRequest's fields identically. NoParent and
|
|
// ExcludeStatus have no listing counterpart to mirror — NoParent is a new
|
|
// boolean switch and ExcludeStatus is a Count-only capability the listing
|
|
// never exposed — so both are read with this file's own conventions for
|
|
// their kind (q.boolean, q.list) rather than a listing precedent.
|
|
ParentID: q.str("parent"),
|
|
NoParent: q.boolean("no_parent"),
|
|
ExcludeTypes: q.list("exclude_type"),
|
|
ExcludeStatus: q.list("exclude_status"),
|
|
}
|
|
}
|
|
|
|
// countGroupOf reads the bucketing dimension and reports whether one was asked
|
|
// for.
|
|
//
|
|
// PRESENCE is the signal, which is why this returns a boolean beside the value:
|
|
// an absent `group_by` selects the scalar method, and q.oneOf's fallback alone
|
|
// would collapse "no bucketing asked for" into a dimension. An unknown value is
|
|
// refused HERE rather than at the role, so the 400 names the parameter — the
|
|
// role's own rule (an unknown dimension is ErrValidation, never an empty
|
|
// answer) with the member name a client dispatches on added.
|
|
func countGroupOf(q *query) (issueops.CountGroup, bool) {
|
|
grouped := q.has("group_by")
|
|
return issueops.CountGroup(q.oneOf("group_by", "", countGroupNames()...)), grouped
|
|
}
|
|
|
|
// countGroups is the closed dimension vocabulary, in the document's order, so
|
|
// the schema's enum and the values this server accepts are one list read twice
|
|
// rather than two lists kept in step by hand.
|
|
//
|
|
// It is spelled with the ROLE's constants rather than as bare strings: the wire
|
|
// names and issueops.CountGroup's values are the same strings today, and
|
|
// deriving one from the other is what keeps them the same tomorrow.
|
|
var countGroups = []issueops.CountGroup{
|
|
issueops.CountGroupStatus,
|
|
issueops.CountGroupPriority,
|
|
issueops.CountGroupType,
|
|
issueops.CountGroupAssignee,
|
|
issueops.CountGroupLabel,
|
|
}
|
|
|
|
// countGroupNames is countGroups as the strings q.oneOf compares against.
|
|
func countGroupNames() []string {
|
|
names := make([]string, len(countGroups))
|
|
for i, g := range countGroups {
|
|
names[i] = string(g)
|
|
}
|
|
return names
|
|
}
|
|
|
|
// handleCountIssues answers GET /v0/beads/issues:count.
|
|
//
|
|
// ONE HANDLER FOR BOTH OF THE ROLE'S METHODS, because `group_by` chooses
|
|
// between two shapes of one answer rather than between two questions: the same
|
|
// predicate over the same set, differing only in whether the reply is one
|
|
// number or a number per bucket. The grouped result carries the scalar total
|
|
// itself, which is why splitting them would have put one role's promise inside
|
|
// the other's result.
|
|
//
|
|
// WHAT IS NOT HERE is this file's whole point, and on a count it is more than
|
|
// usual. No filter is built, no ConfigSource is wired, and the workspace's
|
|
// INFRA VOCABULARY is never read — that config load is precisely what
|
|
// issueops.Counter exists to keep off a front door.
|
|
//
|
|
// The default answer is the ROLE's too, and it is NOT the listing's: an empty
|
|
// request counts every durable row including closed, pinned, template and gate
|
|
// ones. A handler that "helpfully" applied the listing's exclusions would be
|
|
// answering a different question with the same parameters.
|
|
func (s *Server) handleCountIssues(w http.ResponseWriter, r *http.Request) {
|
|
q := newQuery(r.URL.Query())
|
|
|
|
req := countFilters(q)
|
|
group, grouped := countGroupOf(q)
|
|
|
|
if !s.acceptQuery(w, r, q) {
|
|
return
|
|
}
|
|
|
|
counter, err := s.counter(r)
|
|
if err != nil {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
if grouped {
|
|
// THE SAME PREDICATE reaches both methods, which is the identity the
|
|
// role promises: a grouped count is a scalar count plus a dimension, so
|
|
// the two cannot be asked of different sets.
|
|
result, err := counter.CountByGroup(r.Context(), issueops.CountByGroupRequest{Filter: req, GroupBy: group})
|
|
if err != nil {
|
|
s.failReadErr(w, r, err)
|
|
return
|
|
}
|
|
// `groups` is PRESENT because the request asked for buckets, even when
|
|
// the answer has none: an empty object means "nothing matched" and an
|
|
// absent member means "you did not ask", and a client must be able to
|
|
// tell those apart without re-reading its own request. The role promises
|
|
// a non-nil map; this does not lean on that promise, because a nil map
|
|
// would marshal as `{}` anyway and leaning on it would make the
|
|
// difference invisible if it ever broke.
|
|
groups := result.Groups
|
|
if groups == nil {
|
|
groups = map[string]int{}
|
|
}
|
|
writeJSON(w, apigen.IssueCount{Total: result.Total, Groups: &groups})
|
|
return
|
|
}
|
|
result, err := counter.Count(r.Context(), req)
|
|
if err != nil {
|
|
s.failReadErr(w, r, err)
|
|
return
|
|
}
|
|
writeJSON(w, apigen.IssueCount{Total: result.Total})
|
|
}
|
|
|
|
// handleListIssues answers GET /v0/beads/issues.
|
|
func (s *Server) handleListIssues(w http.ResponseWriter, r *http.Request) {
|
|
q := newQuery(r.URL.Query())
|
|
|
|
req := issueops.ListRequest{
|
|
Status: q.csv("status"),
|
|
IssueType: q.str("type"),
|
|
Assignee: q.str("assignee"),
|
|
// `bd list --no-assignee`, behind issues.list.noAssignee
|
|
// (CapIssuesListNoAssignee).
|
|
NoAssignee: q.boolean("no_assignee"),
|
|
|
|
Labels: q.list("label"),
|
|
LabelsAny: q.list("label_any"),
|
|
ExcludeLabels: q.list("exclude_label"),
|
|
|
|
ParentID: q.str("parent"),
|
|
|
|
// `bd list --title`, behind issues.list.title (CapIssuesListTitle).
|
|
TitleSearch: q.str("title"),
|
|
// `bd list --id`, behind issues.list.ids (CapListIDs). The id scope
|
|
// arrives as a repeated parameter and reaches the role as the
|
|
// comma-separated set issueops.ListRequest.IDFilter is. The join is
|
|
// lossless only because listIDFilter refuses a comma inside a value.
|
|
IDFilter: listIDFilter(q),
|
|
|
|
Brief: q.boolean("brief"),
|
|
AllFlag: q.boolean("all"),
|
|
IncludeTemplates: q.boolean("include_templates"),
|
|
IncludeGates: q.boolean("include_gates"),
|
|
IncludeInfra: q.boolean("include_infra"),
|
|
IncludeEphemeral: q.boolean("include_ephemeral"),
|
|
|
|
CreatedBefore: q.timestamp("created_before"),
|
|
CreatedAfter: q.timestamp("created_after"),
|
|
|
|
MetadataFields: q.metadataFields("metadata_field"),
|
|
HasMetadataKey: q.str("has_metadata_key"),
|
|
|
|
// `bd search`'s text, behind issues.list.search (CapIssuesListSearch).
|
|
Query: q.str("q"),
|
|
|
|
Limit: q.limit(),
|
|
}
|
|
|
|
// THE ORDER AND THE CURSOR ARE ONE DECISION. Each served order is a keyset
|
|
// contract — its own position shape and its own strictly-after predicate —
|
|
// so `sort` selects the ORDER BY and, with it, what a position means. The
|
|
// vocabulary is closed for that reason and not for tidiness: the seven
|
|
// other orders `bd list --sort` takes have no proven total key (mutable,
|
|
// nullable, or not expressible in SQL at all), and serving one behind a
|
|
// cursor would page a walk that skips and repeats rows.
|
|
//
|
|
// SortBy takes the wire value verbatim, which is safe only because the two
|
|
// vocabularies coincide by construction: sqlbuild.SortDefs already spells
|
|
// these orders `created` and `priority`, and `priority` there is exactly
|
|
// (priority ASC, created_at DESC, id ASC) — `bd list`'s flagless order.
|
|
order := listOrder(q.oneOf("sort", string(listOrderDefault), listOrders...))
|
|
req.SortBy = string(order)
|
|
|
|
token := q.str("cursor")
|
|
|
|
if !s.acceptQuery(w, r, q) {
|
|
return
|
|
}
|
|
if token != "" {
|
|
// Decoded AGAINST the order this request asked for. A token minted in
|
|
// the other order is refused rather than reinterpreted: its instant and
|
|
// its id would decode perfectly and mean something else, which is a
|
|
// skipped-and-duplicated page served with a 200.
|
|
pos, ok := decodeCursor(token, order)
|
|
if !ok {
|
|
requestInfo(r.Context()).refuse(token)
|
|
s.fail(w, r, InvalidCursor())
|
|
return
|
|
}
|
|
req.AfterCreatedAt = &pos.CreatedAt
|
|
req.AfterID = pos.ID
|
|
req.AfterPriority = pos.Priority
|
|
}
|
|
if !s.allowUnlimited(w, r, req.Limit) {
|
|
return
|
|
}
|
|
|
|
rd, err := s.reader(r)
|
|
if err != nil {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
page, err := rd.List(r.Context(), req)
|
|
if err != nil {
|
|
s.failReadErr(w, r, err)
|
|
return
|
|
}
|
|
|
|
body := apigen.IssuesPage{
|
|
Items: wireItems(page.Items),
|
|
HasMore: page.HasMore,
|
|
}
|
|
if page.HasMore {
|
|
// Present if and only if has_more, which the document states as a
|
|
// biconditional: a client that sees one and not the other has no way
|
|
// to know whether paging is finished.
|
|
// Minted in the order this page was SERVED in, so the token a client
|
|
// hands back is a position the next request can only be read against
|
|
// the same way.
|
|
if next := cursorFor(page.Items, order); next != "" {
|
|
body.NextCursor = &next
|
|
}
|
|
}
|
|
writeJSON(w, body)
|
|
}
|
|
|
|
// maxListIDs bounds listIssues' repeatable `id` filter. It is the spec's
|
|
// `maxItems`, and TestListIDsBoundMatchesTheSpec holds the two together.
|
|
const maxListIDs = 200
|
|
|
|
// listIDFilter decodes listIssues' repeatable `id` filter into the comma-separated
|
|
// set issueops.ListRequest.IDFilter takes. The contract is bd-enterprise's
|
|
// (E9-S2), adopted unchanged.
|
|
//
|
|
// Every value is bounded the way a path id is (customMethodTarget): longer than
|
|
// the column holds, or carrying a control character, names no row that can
|
|
// exist. Unlike the path, a malformed value here is a 400 naming `id` rather
|
|
// than a 404 — there is no single resource to be missing — and two more shapes
|
|
// are refused because of what the role does with the joined set: a COMMA,
|
|
// because the role splits the set on commas and a value carrying one would
|
|
// silently address two ids the caller never named; and LEADING OR TRAILING
|
|
// WHITESPACE, because the role trims every member, so a padded value would
|
|
// silently address the trimmed id — a different one from the id named.
|
|
func listIDFilter(q *query) string {
|
|
vals := q.list("id")
|
|
if len(vals) == 0 {
|
|
return ""
|
|
}
|
|
if len(vals) > maxListIDs {
|
|
q.invalid("id", fmt.Sprintf("at most %d id values per request; got %d", maxListIDs, len(vals)))
|
|
return ""
|
|
}
|
|
for _, id := range vals {
|
|
switch {
|
|
case strings.TrimSpace(id) == "":
|
|
q.invalid("id", "an id value is empty")
|
|
return ""
|
|
case strings.Contains(id, ","):
|
|
q.invalid("id", fmt.Sprintf("%q carries a comma; repeat the parameter once per id instead", id))
|
|
return ""
|
|
case strings.ContainsFunc(id, isControlChar):
|
|
q.invalid("id", "an id value carries a control character")
|
|
return ""
|
|
case strings.TrimSpace(id) != id:
|
|
q.invalid("id", fmt.Sprintf("%q has leading or trailing whitespace; send the canonical id", id))
|
|
return ""
|
|
case types.CheckFieldLen("id", id) != nil:
|
|
q.invalid("id", fmt.Sprintf("an id value is longer than %d characters", types.MaxFieldLen))
|
|
return ""
|
|
}
|
|
}
|
|
return strings.Join(vals, ",")
|
|
}
|
|
|
|
// handleQueryIssues answers GET /v0/beads/issues:query.
|
|
//
|
|
// The EXPRESSION IS NOT PARSED HERE. Parsing, evaluation, the predicate
|
|
// decision and the scan bound all live inside the role, so this handler cannot
|
|
// make the truncating one: it reads five parameters and hands the sentence
|
|
// over.
|
|
func (s *Server) handleQueryIssues(w http.ResponseWriter, r *http.Request) {
|
|
q := newQuery(r.URL.Query())
|
|
|
|
req := issueops.QueryRequest{
|
|
Expression: q.str("q"),
|
|
IncludeClosed: q.boolean("all"),
|
|
SortBy: q.oneOf("sort", "", querySorts...),
|
|
Reverse: q.boolean("reverse"),
|
|
Limit: q.limit(),
|
|
// No Offset. The document publishes no parameter for one, because the
|
|
// two database sources this server can be built on disagree about
|
|
// whether they can honor it — see issueops.QueryRequest.Offset.
|
|
}
|
|
|
|
if !s.acceptQuery(w, r, q) {
|
|
return
|
|
}
|
|
if !s.allowUnlimited(w, r, req.Limit) {
|
|
return
|
|
}
|
|
|
|
qr, err := s.querier(r)
|
|
if err != nil {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
page, err := qr.Query(r.Context(), req)
|
|
if err != nil {
|
|
s.failReadErr(w, r, err)
|
|
return
|
|
}
|
|
writeJSON(w, apigen.QueryPage{
|
|
Items: wireItems(page.Items),
|
|
HasMore: page.HasMore,
|
|
})
|
|
}
|
|
|
|
// querySorts is the display-order vocabulary this operation publishes, in the
|
|
// document's order. It is the set workapi.CompareIssuesBy can order by; a value
|
|
// outside it is refused here rather than accepted and ignored, because a page
|
|
// returned unordered under a sort the caller named is indistinguishable from
|
|
// one whose order the caller does not understand.
|
|
var querySorts = []string{"priority", "created", "updated", "closed", "status", "id", "title", "type", "assignee"}
|
|
|
|
// handleGetIssue answers GET /v0/beads/issues/{id}.
|
|
func (s *Server) handleGetIssue(w http.ResponseWriter, r *http.Request) {
|
|
q := newQuery(r.URL.Query())
|
|
|
|
// Both default off, so a request that names neither builds the request this
|
|
// handler built when the operation had no parameters at all.
|
|
req := issueops.GetRequest{
|
|
IncludeComments: q.boolean("include_comments"),
|
|
IncludeDependents: q.boolean("include_dependents"),
|
|
BriefDeps: q.boolean("brief_deps"),
|
|
}
|
|
|
|
// Before the id bound, which is the order this operation had when
|
|
// requireNoQuery ran first: a refused query string is a 400 that names what
|
|
// to fix, and deciding the id first would answer it with a 404 instead.
|
|
if !s.acceptQuery(w, r, q) {
|
|
return
|
|
}
|
|
id := r.PathValue("id")
|
|
|
|
// The id is bounded HERE, before the request buys a concurrency slot and a
|
|
// database round trip, exactly as the claim route bounds its own. The
|
|
// column is VARCHAR(255) and the document calls this an exact canonical
|
|
// id, so a longer one — or one carrying a control character, which a
|
|
// percent-escape in the path decodes to — names no row that can exist.
|
|
// The refusal is the SAME 404 a real miss gets: a distinct answer would
|
|
// let a caller map this server's notion of a well-formed id, and there is
|
|
// nothing to learn from it.
|
|
if id == "" || types.CheckFieldLen("id", id) != nil || strings.ContainsFunc(id, isControlChar) {
|
|
s.fail(w, r, NotFound())
|
|
return
|
|
}
|
|
|
|
req.ID = id
|
|
|
|
rd, err := s.reader(r)
|
|
if err != nil {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
details, err := rd.Get(r.Context(), req)
|
|
if err != nil {
|
|
s.failReadErr(w, r, err)
|
|
return
|
|
}
|
|
writeJSON(w, *details)
|
|
}
|
|
|
|
// acceptQuery answers a refused query string and reports whether the request
|
|
// may proceed.
|
|
func (s *Server) acceptQuery(w http.ResponseWriter, r *http.Request, q *query) bool {
|
|
res := q.result()
|
|
if res == nil {
|
|
return true
|
|
}
|
|
requestInfo(r.Context()).refuse(res.offender())
|
|
s.fail(w, r, *res)
|
|
return false
|
|
}
|
|
|
|
// allowUnlimited enforces the one mode-dependent refusal on this surface: an
|
|
// unlimited read buffers the whole active set and its JSON encoding inside one
|
|
// shared process, which must not be reachable by arbitrary network peers.
|
|
//
|
|
// The bind mode is deliberately NOT advertised in ContextResponse. A client
|
|
// that wants an unlimited read asks for one and, on this 400, re-issues with
|
|
// an explicit limit; it is a client-side fix, never a retry.
|
|
func (s *Server) allowUnlimited(w http.ResponseWriter, r *http.Request, limit *int) bool {
|
|
if !s.cfg.AllowNonLoopback || limit == nil || *limit != 0 {
|
|
return true
|
|
}
|
|
requestInfo(r.Context()).refuse("0")
|
|
s.fail(w, r, InvalidArgument("limit", ReasonInvalidValue,
|
|
"unlimited reads are loopback-only; pass an explicit limit"))
|
|
return false
|
|
}
|
|
|
|
// failReadErr answers a failed read. It exists so that a filter-construction
|
|
// refusal — an unknown status, an issue type outside the workspace vocabulary,
|
|
// an invalid metadata key — reaches the client as the 400 it is rather than as
|
|
// a 500, while every storage failure keeps going through the one mapping in
|
|
// problem.go.
|
|
//
|
|
// The builders are the authority on what those messages say (the CLI prints
|
|
// them verbatim), so the detail is the builder's own text: it reflects the
|
|
// caller's own input back, which is what a 4xx detail is for.
|
|
func (s *Server) failReadErr(w http.ResponseWriter, r *http.Request, err error) {
|
|
if param, ok := invalidFilterParam(err); ok {
|
|
requestInfo(r.Context()).refuse(param)
|
|
s.fail(w, r, InvalidArgument(param, ReasonInvalidValue, err.Error()))
|
|
return
|
|
}
|
|
s.failErr(w, r, err)
|
|
}
|
|
|
|
// invalidFilterParam maps a filter-construction failure back to the query
|
|
// parameter that caused it.
|
|
//
|
|
// It matches on the builder's message prefixes, and that is a deliberate,
|
|
// bounded exception to this package's "never classify by prose" rule: these
|
|
// are THIS repository's own error strings, not a foreign library's. The
|
|
// alternative — typed errors for each — is the right end state and is a change
|
|
// to internal/workapi, not to the wire. A message that stops matching degrades
|
|
// to a 500, which is loud, rather than to a wrong 400.
|
|
//
|
|
// Every row here is driven end to end by a case in
|
|
// TestABuilderRefusalIsTheDocumentedBadRequest, so a reworded builder message
|
|
// fails a test rather than silently demoting its parameter to a 500. That
|
|
// test IS the pin: the builders' golden files record successful filters only,
|
|
// and cannot see a message at all.
|
|
func invalidFilterParam(err error) (string, bool) {
|
|
msg := err.Error()
|
|
switch {
|
|
case strings.HasPrefix(msg, "invalid status "):
|
|
return "status", true
|
|
// The count role's own refusals (S8 review fix): a misspelled
|
|
// --exclude-status entry, and --parent set together with --no-parent.
|
|
// Both are the ROLE's ErrValidation. They are named here the same way as
|
|
// the `status` row above and the metadata-key rows below, so the client
|
|
// learns which parameter to fix rather than reading an unclassified 500.
|
|
case strings.HasPrefix(msg, "invalid exclude-status "):
|
|
return "exclude_status", true
|
|
case strings.HasPrefix(msg, "--parent and --no-parent are mutually exclusive"):
|
|
return "no_parent", true
|
|
case strings.HasPrefix(msg, "invalid issue type "):
|
|
return "type", true
|
|
case strings.HasPrefix(msg, "invalid sort policy "):
|
|
return "sort", true
|
|
case strings.HasPrefix(msg, "invalid metadata field key"):
|
|
return "metadata_field", true
|
|
case strings.HasPrefix(msg, "invalid metadata key filter"):
|
|
return "has_metadata_key", true
|
|
// The query role's refusal. It is the caller's SENTENCE being wrong, which
|
|
// is a 400 on `q` rather than the 500 an unclassified error would give.
|
|
case strings.HasPrefix(msg, "invalid query expression"):
|
|
return "q", true
|
|
}
|
|
return "", false
|
|
}
|
|
|
|
// wireItems projects the reader's page onto the generated envelope's element
|
|
// type.
|
|
//
|
|
// The element type is an ALIAS of types.IssueWithCounts — the same struct the
|
|
// CLI's --json marshals — so this copies a header and shares everything under
|
|
// it. There is no second wire struct here and there must never be one: that is
|
|
// what keeps `bd list --json` and this body one compatibility domain.
|
|
func wireItems(items []*types.IssueWithCounts) []apigen.IssueWithCounts {
|
|
out := make([]apigen.IssueWithCounts, 0, len(items))
|
|
for _, item := range items {
|
|
if item == nil {
|
|
continue
|
|
}
|
|
out = append(out, *item)
|
|
}
|
|
return out
|
|
}
|