beads/internal/httpclient/encode/encode.go
Julian Knutsen e6a891b900
feat(list): bd list --no-assignee, --title and --id over http behind per-parameter tokens (S15b) (#7550)
* 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>
2026-10-14 00:18:00 +00:00

826 lines
30 KiB
Go

// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/encode.go@49d1df2f6)
// to OSS beads under the MIT license.
// Package encode turns the read requests bd's storage roles take into v0 query
// parameters, and refuses — never drops — everything the wire cannot carry.
//
// It is the client half of internal/httpapi's parameter decoding, and it is a
// separate package from the wire transport for one reason: the decision it
// makes is a POLICY decision, not a transport one. Dropping a filter widens a
// result set invisibly, and the server can only reject parameters it receives,
// so a filter the encoder silently forgets is a wrong answer no gate on either
// side can observe. Everything in here exists to make that impossible:
//
// - the encoder table (table.go) classifies every field of every request
// shape, and the bijection gate checks it against reflection over the
// structs, against the OpenAPI document, and against these encoders;
// - divergence ledger v1 (ledger.go, ledger_fields.go) carries the reason and
// the citation for every field that cannot make the crossing, and a refusal
// is raised BY ledger id so a refusal with no row cannot be written;
// - the refusal checks themselves are TABLE-DRIVEN rather than hand-rolled,
// so an encoder and its table cannot disagree about what refuses. What
// stays hand-written is the value rendering, which is exactly what the
// round-trip gate drives through the server's own decoder.
//
// The refusal taxonomy, the role dispositions and refuse-not-drop
// enumeration, id resolution and MaxRows all trace back to the original
// (bd-enterprise-internal) design's decision log; the divergence ledger
// itself (D9 there) is reproduced in-repo at
// engdocs/design/http-divergence-ledger.md, generated from ledger.go below.
package encode
import (
"errors"
"fmt"
"net/url"
"reflect"
"sort"
"strconv"
"strings"
"time"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// MaxExactIDs bounds the exact-ids fan-out of the SearchIssues bridge: an
// IssueFilter naming more ids than this refuses rather than issuing an
// unbounded burst of getIssue calls at one server (D11; the number itself is
// open question 6, to be measured against real call-site fan-out before GA).
const MaxExactIDs = 100
// ErrRefused matches every refusal this package raises, so a caller that only
// needs to know "the wire cannot express this" does not have to reach for the
// concrete type.
var ErrRefused = errors.New("not expressible on the v0 wire")
// RefusedError is the typed refusal: the operation being encoded for, and the
// divergence-ledger row that says what was refused, why, which decision it
// comes from and what pins it.
//
// It deliberately carries no server URL and no flag rendering. D7's three
// refusal texts are the CLI's to write — they speak the user's vocabulary and
// need the target and the server's version — and the row here is what supplies
// the flag name and the reason they read back.
type RefusedError struct {
Op Op
Shape string
Row Row
}
func (e *RefusedError) Error() string {
subject := e.Row.Flag
if subject == "" && e.Row.Type != nil {
subject = e.Row.Type.Name() + "." + e.Row.Field
}
if subject == "" {
// A row about a COMBINATION of fields has no single subject; its What
// is already the sentence.
return fmt.Sprintf("%s: %s (%s; %s)", e.Op, e.Row.What, e.Row.Why, e.Row.SpecRow)
}
return fmt.Sprintf("%s: %s is %s (%s; %s)", e.Op, subject, ErrRefused, e.Row.Why, e.Row.SpecRow)
}
func (e *RefusedError) Is(target error) bool { return target == ErrRefused }
// Encoded is what one request becomes.
type Encoded struct {
// Params is the query string, empty rather than nil for a request that
// names no parameter.
Params url.Values
// PathIDs are the ids a path-shaped encoding dials, one request each: the
// getIssue id, or the exact-ids fan-out of the SearchIssues bridge.
PathIDs []string
}
// Encode routes one source value to the encoder for an operation and shape.
//
// It exists so the gates can drive every table uniformly. Ordinary callers know
// which request they hold and use the typed functions below.
func Encode(op Op, shape string, source any) (Encoded, error) {
switch (opShape{op, shape}) {
case opShape{OpListReadyWork, ""}:
return encodeAs(op, shape, source, ReadyParams)
case opShape{OpCountReadyWork, ""}:
return encodeAs(op, shape, source, ReadyCountParams)
case opShape{OpListIssues, ""}:
return encodeAs(op, shape, source, ListParams)
case opShape{OpQueryIssues, ""}:
return encodeAs(op, shape, source, QueryParams)
case opShape{OpCountIssues, ""}:
return encodeAs(op, shape, source, CountParams)
case opShape{OpCountIssues, "byGroup"}:
return encodeAs(op, shape, source, CountByGroupParams)
case opShape{OpListReadyWork, "workFilterBridge"}:
return encodeAs(op, shape, source, ReadyBridgeParams)
case opShape{OpGetIssue, ""}:
return encodeGetIssue(op, shape, source)
case opShape{OpGetIssue, "searchExactIDs"}, opShape{OpListIssues, "searchParentWalk"}:
return encodeSearch(op, shape, source)
}
return Encoded{}, fmt.Errorf("encode: no encoder for operation %q shape %q", op, shape)
}
// opShape is the (operation, shape) pair Encode dispatches on.
type opShape struct {
op Op
shape string
}
// encodeGetIssue is Encode's arm for getIssue: GetTarget's id is the one path
// id the request dials.
func encodeGetIssue(op Op, shape string, source any) (Encoded, error) {
req, err := sourceAs[issueops.GetRequest](op, shape, source)
if err != nil {
return Encoded{}, err
}
id, v := GetTarget(req)
return Encoded{Params: v, PathIDs: []string{id}}, nil
}
// encodeSearch is Encode's arm for the two SearchIssues bridge shapes: it plans
// the filter and refuses one that plans to the other shape.
func encodeSearch(op Op, shape string, source any) (Encoded, error) {
filter, err := sourceAs[types.IssueFilter](op, shape, source)
if err != nil {
return Encoded{}, err
}
// The zero vocabulary, which is what a gate driving the table has: it
// falls back to the built-in statuses and the default infra types, the
// same reading BuildListFilter gives an unconfigured workspace.
plan, err := PlanSearch(filter, ZeroVocabulary)
if err != nil {
return Encoded{}, err
}
if string(plan.Shape) != shape {
return Encoded{}, fmt.Errorf("encode: the filter is the %q shape, not %q", plan.Shape, shape)
}
return Encoded{Params: plan.Params, PathIDs: plan.IDs}, nil
}
func encodeAs[T any](op Op, shape string, source any, encoder func(T) (url.Values, error)) (Encoded, error) {
req, err := sourceAs[T](op, shape, source)
if err != nil {
return Encoded{}, err
}
v, err := encoder(req)
if err != nil {
return Encoded{}, err
}
return Encoded{Params: v}, nil
}
func sourceAs[T any](op Op, shape string, source any) (T, error) {
req, ok := source.(T)
if !ok {
return req, fmt.Errorf("encode: operation %q shape %q takes a %T, got %T", op, shape, req, source)
}
return req, nil
}
// ReadyParams encodes a ready-work listing onto GET /v0/beads/ready.
func ReadyParams(req issueops.ReadyRequest) (url.Values, error) {
b := newBuilder(OpListReadyWork, "")
b.refuseInexpressible(req)
b.readyFilters(req)
b.boolean("brief", req.Brief)
b.str("sort", readySort(req.Sort))
b.intPtr("limit", req.Limit)
return b.done()
}
// ClaimNextParams encodes a ClaimNext ready request onto the QUERY STRING of
// POST /v0/beads/issues:claimNext.
//
// IT BUILDS AGAINST listReadyWork's TABLE, which is not laziness about a missing
// one: the claim's filter IS that listing's filter, decoded server-side by the
// same function, and giving this operation a table of its own would be a second
// declaration of one vocabulary — the exact drift the table gate exists to
// prevent. So the refusal walk, the fifteen filter parameters and the sort
// policy all come from readyTable, and what differs is what is NOT emitted.
//
// TWO PARAMETERS ARE WITHHELD and neither absence is one the server would
// forgive. `limit` is refused BY VALUE on this operation, with any value at all
// — the scan has to stay unbounded or a window of rows a racing agent already
// took would report nothing to claim while other ready work waits. `brief` has
// no spelling here, because the claim refetches its winner whole rather than
// reading it through the page's query, so the projection would have nothing to
// apply to and would answer a MUTATING request with a row saying it got
// everything. The ROLE refuses both before this encoder is reached
// (ValidateClaimNextRequest); this is the second line, and it is the one that
// holds if a caller ever reaches the encoder another way.
//
// The SORT is sent explicitly, always, exactly as the listing sends it — an
// absent `sort` is `priority` to the handler and `hybrid` to the storage layer,
// and here that difference decides WHICH ROW IS WRITTEN rather than what order
// rows are printed in.
func ClaimNextParams(req issueops.ReadyRequest) (url.Values, error) {
b := newBuilder(OpListReadyWork, "")
b.refuseInexpressible(req)
b.readyFilters(req)
b.str("sort", readySort(req.Sort))
return b.done()
}
// metadataFieldList renders the metadata equality filter as the wire's repeated
// `key=value` member, in key order — b.metadata's rule, so the object and the
// query produce the same set.
func metadataFieldList(fields map[string]string) []string {
if len(fields) == 0 {
return nil
}
keys := make([]string, 0, len(fields))
for key := range fields {
keys = append(keys, key)
}
sort.Strings(keys)
out := make([]string, 0, len(fields))
for _, key := range keys {
out = append(out, key+"="+fields[key])
}
return out
}
func boolPtr(b bool) *bool { return &b }
// strSlicePtr returns a pointer to a copy of values, or nil for an empty slice.
// An empty-but-non-nil slice constrains nothing, so it is sent as absent — the
// same reading populated() gives it on the refusal walk.
func strSlicePtr(values []string) *[]string {
if len(values) == 0 {
return nil
}
out := append([]string(nil), values...)
return &out
}
// ReadyCountParams encodes a ready-work COUNT onto GET /v0/beads/ready:count.
//
// It sends the listing's filters and nothing else: the operation publishes no
// order and no page, and the role refuses both itself.
func ReadyCountParams(req issueops.ReadyRequest) (url.Values, error) {
b := newBuilder(OpCountReadyWork, "")
b.refuseInexpressible(req)
b.readyFilters(req)
return b.done()
}
// readySort resolves the policy actually sent.
//
// An EMPTY policy is sent as the concrete `hybrid` it means, never omitted.
// Omitting it would adopt the server's own `priority` default while the caller
// meant the storage layer's hybrid fallback, and those two answer with
// different item SETS as soon as a limit truncates — the silent kind of
// divergence this package exists to make impossible.
func readySort(policy string) string {
if policy == "" {
return "hybrid"
}
return policy
}
// ListParams encodes an issue listing onto GET /v0/beads/issues.
//
// It emits no `cursor` and no `sort`: the cursor is the server's to mint and
// the pager's to echo, and the order is welded to created order on the wire —
// see the listIssues table for both.
func ListParams(req issueops.ListRequest) (url.Values, error) {
b := newBuilder(OpListIssues, "")
b.refuseInexpressible(req)
b.str("status", req.Status)
b.str("type", req.IssueType)
b.str("assignee", req.Assignee)
b.boolean("no_assignee", req.NoAssignee)
b.list("label", req.Labels)
b.list("label_any", req.LabelsAny)
b.list("exclude_label", req.ExcludeLabels)
b.str("parent", req.ParentID)
b.str("q", req.Query)
b.str("title", req.TitleSearch)
b.list("id", splitIDSet(req.IDFilter))
b.boolean("all", req.AllFlag)
b.boolean("include_templates", req.IncludeTemplates)
b.boolean("include_gates", req.IncludeGates)
b.boolean("include_infra", req.IncludeInfra)
b.boolean("include_ephemeral", req.IncludeEphemeral)
b.timestamp("created_before", req.CreatedBefore)
b.timestamp("created_after", req.CreatedAfter)
b.metadata(req.MetadataFields)
b.str("has_metadata_key", req.HasMetadataKey)
b.boolean("brief", req.Brief)
b.intPtr("limit", req.Limit)
return b.done()
}
// splitIDSet reads ListRequest.IDFilter's comma-separated set the way the role
// does (workapi.BuildListFilter: split on commas, trim, drop empties and
// repeats) and hands back one member per listIssues `id` value, which is the
// repeatable shape the server takes (issues.list.ids). A set naming no id
// sends no `id` at all.
func splitIDSet(set string) []string {
if set == "" {
return nil
}
var out []string
seen := map[string]bool{}
for _, id := range strings.Split(set, ",") {
id = strings.TrimSpace(id)
if id == "" || seen[id] {
continue
}
seen[id] = true
out = append(out, id)
}
return out
}
// QueryParams encodes a boolean-expression query onto
// GET /v0/beads/issues:query.
func QueryParams(req issueops.QueryRequest) (url.Values, error) {
b := newBuilder(OpQueryIssues, "")
b.refuseInexpressible(req)
b.str("q", req.Expression)
b.boolean("all", req.IncludeClosed)
b.str("sort", req.SortBy)
b.boolean("reverse", req.Reverse)
b.intPtr("limit", req.Limit)
return b.done()
}
// CountParams encodes an issue count onto GET /v0/beads/issues:count.
//
// It sends the predicate and nothing else — there is no page, no order and no
// projection on this operation, because a cardinality has none — and it refuses
// nothing, because the operation publishes every member of the request. The
// refusal walk still runs: it is what turns a member added upstream tomorrow
// into a failure here rather than into a silently narrower predicate behind an
// unchanged-looking number.
func CountParams(req issueops.CountRequest) (url.Values, error) {
b := newBuilder(OpCountIssues, "")
b.refuseInexpressible(req)
b.countFilters(req)
return b.done()
}
// CountByGroupParams encodes a bucketed count onto the same operation.
//
// The predicate is the SCALAR encoder's, called rather than copied: the two
// methods must ask the same question of the same set, and two builders would be
// two chances to disagree about that.
//
// A dimension that is there travels VERBATIM, unrecognized ones included: the
// closed vocabulary is the ROLE's rule at every backend, refused by the role
// client before it ever reaches here — and the server refuses it too, naming
// the parameter. What this layer must not do is drop one: a group_by that went
// missing would earn a scalar answer with no `groups` member at all, which the
// caller reads as "no buckets" rather than as an error.
//
// An EMPTY dimension is the one value that does not travel, and it is not a
// drop — it is the absence itself, which no parameter can spell. Nothing
// reaches this function with one: the role client refuses an empty GroupBy with
// the unrecognized ones, for exactly the reason above. The emptiness check is
// what keeps `group_by=` off the query of a caller who came through some other
// door.
func CountByGroupParams(req issueops.CountByGroupRequest) (url.Values, error) {
v, err := CountParams(req.Filter)
if err != nil {
return nil, err
}
if req.GroupBy != "" {
v.Set("group_by", string(req.GroupBy))
}
return v, nil
}
// countFilters emits the count's whole vocabulary, which is every member of the
// request.
//
// It is spelled beside readyFilters and in the count table's order, so the
// three statements about this operation — the table, this emitter and the
// server's own countFilters decode — read as one list three times rather than
// as three lists.
func (b *builder) countFilters(req issueops.CountRequest) {
b.str("status", req.Status)
b.str("type", req.IssueType)
b.str("assignee", req.Assignee)
b.intPtr("priority", req.Priority)
b.intPtr("priority_min", req.PriorityMin)
b.intPtr("priority_max", req.PriorityMax)
b.list("label", req.Labels)
b.list("label_any", req.LabelsAny)
b.str("title", req.TitleSearch)
b.str("id", req.IDFilter)
b.str("title_contains", req.TitleContains)
b.str("desc_contains", req.DescContains)
b.str("notes_contains", req.NotesContains)
b.timestamp("created_after", req.CreatedAfter)
b.timestamp("created_before", req.CreatedBefore)
b.timestamp("updated_after", req.UpdatedAfter)
b.timestamp("updated_before", req.UpdatedBefore)
b.timestamp("closed_after", req.ClosedAfter)
b.timestamp("closed_before", req.ClosedBefore)
b.boolean("empty_description", req.EmptyDesc)
b.boolean("no_assignee", req.NoAssignee)
b.boolean("no_labels", req.NoLabels)
b.boolean("include_infra", req.IncludeInfra)
// Added alongside the table.go IncludeEphemeral/HasMetadataKey entries: the
// table declared these params but nothing here wrote them, so a populated
// field silently vanished before the request left the process.
b.boolean("include_ephemeral", req.IncludeEphemeral)
b.metadata(req.MetadataFields)
b.str("has_metadata_key", req.HasMetadataKey)
// The issues.count.scope members (upstream #7199), in the server's own
// countFilters order. Each is emitted only when populated, so a request that
// sets none of them stays byte-identical to what a pre-scope server accepts.
b.str("parent", req.ParentID)
b.boolean("no_parent", req.NoParent)
b.list("exclude_type", req.ExcludeTypes)
b.list("exclude_status", req.ExcludeStatus)
}
// GetTarget encodes a detail lookup onto GET /v0/beads/issues/{id}, returning
// the path id and the query.
//
// It cannot refuse: every member of a GetRequest is on the wire, which is what
// retired ledger row L4.
func GetTarget(req issueops.GetRequest) (string, url.Values) {
b := newBuilder(OpGetIssue, "")
b.boolean("include_dependents", req.IncludeDependents)
b.boolean("include_comments", req.IncludeComments)
b.boolean("brief_deps", req.BriefDeps)
return req.ID, b.v
}
// ReadyBridgeParams encodes the legacy types.WorkFilter onto the ready
// operation's parameters.
//
// It is the reverse mapper D8 calls deliberately throwaway: it lives until
// `bd ready`'s listing moves onto issueops.Reader upstream, and until then it
// refuses every field it cannot express rather than answering a wider question
// than was asked (L12).
func ReadyBridgeParams(f types.WorkFilter) (url.Values, error) {
b := newBuilder(OpListReadyWork, "workFilterBridge")
// The one derived default is recognized BEFORE the residual refusal sweep,
// matching the table's declaration order: Status is declared ahead of the
// plain refusals, so a filter that diverges in both refuses on the derived
// member (D4's parent-walk inversion, applied to the ready bridge's single
// derived default).
b.recognizeReadyStatus(f)
b.refuseInexpressible(f)
b.str("type", f.Type)
b.strPtr("assignee", f.Assignee)
b.boolean("unassigned", f.Unassigned)
b.list("label", f.Labels)
b.list("label_any", f.LabelsAny)
b.list("exclude_label", f.ExcludeLabels)
b.str("label_pattern", f.LabelPattern)
b.str("label_regex", f.LabelRegex)
b.intPtr("priority", f.Priority)
b.strPtr("parent", f.ParentID)
b.list("exclude_type", issueTypeNames(f.ExcludeTypes))
b.metadata(f.MetadataFields)
b.str("has_metadata_key", f.HasMetadataKey)
b.boolean("include_ephemeral", f.IncludeEphemeral)
b.boolean("include_deferred", f.IncludeDeferred)
b.boolean("brief", f.Lite)
b.str("sort", readySort(string(f.SortPolicy)))
b.intPositive("limit", f.Limit)
return b.done()
}
// ReadyBridgeCountParams encodes the same legacy types.WorkFilter onto
// countReadyWork's parameters: the size of the set ReadyBridgeParams lists a
// page of.
//
// It is ReadyBridgeParams with the page taken off, not a second mapper. The
// filter half goes through the bridge's own encoder — so every refusal it
// makes (ExcludeIDs, Offset, a non-default Status, ...) refuses here too, and a
// field the listing could not express can never be counted over a wider set —
// and then the three page-only parameters are removed: `limit` (countReadyWork
// refuses any value, and a cardinality has no page), `sort` (the count's order
// is server-fixed and its total order-independent) and `brief` (a count
// hydrates nothing). What remains is exactly readyFilterEntries, the parameter
// list the two operations share by construction.
func ReadyBridgeCountParams(f types.WorkFilter) (url.Values, error) {
f.Limit = 0
f.Lite = false
v, err := ReadyBridgeParams(f)
if err != nil {
return nil, err
}
v.Del("limit")
v.Del("sort")
v.Del("brief")
return v, nil
}
// recognizeReadyStatus inverts ready work's one derived default.
//
// listReadyWork publishes no status parameter: handleReady decodes a status-LESS
// request and the server's role re-derives the status through
// workapi.BuildReadyFilter, which is unconditionally StatusOpen — open work
// only, the set `bd list --ready` shows. So a WorkFilter carrying exactly that
// derived default is the server's own baseline: the encoder sends no `status`
// and the server reproduces the identical row set. This is what lets every real
// `bd ready` and `bd ready --json` cross the wire, because BuildReadyFilter is
// the one shape the CLI ever builds and it always stamps StatusOpen.
//
// Any OTHER status refuses (L12), which is what makes the drop match the real
// filter EXACTLY. A named status the wire cannot carry — in_progress, closed, a
// custom category — would answer over the query's own open-only default rather
// than the set named; and an EMPTY status is the storage layer's own
// open+in_progress default (types.WorkFilter.Status), which the ready operation
// cannot express either. A populated Statuses OR-set is left to the residual
// sweep, which refuses it as E-WorkFilter.Statuses.
func (b *builder) recognizeReadyStatus(f types.WorkFilter) {
if b.err != nil {
return
}
if f.Status != types.StatusOpen {
b.err = &RefusedError{Op: b.op, Shape: b.shape, Row: RowByID("E-WorkFilter.Status")}
}
}
// SearchShape names one of the two shapes the SearchIssues bridge serves.
type SearchShape string
const (
// SearchExactIDs is D11's fast path: one getIssue per named id.
SearchExactIDs SearchShape = "searchExactIDs"
// SearchParentWalk is D4's hierarchical descendant walk: paged
// listIssues?parent=<id> calls, one level at a time.
SearchParentWalk SearchShape = "searchParentWalk"
)
// SearchPlan is what a raw SearchIssues filter becomes.
type SearchPlan struct {
Shape SearchShape
// IDs is the exact-ids fan-out, in the caller's order.
IDs []string
// Params is the listing query for the descendant walk. The pager owns the
// per-page `limit` and the cursor.
Params url.Values
}
// PlanSearch classifies a raw types.IssueFilter into one of the bridge's two
// shapes, or refuses.
//
// SHAPE FIRST, THEN FIELDS. Which shape a filter is in decides which of its
// fields are readable at all — a ParentID means nothing to getIssue and an id
// set means nothing to a descendant walk — so the classification happens before
// the refusal sweep rather than after it.
//
// vocabulary is the status and type set the descendant walk's derived-default
// inversion recognizes with (parentwalk.go). It must yield the SAME ListConfig
// the filter was built from, which is what makes the inversion exact rather than
// approximate.
//
// It is a FUNCTION rather than a value because only one of the two shapes reads
// it, and the other one is the resolver's hot path: ResolvePartialID runs on
// every id-taking command, and loading a vocabulary the exact-ids arm never
// consults would put three round trips in front of every `bd show`. Deferring it
// into the arm that needs it is also what keeps a REFUSED plan from dialing at
// all — the shape is decided, and rejected, before the wire is touched.
func PlanSearch(f types.IssueFilter, vocabulary func() ListConfig) (SearchPlan, error) {
hasIDs, hasParent := len(f.IDs) > 0, f.ParentID != nil && *f.ParentID != ""
switch {
case hasIDs && hasParent:
// Refused BEFORE a shape is chosen. Letting precedence pick one would
// make the refusal cite whichever field the loser happened to be,
// which is a worse answer than naming the conflict itself.
return SearchPlan{}, &RefusedError{Op: OpListIssues, Row: RowByID("E-IssueFilter.shapeConflict")}
case hasIDs:
if len(f.IDs) > MaxExactIDs {
return SearchPlan{}, &RefusedError{Op: OpGetIssue, Shape: string(SearchExactIDs), Row: RowByID("E-IssueFilter.IDs@bound")}
}
b := newBuilder(OpGetIssue, string(SearchExactIDs))
b.refuseInexpressible(f)
if _, err := b.done(); err != nil {
return SearchPlan{}, err
}
return SearchPlan{Shape: SearchExactIDs, IDs: append([]string(nil), f.IDs...)}, nil
case hasParent:
v, err := planParentWalk(f, vocabulary())
if err != nil {
return SearchPlan{}, err
}
return SearchPlan{Shape: SearchParentWalk, Params: v}, nil
}
return SearchPlan{}, &RefusedError{Op: OpListIssues, Row: RowByID("E-IssueFilter.noShape")}
}
// issueTypeNames widens a typed exclusion list onto the wire's plain strings.
func issueTypeNames(in []types.IssueType) []string {
if len(in) == 0 {
return nil
}
out := make([]string, 0, len(in))
for _, t := range in {
out = append(out, string(t))
}
return out
}
// builder accumulates one request's parameters and its first refusal.
//
// FIRST refusal rather than last, mirroring internal/httpapi's own query
// decoder: the answer must not depend on the order a caller happens to populate
// fields in, and the table's declaration order is the order the sweep walks.
type builder struct {
op Op
shape string
v url.Values
err error
}
func newBuilder(op Op, shape string) *builder {
return &builder{op: op, shape: shape, v: url.Values{}}
}
// refuseInexpressible walks this encoding's table and refuses the first
// populated field the wire cannot carry.
//
// It is table-driven on purpose. A hand-rolled check per field is a check that
// can be forgotten for the field added next week, and the forgetting is silent:
// the encoder would emit nothing for it and the server would have nothing to
// reject. Reading the table means the encoder and the classification the gates
// verify are the SAME statement rather than two that agree today.
func (b *builder) refuseInexpressible(source any) {
if b.err != nil {
return
}
table, ok := TableFor(b.op, b.shape)
if !ok {
b.err = fmt.Errorf("encode: no encoder table for operation %q shape %q", b.op, b.shape)
return
}
rv := reflect.ValueOf(source)
if rv.Type() != table.Source {
b.err = fmt.Errorf("encode: %s expects %s, got %s", table.Op, table.Source, rv.Type())
return
}
for _, entry := range table.Fields {
if entry.Disposition != DispRefused {
continue
}
field := rv.FieldByName(entry.Name)
if !field.IsValid() {
b.err = fmt.Errorf("encode: %s has no field %s", table.Source, entry.Name)
return
}
if populated(field) {
b.err = &RefusedError{Op: b.op, Shape: b.shape, Row: RowByID(entry.Ledger)}
return
}
}
}
// populated reports whether a field carries a value the caller set.
//
// An empty-but-non-nil slice or map is NOT populated: it constrains nothing, so
// refusing it would turn a no-op into an error. A non-nil pointer IS, even to a
// zero value — priority 0 is a real priority and `Ephemeral: &false` is a real
// restriction, and both have been lost by code that read a zero as absent.
func populated(v reflect.Value) bool {
switch v.Kind() {
case reflect.Slice, reflect.Map:
return v.Len() > 0
default:
return !v.IsZero()
}
}
func (b *builder) str(param, value string) {
if value != "" {
b.v.Set(param, value)
}
}
func (b *builder) strPtr(param string, value *string) {
if value != nil {
b.str(param, *value)
}
}
// boolean emits only the TRUE spelling. Every flag on this surface documents
// false as its default, so an explicit `false` would be a parameter that says
// nothing — and one more value for the server to parse.
func (b *builder) boolean(param string, value bool) {
if value {
b.v.Set(param, "true")
}
}
// intPtr emits a pointer-valued number, INCLUDING zero. The pointer is what
// distinguishes unset from an explicit value, which is the whole reason these
// fields are pointers.
func (b *builder) intPtr(param string, value *int) {
if value != nil {
b.v.Set(param, strconv.Itoa(*value))
}
}
// intPositive emits a plain int only when it bounds something. The legacy
// filters spell "no bound" as 0, so a zero here is an absent parameter rather
// than the wire's `limit=0`, which means unlimited and is refused off loopback.
// An absent `limit` is the SERVER's default, not unlimited, so a caller that
// means unlimited must not stop here: the ready bridge's pager writes the
// client-capped bound itself (httpclient/unlimited_read.go).
func (b *builder) intPositive(param string, value int) {
if value > 0 {
b.v.Set(param, strconv.Itoa(value))
}
}
func (b *builder) list(param string, values []string) {
for _, value := range values {
b.v.Add(param, value)
}
}
// timestamp emits an instant in UTC with whatever sub-second precision it
// carries. RFC3339Nano round-trips through the server's time.Parse without
// losing a fractional second, which a bare RFC3339 format would silently drop —
// and a dropped fraction on a created bound is a widened result set.
func (b *builder) timestamp(param string, value *time.Time) {
if value != nil {
b.v.Set(param, value.UTC().Format(time.RFC3339Nano))
}
}
// metadata emits the repeatable key=value equality filter, in key order so one
// filter always produces one query string.
//
// The parameter name is not a parameter of this method: every operation that
// publishes the filter at all spells it `metadata_field`, so taking it from the
// caller would be one more thing a call site could get wrong for no expressive
// gain.
func (b *builder) metadata(fields map[string]string) {
const param = "metadata_field"
if len(fields) == 0 {
return
}
keys := make([]string, 0, len(fields))
for key := range fields {
keys = append(keys, key)
}
sort.Strings(keys)
for _, key := range keys {
b.v.Add(param, key+"="+fields[key])
}
}
// readyFilters emits the filter vocabulary listReadyWork and countReadyWork
// share, which is every parameter but the order and the page.
func (b *builder) readyFilters(req issueops.ReadyRequest) {
b.str("type", req.IssueType)
b.str("assignee", req.Assignee)
b.boolean("unassigned", req.Unassigned)
b.list("label", req.Labels)
b.list("label_any", req.LabelsAny)
b.list("exclude_label", req.ExcludeLabels)
b.str("label_pattern", req.LabelPattern)
b.str("label_regex", req.LabelRegex)
b.intPtr("priority", req.Priority)
b.str("parent", req.ParentID)
b.list("exclude_type", req.ExcludeTypes)
b.metadata(req.MetadataFields)
b.str("has_metadata_key", req.HasMetadataKey)
b.boolean("include_ephemeral", req.IncludeEphemeral)
b.boolean("include_deferred", req.IncludeDeferred)
}
func (b *builder) done() (url.Values, error) {
if b.err != nil {
return nil, b.err
}
return b.v, nil
}