beads/internal/httpclient/encode/skew.go
Julian Knutsen edafcbce1b
fix(httpclient): map Counter scope params and issues.count.scope capability (#7250)
#7210 (OSS HTTP client wire/encode layers) and #7199 (Counter scope —
ParentID, NoParent, ExcludeTypes, ExcludeStatus behind issues.count.scope)
merged back to back without a rebase, leaving main red on the client's
parity gates: the count encoder table left the four new CountRequest
members unclassified, the published parent/no_parent/exclude_type/
exclude_status parameters had no driving field, and the client's
capability vocabulary lacked the server's new behavior token.

- encode: countTable maps the four scope members as params, spelled as
  the server's countFilters decodes them; countFilters emits them.
- encode/skew: --no-parent / --exclude-status flag mapping for the
  unknown_parameter refusal.
- wire: CapCountScope mirrors httpapi.CapIssuesCountScope and joins
  behaviorCapabilities; the vocabulary test pins it by name and order.
- roundtrip: scope members round-trip through the server decoder
  (ParentID and NoParent in separate cases, as the role refuses both).

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-05 08:31:08 -07:00

259 lines
11 KiB
Go

// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/skew.go@49d1df2f6)
// to OSS beads under the MIT license.
package encode
import (
"fmt"
"slices"
"strings"
)
// Version skew, read backwards.
//
// Everything else in this package runs one direction — a request FIELD becomes a
// wire parameter — because that is the direction a filter gets silently dropped
// in. This file runs the other way, and it exists for the other half of the skew
// problem: a newer CLI sending a parameter an older bd serve has never heard of.
//
// The server answers that with 400 `invalid_argument`, `reason:
// "unknown_parameter"` and the offending `param` (internal/httpapi/query.go,
// ReasonUnknownParameter at problem.go:139). The client has the parameter; the
// user has a flag. D7's third refusal text is the translation between them, and
// this table is its mechanism.
//
// It is a table rather than a mechanical kebab-case rewrite of the parameter
// name for two reasons, and neither is cosmetic. First, the rewrite would be
// wrong: `q` is `bd query`'s positional argument and `cursor` is minted by the
// server, so both would render as flags that do not exist and send the user
// looking for one. Second, a table is CHECKABLE — the gate in skew_test.go reads
// it against the encoder table in both directions, so a parameter added to the
// wire tomorrow cannot arrive here unmapped and degrade case 3 into a bare
// "invalid argument" the moment it is the parameter that skews.
// UnknownParameterReason is the `reason` member bd serve sets on the 400 that
// means "this server is older than you think" rather than "that value is
// wrong". The two refusals share a code and carry opposite client recoveries —
// upgrade the server versus fix the argument — so the reason is what dispatches,
// never the code alone.
const UnknownParameterReason = "unknown_parameter"
// UnknownParameterFormat is D7's third refusal text, minus the "Error: " prefix
// the standard exit path adds (cmd/bd/errors.go).
//
// It lives here rather than at the render site because the render site is not
// the only party that has to agree on it: the refusal-UX layer byte-pins these
// bytes, and a pin against a string that layer also owns proves only that it
// agrees with itself. Sharing the constant is what makes the pin a contract
// between the mechanism and the text.
//
// Arguments, in order: subject (already spelled the way a user would read it,
// dashes included), server URL, bd_version, parameter.
const UnknownParameterFormat = "%s is not supported by bd serve at %s (bd_version %s): parameter %q is unknown to the server"
// UnknownParameterNoVersionFormat is the same refusal before the handshake has
// run, when there is no server version to name.
//
// The two forms exist because the handshake is LAZY (D6): a case-3 refusal can
// arrive from a baseline operation that never fetched a context, and dialing for
// a version so the refusal could be one clause longer would be the wrong trade —
// a refusal is the one path that has to stay fast and side-effect free.
//
// Arguments, in order: subject, server URL, parameter.
const UnknownParameterNoVersionFormat = "%s is not supported by bd serve at %s: parameter %q is unknown to the server"
// paramFlag is the flag each wire parameter came from.
//
// The map is flat rather than per-operation because the CLI spells these
// identically on every command that has them — `--limit` is `--limit` on `bd
// list`, `bd ready` and `bd query` alike — and because the parameter is all the
// server tells us: a 400 names the parameter, not the operation's flag set. The
// spellings are pinned against the real cobra tree by the enterprise-tagged gate
// in cmd/bd, so a flag renamed upstream fails there rather than shipping as a
// refusal pointing at a flag that no longer exists.
var paramFlag = map[string]string{
"all": "all",
"assignee": "assignee",
"brief": "brief",
"brief_deps": "brief-deps",
"closed_after": "closed-after",
"closed_before": "closed-before",
"created_after": "created-after",
"created_before": "created-before",
"desc_contains": "desc-contains",
"empty_description": "empty-description",
"exclude_label": "exclude-label",
"exclude_status": "exclude-status",
"exclude_type": "exclude-type",
"has_metadata_key": "has-metadata-key",
"id": "id",
"include_comments": "include-comments",
"include_deferred": "include-deferred",
"include_dependents": "include-dependents",
"include_ephemeral": "include-ephemeral",
"include_gates": "include-gates",
"include_infra": "include-infra",
"include_templates": "include-templates",
"label": "label",
"label_any": "label-any",
"label_pattern": "label-pattern",
"label_regex": "label-regex",
"limit": "limit",
"metadata_field": "metadata-field",
"no_assignee": "no-assignee",
"no_labels": "no-labels",
"no_parent": "no-parent",
"notes_contains": "notes-contains",
"parent": "parent",
"priority": "priority",
"priority_max": "priority-max",
"priority_min": "priority-min",
"reverse": "reverse",
"sort": "sort",
"status": "status",
"title": "title",
"title_contains": "title-contains",
"type": "type",
"unassigned": "unassigned",
"updated_after": "updated-after",
"updated_before": "updated-before",
}
// paramNoFlag names the wire members this client puts on a request that no flag
// produced: what the refusal calls each one, and why it has no flag.
//
// They are enumerated rather than left to fall through so that "no flag" is a
// decision with a reason attached instead of the shape a forgotten entry takes.
// Subject is what the user READS and Why is what a reader of this table (and its
// gate) needs; they are different jobs, and collapsing them would either put
// rationale in a refusal or leave the rationale nowhere.
var paramNoFlag = map[string]noFlagParam{
"q": {
Subject: "the bd query expression",
Why: "`bd query`'s expression is its positional argument, not a flag; a refusal naming `--q` would send the user looking for one that does not exist",
},
"cursor": {
Subject: "paging",
Why: "the opaque keyset token is minted by the SERVER and echoed by the pager. No flag can produce it, and a client that minted its own would be " +
"inventing a position in an order it cannot observe. A user who sees this text is looking at a paging bug rather than at something they typed",
},
"group_by": {
Subject: "the count grouping",
Why: "`bd count` spells the dimension as five mutually exclusive booleans — --by-status, --by-priority, --by-type, --by-assignee, --by-label — and the parameter carries whichever one was set. " +
"There is no --group-by to name, and naming any single --by-* flag would name the wrong one four times out of five",
},
"{id}": {
Subject: "the issue id",
Why: "the issue id is a path segment (and, at the front door, a positional argument), so a skew refusal about it would not be a skew refusal at all — " +
"an older server that does not route the path answers 404, which is D6's capability pre-flight case, not this one",
},
}
type noFlagParam struct {
Subject string
Why string
}
// UnknownParameterSubjectFormat is what case 3 calls a parameter this client
// does not send at all.
//
// The enterprise server's Host-allowlist refusal is the live case: it answers
// 400 with `param: "Host"` for a DNS-named URL (internal/httpapi/server.go),
// which is a request header rather than a query parameter. Rendering that as
// `--host` would be a lie, and dropping it would lose the one refusal on this
// surface whose recovery is a serve-side flag.
const UnknownParameterSubjectFormat = "the %q filter"
// FlagForParam reports the flag that produced a wire parameter.
//
// ok is false both for a parameter with no flag behind it and for one this
// client does not send at all; the caller renders the parameter itself in either
// case. Distinguishing them here would buy nothing — the user's recovery is the
// same, and the reason lives in the table for a reader rather than for a branch.
func FlagForParam(param string) (flag string, ok bool) {
f, ok := paramFlag[param]
return f, ok
}
// ParameterSubject is what case 3 calls the thing the server rejected.
//
// A flag is named as the user typed it, dashes and all. A wire member with no
// flag behind it is named by its recorded subject. Anything else — a parameter
// this client never sent — falls back to naming the parameter, because a
// refusal that could not name its subject would be a skew signal swallowed.
func ParameterSubject(param string) string {
if flag, ok := paramFlag[param]; ok {
return "--" + flag
}
if entry, ok := paramNoFlag[param]; ok {
return entry.Subject
}
return fmt.Sprintf(UnknownParameterSubjectFormat, param)
}
// UnknownParameterRefusal renders D7 case 3 for one skew signal.
//
// bdVersion is empty before the lazy handshake has run, and that picks the
// shorter form rather than printing an empty parenthetical.
//
// It always renders. A skew refusal that could come back empty would be the
// silent drop this whole package exists to prevent, wearing a different hat: the
// user typed something, the server refused it, and every path out of here has to
// say so.
func UnknownParameterRefusal(param, serverURL, bdVersion string) string {
subject := ParameterSubject(param)
if bdVersion == "" {
return fmt.Sprintf(UnknownParameterNoVersionFormat, subject, serverURL, param)
}
return fmt.Sprintf(UnknownParameterFormat, subject, serverURL, bdVersion, param)
}
// SkewParams lists every wire member the encoder table puts on a request, sorted,
// paired with the flag behind it where there is one.
//
// It is what the gate walks, and it is also the honest answer to "which of my
// flags can a server be too old for" — a question the refusal text can only
// answer one parameter at a time.
func SkewParams() []ParamFlag {
entryFor := func(param string) ParamFlag {
flag, ok := paramFlag[param]
return ParamFlag{
Param: param,
Flag: flag,
HasFlag: ok,
Subject: ParameterSubject(param),
Why: paramNoFlag[param].Why,
}
}
seen := map[string]ParamFlag{}
for _, table := range cachedTables() {
for _, entry := range table.Fields {
switch entry.Disposition {
case DispParam, DispPath:
seen[entry.Param] = entryFor(entry.Param)
}
}
for _, reserved := range table.Reserved {
seen[reserved.Name] = entryFor(reserved.Name)
}
}
out := make([]ParamFlag, 0, len(seen))
for _, pf := range seen {
out = append(out, pf)
}
slices.SortFunc(out, func(a, b ParamFlag) int { return strings.Compare(a.Param, b.Param) })
return out
}
// ParamFlag is one wire member and the flag behind it.
type ParamFlag struct {
Param string
Flag string
HasFlag bool
// Subject is what a case-3 refusal calls this member: the flag with its
// dashes, or the recorded spelling for a member no flag produces. Never
// empty.
Subject string
// Why is the reason a member has no flag, empty when it has one.
Why string
}