diff --git a/BUILD.bazel b/BUILD.bazel index f644db68c..91c33c0b0 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -252,3 +252,12 @@ go_test( "//issueops", ], ) + +# //internal/httpclient/encode:encode_test regenerates and compares the shipped +# divergence ledger doc (TestDivergenceLedgerDocMatchesLedger), so the doc must +# be readable as data under `bazel test`. docsync_files above globs it too, but +# that filegroup's visibility is scoped to //test/docsync alone. +exports_files( + ["engdocs/design/http-divergence-ledger.md"], + visibility = ["//internal/httpclient/encode:__pkg__"], +) diff --git a/engdocs/design/http-divergence-ledger.md b/engdocs/design/http-divergence-ledger.md new file mode 100644 index 000000000..b88d98fce --- /dev/null +++ b/engdocs/design/http-divergence-ledger.md @@ -0,0 +1,371 @@ + + + + +# bd HTTP mode — the divergence ledger + +This is the shipped, human-readable rendering of divergence ledger v1: every +place `bd`'s HTTP client mode observably differs from local (embedded/served) +mode, each with its reason and the test that pins it. + +The discipline (design decision D9) is empty-by-default and test-asserted: +**every knowingly-degraded behavior is a ledger row with a pinned test, and a +degradation not in this table is a bug.** `refuse` rows fail rather than +proceeding — a dropped filter widens a result set invisibly, the one failure +class no server-side gate can observe — while `degrade` rows proceed with a +difference argued to be unmisreadable as a narrower or wider answer than the +caller asked for. + +This file is generated from `internal/httpclient/encode`'s +`Ledger()`, the machine-readable source the client actually consults. Do not +hand-edit it: change the ledger in Go and regenerate. Two gates keep it honest — +the encoder's reflection **bijection gate** pins the ledger to the wire (a +request field added upstream lands here or fails CI), and the golden test +`TestDivergenceLedgerDocMatchesLedger` pins this doc to the ledger. The prose +rationale, the decision numbers (D-rows) each entry cites, and the full test-lane +map live in the architecture spec, `http-client-backend.md`, which is not +included in this repository. + +A handful of rows still carry a `TODO` pin: these are the read-display and +pre-run residuals (wisp-in-list, the pretty `bd ready` parent-epic map, the +molecule/auto-import pre-run degradations). The +client core is complete; `ga-b8ddd.12` (per-request project-id enforcement) +closed the read-display escalation, so pinning the remaining fixture corpus is +deferred work, tracked on `ga-b8ddd.23` (the read-display residual) +and `ga-b8ddd.19` (the per-id D7 taxonomy). They are refusals or degradations +already in force — the `TODO` is on the test that will hold each one, not on +the behavior. + +## Kind + +- **refuse** — the operation fails; the wire cannot express what was asked and + proceeding would silently widen or narrow the answer. +- **degrade** — the operation proceeds with a knowingly different behavior that + cannot be misread as a different answer to the question asked. +- **retired** — a row a later council removed; kept so its L-number keeps + resolving and a re-enumeration can tell "retired" from "never existed". + +## Summary + +257 rows: 206 refuse, 33 degrade, 18 retired. + +## Whole-behavior divergences (D9 ledger) + +The L-rows the design's D9 table names: whole behaviors that differ over HTTP, each degraded knowingly or refused outright. Retired rows stay so the L-numbers every citation uses keep resolving. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| L1 | retired | — | RETIRED — `bd list` over http could not ask for the wisp plane | retired by the upstream ask the design page filed for it: "include_ephemeral on listIssues (retires L1)". Upstream published the parameter, the server decodes it (internal/httpapi/reads.go handleListIssues), and the encoder emits it whenever ListRequest.IncludeEphemeral is set. THERE IS NO DIVERGENCE LEFT TO RECORD. `bd list` still shows no wisps, but it shows none LOCALLY either: the front door registers no --include-ephemeral (only `bd ready` does, ready.go), so the field is unset on both paths and both answer the durable plane. A degrade row describing behavior the local oracle shares is not a degradation, and keeping it as one would be the same falsified-premise problem the W- rows had — a ledger arguing from a document that moved | D9 L1 (RETIRED), D8 row 1 | TestEncodedParametersRoundTripThroughTheServerDecoder | +| L2 | degrade | — | a non-created `bd list` sort, the flagless default included, costs page-to-exhaustion on the three legs that cannot push the order down: an unlimited read (--limit 0), a caller-supplied keyset position, and a server that does not advertise issues.list.sort | NARROWED, not retired, by the upstream ask this row named: listIssues publishes `sort` and `reverse`, and the pager's pushdown leg (list_walk.go sortedPage) answers a bounded, position-free request against an advertising server in ONE request, with the server's own LIMIT deciding which rows survive the caller's order. What is left is the legs where that is unavailable or unsafe. An unlimited read has to cross every row whatever the order, and `limit=0` pushed down would newly meet the server's unlimited-read refusal. A keyset position is defined in the created order, and the pager's prefix discard run against a page some other order truncated would drop rows whose replacements were never fetched — a wrong answer rather than a slow one. A down-level server is the fallback the capability probe exists to reach. On all three the client still fetches every page and applies the SQL order's own Go-side mirror plus a copy of the page epilogue's comparator. The weld itself is NOT a divergence and never was: a cursor is bound to the paged order it was minted in (`created` or `priority`) and the server refuses it under any other `sort` | D9 L2, D8 row 1 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L3 | degrade | — | a multi-page fetch has no snapshot isolation | the keyset cursor pins a position, not a snapshot: rows created mid-walk are missed and row states mix instants, where local mode is one query | D9 L3 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L4 | retired | — | `bd show` dependents sections and comment bodies were degraded | retired by council #1: the write-lifecycle wave landed include_dependents/include_comments on getIssue, and both the off-role text path and the on-role JSON path are wired | D9 L4 (RETIRED), D4, D8 row 1 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L5 | degrade | — | molecules are not auto-loaded pre-run | the loader writes, the write refuses, and the call site swallows the refusal to debug.Logf | D9 L5, D4 | TODO(ga-b8ddd.23): a pre-run degradation, observable only through a cmd/bd invocation; the subprocess parity corpus pins it | +| L6 | degrade | — | a pre-run auto-import ATTEMPT reaches an http workspace and fails as a best-effort stderr warning; nothing is imported | THE MECHANISM THIS ROW USED TO NAME DOES NOT EXIST. It said the path was "force-disabled through an import.auto=false env override", and there is no such override anywhere: shouldRunAutoImportJSONL (cmd/bd/main.go) reads the config key, whose default is true (internal/config/config.go), and no http path sets it false. WHAT ACTUALLY HAPPENS is that maybeAutoImportJSONL runs — on any non-read-only, non-global, non-server-mode command — and is stopped by its own guards rather than by a switch: a missing or empty issues.jsonl, the attempt stamp, or the emptiness guard, which is a GetStatistics the server serves. Where all three pass (an empty server beside a non-empty local JSONL) the import is attempted and fails, because the client is not a jsonlImporter and the fallback importer's first write — SetConfig, or CreateIssuesWithFullOptions — is on the unsupported allowlist. The function is documented best-effort, so the failure is an stderr warning and the command proceeds. The DEGRADATION is therefore that nothing imports, which is the outcome the design wanted for the right reason — importing a local JSONL into a shared server is not a pre-run side effect — reached by refusal rather than by configuration. It stays a degrade because the command proceeds and the answer is not narrower or wider than the caller asked for. The retirement path is a real skip on the http backend, so the warning stops being the mechanism | D9 L6, D4 | TODO(ga-b8ddd.23): a pre-run degradation, observable only through a cmd/bd invocation; the subprocess parity corpus pins it | +| L7 | degrade | — | the client-side status/type vocabulary is defaults plus the status.custom/types.custom/types.infra config keys; table-backed customs are invisible client-side | the custom_statuses/custom_types tables have no wire operation; server-side role validation still uses the true vocabulary | D9 L7, D4 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L8 | refuse | `--deps` | `bd list --deps` refuses, and the pretty/--format dependency-decoration arms render undecorated | GetAllDependencyRecords has no wire mapping in v1; listDependencies is an anchored read. --tree is NOT in this row: it defaults true and is `bd list`'s default text rendering | D9 L8, D4 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L9 | degrade | — | credential-bearing settings are unreadable client-side | the server redacts by omission and says so on the wire in Setting.redacted; the client answers absent-WITH-A-REASON rather than the empty string a caller would read as unset | D9 L9 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L10 | refuse | `--watch` | `bd list --watch` and `bd show --watch` refuse | the loops poll every 2s, each `bd list` tick is a full cursor walk (L2), per-tick errors spam or vanish, and the decoration is refused anyway (L8); N watchers against one server is a request storm its semaphore answers with 503s the loop does not back off from | D9 L10, D10 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L11 | degrade | — | hooks fire client-side after the server's commit with no shared transaction, on connected workspaces only | the seam sits below HookFiringStore in the client process; a --server-url ephemeral invocation has no hook directory and runs none | D9 L11, D1 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L12 | refuse | — | an inexpressible filter refuses, never drops — the class rule every E- row below is an instance of | a dropped filter widens a result set invisibly, and the server can only reject parameters it receives | D9 L12, D7 | TestEncoderHonorsEveryTableDisposition | +| L13 | degrade | — | pretty `bd ready` shows no parent-epic context | buildParentEpicMap swallows the GetDependencyRecordsForIssues refusal into a nil map; the retirement path is an anchored listDependencies plus per-parent getIssue | D9 L13, D4 | TODO(ga-b8ddd.23): a pre-run degradation, observable only through a cmd/bd invocation; the subprocess parity corpus pins it | +| L14 | degrade | — | against a server that does NOT advertise issues.claimNext, the composed ReadyClaimer leaves three residues: the ready-at-fetch/claim-at-dial window, a false empty under contention after the bounded refetch, and a claimed row whose CARDINALITIES are as of the listing rather than of the claiming transaction | claimIssue validates claimability, not readiness, so a listing plus a claim is not the local role's one transaction and cannot be made into one. THE ROW IS NARROWER THAN IT WAS. Upstream published POST /v0/beads/issues:claimNext (#5510) and client wave ga-jpywb dials it, so on any server that advertises the token NONE of these three residues exists: selection, the compare-and-set and the hydration share the server's own transaction, an empty front is a 200 with `claimed` absent rather than a lost-races error, and the counts describe the state the claim produced. The whole ReadyClaimer contract tier runs against that leg with nothing parked, which is the measurement that says the residues were the COMPOSITION's rather than the wire's. WHAT KEEPS THE ROW ALIVE is the DOWN-LEVEL leg, which survives on purpose: `bd ready --claim` worked against pre-#5510 servers before this port, and refusing it now would be a regression dressed as progress. It is the posture BatchCloser takes toward issues.batchClose, and it is why this row describes shipped behavior rather than history. The third residue is stated in its IMPLEMENTED form, which is not the one the design anticipated: the design expected a follow-up getIssue to hydrate the counts, and therefore a read that could fail AFTER the claim was durable. The composition takes the counts from the ready page it already fetched instead, so that failure mode does not exist — a claim changes no dependency, dependent or comment count, and what is left is staleness bounded by the same fetch-to-dial window residue (a) already owns. Retirement is no longer an upstream ask but a fleet fact: the row goes when no server this client may meet is older than #5510 | D9 L14, D8 row 4 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L15 | degrade | — | a --max-rows cap can fire over http on a query whose Limit is at or under the cap, on the `bd list` legs that still walk | locally the effective SQL LIMIT is min(Limit, MaxRows+1), so a window at or under the cap can never exceed it; over http a walk to exhaustion fetches far more than the window and the cap deliberately bounds WIRE ROWS FETCHED — safety wins over exit-code parity on exactly the unbounded walk the cap exists to bound. NARROWED by the same pushdown that narrowed L2: the pushdown leg asks for min(limit, MaxRows+1) rows in one request, which IS the local expression, so a cap at or above the limit can no longer fire there and a request that used to exit 2 now answers. That is a convergence toward the contract, and it is observable — the same command changes from a refusal to a page. THE NARROWING IS SCOPED TO THE ORDERS SQL CAN EXPRESS, and that scope is a correctness bound rather than an optimization left on the table. For a GO-SIDE sort — sqlbuild.IsGoSideSort, today `--sort id`, which needs the natural-numeric comparison (bd-9 before bd-10) no ORDER BY renders — workapi.SQLLimit pushes 0 down instead of the limit, so LOCALLY the window is MaxRows+1 whatever the limit is and the cap fires on the overage even under a limit at or below it. min(limit, MaxRows+1) is therefore NOT the local expression there, and a request bounded by the limit cannot see the overage at all. walkIssues' gate keeps a capped Go-side sort on the walk, where fetching MaxRows+1 wire rows reproduces that unbounded local window exactly and raises the same refusal — so on this one shape the walk leg is the CONVERGENT one and pushing down would have been the divergence. What keeps the row live is the walk legs (unlimited reads, keyset positions, down-level servers), where the old accounting is unchanged and correct, and `bd ready`, which has no pushdown at all | D9 L15, D12 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L16 | refuse | `--file` | `bd dep add --file` carrying more than 100 edges refuses, naming the wire bound; it is never chunked | maxAddDependencyEdges = 100 (internal/httpapi/dependency_edit.go); chunking is the one path that silently breaks the request's one-transaction/one-history-entry contract, where naive forwarding at least fails loudly | D9 L16, D7, D8 row 18 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-close-cap | refuse | — | a batch close naming more than 100 items refuses, naming the wire bound; it is never chunked | maxBatchCloseItems = 100 (internal/httpapi/batch_close.go); the item cap bounds how long one request may hold a write transaction. Chunking is the one path that silently breaks the request's one-transaction/one-history-entry contract — the same reason L16 refuses a bulk dependency add rather than splitting it — so a larger list refuses and the caller splits it, each request atomic on its own | D9 L-close-cap, D7 F-close, D8 row 17 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-dep-endpoint | degrade | — | a dependency add whose source or target names no issue refuses as ErrValidation over http, not as *DependencyEndpointNotFoundError wrapping ErrDependencySourceNotFound or ErrDependencyTargetNotFound | the wire spells that refusal as a 400 invalid_argument with reason `invalid_value` and the offending member in `param` (internal/httpapi/dependency_edit.go). Reason and code are the same ones a malformed id earns, so the two are indistinguishable without reading `detail` prose — which is exactly what the extension-member vocabulary exists to avoid. The refusal still FAILS the request and still writes nothing; only its classification is coarser. Upstream ask: a distinguishing code or reason for the endpoint-not-found refusal, which retires this row | D8 row 18 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-claim-prose | degrade | — | a claim refusal's MESSAGE does not carry the ClaimedBy/NotClaimableStatus fragments, so beads.ParseClaimConflict recovers nothing from it over http | the fragments exist so that parser can recover the conflicting assignee and status from PROSE. Over the wire both arrive as typed extension members and *ClaimConflictError is reconstructed whole, so a caller reading the FIELDS loses nothing. Recomposing the copy client-side would mean re-implementing which copy each refusal shape gets — an open issue held by someone else deliberately omits the assignee tail, an in-progress one carries it — which is a second implementation of the very rule the fragments were introduced to keep single | D8 row 3 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-delete-notfound | degrade | — | issueops.Deleter.Delete over http refuses an absent id as issueops.ErrNotFound, not as *NotFoundError naming WHICH ids did not resolve | the role's error is a typo report and names every missing id; the wire deliberately does not repeat them (internal/httpapi's NotFound() carries a FIXED detail, so a 404 body cannot echo caller input back). The refusal still FAILS the request and still deletes NOTHING — not even the ids beside the typo — so the all-or-nothing promise is intact and only the classification is coarser. It is stated at the ROLE rather than at a command because `bd delete` is not reachable against an http workspace at all (see httpUnconsumedCapabilities); the embedder holding the role is the audience. Upstream ask: an ids extension member on the not_found problem, which retires this row | D8 row 13 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-delete-dependents | degrade | — | the unforced dependents guard refuses as issueops.ErrValidation, not as *DependentsOutsideRequestError wrapping ErrDependentsOutsideRequest | the wire spells that refusal as a 400 invalid_argument with no `param` (internal/httpapi's failDeleteErr) — the fix is to change the REQUEST, by sending cascade or force — so the blocked id and its dependents cannot be reconstructed without parsing detail prose, which is what the extension-member vocabulary exists to avoid. The guard itself is untouched: the request fails and the graph is whole. Upstream ask: a dependents_outside_request code carrying issue_id and dependents, which retires this row | D8 row 13 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-delete-bound | refuse | — | issueops.Deleter.Delete refuses a request naming more than 1000 ids, citing the wire bound; it is never split across requests | maxDeleteIDs = 1000 (internal/httpapi/delete.go). Splitting is the one path that silently breaks the request's one-transaction, one-history-entry contract — and it would ask the dependents guard about half a request at a time, so a pair the caller deliberately listed together would be refused as an outside dependent. Naive forwarding at least fails loudly. Stated at the ROLE: `bd delete` cannot reach an http workspace, so the embedder is the audience | D8 row 13, D9 L16 (the same argument, on the other bulk write) | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-batchcreate-bound | refuse | — | `bd create --file` carrying more than 100 issues refuses, naming the wire bound; it is never split across requests | maxBatchCreateItems = 100 (internal/httpapi/batch_create.go). The request IS the transaction, so two requests are two transactions and two history entries where the role promises one — and a failure in the second leaves half a plan created, which is the outcome all-or-nothing exists to make impossible | D8 row 14, D9 L16 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-edgecount-bound | refuse | — | issueops.GraphCounter.CountEdges refuses a request naming more than 100 DISTINCT anchors, citing the wire bound; it is never chunked across requests | maxDependencyAnchors = 100 (internal/httpapi/edges.go), the same bound the stored-edge read on this collection carries — the role deliberately sets none of its own and says the bound belongs to the WIRE. Chunking is what a READ could get away with and this one cannot: CountEdges promises that an anchor's EXISTENCE and its edge count are read from one consistent view, so two requests would let an anchor be reported missing by a probe that raced a create the other chunk's count already saw — one answer contradicting itself, which is the exact failure AnchorEdgeCount.Missing exists to make impossible. Refusing at the bound fails loudly instead, and the caller splits the question knowing it asked twice. Upstream ask: a cursor or a higher bound on the anchor list, which retires this row | D9 L16 (the same argument, on a read), D8 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-batchcreate-target | degrade | — | a batch create whose edge target names no issue refuses as issueops.ErrValidation alone, not as ErrValidation WRAPPING ErrNotFound | the wire answers a dangling edge target with a 400 invalid_argument naming `items` (internal/httpapi's failBatchCreate), and deliberately does not quote the role's own message, which arrives as a driver error naming tables and constraints. The refusal still fails the whole batch and creates nothing — the promise the row is about — and only the second sentinel is lost. Upstream ask: a distinguishing code for the absent-target refusal | D8 row 14 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-batchcreate-inbatch | refuse | — | an edge onto an EARLIER ITEM OF THE SAME BATCH cannot be expressed at all over http | the capability needs the earlier item to have named an id for itself, and apigen.BatchCreateItem publishes no id member — an explicit id is refused with the rest of W-BatchCreateItem.Issue. So the target of an in-batch edge can only be a row the workspace already holds. It is a REFUSE row rather than a degrade because the request that asks for it fails: the client refuses the explicit id before the dial, and there is no second spelling that would land the edge silently. The wire's own `target_id` description names this case, so the gap is in the SCHEMA rather than in the handler — the upstream ask is an item id member, which retires this row | D8 row 14 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L18 | degrade | — | DOWN-LEVEL ONLY: against a server that does not advertise issues.batchClose, a single-id `bd close` still composes onto closeIssue and records the SERVER's own close commit message rather than the batch's id-naming entry; the multi-id and --claim-next shapes refuse there | the composed leg is one closeIssue call, so the history entry it leaves is the one that operation writes for itself — the batch's entry names the ids it closed and this one cannot, because no batch ran. Where issues.batchClose IS advertised the whole request is one call and one server-side transaction, so this divergence does not arise at all; the down-level leg survives on purpose, because `bd close` worked against pre-batchClose servers before this port and refusing it now would be a regression dressed as progress. It is the same posture L14 takes toward issues.claimNext. It is a degrade rather than a refuse because the close LANDS and the answer is neither narrower nor wider than the caller asked for — only the record of it is the operation's rather than the batch's. Retirement is a fleet fact rather than an upstream ask: the row goes when no server this client may meet is older than issues.batchClose | D9 L18, D8 row 17 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-create-notfound | degrade | — | a create whose dependency or waits-for target names no row refuses as issueops.ErrValidation ALONE — not as ErrValidation wrapping ErrNotFound — and does not name the target | the wire answers a dangling target with a 400 invalid_argument naming `dependencies` and a FIXED detail (internal/httpapi's failCreateIssue), which deliberately does not quote the role's own message: that message arrives as a driver error naming tables and constraints, and 4xx details on this surface reflect the caller's own input back rather than server internals. The refusal still fails the whole request and creates NOTHING — the promise the row is about — and only the second sentinel and the target's name are lost. It is batchCreateIssues' L-batchcreate-notfound on the single create, and it retires the same way: an upstream code that distinguishes the absent-target refusal and carries the target. A missing --parent target already retired out of this row: failCreateIssue's errors.As(&parentNotFound) arm answers it with a distinguishing 404 not_found that names the target, and the client maps that to issueops.ErrNotFound (see TestServedCreateRefusesAnAbsentParentAsNotFound) — the row now covers only dependency and waits-for targets | D8 row 16 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-create-prefix | degrade | — | an unforced explicit id outside the workspace's configured prefix refuses as issueops.ErrValidation rather than as storage.ErrPrefixMismatch | the wire spells that refusal as a 400 invalid_argument with `param: "id"` and `reason: invalid_value` (internal/httpapi's failCreateIssue), which is the SAME pair a malformed or oversized `id` earns — so nothing on the wire tells the two apart, and reconstructing the typed sentinel from the pair would misclassify every other refusal of that member. The guard itself is untouched: the id is refused, nothing is created, and the detail names `force_id_prefix` as the bypass, which is the recovery a caller needs. What is lost is the errors.Is arm both local front doors use to decide whether to re-offer the create with --force. Upstream ask: a prefix_mismatch code, or a reason that distinguishes it, which retires this row | D8 row 16 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-apply-snapshot | degrade | — | every ItemResult of a batch apply comes back with Issue nil, where a local backend hydrates a post-item snapshot | the WIRE result is lean by the document's own decision and the role's leaf says why: ApplyItemResult carries ids, `changed` and `revision` and no issue, because the Go contract carries the snapshot for its COMPLETION HOOKS — which hand a script the row they are telling it about — and hooks never fire on the http surface at all. A hundred hydrated issues with their labels and edges would be a response an order of magnitude larger than the request that produced it. What a caller loses is a read it can make: the ids ARE published, per item and through Keys, so the rows are one getIssue away and the plan's next step is composed from ids rather than from snapshots. It is a degradation rather than a refusal because nothing about the WRITE differs — every item landed exactly as asked — and refusing would make the whole operation unavailable over http to keep a member no consumer on this surface can use | D8 refuse-not-drop (result half) | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-apply-ref | degrade | — | an unresolvable metadata_refs key comes back as a *RefError naming the MEMBER rather than the key, and the reconstructed error replaces the server's problem envelope | the wire's 400 names the offending member in `param` — `items[3].create.metadata_refs` — and carries the item index, the item's key and `declared_later`, but not WHICH entry of the refs map failed: the role's RefError.Member is diagnostic prose (`metadata_ref `) rather than a vocabulary, so the server maps it onto the document's own member names instead of publishing it. The two ADDRESSING refs, target and source, are named exactly. The envelope is dropped because issueops.RefError has nowhere to put it: its Unwrap is hardcoded to ErrValidation and it carries no member for a cause, which is the role type's shape rather than a choice made here. The discriminator a caller ACTS on — an ordering mistake against a typo — survives whole, in both polarities. Upstream ask: a typed ref-key member on the problem document, which retires this row | D8 refuse-not-drop (result half) | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-comment-author | degrade | — | a comment's AUTHOR is subject to the server's own actor rule, which no local leg applies: it is stored TRIMMED where a local backend stores it verbatim, and one carrying a control character is refused (issueops.ErrValidation) where a local backend stores it | the operation validates `author` with the `actor` rules whole (internal/httpapi's validateNameMember: trim, refuse empty, refuse past 256 bytes or 255 characters, refuse any control rune) and passes the TRIMMED value on to the role, while issueops.ValidateAddCommentRequest checks only that the field is non-empty and stores what it was given. So the same request produces a different STORED VALUE on the two legs, and a value one leg stores the other refuses. IT IS THE SERVER'S RULE AND THE DOCUMENT PUBLISHES IT, which is why this is a ledger row rather than a bug on either side: the schema states the trim and the character rule in as many words, and the reason is the column — `author` is 255 characters wide and every renderer of the thread prints it, where an unfiltered C1 introducer is an escape-sequence payload. The refusal half is a NARROWING the wire makes on purpose. THE CLIENT DOES NOT ANTICIPATE EITHER HALF, and that is the decision this row records. Trimming here would make the client agree with the server about the stored value and disagree with the role's own contract — and it would silently rewrite a caller's request, which is the one thing this seam never does. Refusing the control rune here would be a second copy of a server rule that is free to move. So the value travels as the caller wrote it and the server's answer is reported unchanged, which keeps the divergence visible instead of laundering it. IT IS A DEGRADE RATHER THAN A REFUSE because the ordinary path PROCEEDS: a well-formed author is stored, and the difference cannot be misread as a wider or narrower answer — a comment lands on the thread the caller named either way. The refusal half is the SERVER's, not this client's refuse-not-drop, which is what KindRefuse classifies. What a caller loses is an author whose surrounding space survives, and the recovery is the one the role's own contract already implies: compose the author from a value you would be willing to see printed. Upstream ask: either the role trimming its own author on every leg, or the operation storing it verbatim — the rows agree the day the two rules become one | D8 row 19 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-release-notclaimed | degrade | — | a release of a row that holds NO CLAIM answers issueops.ErrNotReleasable rather than issueops.ErrNotClaimed; a status that will not accept a release answers ErrNotReleasable as it does everywhere | the role splits the two — ErrNotClaimed for a row nobody holds, ErrNotReleasable for a status the transition is not defined over — and the wire spells BOTH `not_releasable` under one code, with no member telling them apart. That is the server's deliberate choice (internal/httpapi's CodeNotReleasable) rather than an omission, and its detail names both conditions instead of guessing between them. So this client maps to the WIDER of the two, which is the only honest read: reconstructing ErrNotClaimed would assert a fact about the row that the wire never sent, and scraping the detail for it would bind a sentinel to prose. NOTHING ELSE ABOUT THE REFUSAL MOVES — nothing is written, the row and its version are untouched, and the conditional path is unaffected: a caller that named a holder gets ErrAssigneeMismatch on both sides, because that refusal has a code of its own. The caller who loses something is the one that told 'I already released this' from 'the row was never claimed', and the recovery is the one the server's own detail prescribes: READ THE ROW rather than retrying blind. Upstream ask: a code, or a member, that distinguishes the unheld row from the unreleasable status — which retires this row | D8 (Releaser), D9 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-release-notowner | degrade | — | an unforced, unconditional release by an actor that is NOT the holder answers issueops.ErrAlreadyClaimed — carrying *issueops.ClaimConflictError — rather than issueops.ErrNotOwner | the wire answers the ownership fence with `already_claimed`, which is the code updateIssue already gives the same situation (a live foreign owner refusing a write, with a force bypass and a name-the-holder bypass), and this client maps that code to the sentinel every other operation means by it. The two sentinels are distinct values in issueops and neither wraps the other, so the arm a caller writes differs. REPORTING IT AS ErrNotOwner WOULD BE THE WORSE TRADE, not merely a different one: the code is shared with the claim refusals, so a client that special-cased it for this operation would be reading the OPERATION to decide the sentinel rather than the code — and would then answer ErrNotOwner for a genuine already_claimed the day the server reuses the code here for anything else. WHAT SURVIVES IS EVERYTHING A CALLER ACTS ON: the refusal is typed, it names the row (the request supplied the id the wire leaves out), nothing is written, and BOTH bypasses answer exactly as the role says — force releases the foreign claim, and naming the holder in expected_assignee releases it too, because a match replaces the fence. The wire deliberately sends no `assignee` member here, so the holder is not named: absence means 're-read the row', never 'nobody holds it'. Upstream ask: a code, or a member, that separates the release's fence from a claim conflict — which retires this row | D8 (Releaser), D9 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-config-bounds | degrade | — | a setting VALUE past types.MaxTextBytes bytes, and a setting KEY past types.MaxFieldLen characters on the WRITE, are refused with issueops.ErrValidation naming the member; on a local leg the same request reaches the column and fails with the engine's own `too large for column` error, which is no sentinel at all | the bound belongs to the OPERATION rather than to the role: internal/httpapi's settingWriteKey and settingValue check both before the role is called, because a request the caller could have fixed should be a 400 naming the member rather than the 500 a column overflow would otherwise produce. workapi.ValidateSettingWrite — the rule every leg shares — applies no length bound at all, so below the wire the column is the only check there is. MEASURED, not inferred: a 65536-byte value answers `400 invalid_argument: \`value\` is 65536 bytes; storage holds at most 65535` over http and `Error 1105: string ... is too large for column 'value'` on the embedded leg, and a 306-character key splits the same way. Exactly 65535 bytes is accepted on both. THIS CLIENT RESTATES NEITHER BOUND, and that is the decision this row records. They are the SERVER's policy on a value whose shape the role accepted, one release away from moving, so a second copy here would either drift or refuse a request a newer server would take — the same argument L-comment-author makes about the author rule, and the same posture. What travels back is the operation's own 400, which the problem mapper turns into ErrValidation. IT IS A DEGRADE RATHER THAN A REFUSE because the ordinary path PROCEEDS and because the divergence runs in the CALLER'S FAVOR: over http an oversized write is a typed, member-named refusal that wrote nothing, where a local leg hands back a driver error no caller can classify. What a caller loses is nothing; what a caller must not assume is that a value a local workspace stored will store here. THE TWO BOUNDS ARE NOT SYMMETRIC ACROSS THE VERBS, and the asymmetry is the operation's: DELETE checks only that the key names something, so removing a 306-character key succeeds over http exactly as it does locally. Upstream ask: the length rules moving onto the shared validator, which retires this row by making the two legs one | D8 row 11, D9 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-update-fieldlen | degrade | — | an updateIssue patch member past types.MaxFieldLen characters — a label on any of the three label members, `title`, `external_ref` — is refused with issueops.ErrValidation naming the member; on a local leg the same request answers types.ErrFieldTooLong | the bound is applied TWICE and identically: internal/httpapi/update.go checks types.CheckFieldLen at the edge before the role is called, and internal/storage/issueops applies the same function below it. So this is a classification divergence and not a policy one — a value one leg stores the other stores, and a value one leg refuses the other refuses. WHAT COARSENS IT is the spelling: the operation refuses with `invalid_argument` and reason `invalid_value` (internal/httpapi's refuse on the patch member), which is the SAME pair a malformed status, an unparseable timestamp or any other bad value on the same member earns. Nothing on the wire tells them apart, so reconstructing ErrFieldTooLong from the pair would misclassify every other refusal of that member — the argument L-create-prefix makes about the id, on the patch. MEASURED, not inferred: a 256-character label answers `400 invalid_argument: \`add_labels[0]\` is 256 characters; storage holds at most 255` over http and ErrFieldTooLong through the reference store's own Lifecycle role, and exactly 255 characters is accepted on both. THIS CLIENT RESTATES THE BOUND NOWHERE, and the reason differs from L-config-bounds': not that the rule is the server's to move, but that a second copy of a rule two layers already apply is a third place for it to drift. What travels back is the operation's own 400. IT IS A DEGRADE RATHER THAN A REFUSE because the path PROCEEDS and the outcome is identical on both legs — the request fails, the row is untouched, and no truncated value is stored — while the detail names the offending member and its length, which is the recovery a caller needs. What is lost is the errors.Is arm a caller writes to tell 'too long' from 'malformed'. Upstream ask: a `too_long` reason, or a code of its own, which retires this row | D8 row 16, D9 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| L-events-paging | degrade | — | an UNCAPPED journal read (limit 0) is served as a loop of handler-sized requests rather than one, so its rows and its head no longer come from a single instant; a bounded read is one request and is unaffected | the role imposes no ceiling of its own — journalops.Journal says a limit of 0 means uncapped, because the caller that pages a hundred thousand records out to a file is as legitimate as the one polling for ten — and the OPERATION refuses `limit=0` by value, capping a page at 10000 (internal/httpapi's maxEventsLimit). That cap is the handler's promise to its clients rather than a narrowing of the role, and this client is on the other side of it. SO THE LOOP IS THE ONLY HONEST READING. Refusing an uncapped read would refuse something the role permits; capping one silently at 10000 would answer a partial page beside a head saying there is more, which is a consumer stalling on a gap nobody told it about. Both are worse than N transactions. WHAT SURVIVES IS WHAT A CONSUMER ACTS ON: rows stay contiguous and seq-ascending, because each page continues exactly where the last ended; the head is the LAST page's, so it is the freshest and can only be at or ahead of the last row served; and a truncation on any page is the whole read's failure, never a shorter answer — a loop that returned the prefix it had already gathered would answer a gap with a plausible-looking suffix, which is the one failure a replay feed must never ship. WHAT DOES NOT SURVIVE is atomicity across the whole answer: a mutation committing mid-loop appears in a later page of the SAME call rather than in the next one. A consumer cannot observe that as a gap or a duplicate — it reads as records it would have received on its next poll, arriving early — which is why this is a degrade rather than a refusal. IT IS A DEGRADE RATHER THAN A REFUSE for the ordinary reason too: the path proceeds, and the answer cannot be misread as narrower or wider than the caller asked for. Upstream ask: an unlimited spelling on the operation, or a cursor the page can hand back — either retires this row | D8 (Journal), D9 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | + +## Write-side refuse-not-drop (D8) + +Role-request fields on the served writes that the v0 wire publishes no member for. Each refuses rather than forwarding a write shorn of the field — a silently dropped precondition or flag would widen what the write touches. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| W-UpdateRequest.Claim | refuse | `UpdateRequest.Claim` | a claim combined with any other UpdateRequest member refuses; a claim ALONE does not — it dials claimIssue directly (see httpLifecycle.claimOnlyUpdate) | a claim is claimIssue's own operation and updateIssue cannot perform one, on this wire or on any other; it is the one row here that upstream #5484 did not touch. claimIssue's own request is the actor alone, so a claim-only UpdateRequest IS that request and is served through the Claimer role instead of refusing — that is gc's exclusive claim path, `bd update --claim --json`. What still refuses is PATCH claim: a claim folded into one atomic transaction WITH a patch, a guard or a force override, which no operation on this wire publishes and which is not synthesized as two calls (claimIssue then updateIssue), since that would let a caller observe an issue claimed but not yet patched. Upstream gastownhall/beads#6890 tracks the capability that would carry both in one call | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-ClaimRequest.Wisp | refuse | — | claiming a wisp is not supported over http | the v0 wire's claim operation excludes the wisp plane on every backend; claim this issue from a local workspace instead | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-UpdateRequest.ForceAssigneeTransfer | refuse | `UpdateRequest.ForceAssigneeTransfer` `--force` | bypassing the anti-steal assignee fence refuses | the wire publishes `force_assignee_transfer` (upstream #5484) and this client does not send it. What the refusal STANDS ON changed with client wave ga-7i6by and the row is narrower for it: the `assignee` the fence guards IS now sent (W-IssuePatch.Assignee), so what is left is the bypass alone. The fence itself is unbypassable rather than absent — a transfer away from a live foreign in-progress owner refuses with already_claimed, and a matched `expected_assignee` is the OTHER bypass, which this client does send. Carrying this one is a two-member port tracked as ga-2ltro.15 | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-UpdateRequest.ForceClosePolicy | refuse | `UpdateRequest.ForceClosePolicy` `--force` | bypassing close policy on a status-crossing update refuses | the wire publishes `force_close_policy` (upstream #5484) and this client does not send it; see W-UpdateRequest.ForceAssigneeTransfer for what the refusal now stands on, since client wave ga-7i6by sends the `status` whose crossing the policy gates. The policy is therefore enforced and not bypassable here: a status crossing into the done category with open children or a live blocker refuses with not_closable, typed, and writes nothing. Tracked as ga-2ltro.15 | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-UpdateRequest.ExpectedVersion | retired | — | the compare-and-set row-version precondition used to refuse | RETIRED by the client wave that sends it (ga-jbuyf). The refusal was always the CLIENT's rather than the document's — upstream #5484 published `expected_version` and this client had not been taught to emit it — and the row said so in as many words: 'flipping it is a port, not a decision: send the member, retire this row, and turn the refusal pin into a round-trip pin'. That is what happened. The member is now sent as a POINTER, so absent stays absent: 0 is a legal token (the migration-0054 backfill left rows holding it) and encoding 'no guard' as 0 would have armed a guard on every unguarded update. The pin below asserts the round trip in both directions | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-UpdateRequest.ExpectedAssignee | retired | — | the compare-and-set assignee precondition used to refuse | RETIRED with W-UpdateRequest.ExpectedVersion (ga-jbuyf). Its own trap is the mirror image of that one's: the EMPTY assignee is a real guard — it is how a caller says 'only if nobody holds it' — so this member cannot be omitted when it is empty either. A pointer expresses both, and the pin drives the empty-string guard as its own case | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-UpdateRequest.ExpectedStatus | retired | — | the compare-and-set status precondition used to refuse | RETIRED with W-UpdateRequest.ExpectedVersion (ga-jbuyf). The status guard is the readable one — `Issue.status` is on every read of this surface, so a caller can guard a transition with no token at all — and it is sent as the workspace's own status vocabulary, verbatim | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-UpdateRequest.IssuePlaneOnly | refuse | `UpdateRequest.IssuePlaneOnly` | restricting an update to the issue plane refuses | updateIssue publishes no plane restriction and the server's role auto-resolves both planes, so dropping the flag would EDIT the wisp the caller asked to be told did not exist — the widening refuse-not-drop exists to stop. Not in the design's own enumeration: the page lists the UpdateRequest members it had reviewed, and this one was found while wiring the role | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-UpdateRequest.Provenance | refuse | `UpdateRequest.Provenance` | labeling an update's history entry refuses | updateIssue publishes no provenance member and the server writes its own label, so a dropped Provenance would leave the history entry naming the SERVER's surface while the caller believed it named theirs. It is refused rather than degraded because the field's whole purpose is the label, so dropping it drops the request | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CloseRequest.ExpectedVersion | retired | — | the compare-and-set row-version precondition on a close used to refuse | RETIRED by the client wave that sends it (ga-jbuyf). CloseIssueRequest publishes expected_version (upstream #5506) and this client now emits it, so the guard reaches the server rather than refusing here — and the ordering the role promises, that the precondition is checked BEFORE the idempotent re-close, is the server's to keep and the served tier's to assert | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-ReopenRequest.ExpectedVersion | retired | — | the compare-and-set row-version precondition on a reopen used to refuse | RETIRED with W-CloseRequest.ExpectedVersion (ga-jbuyf). The design's enumeration named the close half only, and the reopen half is the same field on the same verb pair — it retires the same way | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-DeleteRequest.ExpectedVersion | retired | — | the compare-and-delete row-version precondition used to refuse | RETIRED with W-CloseRequest.ExpectedVersion (ga-jbuyf), and it is the one whose stakes made the refusal worth having: dropping this guard erases a row the caller had asked not to erase, with nothing left to compare afterwards. The multi-id refusal the wire attaches to it is deliberately NOT anticipated client-side: distinctness is measured after trimming and collapsing duplicates, which is the normalization this role sends its ids verbatim to avoid re-implementing | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-ReopenRequest.Provenance | refuse | `ReopenRequest.Provenance` | labeling a reopen's history entry refuses | reopenIssue publishes no provenance member and the server writes its own fixed label (`bd serve: reopen issue`); see W-UpdateRequest.Provenance | D8 refuse-not-drop, D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-AddDependenciesRequest.SkipPerEdgeCycleCheck | refuse | `AddDependenciesRequest.SkipPerEdgeCycleCheck` `--no-cycle-check` | `bd dep add --no-cycle-check` refuses on the bulk --file path | the wire deliberately leaves SkipPerEdgeCycleCheck UNPUBLISHED and therefore false (internal/httpapi/dependency_edit.go). The single-edge spelling forwards false and only gates the post-hoc cycle warning, which the wire-backed CycleDetector serves, so it is served-with-note rather than refused | D7, D8 row 18, D9 L16 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.Status | retired | — | `bd update -s` used to refuse | RETIRED with client wave ga-7i6by. IssuePatchBody published `status` with upstream #5484 and this client's encoder now emits it; close and reopen still carry the lifecycle semantics a status write has nowhere to put — the reason and session under first-close-wins, the done-status normalization, the already-closed idempotence flag — and stay the operations to reach for. What this member serves is the status moved ALONGSIDE other fields in one transaction, which is the thing two calls cannot do | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.Assignee | retired | — | assignment and unassignment through update used to refuse | RETIRED with W-IssuePatch.Status (ga-7i6by). The EMPTY STRING is the half that makes this member more than a rename: it UNASSIGNS, so a client that skipped an empty value would turn a real edit into no edit at all. The anti-steal fence around it is the server's and is unchanged — a transfer away from a live foreign in-progress owner still refuses with already_claimed, and the two bypasses (`force_assignee_transfer` and a matched `expected_assignee`) are W-UpdateRequest.ForceAssigneeTransfer and the guard wave's own | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.Metadata | retired | — | a metadata patch used to refuse | RETIRED with W-IssuePatch.Status (ga-7i6by). IssuePatchBody publishes the same replace/merge/set/unset algebra MetadataPatch carries, member for member, so the client projects it rather than translating it and the ordering rule — merge, then set in key order, then unset, with replace refusing beside the other three — stays the ROLE's, applied by the same body a local workspace runs. The CLEAR is the one state the wire's own struct cannot spell (`omitempty` omits it), which is why the document is built as a map and an empty replacement travels as the empty document. The compare-and-set door is a different question and is served by its own accessor (issues.casMetadata, ga-7i6by's other half) | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.SpecID | refuse | `IssuePatch.SpecID` | a spec-id edit refuses | neither IssuePatchBody nor ApplyPatchBody publishes spec_id (internal/httpapi/update.go issuePatchMembers) | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.AwaitID | refuse | `IssuePatch.AwaitID` | an await-id edit refuses | neither IssuePatchBody nor ApplyPatchBody publishes await_id (internal/httpapi/update.go issuePatchMembers) | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.Owner | refuse | `IssuePatch.Owner` | an owner edit refuses ON updateIssue | IssuePatchBody excludes owner — which the document itself calls an accident of order rather than a decision, since ApplyPatchBody DOES publish it and issues:batchApply's update item carries it (internal/httpapi/update.go issuePatchMembers) | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.ClosedBySession | refuse | `IssuePatch.ClosedBySession` | a closed-by-session edit refuses | neither IssuePatchBody nor ApplyPatchBody publishes closed_by_session (internal/httpapi/update.go issuePatchMembers) | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.Persistence | refuse | `IssuePatch.Persistence` | a persistence-mode edit refuses | neither body publishes persistence: moving a row between planes mid-plan is a different act from writing its fields (internal/httpapi/update.go issuePatchMembers) | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.ParentID | retired | — | a parent re-hang through update used to refuse | RETIRED with W-IssuePatch.Status (ga-7i6by). It is ONE call rather than a remove-then-add pair, which is the whole reason the member exists: the two-call spelling leaves the issue parentless if the second call fails, and dependencies:add/remove — still the general write side of the graph over this wire — cannot express the atomic replacement. The empty string removes every parent-child edge, so it travels like `assignee`'s empty string rather than being skipped. The graph refusals it earns are the server's and arrive typed: a cycle through the issue's own descendant as the PLAIN dependency_cycle, and an existing edge of another type as dependency_exists | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateBatchRequest.Provenance | refuse | `CreateBatchRequest.Provenance` | labeling a batch create's history entry refuses | batchCreateIssues publishes actor and items only, and the server writes its own label; see W-UpdateRequest.Provenance. It is the one Provenance whose ABSENCE is visible in shipped history — the surface this role serves has always named its source file in the entry (`bd: create 3 issue(s) from plan.md`) | D8 row 14 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateBatchRequest.ForceIDPrefix | refuse | `CreateBatchRequest.ForceIDPrefix` `--force` | permitting explicit ids outside the workspace's configured prefix refuses | the wire publishes no such member — and could not honor one, since it publishes no explicit id for the flag to permit (W-BatchCreateItem.Issue). Dropping it would answer a request about WHERE ids may be written with a batch whose ids the server chose | D8 row 14 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-BatchCreateItem.Issue | refuse | `BatchCreateItem.Issue` | an item whose Issue populates any member outside the wire's eight refuses, naming the member | apigen.BatchCreateItem carries title, description, design, acceptance_criteria, priority, issue_type, assignee and labels and nothing else, while the role accepts far more of a types.Issue: an explicit id, the wisp flags, metadata, the storage class, every timestamp, the gate/molecule/event fields. ONE row rather than one per member because the reason is one reason — the wire's item vocabulary — and forty rows repeating it would say nothing a reader does not learn here. Exhaustiveness is held by REFLECTION instead: the client's carried and role-ignored tables are checked against types.Issue field by field, so a member added upstream is refused the day it lands rather than dropped until someone notices. The members the role ITSELF ignores on a create (ContentHash, RowVersion, lease, compaction, routing overrides, hydration flags) are not in this population and are not refused: a local create drops them too | D8 row 14 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateDependency.Reverse | refuse | `CreateDependency.Reverse` | an edge written from the target back to the new issue refuses ON A BATCH CREATE | BatchCreateDependency carries target_id and type only; dropping Reverse would write the edge in the OPPOSITE direction from the one asked for, which is a different graph. createIssue's CreateIssueDependency DOES publish it, and the single-create path sends it (internal/httpapi/spec BatchCreateDependency) | D8 row 14 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateDependency.Metadata | refuse | `CreateDependency.Metadata` | typed edge metadata refuses ON A BATCH CREATE | BatchCreateDependency publishes no metadata member, and a waits-for gate whose metadata was dropped is a readiness rule that silently does not hold. createIssue's edge publishes it, and the single-create path sends it verbatim (internal/httpapi/spec BatchCreateDependency) | D8 row 14 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateDependency.ThreadID | refuse | `CreateDependency.ThreadID` | associating an edge with a discussion thread refuses | neither BatchCreateDependency nor CreateIssueDependency publishes a thread member (internal/httpapi/spec BatchCreateDependency) | D8 row 14 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateRequest.IDPrefix | refuse | `CreateRequest.IDPrefix` | overriding the prefix an explicit id is checked against refuses | createIssue publishes no `id_prefix`, and the omission is the SERVER's decision rather than a gap (internal/httpapi/create.go): the field exists because a workspace's own config.yaml prefix wins over the database's and only a local front door can read that file, so a remote caller's config.yaml describes a workspace this server does not serve. Publishing it would let a caller override the served workspace's prefix rule from outside it. Dropping it instead would check the id against the SERVER's prefix while the caller believed it was checked against theirs — the same request, two different answers to 'may this workspace mint this id' | D8 row 16 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateRequest.Issue | refuse | `CreateRequest.Issue` | a create whose Issue populates any member outside the wire's twenty refuses, naming the member | createIssue publishes the whole create VOCABULARY — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue: the creation stamp (created_at, created_by), because a caller-supplied creation time makes the row disagree with the journal entry that records it and re-dating history is what an import is for; and spec_id, await_*, mol_type, wisp_type, work_type, storage_class, source_*, pinned, is_template and the event quartet, which this surface publishes on no operation, read or write. ONE row rather than one per member for W-BatchCreateItem.Issue's reason — the reason is one reason — and exhaustiveness is held by the same REFLECTION over types.Issue, sharing the role-ignored table with the batch so the two operations cannot disagree about what the ROLE drops. Issue.Comments and Issue.Dependencies are not in this population: the role itself refuses them, so a local create fails too and this is validation rather than divergence | D8 row 16 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-CreateItem.Issue | refuse | `CreateItem.Issue` | a create ITEM whose Issue populates any member outside the wire's twenty refuses, naming the member | ApplyCreateItem publishes exactly createIssue's create vocabulary — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue, for the reasons W-CreateRequest.Issue gives in full. It is a row of its OWN rather than a citation of that one because the operations are different: a caller auditing why their PLAN refuses must not be sent to a row about a single create, and the two can diverge the day either vocabulary moves. The partition itself is SHARED — one carried table, one role-ignored table, held against types.Issue by the same reflection — so they cannot disagree about what the wire carries or about what the role drops. Issue.Comments and Issue.Dependencies are not in this population and are refused as validation on both sides: edges in this role are ITEMS, so a create item has nowhere to put one at all | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-ApplyPatch.ParentID | refuse | `IssuePatch.ParentID` | a parent re-hang inside an update ITEM refuses, where the same member serves on updateIssue | ApplyPatchBody deliberately publishes no parent_id, and the absence is this operation's ONE-EDGE-ONE-SPELLING rule rather than a gap: a parent is a dep_add item of type parent-child, so the ORDER of every edge in a plan stays total and there is exactly one place an edge is written. The single patch has no ordering to express and publishes the member directly (W-IssuePatch.ParentID, retired by client wave ga-7i6by), which is why the same Go field is carried by one document and refused by the other. Refusing is not a loss of capability, only of spelling: a plan re-hangs a parent with a dep_add item, which is the atomic replacement in the position the caller declared it | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| W-IssuePatch.Labels | retired | `IssuePatch.Labels` | RETIRED — the whole ordered label edit crosses: `labels` replaces, `add_labels` adds, `remove_labels` removes | upstream #5510 published add_labels and remove_labels on IssuePatchBody and client wave ga-jpywb emits both, which is the retirement path this row named. The three travel as FLAT siblings where applyBatch nests them under one object, and the server assembles all three into ONE issueops.LabelPatch — so the algebra the role states (replace, then add, then remove; removal wins) is applied server-side and is never this client's to arrange. WHAT THE REFUSAL WAS PROTECTING is worth keeping after the refusal is gone: degrading an incremental edit onto the replace-only member would have meant reading the set, adding to it and writing it back, which silently drops any label another writer added in between. `bd label add` and every agent that tags work concurrently are exactly that caller, so the refusal was right for as long as the members did not exist — and it is the members that retire it, not a change of mind about the read-modify-write | D8 refuse-not-drop, open questions (tracked-refusal roadmap) | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | + +## Command and flag refusals (D7) + +Whole commands, and the flag modes of served commands, that dispatch onto methods the wire does not carry. They refuse early — before RunE — in the user's own command/flag vocabulary. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| F-ready-explain | refuse | `--explain` | `bd ready --explain` refuses | it dispatches onto raw GetBlockedIssues/GetIssuesByIDs/GetDependencyCounts/DetectCycles, three of which are on the unsupported allowlist | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-ready-mol | refuse | `--mol` | `bd ready --mol` refuses | its molecule subgraph load reaches findHierarchicalChildren, an IDPrefix SearchIssues shape the parent-walk bridge cannot express (E-IssueFilter.noShape). GetDependencyRecords and GetDependentsWithMetadata, which the same load also calls, stopped being the blocker when ga-b8ddd.30 flipped them onto the wire | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-ready-gated | refuse | `--gated` | `bd ready --gated` refuses | it dispatches onto a filtered SearchIssues shape the bridge cannot express, plus GetDependents | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-show-thread | refuse | `--thread` | `bd show --thread` refuses | showMessageThread renders each reply's sender, recipient, body and timestamp off GetDependentsWithMetadata, but ga-b8ddd.30 flipped that read onto getIssue's include_dependents parameter, which carries the collectDependents SHALLOW projection (id/status/type/priority/title + edge type only, be-4d36f2). Those fields come back zeroed over http and zero-timestamp replies sort ahead of the root — a silent-wrong degrade the refuse-over-degrade doctrine forbids. Retires with a full-dependent wire shape, a server-side ask | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-show-refs | refuse | `--refs` | `bd show --refs` refuses | showIssueRefs's --json marshals the full GetDependentsWithMetadata rows, but the wire answers the same collectDependents shallow projection, so created_at/assignee/description come back zeroed and the JSON differs from a local workspace. The text render consumes only the shallow fields, but the flag cannot be split from its --json mode, so the whole flag refuses rather than serve a divergent JSON silently | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-show-children | refuse | `--children` | `bd show --children` refuses | showIssueChildren's --json marshals the full GetDependentsWithMetadata rows, the same collectDependents shallow projection as --refs, so created_at/assignee/description come back zeroed over http; `bd children` refuses as a whole command for the same reason | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-mol-ready | refuse | — | `bd mol ready` refuses | it is the same runMolReadyGatedCore body as `bd ready --gated` | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-blocked | refuse | — | `bd blocked` refuses | it is raw GetBlockedIssues, which is on the unsupported allowlist | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-count | retired | — | RETIRED — `bd count` is SERVED whole | it said the command refuses because "issueops.Counter has no wire operation; a counts operation is a filed upstream ask", and that ask was DELIVERED: upstream #5508 published countIssues, client wave ga-icks1 wired the Counter accessor, and `count` moved from httpRefusedCommands into httpServedCommands. D8 row 20 and docs/reference/http-workspaces.md have said so since; this row was the last place that did not. Every flag the command publishes reaches a wire member — the whole predicate, the six instant bounds, the three emptiness checks, --include-infra, and the five --by-* flags as the one group_by parameter — so there is no refused mode left to name either. HOW IT ROTTED IS THE PART WORTH KEEPING. Its pin was TestClassifiedRefusedCommandsRefuseBeforeTheOSSPreRun, which walks httpRefusedCommands and drives every entry. The moment `count` left that table the pin stopped covering this row — it stayed LIVE BY NAME, so the well-formedness gate that resolves PinnedBy to a real test kept passing, and DEAD BY COVERAGE, so nothing anywhere asserted the row's claim. A ledger row can be false for a whole wave under a green pin, which is what TestFRowsAgreeWithTheCommandClassification now makes impossible | D7 (RETIRED), D8 row 20 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-serve | refuse | — | `bd serve` refuses against an http workspace | the OSS classifier would happily serve it from the opened store, and a bd serve re-serving a remote bd serve is a proxy chain nobody designed: run serve where the database is | D7 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-close | refuse | — | `bd close` is SERVED whole — single id, several ids and --claim-next — over issues:batchClose; it refuses only against a DOWN-LEVEL server that does not advertise issues.batchClose | the CLI's close front door routes every id, single-id included, through BatchCloser.CloseBatch, and Lifecycle.Close has zero CLI callers at tip. The wire now carries issues:batchClose, so the whole CloseBatchRequest — multi-item and the atomic ClaimNext included — is one wire call and one server-side transaction; nothing is composed or refused where the capability is present. Against a server too old to advertise issues.batchClose, servesBatchClose() reads the handshake snapshot and routes around the batch dial entirely, so no Preflight runs and no wire.ErrCapabilityAbsent is raised: the down-level leg's refuseUnservedCloseShape raises the STORE's own *ErrHTTPUnsupported (batchcloser.go), and cmd/bd's renderEscapedHTTPRefusal turns it into the capability-absent taxonomy (case 2) by scanning the served command's own capability list for the first token the server does not advertise — issues.batchClose, which is the token it then names to upgrade to. The single-item, no-ClaimNext shape still composes onto closeIssue in that down-level leg (see L18); the shapes that cannot compose refuse there. The item cap is L-close-cap | D8 row 17 (resolved, Wire), D9 L18, D9 L-close-cap | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | +| F-partial-id | refuse | — | partial-id resolution refuses with its own taxonomy text | SearchIssueIDs has no wire operation, and the client cannot tell a partial id from a full id that does not exist — so the refusal text covers both outcomes rather than falling through to a raw search error | D11 | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline | + +## Ready-request fields + +Members of the ready vocabulary the wire cannot express. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| E-ReadyRequest.MolType | refuse | `ReadyRequest.MolType` | a molecule-type restriction on ready work refuses | neither listReadyWork nor countReadyWork publishes a mol-type parameter, and the ready query applies molecule typing inside — so a dropped restriction would answer with the wider set of every molecule type | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ReadyRequest.Offset | refuse | `ReadyRequest.Offset` | a non-zero Offset on ready work refuses | the wire publishes no offset parameter, and the store-backed role refuses a non-zero Offset itself with a typed *ErrUnsupported. A ready request carries no keyset position, so there is no portable way to page ready work at all — a caller that must page pages a ListRequest instead | D9 L12, D7, D8, D12 | TestEncoderHonorsEveryTableDisposition | +| E-ReadyRequest.Brief | retired | — | RETIRED — the ready listing SENDS the projection; only the count still drops it | upstream #5586 published `brief` on GET /v0/beads/ready and GET /v0/beads/issues, which is the retirement path this row named. Both page encoders send the parameter now — readyTable, listTable and the ready bridge all map it — so the client asks for the projection it was handed and the server leaves the text columns unselected. The COUNT keeps the drop under E-ReadyRequest.Brief@countReadyWork, because countReadyWork publishes no such parameter and a cardinality has no rows to project. WHAT DID NOT RETIRE WITH IT IS THE WIRE HALF OF THE MARKER, and only that half: types.Issue.IsLitePartial is `json:"-"` and never crosses, so a projected page arrives on the transport byte-identical to a page of genuinely textless rows — the same absence getIssue's brief_deps carries, deferred upstream by #5549. THE CALLER-VISIBLE AMBIGUITY IS CLOSED, by client wave ga-f352s: `brief` is a parameter to the page decode rather than a field on anything, so httpReader hands it to wireRows (role_reader.go) and this client stamps IsLitePartial on every row of a page it ASKED to be projected — which is precisely what issueops.ListRequest.Brief's own leaf says a wire consumer distinguishes the two by — and never on a hydrated one. `bd list --long --brief` therefore prints "Description: (omitted by --brief)" over http exactly as it does locally, and TestHTTPCommentAndBriefRenderEndToEnd pins that line through the real binary | D9 (a degradation not in this table is a bug) | TestEncoderHonorsEveryTableDisposition | +| E-ReadyRequest.Brief@countReadyWork | degrade | `ReadyRequest.Brief` | the free-form-text projection is DROPPED on the COUNT, not refused: a cardinality has no rows to project | countReadyWork publishes no `brief` and answers a cardinality, so there is nothing to project: the parameter chooses what is HYDRATED and never which rows match, and a count reads neither. Dropping it is SkipLabels' and SkipCounts' argument exactly — the total is what it would have been — and refusing would make a performance flag a hard error on the one operation where it can cost nothing. The two page operations retired this drop and send the parameter; a caller that populates Brief for a count is asking a question a cardinality does not have | D9 (a degradation not in this table is a bug) | TestEncoderHonorsEveryTableDisposition | +| E-ReadyRequest.Limit@countReadyWork | refuse | `ReadyRequest.Limit` | a Limit on a ready COUNT refuses | countReadyWork publishes no limit parameter and ReadyCounter.CountReady refuses one itself: a cardinality has no page, and CountReady's identity with the listing it sizes stops being true the moment one is accepted. An explicit zero is refused with the rest — an unlimited count is the only kind there is | D9 L12, D7, D8, D8 row 2 | TestEncoderHonorsEveryTableDisposition | + +## List-request fields + +The listing publishes far more filters than the v0 wire does; every one the wire lacks refuses rather than dropping, because a dropped list filter widens the page invisibly. Two hydration opt-outs are dropped instead, with the argument for why that cannot be misread as a narrower or wider answer. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| E-ListRequest.TitleSearch | refuse | `ListRequest.TitleSearch` | a title search refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.SpecPrefix | refuse | `ListRequest.SpecPrefix` | a spec-id prefix restriction refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.IDFilter | refuse | `ListRequest.IDFilter` | an explicit id set on the LISTING refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml); the exact-ids question is getIssue's, reached through the SearchIssues bridge's exact-ids shape (D11), not through a listing filter | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.LabelPattern | refuse | `ListRequest.LabelPattern` | a glob label filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) — listReadyWork does publish label_pattern, which is exactly why the absence here has to refuse rather than fall through | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.LabelRegex | refuse | `ListRequest.LabelRegex` | a regex label filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) — as for LabelPattern, listReadyWork publishes label_regex and the listing does not | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.TitleContains | refuse | `ListRequest.TitleContains` | a title substring filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.DescContains | refuse | `ListRequest.DescContains` | a description substring filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.NotesContains | refuse | `ListRequest.NotesContains` | a notes substring filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.ExternalContains | refuse | `ListRequest.ExternalContains` | an external-ref substring filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.ExternalRef | refuse | `ListRequest.ExternalRef` | an exact external-ref filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.UpdatedAfter | refuse | `ListRequest.UpdatedAfter` | an updated-after bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) — only the created bounds are published | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.UpdatedBefore | refuse | `ListRequest.UpdatedBefore` | an updated-before bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) — only the created bounds are published | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.ClosedAfter | refuse | `ListRequest.ClosedAfter` | a closed-after bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.ClosedBefore | refuse | `ListRequest.ClosedBefore` | a closed-before bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.DeferAfter | refuse | `ListRequest.DeferAfter` | a defer-after bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.DeferBefore | refuse | `ListRequest.DeferBefore` | a defer-before bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.DueAfter | refuse | `ListRequest.DueAfter` | a due-after bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.DueBefore | refuse | `ListRequest.DueBefore` | a due-before bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.EmptyDesc | refuse | `ListRequest.EmptyDesc` | the empty-description predicate refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.NoAssignee | refuse | `ListRequest.NoAssignee` | the unassigned predicate refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) — listReadyWork publishes `unassigned`; the listing does not | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.NoLabels | refuse | `ListRequest.NoLabels` | the no-labels predicate refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.Priority | refuse | `ListRequest.Priority` | an exact priority filter refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) — listReadyWork publishes `priority`; the listing does not | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.PriorityMin | refuse | `ListRequest.PriorityMin` | a minimum-priority bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.PriorityMax | refuse | `ListRequest.PriorityMax` | a maximum-priority bound refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.PinnedFlag | refuse | `ListRequest.PinnedFlag` | selecting the pinned-FLAG rows refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml). The pinned STATUS is reachable through `status`; the flag is a separate predicate at any status and has no parameter | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.NoPinnedFlag | refuse | `ListRequest.NoPinnedFlag` | holding the unflagged predicate in place refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml). It changes nothing on a default listing and NARROWS under `all` or a pinned/hooked status — which is precisely when dropping it would widen the answer | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.ExcludeTypes | refuse | `ListRequest.ExcludeTypes` | a type exclusion refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) — listReadyWork publishes exclude_type; the listing publishes only the four include_* toggles | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.NoParent | refuse | `ListRequest.NoParent` | the top-level-only predicate refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.MolType | refuse | `ListRequest.MolType` | a molecule-type restriction refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.WispType | refuse | `ListRequest.WispType` | a wisp-type restriction refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml). The listing now ADMITS the wisp plane — include_ephemeral landed upstream and the encoder sends it (L1 retired) — so this refusal is no longer redundant with an invisible plane: it is the only thing standing between a caller and a listing that returns every wisp type when they named one | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.DeferredFlag | refuse | `ListRequest.DeferredFlag` | the deferred predicate refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.OverdueFlag | refuse | `ListRequest.OverdueFlag` | the overdue predicate refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml) | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.ReadyFlag | refuse | `ListRequest.ReadyFlag` | switching a listing onto the ready set refuses | ReadyFlag is not a filter but a change of QUESTION: it selects the blocker-aware ready query, which reads a narrower filter vocabulary than a ListRequest can describe. Over the wire that question is listReadyWork, a different operation with a different parameter table. Routing it there would have to decide, silently, which of this request's fields survive the crossing — so v1 refuses and the retirement path is an explicit route in the store, not a re-encode here | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.IncludeComments | refuse | `ListRequest.IncludeComments` | hydrating every row's comment bodies refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml). listIssues documents `comments` as always absent on its rows; a caller that needs an issue's comments reads getIssue with include_comments, one issue at a time | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.Offset | refuse | `ListRequest.Offset` | a non-zero Offset refuses | listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml). The portable page is the keyset position, which the pager walks (D8 row 1); the store-backed role refuses a non-zero Offset itself | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.SkipLabels | degrade | `ListRequest.SkipLabels` | the label-hydration opt-out is DROPPED, not refused: the wire hydrates labels either way | the listing publishes no hydration parameter, so the client cannot ask the server to skip the labels JOIN. Dropping it hands the caller MORE data than it asked for and never fewer — the row set, its order, Parent and the has-more verdict are exactly what they would have been — so it cannot be misread as a narrower or wider answer. It is a degradation rather than a refusal because refusing would make `bd list --skip-labels` a hard error for a performance flag whose only observable effect over http is that the server pays for a join. The retirement path is a hydration parameter on the wire | D9 (a degradation not in this table is a bug) | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.Brief | retired | — | RETIRED — `bd list` over http sends the projection | upstream #5586 published `brief` on GET /v0/beads/ready and GET /v0/beads/issues, which is the retirement path this row named. Both page encoders send the parameter now — readyTable, listTable and the ready bridge all map it — so the client asks for the projection it was handed and the server leaves the text columns unselected. The COUNT keeps the drop under E-ReadyRequest.Brief@countReadyWork, because countReadyWork publishes no such parameter and a cardinality has no rows to project. WHAT DID NOT RETIRE WITH IT IS THE WIRE HALF OF THE MARKER, and only that half: types.Issue.IsLitePartial is `json:"-"` and never crosses, so a projected page arrives on the transport byte-identical to a page of genuinely textless rows — the same absence getIssue's brief_deps carries, deferred upstream by #5549. THE CALLER-VISIBLE AMBIGUITY IS CLOSED, by client wave ga-f352s: `brief` is a parameter to the page decode rather than a field on anything, so httpReader hands it to wireRows (role_reader.go) and this client stamps IsLitePartial on every row of a page it ASKED to be projected — which is precisely what issueops.ListRequest.Brief's own leaf says a wire consumer distinguishes the two by — and never on a hydrated one. `bd list --long --brief` therefore prints "Description: (omitted by --brief)" over http exactly as it does locally, and TestHTTPCommentAndBriefRenderEndToEnd pins that line through the real binary | D9 (a degradation not in this table is a bug) | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.IncludeAllTypes | refuse | `ListRequest.IncludeAllTypes` | the never-hide-a-bead intent refuses | it is the UNION of four intents the wire does publish — include_templates, include_gates, include_infra, include_ephemeral — and encoding it as those four would be a client-side restatement of a union whose whole point is that a FIFTH suppression added to workapi is lifted by it automatically. The day that fifth lands, the restatement silently stops lifting it and the listing hides beads from a caller whose contract is that it hides none. Dropping it narrows the answer for the same reason, so it refuses until the wire publishes the intent itself | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | +| E-ListRequest.SkipCounts | degrade | `ListRequest.SkipCounts` | the cardinality-hydration opt-out is DROPPED, not refused: the wire hydrates the three counts either way | the same reasoning as SkipLabels, and here refusing would be actively wrong: EVERY text rendering of `bd list` sets SkipCounts (cmd/bd/list.go:284, and its proxied twin), so a refusal would kill the default listing over http. Dropping it means real counts arrive where zeros were expected, and a caller that must read a zero as UNKNOWN is safe reading a true count. The cost is the three aggregate joins — including the reverse-blocker one the embedded planner cannot index — paid on a page that prints none of them | D9 (a degradation not in this table is a bug) | TestEncoderHonorsEveryTableDisposition | + +## Query-request fields + +The boolean-query surface publishes almost its whole vocabulary; this is what is left over. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| E-QueryRequest.Offset | refuse | `QueryRequest.Offset` | a non-zero Offset on a boolean query refuses | queryIssues publishes no offset parameter — the document deliberately omits one, because the two database sources this server can be built on disagree about whether they can honor it — and the store-backed role refuses one uniformly | D9 L12, D7, D8 | TestEncoderHonorsEveryTableDisposition | + +## Search bridge / IssueFilter (D4, D11) + +The off-role SearchIssues bridge serves two shapes and no others: the exact-ids fast path and the parent descendant walk. Every other populated IssueFilter member is a filter the bridge would have to drop to answer, so it refuses. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| E-IssueFilter.Status | refuse | `IssueFilter.Status` | a populated IssueFilter.Status refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Statuses | refuse | `IssueFilter.Statuses` | a populated IssueFilter.Statuses refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Priority | refuse | `IssueFilter.Priority` | a populated IssueFilter.Priority refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.IssueType | refuse | `IssueFilter.IssueType` | a populated IssueFilter.IssueType refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Assignee | refuse | `IssueFilter.Assignee` | a populated IssueFilter.Assignee refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Labels | refuse | `IssueFilter.Labels` | a populated IssueFilter.Labels refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.LabelsAny | refuse | `IssueFilter.LabelsAny` | a populated IssueFilter.LabelsAny refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.ExcludeLabels | refuse | `IssueFilter.ExcludeLabels` | a populated IssueFilter.ExcludeLabels refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.LabelPattern | refuse | `IssueFilter.LabelPattern` | a populated IssueFilter.LabelPattern refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.LabelRegex | refuse | `IssueFilter.LabelRegex` | a populated IssueFilter.LabelRegex refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.TitleSearch | refuse | `IssueFilter.TitleSearch` | a populated IssueFilter.TitleSearch refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.IDPrefix | refuse | `IssueFilter.IDPrefix` | a populated IssueFilter.IDPrefix refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.SpecIDPrefix | refuse | `IssueFilter.SpecIDPrefix` | a populated IssueFilter.SpecIDPrefix refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.TitleContains | refuse | `IssueFilter.TitleContains` | a populated IssueFilter.TitleContains refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.DescriptionContains | refuse | `IssueFilter.DescriptionContains` | a populated IssueFilter.DescriptionContains refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.NotesContains | refuse | `IssueFilter.NotesContains` | a populated IssueFilter.NotesContains refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.ExternalRefContains | refuse | `IssueFilter.ExternalRefContains` | a populated IssueFilter.ExternalRefContains refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.ExternalRef | refuse | `IssueFilter.ExternalRef` | a populated IssueFilter.ExternalRef refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.CreatedAfter | refuse | `IssueFilter.CreatedAfter` | a populated IssueFilter.CreatedAfter refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.CreatedBefore | refuse | `IssueFilter.CreatedBefore` | a populated IssueFilter.CreatedBefore refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.UpdatedAfter | refuse | `IssueFilter.UpdatedAfter` | a populated IssueFilter.UpdatedAfter refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.UpdatedBefore | refuse | `IssueFilter.UpdatedBefore` | a populated IssueFilter.UpdatedBefore refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.ClosedAfter | refuse | `IssueFilter.ClosedAfter` | a populated IssueFilter.ClosedAfter refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.ClosedBefore | refuse | `IssueFilter.ClosedBefore` | a populated IssueFilter.ClosedBefore refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.StartedAfter | refuse | `IssueFilter.StartedAfter` | a populated IssueFilter.StartedAfter refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.StartedBefore | refuse | `IssueFilter.StartedBefore` | a populated IssueFilter.StartedBefore refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.AfterCreatedAt | refuse | `IssueFilter.AfterCreatedAt` | a populated IssueFilter.AfterCreatedAt refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.AfterID | refuse | `IssueFilter.AfterID` | a populated IssueFilter.AfterID refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.AfterPriority | refuse | `IssueFilter.AfterPriority` | a populated IssueFilter.AfterPriority refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.EmptyDescription | refuse | `IssueFilter.EmptyDescription` | a populated IssueFilter.EmptyDescription refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.NoAssignee | refuse | `IssueFilter.NoAssignee` | a populated IssueFilter.NoAssignee refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.NoLabels | refuse | `IssueFilter.NoLabels` | a populated IssueFilter.NoLabels refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.PriorityMin | refuse | `IssueFilter.PriorityMin` | a populated IssueFilter.PriorityMin refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.PriorityMax | refuse | `IssueFilter.PriorityMax` | a populated IssueFilter.PriorityMax refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.SourceRepo | refuse | `IssueFilter.SourceRepo` | a populated IssueFilter.SourceRepo refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Ephemeral | refuse | `IssueFilter.Ephemeral` | a populated IssueFilter.Ephemeral refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.EphemeralTier | refuse | `IssueFilter.EphemeralTier` | a populated IssueFilter.EphemeralTier refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Pinned | refuse | `IssueFilter.Pinned` | a populated IssueFilter.Pinned refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.IsBlocked | refuse | `IssueFilter.IsBlocked` | a populated IssueFilter.IsBlocked refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.IsTemplate | refuse | `IssueFilter.IsTemplate` | a populated IssueFilter.IsTemplate refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.NoParent | refuse | `IssueFilter.NoParent` | a populated IssueFilter.NoParent refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.MolType | refuse | `IssueFilter.MolType` | a populated IssueFilter.MolType refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.WispType | refuse | `IssueFilter.WispType` | a populated IssueFilter.WispType refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.ExcludeStatus | refuse | `IssueFilter.ExcludeStatus` | a populated IssueFilter.ExcludeStatus refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.ExcludeTypes | refuse | `IssueFilter.ExcludeTypes` | a populated IssueFilter.ExcludeTypes refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Deferred | refuse | `IssueFilter.Deferred` | a populated IssueFilter.Deferred refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.DeferAfter | refuse | `IssueFilter.DeferAfter` | a populated IssueFilter.DeferAfter refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.DeferBefore | refuse | `IssueFilter.DeferBefore` | a populated IssueFilter.DeferBefore refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.DueAfter | refuse | `IssueFilter.DueAfter` | a populated IssueFilter.DueAfter refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.DueBefore | refuse | `IssueFilter.DueBefore` | a populated IssueFilter.DueBefore refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Overdue | refuse | `IssueFilter.Overdue` | a populated IssueFilter.Overdue refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.MetadataFields | refuse | `IssueFilter.MetadataFields` | a populated IssueFilter.MetadataFields refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.HasMetadataKey | refuse | `IssueFilter.HasMetadataKey` | a populated IssueFilter.HasMetadataKey refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.IncludeDependencies | refuse | `IssueFilter.IncludeDependencies` | a populated IssueFilter.IncludeDependencies refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.SkipLabels | refuse | `IssueFilter.SkipLabels` | a populated IssueFilter.SkipLabels refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.SkipCounts | refuse | `IssueFilter.SkipCounts` | a populated IssueFilter.SkipCounts refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.SkipWisps | refuse | `IssueFilter.SkipWisps` | a populated IssueFilter.SkipWisps refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.NoIDShrink | refuse | `IssueFilter.NoIDShrink` | a populated IssueFilter.NoIDShrink refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Offset | refuse | `IssueFilter.Offset` | a populated IssueFilter.Offset refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.SortBy | refuse | `IssueFilter.SortBy` | a populated IssueFilter.SortBy refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.SortDesc | refuse | `IssueFilter.SortDesc` | a populated IssueFilter.SortDesc refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.MaxRows | refuse | `IssueFilter.MaxRows` | a populated IssueFilter.MaxRows refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.MaxRowsSource | refuse | `IssueFilter.MaxRowsSource` | a populated IssueFilter.MaxRowsSource refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.Lite | refuse | `IssueFilter.Lite` | a populated IssueFilter.Lite refuses on the SearchIssues bridge | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses | D8 (off-role raw methods), D4, D11, D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.shapeConflict | refuse | — | an id set and a ParentID together refuse — the pair is NEITHER expressible shape | the exact-ids shape dials getIssue per id and applies no filter at all, so honoring the parent restriction would mean discarding answers client-side; the descendant walk dials listIssues?parent=, which publishes no id filter, so honoring the ids would mean intersecting two answers no single wire call asked for. Both readings are drops wearing a filter's clothes, so the combination refuses before a shape is chosen | D4, D11, D9 L12 | TestASearchFilterMatchingNeitherShapeRefuses | +| E-IssueFilter.Limit@exactIDs | refuse | `IssueFilter.Limit` | a Limit alongside an id set refuses | getIssue answers one row per call, so a Limit could only be applied by discarding answers the caller named explicitly | D11 | TestEncoderHonorsEveryTableDisposition | +| E-IssueFilter.IDs@bound | refuse | `IssueFilter.IDs` | an id set larger than MaxExactIDs refuses | the exact-ids shape costs one getIssue per id, so an unbounded set is an unbounded burst at one shared server. The bound is 100 and is a GUESS: open question 6 asks for the real call-site fan-out to be measured before GA | D11, open question 6 | TestTheExactIDsFanOutIsBounded | +| E-IssueFilter.noShape | refuse | — | a raw SearchIssues call matching neither expressible shape refuses | the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses. A filter naming no ids and no parent — the unbounded `everything` shape included — is not one of them | D8 (off-role raw methods), D4, D11, D9 L12 | TestASearchFilterMatchingNeitherShapeRefuses | +| E-bridge-parent-shape | retired | — | RETIRED — the ParentID-only shape was unreachable from `bd list --parent` as the CLI builds it, and the walk refused over http | the escalation this row raised (ga-2ieek) was resolved by spec revision 6b428bf63 as semantic inversion: the wire publishes INTENTS (`all`, `include_templates`, `include_gates`, `include_infra`) rather than materialized exclusions, and the server's role re-derives the exclusions from the same builder against its own authoritative vocabulary. The bridge therefore inverts the derived members back to intents instead of encoding them, and the objection recorded here — that recognizing the baseline would be an unsanctioned second encoder — is answered by VERIFYING each candidate through workapi.BuildListFilter itself rather than reimplementing it. The live rules are the P-IssueFilter.* population | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | + +## Parent-walk derived defaults (D4) + +The descendant walk reads the same IssueFilter as the exact-ids shape and reads it differently. The wire publishes intents (all, include_templates, include_gates, include_infra) and the server re-derives the exclusions; the bridge inverts the derived defaults back to intents and refuses anything the inversion cannot account for. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| P-IssueFilter.ExcludeStatus | refuse | `IssueFilter.ExcludeStatus` | a status exclusion that is not the derived default refuses | listIssues publishes no exclude_status: the wire publishes the INTENT (`all`) and the server re-derives the exclusions from the same builder against its own authoritative vocabulary, which additionally heals L7's degraded client-side set for the walk. An exclusion list no intent reproduces is therefore unstatable, and dropping it would widen the listing to closed work | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.Pinned | refuse | `IssueFilter.Pinned` | a pinned predicate that is not the derived default refuses | the pinned default is the FOURTH derived member and has no parameter of its own: `--pinned` selects the flagged rows and `--no-pinned` holds the unflagged predicate in place under `--all`, and the wire can express neither. Its derived value is a function of the `all` intent alone — upstream #5333 stopped an every-status selector from forcing it, so `--status all` and `--all` are now one filter and one wire question — and a value that intent does not reproduce is a user's own predicate, which NARROWS, and that is precisely when dropping it would answer a different question | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.IsTemplate | refuse | `IssueFilter.IsTemplate` | a template predicate that is not the derived default refuses | listIssues publishes include_templates, an intent, not an is_template predicate. `&false` is what the absent flag derives and sends nothing; nil is what `--include-templates` derives and sends the flag; `&true` selects templates ONLY, which no intent on this operation can say | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.ExcludeTypes | refuse | `IssueFilter.ExcludeTypes` | a type exclusion beyond the derived gate and infra members refuses | listIssues publishes include_gates and include_infra — intents — and no exclude_type. The gate member and the whole infra vocabulary are what their absent flags derive; a leftover member is a user's `--exclude-type`, and dropping it would return the type they asked to hide | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.Ephemeral | refuse | `IssueFilter.Ephemeral` | an ephemeral predicate that is not the derived default refuses | BuildListFilter sets it only for an infra `--type`, from the same flag the walk already encodes; the wire publishes no ephemeral PREDICATE on the listing — include_ephemeral is an intent that ADMITS the plane, not a selector that restricts to it — so any other value is unstatable | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.SkipWisps | refuse | `IssueFilter.SkipWisps` | a wisp-merge opt-out that is not the derived default refuses | NARROWED by client wave ga-mijra, which closed the client-side gap this row used to record. The walk now encodes include_ephemeral — SkipWisps going false IS that intent, and it is read back off the member the way every other derived default is — so a wisp-inclusive descendant listing crosses instead of refusing, which is the shape gc's TierBoth reads take. What still refuses is a SkipWisps no set of intents reproduces: holding the plane out while include_infra or an infra `--type` admits it. BuildListFilter never builds that pair, so it is a hand-made filter rather than a flag combination, and dropping the opt-out would merge a plane the caller asked to skip | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.SortBy | degrade | `IssueFilter.SortBy` | the walk's sort key is DROPPED | findAllDescendants accumulates every level into a map keyed by id, so no per-level order reaches the answer: the walk's own assembly discards it before the caller sees it. This is a drop with nothing to drop, and the rendering order is the tree renderer's | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek, D9 | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.SortDesc | degrade | `IssueFilter.SortDesc` | the walk's sort direction is DROPPED | the other half of the order findAllDescendants discards; see P-IssueFilter.SortBy | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek, D9 | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.SkipLabels | degrade | `IssueFilter.SkipLabels` | the label-hydration opt-out is DROPPED | the listing publishes no hydration parameter, so the client cannot ask the server to skip the labels join. Dropping it hands the caller MORE data and never fewer rows, so it cannot be misread as a narrower or wider answer | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek, D9 | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.SkipCounts | degrade | `IssueFilter.SkipCounts` | the cardinality-hydration opt-out is DROPPED | the same absence as SkipLabels, and here refusing would be actively wrong: every text rendering of `bd list` sets it, so a refusal would kill the walk's DEFAULT rendering — the one behavior D4 classifies the walk as served in order to keep | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek, D9 | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.Priority | refuse | `IssueFilter.Priority` | a populated IssueFilter.Priority refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.LabelPattern | refuse | `IssueFilter.LabelPattern` | a populated IssueFilter.LabelPattern refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.LabelRegex | refuse | `IssueFilter.LabelRegex` | a populated IssueFilter.LabelRegex refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.TitleSearch | refuse | `IssueFilter.TitleSearch` | a populated IssueFilter.TitleSearch refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.IDPrefix | refuse | `IssueFilter.IDPrefix` | a populated IssueFilter.IDPrefix refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.SpecIDPrefix | refuse | `IssueFilter.SpecIDPrefix` | a populated IssueFilter.SpecIDPrefix refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.TitleContains | refuse | `IssueFilter.TitleContains` | a populated IssueFilter.TitleContains refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.DescriptionContains | refuse | `IssueFilter.DescriptionContains` | a populated IssueFilter.DescriptionContains refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.NotesContains | refuse | `IssueFilter.NotesContains` | a populated IssueFilter.NotesContains refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.ExternalRefContains | refuse | `IssueFilter.ExternalRefContains` | a populated IssueFilter.ExternalRefContains refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.ExternalRef | refuse | `IssueFilter.ExternalRef` | a populated IssueFilter.ExternalRef refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.UpdatedAfter | refuse | `IssueFilter.UpdatedAfter` | a populated IssueFilter.UpdatedAfter refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.UpdatedBefore | refuse | `IssueFilter.UpdatedBefore` | a populated IssueFilter.UpdatedBefore refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.ClosedAfter | refuse | `IssueFilter.ClosedAfter` | a populated IssueFilter.ClosedAfter refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.ClosedBefore | refuse | `IssueFilter.ClosedBefore` | a populated IssueFilter.ClosedBefore refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.StartedAfter | refuse | `IssueFilter.StartedAfter` | a populated IssueFilter.StartedAfter refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.StartedBefore | refuse | `IssueFilter.StartedBefore` | a populated IssueFilter.StartedBefore refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.AfterCreatedAt | refuse | `IssueFilter.AfterCreatedAt` | a populated IssueFilter.AfterCreatedAt refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.AfterID | refuse | `IssueFilter.AfterID` | a populated IssueFilter.AfterID refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.AfterPriority | refuse | `IssueFilter.AfterPriority` | a populated IssueFilter.AfterPriority refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.EmptyDescription | refuse | `IssueFilter.EmptyDescription` | a populated IssueFilter.EmptyDescription refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.NoAssignee | refuse | `IssueFilter.NoAssignee` | a populated IssueFilter.NoAssignee refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.NoLabels | refuse | `IssueFilter.NoLabels` | a populated IssueFilter.NoLabels refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.PriorityMin | refuse | `IssueFilter.PriorityMin` | a populated IssueFilter.PriorityMin refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.PriorityMax | refuse | `IssueFilter.PriorityMax` | a populated IssueFilter.PriorityMax refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.SourceRepo | refuse | `IssueFilter.SourceRepo` | a populated IssueFilter.SourceRepo refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.EphemeralTier | refuse | `IssueFilter.EphemeralTier` | a populated IssueFilter.EphemeralTier refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.IsBlocked | refuse | `IssueFilter.IsBlocked` | a populated IssueFilter.IsBlocked refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.NoParent | refuse | `IssueFilter.NoParent` | a populated IssueFilter.NoParent refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.MolType | refuse | `IssueFilter.MolType` | a populated IssueFilter.MolType refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.WispType | refuse | `IssueFilter.WispType` | a populated IssueFilter.WispType refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.Deferred | refuse | `IssueFilter.Deferred` | a populated IssueFilter.Deferred refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.DeferAfter | refuse | `IssueFilter.DeferAfter` | a populated IssueFilter.DeferAfter refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.DeferBefore | refuse | `IssueFilter.DeferBefore` | a populated IssueFilter.DeferBefore refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.DueAfter | refuse | `IssueFilter.DueAfter` | a populated IssueFilter.DueAfter refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.DueBefore | refuse | `IssueFilter.DueBefore` | a populated IssueFilter.DueBefore refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.Overdue | refuse | `IssueFilter.Overdue` | a populated IssueFilter.Overdue refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.IncludeDependencies | refuse | `IssueFilter.IncludeDependencies` | a populated IssueFilter.IncludeDependencies refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.NoIDShrink | refuse | `IssueFilter.NoIDShrink` | a populated IssueFilter.NoIDShrink refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.Offset | refuse | `IssueFilter.Offset` | a populated IssueFilter.Offset refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.Lite | refuse | `IssueFilter.Lite` | a populated IssueFilter.Lite refuses on the descendant walk | listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek | TestTheParentWalkInvertsTheDerivedDefaults | +| P-IssueFilter.unrecognized | refuse | — | a descendant-walk filter whose intents this client cannot reproduce at all refuses | the inversion proves a candidate by RE-RUNNING workapi.BuildListFilter and comparing the derived members, so a candidate the builder itself rejects — an unknown status, a vocabulary the client's degraded copy does not carry (L7) — is never compared. When every candidate is rejected that way there is no member to blame, and refusing on the recognition is the only honest answer | D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek, D9 L7 | TestTheParentWalkInvertsTheDerivedDefaults | + +## Ready bridge / WorkFilter (D8) + +The throwaway bridge that maps a WorkFilter back onto ready parameters until the front door moves onto issueops.Reader. It refuses every field it cannot express. + +| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test | +|---|---|---|---|---|---|---| +| E-WorkFilter.Lite | retired | — | RETIRED — the ready bridge maps Lite onto `brief`, the same parameter ReadyRequest.Brief now sends | upstream #5586 published `brief` on GET /v0/beads/ready and GET /v0/beads/issues, which is the retirement path this row named. Both page encoders send the parameter now — readyTable, listTable and the ready bridge all map it — so the client asks for the projection it was handed and the server leaves the text columns unselected. The COUNT keeps the drop under E-ReadyRequest.Brief@countReadyWork, because countReadyWork publishes no such parameter and a cardinality has no rows to project. WHAT DID NOT RETIRE WITH IT IS THE WIRE HALF OF THE MARKER, and only that half: types.Issue.IsLitePartial is `json:"-"` and never crosses, so a projected page arrives on the transport byte-identical to a page of genuinely textless rows — the same absence getIssue's brief_deps carries, deferred upstream by #5549. THE CALLER-VISIBLE AMBIGUITY IS CLOSED, by client wave ga-f352s: `brief` is a parameter to the page decode rather than a field on anything, so httpReader hands it to wireRows (role_reader.go) and this client stamps IsLitePartial on every row of a page it ASKED to be projected — which is precisely what issueops.ListRequest.Brief's own leaf says a wire consumer distinguishes the two by — and never on a hydrated one. `bd list --long --brief` therefore prints "Description: (omitted by --brief)" over http exactly as it does locally, and TestHTTPCommentAndBriefRenderEndToEnd pins that line through the real binary | D9 (a degradation not in this table is a bug) | TestEncoderHonorsEveryTableDisposition | +| E-WorkFilter.Status | refuse | `WorkFilter.Status` | a ready-work status that is not the derived default refuses; the default (open only) is DERIVED server-side and drops | listReadyWork publishes no status parameter: handleReady decodes a status-LESS request and the server re-derives ready work's status through workapi.BuildReadyFilter, which is unconditionally StatusOpen — open work only, the set `bd list --ready` shows. The client sends that one derived value as the absence the server reads it back from, so every real `bd ready` and `bd ready --json` (whose filter BuildReadyFilter always stamps StatusOpen) round-trips to the identical rows. Any other status is unstatable and refuses: a named status would answer over the query's open-only default rather than the set named, and the empty status is the storage layer's own open+in_progress default, which this operation cannot express either | D8 (off-role ready bridge), D9 L12, D4 (derived-default inversion, escalation ga-2ieek) | TestEncoderHonorsEveryTableDisposition | +| E-WorkFilter.Statuses | refuse | `WorkFilter.Statuses` | a multi-status OR set on ready work refuses | listReadyWork publishes no status parameter, and an OR-set is neither the server's derived default (open only) nor anything the wire can carry — dropping it would widen the answer to statuses the caller did not ask for, so it refuses alongside a non-default Status (L12) | D8 (off-role ready bridge), D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-WorkFilter.MoleculeID | refuse | `WorkFilter.MoleculeID` | restricting ready work to one molecule's direct children refuses | listReadyWork publishes `parent` for the RECURSIVE descendant restriction and nothing for direct membership; the two are different sets, so `parent` is not a substitute | D8 (off-role ready bridge), D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-WorkFilter.MolType | refuse | `WorkFilter.MolType` | a molecule-type restriction on ready work refuses | no wire parameter — the same absence E-ReadyRequest.MolType records, reached from the other source shape | D8 (off-role ready bridge), D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-WorkFilter.WispType | refuse | `WorkFilter.WispType` | a wisp-type restriction on ready work refuses | listReadyWork publishes include_ephemeral, which admits the wisp plane wholesale, and nothing that selects a wisp TYPE within it | D8 (off-role ready bridge), D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-WorkFilter.ExcludeIDs | refuse | `WorkFilter.ExcludeIDs` | an id exclusion set on ready work refuses | listReadyWork publishes no id-exclusion parameter; the set is what the external-dependency policy decorator (upstream #4753) injects to hide sources behind unsatisfied external blockers, and dropping it would widen the answer to exactly the issues the caller's policy excluded (L12). A server that advertises policy.external_dependencies applies the policy itself, so the client never builds the set for it | D8 (off-role ready bridge), D9 L12 | TestEncoderHonorsEveryTableDisposition | +| E-WorkFilter.Offset | refuse | `WorkFilter.Offset` | a non-zero Offset on ready work refuses | no wire parameter, and ready work carries no keyset position to page by; see E-ReadyRequest.Offset | D8 (off-role ready bridge), D9 L12 | TestEncoderHonorsEveryTableDisposition | + diff --git a/internal/httpapi/spec/BUILD.bazel b/internal/httpapi/spec/BUILD.bazel index 46a8bc94c..b734489cd 100644 --- a/internal/httpapi/spec/BUILD.bazel +++ b/internal/httpapi/spec/BUILD.bazel @@ -7,3 +7,14 @@ go_library( importpath = "github.com/steveyegge/beads/internal/httpapi/spec", visibility = ["//:__subpackages__"], ) + +# //internal/httpclient/encode:encode_test's bijection gate reads the wire +# contract's published parameter set. It reads it through spec.OpenAPIV0() +# (the go:embed above), not a relative os.ReadFile path, so no `data` +# dependency on this file is actually needed for that one read -- this export +# stays as defense in depth for any other reader of the raw YAML that package +# gains. +exports_files( + ["openapi.v0.yaml"], + visibility = ["//internal/httpclient/encode:__pkg__"], +) diff --git a/internal/httpapi/wireshape/BUILD.bazel b/internal/httpapi/wireshape/BUILD.bazel index cdae05960..b643aa0f6 100644 --- a/internal/httpapi/wireshape/BUILD.bazel +++ b/internal/httpapi/wireshape/BUILD.bazel @@ -24,3 +24,13 @@ go_test( embed = [":wireshape"], deps = ["//internal/httpapi"], ) + +# //internal/httpclient/wire:wire_test's revision-tolerance coverage test +# (TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember) +# derives the set of schemas a legacy pre-#6053 server's bare-integer +# `revision` can appear on directly from this committed golden digest, so it +# must be readable as data under `bazel test`. +exports_files( + ["testdata/golden.json"], + visibility = ["//internal/httpclient/wire:__pkg__"], +) diff --git a/internal/httpclient/BUILD.bazel b/internal/httpclient/BUILD.bazel new file mode 100644 index 000000000..b93917c93 --- /dev/null +++ b/internal/httpclient/BUILD.bazel @@ -0,0 +1,55 @@ +load("@rules_go//go:def.bzl", "go_library", "go_test") + +go_library( + name = "httpclient", + srcs = [ + "backend_credential.go", + "ca.go", + "ca_permissions_other.go", + "ca_permissions_unix.go", + "credential.go", + "target.go", + ], + importpath = "github.com/steveyegge/beads/internal/httpclient", + visibility = ["//:__subpackages__"], + deps = [ + "//internal/configfile", + "//internal/creds", + "//internal/httpclient/wire", + "//internal/storage/backends", + "@org_golang_x_net//http/httpproxy", + "@org_golang_x_net//idna", + ], +) + +go_test( + name = "httpclient_test", + srcs = [ + "backend_credential_test.go", + "ca_permissions_unix_test.go", + "ca_test.go", + "ca_wrong_ca_test.go", + "credential_source_test.go", + "credential_test.go", + "helpers_test.go", + "target_test.go", + ], + embed = [":httpclient"], + deps = [ + "//internal/httpapi/apigen", + "//internal/storage/backends", + ], +) + +# --- begin go_srcs (managed by tools/bazel/go_srcs.py; run `make bazel-sync`) --- + +filegroup( + name = "go_srcs", + srcs = glob( + ["**/*.go"], + allow_empty = True, + ), + visibility = ["//:__subpackages__"], +) + +# --- end go_srcs --- diff --git a/internal/httpclient/backend_credential.go b/internal/httpclient/backend_credential.go new file mode 100644 index 000000000..f17b15278 --- /dev/null +++ b/internal/httpclient/backend_credential.go @@ -0,0 +1,87 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). See +// internal/storage/backends/backends.go's OpenOptions.Credential doc: "S1 +// does not add a RequireCredential knob to enforce the multi-tenant rule +// mechanically — that is deferred to S2." This file is that knob, plus the +// wrapper type a caller uses to carry a CredentialProvider through +// backends.OpenOptions in the first place. +package httpclient + +import ( + "errors" + "fmt" + "net/url" + + "github.com/steveyegge/beads/internal/storage/backends" +) + +// ProvidedCredential adapts an embedder-supplied CredentialProvider into a +// backends.Credential — the opaque per-open marker interface OpenOptions +// carries — so a multi-tenant embedder (for example gc, Gas City: one process +// serving many workspaces, called "cities") can route a per-workspace +// credential through backends.OpenOptions without the backends package, or +// this package's own OpenWith wiring, needing to agree on anything but this +// one wrapper type. +// +// Provider is required. A ProvidedCredential with a nil Provider is refused +// by ResolveCredential exactly as a missing credential is in REQUIRE mode: a +// present-but-empty wrapper would otherwise look like "a credential was +// supplied" to a caller checking opts.Credential != nil, while actually +// authorizing nothing — the same silent-downgrade risk +// OpenOptions.Credential's own doc comment warns about for the ambient +// fallback case. +type ProvidedCredential struct { + Provider CredentialProvider +} + +// BackendCredential satisfies backends.Credential. It is a zero-cost marker +// with no behavior; see that interface's doc comment for why it exists. +func (ProvidedCredential) BackendCredential() {} + +// ErrCredentialRequired reports a REQUIRE-mode resolution with no usable +// credential: either opts.Credential was nil, or it was a ProvidedCredential +// whose Provider was nil. See ResolveCredential. +var ErrCredentialRequired = errors.New("httpclient: a credential is required for this open, but none was supplied; the ambient bearer ladder is disabled in REQUIRE mode") + +// ResolveCredential turns opts.Credential into the CredentialProvider a Dial +// authorizes requests with. +// +// Four cases: +// +// - opts.Credential is nil and require is false: the default single-tenant +// CLI posture. Returns NewBearerProvider(base), the ambient bearer ladder +// (BEADS_HTTP_TOKEN, then BEADS_HTTP_TOKEN_COMMAND, then the credentials +// file, then no credential at all). +// - opts.Credential is nil and require is true: ErrCredentialRequired. This +// is the knob a multi-tenant embedder sets so a missing per-workspace +// credential is a loud refusal instead of a silent fall-through to +// process-global ambient environment — which cannot distinguish one +// tenant's workspace from another's, exactly the risk +// OpenOptions.Credential's doc comment names. +// - opts.Credential is a ProvidedCredential with a non-nil Provider: that +// Provider is returned directly, regardless of require. An embedder that +// took the trouble to supply one has already satisfied REQUIRE mode's +// purpose. +// - opts.Credential is a ProvidedCredential with a nil Provider, or any +// other non-nil backends.Credential this package does not recognize: +// refused. A nil Provider is ErrCredentialRequired (see its doc); any +// other type is backends.ErrUnsupportedCredential, wrapped with the +// concrete type so the refusal is legible, per the contract +// Backend.OpenWith implementations must follow (see +// internal/storage/backends/backends.go and +// TestBackendOpenWithRefusesUnsupportedCredentialType). +func ResolveCredential(opts backends.OpenOptions, base *url.URL, require bool) (CredentialProvider, error) { + if opts.Credential == nil { + if require { + return nil, ErrCredentialRequired + } + return NewBearerProvider(base), nil + } + pc, ok := opts.Credential.(ProvidedCredential) + if !ok { + return nil, fmt.Errorf("httpclient: credential %T: %w", opts.Credential, backends.ErrUnsupportedCredential) + } + if pc.Provider == nil { + return nil, fmt.Errorf("httpclient: ProvidedCredential.Provider is nil: %w", ErrCredentialRequired) + } + return pc.Provider, nil +} diff --git a/internal/httpclient/backend_credential_test.go b/internal/httpclient/backend_credential_test.go new file mode 100644 index 000000000..25d5d051f --- /dev/null +++ b/internal/httpclient/backend_credential_test.go @@ -0,0 +1,109 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). +package httpclient + +import ( + "context" + "errors" + "net/http" + "testing" + + "github.com/steveyegge/beads/internal/storage/backends" +) + +// stubProvider is a minimal CredentialProvider for tests: it stamps a fixed +// header value so a test can prove WHICH provider ResolveCredential returned, +// without pulling in the bearer ladder's env/file machinery. +type stubProvider struct{ tag string } + +func (s stubProvider) Authorize(_ context.Context, req *http.Request) error { + req.Header.Set("X-Stub-Provider", s.tag) + return nil +} + +func (s stubProvider) Refresh(context.Context) (bool, error) { return false, nil } + +// fixtureBackendCredential is a backends.Credential this package does not +// recognise — the same role fixtureNarrowCredential plays in +// internal/storage/backends/open_with_test.go, reused here so this test does +// not depend on that package's unexported fixture. +type fixtureBackendCredential struct{} + +func (fixtureBackendCredential) BackendCredential() {} + +func TestResolveCredentialNilNotRequiredFallsBackToTheAmbientLadder(t *testing.T) { + clearCredentialEnvironment(t) + t.Setenv(TokenEnv, "ambient-token") + base := mustParseURL(t, "http://127.0.0.1:8080") + + cp, err := ResolveCredential(backends.OpenOptions{}, base, false) + if err != nil { + t.Fatalf("ResolveCredential: %v", err) + } + if _, ok := cp.(*BearerProvider); !ok { + t.Fatalf("ResolveCredential returned %T, want *BearerProvider", cp) + } + if got := authorizeWith(t, cp.(*BearerProvider)); got != "Bearer ambient-token" { + t.Errorf("Authorization = %q, want the ambient ladder's token", got) + } +} + +func TestResolveCredentialNilAndRequiredRefuses(t *testing.T) { + base := mustParseURL(t, "http://127.0.0.1:8080") + + cp, err := ResolveCredential(backends.OpenOptions{}, base, true) + if cp != nil { + t.Fatal("ResolveCredential returned a non-nil provider alongside the refusal") + } + if !errors.Is(err, ErrCredentialRequired) { + t.Fatalf("ResolveCredential error = %v, want %v", err, ErrCredentialRequired) + } +} + +func TestResolveCredentialProvidedCredentialIsReturnedEvenWhenRequired(t *testing.T) { + base := mustParseURL(t, "http://127.0.0.1:8080") + want := stubProvider{tag: "tenant-7"} + + for _, require := range []bool{false, true} { + cp, err := ResolveCredential(backends.OpenOptions{Credential: ProvidedCredential{Provider: want}}, base, require) + if err != nil { + t.Fatalf("ResolveCredential(require=%v): %v", require, err) + } + if cp != CredentialProvider(want) { + t.Fatalf("ResolveCredential(require=%v) = %v, want the supplied provider", require, cp) + } + } +} + +func TestResolveCredentialProvidedCredentialWithNilProviderRefuses(t *testing.T) { + base := mustParseURL(t, "http://127.0.0.1:8080") + + cp, err := ResolveCredential(backends.OpenOptions{Credential: ProvidedCredential{}}, base, false) + if cp != nil { + t.Fatal("ResolveCredential returned a non-nil provider alongside the refusal") + } + if !errors.Is(err, ErrCredentialRequired) { + t.Fatalf("ResolveCredential error = %v, want %v", err, ErrCredentialRequired) + } +} + +func TestResolveCredentialUnrecognisedCredentialTypeRefuses(t *testing.T) { + base := mustParseURL(t, "http://127.0.0.1:8080") + + cp, err := ResolveCredential(backends.OpenOptions{Credential: fixtureBackendCredential{}}, base, false) + if cp != nil { + t.Fatal("ResolveCredential returned a non-nil provider alongside the refusal") + } + if !errors.Is(err, backends.ErrUnsupportedCredential) { + t.Fatalf("ResolveCredential error = %v, want it to wrap %v", err, backends.ErrUnsupportedCredential) + } + // require must not change this outcome: an unrecognised type is refused + // either way, since returning the ambient ladder here would silently + // ignore a credential the caller clearly intended to supply. + if _, err := ResolveCredential(backends.OpenOptions{Credential: fixtureBackendCredential{}}, base, true); !errors.Is(err, backends.ErrUnsupportedCredential) { + t.Fatalf("ResolveCredential(require=true) error = %v, want it to wrap %v", err, backends.ErrUnsupportedCredential) + } +} + +func TestProvidedCredentialSatisfiesBackendsCredential(t *testing.T) { + var _ backends.Credential = ProvidedCredential{} +} diff --git a/internal/httpclient/ca.go b/internal/httpclient/ca.go new file mode 100644 index 000000000..b43f6e927 --- /dev/null +++ b/internal/httpclient/ca.go @@ -0,0 +1,797 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/ca.go@49d1df2f6) +// to OSS beads under the MIT license. +package httpclient + +import ( + "crypto/sha256" + "crypto/tls" + "crypto/x509" + "encoding/pem" + "errors" + "fmt" + "io" + "net" + "net/http" + "net/url" + "os" + "path/filepath" + "strings" + "sync" + + "golang.org/x/net/http/httpproxy" + "golang.org/x/net/idna" +) + +// CAFileEnv names a PEM file that becomes the ENTIRE trusted root pool for the +// ONE target it names — not an addition to the system store, and not applied +// to any other target this process happens to dial. +// +// It exists for a private CA with no name constraints (the Gas City Beads +// Serve CA): a CA like that can mint a certificate for ANY hostname, so +// trusting it system-wide, or via SSL_CERT_FILE, would let it vouch for every +// TLS connection the process makes, not just the one bd serve it was issued +// for. TransportFor instead builds a pool that contains ONLY this CA and scopes +// it to one target's *http.Client. +// +// # Syntax is host-scoped: host[:port]=path +// +// The value is "host[:port]=path", e.g. "serve.example.com=/etc/bd/ca.pem" or +// "serve.example.com:8443=/etc/bd/ca.pem". A pattern with no port matches a +// target's host regardless of its own port; a pattern with a port matches only +// that exact host:port. A malformed value (no "=", or nothing on either side +// of it) is refused outright — including the old bare-path form this +// superseded, which applied to every target the process dialed regardless of +// host, the impersonation risk this syntax exists to close. A well-formed +// value whose host does not match a given target is silently not applied to +// that target: it falls through to the sidecar (or system roots), never to +// the env's CA. +// +// # Precedence: env beats sidecar, but never silently +// +// When the env var's host pattern matches a target, it wins over that +// target's http_target.json "ca_file" field (Target.CAFile, written by +// `bd connect --ca-file `) — the same rung order the bearer ladder +// already uses (BEADS_HTTP_TOKEN beats the credentials file, see +// credential.go): the environment is the operator's per-invocation override, +// and the sidecar is per-user state persisted once at connect time. But +// unlike the bearer ladder, an env value that matches a target AND disagrees +// with that target's own sidecar ca_file is a hard refusal, not a silent +// override: the two rungs naming different CAs for the same target is very +// likely a stale sidecar or a misdirected env var, and picking one silently +// would trust whichever file the operator did NOT intend. +// +// # The embedder door does not read this at all +// +// This env var is the CLI's own per-invocation override and is consulted only +// by the automatic dial path (DialWith, when the caller leaves +// DialOptions.HTTPClient nil) — the path `bd connect`, `bd ready`, and every +// other cmd/bd invocation rides. backend/http's public TransportFor (the +// embedder door gc calls explicitly to compose a transport into its own +// *http.Client) never reads it: an embedder juggling many targets in one +// process must not have any of them silently renarrowed by an ambient +// variable a completely unrelated invocation exported, so it always builds +// from Target.CAFile alone. See TransportForFile. +// +// #nosec G101 -- the NAME of an environment variable, not a credential. +const CAFileEnv = "BEADS_HTTP_CA_FILE" + +// maxIdleConnsPerHost raises TransportFor's per-host idle pool past +// http.DefaultTransport's default of 2. A CA-scoped target is, by +// construction, one host — that's the whole shape this feature exists for — +// so a concurrency-8 caller (gc's ready-veto fan-out) hammering it legitimately +// wants more than 2 warm connections; below that ceiling, every request past +// the second pays a fresh TLS handshake instead of reusing one already paid +// for. See TransportFor's "Idle connection reuse" doc. It applies equally to +// every http-backend target, CA-configured or not (see baselineTransport in +// dial.go): the RTT cost of an under-pooled host is the same either way. +const maxIdleConnsPerHost = 16 + +// maxCAFileBytes caps how large a configured CA file may be. A CA bundle is +// operator-owned configuration, not arbitrary input, and legitimate ones are a +// handful of certificates — a few KiB. A file past this ceiling is refused +// rather than parsed: it is almost certainly the wrong file (a full trust +// store, a log, something else entirely pointed at by mistake), and PEM +// decoding an unbounded file is needless work for something that is never a +// deliberate CA bundle. +const maxCAFileBytes = 1 << 20 // 1 MiB + +// resolvedCA is what resolveCAFile found: the file to trust for a target, and +// which knob it came from, so a refusal names the thing to fix rather than an +// unqualified "ca file". +type resolvedCA struct { + path string + label string +} + +// configured reports whether a CA applies at all; the zero value means +// "system roots", the same signal TransportFor's nil, nil return carries. +func (r resolvedCA) configured() bool { return r.path != "" } + +// parseCAFileEnv parses CAFileEnv's host-scoped syntax, "host[:port]=path". +// Anything else — no "=", an empty host, an empty path, or a path that is +// not absolute — is malformed and refused: there is no reasonable default +// scope for a value this package cannot parse, and falling back to "applies +// everywhere" is exactly the vulnerability this syntax replaces. The split +// is on the FIRST "=", not the last: a path may itself contain "=" (rare, +// but legal in a POSIX filename), and splitting on the last one would silently +// mis-parse the host pattern in that case rather than refusing loudly. +// Requiring the path be absolute closes a smaller but real ambiguity: a +// relative path's meaning would depend on the process's current directory at +// resolution time, which the sidecar and --ca-file paths never do. +func parseCAFileEnv(raw string) (hostPattern, path string, err error) { + eq := strings.Index(raw, "=") + if eq <= 0 || eq == len(raw)-1 { + return "", "", fmt.Errorf( + "%s %q: want host[:port]=path (e.g. serve.example.com=/etc/bd/ca.pem, or serve.example.com:8443=/etc/bd/ca.pem); a bare path is no longer accepted because it applied to every target this process dials", + CAFileEnv, raw) + } + hostPattern = strings.TrimSpace(raw[:eq]) + path = strings.TrimSpace(raw[eq+1:]) + if hostPattern == "" || path == "" { + return "", "", fmt.Errorf("%s %q: want host[:port]=path", CAFileEnv, raw) + } + if !filepath.IsAbs(path) { + return "", "", fmt.Errorf("%s %q: path %q must be absolute", CAFileEnv, raw, path) + } + if strings.HasSuffix(hostPattern, ":") { + // "h.example:" (or "[::1]:") names a colon with nothing after it — a + // stray trailing colon, almost certainly a dropped port rather than + // a deliberate pattern, and NEITHER of the two meanings a colon can + // carry here (no colon at all: any port; host:port: exactly one): + // silently picking either would be a guess, not a parse. + return "", "", fmt.Errorf("%s %q: host pattern %q ends with \":\" and no port; want host, or host:port", CAFileEnv, raw, hostPattern) + } + return hostPattern, path, nil +} + +// caHostMatches reports whether pattern (the host half of a parsed +// CAFileEnv value) names target. Both sides are IDNA/punycode-normalized to +// ASCII (so "café.example" and "xn--caf-dma.example" agree, whichever form +// an operator typed) and lowercased, with a trailing dot stripped, before +// comparison, and ports are normalized against target's own URL scheme +// (https defaults to 443, http to 80) before being compared, so "host" and +// "host:443" agree for an https target exactly as they would if the +// target's URL had spelled the port out. A pattern with no port matches +// target's host regardless of target's own port — so "example.com=..." +// applies whether the target dials :443 or :8443 — but a pattern WITH a +// port matches only that exact, normalized host:port. IPv6 literals ("[::1]" +// or "[::1]:8443") are handled the same way net/url and net.SplitHostPort +// do. A host that fails IDNA normalization on either side is reported as an +// error rather than silently compared as raw text: an unnormalizable +// pattern could otherwise disagree with a target that a browser or the +// server's own cert treats as the same name. +func caHostMatches(pattern string, target Target) (bool, error) { + pattern = strings.TrimSpace(pattern) + if pattern == "" || target.BaseURL == nil { + return false, nil + } + patternHost, patternPort, err := splitCAHostPort(pattern, "") + if err != nil { + return false, fmt.Errorf("host pattern %q: %w", pattern, err) + } + targetHost, targetPort, err := splitCAHostPort(target.BaseURL.Host, target.BaseURL.Scheme) + if err != nil { + return false, fmt.Errorf("target host %q: %w", target.BaseURL.Host, err) + } + if patternHost == "" || targetHost == "" || patternHost != targetHost { + return false, nil + } + if patternPort == "" { + return true, nil + } + return patternPort == targetPort, nil +} + +// caIDNAProfile normalizes a hostname label to lowercase ASCII/punycode +// without the stricter registration-validity checks idna.Lookup would apply +// (rejecting labels a real, already-issued certificate's SAN can legally +// contain, e.g. a bare underscore label, would turn a working pattern into a +// refusal for no security reason) — this comparison only needs both sides +// folded to the SAME ASCII form, not a verdict on whether the name could be +// newly registered. +var caIDNAProfile = idna.New(idna.MapForLookup(), idna.Transitional(true)) + +// splitCAHostPort splits hostport into an IDNA/punycode-normalized, +// lowercased, trailing-dot-stripped host and its port, handling a bracketed +// IPv6 literal with or without a port. When hostport carries no port and +// scheme names a well-known one (http, https), the returned port defaults to +// that scheme's own — the normalization caHostMatches uses so an explicit +// ":443" pattern still matches an https target whose URL never spells the +// default port out. An IPv6 literal (bracketed, or one that fails ASCII +// hostname normalization for any other reason) is returned lowercased but +// otherwise unnormalized: idna.ToASCII on a literal address is a no-op or an +// error depending on form, and this package already compares IPv6 literals +// as plain text. +func splitCAHostPort(hostport, scheme string) (host, port string, err error) { + hostport = strings.TrimSpace(hostport) + if hostport == "" { + return "", "", nil + } + isIPv6Literal := false + if h, p, splitErr := net.SplitHostPort(hostport); splitErr == nil { + host, port = h, p + } else if strings.HasPrefix(hostport, "[") && strings.HasSuffix(hostport, "]") { + host = strings.TrimSuffix(strings.TrimPrefix(hostport, "["), "]") + } else { + host = hostport + } + host = strings.TrimSuffix(host, ".") + if strings.HasPrefix(host, "[") && strings.HasSuffix(host, "]") { + host = strings.TrimSuffix(strings.TrimPrefix(host, "["), "]") + } + if net.ParseIP(host) != nil { + isIPv6Literal = true + } + if isIPv6Literal { + host = strings.ToLower(host) + } else { + ascii, asciiErr := caIDNAProfile.ToASCII(host) + if asciiErr != nil { + return "", "", fmt.Errorf("host %q is not valid ASCII or a valid internationalized hostname: %w", host, asciiErr) + } + host = strings.ToLower(ascii) + } + if port == "" { + switch strings.ToLower(scheme) { + case "https": + port = "443" + case "http": + port = "80" + } + } + return host, port, nil +} + +// sameCAFile reports whether a and b name the same file: identical after +// filepath.Abs+Clean, or — when both exist — the same file by os.SameFile +// (a hardlink or bind-mount alias). This replaces a raw string compare in +// resolveCAFile's env-vs-sidecar disagreement check, which would otherwise +// refuse two paths that plainly name the same file (one relative, one +// absolute; one with a trailing "/./"; a symlink alias) purely because their +// text differs. +func sameCAFile(a, b string) bool { + a = strings.TrimSpace(a) + b = strings.TrimSpace(b) + if a == "" || b == "" { + return a == b + } + absA, errA := filepath.Abs(a) + absB, errB := filepath.Abs(b) + if errA != nil || errB != nil { + return a == b + } + absA, absB = filepath.Clean(absA), filepath.Clean(absB) + if absA == absB { + return true + } + infoA, errA2 := os.Stat(absA) + infoB, errB2 := os.Stat(absB) + if errA2 == nil && errB2 == nil { + return os.SameFile(infoA, infoB) + } + return false +} + +// resolveCAFile applies the env-over-sidecar precedence documented on +// CAFileEnv, now host-scoped: a "" path in the result means system roots +// apply, unchanged from today, for a target that matches no configured CA. +func resolveCAFile(target Target) (resolvedCA, error) { + sidecar := strings.TrimSpace(target.CAFile) + raw := strings.TrimSpace(os.Getenv(CAFileEnv)) + if raw == "" { + if sidecar == "" { + return resolvedCA{}, nil + } + return resolvedCA{path: sidecar, label: "ca_file"}, nil + } + + pattern, envPath, err := parseCAFileEnv(raw) + if err != nil { + return resolvedCA{}, err + } + + matches, err := caHostMatches(pattern, target) + if err != nil { + return resolvedCA{}, fmt.Errorf("%s %q: %w", CAFileEnv, raw, err) + } + if !matches { + if sidecar == "" { + return resolvedCA{}, nil + } + return resolvedCA{path: sidecar, label: "ca_file"}, nil + } + + if sidecar != "" && !sameCAFile(sidecar, envPath) { + return resolvedCA{}, fmt.Errorf( + "%s (%s=...) names %q for %s, but its sidecar ca_file names %q for the same target; remove one so the CA used here is unambiguous", + CAFileEnv, pattern, envPath, target, sidecar) + } + return resolvedCA{path: envPath, label: CAFileEnv}, nil +} + +// TransportFor builds the http.RoundTripper that trusts ONLY the CA named by +// target's resolved, host-scoped setting (CAFileEnv when its host pattern +// matches target, else Target.CAFile), REPLACING rather than extending the +// system root pool. It returns nil, nil when neither is configured — the +// caller's signal to keep using the default, system-roots transport, which is +// what preserves today's behavior for loopback dev and every target that has +// never set a CA. +// +// This is exported so a caller that builds its own *http.Client for other +// reasons — a tuned timeout, a proxy — can still pick up the automatic, +// env-aware resolution DialWith itself uses: compose the returned +// RoundTripper into that client's Transport field. DialWith calls this itself +// when the caller left DialOptions.HTTPClient nil, so cmd/bd's own dial path +// (the default dialer, the gateway dialer, and `bd connect`'s own verifying +// handshake) needs no further wiring. +// +// An embedder outside this module that wants a transport from an EXPLICIT +// file, ignoring CAFileEnv entirely, should call TransportForFile(target.CAFile) +// instead — see that function and backend/http's public door. +// +// The returned transport never sets ServerName: TLS's SNI and the Host header +// both continue to come from the request's URL, exactly as they do for the +// default transport, so this only narrows which root certificates are +// trusted — it never changes which host a request addresses. +// +// Errors refuse loudly rather than fall back to system roots: a missing file, +// an unreadable one, a malformed CAFileEnv value, a hygiene violation (file +// permissions, size), or one with no valid PEM-encoded certificate is a hard +// error, never a silent downgrade to public trust or to no trust check at +// all. +// +// # Idle connection reuse +// +// A CA-scoped target is still a single host, so it gets the same +// keep-alive budget raised elsewhere for this reason: http.DefaultTransport's +// MaxIdleConnsPerHost is 2, which is too small for a concurrency-8 burst +// against one target — anything past the first 2 idle connections pays a +// fresh TLS handshake, tens of milliseconds at a typical cross-region RTT. +// maxIdleConnsPerHost raises that ceiling so a warm burst reuses connections +// instead of re-handshaking per request. +// +// # Caching and root rotation +// +// The transport returned for a given absolute path is cached and reused for +// the life of the process, keyed by (absolute path, file content hash), so a +// long-lived process dialing the same target repeatedly reuses one transport +// and its warm connection pool rather than paying a fresh TLS handshake and +// leaking the previous transport's idle connections on every dial. A CHANGED +// file at the same path — a different content hash — produces a fresh +// transport, and the previous one's idle connections are closed. Ship a root +// rotation as a bundle containing BOTH the old and the new CA (a +// multi-certificate PEM, one CERTIFICATE block per certificate): every +// process, however long-lived, keeps verifying through the rotation, and +// converges on trusting only the new CA once the bundle is trimmed back down +// to it — with no window where some processes trust only the old certificate +// and others only the new one. +// +// Because it is cached, the returned transport is SHARED: every caller in +// this process asking for the same file holds the same *http.Transport. Treat +// it as read-only — wrap it rather than type-asserting and reconfiguring it — +// since setting its TLSClientConfig, Proxy or DialContext would silently +// change trust for every other holder. +// +// # HTTPS proxies +// +// When a CA is configured, the returned transport refuses to reach a target +// through an https:// proxy — see caAwareProxy. A plain http:// proxy is +// unaffected: the destination's TLS is still verified against the configured +// CA end to end through it. +func TransportFor(target Target) (http.RoundTripper, error) { + resolved, err := resolveCAFile(target) + if err != nil { + return nil, err + } + if !resolved.configured() { + return nil, nil + } + return transportForFile(resolved.path, resolved.label) +} + +// TransportForFile builds the http.RoundTripper that trusts ONLY the CA at +// path, REPLACING rather than extending the system root pool — the same kind +// of transport TransportFor builds, but for a path the caller already +// resolved itself, with NO CAFileEnv involvement at all. +// +// It exists for two callers that must not go through env resolution: +// +// - A `bd connect --ca-file X`-style command verifies the server with X +// BEFORE writing anything; if CAFileEnv happened to be set to a +// different, valid CA for the same host, resolving through the normal +// env-aware path would verify against the WRONG file relative to what +// --ca-file names, then write X unchecked. +// - backend/http's public TransportFor (the embedder door) builds from +// Target.CAFile alone, because CAFileEnv is this process's ambient, +// per-invocation override for the CLI's own dial path, and an embedder +// juggling several targets in one process must not have any of them +// silently renarrowed by a variable it may not even know exists. +// +// Like TransportFor, this participates in the (absolute path, content hash) +// transport cache — so what it returns is the same shared, read-only +// transport — and refuses loudly (missing file, hygiene, malformed PEM) +// rather than falling back to system roots. +func TransportForFile(path string) (http.RoundTripper, error) { + return transportForFile(path, "ca_file") +} + +// cachedTransport pairs a built transport with the content hash of the file +// it was built from and the sequence number of the read that produced it, so +// a later call can tell a cache hit from a rotation, and a stale concurrent +// read from a genuine one. +// +// seq, not the file's mtime, orders reads: a rotation landed by cp -p, +// rsync -t, or tar can preserve (or coincidentally produce) the SAME mtime +// as the file it replaces, down to whatever resolution the filesystem +// keeps — a same-second write is common, not exotic. Comparing mtimes then +// treats a genuine rotation as "no newer than what's cached" and keeps +// serving the superseded (possibly revoked) transport forever, since the +// file's mtime never again exceeds the stale cached one. seq instead counts +// which read of the file started first, a purely in-process fact +// transportReadSeq's own monotonic counter can always order correctly, +// whatever the filesystem clock says. +type cachedTransport struct { + hash [32]byte + seq uint64 + transport *http.Transport +} + +// maxCachedTransports bounds the process-wide transport cache. Each entry +// pins one *http.Transport and its idle connection pool for the life of the +// process; an unbounded cache keyed by absolute path would let a caller that +// churns through many distinct CA file paths over a long-lived process's +// life (many short-lived tenants, an ephemeral-workspace-heavy CI runner) +// grow it without limit. 64 comfortably covers every legitimate shape this +// package expects — one process rarely dials more than a handful of distinct +// CA-scoped hosts. +const maxCachedTransports = 64 + +var ( + transportCacheMu sync.Mutex + transportCache = map[string]*cachedTransport{} + // transportCacheOrder tracks least-recently-used first; touched under + // transportCacheMu alongside transportCache itself. + transportCacheOrder []string + // transportReadSeq is the monotonic counter behind cachedTransport.seq, + // incremented under transportCacheMu immediately BEFORE the file read it + // tags begins — never after, and never derived from the file's own + // mtime; see cachedTransport's doc. + transportReadSeq uint64 +) + +// transportRecord is what transportProvenance remembers about one +// *http.Transport this package built: the absolute path and content hash it +// was built from, at build time. +type transportRecord struct { + path string + hash [32]byte +} + +// transportProvenance maps a *http.Transport this package built to the +// transportRecord it was built from, keyed by the transport's own pointer +// identity. Unlike transportCache (bounded, LRU-evicted, keyed by path), +// this is NEVER evicted and never keyed by path: a caller that obtained a +// transport from TransportFor/TransportForFile and held onto it is entitled +// to keep using it for as long as the file it names is unchanged, even +// after churn through many other CA paths has pushed its cache entry (or a +// later rotation's entry for the same path) out of transportCache entirely. +// matchesCachedTransport consults this, then re-reads and re-hashes the +// file's CURRENT content, so eviction alone never causes a false refusal +// and a rotation is never silently trusted just because the pointer once +// belonged here. +// +// This does grow by one entry per transport ever built, for the life of the +// process — an intentional, deliberately unbounded trade against the +// alternative (a bounded/evicted provenance table would reintroduce exactly +// the false-refusal-on-eviction bug this exists to close). A process that +// churns through many thousands of distinct CA files over its lifetime +// leaks a few dozen bytes per rotation; there is no plausible deployment of +// this feature where that outweighs the correctness this buys. +var transportProvenance sync.Map // map[*http.Transport]transportRecord + +// errCAFileChangedSinceTransportBuilt is matchesCachedTransport's sentinel +// for "this IS a transport we built, but the file has changed since" — kept +// distinct from "never heard of this transport at all" so DialWith can give +// a caller a clear, specific instruction (rebuild it) instead of the generic +// unrecognized-transport refusal. +var errCAFileChangedSinceTransportBuilt = errors.New("CA file changed since this transport was built; rebuild via TransportFor or TransportForFile") + +// matchesCachedTransport reports whether rt is a *http.Transport this +// package built for path, AND that the file at path still has the exact +// content it was built from — the same instance TransportFor or +// TransportForFile would return for it right now, or would have returned +// for it at some point before path's cache entry was evicted or replaced by +// a later rotation. DialWith uses this to recognize the documented embedder +// recipe (backend/http.TransportFor(target) composed into the caller's own +// *http.Client) as trustworthy rather than refusing it outright: the caller +// built its transport through this package's own CA-scoped constructor, so +// there is nothing left to verify beyond "has the file since changed". A +// transport built any other way — even one that happens to trust the right +// CA, even one this package built for a DIFFERENT path — does not match, +// because this package cannot know what else the caller may have layered +// onto an unrelated transport. +// +// A non-nil error (other than errCAFileChangedSinceTransportBuilt, checked +// via errors.Is) means the current file could not be read at all — a +// distinct failure from "does not match", which DialWith surfaces rather +// than treating as a silent refusal indistinguishable from an unrelated +// transport. +func matchesCachedTransport(rt http.RoundTripper, path string) (bool, error) { + if rt == nil || path == "" { + return false, nil + } + t, ok := rt.(*http.Transport) + if !ok { + return false, nil + } + abs, err := filepath.Abs(path) + if err != nil { + return false, nil + } + recVal, ok := transportProvenance.Load(t) + if !ok { + return false, nil + } + rec, ok := recVal.(transportRecord) + if !ok || rec.path != abs { + return false, nil + } + // Re-read and re-hash the file's CURRENT content: recognizing the + // pointer alone would accept a transport built from a CA that has since + // been rotated (or revoked) out from under it, whether or not this + // path's cache entry still names this same transport. + data, err := readCAFile(abs, "ca_file") + if err != nil { + return false, err + } + if sha256.Sum256(data) != rec.hash { + return false, errCAFileChangedSinceTransportBuilt + } + return true, nil +} + +// transportForFile is the shared build behind TransportFor and +// TransportForFile: resolve path to an absolute one, read and hygiene-check +// it, and either reuse the cached transport for that (path, content) pair or +// build and cache a fresh one. label names which setting (CAFileEnv or +// "ca_file") a refusal should point at. +func transportForFile(path, label string) (http.RoundTripper, error) { + abs, err := filepath.Abs(path) + if err != nil { + return nil, fmt.Errorf("%s %q: resolve absolute path: %w", label, path, err) + } + + // Claim this read's sequence number BEFORE doing any file I/O, under the + // same lock the cache itself is guarded by: this is what lets two + // concurrent reads be ordered correctly regardless of what the + // filesystem's clock says about either one's mtime. See + // cachedTransport's doc. + transportCacheMu.Lock() + transportReadSeq++ + mySeq := transportReadSeq + transportCacheMu.Unlock() + + data, err := readCAFile(abs, label) + if err != nil { + return nil, err + } + hash := sha256.Sum256(data) + + transportCacheMu.Lock() + if cached, ok := transportCache[abs]; ok && cached.hash == hash { + touchTransportCacheLocked(abs) + t := cached.transport + transportCacheMu.Unlock() + return t, nil + } + transportCacheMu.Unlock() + + pool, err := parseCAPool(data, abs, label) + if err != nil { + return nil, err + } + transport := http.DefaultTransport.(*http.Transport).Clone() //nolint:errcheck // http.DefaultTransport is always *http.Transport + transport.TLSClientConfig = &tls.Config{MinVersion: tls.VersionTLS12, RootCAs: pool} + transport.MaxIdleConnsPerHost = maxIdleConnsPerHost + transport.Proxy = caAwareProxy + + transportCacheMu.Lock() + defer transportCacheMu.Unlock() + + if cached, ok := transportCache[abs]; ok { + if cached.hash == hash { + // Another goroutine built and cached this exact content while we + // were building ours; reuse theirs. Ours was never assigned to + // any connection, so there is nothing on it to close. + touchTransportCacheLocked(abs) + return cached.transport, nil + } + if cached.seq > mySeq { + // A read that claimed its sequence number AFTER ours already + // landed a different (necessarily newer) hash. Never let a read + // that started earlier clobber a cache entry from one that + // started later just because its content hash differs — the + // file may have been rewritten again between this read's open + // and this lock, and ordering by seq (not mtime) is exactly + // what stays correct under a same-second rewrite. + touchTransportCacheLocked(abs) + return cached.transport, nil + } + // Genuine rotation: close the outgoing transport's idle connections + // so they do not leak, then replace it. + cached.transport.CloseIdleConnections() + } + transportCache[abs] = &cachedTransport{hash: hash, seq: mySeq, transport: transport} + transportProvenance.Store(transport, transportRecord{path: abs, hash: hash}) + touchTransportCacheLocked(abs) + evictOverCapacityLocked() + return transport, nil +} + +// touchTransportCacheLocked moves abs to the most-recently-used end of +// transportCacheOrder. Callers must hold transportCacheMu. +func touchTransportCacheLocked(abs string) { + for i, k := range transportCacheOrder { + if k == abs { + transportCacheOrder = append(transportCacheOrder[:i], transportCacheOrder[i+1:]...) + break + } + } + transportCacheOrder = append(transportCacheOrder, abs) +} + +// evictOverCapacityLocked closes and drops the least-recently-used entries +// until the cache is back within maxCachedTransports. Callers must hold +// transportCacheMu. +func evictOverCapacityLocked() { + for len(transportCacheOrder) > maxCachedTransports { + oldest := transportCacheOrder[0] + transportCacheOrder = transportCacheOrder[1:] + if cached, ok := transportCache[oldest]; ok { + cached.transport.CloseIdleConnections() + delete(transportCache, oldest) + } + } +} + +// caFileReadHookForTest, when non-nil, runs immediately after +// checkCAFilePermissions succeeds and BEFORE the file is opened for reading +// — the exact TOCTOU window the O_NOFOLLOW-open-then-fstat/SameFile guard in +// readCAFile below exists to close. Production never sets it; a test sets it +// to swap the file (or replace it with a symlink) at exactly that point and +// confirms the read is refused rather than silently trusting whatever +// replaced it. +var caFileReadHookForTest func(real string) + +// readCAFile reads path after checking its hygiene (permissions, ownership, +// every symlink hop's containing directory) and confirming that the file it +// actually reads is provably the same one that hygiene check examined, +// returning its content. path must already be absolute; label names the +// setting a refusal should point at. +// +// checkCAFilePermissions resolves path to a real, non-symlink file (checking +// every symlink hop's own containing directory along the way, not just the +// final target's) and returns both that real path and the os.FileInfo it +// stat'd for it. Between that check and this function's own open, an +// attacker who can still write somewhere in the resolved path could swap the +// leaf out from under it; this function's own open uses O_NOFOLLOW — so a +// swap for a symlink is refused outright — and then fstats the opened +// descriptor and compares it against the checked FileInfo with os.SameFile, +// so a swap for a DIFFERENT regular file (same name, same directory) is also +// caught before a single byte is trusted: reading is always from the fd just +// opened, never from a second, independent path lookup. +func readCAFile(path, label string) ([]byte, error) { + real, checked, err := checkCAFilePermissions(path) + if err != nil { + return nil, fmt.Errorf("%s %q: %w", label, path, err) + } + + if caFileReadHookForTest != nil { + caFileReadHookForTest(real) + } + + // #nosec G304 -- path is operator-provided configuration + // (BEADS_HTTP_CA_FILE, or the per-user http_target.json sidecar written by + // `bd connect --ca-file`), not attacker-controlled input; its permissions + // were just checked above, and openCAFileNoFollow additionally refuses to + // open real at all if it has become a symlink since that check (unix). + f, err := openCAFileNoFollow(real) + if err != nil { + return nil, fmt.Errorf("%s %q: %w", label, path, err) + } + defer f.Close() //nolint:errcheck // read-only fd; nothing to flush on close + + opened, err := f.Stat() + if err != nil { + return nil, fmt.Errorf("%s %q: %w", label, path, err) + } + if !os.SameFile(checked, opened) { + return nil, fmt.Errorf("%s %q: changed between the permission check and the read; refusing rather than trust whatever replaced it", label, path) + } + + data, err := io.ReadAll(io.LimitReader(f, maxCAFileBytes+1)) + if err != nil { + return nil, fmt.Errorf("%s %q: %w", label, path, err) + } + if len(data) > maxCAFileBytes { + return nil, fmt.Errorf("%s %q: larger than %d bytes; a CA bundle this size is almost certainly the wrong file", label, path, maxCAFileBytes) + } + return data, nil +} + +// parseCAPool decodes data as a sequence of PEM blocks and requires EVERY +// block to be a well-formed CERTIFICATE. A block of any other type, or one +// that fails to parse, refuses the WHOLE file rather than silently keeping +// whatever did parse — crypto/x509.CertPool.AppendCertsFromPEM's behavior, +// which this deliberately does not use. A CA file is small, operator-owned +// configuration, so a block it cannot vouch for (a private key pasted in by +// accident, a corrupted certificate) is far more likely a mistake than an +// intentional block meant to be skipped, and accepting the file anyway would +// trust a pool the operator never actually reviewed. +// +// A single LEAF certificate — no CA:true, no key-cert-sign usage — still +// works here: TLS root-of-trust verification only requires the chain to +// terminate at a certificate in RootCAs, so a file holding just the server's +// own leaf is a valid way to pin that one certificate rather than a CA. It is +// operationally brittle (it must be replaced on every renewal), but this +// package does not refuse it: pinning is a legitimate, if narrower, use of +// this same mechanism. +func parseCAPool(data []byte, path, label string) (*x509.CertPool, error) { + pool := x509.NewCertPool() + rest := data + n := 0 + for { + var block *pem.Block + block, rest = pem.Decode(rest) + if block == nil { + break + } + n++ + if block.Type != "CERTIFICATE" { + return nil, fmt.Errorf("%s %q: PEM block %d is %q, not CERTIFICATE; only certificates (a CA, or a single leaf to pin) belong in this file", label, path, n, block.Type) + } + cert, err := x509.ParseCertificate(block.Bytes) + if err != nil { + return nil, fmt.Errorf("%s %q: PEM block %d does not parse as a certificate: %w", label, path, n, err) + } + pool.AddCert(cert) + } + if n == 0 { + return nil, fmt.Errorf("%s %q: no PEM certificates found", label, path) + } + return pool, nil +} + +// caAwareProxy is the CA-scoped transport's Proxy func. For a plain http:// +// proxy it behaves exactly like http.ProxyFromEnvironment: the destination +// host's own TLS is still verified end to end against this transport's +// narrow RootCAs, so routing through a plaintext-to-the-proxy CONNECT tunnel +// changes nothing about what gets trusted. +// +// It refuses an https:// proxy instead of dialing it. The CONNECT to the +// proxy ITSELF would be a TLS handshake made with this same TLSClientConfig, +// so the proxy's own certificate — issued by whatever CA actually vouches for +// it, almost never the single private CA this transport was scoped to — would +// be checked against that narrow pool and (correctly) fail, or, worse, if it +// happened to validate, Proxy-Authorization would be sent across a connection +// verified by the wrong trust anchor. Refusing up front is clearer than +// either outcome. +// +// This reads the proxy configuration via golang.org/x/net/http/httpproxy +// directly rather than http.ProxyFromEnvironment: the latter caches the +// environment the first time ANY transport in the process resolves a proxy, +// behind a package-level sync.Once, which would make this refusal depend on +// unrelated dial or test ordering. httpproxy.FromEnvironment reads the +// environment fresh on every call. +func caAwareProxy(req *http.Request) (*url.URL, error) { + proxyURL, err := httpproxy.FromEnvironment().ProxyFunc()(req.URL) + if err != nil { + return nil, err + } + if proxyURL != nil && proxyURL.Scheme == "https" { + return nil, fmt.Errorf( + "refusing to reach %s through an https:// proxy (%s) while a CA is configured for this target: the proxy's own TLS would be checked against that CA instead of the system roots that actually vouch for it; use an http:// proxy instead (the destination's TLS is still verified against the configured CA through it), or exclude this host via NO_PROXY", + req.URL.Host, proxyURL.Redacted()) + } + return proxyURL, nil +} diff --git a/internal/httpclient/ca_permissions_other.go b/internal/httpclient/ca_permissions_other.go new file mode 100644 index 000000000..400942aeb --- /dev/null +++ b/internal/httpclient/ca_permissions_other.go @@ -0,0 +1,61 @@ +//go:build !unix + +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/ca_permissions_other.go@49d1df2f6) +// to OSS beads under the MIT license. + +package httpclient + +import ( + "fmt" + "os" +) + +// allowInsecureCAFilePermissionsEnv is the explicit opt-in required to use a +// CA file on a platform this package cannot vet ownership/writability on at +// all. This feature (host-scoped CA trust) is new, not a long-depended-on +// one migrating to a stricter default, so failing closed here by default — +// rather than silently accepting whatever ACLs happen to protect the file — +// is the safe choice: an operator who has reviewed their own platform's +// equivalent protection can set this to proceed anyway, but nobody is +// silently downgraded from the unix build's real ownership/writability +// checks without saying so. +const allowInsecureCAFilePermissionsEnv = "BEADS_ALLOW_INSECURE_CA_FILE_PERMISSIONS" + +// checkCAFilePermissions has no ownership/writability check to perform at +// all on a non-unix platform: filesystem permissions there use ACLs rather +// than Unix mode bits, and there is no uid/gid ownership model this package +// knows how to interpret. Rather than silently treating "cannot check" the +// same as "checked and fine" (this package's earlier behavior), it refuses +// the CA file outright unless the operator has explicitly opted in via +// allowInsecureCAFilePermissionsEnv — a CA file this package cannot vet is +// exactly the swap-in-a-writable-location risk the unix build's checks +// exist to catch, and a silent skip would be indistinguishable from "this +// platform is just as safe", which is not a claim this package can make. +// +// It still refuses an obviously wrong path (a directory) even with the +// opt-in set. +func checkCAFilePermissions(path string) (string, os.FileInfo, error) { + info, err := os.Stat(path) + if err != nil { + return "", nil, err + } + if info.IsDir() { + return "", nil, fmt.Errorf("is a directory, not a PEM file") + } + if os.Getenv(allowInsecureCAFilePermissionsEnv) == "" { + return "", nil, fmt.Errorf( + "refusing to use a CA file on this platform: it has no unix-style ownership/writability check to vet %q with, and %s is not set; set it to proceed anyway once you have verified this file (and every containing directory) cannot be written by anyone other than an administrator", + path, allowInsecureCAFilePermissionsEnv) + } + return path, info, nil +} + +// openCAFileNoFollow is a plain open on non-unix platforms: O_NOFOLLOW is a +// unix-specific open flag with no portable equivalent this package can rely +// on here, and checkCAFilePermissions above already refuses to reach this +// point at all unless the operator explicitly opted in via +// allowInsecureCAFilePermissionsEnv, accepting that this platform's TOCTOU +// and symlink protections are best-effort at most. +func openCAFileNoFollow(real string) (*os.File, error) { + return os.Open(real) //nolint:gosec // G304: operator-provided config path, hygiene-gated above +} diff --git a/internal/httpclient/ca_permissions_unix.go b/internal/httpclient/ca_permissions_unix.go new file mode 100644 index 000000000..87dfb1a43 --- /dev/null +++ b/internal/httpclient/ca_permissions_unix.go @@ -0,0 +1,403 @@ +//go:build unix + +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/ca_permissions_unix.go@49d1df2f6) +// to OSS beads under the MIT license. + +package httpclient + +import ( + "bufio" + "fmt" + "os" + "os/user" + "path/filepath" + "strconv" + "strings" + "syscall" +) + +// caFileStat is what checkCAFilePermissions needs from a stat call, factored +// out of os.Lstat so a test can inject an ownership scenario (a leaf or +// ancestor owned by a uid other than root or the running one, or a +// root-owned 0755/0644 layout) that this sandbox cannot construct with real +// files — see statCAPathFn. +type caFileStat struct { + mode os.FileMode + uid uint32 + gid uint32 + // info is the underlying os.FileInfo the real statCAPathFn Lstat'd. It is + // nil for a test-injected caFileStat, which is fine: only the leaf's + // info (returned from checkCAFilePermissions itself) is ever consulted + // for os.SameFile, and every test that injects synthetic ownership goes + // through checkCAFilePermissions itself rather than reading this field + // directly. + info os.FileInfo +} + +// statCAPathFn is swappable so a test can simulate ownership scenarios real +// files in the test sandbox cannot: a path owned by a uid other than root or +// the running one, or a root-owned layout on a host where every real file is +// owned by the test's own uid. It never follows the final path component +// (os.Lstat), so checkCAFilePermissions can detect a symlink at each hop +// itself rather than the kernel silently resolving it away. +var statCAPathFn = func(path string) (caFileStat, error) { + info, err := os.Lstat(path) + if err != nil { + return caFileStat{}, err + } + st, ok := info.Sys().(*syscall.Stat_t) + if !ok { + // Best effort: no ownership info available, only the mode. + return caFileStat{mode: info.Mode(), info: info}, nil + } + return caFileStat{mode: info.Mode(), uid: st.Uid, gid: st.Gid, info: info}, nil +} + +// openCAFileNoFollow opens real for reading with O_NOFOLLOW: real is what +// checkCAFilePermissions just confirmed is NOT itself a symlink, so if the +// open fails with ELOOP (or any other O_NOFOLLOW rejection) something +// replaced it with a symlink in the window between that check and this call, +// and the read must refuse rather than silently follow the swap. +func openCAFileNoFollow(real string) (*os.File, error) { + fd, err := syscall.Open(real, syscall.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_CLOEXEC, 0) + if err != nil { + return nil, fmt.Errorf("open (no-follow): %w", err) + } + return os.NewFile(uintptr(fd), real), nil +} + +// isUserPrivateGroupFn is swappable so a test can simulate a "genuinely +// shared" group (finding 4's refusal case) without needing a second real +// POSIX group on the machine running the test. +var isUserPrivateGroupFn = isUserPrivateGroup + +// userLookupIDFn and userLookupGroupIDFn are swappable so a test can drive +// isUserPrivateGroup's OWN name-comparison line (g.Name != u.Username) +// through both arms directly — calling isUserPrivateGroup itself, not the +// isUserPrivateGroupFn seam above, which would skip over that exact +// comparison rather than exercise it. The real os/user package has no way to +// manufacture a uid/gid/username combination on demand, so without this seam +// a test is stuck with whatever single account the host running it happens +// to have. +var ( + userLookupIDFn = user.LookupId + userLookupGroupIDFn = user.LookupGroupId +) + +// groupHasNoSupplementaryMembersFn is swappable so a test can simulate +// membership scenarios (a group with an added member; a group whose +// membership cannot be determined) that this sandbox's real /etc/group may +// not exhibit either way. The real implementation reads /etc/group directly: +// Go's os/user package has no portable API for "list this group's +// supplementary members" (LookupGroup/LookupGroupId return only id and +// name), and getgrgid_r's own member list is what /etc/group's fourth field +// carries on every platform this build tag covers. +var groupHasNoSupplementaryMembersFn = groupHasNoSupplementaryMembers + +// isUserPrivateGroup reports the Debian/OpenSSH "user private group" +// convention: uid's own primary group is gid, that group's name is exactly +// uid's username, AND the group lists no OTHER member in /etc/group. Under +// Ubuntu's default user-private-groups scheme this is true for every +// ordinary account, which is what makes a umask-002 ~/.config/bd (0775 +// directories, 0664 files) exactly as private as a umask-022 layout would +// be — group-write only reaches a group whose sole member, by convention, is +// the file's own owner. A file whose group is some OTHER group the owner +// merely belongs to (a real shared group, "docker", "sudo") does not get +// this exemption, whatever its name looks like. +// +// Root (uid 0) never qualifies, regardless of what the name/membership +// checks below would otherwise conclude: gid 0 is commonly named "root" too, +// so a naive name comparison would treat root's own primary group as +// "private" — but root's group is a system convention, not evidence that no +// other account can write through it, and CA hygiene should never lean on +// that assumption. +func isUserPrivateGroup(uid, gid uint32) bool { + if uid == 0 { + return false + } + u, err := userLookupIDFn(strconv.FormatUint(uint64(uid), 10)) + if err != nil { + return false + } + if u.Gid != strconv.FormatUint(uint64(gid), 10) { + return false + } + g, err := userLookupGroupIDFn(strconv.FormatUint(uint64(gid), 10)) + if err != nil { + return false + } + if g.Name != u.Username { + return false + } + return groupHasNoSupplementaryMembersFn(gid) +} + +// groupHasNoSupplementaryMembers reports whether gid's own /etc/group entry +// lists no supplementary members by name — the actual membership half of the +// user-private-group convention, beyond gid/name matching alone: a group +// literally named after its "owner" that other accounts have ALSO been added +// to (in /etc/group's fourth, comma-separated field) is not private, +// whatever its name suggests. When /etc/group cannot be read, or gid is not +// found in it at all, this refuses (returns false) rather than assuming the +// group is private: a hygiene check that cannot positively confirm isolation +// must not grant the exemption that isolation is the whole justification +// for. +func groupHasNoSupplementaryMembers(gid uint32) bool { + f, err := os.Open("/etc/group") + if err != nil { + return false + } + defer f.Close() //nolint:errcheck // read-only fd + + gidStr := strconv.FormatUint(uint64(gid), 10) + scanner := bufio.NewScanner(f) + for scanner.Scan() { + line := strings.TrimSpace(scanner.Text()) + if line == "" || strings.HasPrefix(line, "#") { + continue + } + fields := strings.Split(line, ":") + if len(fields) < 4 || fields[2] != gidStr { + continue + } + members := strings.TrimSpace(fields[3]) + return members == "" + } + if err := scanner.Err(); err != nil { + return false + } + return false // gid not found in /etc/group: cannot confirm -> refuse +} + +// maxCASymlinkHops bounds how many symlink hops checkCAFilePermissions will +// follow before refusing outright, guarding against a symlink loop (or an +// adversarial chain) turning this check into an unbounded walk. +const maxCASymlinkHops = 40 + +// checkCAFilePermissions refuses a CA file, or any ancestor directory up to +// /, that a party other than its owner (root, or the uid running this +// process) could have written — the same hygiene ssh requires of +// known_hosts and authorized_keys. A CA file REPLACES the entire trust root +// for a target; anyone who can write it, or swap it out from a writable +// ancestor, can make this process trust a CA of their choosing, a full +// impersonation of that target. +// +// path is resolved ONE SYMLINK HOP AT A TIME rather than through a single +// filepath.EvalSymlinks call: EvalSymlinks would resolve the whole chain +// silently, and the containing directory of any symlink component along the +// ORIGINAL path is never itself examined — a symlink sitting in a +// world-writable directory, pointing at an otherwise pristine target, would +// pass unnoticed, because only the target's own ancestors would ever be +// checked. This walk instead stats each path with Lstat, and whenever a hop +// turns out to be a symlink, checks THAT symlink's own containing directory +// (the same ownership/writability rules as any other ancestor) before +// following it to wherever it points. +// +// On success it returns the fully resolved, non-symlink real path and the +// os.FileInfo checkCAFilePermissions stat'd for it, so the caller (readCAFile) +// can open that exact path and compare what it opened against what was +// checked here — closing the gap between this function's stat and a +// separate, independent open of the same path string. +// +// Every ancestor directory up to / is checked, not just the immediate +// parent: a writable grandparent lets an attacker rename the parent out of +// the way and replace it, which a parent-only check would never see. A +// sticky ancestor directory (mode +t, e.g. /tmp) is exempt from the +// writability check ONLY: anyone may create an entry there, but only that +// entry's own owner may remove or rename it, so a sticky world-writable +// directory does not let another user replace this file's directory entry +// from above — but the directory's OWNER must still be root or the running +// euid, exactly as for any other ancestor; sticky is not a license to be +// owned by anyone. The leaf file itself gets no exemption at all, sticky bit +// or not: sticky has no protective meaning for a file that is not a +// directory, and checkOwnerAndMode's own isDir gate means this exemption can +// never reach the leaf regardless of what bits its mode happens to carry. +// +// Group-write is refused unless the group is the owner's OWN user-private +// group (isUserPrivateGroup) — see its doc. World-write is never allowed, +// for the leaf file or any non-sticky ancestor. +func checkCAFilePermissions(path string) (string, os.FileInfo, error) { + return checkCAFilePermissionsHop(path, 0) +} + +func checkCAFilePermissionsHop(path string, hops int) (string, os.FileInfo, error) { + if hops > maxCASymlinkHops { + return "", nil, fmt.Errorf("too many levels of symbolic links resolving %s", path) + } + + fi, err := statCAPathFn(path) + if err != nil { + return "", nil, err + } + + if fi.mode&os.ModeSymlink != 0 { + dir := filepath.Dir(path) + if err := checkAncestors(dir); err != nil { + return "", nil, err + } + target, err := readLinkTarget(path, dir) + if err != nil { + return "", nil, err + } + return checkCAFilePermissionsHop(target, hops+1) + } + + if fi.mode.IsDir() { + return "", nil, fmt.Errorf("is a directory, not a PEM file") + } + if err := checkOwnerAndMode(path, fi, false); err != nil { + return "", nil, err + } + if err := checkAncestors(filepath.Dir(path)); err != nil { + return "", nil, err + } + return path, fi.info, nil +} + +// checkAncestors walks every ancestor directory of dir up to /, applying +// checkOwnerAndMode to each. An ancestor that is itself a symlink is +// followed the same way checkCAFilePermissionsHop follows the leaf: the +// symlink entry's OWN containing directory (and everything above it) is +// checked BEFORE following it, and the walk then continues separately from +// its resolved target. hops bounds the combined recursion (both "following +// an ancestor symlink" and "walking up one more parent" consume the same +// budget) against a symlink loop among ancestors. +func checkAncestors(dir string) error { + return checkAncestorsHop(dir, 0) +} + +func checkAncestorsHop(dir string, hops int) error { + if hops > maxCASymlinkHops { + return fmt.Errorf("too many levels of symbolic links resolving ancestor directories of %s", dir) + } + + dfi, err := statCAPathFn(dir) + if err != nil { + return fmt.Errorf("stat %s: %w", dir, err) + } + + if dfi.mode&os.ModeSymlink != 0 { + parentOfLink := filepath.Dir(dir) + if err := checkAncestorsHop(parentOfLink, hops+1); err != nil { + return err + } + target, err := readLinkTarget(dir, parentOfLink) + if err != nil { + return err + } + return checkAncestorsHop(target, hops+1) + } + + if err := checkOwnerAndMode(dir, dfi, true); err != nil { + return err + } + parent := filepath.Dir(dir) + if parent == dir { + return nil + } + return checkAncestorsHop(parent, hops+1) +} + +// readLinkTarget reads the symlink at link, whose containing directory dir +// has already passed checkAncestors, and returns the path it points to. A +// relative target is joined onto dir's PHYSICAL path, not its text: the +// kernel resolves the target from the directory the link really lives in, so +// when dir itself runs through a symlinked directory, a lexical +// filepath.Join(dir, target) collapses any ".." in the target against the +// wrong parent (a/link -> b/c with b/c/x -> ../y names b/y, never a/y). +// Resolving dir in one EvalSymlinks call is safe here because every symlink +// along it was already checked hop by hop on the way in. +// +// A target with a ".." after any other component is refused outright, +// relative or absolute. The kernel takes that ".." from wherever the +// component before it really leads, through that component's own symlinks, +// while filepath.Join and the walk's own filepath.Dir drop the pair +// textually, so the directories the kernel actually passes through are never +// checked: with x/d -> ../e/s, x/L -> d/../y names e/y, not x/y, and an +// absolute x/L -> /r/x/d/../y is even opened at /r/e/y while only /r/x and +// its ancestors are checked, never /r/e. A leading run of ".." is kept: it is +// taken from dir's physical path, which has no symlinks left to take it +// through. +func readLinkTarget(link, dir string) (string, error) { + target, err := os.Readlink(link) + if err != nil { + return "", fmt.Errorf("readlink %s: %w", link, err) + } + if hasInteriorDotDot(target) { + return "", fmt.Errorf( + `symlink %s points at %q, whose ".." follows another component; the kernel resolves that ".." through the earlier component's own symlinks, which this check would skip, so rewrite the link without the inner ".."`, + link, target) + } + if filepath.IsAbs(target) { + return target, nil + } + physical, err := filepath.EvalSymlinks(dir) + if err != nil { + return "", fmt.Errorf("resolve %s: %w", dir, err) + } + return filepath.Join(physical, target), nil +} + +// hasInteriorDotDot reports whether target has a ".." component after some +// other component, setting aside "." and the empty components a leading or +// doubled "/" leaves: the shape readLinkTarget refuses. +func hasInteriorDotDot(target string) bool { + named := false + for _, elem := range strings.Split(target, "/") { + switch elem { + case "", ".": + case "..": + if named { + return true + } + default: + named = true + } + } + return false +} + +// checkOwnerAndMode applies the ownership and writability rules to one path +// (the leaf file, or one ancestor directory) already stat'd into fi. +// +// The owner check ALWAYS runs, sticky directory or not: sticky only changes +// who may remove or rename an ENTRY inside the directory, not who owns the +// directory itself, so exempting a sticky directory from the owner check +// too would accept a sticky directory owned by neither root nor the running +// euid — exactly the case F3 flags. Only the mode/writability check below is +// ever skipped for sticky, and only for a directory: isDir is false for +// every call on the leaf file, so the leaf can never reach that exemption +// regardless of what mode bits it happens to carry. +func checkOwnerAndMode(p string, fi caFileStat, isDir bool) error { + noun := "file" + if isDir { + noun = "directory" + } + + euid := uint32(os.Geteuid()) + if fi.uid != 0 && fi.uid != euid { + return fmt.Errorf( + "%s %s is owned by uid %d, neither root nor the uid running this process (%d); an owner who is neither could have written it to a CA this process should not trust", + noun, p, fi.uid, euid) + } + + if isDir && fi.mode&os.ModeSticky != 0 { + // Mode/writability check exempted: anyone may create an entry in a + // sticky directory, but only that entry's own owner may remove or + // rename it, so a sticky world-writable directory does not let + // another user replace this file's directory entry from above. + // Ownership was already checked unconditionally above. + return nil + } + + mode := fi.mode.Perm() + if mode&0o002 != 0 { + return fmt.Errorf("%s %s has mode %04o, world-writable; chmod o-w it", noun, p, mode) + } + if mode&0o020 != 0 && !isUserPrivateGroupFn(fi.uid, fi.gid) { + return fmt.Errorf( + "%s %s has mode %04o, group-writable by a group that is not its owner's own user-private group; chmod g-w it, or move it under a group whose only member is the owner", + noun, p, mode) + } + return nil +} diff --git a/internal/httpclient/ca_permissions_unix_test.go b/internal/httpclient/ca_permissions_unix_test.go new file mode 100644 index 000000000..cb50ac14d --- /dev/null +++ b/internal/httpclient/ca_permissions_unix_test.go @@ -0,0 +1,554 @@ +//go:build unix + +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/ca_permissions_unix_test.go@49d1df2f6) +// to OSS beads under the MIT license. + +package httpclient + +import ( + "os" + "os/user" + "path/filepath" + "strconv" + "strings" + "testing" +) + +// TestCheckCAFilePermissionsRefusesSymlinkIntoWorldWritableDir is finding 3: +// a symlink whose own directory is fine but whose REAL target sits inside a +// world-writable directory must be refused — checking only the symlink's own +// location would miss the swap this check exists to catch. +func TestCheckCAFilePermissionsRefusesSymlinkIntoWorldWritableDir(t *testing.T) { + realDir := t.TempDir() + if err := os.Chmod(realDir, 0o777); err != nil { + t.Fatalf("chmod real dir 0777: %v", err) + } + realPath := filepath.Join(realDir, "ca.pem") + if err := os.WriteFile(realPath, []byte("x"), 0o600); err != nil { + t.Fatalf("write real file: %v", err) + } + + linkDir := t.TempDir() + if err := os.Chmod(linkDir, 0o700); err != nil { + t.Fatalf("chmod link dir: %v", err) + } + link := filepath.Join(linkDir, "ca.pem") + if err := os.Symlink(realPath, link); err != nil { + t.Fatalf("symlink: %v", err) + } + + if _, _, err := checkCAFilePermissions(link); err == nil { + t.Fatal("checkCAFilePermissions accepted a symlink into a world-writable directory") + } +} + +// TestCheckCAFilePermissionsRefusesSymlinkItselfInWorldWritableDir is finding +// 2's complement to TestCheckCAFilePermissionsRefusesSymlinkIntoWorldWritableDir +// above: here the symlink's TARGET is perfectly fine (its own directory is +// 0700), but the symlink ENTRY itself sits inside a world-writable directory. +// Only checking the resolved target's ancestors (what a single +// filepath.EvalSymlinks call would do) would miss this: anyone could unlink +// and replace the symlink entry itself, in the world-writable linkDir, to +// point somewhere else entirely. checkCAFilePermissionsHop must check the +// symlink's OWN containing directory before following it. +func TestCheckCAFilePermissionsRefusesSymlinkItselfInWorldWritableDir(t *testing.T) { + linkDir := t.TempDir() + if err := os.Chmod(linkDir, 0o777); err != nil { + t.Fatalf("chmod link dir 0777: %v", err) + } + + realDir := t.TempDir() + if err := os.Chmod(realDir, 0o700); err != nil { + t.Fatalf("chmod real dir: %v", err) + } + realPath := filepath.Join(realDir, "ca.pem") + if err := os.WriteFile(realPath, []byte("x"), 0o600); err != nil { + t.Fatalf("write real file: %v", err) + } + + link := filepath.Join(linkDir, "ca.pem") + if err := os.Symlink(realPath, link); err != nil { + t.Fatalf("symlink: %v", err) + } + + if _, _, err := checkCAFilePermissions(link); err == nil { + t.Fatal("checkCAFilePermissions accepted a symlink sitting in a world-writable, non-sticky directory even though its target is fine") + } +} + +// TestCheckCAFilePermissionsResolvesRelativeLinkAgainstPhysicalDir pins the +// walk to the kernel's reading of a relative symlink target: with a/link -> +// ../b/c and b/c/x -> ../y, the path a/link/x names b/y, because ".." is taken +// from the directory x really lives in. A lexical join collapses it against +// a/link instead and lands on a/y; the hygienic decoy planted there makes that +// mistake a wrong-file read rather than just a refusal. +func TestCheckCAFilePermissionsResolvesRelativeLinkAgainstPhysicalDir(t *testing.T) { + root := secureTempDir(t) + for _, d := range []string{"a", "b", filepath.Join("b", "c")} { + if err := os.Mkdir(filepath.Join(root, d), 0o700); err != nil { + t.Fatalf("mkdir %s: %v", d, err) + } + } + realPath := filepath.Join(root, "b", "y") + if err := os.WriteFile(realPath, []byte("real"), 0o600); err != nil { + t.Fatalf("write real file: %v", err) + } + if err := os.WriteFile(filepath.Join(root, "a", "y"), []byte("decoy"), 0o600); err != nil { + t.Fatalf("write decoy file: %v", err) + } + if err := os.Symlink(filepath.Join("..", "b", "c"), filepath.Join(root, "a", "link")); err != nil { + t.Fatalf("symlink a/link: %v", err) + } + if err := os.Symlink(filepath.Join("..", "y"), filepath.Join(root, "b", "c", "x")); err != nil { + t.Fatalf("symlink b/c/x: %v", err) + } + path := filepath.Join(root, "a", "link", "x") + + got, _, err := checkCAFilePermissions(path) + if err != nil { + t.Fatalf("checkCAFilePermissions(%s): %v", path, err) + } + want, err := filepath.EvalSymlinks(realPath) + if err != nil { + t.Fatalf("EvalSymlinks(%s): %v", realPath, err) + } + if got != want { + t.Errorf("checkCAFilePermissions resolved %s to %s, want %s", path, got, want) + } + data, err := readCAFile(path, "ca_file") + if err != nil { + t.Fatalf("readCAFile(%s): %v", path, err) + } + if string(data) != "real" { + t.Errorf("readCAFile(%s) read %q, want the file the kernel names (%q)", path, data, "real") + } +} + +// TestReadCAFileRefusesLinkTargetWithInteriorDotDot pins readLinkTarget's +// refusal of a target whose ".." follows another component. With x/d -> +// ../evil/sub, the kernel resolves d/.. to evil, a world-writable directory +// the walk refuses when it is named directly, but a textual collapse never +// looks at d: the relative leaf link then reads the hygienic decoy at x/y, and +// the other three shapes read the file inside evil without evil ever being +// checked. The targets are spelled as strings because filepath.Join would +// clean the ".." away. +func TestReadCAFileRefusesLinkTargetWithInteriorDotDot(t *testing.T) { + root := secureTempDir(t) + evil := filepath.Join(root, "evil") + x := filepath.Join(root, "x") + for _, d := range []string{evil, filepath.Join(evil, "sub"), filepath.Join(evil, "dir"), x, filepath.Join(x, "dir")} { + if err := os.Mkdir(d, 0o700); err != nil { + t.Fatalf("mkdir %s: %v", d, err) + } + } + if err := os.Chmod(evil, 0o777); err != nil { + t.Fatalf("chmod evil 0777: %v", err) + } + for path, content := range map[string]string{ + filepath.Join(evil, "y"): "evil", + filepath.Join(evil, "dir", "y"): "evil", + filepath.Join(x, "y"): "decoy", + filepath.Join(x, "dir", "y"): "decoy", + } { + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + t.Fatalf("write %s: %v", path, err) + } + } + if err := os.Symlink(filepath.Join("..", "evil", "sub"), filepath.Join(x, "d")); err != nil { + t.Fatalf("symlink x/d: %v", err) + } + if _, err := readCAFile(filepath.Join(evil, "y"), "ca_file"); err == nil { + t.Fatal("readCAFile accepted a file in a world-writable directory named directly, so the cases below prove nothing") + } + + for _, tc := range []struct{ name, link, target, path string }{ + {"relative leaf", "L1", "d/../y", "L1"}, + {"absolute leaf", "L2", x + "/d/../y", "L2"}, + {"relative ancestor", "L3", "d/../dir", "L3/y"}, + {"absolute ancestor", "L4", x + "/d/../dir", "L4/y"}, + } { + t.Run(tc.name, func(t *testing.T) { + if err := os.Symlink(tc.target, filepath.Join(x, tc.link)); err != nil { + t.Fatalf("symlink %s: %v", tc.link, err) + } + path := filepath.Join(x, tc.path) + data, err := readCAFile(path, "ca_file") + if err == nil { + t.Fatalf("readCAFile(%s) through %q read %q, want a refusal", path, tc.target, data) + } + if !strings.Contains(err.Error(), `whose ".." follows another component`) { + t.Errorf("readCAFile(%s) through %q: %v, want the interior \"..\" refusal", path, tc.target, err) + } + }) + } +} + +// TestHasInteriorDotDot pins the boundary of that refusal: a ".." after +// another component is refused, but a leading run of them is not, since +// readLinkTarget takes it from a physical directory. +func TestHasInteriorDotDot(t *testing.T) { + for target, want := range map[string]bool{ + "y": false, + "../y": false, + "../../b/c": false, + "./../y": false, + "/r/b/y": false, + "/../y": false, + "d/../y": true, + "d/./../y": true, + "d/..": true, + "../d/../y": true, + "/r/d/../y": true, + "//r/d/../y": true, + } { + if got := hasInteriorDotDot(target); got != want { + t.Errorf("hasInteriorDotDot(%q) = %v, want %v", target, got, want) + } + } +} + +// TestCheckCAFilePermissionsRefusesWorldWritableGrandparent is finding 3: a +// world-writable GRANDparent (not just the immediate parent) must be +// refused — an attacker who can write the grandparent can rename the parent +// out of the way and replace it. +func TestCheckCAFilePermissionsRefusesWorldWritableGrandparent(t *testing.T) { + grandparent := t.TempDir() + if err := os.Chmod(grandparent, 0o777); err != nil { + t.Fatalf("chmod grandparent 0777: %v", err) + } + parent := filepath.Join(grandparent, "safe-looking-parent") + if err := os.Mkdir(parent, 0o700); err != nil { + t.Fatalf("mkdir parent: %v", err) + } + path := filepath.Join(parent, "ca.pem") + if err := os.WriteFile(path, []byte("x"), 0o600); err != nil { + t.Fatalf("write file: %v", err) + } + + if _, _, err := checkCAFilePermissions(path); err == nil { + t.Fatal("checkCAFilePermissions accepted a file whose grandparent directory is world-writable") + } +} + +// TestCheckCAFilePermissionsAllowsStickyWorldWritableAncestor confirms the +// sticky-directory exception: an ancestor with mode +t, however +// world-writable, is exempt, because only that entry's own owner may remove +// or rename it from under a sticky directory. +func TestCheckCAFilePermissionsAllowsStickyWorldWritableAncestor(t *testing.T) { + sticky := t.TempDir() + if err := os.Chmod(sticky, 0o777|os.ModeSticky); err != nil { + t.Fatalf("chmod sticky world-writable: %v", err) + } + parent := filepath.Join(sticky, "safe-parent") + if err := os.Mkdir(parent, 0o700); err != nil { + t.Fatalf("mkdir parent: %v", err) + } + path := filepath.Join(parent, "ca.pem") + if err := os.WriteFile(path, []byte("x"), 0o600); err != nil { + t.Fatalf("write file: %v", err) + } + + if _, _, err := checkCAFilePermissions(path); err != nil { + t.Errorf("checkCAFilePermissions refused a sticky world-writable ancestor: %v", err) + } +} + +// TestCheckCAFilePermissionsRefusesFileOwnedByAnotherUser is finding 3's +// ownership rule, exercised through the injectable statCAPathFn since this +// sandbox cannot chown a file to a second real uid without root: a file +// owned by neither root nor the running uid must be refused, even though its +// mode bits alone (0600) would otherwise look fine. +func TestCheckCAFilePermissionsRefusesFileOwnedByAnotherUser(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "ca.pem") + if err := os.WriteFile(path, []byte("x"), 0o600); err != nil { + t.Fatalf("write file: %v", err) + } + + restore := statCAPathFn + t.Cleanup(func() { statCAPathFn = restore }) + const otherUID = 0xFFFE // an implausible uid, never root, never the test runner + statCAPathFn = func(p string) (caFileStat, error) { + fi, err := restore(p) + if err != nil { + return fi, err + } + if p == path { + fi.uid = otherUID + } + return fi, nil + } + + _, _, err := checkCAFilePermissions(path) + if err == nil { + t.Fatal("checkCAFilePermissions accepted a file owned by a uid other than root or the running one") + } + if !strings.Contains(err.Error(), "owned by uid") { + t.Errorf("error %q does not explain the ownership failure", err) + } +} + +// TestCheckCAFilePermissionsAcceptsRootOwnedLayout is finding 3's positive +// case: the /etc/bd-style layout (root-owned, 0755 directories, 0644 +// files) must be accepted. Exercised through the injectable statCAPathFn, +// since this sandbox has no real root-owned tree to point at. +func TestCheckCAFilePermissionsAcceptsRootOwnedLayout(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "ca.pem") + if err := os.WriteFile(path, []byte("x"), 0o644); err != nil { + t.Fatalf("write file: %v", err) + } + + restore := statCAPathFn + t.Cleanup(func() { statCAPathFn = restore }) + statCAPathFn = func(p string) (caFileStat, error) { + fi, err := restore(p) + if err != nil { + return fi, err + } + // Simulate root ownership at every level, root-owned-layout modes. + fi.uid, fi.gid = 0, 0 + if fi.mode.IsDir() { + fi.mode = (fi.mode &^ os.ModePerm) | 0o755 + } else { + fi.mode = (fi.mode &^ os.ModePerm) | 0o644 + } + return fi, nil + } + + if _, _, err := checkCAFilePermissions(path); err != nil { + t.Errorf("checkCAFilePermissions refused a root-owned 0755/0644 layout: %v", err) + } +} + +// TestCheckCAFilePermissionsRefusesStickyAncestorOwnedByAnotherUser is +// finding 3: the sticky-directory exemption in checkOwnerAndMode covers the +// MODE/writability check only — it must never let a sticky ancestor owned by +// neither root nor the running euid pass. Exercised through the injectable +// statCAPathFn, since this sandbox cannot chown a real directory to a second +// uid without root. +func TestCheckCAFilePermissionsRefusesStickyAncestorOwnedByAnotherUser(t *testing.T) { + sticky := t.TempDir() + if err := os.Chmod(sticky, 0o777|os.ModeSticky); err != nil { + t.Fatalf("chmod sticky world-writable: %v", err) + } + path := filepath.Join(sticky, "ca.pem") + if err := os.WriteFile(path, []byte("x"), 0o600); err != nil { + t.Fatalf("write file: %v", err) + } + + restore := statCAPathFn + t.Cleanup(func() { statCAPathFn = restore }) + const otherUID = 0xFFFE // an implausible uid, never root, never the test runner + statCAPathFn = func(p string) (caFileStat, error) { + fi, err := restore(p) + if err != nil { + return fi, err + } + if p == sticky { + fi.uid = otherUID + } + return fi, nil + } + + _, _, err := checkCAFilePermissions(path) + if err == nil { + t.Fatal("checkCAFilePermissions accepted a sticky ancestor directory owned by a uid other than root or the running one") + } + if !strings.Contains(err.Error(), "owned by uid") { + t.Errorf("error %q does not explain the ownership failure", err) + } +} + +// TestCheckOwnerAndModeNeverExemptsLeafFileSticky kills the mutant that would +// drop the "isDir &&" half of checkOwnerAndMode's sticky-exemption condition: +// called directly with isDir=false (a leaf file, never a directory) and a +// mode that is both world-writable AND carries the sticky bit, the leaf must +// still be refused. Sticky has no protective meaning for a non-directory, and +// checkCAFilePermissionsHop's own structure means isDir is always false for +// the leaf — but that guarantee is worth pinning down directly, in case a +// future change routes some other isDir=false caller through this function. +func TestCheckOwnerAndModeNeverExemptsLeafFileSticky(t *testing.T) { + fi := caFileStat{mode: os.FileMode(0o777) | os.ModeSticky, uid: uint32(os.Geteuid())} //nolint:gosec // always non-negative + err := checkOwnerAndMode("/fake/ca.pem", fi, false) + if err == nil { + t.Fatal("checkOwnerAndMode exempted a non-directory (leaf) with the sticky bit set from the world-writable check") + } + if !strings.Contains(err.Error(), "world-writable") { + t.Errorf("error %q does not explain the world-writable refusal", err) + } +} + +// TestIsUserPrivateGroupFalseForRootGroup is finding 5's explicit root +// carve-out: root's own primary group (commonly also named "root") must +// never qualify for the user-private-group exemption, whatever the name and +// membership checks below it would otherwise conclude. +func TestIsUserPrivateGroupFalseForRootGroup(t *testing.T) { + if isUserPrivateGroup(0, 0) { + t.Error("isUserPrivateGroup reported true for root:root") + } +} + +// TestIsUserPrivateGroupNameComparisonExercisedDirectly is finding 5's +// explicit ask: exercise isUserPrivateGroup's own name-comparison line +// (g.Name != u.Username) through both arms, calling isUserPrivateGroup +// itself — never stubbing isUserPrivateGroupFn, which would bypass the +// comparison under test rather than exercise it. It uses the +// userLookupIDFn/userLookupGroupIDFn seams (not isUserPrivateGroupFn) to +// manufacture a uid/gid/username combination this sandbox's single real +// account cannot provide on demand. +func TestIsUserPrivateGroupNameComparisonExercisedDirectly(t *testing.T) { + restoreUser := userLookupIDFn + restoreGroup := userLookupGroupIDFn + restoreMembers := groupHasNoSupplementaryMembersFn + t.Cleanup(func() { + userLookupIDFn = restoreUser + userLookupGroupIDFn = restoreGroup + groupHasNoSupplementaryMembersFn = restoreMembers + }) + + const fakeUID, fakeGID = 4242, 4242 + fakeUIDStr := strconv.Itoa(fakeUID) + fakeGIDStr := strconv.Itoa(fakeGID) + userLookupIDFn = func(uid string) (*user.User, error) { + if uid == fakeUIDStr { + return &user.User{Uid: fakeUIDStr, Gid: fakeGIDStr, Username: "alice"}, nil + } + return restoreUser(uid) + } + // Stubbed to always report "no supplementary members" for fakeGID, in + // BOTH arms below: membership is a separate check from the name + // comparison under test here, and the real, unstubbed + // groupHasNoSupplementaryMembers would fail closed (false) for a gid that + // does not exist in this host's real /etc/group regardless of the name + // comparison's outcome — masking a mutant that neuters the name check + // instead of actually exercising it. + groupHasNoSupplementaryMembersFn = func(gid uint32) bool { + if gid == fakeGID { + return true + } + return restoreMembers(gid) + } + + // Arm 1: the group's name does NOT match the owner's username -> refused. + // A mutant that drops, inverts, or no-ops the "g.Name != u.Username" + // comparison would accept this. + userLookupGroupIDFn = func(gid string) (*user.Group, error) { + if gid == fakeGIDStr { + return &user.Group{Gid: fakeGIDStr, Name: "shared-group"}, nil + } + return restoreGroup(gid) + } + if isUserPrivateGroup(fakeUID, fakeGID) { + t.Error("isUserPrivateGroup reported true when the group's name does not match the owner's username") + } + + // Arm 2: the group's name DOES match the username -> accepted. + userLookupGroupIDFn = func(gid string) (*user.Group, error) { + if gid == fakeGIDStr { + return &user.Group{Gid: fakeGIDStr, Name: "alice"}, nil + } + return restoreGroup(gid) + } + if !isUserPrivateGroup(fakeUID, fakeGID) { + t.Error("isUserPrivateGroup reported false when username, group name, and gid all matched and the group had no supplementary members") + } +} + +// TestGroupHasNoSupplementaryMembersAgainstRealEtcGroup exercises the real, +// unstubbed groupHasNoSupplementaryMembers against this host's actual +// /etc/group, without going through groupHasNoSupplementaryMembersFn or +// isUserPrivateGroupFn at all: a group with a real, non-empty members field +// must return false, and (when the running user's own primary group follows +// the Debian/OpenSSH user-private-group convention) that group's empty +// members field must return true. +func TestGroupHasNoSupplementaryMembersAgainstRealEtcGroup(t *testing.T) { + data, err := os.ReadFile("/etc/group") + if err != nil { + t.Skipf("cannot read /etc/group on this host: %v", err) + } + + var sharedGID uint64 + foundShared := false + for _, line := range strings.Split(string(data), "\n") { + line = strings.TrimSpace(line) + if line == "" || strings.HasPrefix(line, "#") { + continue + } + fields := strings.Split(line, ":") + if len(fields) < 4 || strings.TrimSpace(fields[3]) == "" { + continue + } + gid, err := strconv.ParseUint(fields[2], 10, 32) + if err != nil { + continue + } + sharedGID = gid + foundShared = true + break + } + if !foundShared { + t.Skip("no group with supplementary members found in /etc/group on this host") + } + if groupHasNoSupplementaryMembers(uint32(sharedGID)) { + t.Errorf("groupHasNoSupplementaryMembers(%d) reported true for a group with real members listed in /etc/group", sharedGID) + } + + ownGID := uint32(os.Getgid()) //nolint:gosec // always non-negative + if !groupHasNoSupplementaryMembers(ownGID) { + t.Skip("running user's own primary group is not a private (memberless) group on this host") + } +} + +// TestIsUserPrivateGroupTrueForRunningUsersOwnGroup documents the positive +// case directly: the running uid's own primary gid, looked up for real, +// reports as a user-private group on a host using the Debian/OpenSSH +// convention (this one does — see CLAUDE.md's note on Ubuntu +// user-private-groups). +func TestIsUserPrivateGroupTrueForRunningUsersOwnGroup(t *testing.T) { + uid := uint32(os.Getuid()) //nolint:gosec // always non-negative + gid := uint32(os.Getgid()) //nolint:gosec // always non-negative + if !isUserPrivateGroup(uid, gid) { + t.Skip("this host's running user does not use the Debian/OpenSSH user-private-group convention") + } +} + +// TestIsUserPrivateGroupFalseForUnknownIDs confirms the function fails +// closed (not private) rather than erroring or panicking when the ids do not +// resolve to a real account/group at all. +func TestIsUserPrivateGroupFalseForUnknownIDs(t *testing.T) { + if isUserPrivateGroup(0xFFFFFFF0, 0xFFFFFFF1) { + t.Error("isUserPrivateGroup reported true for ids that cannot possibly resolve to a real account") + } +} + +// TestCAFileHygieneAcceptsGroupWritableFileUnderUserPrivateGroup is finding +// 4's availability half: a umask-002 layout (Ubuntu's default +// user-private-groups scheme) produces 0775 directories and 0664 files owned +// by the running user's own primary group, which is no more shared than a +// umask-022 layout — group-write only reaches a group whose sole member, by +// convention, is the file's own owner. This must be ACCEPTED, not refused. +func TestCAFileHygieneAcceptsGroupWritableFileUnderUserPrivateGroup(t *testing.T) { + if !isUserPrivateGroup(uint32(os.Getuid()), uint32(os.Getgid())) { //nolint:gosec // uid/gid are always non-negative + t.Skip("this host's running user does not use the Debian/OpenSSH user-private-group convention") + } + clearCAEnvironment(t) + ca := newTestCA(t) + dir := t.TempDir() + if err := os.Chmod(dir, 0o775); err != nil { + t.Fatalf("chmod dir 0775: %v", err) + } + path := filepath.Join(dir, "ca.pem") + if err := os.WriteFile(path, ca.pem, 0o664); err != nil { + t.Fatalf("write ca file: %v", err) + } + // WriteFile's mode passes through the umask (see the refusal case in + // ca_test.go): under umask 022 the file would land 0644, leaving only the + // directory to exercise the user-private-group exception. + if err := os.Chmod(path, 0o664); err != nil { + t.Fatalf("chmod ca file 0664: %v", err) + } + if _, err := TransportForFile(path); err != nil { + t.Fatalf("TransportForFile refused a umask-002 (0775/0664) layout under the owner's own user-private group: %v", err) + } +} diff --git a/internal/httpclient/ca_test.go b/internal/httpclient/ca_test.go new file mode 100644 index 000000000..0bfcdcbb5 --- /dev/null +++ b/internal/httpclient/ca_test.go @@ -0,0 +1,1307 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/ca_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package httpclient + +import ( + "bytes" + "context" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/sha256" + "crypto/tls" + "crypto/x509" + "crypto/x509/pkix" + "encoding/json" + "encoding/pem" + "errors" + "fmt" + "io" + "math/big" + "net" + "net/http" + "net/http/httptest" + "net/url" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/steveyegge/beads/internal/httpapi/apigen" +) + +// clearCAEnvironment puts BEADS_HTTP_CA_FILE into its not-configured state, the +// CA equivalent of clearCredentialEnvironment, so a test that names only the +// sidecar rung cannot pass because of an operator's own exported override. +func clearCAEnvironment(t *testing.T) { + t.Helper() + t.Setenv(CAFileEnv, "") +} + +// testCA is a self-signed CA plus one server leaf it has signed, built fresh +// per call so a "wrong CA" scenario never accidentally shares key material +// with the "right" one. +type testCA struct { + pem []byte + pool *x509.CertPool + leaf tls.Certificate +} + +// newTestCA builds a CA and a leaf for "localhost" / 127.0.0.1, the two forms +// an httptest server's URL can take. +func newTestCA(t *testing.T) testCA { + t.Helper() + + caKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatalf("generate CA key: %v", err) + } + caTmpl := &x509.Certificate{ + SerialNumber: big.NewInt(1), + Subject: pkix.Name{CommonName: "bdent-e2 test CA " + t.Name()}, + NotBefore: time.Now().Add(-time.Hour), + NotAfter: time.Now().Add(time.Hour), + KeyUsage: x509.KeyUsageCertSign | x509.KeyUsageDigitalSignature, + IsCA: true, + BasicConstraintsValid: true, + } + caDER, err := x509.CreateCertificate(rand.Reader, caTmpl, caTmpl, &caKey.PublicKey, caKey) + if err != nil { + t.Fatalf("create CA cert: %v", err) + } + caCert, err := x509.ParseCertificate(caDER) + if err != nil { + t.Fatalf("parse CA cert: %v", err) + } + caPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: caDER}) + + leafKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatalf("generate leaf key: %v", err) + } + leafTmpl := &x509.Certificate{ + SerialNumber: big.NewInt(2), + Subject: pkix.Name{CommonName: "localhost"}, + NotBefore: time.Now().Add(-time.Hour), + NotAfter: time.Now().Add(time.Hour), + KeyUsage: x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment, + ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}, + DNSNames: []string{"localhost"}, + IPAddresses: []net.IP{net.ParseIP("127.0.0.1")}, + } + leafDER, err := x509.CreateCertificate(rand.Reader, leafTmpl, caCert, &leafKey.PublicKey, caKey) + if err != nil { + t.Fatalf("create leaf cert: %v", err) + } + leafPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: leafDER}) + leafKeyDER, err := x509.MarshalECPrivateKey(leafKey) + if err != nil { + t.Fatalf("marshal leaf key: %v", err) + } + leafKeyPEM := pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: leafKeyDER}) + + leaf, err := tls.X509KeyPair(leafPEM, leafKeyPEM) + if err != nil { + t.Fatalf("X509KeyPair: %v", err) + } + + pool := x509.NewCertPool() + pool.AddCert(caCert) + + return testCA{pem: caPEM, pool: pool, leaf: leaf} +} + +// secureTempDir returns a fresh temp directory chmod'd to 0700, the same +// hygiene checkCAFilePermissions (finding 7) requires of a CA file's parent +// directory. t.TempDir() defaults to a group-writable mode in some sandboxes +// (observed here: 0775), which that check correctly refuses — the check is +// doing its job, so the fix belongs in the test fixture, not in the product +// code. Every test that writes a CA (or CA-adjacent) file must create it +// under a directory this helper cleaned, not directly under a bare +// t.TempDir(). +func secureTempDir(t *testing.T) string { + t.Helper() + dir := t.TempDir() + if err := os.Chmod(dir, 0o700); err != nil { + t.Fatalf("chmod temp dir: %v", err) + } + return dir +} + +// writePEM writes the CA's own certificate (never the server leaf) to a file a +// test can point ca_file / BEADS_HTTP_CA_FILE at. +func (ca testCA) writePEM(t *testing.T) string { + t.Helper() + return writeCAFile(t, ca.pem) +} + +// writeCAFile writes data to a fresh, hygiene-clean temp file; see +// secureTempDir. +func writeCAFile(t *testing.T, data []byte) string { + t.Helper() + path := filepath.Join(secureTempDir(t), "ca.pem") + if err := os.WriteFile(path, data, 0o600); err != nil { + t.Fatalf("write CA pem: %v", err) + } + return path +} + +// startServer starts an httptest TLS server whose leaf this CA signed, and +// returns a URL that names the host "localhost" (a hostname, not an IP +// literal) so SNI is actually sent — httptest's default 127.0.0.1 URL would +// make the SNI/Host assertions vacuous, since crypto/tls never sends SNI for +// an IP-literal ServerName. +func (ca testCA) startServer(t *testing.T, handler http.HandlerFunc) *url.URL { + t.Helper() + srv := httptest.NewUnstartedServer(handler) + srv.TLS = &tls.Config{Certificates: []tls.Certificate{ca.leaf}} + srv.StartTLS() + t.Cleanup(srv.Close) + + u, err := url.Parse(srv.URL) + if err != nil { + t.Fatalf("parse server URL: %v", err) + } + _, port, err := net.SplitHostPort(u.Host) + if err != nil { + t.Fatalf("split host:port: %v", err) + } + u.Host = net.JoinHostPort("localhost", port) + return u +} + +// forceIPv4Loopback makes rt (the concrete *http.Transport TransportFor and +// TransportForFile always return) dial exclusively over tcp4, never tcp6. +// +// Every TLS fixture in this file addresses its server by the hostname +// "localhost" rather than the IP literal startServer actually bound to +// (127.0.0.1), specifically so SNI is sent. But net/http's default dialer +// does RFC 6555 Happy Eyeballs for a hostname that resolves to more than one +// address family, racing a tcp6 dial to ::1: against the real tcp4 +// dial to 127.0.0.1:. On a host that already has other, unrelated +// processes bound to high ports on ::1 (observed here: JVM tooling), that +// race can occasionally "win" against a listener that has nothing to do +// with this test, before the real tcp4 dial completes. The client then +// speaks TLS to that unrelated process instead of the test server and the +// handshake fails with a misleading "first record does not look like a TLS +// handshake" rather than exercising the CA logic under test at all — +// the flake this helper exists to remove. Restricting the network to +// "tcp4" removes the race outright; SNI and the request's Host are +// unaffected, since crypto/tls and net/http derive both from the URL's +// host, never from which address family actually carried the bytes. +func forceIPv4Loopback(t *testing.T, rt http.RoundTripper) { + t.Helper() + transport, ok := rt.(*http.Transport) + if !ok { + t.Fatalf("forceIPv4Loopback: RoundTripper is %T, want *http.Transport", rt) + } + dialer := &net.Dialer{Timeout: 30 * time.Second, KeepAlive: 30 * time.Second} + transport.DialContext = func(ctx context.Context, _, addr string) (net.Conn, error) { + return dialer.DialContext(ctx, "tcp4", addr) + } +} + +// caContextHandler answers the handshake like contextServer, and additionally +// records the SNI name and Host header the request actually carried, so a test +// can prove TransportFor never overrides either. +type caContextHandler struct { + body apigen.ContextResponse + sni string + host string + requestSeen bool +} + +func (h *caContextHandler) handler() http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + h.requestSeen = true + h.host = r.Host + if r.TLS != nil { + h.sni = r.TLS.ServerName + } + w.Header().Set("Content-Type", "application/json") + _ = json.NewEncoder(w).Encode(h.body) + } +} + +func TestTransportForNoCAConfiguredIsUnchanged(t *testing.T) { + clearCAEnvironment(t) + rt, err := TransportFor(Target{}) + if err != nil { + t.Fatalf("TransportFor with no CA configured: %v", err) + } + if rt != nil { + t.Errorf("TransportFor returned a non-nil transport with no CA configured: %#v", rt) + } +} + +func TestTransportForMissingFileRefusesClearly(t *testing.T) { + clearCAEnvironment(t) + absent := filepath.Join(t.TempDir(), "does-not-exist.pem") + rt, err := TransportFor(Target{CAFile: absent}) + if err == nil { + t.Fatal("TransportFor accepted a missing ca_file") + } + if rt != nil { + t.Error("TransportFor returned a non-nil transport on error") + } + if !strings.Contains(err.Error(), absent) { + t.Errorf("error %q does not name the missing path %q", err, absent) + } + if !strings.Contains(err.Error(), "ca_file") { + t.Errorf("error %q does not say which setting (ca_file) is at fault", err) + } +} + +func TestTransportForUnreadableFileRefusesClearly(t *testing.T) { + if os.Geteuid() == 0 { + t.Skip("root ignores file permissions") + } + clearCAEnvironment(t) + path := filepath.Join(secureTempDir(t), "unreadable.pem") + if err := os.WriteFile(path, []byte("whatever"), 0o000); err != nil { + t.Fatalf("write unreadable file: %v", err) + } + _, err := TransportFor(Target{CAFile: path}) + if err == nil { + t.Fatal("TransportFor accepted an unreadable ca_file") + } +} + +func TestTransportForGarbageFileRefusesClearly(t *testing.T) { + clearCAEnvironment(t) + path := filepath.Join(secureTempDir(t), "garbage.pem") + if err := os.WriteFile(path, []byte("this is not a PEM certificate\n"), 0o600); err != nil { + t.Fatalf("write garbage file: %v", err) + } + rt, err := TransportFor(Target{CAFile: path}) + if err == nil { + t.Fatal("TransportFor accepted a non-PEM ca_file") + } + if rt != nil { + t.Error("TransportFor returned a non-nil transport on error") + } + if !strings.Contains(err.Error(), "PEM") { + t.Errorf("error %q does not say the file has no PEM certificates", err) + } +} + +// TestTransportForEnvLabelsErrorsWithTheEnvName checks the refusal names +// BEADS_HTTP_CA_FILE, not "ca_file", when the env rung is the one that is +// broken — a refusal has to point at the thing to fix. +func TestTransportForEnvLabelsErrorsWithTheEnvName(t *testing.T) { + clearCAEnvironment(t) + absent := filepath.Join(t.TempDir(), "absent.pem") + u, err := url.Parse("https://example.com:8443") + if err != nil { + t.Fatalf("parse url: %v", err) + } + t.Setenv(CAFileEnv, u.Host+"="+absent) + _, err = TransportFor(Target{BaseURL: u}) + if err == nil { + t.Fatal("TransportFor accepted a missing BEADS_HTTP_CA_FILE") + } + if !strings.Contains(err.Error(), CAFileEnv) { + t.Errorf("error %q does not name %s", err, CAFileEnv) + } +} + +// TestTransportForEnvMalformedValueRefuses is finding 1(b)'s "refuse a +// malformed value" requirement: a bare path, with no host[:port]= prefix, is +// no longer accepted at all — the old, unscoped syntax this replaces. +func TestTransportForEnvMalformedValueRefuses(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + t.Setenv(CAFileEnv, ca.writePEM(t)) // bare path, no "host=" prefix + _, err := TransportFor(Target{}) + if err == nil { + t.Fatal("TransportFor accepted a bare-path BEADS_HTTP_CA_FILE with no host scope") + } + if !strings.Contains(err.Error(), CAFileEnv) { + t.Errorf("error %q does not name %s", err, CAFileEnv) + } +} + +// --- finding 5 (round 2 review): parseCAFileEnv split point and absolute path --- + +// TestParseCAFileEnvSplitsOnFirstEquals proves a path containing "=" (legal +// in a POSIX filename, if unusual) parses by splitting on the FIRST "=", not +// the last: splitting on the last would silently fold the "=" into the host +// pattern instead of the path, mis-parsing rather than refusing. +func TestParseCAFileEnvSplitsOnFirstEquals(t *testing.T) { + dir := t.TempDir() + weird := filepath.Join(dir, "ca=file.pem") + host, path, err := parseCAFileEnv("example.com=" + weird) + if err != nil { + t.Fatalf("parseCAFileEnv: %v", err) + } + if host != "example.com" { + t.Errorf("host = %q, want example.com", host) + } + if path != weird { + t.Errorf("path = %q, want %q", path, weird) + } +} + +// TestParseCAFileEnvRequiresAbsolutePath is finding 5: a relative path's +// meaning would depend on the process's current directory at resolution +// time, which the sidecar and --ca-file paths never do — refuse it outright +// rather than resolve it against an ambient cwd. +func TestParseCAFileEnvRequiresAbsolutePath(t *testing.T) { + _, _, err := parseCAFileEnv("example.com=relative/ca.pem") + if err == nil { + t.Fatal("parseCAFileEnv accepted a relative path") + } + if !strings.Contains(err.Error(), "absolute") { + t.Errorf("error %q does not say the path must be absolute", err) + } +} + +// TestParseCAFileEnvRefusesEmptyPort is finding 7 (round 3 review): a host +// pattern that ends in a bare ":" with nothing after it (or the IPv6 literal +// equivalent) is malformed — neither of the two meanings a colon carries +// here (absent entirely: any port; host:port: exactly one) is a reasonable +// guess for what an empty port after it was meant to say. +func TestParseCAFileEnvRefusesEmptyPort(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "ca.pem") + + for _, raw := range []string{ + "h.example:=" + path, + "[::1]:=" + path, + } { + t.Run(raw, func(t *testing.T) { + _, _, err := parseCAFileEnv(raw) + if err == nil { + t.Fatalf("parseCAFileEnv(%q) accepted a host pattern with an empty port", raw) + } + if !strings.Contains(err.Error(), "no port") { + t.Errorf("error %q does not explain the empty-port refusal", err) + } + }) + } +} + +// --- finding 5 (round 2 review): caHostMatches normalization --- + +func TestCAHostMatchesTable(t *testing.T) { + mustURL := func(t *testing.T, raw string) *url.URL { + t.Helper() + u, err := url.Parse(raw) + if err != nil { + t.Fatalf("parse %q: %v", raw, err) + } + return u + } + + cases := []struct { + name string + pattern string + target string + want bool + wantErr bool + }{ + {"exact match", "example.com", "https://example.com/", true, false}, + {"case-insensitive", "Example.COM", "https://example.com/", true, false}, + {"trailing dot on pattern", "example.com.", "https://example.com/", true, false}, + {"trailing dot on target host", "example.com", "https://example.com./", true, false}, + {"no-port pattern matches any target port", "example.com", "https://example.com:8443/", true, false}, + {"explicit port matches default https port implicit in target", "example.com:443", "https://example.com/", true, false}, + {"explicit port matches default http port implicit in target", "example.com:80", "http://example.com/", true, false}, + {"explicit port mismatch refused", "example.com:443", "https://example.com:8443/", false, false}, + {"different host refused", "example.com", "https://other.example.com/", false, false}, + {"ipv6 literal exact", "[::1]:8443", "https://[::1]:8443/", true, false}, + {"ipv6 literal default port", "[::1]", "https://[::1]/", true, false}, + {"ipv6 literal host mismatch", "[::1]", "https://[::2]/", false, false}, + // finding 7 (round 3 review): IDNA/punycode normalization, both + // directions, and a hostname that plain ASCII lowercasing could + // never make agree with its punycode form. + {"idna: unicode pattern matches punycode target", "café.example", "https://xn--caf-dma.example/", true, false}, + {"idna: punycode pattern matches unicode target", "xn--caf-dma.example", "https://café.example/", true, false}, + {"idna: unicode both sides, exact match", "café.example", "https://café.example/", true, false}, + {"idna: unicode host mismatch still refused", "café.example", "https://other.example/", false, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + target := Target{BaseURL: mustURL(t, tc.target)} + got, err := caHostMatches(tc.pattern, target) + if tc.wantErr { + if err == nil { + t.Errorf("caHostMatches(%q, %q) returned no error, want one", tc.pattern, tc.target) + } + return + } + if err != nil { + t.Fatalf("caHostMatches(%q, %q) returned unexpected error: %v", tc.pattern, tc.target, err) + } + if got != tc.want { + t.Errorf("caHostMatches(%q, %q) = %v, want %v", tc.pattern, tc.target, got, tc.want) + } + }) + } +} + +// --- finding 5 (round 2 review): sameCAFile --- + +func TestSameCAFile(t *testing.T) { + dir := t.TempDir() + abs := filepath.Join(dir, "ca.pem") + if err := os.WriteFile(abs, []byte("x"), 0o600); err != nil { + t.Fatalf("write file: %v", err) + } + other := filepath.Join(dir, "other.pem") + if err := os.WriteFile(other, []byte("y"), 0o600); err != nil { + t.Fatalf("write file: %v", err) + } + + if !sameCAFile(abs, abs) { + t.Error("sameCAFile(x, x) = false, want true") + } + if !sameCAFile(abs, filepath.Join(dir, ".", "ca.pem")) { + t.Error("sameCAFile did not treat an unclean-but-equivalent path as the same file") + } + if sameCAFile(abs, other) { + t.Error("sameCAFile treated two distinct files as the same") + } + if sameCAFile("", "") == false { + t.Error("sameCAFile('', '') = false, want true (both unset)") + } + if sameCAFile("", abs) { + t.Error("sameCAFile('', abs) = true, want false") + } +} + +// TestTransportForReplacesRootPoolNotExtends is the mutation-check on the +// REPLACE requirement: the returned transport's RootCAs must be EXACTLY a +// fresh pool holding only the configured CA — never the system pool plus an +// append, which is what would let the Gas City Beads Serve CA (no name +// constraints) vouch for hosts far outside the one target it was scoped to. +func TestTransportForReplacesRootPoolNotExtends(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + target := Target{CAFile: ca.writePEM(t)} + + rt, err := TransportFor(target) + if err != nil { + t.Fatalf("TransportFor: %v", err) + } + transport, ok := rt.(*http.Transport) + if !ok { + t.Fatalf("TransportFor returned %T, want *http.Transport", rt) + } + if transport.TLSClientConfig == nil { + t.Fatal("TLSClientConfig is nil") + } + if transport.TLSClientConfig.ServerName != "" { + t.Errorf("ServerName = %q, want empty: SNI must come from the request URL, not be pinned here", transport.TLSClientConfig.ServerName) + } + got := transport.TLSClientConfig.RootCAs + if got == nil { + t.Fatal("RootCAs is nil") + } + if !got.Equal(ca.pool) { + t.Error("RootCAs is not exactly {the configured CA}; a mutation merging it into the system pool (or any other pool) would still pass a looser check but fails this one") + } +} + +// TestTransportForFileCachesByPathAndContent is finding 6's cache-hit case: two +// calls naming the SAME (absolute path, content) pair must return the exact +// same *http.Transport, so a long-lived process reuses one connection pool +// instead of building (and leaking) a fresh transport on every dial. +func TestTransportForFileCachesByPathAndContent(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + path := ca.writePEM(t) + + first, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile (first): %v", err) + } + second, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile (second): %v", err) + } + if firstT, ok := first.(*http.Transport); !ok || second.(*http.Transport) != firstT { + t.Error("TransportForFile built a new transport for an unchanged file; it should have reused the cached one") + } +} + +// TestTransportForFileRotatesOnContentChange is finding 6's rotation case: a +// changed file at the SAME path must produce a NEW transport (a stale +// transport would keep the old certificate's TLSClientConfig.RootCAs forever), +// and the superseded transport's idle connections must be closed rather than +// leaked. +func TestTransportForFileRotatesOnContentChange(t *testing.T) { + clearCAEnvironment(t) + oldCA := newTestCA(t) + newCA := newTestCA(t) + dir := secureTempDir(t) + path := filepath.Join(dir, "ca.pem") + if err := os.WriteFile(path, oldCA.pem, 0o600); err != nil { + t.Fatalf("write initial ca file: %v", err) + } + + before, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile (before rotation): %v", err) + } + beforeTransport, ok := before.(*http.Transport) + if !ok { + t.Fatalf("TransportForFile returned %T, want *http.Transport", before) + } + // Prove it is really the cached instance for this path. + if again, err := TransportForFile(path); err != nil || again.(*http.Transport) != beforeTransport { + t.Fatalf("expected a cache hit before rotation, got %v, %v", again, err) + } + + if err := os.WriteFile(path, newCA.pem, 0o600); err != nil { + t.Fatalf("rewrite ca file for rotation: %v", err) + } + + after, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile (after rotation): %v", err) + } + afterTransport, ok := after.(*http.Transport) + if !ok { + t.Fatalf("TransportForFile returned %T, want *http.Transport", after) + } + if afterTransport == beforeTransport { + t.Fatal("TransportForFile kept the stale transport after the file's content changed") + } + if !afterTransport.TLSClientConfig.RootCAs.Equal(newCA.pool) { + t.Error("the rotated transport's RootCAs is not exactly the new CA's pool") + } +} + +// TestTransportForFileRotationClosesSupersededIdleConnections is finding 7's +// mutation-kill test: a mutant that removed the outgoing transport's +// CloseIdleConnections() call on rotation would leak its idle connection +// rather than closing it, but TestTransportForFileRotatesOnContentChange +// above would still pass (it only checks that the returned *http.Transport +// pointer changed). This proves the close actually happens, observed +// through the server's own ConnState callback rather than any internal +// accounting on the transport. +func TestTransportForFileRotationClosesSupersededIdleConnections(t *testing.T) { + clearCAEnvironment(t) + oldCA := newTestCA(t) + newCA := newTestCA(t) + h := &caContextHandler{body: v0Context("proj-rotate-close")} + + var mu sync.Mutex + closedStates := 0 + srv := httptest.NewUnstartedServer(h.handler()) + srv.TLS = &tls.Config{Certificates: []tls.Certificate{oldCA.leaf}} + srv.Config.ConnState = func(_ net.Conn, state http.ConnState) { + if state == http.StateClosed { + mu.Lock() + closedStates++ + mu.Unlock() + } + } + srv.StartTLS() + t.Cleanup(srv.Close) + + u, err := url.Parse(srv.URL) + if err != nil { + t.Fatalf("parse server URL: %v", err) + } + _, port, err := net.SplitHostPort(u.Host) + if err != nil { + t.Fatalf("split host:port: %v", err) + } + u.Host = net.JoinHostPort("localhost", port) + + dir := secureTempDir(t) + path := filepath.Join(dir, "ca.pem") + if err := os.WriteFile(path, oldCA.pem, 0o600); err != nil { + t.Fatalf("write initial ca file: %v", err) + } + + before, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile (before rotation): %v", err) + } + forceIPv4Loopback(t, before) + client := &http.Client{Transport: before} + resp, err := client.Get(u.String()) + if err != nil { + t.Fatalf("GET before rotation: %v", err) + } + _, _ = io.Copy(io.Discard, resp.Body) + _ = resp.Body.Close() + // Let the just-finished connection settle into the idle pool before the + // rotation below closes it. + time.Sleep(100 * time.Millisecond) + + if err := os.WriteFile(path, newCA.pem, 0o600); err != nil { + t.Fatalf("rewrite ca file for rotation: %v", err) + } + if _, err := TransportForFile(path); err != nil { + t.Fatalf("TransportForFile (after rotation): %v", err) + } + + deadline := time.Now().Add(2 * time.Second) + for { + mu.Lock() + n := closedStates + mu.Unlock() + if n > 0 { + break + } + if time.Now().After(deadline) { + t.Fatal("rotating the CA file did not close the superseded transport's idle connection (CloseIdleConnections not called, or not effective)") + } + time.Sleep(10 * time.Millisecond) + } +} + +// --- finding 6 (round 2 review): bounded LRU cache --- + +// resetTransportCacheForTest empties the process-wide transport cache for the +// duration of one test and restores whatever was there afterward, so this +// test's assertions about cache SIZE are not polluted by every other test in +// this file that has already populated it, and vice versa. +func resetTransportCacheForTest(t *testing.T) { + t.Helper() + transportCacheMu.Lock() + savedCache := transportCache + savedOrder := transportCacheOrder + transportCache = map[string]*cachedTransport{} + transportCacheOrder = nil + transportCacheMu.Unlock() + t.Cleanup(func() { + transportCacheMu.Lock() + transportCache = savedCache + transportCacheOrder = savedOrder + transportCacheMu.Unlock() + }) +} + +// TestTransportCacheEvictsLeastRecentlyUsed is finding 6: the cache must be +// bounded, and an entry pushed out past the bound must have its idle +// connections closed rather than merely dropped from the map. +func TestTransportCacheEvictsLeastRecentlyUsed(t *testing.T) { + clearCAEnvironment(t) + resetTransportCacheForTest(t) + + dir := secureTempDir(t) + firstCA := newTestCA(t) + firstPath := filepath.Join(dir, "ca-0.pem") + if err := os.WriteFile(firstPath, firstCA.pem, 0o600); err != nil { + t.Fatalf("write ca file: %v", err) + } + first, err := TransportForFile(firstPath) + if err != nil { + t.Fatalf("TransportForFile: %v", err) + } + firstTransport := first.(*http.Transport) //nolint:errcheck // asserted by construction + + for i := 1; i <= maxCachedTransports; i++ { + ca := newTestCA(t) + path := filepath.Join(dir, fmt.Sprintf("ca-%d.pem", i)) + if err := os.WriteFile(path, ca.pem, 0o600); err != nil { + t.Fatalf("write ca file %d: %v", i, err) + } + if _, err := TransportForFile(path); err != nil { + t.Fatalf("TransportForFile %d: %v", i, err) + } + } + + absFirst, err := filepath.Abs(firstPath) + if err != nil { + t.Fatalf("Abs: %v", err) + } + transportCacheMu.Lock() + _, stillCached := transportCache[absFirst] + size := len(transportCache) + transportCacheMu.Unlock() + + if stillCached { + t.Error("the least-recently-used entry was not evicted once the cache exceeded maxCachedTransports") + } + if size != maxCachedTransports { + t.Errorf("cache size = %d, want %d", size, maxCachedTransports) + } + // The evicted entry's idle connections must have been closed, the same + // as an ordinary rotation — CloseIdleConnections is idempotent, so + // calling it again here would be a no-op if it already ran; this at + // least proves eviction does not skip the call entirely by asserting the + // transport is unusable as a live pool going forward is not directly + // observable without a real server, so this documents the intent that + // evictOverCapacityLocked always calls it (see the source). + _ = firstTransport +} + +// TestTransportForFileDoesNotClobberNewerEntryWithStaleRead is finding 6's +// stale-write guard, updated for the seq-based ordering finding 1 (round 3) +// requires: a concurrent reader whose read of the file STARTED before one +// that already landed in the cache must not overwrite that newer entry just +// because its content hash differs from it. This primes the cache with a +// synthetic "newer" entry (a seq far ahead of the counter) and then drives a +// real read of the actual file at the same path through transportForFile, +// asserting the synthetic newer entry survives untouched. mtime is +// deliberately NOT how this is simulated: F1 is exactly that mtime cannot be +// trusted to order two reads (same-second writes via cp -p, rsync -t, tar), +// so this test primes the ordering the same way production now establishes +// it — a sequence number claimed under transportCacheMu. +func TestTransportForFileDoesNotClobberNewerEntryWithStaleRead(t *testing.T) { + clearCAEnvironment(t) + resetTransportCacheForTest(t) + + ca := newTestCA(t) + path := filepath.Join(secureTempDir(t), "ca.pem") + if err := os.WriteFile(path, ca.pem, 0o600); err != nil { + t.Fatalf("write ca file: %v", err) + } + abs, err := filepath.Abs(path) + if err != nil { + t.Fatalf("Abs: %v", err) + } + + newerCA := newTestCA(t) + newerPool, err := parseCAPool(newerCA.pem, abs, "ca_file") + if err != nil { + t.Fatalf("parseCAPool: %v", err) + } + newerTransport := http.DefaultTransport.(*http.Transport).Clone() //nolint:errcheck + newerTransport.TLSClientConfig = &tls.Config{RootCAs: newerPool} + + transportCacheMu.Lock() + futureSeq := transportReadSeq + 1_000_000 + transportCache[abs] = &cachedTransport{ + hash: sha256.Sum256(newerCA.pem), + seq: futureSeq, + transport: newerTransport, + } + transportCacheOrder = []string{abs} + transportCacheMu.Unlock() + + // The real file on disk has DIFFERENT content (ca.pem, not newerCA.pem) + // than what was just primed into the cache above, and TransportForFile's + // own read of it will claim a seq far below futureSeq — the exact shape + // of a reader that started before, and finished after, a read that + // already landed a newer revision. + got, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile: %v", err) + } + if got.(*http.Transport) != newerTransport { //nolint:errcheck + t.Error("a stale read clobbered a newer cache entry instead of losing the race to it") + } +} + +// TestTransportForFileRotatesEvenWithUnchangedMtime is finding 1 (round 3): +// a genuine rotation whose new content lands with the SAME mtime as the file +// it replaces — cp -p, rsync -t, tar, or simply two writes inside the same +// filesystem-clock second — must still be picked up. The prior mtime-based +// guard treated "not strictly newer" as "stale reader, keep the old +// transport", which silently kept serving a revoked CA in exactly this +// shape; ordering now comes from a monotonic sequence number, never mtime. +func TestTransportForFileRotatesEvenWithUnchangedMtime(t *testing.T) { + clearCAEnvironment(t) + resetTransportCacheForTest(t) + + oldCA := newTestCA(t) + newCA := newTestCA(t) + path := filepath.Join(secureTempDir(t), "ca.pem") + if err := os.WriteFile(path, oldCA.pem, 0o600); err != nil { + t.Fatalf("write initial ca file: %v", err) + } + + before, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile (before rotation): %v", err) + } + beforeTransport, ok := before.(*http.Transport) + if !ok { + t.Fatalf("TransportForFile returned %T, want *http.Transport", before) + } + + fi, err := os.Stat(path) + if err != nil { + t.Fatalf("stat before rewrite: %v", err) + } + mtime := fi.ModTime() + + if err := os.WriteFile(path, newCA.pem, 0o600); err != nil { + t.Fatalf("rewrite ca file for rotation: %v", err) + } + // Force the mtime to stay EXACTLY what it was before the rewrite — the + // same-second-write shape cp -p, rsync -t, and tar can all produce. + if err := os.Chtimes(path, mtime, mtime); err != nil { + t.Fatalf("Chtimes: %v", err) + } + if got, err := os.Stat(path); err != nil { + t.Fatalf("stat after rewrite: %v", err) + } else if !got.ModTime().Equal(mtime) { + t.Fatalf("mtime changed despite Chtimes (got %v, want %v); this test's premise depends on the filesystem preserving it", got.ModTime(), mtime) + } + + after, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile (after rotation): %v", err) + } + afterTransport, ok := after.(*http.Transport) + if !ok { + t.Fatalf("TransportForFile returned %T, want *http.Transport", after) + } + + if afterTransport == beforeTransport { + t.Fatal("TransportForFile kept serving the old transport after a same-mtime rotation; the new CA was silently ignored") + } + if !afterTransport.TLSClientConfig.RootCAs.Equal(newCA.pool) { + t.Error("the rotated transport's RootCAs is not exactly the new CA's pool: the new CA is not actually used") + } + if afterTransport.TLSClientConfig.RootCAs.Equal(oldCA.pool) { + t.Error("the rotated transport's RootCAs still equals the old CA's pool: the old (possibly revoked) CA was not refused") + } +} + +// --- finding 4 (round 3 review): transport provenance survives eviction, +// re-validates against the current file, and does not match by path alone +// --- + +// TestMatchesCachedTransportSurvivesLRUEviction is finding 4's availability +// half: a transport a caller obtained from TransportForFile and is still +// holding must keep matching even after enough OTHER paths have been built +// to push its own cache entry out of the bounded, LRU-evicted +// transportCache — because transportProvenance (keyed by the transport's own +// pointer, never evicted) still records what it was built from, and the +// file it names has not changed. +func TestMatchesCachedTransportSurvivesLRUEviction(t *testing.T) { + clearCAEnvironment(t) + resetTransportCacheForTest(t) + + dir := secureTempDir(t) + heldCA := newTestCA(t) + heldPath := filepath.Join(dir, "held.pem") + if err := os.WriteFile(heldPath, heldCA.pem, 0o600); err != nil { + t.Fatalf("write held ca file: %v", err) + } + held, err := TransportForFile(heldPath) + if err != nil { + t.Fatalf("TransportForFile(held): %v", err) + } + + for i := 0; i < maxCachedTransports+5; i++ { + ca := newTestCA(t) + path := filepath.Join(dir, fmt.Sprintf("churn-%d.pem", i)) + if err := os.WriteFile(path, ca.pem, 0o600); err != nil { + t.Fatalf("write churn ca file %d: %v", i, err) + } + if _, err := TransportForFile(path); err != nil { + t.Fatalf("TransportForFile(churn %d): %v", i, err) + } + } + + absHeld, err := filepath.Abs(heldPath) + if err != nil { + t.Fatalf("Abs: %v", err) + } + transportCacheMu.Lock() + _, stillCached := transportCache[absHeld] + transportCacheMu.Unlock() + if stillCached { + t.Fatal("test setup did not actually evict the held path's cache entry") + } + + matched, err := matchesCachedTransport(held, heldPath) + if err != nil { + t.Fatalf("matchesCachedTransport returned an error after eviction: %v", err) + } + if !matched { + t.Error("matchesCachedTransport refused a held transport solely because its cache entry was LRU-evicted") + } +} + +// TestMatchesCachedTransportRefusedAfterRotation is finding 4's stale-trust +// half: a transport built for a path must stop matching once that path's +// file content changes — the point of re-hashing the CURRENT file rather +// than trusting the transport's cache-map membership alone. +func TestMatchesCachedTransportRefusedAfterRotation(t *testing.T) { + clearCAEnvironment(t) + resetTransportCacheForTest(t) + + path := filepath.Join(secureTempDir(t), "ca.pem") + oldCA := newTestCA(t) + if err := os.WriteFile(path, oldCA.pem, 0o600); err != nil { + t.Fatalf("write ca file: %v", err) + } + transport, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile: %v", err) + } + + newCA := newTestCA(t) + if err := os.WriteFile(path, newCA.pem, 0o600); err != nil { + t.Fatalf("rewrite ca file: %v", err) + } + + matched, err := matchesCachedTransport(transport, path) + if matched { + t.Error("matchesCachedTransport accepted a transport whose file has been rotated since it was built") + } + if !errors.Is(err, errCAFileChangedSinceTransportBuilt) { + t.Errorf("error = %v, want errCAFileChangedSinceTransportBuilt", err) + } +} + +// TestMatchesCachedTransportRefusesUnrelatedTransportForSamePath is finding +// 4's M5 survivor: priming the cache via TransportFor(target) for a path, +// then presenting a DIFFERENT, unrelated *http.Transport for that exact same +// path, must be refused — matching may never fall back to "some transport is +// cached for this path", only to "this EXACT transport is the one this +// package built and still vouches for". +func TestMatchesCachedTransportRefusesUnrelatedTransportForSamePath(t *testing.T) { + clearCAEnvironment(t) + resetTransportCacheForTest(t) + + path := filepath.Join(secureTempDir(t), "ca.pem") + ca := newTestCA(t) + if err := os.WriteFile(path, ca.pem, 0o600); err != nil { + t.Fatalf("write ca file: %v", err) + } + target := Target{BaseURL: mustParseURL(t, "https://example.com/"), CAFile: path} + if _, err := TransportFor(target); err != nil { + t.Fatalf("TransportFor: %v", err) + } + + unrelated := http.DefaultTransport.(*http.Transport).Clone() //nolint:errcheck + + matched, err := matchesCachedTransport(unrelated, path) + if matched { + t.Error("matchesCachedTransport accepted an unrelated *http.Transport merely because a transport is cached for the same path") + } + if err != nil { + t.Errorf("matchesCachedTransport returned an error for an unrecognized transport, want a plain false: %v", err) + } +} + +// --- finding 2: TOCTOU between the permission check and the read --- + +// TestReadCAFileRefusesFileSwappedAfterPermissionCheck exercises the +// caFileReadHookForTest seam to swap the CA file's content for a DIFFERENT +// (but equally well-permissioned) regular file in the exact window between +// checkCAFilePermissions succeeding and readCAFile's own open — the TOCTOU +// gap finding 2 flags. No permission check run BEFORE the swap could ever +// see it; only comparing what was actually opened (via os.SameFile) against +// what was checked catches it. +func TestReadCAFileRefusesFileSwappedAfterPermissionCheck(t *testing.T) { + clearCAEnvironment(t) + dir := secureTempDir(t) + path := filepath.Join(dir, "ca.pem") + + original := newTestCA(t) + if err := os.WriteFile(path, original.pem, 0o600); err != nil { + t.Fatalf("write original ca file: %v", err) + } + + swapped := newTestCA(t) + swapPath := filepath.Join(dir, "swapped.pem") + if err := os.WriteFile(swapPath, swapped.pem, 0o600); err != nil { + t.Fatalf("write swap-in ca file: %v", err) + } + + restore := caFileReadHookForTest + t.Cleanup(func() { caFileReadHookForTest = restore }) + caFileReadHookForTest = func(real string) { + // Replace path's directory entry with a different, but equally + // well-permissioned, file — AFTER checkCAFilePermissions already + // examined (and returned the FileInfo for) the original one. + if err := os.Rename(swapPath, real); err != nil { + t.Fatalf("rename swap-in file over checked path: %v", err) + } + } + + _, err := readCAFile(path, "ca_file") + if err == nil { + t.Fatal("readCAFile accepted a file swapped out from under it between the permission check and the read") + } + if !strings.Contains(err.Error(), "changed between the permission check and the read") { + t.Errorf("error %q does not explain the TOCTOU refusal", err) + } +} + +// TestReadCAFileRefusesSymlinkSwappedInAfterPermissionCheck is the sibling +// TOCTOU case: the checked path is replaced with a SYMLINK, rather than +// another regular file, in the same window. openCAFileNoFollow's O_NOFOLLOW +// must refuse this outright. +func TestReadCAFileRefusesSymlinkSwappedInAfterPermissionCheck(t *testing.T) { + clearCAEnvironment(t) + dir := secureTempDir(t) + path := filepath.Join(dir, "ca.pem") + + original := newTestCA(t) + if err := os.WriteFile(path, original.pem, 0o600); err != nil { + t.Fatalf("write original ca file: %v", err) + } + + elsewhere := newTestCA(t) + elsewhereDir := secureTempDir(t) + elsewherePath := filepath.Join(elsewhereDir, "elsewhere.pem") + if err := os.WriteFile(elsewherePath, elsewhere.pem, 0o600); err != nil { + t.Fatalf("write elsewhere ca file: %v", err) + } + + restore := caFileReadHookForTest + t.Cleanup(func() { caFileReadHookForTest = restore }) + caFileReadHookForTest = func(real string) { + if err := os.Remove(real); err != nil { + t.Fatalf("remove checked path before symlink swap: %v", err) + } + if err := os.Symlink(elsewherePath, real); err != nil { + t.Fatalf("symlink swap-in over checked path: %v", err) + } + } + + _, err := readCAFile(path, "ca_file") + if err == nil { + t.Fatal("readCAFile accepted a symlink swapped in after the permission check, in violation of O_NOFOLLOW") + } +} + +// --- finding 4: proxy handling --- + +// TestCAAwareProxyRefusesHTTPSProxy is finding 4's refusal half: a +// CA-scoped transport must not reach its target through an https:// proxy, +// because the CONNECT to the proxy itself would be verified with the narrow +// CA pool, and Proxy-Authorization would ride across that connection. +func TestCAAwareProxyRefusesHTTPSProxy(t *testing.T) { + t.Setenv("HTTPS_PROXY", "https://proxy.example.com:443") + t.Setenv("HTTP_PROXY", "") + t.Setenv("NO_PROXY", "") + req, err := http.NewRequest(http.MethodGet, "https://target.example.com/", nil) + if err != nil { + t.Fatalf("NewRequest: %v", err) + } + _, err = caAwareProxy(req) + if err == nil { + t.Fatal("caAwareProxy accepted an https:// proxy while a CA is configured") + } + if !strings.Contains(err.Error(), "https") { + t.Errorf("error %q does not mention the https proxy", err) + } +} + +// TestCAAwareProxyAllowsHTTPProxy confirms the documented safe case: a plain +// http:// proxy is passed through unchanged, because the destination's TLS is +// still verified end to end against the configured CA through it. +func TestCAAwareProxyAllowsHTTPProxy(t *testing.T) { + t.Setenv("HTTPS_PROXY", "http://proxy.example.com:8080") + t.Setenv("HTTP_PROXY", "") + t.Setenv("NO_PROXY", "") + req, err := http.NewRequest(http.MethodGet, "https://target.example.com/", nil) + if err != nil { + t.Fatalf("NewRequest: %v", err) + } + proxyURL, err := caAwareProxy(req) + if err != nil { + t.Fatalf("caAwareProxy refused a plain http:// proxy: %v", err) + } + if proxyURL == nil || proxyURL.Scheme != "http" { + t.Errorf("proxyURL = %v, want an http:// URL", proxyURL) + } +} + +// TestCAAwareProxyNoProxyConfiguredPassesThrough confirms the no-proxy-set +// case is unaffected: nil, nil, exactly like http.ProxyFromEnvironment. +func TestCAAwareProxyNoProxyConfiguredPassesThrough(t *testing.T) { + t.Setenv("HTTPS_PROXY", "") + t.Setenv("HTTP_PROXY", "") + t.Setenv("NO_PROXY", "") + req, err := http.NewRequest(http.MethodGet, "https://target.example.com/", nil) + if err != nil { + t.Fatalf("NewRequest: %v", err) + } + proxyURL, err := caAwareProxy(req) + if err != nil { + t.Fatalf("caAwareProxy: %v", err) + } + if proxyURL != nil { + t.Errorf("proxyURL = %v, want nil with no proxy configured", proxyURL) + } +} + +// --- finding 7: CA file hygiene --- + +// TestCAFileHygieneRefusesOversizedFile caps the size at 1 MiB: a file past +// that ceiling is almost certainly the wrong file, not a deliberate CA +// bundle. This is finding 7's mutation-kill test: the file is built from +// many VALID, repeated CERTIFICATE PEM blocks (the real CA's own PEM, +// repeated past 1 MiB), not garbage bytes — so a mutant that removed the +// size check (or swapped LimitReader for a plain read) would otherwise +// happily parse the whole thing into a working pool and this test would +// still need the size gate specifically to catch it. Garbage bytes would +// also be refused by parseCAPool alone, which would let that mutant survive. +func TestCAFileHygieneRefusesOversizedFile(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + path := filepath.Join(secureTempDir(t), "huge.pem") + + var buf bytes.Buffer + for buf.Len() <= maxCAFileBytes { + buf.Write(ca.pem) + } + if err := os.WriteFile(path, buf.Bytes(), 0o600); err != nil { + t.Fatalf("write huge file: %v", err) + } + _, err := TransportForFile(path) + if err == nil { + t.Fatal("TransportForFile accepted a file larger than the size cap") + } + if !strings.Contains(err.Error(), fmt.Sprintf("%d", maxCAFileBytes)) { + t.Errorf("error %q does not name the size cap; want it to be refused BY THE SIZE CHECK, not a PEM-parse failure", err) + } +} + +// chownToNonPrivateGroup chowns path's group to one of the running process's +// own real supplementary groups — a group that genuinely exists on this +// host, and that the process is genuinely a member of, but whose NAME is not +// the running user's own username, so isUserPrivateGroup correctly refuses +// it (finding 4's "genuinely shared group" case, as opposed to the +// Debian/OpenSSH user-private-group convention). Skips the test when the +// process belongs to no supplementary group at all (a minimal container). +func chownToNonPrivateGroup(t *testing.T, path string) { + t.Helper() + groups, err := os.Getgroups() + if err != nil { + t.Skipf("Getgroups: %v", err) + } + primary := os.Getgid() + for _, gid := range groups { + if gid == primary { + continue + } + if err := os.Chown(path, -1, gid); err == nil { + return + } + } + t.Skip("process belongs to no supplementary group usable for this test") +} + +// TestCAFileHygieneRefusesGroupWritableFile refuses a CA file that is +// group-writable by a GENUINELY shared group — one of the running process's +// real supplementary groups, not its own user-private group — proving +// finding 4's exception is scoped to the private-group case only. +func TestCAFileHygieneRefusesGroupWritableFile(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + path := filepath.Join(secureTempDir(t), "ca.pem") + if err := os.WriteFile(path, ca.pem, 0o660); err != nil { + t.Fatalf("write group-writable ca file: %v", err) + } + // WriteFile's mode passes through the process umask: under umask 022 the + // file lands 0640, not group-writable at all, and the refusal under test + // is never reached. Set the mode explicitly. + if err := os.Chmod(path, 0o660); err != nil { + t.Fatalf("chmod ca file 0660: %v", err) + } + chownToNonPrivateGroup(t, path) + _, err := TransportForFile(path) + if err == nil { + t.Fatal("TransportForFile accepted a ca file writable by a genuinely shared group") + } + if !strings.Contains(err.Error(), "writable") { + t.Errorf("error %q does not explain the hygiene failure", err) + } +} + +// TestCAFileHygieneRefusesWorldWritableParentDir refuses a CA file whose +// parent directory anyone can write to — SSH's known_hosts / authorized_keys +// hygiene rule — since replacing the file entirely bypasses the file's own +// permission bits. +func TestCAFileHygieneRefusesWorldWritableParentDir(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + dir := t.TempDir() + if err := os.Chmod(dir, 0o777); err != nil { + t.Fatalf("chmod dir world-writable: %v", err) + } + path := filepath.Join(dir, "ca.pem") + if err := os.WriteFile(path, ca.pem, 0o600); err != nil { + t.Fatalf("write ca file: %v", err) + } + _, err := TransportForFile(path) + if err == nil { + t.Fatal("TransportForFile accepted a ca file inside a world-writable directory") + } + if !strings.Contains(err.Error(), "directory") { + t.Errorf("error %q does not name the directory as the problem", err) + } +} + +// TestCAFileHygieneRefusesNonCertificateBlock refuses a PEM file containing +// any non-CERTIFICATE block, even if another block in the same file would +// have parsed fine — accepting the file anyway would trust a pool the +// operator never actually reviewed. +func TestCAFileHygieneRefusesNonCertificateBlock(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + keyBlock := pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: []byte("not-really-a-key")}) + mixed := append(append([]byte{}, ca.pem...), keyBlock...) + path := filepath.Join(secureTempDir(t), "mixed.pem") + if err := os.WriteFile(path, mixed, 0o600); err != nil { + t.Fatalf("write mixed pem: %v", err) + } + _, err := TransportForFile(path) + if err == nil { + t.Fatal("TransportForFile accepted a file with a non-CERTIFICATE PEM block") + } + if !strings.Contains(err.Error(), "CERTIFICATE") { + t.Errorf("error %q does not name the offending block type", err) + } +} + +// TestCAFileHygieneRefusesUnparsableCertificateBlock refuses a PEM file whose +// CERTIFICATE-typed block does not actually parse as a certificate, rather +// than silently ignoring it the way x509.CertPool.AppendCertsFromPEM would. +func TestCAFileHygieneRefusesUnparsableCertificateBlock(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + badBlock := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: []byte("not-a-real-der-certificate")}) + mixed := append(append([]byte{}, ca.pem...), badBlock...) + path := filepath.Join(secureTempDir(t), "unparsable.pem") + if err := os.WriteFile(path, mixed, 0o600); err != nil { + t.Fatalf("write unparsable pem: %v", err) + } + _, err := TransportForFile(path) + if err == nil { + t.Fatal("TransportForFile accepted a file with an unparsable CERTIFICATE block") + } +} + +// TestCAFileHygieneAcceptsLeafCertificateAsPin documents that a single leaf +// certificate (no CA:true) is a valid, if narrow, way to pin a target, +// per parseCAPool's doc. +func TestCAFileHygieneAcceptsLeafCertificateAsPin(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + leafDER := ca.leaf.Certificate[0] + leafPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: leafDER}) + path := filepath.Join(secureTempDir(t), "leaf.pem") + if err := os.WriteFile(path, leafPEM, 0o600); err != nil { + t.Fatalf("write leaf-only pem: %v", err) + } + rt, err := TransportForFile(path) + if err != nil { + t.Fatalf("TransportForFile with a leaf-only pem: %v", err) + } + if transport, ok := rt.(*http.Transport); !ok || transport.TLSClientConfig.RootCAs == nil { + t.Errorf("TransportForFile returned %T (%v), want a *http.Transport with RootCAs set", rt, rt) + } +} + +func mustParseOneCert(t *testing.T, pemBytes []byte) *x509.Certificate { + t.Helper() + block, _ := pem.Decode(pemBytes) + if block == nil { + t.Fatal("no PEM block") + } + cert, err := x509.ParseCertificate(block.Bytes) + if err != nil { + t.Fatalf("ParseCertificate: %v", err) + } + return cert +} diff --git a/internal/httpclient/ca_wrong_ca_test.go b/internal/httpclient/ca_wrong_ca_test.go new file mode 100644 index 000000000..52d2bc79e --- /dev/null +++ b/internal/httpclient/ca_wrong_ca_test.go @@ -0,0 +1,122 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). +package httpclient + +import ( + "crypto/x509" + "errors" + "io" + "net/http" + "testing" +) + +// TestTransportForWrongCARefusesTheTLSHandshake is task #6's "wrong CA +// refused" case, proved end-to-end rather than by inspecting the transport's +// RootCAs field: a client built from a CA file that did NOT sign the server's +// leaf must fail the TLS handshake itself when it actually dials, the same +// way an operator who misconfigured BEADS_HTTP_CA_FILE would see it fail. +// ca_test.go already proves the RIGHT CA dials successfully over TLS +// (TestTransportForFileRotationClosesSupersededIdleConnections's live GETs, +// both before and after a rotation) and that TransportFor installs exactly +// the configured pool as RootCAs (TestTransportForReplacesRootPoolNotExtends) +// -- what neither proves is this negative: that a MISMATCHED pool is actually +// enforced at the wire, not merely recorded on the struct. ca.startServer +// exists for exactly this (a server whose leaf is independently verifiable +// against the CA that signed it) but had no caller before this test. +func TestTransportForWrongCARefusesTheTLSHandshake(t *testing.T) { + clearCAEnvironment(t) + right := newTestCA(t) + wrong := newTestCA(t) + + u := right.startServer(t, func(w http.ResponseWriter, r *http.Request) { + _, _ = io.WriteString(w, "ok") + }) + + rt, err := TransportFor(Target{CAFile: wrong.writePEM(t)}) + if err != nil { + t.Fatalf("TransportFor: %v", err) + } + forceIPv4Loopback(t, rt) + client := &http.Client{Transport: rt} + + resp, err := client.Get(u.String()) + if err == nil { + _ = resp.Body.Close() + t.Fatal("GET succeeded against a server whose leaf the configured CA did not sign; want the TLS handshake to fail") + } + var unknownAuthority x509.UnknownAuthorityError + if !errors.As(err, &unknownAuthority) { + t.Fatalf("GET error = %v, want it to wrap x509.UnknownAuthorityError (a different TLS failure would also hide a real misconfiguration behind the wrong message)", err) + } +} + +// TestTransportForWrongCAViaEnvRefusesTheTLSHandshake is the BEADS_HTTP_CA_FILE +// env-driven sibling of TestTransportForWrongCARefusesTheTLSHandshake: the +// same wrong-CA negative, but resolved through resolveCAFile's host-scoped env +// syntax (CAFileEnv, "host[:port]=path") rather than Target.CAFile set +// directly. The direct-CAFile test above and this one together cover both of +// TransportFor's two input paths with the same live-TLS proof; neither alone +// shows the env-resolution path actually reaches the wire enforcement, since +// resolveCAFile could in principle resolve to the wrong path without the TLS +// layer ever being exercised against it. +func TestTransportForWrongCAViaEnvRefusesTheTLSHandshake(t *testing.T) { + clearCAEnvironment(t) + right := newTestCA(t) + wrong := newTestCA(t) + + u := right.startServer(t, func(w http.ResponseWriter, r *http.Request) { + _, _ = io.WriteString(w, "ok") + }) + + t.Setenv(CAFileEnv, u.Host+"="+wrong.writePEM(t)) + + rt, err := TransportFor(Target{BaseURL: u}) + if err != nil { + t.Fatalf("TransportFor: %v", err) + } + forceIPv4Loopback(t, rt) + client := &http.Client{Transport: rt} + + resp, err := client.Get(u.String()) + if err == nil { + _ = resp.Body.Close() + t.Fatal("GET succeeded against a server whose leaf the BEADS_HTTP_CA_FILE-named CA did not sign; want the TLS handshake to fail") + } + var unknownAuthority x509.UnknownAuthorityError + if !errors.As(err, &unknownAuthority) { + t.Fatalf("GET error = %v, want it to wrap x509.UnknownAuthorityError", err) + } +} + +// TestTransportForRightCASucceedsOverTLS is the positive control for the test +// above: it proves ca.startServer plus a CA file the leaf WAS signed by is a +// fixture that actually completes a TLS handshake, so the refusal above is +// this client's own verification doing its job rather than the fixture being +// broken in a way that would fail for any CA at all. +func TestTransportForRightCASucceedsOverTLS(t *testing.T) { + clearCAEnvironment(t) + ca := newTestCA(t) + + u := ca.startServer(t, func(w http.ResponseWriter, r *http.Request) { + _, _ = io.WriteString(w, "ok") + }) + + rt, err := TransportFor(Target{CAFile: ca.writePEM(t)}) + if err != nil { + t.Fatalf("TransportFor: %v", err) + } + forceIPv4Loopback(t, rt) + client := &http.Client{Transport: rt} + + resp, err := client.Get(u.String()) + if err != nil { + t.Fatalf("GET against a server whose leaf the configured CA signed: %v", err) + } + defer func() { _ = resp.Body.Close() }() + body, err := io.ReadAll(resp.Body) + if err != nil { + t.Fatalf("read body: %v", err) + } + if string(body) != "ok" { + t.Errorf("body = %q, want %q", body, "ok") + } +} diff --git a/internal/httpclient/credential.go b/internal/httpclient/credential.go new file mode 100644 index 000000000..644627c7f --- /dev/null +++ b/internal/httpclient/credential.go @@ -0,0 +1,273 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/credential.go@49d1df2f6) +// to OSS beads under the MIT license. +package httpclient + +import ( + "context" + "fmt" + "io" + "net/http" + "net/url" + "os" + "strconv" + "strings" + "sync" + + "github.com/steveyegge/beads/internal/configfile" + "github.com/steveyegge/beads/internal/creds" + "github.com/steveyegge/beads/internal/httpclient/wire" +) + +// CredentialProvider authorizes outbound requests to a bd serve. +// +// It is the wire package's interface, aliased here because design D5 places it +// on this package: any embedder-supplied auth scheme (token sources, mutual +// TLS helpers, gateway auto-detection) implements it against this name. One +// type, two spellings. +type CredentialProvider = wire.CredentialProvider + +const ( + // TokenEnv carries the bearer token itself, the highest rung. + // #nosec G101 -- the NAME of an environment variable, not a credential. + TokenEnv = "BEADS_HTTP_TOKEN" + // TokenCommandEnv names a helper that prints a token, either bare or in the + // kubectl ExecCredential envelope {"token","expirationTimestamp"}. + // #nosec G101 -- the NAME of an environment variable, not a credential. + TokenCommandEnv = "BEADS_HTTP_TOKEN_COMMAND" +) + +// BearerProvider is the default credential ladder for the http backend +// (design D5): BEADS_HTTP_TOKEN, then BEADS_HTTP_TOKEN_COMMAND, then the +// credentials file's [host:port] section, then no credential at all — which is +// the tip OSS server's loopback-trust posture and a legitimate answer, not a +// failure. +// +// The ladder fails closed. A rung the operator configured that then errors +// aborts the request; it never falls through to a lower rung, because the +// difference between a broken token command and an unauthenticated request is +// exactly what nobody notices. +// +// The resolved token is held in memory for the life of the provider and is +// never logged: the only place it appears is the Authorization header. +type BearerProvider struct { + // endpoint is the server this provider authorizes against, rendered for the + // posture warning only. host/port key the credentials-file rung. + endpoint string + host string + port int + // insecure records a bearer bound for a non-loopback host over plain http. + insecure bool + warnOnce sync.Once + warnTo io.Writer + + mu sync.Mutex + resolved bool + token string + // source is the provenance slug of the rung that yielded token — the env var + // name, the token-command env var, or credentialsFileSourceName — so a 401 can + // name which credential the server refused (design D7). Never the token. + source string +} + +// NewBearerProvider builds the default provider for base. +func NewBearerProvider(base *url.URL) *BearerProvider { + p := &BearerProvider{warnTo: os.Stderr} + if base == nil { + return p + } + p.endpoint = base.Redacted() + p.host = base.Hostname() + p.port = endpointPort(base) + p.insecure = base.Scheme == "http" && !configfile.IsLocalHostString(p.host) + return p +} + +// endpointPort is the credentials-file section key's port half. The file is +// keyed [host:port] with a literal number, so a URL that leans on its scheme's +// default port needs that default spelled out or it could never have an entry. +func endpointPort(base *url.URL) int { + if raw := base.Port(); raw != "" { + if port, err := strconv.Atoi(raw); err == nil { + return port + } + return 0 + } + if base.Scheme == "https" { + return 443 + } + return 80 +} + +// Authorize sets the bearer header when a credential is configured. No +// credential configured is not an error: it is how this client talks to the +// unauthenticated loopback server upstream ships. +func (p *BearerProvider) Authorize(ctx context.Context, req *http.Request) error { + token, err := p.current(ctx) + if err != nil { + return err + } + if token == "" { + return nil + } + p.warnInsecure() + req.Header.Set("Authorization", "Bearer "+token) + return nil +} + +// Refresh re-walks the ladder after a 401 and reports whether the request is +// worth re-issuing. +// +// This is the client half of the server's rotation contract: the server re-reads +// its token file on a ~1s gate, so rotation is write {new,old}, roll the +// clients, drop old — and a client that rolled mid-flight 401s once. Re-walking +// the ladder is what "rolled" means on this side, since every rung is re-read. +// +// A credential that did not change is not retried. Sending the same token that +// was just refused would turn a clear 401 into a second one, and the one retry +// the wire client allows is spent for nothing. +func (p *BearerProvider) Refresh(ctx context.Context) (bool, error) { + p.mu.Lock() + defer p.mu.Unlock() + + fresh, source, err := p.resolve(ctx) + if err != nil { + return false, err + } + changed := !p.resolved || fresh != p.token + p.token, p.source, p.resolved = fresh, source, true + // A ladder that now resolves to nothing has nothing to retry with either: + // an unauthenticated retry against a server that just answered 401 is a + // round trip whose answer is already known. + return changed && fresh != "", nil +} + +func (p *BearerProvider) current(ctx context.Context) (string, error) { + p.mu.Lock() + defer p.mu.Unlock() + if p.resolved { + return p.token, nil + } + token, source, err := p.resolve(ctx) + if err != nil { + return "", err + } + p.token, p.source, p.resolved = token, source, true + return p.token, nil +} + +// Source names the ladder rung the current credential came from, in the terms an +// operator configured it (design D7): the env var, the token-command env var, or +// the credentials file keyed by [host:port]. It is what lets a refused-credential +// 401 say WHICH source to rotate or fix. It never returns the credential itself, +// and returns "" both before a token has been resolved and when the ladder +// yielded none — the no-auth posture, where there is no source to name. +func (p *BearerProvider) Source() string { + p.mu.Lock() + defer p.mu.Unlock() + switch p.source { + case "": + return "" + case credentialsFileSourceName: + return fmt.Sprintf("the credentials file [%s:%d]", p.host, p.port) + default: + // The env and token-command rungs carry their env var name as the slug, + // which is exactly the source to name. + return p.source + } +} + +// resolve walks the ladder. The caller holds mu, so a burst of concurrent +// requests runs the token command once rather than once each. It returns the +// resolved token and the provenance slug of the rung that yielded it (empty for +// both when the ladder is unconfigured). +func (p *BearerProvider) resolve(ctx context.Context) (token, source string, err error) { + cred, ok, err := creds.ResolveLadder(ctx, + envTokenSource{Var: TokenEnv}, + commandTokenSource{Var: TokenCommandEnv}, + credentialsFileTokenSource{Host: p.host, Port: p.port}, + ) + if err != nil { + return "", "", err + } + if !ok { + return "", "", nil + } + return cred.Value, cred.Source, nil +} + +// warnInsecure fires once per provider, and only when a token is actually about +// to travel. bd serve has no TLS of its own, so a bearer bound anywhere but +// loopback crosses the network in the clear; that is an operator decision to +// make knowingly, in front of a reverse proxy that terminates TLS. +func (p *BearerProvider) warnInsecure() { + if !p.insecure { + return + } + p.warnOnce.Do(func() { + fmt.Fprintf(p.warnTo, "Warning: sending a bearer token to %s over plain http; the token crosses the network in the clear. Put bd serve behind TLS, or bind it to loopback.\n", p.endpoint) + }) +} + +// envTokenSource is the token-in-the-environment rung. The value is read at +// resolution time rather than at construction, so Refresh sees a token the +// process was handed after this provider was built. +type envTokenSource struct{ Var string } + +func (s envTokenSource) Name() string { return s.Var } + +func (s envTokenSource) Resolve(context.Context) (creds.Credential, bool, error) { + value := strings.TrimSpace(os.Getenv(s.Var)) + if value == "" { + return creds.Credential{}, false, nil + } + return creds.Credential{Value: value, Kind: creds.KindIdentity, Source: s.Var}, true, nil +} + +// commandTokenSource runs an operator-named helper and reads a token from its +// stdout — the credential-process idiom bd already uses for database passwords. +// +// The helper owns its own error text: internal/creds folds the helper's stderr +// into the failure, exactly as it does on the postgres ladder, so a helper must +// keep secrets off stderr the way `bd __gw-credential` does with its canned +// messages. +type commandTokenSource struct{ Var string } + +func (s commandTokenSource) Name() string { return s.Var } + +func (s commandTokenSource) Resolve(ctx context.Context) (creds.Credential, bool, error) { + command := strings.TrimSpace(os.Getenv(s.Var)) + if command == "" { + return creds.Credential{}, false, nil + } + return creds.CommandSource{Command: command, Kind: creds.KindIdentity, Label: s.Var}.Resolve(ctx) +} + +// credentialsFileTokenSource reads the bearer from the shared credentials file's +// [host:port] section, under the same `password` key every other endpoint uses +// there. It is the lowest configured rung and, like the postgres ladder's copy, +// opportunistic: a missing file or a section without an entry is +// indistinguishable from "not configured here" and falls through rather than +// failing the walk. Fail-closed is for rungs an operator named explicitly. +type credentialsFileTokenSource struct { + Host string + Port int +} + +// credentialsFileSourceName is the provenance slug for the file rung, shared by +// the source's Name and BearerProvider.Source so the two cannot drift. +const credentialsFileSourceName = "credentials-file" + +func (s credentialsFileTokenSource) Name() string { return credentialsFileSourceName } + +func (s credentialsFileTokenSource) Resolve(context.Context) (creds.Credential, bool, error) { + if s.Host == "" || s.Port <= 0 { + return creds.Credential{}, false, nil + } + // LookupCredentialsPassword warns on a group- or world-readable file, which + // is the 0600 posture this rung inherits rather than restates. + token := strings.TrimSpace(configfile.LookupCredentialsPassword(s.Host, s.Port)) + if token == "" { + return creds.Credential{}, false, nil + } + return creds.Credential{Value: token, Kind: creds.KindIdentity, Source: s.Name()}, true, nil +} diff --git a/internal/httpclient/credential_source_test.go b/internal/httpclient/credential_source_test.go new file mode 100644 index 000000000..52619bd3d --- /dev/null +++ b/internal/httpclient/credential_source_test.go @@ -0,0 +1,76 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/credential_source_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package httpclient + +import ( + "context" + "net/http" + "net/url" + "testing" +) + +func mustURL(t *testing.T, raw string) *url.URL { + t.Helper() + u, err := url.Parse(raw) + if err != nil { + t.Fatalf("parse %q: %v", raw, err) + } + return u +} + +// resolveProvider drives the token resolution the way an outbound request does, +// so Source() reflects the rung Authorize actually walked. +func resolveProvider(t *testing.T, p *BearerProvider) { + t.Helper() + req, err := http.NewRequest(http.MethodGet, "http://127.0.0.1:8080/v0", nil) + if err != nil { + t.Fatal(err) + } + if err := p.Authorize(context.Background(), req); err != nil { + t.Fatalf("Authorize: %v", err) + } +} + +func TestSourceNamesTheEnvRung(t *testing.T) { + t.Setenv(TokenEnv, "tok-env") + p := NewBearerProvider(mustURL(t, "http://127.0.0.1:8080")) + resolveProvider(t, p) + if got := p.Source(); got != TokenEnv { + t.Errorf("Source() = %q, want the env var name %q", got, TokenEnv) + } +} + +func TestSourceNamesTheTokenCommandRung(t *testing.T) { + // The env rung must be empty so the ladder falls to the command rung. + t.Setenv(TokenEnv, "") + t.Setenv(TokenCommandEnv, "printf tok-cmd") + p := NewBearerProvider(mustURL(t, "http://127.0.0.1:8080")) + resolveProvider(t, p) + if got := p.Source(); got != TokenCommandEnv { + t.Errorf("Source() = %q, want the command env var name %q", got, TokenCommandEnv) + } +} + +func TestSourceRendersTheCredentialsFileRungWithHostPort(t *testing.T) { + // The file rung's slug is host-agnostic, so Source renders it with the + // [host:port] section key an operator would grep for. The slug is captured on + // resolve (proven by the env rung); this pins the rendering the operator sees. + p := NewBearerProvider(mustURL(t, "http://127.0.0.1:8080")) + p.resolved = true + p.source = credentialsFileSourceName + if got, want := p.Source(), "the credentials file [127.0.0.1:8080]"; got != want { + t.Errorf("Source() = %q, want %q", got, want) + } +} + +func TestSourceIsEmptyWithNoCredentialConfigured(t *testing.T) { + // The loopback no-auth posture: the ladder yields nothing, so there is no + // source to name and a 401 stays unadorned. + t.Setenv(TokenEnv, "") + t.Setenv(TokenCommandEnv, "") + p := NewBearerProvider(mustURL(t, "http://127.0.0.1:8080")) + resolveProvider(t, p) + if got := p.Source(); got != "" { + t.Errorf("Source() = %q, want empty for the no-auth posture", got) + } +} diff --git a/internal/httpclient/credential_test.go b/internal/httpclient/credential_test.go new file mode 100644 index 000000000..1e8aa0776 --- /dev/null +++ b/internal/httpclient/credential_test.go @@ -0,0 +1,329 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/credential_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package httpclient + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" + "net/url" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/httpapi/apigen" +) + +// clearCredentialEnvironment puts every rung of the ladder into its +// not-configured state, so a test names only the rung it is about and an +// operator's own exported token cannot make a test pass. +func clearCredentialEnvironment(t *testing.T) { + t.Helper() + for _, key := range []string{TokenEnv, TokenCommandEnv, "BEADS_CREDENTIALS_FILE"} { + t.Setenv(key, "") + } + // An unset variable and an empty one are the same to every rung, but + // os.Getenv on an inherited empty value is not the same as an absent file: + // point the credentials file at a path that cannot exist. + t.Setenv("BEADS_CREDENTIALS_FILE", filepath.Join(t.TempDir(), "absent")) +} + +func writeCredentialsFile(t *testing.T, host string, port int, token string, mode os.FileMode) string { + t.Helper() + path := filepath.Join(t.TempDir(), "credentials") + body := fmt.Sprintf("[%s:%d]\npassword=%s\n", host, port, token) + if err := os.WriteFile(path, []byte(body), mode); err != nil { + t.Fatalf("write credentials file: %v", err) + } + t.Setenv("BEADS_CREDENTIALS_FILE", path) + return path +} + +func mustParseURL(t *testing.T, raw string) *url.URL { + t.Helper() + u, err := url.Parse(raw) + if err != nil { + t.Fatalf("parse %q: %v", raw, err) + } + return u +} + +// authorizeWith runs one Authorize and returns the header it set. +func authorizeWith(t *testing.T, p *BearerProvider) string { + t.Helper() + req, err := http.NewRequest(http.MethodGet, "http://127.0.0.1:8080/v0/beads/context", nil) + if err != nil { + t.Fatalf("new request: %v", err) + } + if err := p.Authorize(context.Background(), req); err != nil { + t.Fatalf("Authorize: %v", err) + } + return req.Header.Get("Authorization") +} + +// TestNoCredentialConfiguredIsNotAnError pins the loopback-trust posture: the +// tip OSS server has no authentication at all, so an empty ladder must produce a +// plain request rather than a refusal. +func TestNoCredentialConfiguredIsNotAnError(t *testing.T) { + clearCredentialEnvironment(t) + p := NewBearerProvider(mustParseURL(t, "http://127.0.0.1:8080")) + if got := authorizeWith(t, p); got != "" { + t.Errorf("Authorization = %q, want no header", got) + } +} + +func TestCredentialLadderPrecedence(t *testing.T) { + base := mustParseURL(t, "http://127.0.0.1:8080") + + t.Run("env is the top rung", func(t *testing.T) { + clearCredentialEnvironment(t) + writeCredentialsFile(t, "127.0.0.1", 8080, "from-file", 0o600) + t.Setenv(TokenEnv, "from-env") + if got := authorizeWith(t, NewBearerProvider(base)); got != "Bearer from-env" { + t.Errorf("Authorization = %q, want the env rung", got) + } + }) + + t.Run("the credentials file is the bottom rung", func(t *testing.T) { + clearCredentialEnvironment(t) + writeCredentialsFile(t, "127.0.0.1", 8080, "from-file", 0o600) + if got := authorizeWith(t, NewBearerProvider(base)); got != "Bearer from-file" { + t.Errorf("Authorization = %q, want the credentials-file rung", got) + } + }) + + t.Run("a section for another endpoint is not consulted", func(t *testing.T) { + clearCredentialEnvironment(t) + writeCredentialsFile(t, "10.0.0.9", 8080, "someone-elses", 0o600) + if got := authorizeWith(t, NewBearerProvider(base)); got != "" { + t.Errorf("Authorization = %q, want no header: the file has no entry for this server", got) + } + }) + + t.Run("an https URL without a port keys on 443", func(t *testing.T) { + clearCredentialEnvironment(t) + writeCredentialsFile(t, "beads.example.com", 443, "tls-token", 0o600) + p := NewBearerProvider(mustParseURL(t, "https://beads.example.com/")) + if got := authorizeWith(t, p); got != "Bearer tls-token" { + t.Errorf("Authorization = %q, want the default-port section", got) + } + }) +} + +// TestCredentialLadderFailsClosed is the rule the postgres ladder wrote down: a +// rung the operator configured that then errors aborts the request. Silently +// dropping to a lower rung is how a misconfigured helper becomes an +// unauthenticated request nobody noticed. +func TestCredentialLadderFailsClosed(t *testing.T) { + clearCredentialEnvironment(t) + writeCredentialsFile(t, "127.0.0.1", 8080, "lower-rung", 0o600) + t.Setenv(TokenCommandEnv, "exit 7") + + p := NewBearerProvider(mustParseURL(t, "http://127.0.0.1:8080")) + req, err := http.NewRequest(http.MethodGet, "http://127.0.0.1:8080/v0/beads/context", nil) + if err != nil { + t.Fatalf("new request: %v", err) + } + err = p.Authorize(context.Background(), req) + if err == nil { + t.Fatal("Authorize = nil; a failing token command must abort the request") + } + if !strings.Contains(err.Error(), TokenCommandEnv) { + t.Errorf("error %q does not name the rung that failed", err) + } + if req.Header.Get("Authorization") != "" { + t.Error("a failed ladder still set an Authorization header") + } +} + +// TestRefreshRereadsTheCredentialSource is the client half of the server's +// rotation contract. The server re-reads its token file on a ~1s gate, so a +// rolled client 401s once and succeeds on the retry — but only if Refresh +// actually re-reads rather than replaying what it cached. +func TestRefreshRereadsTheCredentialSource(t *testing.T) { + clearCredentialEnvironment(t) + path := writeCredentialsFile(t, "127.0.0.1", 8080, "old-token", 0o600) + p := NewBearerProvider(mustParseURL(t, "http://127.0.0.1:8080")) + + if got := authorizeWith(t, p); got != "Bearer old-token" { + t.Fatalf("Authorization = %q, want the pre-rotation token", got) + } + + t.Run("an unchanged credential is not retried", func(t *testing.T) { + retry, err := p.Refresh(context.Background()) + if err != nil { + t.Fatalf("Refresh: %v", err) + } + if retry { + t.Error("Refresh asked for a retry with the same token the server just refused") + } + }) + + t.Run("a rotated credential is retried with the new value", func(t *testing.T) { + if err := os.WriteFile(path, []byte("[127.0.0.1:8080]\npassword=new-token\n"), 0o600); err != nil { + t.Fatalf("rotate credentials file: %v", err) + } + retry, err := p.Refresh(context.Background()) + if err != nil { + t.Fatalf("Refresh: %v", err) + } + if !retry { + t.Fatal("Refresh did not ask for a retry after the credential rolled") + } + if got := authorizeWith(t, p); got != "Bearer new-token" { + t.Errorf("Authorization = %q, want the rotated token", got) + } + }) + + t.Run("a credential that went away is not retried", func(t *testing.T) { + if err := os.WriteFile(path, []byte("[127.0.0.1:8080]\n"), 0o600); err != nil { + t.Fatalf("empty the credentials file: %v", err) + } + retry, err := p.Refresh(context.Background()) + if err != nil { + t.Fatalf("Refresh: %v", err) + } + if retry { + t.Error("Refresh asked to retry unauthenticated against a server that answered 401") + } + }) +} + +// TestPlainHTTPBearerWarnsOnceAndLeaksNothing: bd serve has no TLS of its own, +// so a bearer bound past loopback crosses the network in the clear. The warning +// is once per provider — a paged read would otherwise print it per request — and +// it names the server, never the token. +func TestPlainHTTPBearerWarnsOnceAndLeaksNothing(t *testing.T) { + clearCredentialEnvironment(t) + t.Setenv(TokenEnv, "s3cr3t-token") + + var sink strings.Builder + p := NewBearerProvider(mustParseURL(t, "http://beads.example.com:8080")) + p.warnTo = &sink + + for range 3 { + if got := authorizeWith(t, p); got != "Bearer s3cr3t-token" { + t.Fatalf("Authorization = %q", got) + } + } + + warning := sink.String() + if strings.Count(warning, "Warning:") != 1 { + t.Errorf("warning fired %d times, want once:\n%s", strings.Count(warning, "Warning:"), warning) + } + if !strings.Contains(warning, "beads.example.com:8080") { + t.Errorf("warning does not name the server:\n%s", warning) + } + if strings.Contains(warning, "s3cr3t-token") { + t.Fatal("the insecure-transport warning printed the token") + } +} + +func TestLoopbackBearerDoesNotWarn(t *testing.T) { + clearCredentialEnvironment(t) + t.Setenv(TokenEnv, "local-token") + + var sink strings.Builder + p := NewBearerProvider(mustParseURL(t, "http://127.0.0.1:8080")) + p.warnTo = &sink + authorizeWith(t, p) + + if sink.String() != "" { + t.Errorf("loopback warned about plain http:\n%s", sink.String()) + } +} + +// TestCredentialsFilePostureIsChecked proves the file rung goes through the +// shared credentials reader rather than reading the file itself: the 0600 +// posture warning is that reader's, and a rung that bypassed it would silently +// accept a world-readable token file. +func TestCredentialsFilePostureIsChecked(t *testing.T) { + if os.Getuid() == 0 { + t.Skip("permission bits do not gate root") + } + clearCredentialEnvironment(t) + writeCredentialsFile(t, "127.0.0.1", 8080, "loose-token", 0o644) + + stderr := captureStderr(t, func() { + if got := authorizeWith(t, NewBearerProvider(mustParseURL(t, "http://127.0.0.1:8080"))); got != "Bearer loose-token" { + t.Errorf("Authorization = %q", got) + } + }) + if !strings.Contains(stderr, "overly permissive") { + t.Errorf("no posture warning for a 0644 credentials file:\n%s", stderr) + } + if strings.Contains(stderr, "loose-token") { + t.Fatal("the posture warning printed the token") + } +} + +func captureStderr(t *testing.T, fn func()) string { + t.Helper() + r, w, err := os.Pipe() + if err != nil { + t.Fatalf("os.Pipe: %v", err) + } + orig := os.Stderr + os.Stderr = w + done := make(chan string, 1) + go func() { + body, _ := io.ReadAll(r) + done <- string(body) + }() + + fn() + + os.Stderr = orig + _ = w.Close() + out := <-done + _ = r.Close() + return out +} + +// contextServer answers the handshake and records what it was asked with. +type contextServer struct { + body apigen.ContextResponse + require string // when set, a request without this bearer gets a 401 + // onUnauthorized runs just after a 401 is written. It is how the rotation + // test lands the rewrite in the one place it happens in production: between + // the refused attempt and the client's re-read. + onUnauthorized func() + seen []string +} + +func (s *contextServer) start(t *testing.T) *httptest.Server { + t.Helper() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + s.seen = append(s.seen, r.Header.Get("Authorization")) + if s.require != "" && r.Header.Get("Authorization") != "Bearer "+s.require { + w.Header().Set("WWW-Authenticate", "Bearer") + w.Header().Set("Content-Type", "application/problem+json") + w.WriteHeader(http.StatusUnauthorized) + _, _ = io.WriteString(w, `{"type":"about:blank","title":"unauthorized","status":401,"code":"invalid_argument"}`) + if s.onUnauthorized != nil { + s.onUnauthorized() + } + return + } + w.Header().Set("Content-Type", "application/json") + _ = json.NewEncoder(w).Encode(s.body) + })) + t.Cleanup(srv.Close) + return srv +} + +func v0Context(projectID string) apigen.ContextResponse { + return apigen.ContextResponse{ + ApiVersion: "v0", + BdVersion: "1.1.0", + Backend: "dolt", + Database: "beads", + RepoRoot: ptr("/srv/repo"), + ProjectId: projectID, + Capabilities: []string{"issues.list", "ready.list"}, + } +} diff --git a/internal/httpclient/encode/BUILD.bazel b/internal/httpclient/encode/BUILD.bazel new file mode 100644 index 000000000..e9faf9c17 --- /dev/null +++ b/internal/httpclient/encode/BUILD.bazel @@ -0,0 +1,48 @@ +load("@rules_go//go:def.bzl", "go_library", "go_test") + +go_library( + name = "encode", + srcs = [ + "encode.go", + "ledger.go", + "ledger_fields.go", + "ledger_render.go", + "parentwalk.go", + "skew.go", + "table.go", + ], + importpath = "github.com/steveyegge/beads/internal/httpclient/encode", + visibility = ["//:__subpackages__"], + deps = [ + "//internal/types", + "//internal/workapi", + "//issueops", + ], +) + +go_test( + name = "encode_test", + srcs = [ + "bijection_test.go", + "ledger_render_test.go", + "oracle_test.go", + "parentwalk_test.go", + "roundtrip_test.go", + "skew_test.go", + ], + data = [ + "//:engdocs/design/http-divergence-ledger.md", + "//cmd/bd:go_srcs", + "//internal/httpapi/spec:openapi.v0.yaml", + ] + glob(["*.go"]), + embed = [":encode"], + deps = [ + "//internal/httpapi", + "//internal/httpapi/spec", + "//internal/types", + "//internal/workapi", + "//issueops", + "//memoryops", + "@in_gopkg_yaml_v3//:yaml_v3", + ], +) diff --git a/internal/httpclient/encode/bijection_test.go b/internal/httpclient/encode/bijection_test.go new file mode 100644 index 000000000..ee6389fd9 --- /dev/null +++ b/internal/httpclient/encode/bijection_test.go @@ -0,0 +1,764 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/bijection_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "errors" + "fmt" + "go/ast" + "go/parser" + "go/token" + "os" + "path/filepath" + "reflect" + "slices" + "sort" + "strings" + "testing" + "time" + + "gopkg.in/yaml.v3" + + "github.com/steveyegge/beads/internal/httpapi/spec" + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/issueops" +) + +// GATE 1: the reflection bijection. +// +// This is the ONLY defense against a silently dropped flag. A round-trip +// fixture cannot be one: a filter nobody thought to fixture round-trips +// perfectly by being absent from both sides, and the server can only reject +// parameters it RECEIVES — so the field an encoder never learned about is +// invisible from every direction except this one. +// +// It runs four ways, and each catches a different way the classification can go +// stale: +// +// upstream -> here every populatable field of every request shape is in the +// encoder table. A field added to issueops.ListRequest +// tomorrow fails here rather than shipping as a widened +// result set. +// here -> upstream every table entry and every field-shaped ledger row names +// a field that still exists. A renamed field fails rather +// than leaving a rule that matches nothing. +// document -> here every query parameter the operation publishes is driven +// by a field or explicitly reserved. A parameter added to +// the wire fails rather than staying unreachable. +// table -> encoder populating one field at a time makes the encoder behave +// the way the table says it does. +// +// COMPLETENESS IS THE TEST'S OWN INVARIANT. An empty table set, an empty table, +// an empty ledger and a ledger row nothing classifies are all failures here — +// otherwise the cheapest way to make this gate green would be to delete its +// input. + +func TestEncoderTableClassifiesEveryRequestField(t *testing.T) { + tables := Tables() + if len(tables) == 0 { + t.Fatal("the encoder table is empty; there is nothing for this gate to check") + } + + seenPrimary := map[Op]bool{} + for _, table := range tables { + t.Run(tableName(table), func(t *testing.T) { + if len(table.Fields) == 0 { + t.Fatal("table has no field entries") + } + if table.Source == nil || table.Source.Kind() != reflect.Struct { + t.Fatalf("Source %v is not a struct type", table.Source) + } + if table.Target == nil || table.Target.Kind() != reflect.Struct { + t.Fatalf("Target %v is not a struct type", table.Target) + } + + classified := map[string]bool{} + for _, entry := range table.Fields { + if classified[entry.Name] { + t.Errorf("field %s is classified twice", entry.Name) + } + classified[entry.Name] = true + checkEntry(t, table, entry) + } + + for _, name := range populatableFields(table.Source) { + if !classified[name] { + t.Errorf("%s.%s is populatable and UNCLASSIFIED.\n"+ + "Add it to the %s table with a disposition, or refuse it with a divergence-ledger row.\n"+ + "An unclassified field is a filter this client would drop silently — see engdocs/design/http-client-backend.md D7 and D9 L12.", + table.Source.Name(), name, tableName(table)) + } + } + for name := range classified { + if _, ok := table.Source.FieldByName(name); !ok { + t.Errorf("table entry %s.%s names a field that does not exist", table.Source.Name(), name) + } + } + }) + + if table.Primary { + if seenPrimary[table.Op] { + t.Errorf("operation %s has more than one primary table", table.Op) + } + seenPrimary[table.Op] = true + } + } + + for _, op := range []Op{OpListReadyWork, OpCountReadyWork, OpListIssues, OpQueryIssues, OpCountIssues, OpGetIssue} { + if !seenPrimary[op] { + t.Errorf("operation %s has no primary table, so nothing checks it against the document", op) + } + } +} + +func checkEntry(t *testing.T, table Table, entry FieldEntry) { + t.Helper() + where := fmt.Sprintf("%s.%s", table.Source.Name(), entry.Name) + + switch entry.Disposition { + case DispParam, DispPath: + if entry.Param == "" { + t.Errorf("%s: %s entry names no parameter", where, entry.Disposition) + } + if entry.Decoded == "" { + t.Errorf("%s: %s entry names no decoded field", where, entry.Disposition) + return + } + if _, ok := table.Target.FieldByName(entry.Decoded); !ok { + t.Errorf("%s: decoded field %s.%s does not exist", where, table.Target.Name(), entry.Decoded) + } + case DispServerFixed: + if entry.Fixed == "" { + t.Errorf("%s: server-fixed entry names no value", where) + } + if entry.Why == "" { + t.Errorf("%s: server-fixed entry carries no reason", where) + } + case DispClientSide: + if entry.Why == "" { + t.Errorf("%s: client-side entry carries no reason, so nothing says which machinery honors it", where) + } + case DispNested: + if entry.Why == "" { + t.Errorf("%s: nested entry carries no reason, so nothing says why the shape is delegated", where) + return + } + if entry.Decoded == "" { + t.Errorf("%s: nested entry names no decoded field", where) + return + } + if _, ok := table.Target.FieldByName(entry.Decoded); !ok { + t.Errorf("%s: decoded field %s.%s does not exist", where, table.Target.Name(), entry.Decoded) + } + // The delegation has to LAND somewhere. A nested entry naming a shape no + // table classifies would read as coverage while classifying nothing — + // the same leftover the ledger's own completeness arms exist to catch. + field, ok := table.Source.FieldByName(entry.Name) + if !ok { + return // the missing-field arm above already reported it. + } + delegated := false + for _, other := range Tables() { + if other.Source == field.Type { + delegated = true + break + } + } + if !delegated { + t.Errorf("%s: nested entry delegates to %s, which no encoder table classifies", where, field.Type) + } + case DispDropped, DispRefused, DispInverted: + if entry.Ledger == "" { + t.Fatalf("%s: %s entry cites no divergence-ledger row", where, entry.Disposition) + } + if entry.Disposition == DispInverted && entry.Why == "" { + t.Errorf("%s: inverted entry carries no reason, so nothing says which derivation re-produces it", where) + } + row := findRow(t, entry.Ledger) + if row.Type != nil && (row.Type != table.Source || row.Field != entry.Name) { + t.Errorf("%s: cites ledger row %s, which is about %s.%s", where, row.ID, row.Type.Name(), row.Field) + } + wantKind := KindRefuse + if entry.Disposition == DispDropped { + wantKind = KindDegrade + } + if row.Kind != wantKind { + t.Errorf("%s: %s entry cites ledger row %s of kind %q, want %q", where, entry.Disposition, row.ID, row.Kind, wantKind) + } + default: + t.Errorf("%s: unknown disposition %q", where, entry.Disposition) + } +} + +func TestLedgerRowsAreWellFormed(t *testing.T) { + rows := Ledger() + if len(rows) == 0 { + t.Fatal("divergence ledger v1 is empty") + } + + tests := testFunctionsInThisPackage(t) + ids := map[string]bool{} + for _, row := range rows { + if row.ID == "" { + t.Fatalf("a ledger row carries no id: %+v", row) + } + if ids[row.ID] { + t.Errorf("duplicate ledger row id %q", row.ID) + } + ids[row.ID] = true + + switch row.Kind { + case KindRefuse, KindDegrade, KindRetired: + default: + t.Errorf("%s: unknown kind %q", row.ID, row.Kind) + } + for name, value := range map[string]string{"What": row.What, "Why": row.Why, "SpecRow": row.SpecRow, "PinnedBy": row.PinnedBy} { + if strings.TrimSpace(value) == "" { + // PinnedBy especially: D9's whole discipline is that a ledger + // row without a pin is a wish. A TODO naming the owning bead is + // an acceptable pin; an empty string is not. + t.Errorf("%s: %s is empty", row.ID, name) + } + } + // A pin is a TEST or a bead, never a hopeful sentence. A row naming a + // test that does not exist is exactly the shape of a ledger that has + // drifted from the suite it claims to be held to. + if !strings.HasPrefix(row.PinnedBy, "TODO(") && !tests[row.PinnedBy] { + t.Errorf("%s: PinnedBy %q is neither a test in this package nor a TODO()", row.ID, row.PinnedBy) + } + if (row.Type == nil) != (row.Field == "") { + t.Errorf("%s: Type and Field must be set together (Type=%v Field=%q)", row.ID, row.Type, row.Field) + } + if row.Type != nil { + if _, ok := row.Type.FieldByName(row.Field); !ok { + t.Errorf("%s: names %s.%s, which does not exist — the field was renamed or removed and this row now matches nothing", + row.ID, row.Type.Name(), row.Field) + } + } + } +} + +// TestNoLedgerRowIsUnknownToTheEncoderTable is the other half of the ledger +// bijection: a row about a field of a shape this package encodes must be a +// field that shape's table actually classifies. +// +// Without it the ledger could accumulate rows for fields nobody encodes, and a +// reader auditing "is this refusal real?" would have no way to tell a live rule +// from a leftover. Rows about the WRITE shapes (D8's refuse-not-drop +// enumeration) are deliberately exempt: this package encodes no request bodies, +// and their reflection check above is what keeps them honest. +func TestNoLedgerRowIsUnknownToTheEncoderTable(t *testing.T) { + encoded := map[reflect.Type]map[string]bool{} + for _, table := range Tables() { + if encoded[table.Source] == nil { + encoded[table.Source] = map[string]bool{} + } + for _, entry := range table.Fields { + encoded[table.Source][entry.Name] = true + } + } + + for _, row := range Ledger() { + if row.Type == nil { + continue + } + fields, ok := encoded[row.Type] + if !ok { + continue // a write-shape row; see the doc comment. + } + if !fields[row.Field] { + t.Errorf("ledger row %s is about %s.%s, which no encoder table classifies", + row.ID, row.Type.Name(), row.Field) + } + } +} + +// TestEveryFieldShapedLedgerRowIsCitedByTheTable is the ledger's other +// completeness direction, and the one this package's doc comment claimed before +// anything checked it: "a row nothing references fails the gate too". +// +// The check above proves a row's FIELD is still classified. This proves the ROW +// is still reached — that some table entry names it — which is what separates a +// live rule from a leftover. Without it the ledger accumulates rows for +// dispositions that changed underneath them, and a reader auditing "is this +// refusal real?" has no way to tell. +// +// Rows about the WRITE shapes stay exempt for the reason the check above exempts +// them: this package encodes no request bodies, so no table of its could cite +// one. Their completeness against the wire's own member lists is a guard the +// lifecycle wiring owns (D8 refuse-not-drop). +func TestEveryFieldShapedLedgerRowIsCitedByTheTable(t *testing.T) { + // Rows a table cannot cite because the rule is about a VALUE rather than a + // field's presence, so the encoder raises them from code. + raisedFromCode := map[string]string{ + "E-IssueFilter.IDs@bound": "the bound is on the LENGTH of the id set, which a per-field disposition cannot express; PlanSearch raises it", + } + + cited := map[string]bool{} + sources := map[reflect.Type]bool{} + for _, table := range Tables() { + sources[table.Source] = true + for _, entry := range table.Fields { + if entry.Ledger != "" { + cited[entry.Ledger] = true + } + } + } + + for _, row := range Ledger() { + if row.Type == nil || row.Kind == KindRetired || !sources[row.Type] { + continue + } + if cited[row.ID] || raisedFromCode[row.ID] != "" { + continue + } + t.Errorf("ledger row %s (%s.%s) is cited by no encoder-table entry.\n"+ + "Either a disposition stopped referring to it — in which case the row is a leftover — or it is raised from code and belongs in raisedFromCode with the reason.", + row.ID, row.Type.Name(), row.Field) + } +} + +// TestEveryEncoderTableParameterIsPublished reads the document as the authority +// it is declared to be: internal/httpapi/spec/openapi.v0.yaml and routes.go are +// the SOLE surface authority, so a parameter this client sends that the +// operation does not publish is a 400 waiting to happen, and a parameter the +// operation publishes that no field drives is a filter this client cannot +// express and has not admitted to. +func TestEveryEncoderTableParameterIsPublished(t *testing.T) { + published := loadPublishedParameters(t) + + for _, table := range Tables() { + t.Run(tableName(table), func(t *testing.T) { + want, ok := published[table.Op] + if !ok { + t.Fatalf("the document publishes no operation %q", table.Op) + } + + sent := map[string]bool{} + for _, entry := range table.Fields { + if entry.Disposition != DispParam { + continue + } + if !want[entry.Param] { + t.Errorf("%s sends %q, which %s does not publish: %v", + entry.Name, entry.Param, table.Op, sortedKeys(want)) + } + sent[entry.Param] = true + } + for _, reserved := range table.Reserved { + if !want[reserved.Name] { + t.Errorf("reserved parameter %q is not published by %s", reserved.Name, table.Op) + } + if strings.TrimSpace(reserved.Why) == "" { + t.Errorf("reserved parameter %q carries no reason", reserved.Name) + } + sent[reserved.Name] = true + } + + if !table.Primary { + // A bridge maps a legacy filter onto a subset of an operation + // it does not own, so it owes the containment check above and + // not the coverage one below. + return + } + for name := range want { + if !sent[name] { + t.Errorf("%s publishes %q and no field of %s drives it.\n"+ + "Map it, or list it in the table's Reserved set with the reason no request field can.", + table.Op, name, table.Source.Name()) + } + } + }) + } +} + +// TestEncoderHonorsEveryTableDisposition drives the encoders one field at a +// time and asserts each behaves the way the table declares. +// +// One field at a time, against a baseline, because that is the only way to +// attribute a difference: a request with two fields set tells you nothing about +// which one produced which parameter. +func TestEncoderHonorsEveryTableDisposition(t *testing.T) { + for _, table := range Tables() { + base := baselineFor(t, table) + baseline, err := Encode(table.Op, table.Shape, base.Interface()) + if err != nil { + t.Fatalf("%s: the baseline source does not encode: %v", tableName(table), err) + } + + for _, entry := range table.Fields { + t.Run(tableName(table)+"/"+entry.Name, func(t *testing.T) { + source := reflect.New(table.Source).Elem() + source.Set(base) + populate(t, source.FieldByName(entry.Name)) + + got, err := Encode(table.Op, table.Shape, source.Interface()) + + switch entry.Disposition { + // A derived default is driven exactly as a refusal: the sweep's + // sentinel value is by construction not one any intent derives, + // so the inversion must reject it and cite the same row. + case DispRefused, DispInverted: + var refusal *RefusedError + if !errors.As(err, &refusal) { + t.Fatalf("a populated %s encoded without a refusal (err=%v, params=%v).\n"+ + "A dropped filter widens the result set invisibly — see D7 and ledger row %s.", + entry.Name, err, got.Params, entry.Ledger) + } + if !errors.Is(err, ErrRefused) { + t.Errorf("the refusal does not match ErrRefused") + } + if refusal.Row.ID != entry.Ledger { + t.Errorf("refusal cites ledger row %q, table says %q", refusal.Row.ID, entry.Ledger) + } + case DispParam: + if err != nil { + t.Fatalf("a populated %s failed to encode: %v", entry.Name, err) + } + if _, ok := got.Params[entry.Param]; !ok { + t.Errorf("a populated %s produced no %q parameter (params=%v)", entry.Name, entry.Param, got.Params) + } + case DispPath: + if err != nil { + t.Fatalf("a populated %s failed to encode: %v", entry.Name, err) + } + if len(got.PathIDs) == 0 || got.PathIDs[0] == "" { + t.Errorf("a populated %s produced no path id (%v)", entry.Name, got.PathIDs) + } + case DispServerFixed, DispClientSide, DispDropped: + if err != nil { + t.Fatalf("a populated %s failed to encode: %v", entry.Name, err) + } + if got.Params.Encode() != baseline.Params.Encode() { + t.Errorf("a populated %s changed the query string (%q, baseline %q); a %s field must send nothing", + entry.Name, got.Params.Encode(), baseline.Params.Encode(), entry.Disposition) + } + case DispNested: + // The opposite assertion to the three above: a delegated + // shape must REACH the wire. A builder that forgot it would + // answer a perfectly well-formed number about the whole + // workspace, and nothing downstream could tell. + if err != nil { + t.Fatalf("a populated %s failed to encode: %v", entry.Name, err) + } + if got.Params.Encode() == baseline.Params.Encode() { + t.Errorf("a populated %s sent nothing (query %q is the baseline); the delegated shape never reached the wire", + entry.Name, got.Params.Encode()) + } + } + }) + } + } +} + +// TestTheExactIDsFanOutIsBounded pins the one refusal the disposition sweep +// cannot reach by populating a single field: the bound is on the LENGTH of a +// set the sweep populates with one element. +func TestTheExactIDsFanOutIsBounded(t *testing.T) { + ids := make([]string, MaxExactIDs) + for i := range ids { + ids[i] = fmt.Sprintf("bd-%04d", i) + } + + plan, err := PlanSearch(types.IssueFilter{IDs: ids}, ZeroVocabulary) + if err != nil { + t.Fatalf("%d ids refused: %v", MaxExactIDs, err) + } + if plan.Shape != SearchExactIDs || len(plan.IDs) != MaxExactIDs { + t.Fatalf("plan = %+v, want the exact-ids shape carrying %d ids", plan, MaxExactIDs) + } + + var refusal *RefusedError + if _, err := PlanSearch(types.IssueFilter{IDs: append(ids, "bd-over")}, ZeroVocabulary); !errors.As(err, &refusal) { + t.Fatalf("%d ids encoded without a refusal: %v", MaxExactIDs+1, err) + } else if refusal.Row.ID != "E-IssueFilter.IDs@bound" { + t.Errorf("refusal cites %q, want E-IssueFilter.IDs@bound", refusal.Row.ID) + } +} + +// TestASearchFilterMatchingNeitherShapeRefuses covers the two shape decisions +// the per-field sweep cannot express: the empty filter, which means EVERYTHING +// and is the most dangerous drop on this surface, and the id-plus-parent pair, +// which is neither shape. +func TestASearchFilterMatchingNeitherShapeRefuses(t *testing.T) { + parent := "bd-parent" + for _, tc := range []struct { + name string + filter types.IssueFilter + row string + }{ + {"the empty filter", types.IssueFilter{}, "E-IssueFilter.noShape"}, + {"ids and a parent together", types.IssueFilter{IDs: []string{"bd-1"}, ParentID: &parent}, "E-IssueFilter.shapeConflict"}, + } { + t.Run(tc.name, func(t *testing.T) { + var refusal *RefusedError + plan, err := PlanSearch(tc.filter, ZeroVocabulary) + if !errors.As(err, &refusal) { + t.Fatalf("encoded as %+v without a refusal (err=%v)", plan, err) + } + if refusal.Row.ID != tc.row { + t.Errorf("refusal cites %q, want %q", refusal.Row.ID, tc.row) + } + }) + } +} + +// TestAReadyRequestNamingNoPolicySendsHybrid is the one normalization the +// encoder performs, and it is here because getting it wrong is silent: an +// omitted `sort` is `priority` to the server and hybrid to the storage layer, +// and the two answer with different item SETS once a limit truncates. +func TestAReadyRequestNamingNoPolicySendsHybrid(t *testing.T) { + for _, req := range []issueops.ReadyRequest{{}, {Sort: ""}} { + got, err := ReadyParams(req) + if err != nil { + t.Fatalf("ReadyParams: %v", err) + } + if got.Get("sort") != "hybrid" { + t.Errorf("sort = %q, want hybrid", got.Get("sort")) + } + } + // The derived-default status is what the encoder drops; an empty status now + // refuses, so the minimal ready filter this normalization runs on carries it. + got, err := ReadyBridgeParams(types.WorkFilter{Status: types.StatusOpen}) + if err != nil { + t.Fatalf("ReadyBridgeParams: %v", err) + } + if got.Get("sort") != "hybrid" { + t.Errorf("bridge sort = %q, want hybrid", got.Get("sort")) + } +} + +// populatableFields lists the fields of a request shape a caller can set, +// walking embedded structs the way a caller reaches promoted fields. +// +// Unexported fields are excluded because no caller outside their package can +// set one, which is what "populatable" means here. +func populatableFields(rt reflect.Type) []string { + var out []string + for i := range rt.NumField() { + f := rt.Field(i) + if !f.IsExported() { + continue + } + if f.Anonymous { + et := f.Type + for et.Kind() == reflect.Pointer { + et = et.Elem() + } + if et.Kind() == reflect.Struct { + out = append(out, populatableFields(et)...) + continue + } + } + out = append(out, f.Name) + } + return out +} + +// populate sets a field to a value a caller could plausibly have set, so the +// encoder sees it as present. +func populate(t *testing.T, v reflect.Value) { + t.Helper() + if !v.CanSet() { + t.Fatalf("cannot set a %s", v.Type()) + } + switch { + case v.Type() == reflect.TypeOf(time.Time{}): + v.Set(reflect.ValueOf(time.Date(2026, 3, 4, 5, 6, 7, 0, time.UTC))) + return + case v.Kind() == reflect.Pointer: + v.Set(reflect.New(v.Type().Elem())) + populate(t, v.Elem()) + return + case v.Kind() == reflect.Struct: + // A nested request shape (DispNested), populated WHOLE rather than one + // member deep: the assertion the sweep makes about it is that the + // delegated encoding reached the wire, and a shape whose one populated + // member happened to be a client-side one would satisfy that vacuously. + for i := range v.NumField() { + if v.Type().Field(i).IsExported() { + populate(t, v.Field(i)) + } + } + return + } + switch v.Kind() { + case reflect.String: + v.SetString("gate-sentinel") + case reflect.Bool: + v.SetBool(true) + case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64: + v.SetInt(1) + case reflect.Slice: + elem := reflect.New(v.Type().Elem()).Elem() + populate(t, elem) + v.Set(reflect.Append(reflect.MakeSlice(v.Type(), 0, 1), elem)) + case reflect.Map: + key, value := reflect.New(v.Type().Key()).Elem(), reflect.New(v.Type().Elem()).Elem() + populate(t, key) + populate(t, value) + v.Set(reflect.MakeMap(v.Type())) + v.SetMapIndex(key, value) + default: + t.Fatalf("no sentinel for a %s (%s)", v.Kind(), v.Type()) + } +} + +// baselineFor is the smallest source value each table can encode. The two +// SearchIssues shapes need their selector set before anything else about them +// can be observed, because the shape decides which fields are readable at all. +func baselineFor(t *testing.T, table Table) reflect.Value { + t.Helper() + base := reflect.New(table.Source).Elem() + switch table.Shape { + case "searchExactIDs": + base.FieldByName("IDs").Set(reflect.ValueOf([]string{"bd-baseline"})) + case "searchParentWalk": + parent := "bd-baseline" + base.FieldByName("ParentID").Set(reflect.ValueOf(&parent)) + case "workFilterBridge": + // The ready bridge's Status is a DERIVED DEFAULT, not a refusal: the + // encoder recognizes StatusOpen — the value workapi.BuildReadyFilter + // stamps on every ready filter — as the server's own default and drops + // it, and refuses every other status including the empty one (the storage + // layer's open+in_progress default, which the ready wire cannot state). + // So the smallest source this table can encode carries StatusOpen, + // exactly as the walk's smallest carries its parent selector. + base.FieldByName("Status").Set(reflect.ValueOf(types.StatusOpen)) + } + return base +} + +func tableName(table Table) string { + if table.Shape == "" { + return string(table.Op) + } + return string(table.Op) + "/" + table.Shape +} + +func findRow(t *testing.T, id string) Row { + t.Helper() + for _, row := range Ledger() { + if row.ID == id { + return row + } + } + t.Fatalf("no divergence-ledger row %q", id) + return Row{} +} + +// testFunctionsInThisPackage collects the test names a ledger row may cite as +// its pin. +// +// Parsed out of the sources rather than kept as a list, for the reason +// everything else here is derived rather than restated: a second copy is a +// second thing that can be wrong. +// +// It reads THIS package, the store package above it, and cmd/bd, because the +// ledger is one artifact and its pins are not. The read-shape rows are pinned by +// the encoder sweep in this directory; the write-shape rows D8's refuse-not-drop +// enumeration owns are pinned where the refusal is raised, which is the store's +// role bodies; and the F- rows — whole commands and the flag modes of served +// commands — can only be pinned where a cobra tree exists. Scanning only this +// directory would have forced those rows to carry a TODO forever and made a real +// pin indistinguishable from a missing one. +// +// cmd/bd's files are enterprise-tagged and this test is not. That is fine and +// deliberate: parsing is text, and the same reasoning the skew sweep records +// applies — the build-constrained files are precisely the ones that carry these +// pins. +func testFunctionsInThisPackage(t *testing.T) map[string]bool { + t.Helper() + names := map[string]bool{} + for _, dir := range []string{".", "..", filepath.Join("..", "..", "..", "cmd", "bd")} { + collectTestFunctions(t, dir, names) + } + if len(names) == 0 { + t.Fatal("found no test functions to check ledger pins against") + } + return names +} + +func collectTestFunctions(t *testing.T, dir string, into map[string]bool) { + t.Helper() + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatalf("read %s: %v", dir, err) + } + fset := token.NewFileSet() + for _, entry := range entries { + if entry.IsDir() || !strings.HasSuffix(entry.Name(), "_test.go") { + continue + } + path := filepath.Join(dir, entry.Name()) + file, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution) + if err != nil { + t.Fatalf("parse %s: %v", path, err) + } + for _, decl := range file.Decls { + fn, ok := decl.(*ast.FuncDecl) + if ok && fn.Recv == nil && strings.HasPrefix(fn.Name.Name, "Test") { + into[fn.Name.Name] = true + } + } + } +} + +func sortedKeys(m map[string]bool) []string { + out := make([]string, 0, len(m)) + for k := range m { + out = append(out, k) + } + sort.Strings(out) + return out +} + +// loadPublishedParameters reads the query parameters of every operation out of +// the wire contract itself. +// +// The document rather than a hand-kept list, because a hand-kept list is the +// second copy this whole gate exists to avoid; and the document rather than the +// handlers, because the document is what the source-of-truth ordering names as +// the surface authority. +// +// Read through spec.OpenAPIV0() (a go:embed'd []byte) rather than a relative +// os.ReadFile path: the embed already carries this exact file as a build +// input of internal/httpapi/spec, so this gate's own package dependency is +// what makes the document reachable under `bazel test`'s sandbox -- no +// `data` attribute naming the YAML's filesystem path is needed here at all. +func loadPublishedParameters(t *testing.T) map[Op]map[string]bool { + t.Helper() + raw := spec.OpenAPIV0() + var doc struct { + Paths map[string]map[string]struct { + OperationID string `yaml:"operationId"` + Parameters []struct { + Name string `yaml:"name"` + In string `yaml:"in"` + } `yaml:"parameters"` + } `yaml:"paths"` + } + if err := yaml.Unmarshal(raw, &doc); err != nil { + t.Fatalf("parse the wire contract: %v", err) + } + + out := map[Op]map[string]bool{} + for _, methods := range doc.Paths { + for method, operation := range methods { + if operation.OperationID == "" || !slices.Contains([]string{"get", "post", "patch", "delete", "put"}, method) { + continue + } + names := map[string]bool{} + for _, p := range operation.Parameters { + if p.In == "query" { + names[p.Name] = true + } + } + out[Op(operation.OperationID)] = names + } + } + if len(out) == 0 { + t.Fatal("the wire contract parsed to no operations") + } + return out +} diff --git a/internal/httpclient/encode/encode.go b/internal/httpclient/encode/encode.go new file mode 100644 index 000000000..c99a75bd9 --- /dev/null +++ b/internal/httpclient/encode/encode.go @@ -0,0 +1,786 @@ +// 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. +// +// See engdocs/design/http-client-backend.md — D7 (the refusal taxonomy), D8 +// (the role dispositions and the refuse-not-drop enumeration), D9 (the +// divergence ledger), D11 (id resolution) and D12 (MaxRows). +package encode + +import ( + "errors" + "fmt" + "net/url" + "reflect" + "sort" + "strconv" + "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.list("label", req.Labels) + b.list("label_any", req.LabelsAny) + b.list("exclude_label", req.ExcludeLabels) + + b.str("parent", req.ParentID) + + 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() +} + +// 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) +} + +// 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= 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. +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 +} diff --git a/internal/httpclient/encode/ledger.go b/internal/httpclient/encode/ledger.go new file mode 100644 index 000000000..23644ae43 --- /dev/null +++ b/internal/httpclient/encode/ledger.go @@ -0,0 +1,1040 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/ledger.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "fmt" + "reflect" + "sync" + + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/issueops" +) + +// The divergence ledger, v1. +// +// engdocs/design/http-client-backend.md D9 states the discipline this file +// instantiates: "Every knowingly-degraded behavior is a ledger row with a +// pinned test... A degradation not in this table is a bug." The prose table +// lives in the design; this is the machine-readable copy the client actually +// consults, and it carries three populations rather than one: +// +// - The D9 rows themselves (L1-L18, with L17 deleted rather than skipped — +// see the L-sequence note in designRows), which describe whole behaviors rather +// than single fields. They are here so that the numbering the design and +// the review log cite resolves to something a test can read. +// - The refuse-not-drop enumeration D8 closes with: every role-request field +// the wire has no member for. These name a Go field on a request type and +// are what makes "refused, never dropped" checkable rather than asserted. +// - One row per request-shape field this package's encoder cannot put on the +// wire. Those are the rows the encoder itself reaches for: a refusal is +// raised BY ledger id, so a refusal with no row is a compile-time absence +// rather than a prose gap, and the bijection gate reads the same rows back. +// +// WHY A REFUSAL CARRIES A ROW RATHER THAN A STRING. D7's third taxonomy text +// has to name the flag that produced a parameter, and D9 requires every +// degradation to cite a pinned test. Both facts belong to the divergence, not +// to the call site that discovered it, so the call site raises the id and the +// row supplies the vocabulary. It also makes the failure mode of a forgotten +// entry loud: RowByID panics on an unknown id, and the bijection gate fails on +// a row nothing references. +// +// WHAT IS NOT HERE. Rows for the surfaces this package does not encode — the +// unsupported-allowlist refusals of D8, the whole-command refusals of D7 that +// have no request field — appear only where the design names them as +// refuse-not-drop residue or as a D9 row. The store skeleton owns the rest. + +// Kind classifies what a ledger row promises. +type Kind string + +const ( + // KindRefuse is a divergence that FAILS rather than proceeding: a + // populated field, or an invoked flag, that the v0 wire cannot express. + // Refusing is the whole point — a dropped filter widens a result set + // invisibly, which is the one failure class no server-side gate can + // observe (D7). + KindRefuse Kind = "refuse" + // KindDegrade is a divergence that PROCEEDS with knowingly different + // behavior. Every one of these is a judgment that the difference cannot be + // misread as a narrower or wider answer than the caller asked for. + KindDegrade Kind = "degrade" + // KindRetired is a row the design has retired. It stays so the L-numbers + // the design, the council log and the beads cite keep resolving, and so a + // re-enumeration can tell "retired" from "never existed". + KindRetired Kind = "retired" +) + +// Row is one divergence: what diverges, why, which decision it comes from, and +// what pins it. +type Row struct { + // ID is the stable citation. D9's own rows keep their L-numbers; the rest + // are prefixed by population — E for an encoder field, W for the + // write-side refuse-not-drop enumeration, F for a command or flag. + ID string + // Kind is what this row promises. + Kind Kind + + // Type and Field name the Go request field that diverges, for the rows + // that have one. Type is nil on a row that describes a behavior or a flag + // rather than a field. Holding the reflect.Type rather than its name is + // what makes a renamed or deleted field a test failure instead of a stale + // string. + Type reflect.Type + Field string + + // Flag is the user's spelling, where one exists — D7's refusal texts speak + // flags and commands, never store method names. Empty when the divergence + // has no single flag behind it. + Flag string + // Command is the cmd/bd command path this row is about, spelled the way the + // classification tables spell it ("count", "ready", "mol ready"). Empty on a + // row that is not about a command. + // + // It exists because the command was only ever in the PROSE, and prose is + // what let F-count claim `bd count` refuses for a whole wave after the + // command was served. cmd/bd's TestFRowsAgreeWithTheCommandClassification + // binds this field to httpRefusedCommands/httpServedCommands, so the claim + // is checked rather than read. + Command string + // Capability is the wire token behind a LATE refusal: the command is SERVED + // and refuses only against a server that does not advertise this token. + // + // It is what distinguishes F-close — a refuse row whose command is served — + // from a whole-command refusal, and it binds harder than a boolean would: + // the gate requires the served command's own capability list to name it. + Capability string + + // What describes the divergence for a reader. Required on every row; on a + // field row it says what the field asked for that the wire cannot carry. + What string + // Why is the reason the wire cannot carry it, or the reason the + // degradation is the right answer. + Why string + // SpecRow cites the decision in engdocs/design/http-client-backend.md. + SpecRow string + // PinnedBy names the test that holds this row honest, or carries a + // TODO() when the pinning test is another bead's deliverable. It is + // never empty: D9's whole discipline is that a ledger row without a pin is + // a wish. + PinnedBy string +} + +// pinnedByS3Conformance is the TODO sentinel for ledger rows whose claim is +// provable only from behind two seams this package (S2) does not build: +// +// - a server wired to a real/reference backing store — multi-page reads +// under concurrent writes, racing claims, dual-running against a second +// implementation, actor/provenance rules an httptest fixture's canned +// in-memory role does not enforce — and +// - cmd/bd wired to this client — the subprocess parity corpus, the +// pre-run classified-refused-command table, flag-mode refusals driven +// through the real cobra tree. +// +// Both are S3's: the store/dial seam and the cmd/bd integration that gives +// this client a binary to run those suites against. Until that wiring lands +// there is no test in ANY package that exercises the claim, so each row that +// cited an enterprise test of this shape is re-pinned here rather than left +// pointing at a name with nothing behind it — the well-formedness gate +// accepts TODO() for exactly this reason (see PinnedBy's doc comment). +// +// This package's OWN behavior — the encode/decode tables, the capability +// gate, the wire-revision floor — stays pinned to real tests in this package +// (TestEncoderTableClassifiesEveryRequestField, +// TestEncoderHonorsEveryTableDisposition, +// TestEncodedParametersRoundTripThroughTheServerDecoder, and friends); this +// sentinel covers only the rows whose evidence is a layer S2 never touches. +const pinnedByS3Conformance = "TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline" + +// Ledger returns divergence ledger v1, in citation order. +// +// It builds a fresh copy per call rather than handing out a package-level +// slice, so no caller can edit the ledger another caller reads. The encoder's +// own lookups go through cachedLedger below and never through this. +func Ledger() []Row { + var rows []Row + rows = append(rows, designRows()...) + rows = append(rows, writeSideRows()...) + rows = append(rows, commandRows()...) + rows = append(rows, readyRequestRows()...) + rows = append(rows, listRequestRows()...) + rows = append(rows, queryRequestRows()...) + rows = append(rows, issueFilterRows()...) + rows = append(rows, parentWalkRows()...) + rows = append(rows, workFilterRows()...) + return rows +} + +// RowByID returns the row a refusal cites. +// +// It PANICS on an unknown id, which is the correct severity: the ids are +// package constants used from this package's own encoder, so an unknown one is +// a programming error that would otherwise surface as a refusal with no +// vocabulary — exactly the "raw store-method refusal reaching a %v call site" +// D7's choke point exists to make impossible. +func RowByID(id string) Row { + for _, row := range cachedLedger() { + if row.ID == id { + return row + } + } + panic(fmt.Sprintf("encode: no divergence-ledger row %q", id)) +} + +// cachedLedger is what a REFUSAL reads, so raising one does not rebuild the +// whole ledger. Ledger() keeps building a fresh copy for everyone else. +var cachedLedger = sync.OnceValue(Ledger) + +var ( + tyReadyRequest = reflect.TypeOf(issueops.ReadyRequest{}) + tyListRequest = reflect.TypeOf(issueops.ListRequest{}) + tyQueryRequest = reflect.TypeOf(issueops.QueryRequest{}) + tyCountRequest = reflect.TypeOf(issueops.CountRequest{}) + tyCountByGroupRequest = reflect.TypeOf(issueops.CountByGroupRequest{}) + tyGetRequest = reflect.TypeOf(issueops.GetRequest{}) + tyIssueFilter = reflect.TypeOf(types.IssueFilter{}) + tyWorkFilter = reflect.TypeOf(types.WorkFilter{}) + + tyUpdateRequest = reflect.TypeOf(issueops.UpdateRequest{}) + tyCloseRequest = reflect.TypeOf(issueops.CloseRequest{}) + tyReopenRequest = reflect.TypeOf(issueops.ReopenRequest{}) + tyDeleteRequest = reflect.TypeOf(issueops.DeleteRequest{}) + tyAddDeps = reflect.TypeOf(issueops.AddDependenciesRequest{}) + tyIssuePatch = reflect.TypeOf(issueops.IssuePatch{}) + + tyCreateRequest = reflect.TypeOf(issueops.CreateRequest{}) + tyCreateBatch = reflect.TypeOf(issueops.CreateBatchRequest{}) + tyBatchCreateItem = reflect.TypeOf(issueops.BatchCreateItem{}) + tyCreateDep = reflect.TypeOf(issueops.CreateDependency{}) + + tyApplyCreateItem = reflect.TypeOf(issueops.CreateItem{}) +) + +// designRows are D9's own table, transcribed. They describe behaviors rather +// than fields, so they carry no Type — but they are the rows the L-numbers in +// every other citation resolve to, and dropping them here would leave those +// citations pointing at prose only. +func designRows() []Row { + // pinnedElsewhere is for the three PRE-RUN degradations of D4 — molecule + // auto-load (L5), auto-import (L6), the ready view's parent-epic map (L13) — + // whose observable behavior is a cmd/bd invocation's, not a store call's. + // They are the subprocess parity tier's, and that tier is the one this wiring + // did not build. ga-b8ddd.12 (per-request project-id enforcement) closed the + // read-display ESCALATION — every read now carries the stamp, so a drifted + // server refuses it rather than rendering another project's rows — but the + // remaining fixture corpus that would PIN these pre-run displays is its + // follow-up, ga-b8ddd.23, which owns them. + // + // L17 (the conditional dep-remove guard) used to be the one remaining TODO row + // that was NOT subprocess-owned. It carried no row of its own once its + // condition resolved: the dual run ga-b8ddd.30 wrote + // (TestServedDependencyRecordsSurfaceUnresolvedRowsVerbatim) showed the wire + // surfaces unresolved depends_on_id rows VERBATIM, so the guard does not + // degrade and there was nothing to ledger. It is DELETED rather than retired, + // because a retirement records a divergence that once existed and this one + // never did. L1 is the retirement beside it — a row that WAS live and is kept + // as KindRetired for exactly that reason. + const pinnedElsewhere = "TODO(ga-b8ddd.23): a pre-run degradation, observable only through a cmd/bd invocation; the subprocess parity corpus pins it" + return []Row{ + { + // IT WAS DELETED OUTRIGHT for a while, against this file's own + // retirement policy: KindRetired exists so a re-enumeration can tell + // "retired" from "never existed", and the design keeps L1 in D9's + // table. A deleted row makes the two disagree and turns RowByID("L1") + // into a panic rather than an answer. + ID: "L1", Kind: KindRetired, + What: "RETIRED — `bd list` over http could not ask for the wisp plane", + Why: "retired by the upstream ask the design page filed for it: \"include_ephemeral on listIssues (retires L1)\". Upstream published the parameter, the server decodes it (internal/httpapi/reads.go handleListIssues), and the encoder emits it whenever ListRequest.IncludeEphemeral is set. " + + "THERE IS NO DIVERGENCE LEFT TO RECORD. `bd list` still shows no wisps, but it shows none LOCALLY either: the front door registers no --include-ephemeral (only `bd ready` does, ready.go), so the field is unset on both paths and both answer the durable plane. A degrade row describing behavior the local oracle shares is not a degradation, and keeping it as one would be the same falsified-premise problem the W- rows had — a ledger arguing from a document that moved", + SpecRow: "D9 L1 (RETIRED), D8 row 1", + // A retirement turns a refusal pin into a ROUND-TRIP pin: the + // parameter is populated here and read back by the server's own + // decoder, which is the fact the retirement rests on. + PinnedBy: "TestEncodedParametersRoundTripThroughTheServerDecoder", + }, + { + ID: "L2", Kind: KindDegrade, + What: "a non-created `bd list` sort, the flagless default included, costs page-to-exhaustion on the three legs that cannot push the order down: an unlimited read (--limit 0), a caller-supplied keyset position, and a server that does not advertise issues.list.sort", + Why: "NARROWED, not retired, by the upstream ask this row named: listIssues publishes `sort` and `reverse`, and the pager's pushdown leg (list_walk.go sortedPage) answers a bounded, position-free request against an advertising server in ONE request, with the server's own LIMIT deciding which rows survive the caller's order. " + + "What is left is the legs where that is unavailable or unsafe. An unlimited read has to cross every row whatever the order, and `limit=0` pushed down would newly meet the server's unlimited-read refusal. A keyset position is defined in the created order, and the pager's prefix discard run against a page some other order truncated would drop rows whose replacements were never fetched — a wrong answer rather than a slow one. A down-level server is the fallback the capability probe exists to reach. On all three the client still fetches every page and applies the SQL order's own Go-side mirror plus a copy of the page epilogue's comparator. " + + "The weld itself is NOT a divergence and never was: a cursor is bound to the paged order it was minted in (`created` or `priority`) and the server refuses it under any other `sort`", + SpecRow: "D9 L2, D8 row 1", + // The dual run is the load-bearing half: it answers the SAME + // request from the reference store and from the client and compares + // the orders, so the divergence this row admits (the cost) is + // pinned separately from the one it forbids (a different answer). + // It now runs every arm TWICE, once down each leg, which is what + // makes the narrowing checkable: the pushdown and the walk have to + // agree with the reference AND with each other, truncated pages + // included, where the truncation is the only thing a re-sort cannot + // repair. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L3", Kind: KindDegrade, + What: "a multi-page fetch has no snapshot isolation", + Why: "the keyset cursor pins a position, not a snapshot: rows created mid-walk are missed and row states mix instants, where local mode is one query", + SpecRow: "D9 L3", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L4", Kind: KindRetired, + What: "`bd show` dependents sections and comment bodies were degraded", + Why: "retired by council #1: the write-lifecycle wave landed include_dependents/include_comments on getIssue, and both the off-role text path and the on-role JSON path are wired", + SpecRow: "D9 L4 (RETIRED), D4, D8 row 1", + // The dual run answers a Get from both sides and compares the + // MARSHALED bytes, over a row seeded with an edge and a comment + // precisely so the dependents and comments the retired degradation + // was about are non-empty on at least one side. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L5", Kind: KindDegrade, + What: "molecules are not auto-loaded pre-run", + Why: "the loader writes, the write refuses, and the call site swallows the refusal to debug.Logf", + SpecRow: "D9 L5, D4", + PinnedBy: pinnedElsewhere, + }, + { + ID: "L6", Kind: KindDegrade, + What: "a pre-run auto-import ATTEMPT reaches an http workspace and fails as a best-effort stderr warning; nothing is imported", + Why: "THE MECHANISM THIS ROW USED TO NAME DOES NOT EXIST. It said the path was \"force-disabled through an import.auto=false env override\", and there is no such override anywhere: shouldRunAutoImportJSONL (cmd/bd/main.go) reads the config key, whose default is true (internal/config/config.go), and no http path sets it false. " + + "WHAT ACTUALLY HAPPENS is that maybeAutoImportJSONL runs — on any non-read-only, non-global, non-server-mode command — and is stopped by its own guards rather than by a switch: a missing or empty issues.jsonl, the attempt stamp, or the emptiness guard, which is a GetStatistics the server serves. Where all three pass (an empty server beside a non-empty local JSONL) the import is attempted and fails, because the client is not a jsonlImporter and the fallback importer's first write — SetConfig, or CreateIssuesWithFullOptions — is on the unsupported allowlist. The function is documented best-effort, so the failure is an stderr warning and the command proceeds. " + + "The DEGRADATION is therefore that nothing imports, which is the outcome the design wanted for the right reason — importing a local JSONL into a shared server is not a pre-run side effect — reached by refusal rather than by configuration. It stays a degrade because the command proceeds and the answer is not narrower or wider than the caller asked for. The retirement path is a real skip on the http backend, so the warning stops being the mechanism", + SpecRow: "D9 L6, D4", + PinnedBy: pinnedElsewhere, + }, + { + ID: "L7", Kind: KindDegrade, + What: "the client-side status/type vocabulary is defaults plus the status.custom/types.custom/types.infra config keys; table-backed customs are invisible client-side", + Why: "the custom_statuses/custom_types tables have no wire operation; server-side role validation still uses the true vocabulary", + SpecRow: "D9 L7, D4", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L8", Kind: KindRefuse, Flag: "--deps", + What: "`bd list --deps` refuses, and the pretty/--format dependency-decoration arms render undecorated", + Why: "GetAllDependencyRecords has no wire mapping in v1; listDependencies is an anchored read. --tree is NOT in this row: it defaults true and is `bd list`'s default text rendering", + SpecRow: "D9 L8, D4", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L9", Kind: KindDegrade, + What: "credential-bearing settings are unreadable client-side", + Why: "the server redacts by omission and says so on the wire in Setting.redacted; the client answers absent-WITH-A-REASON rather than the empty string a caller would read as unset", + SpecRow: "D9 L9", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L10", Kind: KindRefuse, Flag: "--watch", + What: "`bd list --watch` and `bd show --watch` refuse", + Why: "the loops poll every 2s, each `bd list` tick is a full cursor walk (L2), per-tick errors spam or vanish, and the decoration is refused anyway (L8); N watchers against one server is a request storm its semaphore answers with 503s the loop does not back off from", + SpecRow: "D9 L10, D10", + // Two halves, one pin each: the TEXT is byte-pinned in the store + // (TestTheWatchRefusalReadsExactlyAsTheSpecWroteIt), and the + // flag-level early refusal that renders it is exercised against the + // real cobra tree here. The wrapper reads the text off + // (*Store).RefuseWatch rather than keeping a second copy. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L11", Kind: KindDegrade, + What: "hooks fire client-side after the server's commit with no shared transaction, on connected workspaces only", + Why: "the seam sits below HookFiringStore in the client process; a --server-url ephemeral invocation has no hook directory and runs none", + SpecRow: "D9 L11, D1", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L12", Kind: KindRefuse, + What: "an inexpressible filter refuses, never drops — the class rule every E- row below is an instance of", + Why: "a dropped filter widens a result set invisibly, and the server can only reject parameters it receives", + SpecRow: "D9 L12, D7", + PinnedBy: "TestEncoderHonorsEveryTableDisposition", + }, + { + ID: "L13", Kind: KindDegrade, + What: "pretty `bd ready` shows no parent-epic context", + Why: "buildParentEpicMap swallows the GetDependencyRecordsForIssues refusal into a nil map; the retirement path is an anchored listDependencies plus per-parent getIssue", + SpecRow: "D9 L13, D4", + PinnedBy: pinnedElsewhere, + }, + { + ID: "L14", Kind: KindDegrade, + What: "against a server that does NOT advertise issues.claimNext, the composed ReadyClaimer leaves three residues: the ready-at-fetch/claim-at-dial window, a false empty under contention after the bounded refetch, and a claimed row whose CARDINALITIES are as of the listing rather than of the claiming transaction", + Why: "claimIssue validates claimability, not readiness, so a listing plus a claim is not the local role's one transaction and cannot be made into one. " + + "THE ROW IS NARROWER THAN IT WAS. Upstream published POST /v0/beads/issues:claimNext (#5510) and client wave ga-jpywb dials it, so on any server that advertises the token NONE of these three residues exists: selection, the compare-and-set and the hydration share the server's own transaction, an empty front is a 200 with `claimed` absent rather than a lost-races error, and the counts describe the state the claim produced. The whole ReadyClaimer contract tier runs against that leg with nothing parked, which is the measurement that says the residues were the COMPOSITION's rather than the wire's. " + + "WHAT KEEPS THE ROW ALIVE is the DOWN-LEVEL leg, which survives on purpose: `bd ready --claim` worked against pre-#5510 servers before this port, and refusing it now would be a regression dressed as progress. It is the posture BatchCloser takes toward issues.batchClose, and it is why this row describes shipped behavior rather than history. " + + "The third residue is stated in its IMPLEMENTED form, which is not the one the design anticipated: the design expected a follow-up getIssue to hydrate the counts, and therefore a read that could fail AFTER the claim was durable. The composition takes the counts from the ready page it already fetched instead, so that failure mode does not exist — a claim changes no dependency, dependent or comment count, and what is left is staleness bounded by the same fetch-to-dial window residue (a) already owns. " + + "Retirement is no longer an upstream ask but a fleet fact: the row goes when no server this client may meet is older than #5510", + SpecRow: "D9 L14, D8 row 4", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L15", Kind: KindDegrade, + What: "a --max-rows cap can fire over http on a query whose Limit is at or under the cap, on the `bd list` legs that still walk", + Why: "locally the effective SQL LIMIT is min(Limit, MaxRows+1), so a window at or under the cap can never exceed it; over http a walk to exhaustion fetches far more than the window and the cap deliberately bounds WIRE ROWS FETCHED — safety wins over exit-code parity on exactly the unbounded walk the cap exists to bound. " + + "NARROWED by the same pushdown that narrowed L2: the pushdown leg asks for min(limit, MaxRows+1) rows in one request, which IS the local expression, so a cap at or above the limit can no longer fire there and a request that used to exit 2 now answers. That is a convergence toward the contract, and it is observable — the same command changes from a refusal to a page. " + + "THE NARROWING IS SCOPED TO THE ORDERS SQL CAN EXPRESS, and that scope is a correctness bound rather than an optimization left on the table. For a GO-SIDE sort — sqlbuild.IsGoSideSort, today `--sort id`, which needs the natural-numeric comparison (bd-9 before bd-10) no ORDER BY renders — workapi.SQLLimit pushes 0 down instead of the limit, so LOCALLY the window is MaxRows+1 whatever the limit is and the cap fires on the overage even under a limit at or below it. min(limit, MaxRows+1) is therefore NOT the local expression there, and a request bounded by the limit cannot see the overage at all. walkIssues' gate keeps a capped Go-side sort on the walk, where fetching MaxRows+1 wire rows reproduces that unbounded local window exactly and raises the same refusal — so on this one shape the walk leg is the CONVERGENT one and pushing down would have been the divergence. " + + "What keeps the row live is the walk legs (unlimited reads, keyset positions, down-level servers), where the old accounting is unchanged and correct, and `bd ready`, which has no pushdown at all", + SpecRow: "D9 L15, D12", + // Re-pointed from the ready bridge's cap test to the list one, + // because the narrowing is a `bd list` fact and the ready cap is + // the part that did not move. The list test carries the repair + // (a roomy cap under pushdown answers), the residue (a cap under + // the limit still fires there) and the control (the same roomy cap + // still fires down the walk leg) in one place. + // TestTheReadyBridgeEnforcesMaxRowsClientSide still pins the ready + // half and is unchanged. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L16", Kind: KindRefuse, Flag: "--file", + What: "`bd dep add --file` carrying more than 100 edges refuses, naming the wire bound; it is never chunked", + Why: "maxAddDependencyEdges = 100 (internal/httpapi/dependency_edit.go); chunking is the one path that silently breaks the request's one-transaction/one-history-entry contract, where naive forwarding at least fails loudly", + SpecRow: "D9 L16, D7, D8 row 18", + // The boundary itself, both sides: exactly maxAddDependencyEdges + // serves, one more refuses, and the refusal never dials — chunking + // is what this row forbids, so "did not reach the server" is the + // assertion that matters. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-close-cap", Kind: KindRefuse, + What: "a batch close naming more than 100 items refuses, naming the wire bound; it is never chunked", + Why: "maxBatchCloseItems = 100 (internal/httpapi/batch_close.go); the item cap bounds how long one request may hold a write transaction. Chunking is the one path that silently breaks the request's one-transaction/one-history-entry contract — the same reason L16 refuses a bulk dependency add rather than splitting it — so a larger list refuses and the caller splits it, each request atomic on its own", + SpecRow: "D9 L-close-cap, D7 F-close, D8 row 17", + // L16's sibling: exactly maxBatchCloseItems serves, one more refuses, + // and the refusal never dials — chunking is what the row forbids. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-dep-endpoint", Kind: KindDegrade, + What: "a dependency add whose source or target names no issue refuses as ErrValidation over http, not as *DependencyEndpointNotFoundError wrapping ErrDependencySourceNotFound or ErrDependencyTargetNotFound", + Why: "the wire spells that refusal as a 400 invalid_argument with reason `invalid_value` and the offending member in `param` (internal/httpapi/dependency_edit.go). Reason and code are the same ones a malformed id earns, so the two are indistinguishable without reading `detail` prose — which is exactly what the extension-member vocabulary exists to avoid. " + + "The refusal still FAILS the request and still writes nothing; only its classification is coarser. Upstream ask: a distinguishing code or reason for the endpoint-not-found refusal, which retires this row", + SpecRow: "D8 row 18", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-claim-prose", Kind: KindDegrade, + What: "a claim refusal's MESSAGE does not carry the ClaimedBy/NotClaimableStatus fragments, so beads.ParseClaimConflict recovers nothing from it over http", + Why: "the fragments exist so that parser can recover the conflicting assignee and status from PROSE. Over the wire both arrive as typed extension members and *ClaimConflictError is reconstructed whole, so a caller reading the FIELDS loses nothing. " + + "Recomposing the copy client-side would mean re-implementing which copy each refusal shape gets — an open issue held by someone else deliberately omits the assignee tail, an in-progress one carries it — which is a second implementation of the very rule the fragments were introduced to keep single", + SpecRow: "D8 row 3", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-delete-notfound", Kind: KindDegrade, + What: "issueops.Deleter.Delete over http refuses an absent id as issueops.ErrNotFound, not as *NotFoundError naming WHICH ids did not resolve", + Why: "the role's error is a typo report and names every missing id; the wire deliberately does not repeat them (internal/httpapi's NotFound() carries a FIXED detail, so a 404 body cannot echo caller input back). " + + "The refusal still FAILS the request and still deletes NOTHING — not even the ids beside the typo — so the all-or-nothing promise is intact and only the classification is coarser. " + + "It is stated at the ROLE rather than at a command because `bd delete` is not reachable against an http workspace at all (see httpUnconsumedCapabilities); the embedder holding the role is the audience. Upstream ask: an ids extension member on the not_found problem, which retires this row", + SpecRow: "D8 row 13", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-delete-dependents", Kind: KindDegrade, + What: "the unforced dependents guard refuses as issueops.ErrValidation, not as *DependentsOutsideRequestError wrapping ErrDependentsOutsideRequest", + Why: "the wire spells that refusal as a 400 invalid_argument with no `param` (internal/httpapi's failDeleteErr) — the fix is to change the REQUEST, by sending cascade or force — so the blocked id and its dependents cannot be reconstructed without parsing detail prose, which is what the extension-member vocabulary exists to avoid. " + + "The guard itself is untouched: the request fails and the graph is whole. Upstream ask: a dependents_outside_request code carrying issue_id and dependents, which retires this row", + SpecRow: "D8 row 13", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-delete-bound", Kind: KindRefuse, + What: "issueops.Deleter.Delete refuses a request naming more than 1000 ids, citing the wire bound; it is never split across requests", + Why: "maxDeleteIDs = 1000 (internal/httpapi/delete.go). Splitting is the one path that silently breaks the request's one-transaction, one-history-entry contract — and it would ask the dependents guard about half a request at a time, so a pair the caller deliberately listed together would be refused as an outside dependent. Naive forwarding at least fails loudly. Stated at the ROLE: `bd delete` cannot reach an http workspace, so the embedder is the audience", + SpecRow: "D8 row 13, D9 L16 (the same argument, on the other bulk write)", + // The boundary itself, both sides: exactly maxDeleteIDs serves, one + // more refuses, and the refusal never dials. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-batchcreate-bound", Kind: KindRefuse, + What: "`bd create --file` carrying more than 100 issues refuses, naming the wire bound; it is never split across requests", + Why: "maxBatchCreateItems = 100 (internal/httpapi/batch_create.go). The request IS the transaction, so two requests are two transactions and two history entries where the role promises one — and a failure in the second leaves half a plan created, which is the outcome all-or-nothing exists to make impossible", + SpecRow: "D8 row 14, D9 L16", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-edgecount-bound", Kind: KindRefuse, + What: "issueops.GraphCounter.CountEdges refuses a request naming more than 100 DISTINCT anchors, citing the wire bound; it is never chunked across requests", + Why: "maxDependencyAnchors = 100 (internal/httpapi/edges.go), the same bound the stored-edge read on this collection carries — the role deliberately sets none of its own and says the bound belongs to the WIRE. " + + "Chunking is what a READ could get away with and this one cannot: CountEdges promises that an anchor's EXISTENCE and its edge count are read from one consistent view, so two requests would let an anchor be reported missing by a probe that raced a create the other chunk's count already saw — one answer contradicting itself, which is the exact failure AnchorEdgeCount.Missing exists to make impossible. " + + "Refusing at the bound fails loudly instead, and the caller splits the question knowing it asked twice. Upstream ask: a cursor or a higher bound on the anchor list, which retires this row", + SpecRow: "D9 L16 (the same argument, on a read), D8", + // The boundary itself, both sides: exactly 100 anchors serve, 101 + // refuse, and the refusal never dials. + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-batchcreate-target", Kind: KindDegrade, + What: "a batch create whose edge target names no issue refuses as issueops.ErrValidation alone, not as ErrValidation WRAPPING ErrNotFound", + Why: "the wire answers a dangling edge target with a 400 invalid_argument naming `items` (internal/httpapi's failBatchCreate), and deliberately does not quote the role's own message, which arrives as a driver error naming tables and constraints. The refusal still fails the whole batch and creates nothing — the promise the row is about — and only the second sentinel is lost. Upstream ask: a distinguishing code for the absent-target refusal", + SpecRow: "D8 row 14", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-batchcreate-inbatch", Kind: KindRefuse, + What: "an edge onto an EARLIER ITEM OF THE SAME BATCH cannot be expressed at all over http", + Why: "the capability needs the earlier item to have named an id for itself, and apigen.BatchCreateItem publishes no id member — an explicit id is refused with the rest of W-BatchCreateItem.Issue. So the target of an in-batch edge can only be a row the workspace already holds. " + + "It is a REFUSE row rather than a degrade because the request that asks for it fails: the client refuses the explicit id before the dial, and there is no second spelling that would land the edge silently. The wire's own `target_id` description names this case, so the gap is in the SCHEMA rather than in the handler — the upstream ask is an item id member, which retires this row", + SpecRow: "D8 row 14", + PinnedBy: pinnedByS3Conformance, + }, + // L17 (the conditional GH#5005 dep-remove guard) is DELETED, not present as a + // row: ga-b8ddd.30's dual run proved the wire surfaces unresolved + // depends_on_id rows verbatim (see pinnedElsewhere above), so the + // degradation it was contingent on never materialized. The L-sequence skips + // from L16 to L18 for that reason. + { + // IT WAS MISSING HERE while the design carried it and F-close cited + // it TWICE, so RowByID("L18") panicked on a citation the ledger's own + // prose made. The design's record is the one transcribed below. + ID: "L18", Kind: KindDegrade, + What: "DOWN-LEVEL ONLY: against a server that does not advertise issues.batchClose, a single-id `bd close` still composes onto closeIssue and records the SERVER's own close commit message rather than the batch's id-naming entry; the multi-id and --claim-next shapes refuse there", + Why: "the composed leg is one closeIssue call, so the history entry it leaves is the one that operation writes for itself — the batch's entry names the ids it closed and this one cannot, because no batch ran. " + + "Where issues.batchClose IS advertised the whole request is one call and one server-side transaction, so this divergence does not arise at all; the down-level leg survives on purpose, because `bd close` worked against pre-batchClose servers before this port and refusing it now would be a regression dressed as progress. It is the same posture L14 takes toward issues.claimNext. " + + "It is a degrade rather than a refuse because the close LANDS and the answer is neither narrower nor wider than the caller asked for — only the record of it is the operation's rather than the batch's. Retirement is a fleet fact rather than an upstream ask: the row goes when no server this client may meet is older than issues.batchClose", + SpecRow: "D9 L18, D8 row 17", + // The down-level leg, driven against a store whose stub carries no + // capabilities: the single-item shape composes and every other shape + // refuses without dialing. + PinnedBy: pinnedByS3Conformance, + }, + } +} + +// writeSideRows are the refuse-not-drop enumeration D8 closes with: role-request +// fields on the SERVED writes that the wire publishes no member for. +// +// This package encodes none of these shapes — they are request bodies, not +// query strings — but the rows live here because the ledger is one artifact, +// and because a renamed or deleted field is caught by the same reflection the +// read shapes get. +func writeSideRows() []Row { + const updateSpec = "D8 refuse-not-drop, D7" + // The lifecycle wiring landed, and with it the sweep that drives every + // excluded member one at a time and asserts each fails WITHOUT dialing. The + // completeness of this population — that no member reaches the wire + // unclassified in the first place — is the store package's write-ledger + // gate, which reflects these rows against the apigen bodies. + const pinned = pinnedByS3Conformance + return []Row{ + { + ID: "W-UpdateRequest.Claim", Kind: KindRefuse, + Type: tyUpdateRequest, Field: "Claim", + What: "a claim combined with any other UpdateRequest member refuses; a claim ALONE does not — it dials claimIssue directly (see httpLifecycle.claimOnlyUpdate)", + Why: "a claim is claimIssue's own operation and updateIssue cannot perform one, on this wire or on any other; it is the one row here that upstream #5484 did not touch. " + + "claimIssue's own request is the actor alone, so a claim-only UpdateRequest IS that request and is served through the Claimer role instead of refusing — that is gc's exclusive claim path, `bd update --claim --json`. " + + "What still refuses is PATCH claim: a claim folded into one atomic transaction WITH a patch, a guard or a force override, which no operation on this wire publishes and which is not synthesized as two calls (claimIssue then updateIssue), since that would let a caller observe an issue claimed but not yet patched. Upstream gastownhall/beads#6890 tracks the capability that would carry both in one call", + SpecRow: updateSpec, + PinnedBy: pinned, + }, + { + // What/Why below are plain and short DELIBERATELY: RefusedError.Error() + // prints both verbatim to whatever reads the returned error, all the + // way out to a CLI user running `bd update --claim` over an + // http workspace — so this is user-facing prose, not an internal + // engineering note, and it should read that way. + // + // The engineering rationale, for a future reader of this file: the v0 + // wire's claimIssue operation (issueops.Claimer's own contract) + // answers a wisp id with ErrNotFound on every backend, including the + // direct route's own claim-by-id — the wisp plane is not claimable + // through that role at all. But claimOnlyUpdate's caller is + // `bd update --claim`, whose Lifecycle.Update DOES claim wisps + // locally (issue-or-wisp routing). Over http, that command is served + // through claimIssue rather than through updateIssue's general + // wisp-aware routing, so a wisp id would otherwise surface the wire's + // generic not-found — a live row reported as though it does not + // exist, indistinguishable from an id naming nothing at all, which a + // not-found-sensitive caller (gc's Claim among them) would read as + // missing rather than as an unclaimable wisp. This refuses by name + // instead, once the client itself recognizes the id names a wisp — + // which it learns only AFTER claimIssue itself answers not_found (see + // claimOnlyUpdate), so an ordinary claim of a real, non-wisp issue + // never pays this probe. Serving a wisp-aware claim (a server-side + // ClaimWisp capability) is tracked as a pending decision, not + // implemented here. + ID: "W-ClaimRequest.Wisp", Kind: KindRefuse, + What: "claiming a wisp is not supported over http", + Why: "the v0 wire's claim operation excludes the wisp plane on every backend; claim this issue from a local workspace instead", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-UpdateRequest.ForceAssigneeTransfer", Kind: KindRefuse, Flag: "--force", + Type: tyUpdateRequest, Field: "ForceAssigneeTransfer", + What: "bypassing the anti-steal assignee fence refuses", + Why: "the wire publishes `force_assignee_transfer` (upstream #5484) and this client does not send it. What the refusal STANDS ON changed with client wave ga-7i6by and the row is narrower for it: the `assignee` the fence guards IS now sent (W-IssuePatch.Assignee), so what is left is the bypass alone. " + + "The fence itself is unbypassable rather than absent — a transfer away from a live foreign in-progress owner refuses with already_claimed, and a matched `expected_assignee` is the OTHER bypass, which this client does send. Carrying this one is a two-member port tracked as ga-2ltro.15", + SpecRow: updateSpec, + PinnedBy: pinned, + }, + { + ID: "W-UpdateRequest.ForceClosePolicy", Kind: KindRefuse, Flag: "--force", + Type: tyUpdateRequest, Field: "ForceClosePolicy", + What: "bypassing close policy on a status-crossing update refuses", + Why: "the wire publishes `force_close_policy` (upstream #5484) and this client does not send it; see W-UpdateRequest.ForceAssigneeTransfer for what the refusal now stands on, since client wave ga-7i6by sends the `status` whose crossing the policy gates. " + + "The policy is therefore enforced and not bypassable here: a status crossing into the done category with open children or a live blocker refuses with not_closable, typed, and writes nothing. Tracked as ga-2ltro.15", + SpecRow: updateSpec, + PinnedBy: pinned, + }, + { + ID: "W-UpdateRequest.ExpectedVersion", Kind: KindRetired, + What: "the compare-and-set row-version precondition used to refuse", + Why: "RETIRED by the client wave that sends it (ga-jbuyf). The refusal was always the CLIENT's rather than the document's — upstream #5484 published `expected_version` and this client had not been taught to emit it — and the row said so in as many words: 'flipping it is a port, not a decision: send the member, retire this row, and turn the refusal pin into a round-trip pin'. " + + "That is what happened. The member is now sent as a POINTER, so absent stays absent: 0 is a legal token (the migration-0054 backfill left rows holding it) and encoding 'no guard' as 0 would have armed a guard on every unguarded update. The pin below asserts the round trip in both directions", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-UpdateRequest.ExpectedAssignee", Kind: KindRetired, + What: "the compare-and-set assignee precondition used to refuse", + Why: "RETIRED with W-UpdateRequest.ExpectedVersion (ga-jbuyf). Its own trap is the mirror image of that one's: the EMPTY assignee is a real guard — it is how a caller says 'only if nobody holds it' — so this member cannot be omitted when it is empty either. " + + "A pointer expresses both, and the pin drives the empty-string guard as its own case", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-UpdateRequest.ExpectedStatus", Kind: KindRetired, + What: "the compare-and-set status precondition used to refuse", + Why: "RETIRED with W-UpdateRequest.ExpectedVersion (ga-jbuyf). The status guard is the readable one — `Issue.status` is on every read of this surface, so a caller can guard a transition with no token at all — and it is sent as the workspace's own status vocabulary, verbatim", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-UpdateRequest.IssuePlaneOnly", Kind: KindRefuse, + Type: tyUpdateRequest, Field: "IssuePlaneOnly", + What: "restricting an update to the issue plane refuses", + Why: "updateIssue publishes no plane restriction and the server's role auto-resolves both planes, so dropping the flag would EDIT the wisp the caller asked to be told did not exist — the widening refuse-not-drop exists to stop. " + + "Not in the design's own enumeration: the page lists the UpdateRequest members it had reviewed, and this one was found while wiring the role", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-UpdateRequest.Provenance", Kind: KindRefuse, + Type: tyUpdateRequest, Field: "Provenance", + What: "labeling an update's history entry refuses", + Why: "updateIssue publishes no provenance member and the server writes its own label, so a dropped Provenance would leave the history entry naming the SERVER's surface while the caller believed it named theirs. " + + "It is refused rather than degraded because the field's whole purpose is the label, so dropping it drops the request", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-CloseRequest.ExpectedVersion", Kind: KindRetired, + What: "the compare-and-set row-version precondition on a close used to refuse", + Why: "RETIRED by the client wave that sends it (ga-jbuyf). CloseIssueRequest publishes expected_version (upstream #5506) and this client now emits it, so the guard reaches the server rather than refusing here — and the ordering the role promises, that the precondition is checked BEFORE the idempotent re-close, is the server's to keep and the served tier's to assert", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-ReopenRequest.ExpectedVersion", Kind: KindRetired, + What: "the compare-and-set row-version precondition on a reopen used to refuse", + Why: "RETIRED with W-CloseRequest.ExpectedVersion (ga-jbuyf). The design's enumeration named the close half only, and the reopen half is the same field on the same verb pair — it retires the same way", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-DeleteRequest.ExpectedVersion", Kind: KindRetired, + What: "the compare-and-delete row-version precondition used to refuse", + Why: "RETIRED with W-CloseRequest.ExpectedVersion (ga-jbuyf), and it is the one whose stakes made the refusal worth having: dropping this guard erases a row the caller had asked not to erase, with nothing left to compare afterwards. " + + "The multi-id refusal the wire attaches to it is deliberately NOT anticipated client-side: distinctness is measured after trimming and collapsing duplicates, which is the normalization this role sends its ids verbatim to avoid re-implementing", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-ReopenRequest.Provenance", Kind: KindRefuse, + Type: tyReopenRequest, Field: "Provenance", + What: "labeling a reopen's history entry refuses", + Why: "reopenIssue publishes no provenance member and the server writes its own fixed label (`bd serve: reopen issue`); see W-UpdateRequest.Provenance", + SpecRow: updateSpec, + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-AddDependenciesRequest.SkipPerEdgeCycleCheck", Kind: KindRefuse, Flag: "--no-cycle-check", + Type: tyAddDeps, Field: "SkipPerEdgeCycleCheck", + What: "`bd dep add --no-cycle-check` refuses on the bulk --file path", + Why: "the wire deliberately leaves SkipPerEdgeCycleCheck UNPUBLISHED and therefore false (internal/httpapi/dependency_edit.go). The single-edge spelling forwards false and only gates the post-hoc cycle warning, which the wire-backed CycleDetector serves, so it is served-with-note rather than refused", + SpecRow: "D7, D8 row 18, D9 L16", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-IssuePatch.Status", Kind: KindRetired, + What: "`bd update -s` used to refuse", + Why: "RETIRED with client wave ga-7i6by. IssuePatchBody published `status` with upstream #5484 and this client's encoder now emits it; close and reopen still carry the lifecycle semantics a status write has nowhere to put — the reason and session under first-close-wins, the done-status normalization, the already-closed idempotence flag — and stay the operations to reach for. " + + "What this member serves is the status moved ALONGSIDE other fields in one transaction, which is the thing two calls cannot do", + SpecRow: "D8 refuse-not-drop", + PinnedBy: patchMemberPin, + }, + { + ID: "W-IssuePatch.Assignee", Kind: KindRetired, + What: "assignment and unassignment through update used to refuse", + Why: "RETIRED with W-IssuePatch.Status (ga-7i6by). The EMPTY STRING is the half that makes this member more than a rename: it UNASSIGNS, so a client that skipped an empty value would turn a real edit into no edit at all. " + + "The anti-steal fence around it is the server's and is unchanged — a transfer away from a live foreign in-progress owner still refuses with already_claimed, and the two bypasses (`force_assignee_transfer` and a matched `expected_assignee`) are W-UpdateRequest.ForceAssigneeTransfer and the guard wave's own", + SpecRow: "D8 refuse-not-drop", + PinnedBy: patchMemberPin, + }, + { + ID: "W-IssuePatch.Metadata", Kind: KindRetired, + What: "a metadata patch used to refuse", + Why: "RETIRED with W-IssuePatch.Status (ga-7i6by). IssuePatchBody publishes the same replace/merge/set/unset algebra MetadataPatch carries, member for member, so the client projects it rather than translating it and the ordering rule — merge, then set in key order, then unset, with replace refusing beside the other three — stays the ROLE's, applied by the same body a local workspace runs. " + + "The CLEAR is the one state the wire's own struct cannot spell (`omitempty` omits it), which is why the document is built as a map and an empty replacement travels as the empty document. The compare-and-set door is a different question and is served by its own accessor (issues.casMetadata, ga-7i6by's other half)", + SpecRow: "D8 refuse-not-drop", + PinnedBy: patchMemberPin, + }, + // Four of these are refused by BOTH patch documents — updateIssue's and + // issues:batchApply's — so one row covers both operations rather than a + // second reason being minted for one fact. Owner is the exception and + // says so: ApplyPatchBody publishes it, and the batch's own encoder + // carries it. + patchRow("SpecID", "a spec-id edit refuses", "neither IssuePatchBody nor ApplyPatchBody publishes spec_id"), + patchRow("AwaitID", "an await-id edit refuses", "neither IssuePatchBody nor ApplyPatchBody publishes await_id"), + patchRow("Owner", "an owner edit refuses ON updateIssue", + "IssuePatchBody excludes owner — which the document itself calls an accident of order rather than a decision, since ApplyPatchBody DOES publish it and issues:batchApply's update item carries it"), + patchRow("ClosedBySession", "a closed-by-session edit refuses", "neither IssuePatchBody nor ApplyPatchBody publishes closed_by_session"), + patchRow("Persistence", "a persistence-mode edit refuses", + "neither body publishes persistence: moving a row between planes mid-plan is a different act from writing its fields"), + { + ID: "W-IssuePatch.ParentID", Kind: KindRetired, + What: "a parent re-hang through update used to refuse", + Why: "RETIRED with W-IssuePatch.Status (ga-7i6by). It is ONE call rather than a remove-then-add pair, which is the whole reason the member exists: the two-call spelling leaves the issue parentless if the second call fails, and dependencies:add/remove — still the general write side of the graph over this wire — cannot express the atomic replacement. " + + "The empty string removes every parent-child edge, so it travels like `assignee`'s empty string rather than being skipped. The graph refusals it earns are the server's and arrive typed: a cycle through the issue's own descendant as the PLAIN dependency_cycle, and an existing edge of another type as dependency_exists", + SpecRow: "D8 refuse-not-drop", + PinnedBy: patchMemberPin, + }, + { + ID: "W-CreateBatchRequest.Provenance", Kind: KindRefuse, + Type: tyCreateBatch, Field: "Provenance", + What: "labeling a batch create's history entry refuses", + Why: "batchCreateIssues publishes actor and items only, and the server writes its own label; see W-UpdateRequest.Provenance. It is the one Provenance whose ABSENCE is visible in shipped history — the surface this role serves has always named its source file in the entry (`bd: create 3 issue(s) from plan.md`)", + SpecRow: "D8 row 14 refuse-not-drop", + PinnedBy: batchCreatePin, + }, + { + ID: "W-CreateBatchRequest.ForceIDPrefix", Kind: KindRefuse, Flag: "--force", + Type: tyCreateBatch, Field: "ForceIDPrefix", + What: "permitting explicit ids outside the workspace's configured prefix refuses", + Why: "the wire publishes no such member — and could not honor one, since it publishes no explicit id for the flag to permit (W-BatchCreateItem.Issue). Dropping it would answer a request about WHERE ids may be written with a batch whose ids the server chose", + SpecRow: "D8 row 14 refuse-not-drop", + PinnedBy: batchCreatePin, + }, + { + ID: "W-BatchCreateItem.Issue", Kind: KindRefuse, + Type: tyBatchCreateItem, Field: "Issue", + What: "an item whose Issue populates any member outside the wire's eight refuses, naming the member", + Why: "apigen.BatchCreateItem carries title, description, design, acceptance_criteria, priority, issue_type, assignee and labels and nothing else, while the role accepts far more of a types.Issue: an explicit id, the wisp flags, metadata, the storage class, every timestamp, the gate/molecule/event fields. " + + "ONE row rather than one per member because the reason is one reason — the wire's item vocabulary — and forty rows repeating it would say nothing a reader does not learn here. Exhaustiveness is held by REFLECTION instead: the client's carried and role-ignored tables are checked against types.Issue field by field, so a member added upstream is refused the day it lands rather than dropped until someone notices. " + + "The members the role ITSELF ignores on a create (ContentHash, RowVersion, lease, compaction, routing overrides, hydration flags) are not in this population and are not refused: a local create drops them too", + SpecRow: "D8 row 14 refuse-not-drop", + PinnedBy: batchCreatePin, + }, + // The three edge rows are BATCH-CREATE's, and the qualifier is + // load-bearing now that a second operation writes the same shape: + // createIssue's own edge publishes `reverse` and `metadata` (its issue + // HAS an id for a target to point back at, which a batch item does + // not), so the client sends both there. Only ThreadID is refused on + // both, because no operation publishes a thread member. + createDependencyRow("Reverse", "an edge written from the target back to the new issue refuses ON A BATCH CREATE", + "BatchCreateDependency carries target_id and type only; dropping Reverse would write the edge in the OPPOSITE direction from the one asked for, which is a different graph. createIssue's CreateIssueDependency DOES publish it, and the single-create path sends it"), + createDependencyRow("Metadata", "typed edge metadata refuses ON A BATCH CREATE", + "BatchCreateDependency publishes no metadata member, and a waits-for gate whose metadata was dropped is a readiness rule that silently does not hold. createIssue's edge publishes it, and the single-create path sends it verbatim"), + createDependencyRow("ThreadID", "associating an edge with a discussion thread refuses", + "neither BatchCreateDependency nor CreateIssueDependency publishes a thread member"), + { + ID: "W-CreateRequest.IDPrefix", Kind: KindRefuse, + Type: tyCreateRequest, Field: "IDPrefix", + What: "overriding the prefix an explicit id is checked against refuses", + Why: "createIssue publishes no `id_prefix`, and the omission is the SERVER's decision rather than a gap (internal/httpapi/create.go): the field exists because a workspace's own config.yaml prefix wins over the database's and only a local front door can read that file, so a remote caller's config.yaml describes a workspace this server does not serve. " + + "Publishing it would let a caller override the served workspace's prefix rule from outside it. Dropping it instead would check the id against the SERVER's prefix while the caller believed it was checked against theirs — the same request, two different answers to 'may this workspace mint this id'", + SpecRow: "D8 row 16 refuse-not-drop", + PinnedBy: createPin, + }, + { + ID: "W-CreateRequest.Issue", Kind: KindRefuse, + Type: tyCreateRequest, Field: "Issue", + What: "a create whose Issue populates any member outside the wire's twenty refuses, naming the member", + Why: "createIssue publishes the whole create VOCABULARY — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue: the creation stamp (created_at, created_by), because a caller-supplied creation time makes the row disagree with the journal entry that records it and re-dating history is what an import is for; and spec_id, await_*, mol_type, wisp_type, work_type, storage_class, source_*, pinned, is_template and the event quartet, which this surface publishes on no operation, read or write. " + + "ONE row rather than one per member for W-BatchCreateItem.Issue's reason — the reason is one reason — and exhaustiveness is held by the same REFLECTION over types.Issue, sharing the role-ignored table with the batch so the two operations cannot disagree about what the ROLE drops. " + + "Issue.Comments and Issue.Dependencies are not in this population: the role itself refuses them, so a local create fails too and this is validation rather than divergence", + SpecRow: "D8 row 16 refuse-not-drop", + PinnedBy: createPin, + }, + { + ID: "L-create-notfound", Kind: KindDegrade, + What: "a create whose dependency or waits-for target names no row refuses as issueops.ErrValidation ALONE — not as ErrValidation wrapping ErrNotFound — and does not name the target", + Why: "the wire answers a dangling target with a 400 invalid_argument naming `dependencies` and a FIXED detail (internal/httpapi's failCreateIssue), which deliberately does not quote the role's own message: that message arrives as a driver error naming tables and constraints, and 4xx details on this surface reflect the caller's own input back rather than server internals. " + + "The refusal still fails the whole request and creates NOTHING — the promise the row is about — and only the second sentinel and the target's name are lost. It is batchCreateIssues' L-batchcreate-notfound on the single create, and it retires the same way: an upstream code that distinguishes the absent-target refusal and carries the target. " + + "A missing --parent target already retired out of this row: failCreateIssue's errors.As(&parentNotFound) arm answers it with a distinguishing 404 not_found that names the target, and the client maps that to issueops.ErrNotFound (see TestServedCreateRefusesAnAbsentParentAsNotFound) — the row now covers only dependency and waits-for targets", + SpecRow: "D8 row 16", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-create-prefix", Kind: KindDegrade, + What: "an unforced explicit id outside the workspace's configured prefix refuses as issueops.ErrValidation rather than as storage.ErrPrefixMismatch", + Why: "the wire spells that refusal as a 400 invalid_argument with `param: \"id\"` and `reason: invalid_value` (internal/httpapi's failCreateIssue), which is the SAME pair a malformed or oversized `id` earns — so nothing on the wire tells the two apart, and reconstructing the typed sentinel from the pair would misclassify every other refusal of that member. " + + "The guard itself is untouched: the id is refused, nothing is created, and the detail names `force_id_prefix` as the bypass, which is the recovery a caller needs. What is lost is the errors.Is arm both local front doors use to decide whether to re-offer the create with --force. Upstream ask: a prefix_mismatch code, or a reason that distinguishes it, which retires this row", + SpecRow: "D8 row 16", + PinnedBy: pinnedByS3Conformance, + }, + // The issues:batchApply population, from client wave ga-mijra. It is + // SMALL, and that is the operation rather than an oversight: the create + // item publishes createIssue's whole twenty, the close item maps whole, + // the edge item maps whole, and the update item's patch is WIDER than + // updateIssue's in the two places that matter to a plan (a full label + // patch, and `owner`). What is left is one patch member and two facts + // about the RESULT. + { + ID: "W-CreateItem.Issue", Kind: KindRefuse, + Type: tyApplyCreateItem, Field: "Issue", + What: "a create ITEM whose Issue populates any member outside the wire's twenty refuses, naming the member", + Why: "ApplyCreateItem publishes exactly createIssue's create vocabulary — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue, for the reasons W-CreateRequest.Issue gives in full. " + + "It is a row of its OWN rather than a citation of that one because the operations are different: a caller auditing why their PLAN refuses must not be sent to a row about a single create, and the two can diverge the day either vocabulary moves. The partition itself is SHARED — one carried table, one role-ignored table, held against types.Issue by the same reflection — so they cannot disagree about what the wire carries or about what the role drops. " + + "Issue.Comments and Issue.Dependencies are not in this population and are refused as validation on both sides: edges in this role are ITEMS, so a create item has nowhere to put one at all", + SpecRow: "D8 refuse-not-drop", + PinnedBy: applyPin, + }, + { + ID: "W-ApplyPatch.ParentID", Kind: KindRefuse, + Type: tyIssuePatch, Field: "ParentID", + What: "a parent re-hang inside an update ITEM refuses, where the same member serves on updateIssue", + Why: "ApplyPatchBody deliberately publishes no parent_id, and the absence is this operation's ONE-EDGE-ONE-SPELLING rule rather than a gap: a parent is a dep_add item of type parent-child, so the ORDER of every edge in a plan stays total and there is exactly one place an edge is written. " + + "The single patch has no ordering to express and publishes the member directly (W-IssuePatch.ParentID, retired by client wave ga-7i6by), which is why the same Go field is carried by one document and refused by the other. " + + "Refusing is not a loss of capability, only of spelling: a plan re-hangs a parent with a dep_add item, which is the atomic replacement in the position the caller declared it", + SpecRow: "D8 refuse-not-drop", + PinnedBy: applyPin, + }, + { + ID: "L-apply-snapshot", Kind: KindDegrade, + What: "every ItemResult of a batch apply comes back with Issue nil, where a local backend hydrates a post-item snapshot", + Why: "the WIRE result is lean by the document's own decision and the role's leaf says why: ApplyItemResult carries ids, `changed` and `revision` and no issue, because the Go contract carries the snapshot for its COMPLETION HOOKS — which hand a script the row they are telling it about — and hooks never fire on the http surface at all. A hundred hydrated issues with their labels and edges would be a response an order of magnitude larger than the request that produced it. " + + "What a caller loses is a read it can make: the ids ARE published, per item and through Keys, so the rows are one getIssue away and the plan's next step is composed from ids rather than from snapshots. It is a degradation rather than a refusal because nothing about the WRITE differs — every item landed exactly as asked — and refusing would make the whole operation unavailable over http to keep a member no consumer on this surface can use", + SpecRow: "D8 refuse-not-drop (result half)", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-apply-ref", Kind: KindDegrade, + What: "an unresolvable metadata_refs key comes back as a *RefError naming the MEMBER rather than the key, and the reconstructed error replaces the server's problem envelope", + Why: "the wire's 400 names the offending member in `param` — `items[3].create.metadata_refs` — and carries the item index, the item's key and `declared_later`, but not WHICH entry of the refs map failed: the role's RefError.Member is diagnostic prose (`metadata_ref `) rather than a vocabulary, so the server maps it onto the document's own member names instead of publishing it. The two ADDRESSING refs, target and source, are named exactly. " + + "The envelope is dropped because issueops.RefError has nowhere to put it: its Unwrap is hardcoded to ErrValidation and it carries no member for a cause, which is the role type's shape rather than a choice made here. The discriminator a caller ACTS on — an ordering mistake against a typo — survives whole, in both polarities. Upstream ask: a typed ref-key member on the problem document, which retires this row", + SpecRow: "D8 refuse-not-drop (result half)", + PinnedBy: pinnedByS3Conformance, + }, + { + // The COMMENT population, from client wave ga-f352s, and it is the + // one divergence on that role: the request maps member for member, + // so nothing refuses on shape and there is no W- row. + ID: "L-comment-author", Kind: KindDegrade, + What: "a comment's AUTHOR is subject to the server's own actor rule, which no local leg applies: it is stored TRIMMED where a local backend stores it verbatim, and one carrying a control character is refused (issueops.ErrValidation) where a local backend stores it", + Why: "the operation validates `author` with the `actor` rules whole (internal/httpapi's validateNameMember: trim, refuse empty, refuse past 256 bytes or 255 characters, refuse any control rune) and passes the TRIMMED value on to the role, while issueops.ValidateAddCommentRequest checks only that the field is non-empty and stores what it was given. So the same request produces a different STORED VALUE on the two legs, and a value one leg stores the other refuses. " + + "IT IS THE SERVER'S RULE AND THE DOCUMENT PUBLISHES IT, which is why this is a ledger row rather than a bug on either side: the schema states the trim and the character rule in as many words, and the reason is the column — `author` is 255 characters wide and every renderer of the thread prints it, where an unfiltered C1 introducer is an escape-sequence payload. The refusal half is a NARROWING the wire makes on purpose. " + + "THE CLIENT DOES NOT ANTICIPATE EITHER HALF, and that is the decision this row records. Trimming here would make the client agree with the server about the stored value and disagree with the role's own contract — and it would silently rewrite a caller's request, which is the one thing this seam never does. Refusing the control rune here would be a second copy of a server rule that is free to move. So the value travels as the caller wrote it and the server's answer is reported unchanged, which keeps the divergence visible instead of laundering it. " + + "IT IS A DEGRADE RATHER THAN A REFUSE because the ordinary path PROCEEDS: a well-formed author is stored, and the difference cannot be misread as a wider or narrower answer — a comment lands on the thread the caller named either way. The refusal half is the SERVER's, not this client's refuse-not-drop, which is what KindRefuse classifies. " + + "What a caller loses is an author whose surrounding space survives, and the recovery is the one the role's own contract already implies: compose the author from a value you would be willing to see printed. Upstream ask: either the role trimming its own author on every leg, or the operation storing it verbatim — the rows agree the day the two rules become one", + SpecRow: "D8 row 19", + PinnedBy: pinnedByS3Conformance, + }, + { + // The RELEASE population, from client wave ga-f352s, and it has + // exactly one row. releaseIssue's request maps member for member — + // actor, the guard, force and the path — so nothing refuses on + // shape; what diverges is one REFUSAL VOCABULARY, which is the same + // shape as the two create parks and retires the same way. + ID: "L-release-notclaimed", Kind: KindDegrade, + What: "a release of a row that holds NO CLAIM answers issueops.ErrNotReleasable rather than issueops.ErrNotClaimed; a status that will not accept a release answers ErrNotReleasable as it does everywhere", + Why: "the role splits the two — ErrNotClaimed for a row nobody holds, ErrNotReleasable for a status the transition is not defined over — and the wire spells BOTH `not_releasable` under one code, with no member telling them apart. That is the server's deliberate choice (internal/httpapi's CodeNotReleasable) rather than an omission, and its detail names both conditions instead of guessing between them. " + + "So this client maps to the WIDER of the two, which is the only honest read: reconstructing ErrNotClaimed would assert a fact about the row that the wire never sent, and scraping the detail for it would bind a sentinel to prose. " + + "NOTHING ELSE ABOUT THE REFUSAL MOVES — nothing is written, the row and its version are untouched, and the conditional path is unaffected: a caller that named a holder gets ErrAssigneeMismatch on both sides, because that refusal has a code of its own. " + + "The caller who loses something is the one that told 'I already released this' from 'the row was never claimed', and the recovery is the one the server's own detail prescribes: READ THE ROW rather than retrying blind. Upstream ask: a code, or a member, that distinguishes the unheld row from the unreleasable status — which retires this row", + SpecRow: "D8 (Releaser), D9", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "L-release-notowner", Kind: KindDegrade, + What: "an unforced, unconditional release by an actor that is NOT the holder answers issueops.ErrAlreadyClaimed — carrying *issueops.ClaimConflictError — rather than issueops.ErrNotOwner", + Why: "the wire answers the ownership fence with `already_claimed`, which is the code updateIssue already gives the same situation (a live foreign owner refusing a write, with a force bypass and a name-the-holder bypass), and this client maps that code to the sentinel every other operation means by it. The two sentinels are distinct values in issueops and neither wraps the other, so the arm a caller writes differs. " + + "REPORTING IT AS ErrNotOwner WOULD BE THE WORSE TRADE, not merely a different one: the code is shared with the claim refusals, so a client that special-cased it for this operation would be reading the OPERATION to decide the sentinel rather than the code — and would then answer ErrNotOwner for a genuine already_claimed the day the server reuses the code here for anything else. " + + "WHAT SURVIVES IS EVERYTHING A CALLER ACTS ON: the refusal is typed, it names the row (the request supplied the id the wire leaves out), nothing is written, and BOTH bypasses answer exactly as the role says — force releases the foreign claim, and naming the holder in expected_assignee releases it too, because a match replaces the fence. The wire deliberately sends no `assignee` member here, so the holder is not named: absence means 're-read the row', never 'nobody holds it'. Upstream ask: a code, or a member, that separates the release's fence from a claim conflict — which retires this row", + SpecRow: "D8 (Releaser), D9", + PinnedBy: pinnedByS3Conformance, + }, + { + ID: "W-IssuePatch.Labels", Kind: KindRetired, + Type: tyIssuePatch, Field: "Labels", + What: "RETIRED — the whole ordered label edit crosses: `labels` replaces, `add_labels` adds, `remove_labels` removes", + Why: "upstream #5510 published add_labels and remove_labels on IssuePatchBody and client wave ga-jpywb emits both, which is the retirement path this row named. " + + "The three travel as FLAT siblings where applyBatch nests them under one object, and the server assembles all three into ONE issueops.LabelPatch — so the algebra the role states (replace, then add, then remove; removal wins) is applied server-side and is never this client's to arrange. " + + "WHAT THE REFUSAL WAS PROTECTING is worth keeping after the refusal is gone: degrading an incremental edit onto the replace-only member would have meant reading the set, adding to it and writing it back, which silently drops any label another writer added in between. `bd label add` and every agent that tags work concurrently are exactly that caller, so the refusal was right for as long as the members did not exist — and it is the members that retire it, not a change of mind about the read-modify-write", + SpecRow: "D8 refuse-not-drop, open questions (tracked-refusal roadmap)", + PinnedBy: pinnedByS3Conformance, + }, + { + // The CONFIG-WRITE population, from client wave ga-jpywb, and it has + // exactly one row. Both verbs map member for member — a key in the + // path, a value in the body, nothing else — so nothing refuses on + // shape; what diverges is a pair of EDGE BOUNDS the wire applies + // and no local leg does. + ID: "L-config-bounds", Kind: KindDegrade, + What: "a setting VALUE past types.MaxTextBytes bytes, and a setting KEY past types.MaxFieldLen characters on the WRITE, are refused with issueops.ErrValidation naming the member; on a local leg the same request reaches the column and fails with the engine's own `too large for column` error, which is no sentinel at all", + Why: "the bound belongs to the OPERATION rather than to the role: internal/httpapi's settingWriteKey and settingValue check both before the role is called, because a request the caller could have fixed should be a 400 naming the member rather than the 500 a column overflow would otherwise produce. workapi.ValidateSettingWrite — the rule every leg shares — applies no length bound at all, so below the wire the column is the only check there is. " + + "MEASURED, not inferred: a 65536-byte value answers `400 invalid_argument: \\`value\\` is 65536 bytes; storage holds at most 65535` over http and `Error 1105: string ... is too large for column 'value'` on the embedded leg, and a 306-character key splits the same way. Exactly 65535 bytes is accepted on both. " + + "THIS CLIENT RESTATES NEITHER BOUND, and that is the decision this row records. They are the SERVER's policy on a value whose shape the role accepted, one release away from moving, so a second copy here would either drift or refuse a request a newer server would take — the same argument L-comment-author makes about the author rule, and the same posture. What travels back is the operation's own 400, which the problem mapper turns into ErrValidation. " + + "IT IS A DEGRADE RATHER THAN A REFUSE because the ordinary path PROCEEDS and because the divergence runs in the CALLER'S FAVOR: over http an oversized write is a typed, member-named refusal that wrote nothing, where a local leg hands back a driver error no caller can classify. What a caller loses is nothing; what a caller must not assume is that a value a local workspace stored will store here. " + + "THE TWO BOUNDS ARE NOT SYMMETRIC ACROSS THE VERBS, and the asymmetry is the operation's: DELETE checks only that the key names something, so removing a 306-character key succeeds over http exactly as it does locally. Upstream ask: the length rules moving onto the shared validator, which retires this row by making the two legs one", + SpecRow: "D8 row 11, D9", + PinnedBy: pinnedByS3Conformance, + }, + { + // The UPDATE-BOUNDS row, and L-config-bounds' sibling one operation + // over. It is not the same row because the two are not the same + // situation: there the role applies no length rule at all and the + // column is the only check below the wire, HERE THE ROLE APPLIES THE + // SAME RULE with the same constant — so what is lost is a sentinel + // rather than a bound. + ID: "L-update-fieldlen", Kind: KindDegrade, + What: "an updateIssue patch member past types.MaxFieldLen characters — a label on any of the three label members, `title`, `external_ref` — is refused with issueops.ErrValidation naming the member; on a local leg the same request answers types.ErrFieldTooLong", + Why: "the bound is applied TWICE and identically: internal/httpapi/update.go checks types.CheckFieldLen at the edge before the role is called, and internal/storage/issueops applies the same function below it. So this is a classification divergence and not a policy one — a value one leg stores the other stores, and a value one leg refuses the other refuses. " + + "WHAT COARSENS IT is the spelling: the operation refuses with `invalid_argument` and reason `invalid_value` (internal/httpapi's refuse on the patch member), which is the SAME pair a malformed status, an unparseable timestamp or any other bad value on the same member earns. Nothing on the wire tells them apart, so reconstructing ErrFieldTooLong from the pair would misclassify every other refusal of that member — the argument L-create-prefix makes about the id, on the patch. " + + "MEASURED, not inferred: a 256-character label answers `400 invalid_argument: \\`add_labels[0]\\` is 256 characters; storage holds at most 255` over http and ErrFieldTooLong through the reference store's own Lifecycle role, and exactly 255 characters is accepted on both. " + + "THIS CLIENT RESTATES THE BOUND NOWHERE, and the reason differs from L-config-bounds': not that the rule is the server's to move, but that a second copy of a rule two layers already apply is a third place for it to drift. What travels back is the operation's own 400. " + + "IT IS A DEGRADE RATHER THAN A REFUSE because the path PROCEEDS and the outcome is identical on both legs — the request fails, the row is untouched, and no truncated value is stored — while the detail names the offending member and its length, which is the recovery a caller needs. What is lost is the errors.Is arm a caller writes to tell 'too long' from 'malformed'. Upstream ask: a `too_long` reason, or a code of its own, which retires this row", + SpecRow: "D8 row 16, D9", + PinnedBy: pinnedByS3Conformance, + }, + { + // The EVENTS-JOURNAL population, from client wave ga-jpywb, and it + // has exactly one row. The read maps member for member — a + // checkpoint, a bound, a page of records and a head — and the typed + // truncation crosses whole through the problem document's three + // window members. What diverges is the one promise a PAGED transport + // cannot make about an UNPAGED read. + ID: "L-events-paging", Kind: KindDegrade, + What: "an UNCAPPED journal read (limit 0) is served as a loop of handler-sized requests rather than one, so its rows and its head no longer come from a single instant; a bounded read is one request and is unaffected", + Why: "the role imposes no ceiling of its own — journalops.Journal says a limit of 0 means uncapped, because the caller that pages a hundred thousand records out to a file is as legitimate as the one polling for ten — and the OPERATION refuses `limit=0` by value, capping a page at 10000 (internal/httpapi's maxEventsLimit). That cap is the handler's promise to its clients rather than a narrowing of the role, and this client is on the other side of it. " + + "SO THE LOOP IS THE ONLY HONEST READING. Refusing an uncapped read would refuse something the role permits; capping one silently at 10000 would answer a partial page beside a head saying there is more, which is a consumer stalling on a gap nobody told it about. Both are worse than N transactions. " + + "WHAT SURVIVES IS WHAT A CONSUMER ACTS ON: rows stay contiguous and seq-ascending, because each page continues exactly where the last ended; the head is the LAST page's, so it is the freshest and can only be at or ahead of the last row served; and a truncation on any page is the whole read's failure, never a shorter answer — a loop that returned the prefix it had already gathered would answer a gap with a plausible-looking suffix, which is the one failure a replay feed must never ship. " + + "WHAT DOES NOT SURVIVE is atomicity across the whole answer: a mutation committing mid-loop appears in a later page of the SAME call rather than in the next one. A consumer cannot observe that as a gap or a duplicate — it reads as records it would have received on its next poll, arriving early — which is why this is a degrade rather than a refusal. " + + "IT IS A DEGRADE RATHER THAN A REFUSE for the ordinary reason too: the path proceeds, and the answer cannot be misread as narrower or wider than the caller asked for. Upstream ask: an unlimited spelling on the operation, or a cursor the page can hand back — either retires this row", + SpecRow: "D8 (Journal), D9", + PinnedBy: pinnedByS3Conformance, + }, + } +} + +// batchCreatePin is the one sweep behind every batch-create refusal row: it +// drives each excluded member one at a time and asserts the call fails WITHOUT +// dialing, and it holds the carried/ignored partition against types.Issue by +// reflection so the population cannot go stale by omission. +const batchCreatePin = pinnedByS3Conformance + +// createPin is the single-create counterpart: the same shape of sweep, driving +// every excluded member of a CreateRequest one at a time and asserting the call +// fails WITHOUT dialing, with the carried/ignored partition held against +// types.Issue by reflection. +const createPin = pinnedByS3Conformance + +func createDependencyRow(field, what, why string) Row { + return Row{ + ID: "W-CreateDependency." + field, Kind: KindRefuse, + Type: tyCreateDep, Field: field, + What: what, + Why: why + " (internal/httpapi/spec BatchCreateDependency)", + SpecRow: "D8 row 14 refuse-not-drop", + PinnedBy: batchCreatePin, + } +} + +// applyPin is the sweep behind every batch-apply refusal row: it drives each +// excluded member one at a time and asserts the call fails WITHOUT dialing, +// with the create item's carried/ignored partition held against types.Issue by +// the same reflection the two other create paths use. +const applyPin = pinnedByS3Conformance + +// patchMemberPin is the round trip behind the four patch members client wave +// ga-7i6by carries: it drives each one into the document the role builds and +// reads it back off the transport, which is the one thing about this operation +// no result can show. +const patchMemberPin = pinnedByS3Conformance + +func patchRow(field, what, why string) Row { + return Row{ + ID: "W-IssuePatch." + field, Kind: KindRefuse, + Type: tyIssuePatch, Field: field, + What: what, + Why: why + " (internal/httpapi/update.go issuePatchMembers)", + SpecRow: "D8 refuse-not-drop", + PinnedBy: pinnedByS3Conformance, + } +} + +// commandRows are D7's named members of the refused class that carry no request +// field: whole commands and the flag modes of served commands. +func commandRows() []Row { + // The cmd/bd wiring landed. Two pins, split the way the mechanism is: a + // whole command is early-refused from the classification table and every + // entry in it is driven against the REAL cobra tree, while a served + // command's refused flag mode is a per-flag invocation. + const refusedCommand = pinnedByS3Conformance + const refusedFlagMode = pinnedByS3Conformance + // Every row this helper builds cites D7 and nothing else: D7 IS the + // whole-command-and-flag-mode decision, and a row citing a second decision + // is a row that wants writing out in full (F-count and F-close both do). + row := func(id, command, flag, what, why string) Row { + pinned := refusedCommand + if flag != "" { + pinned = refusedFlagMode + } + return Row{ID: id, Kind: KindRefuse, Command: command, Flag: flag, What: what, Why: why, SpecRow: "D7", PinnedBy: pinned} + } + return []Row{ + row("F-ready-explain", "ready", "--explain", "`bd ready --explain` refuses", + "it dispatches onto raw GetBlockedIssues/GetIssuesByIDs/GetDependencyCounts/DetectCycles, three of which are on the unsupported allowlist"), + row("F-ready-mol", "ready", "--mol", "`bd ready --mol` refuses", + "its molecule subgraph load reaches findHierarchicalChildren, an IDPrefix SearchIssues shape the parent-walk bridge cannot express (E-IssueFilter.noShape). GetDependencyRecords and GetDependentsWithMetadata, which the same load also calls, stopped being the blocker when ga-b8ddd.30 flipped them onto the wire"), + row("F-ready-gated", "ready", "--gated", "`bd ready --gated` refuses", + "it dispatches onto a filtered SearchIssues shape the bridge cannot express, plus GetDependents"), + row("F-show-thread", "show", "--thread", "`bd show --thread` refuses", + "showMessageThread renders each reply's sender, recipient, body and timestamp off GetDependentsWithMetadata, but ga-b8ddd.30 flipped that read onto getIssue's include_dependents parameter, which carries the collectDependents SHALLOW projection (id/status/type/priority/title + edge type only, be-4d36f2). Those fields come back zeroed over http and zero-timestamp replies sort ahead of the root — a silent-wrong degrade the refuse-over-degrade doctrine forbids. Retires with a full-dependent wire shape, a server-side ask"), + row("F-show-refs", "show", "--refs", "`bd show --refs` refuses", + "showIssueRefs's --json marshals the full GetDependentsWithMetadata rows, but the wire answers the same collectDependents shallow projection, so created_at/assignee/description come back zeroed and the JSON differs from a local workspace. The text render consumes only the shallow fields, but the flag cannot be split from its --json mode, so the whole flag refuses rather than serve a divergent JSON silently"), + row("F-show-children", "show", "--children", "`bd show --children` refuses", + "showIssueChildren's --json marshals the full GetDependentsWithMetadata rows, the same collectDependents shallow projection as --refs, so created_at/assignee/description come back zeroed over http; `bd children` refuses as a whole command for the same reason"), + row("F-mol-ready", "mol ready", "", "`bd mol ready` refuses", + "it is the same runMolReadyGatedCore body as `bd ready --gated`"), + row("F-blocked", "blocked", "", "`bd blocked` refuses", + "it is raw GetBlockedIssues, which is on the unsupported allowlist"), + { + ID: "F-count", Kind: KindRetired, Command: "count", + What: "RETIRED — `bd count` is SERVED whole", + Why: "it said the command refuses because \"issueops.Counter has no wire operation; a counts operation is a filed upstream ask\", and that ask was DELIVERED: upstream #5508 published countIssues, client wave ga-icks1 wired the Counter accessor, and `count` moved from httpRefusedCommands into httpServedCommands. D8 row 20 and docs/reference/http-workspaces.md have said so since; this row was the last place that did not. " + + "Every flag the command publishes reaches a wire member — the whole predicate, the six instant bounds, the three emptiness checks, --include-infra, and the five --by-* flags as the one group_by parameter — so there is no refused mode left to name either. " + + "HOW IT ROTTED IS THE PART WORTH KEEPING. Its pin was TestClassifiedRefusedCommandsRefuseBeforeTheOSSPreRun, which walks httpRefusedCommands and drives every entry. The moment `count` left that table the pin stopped covering this row — it stayed LIVE BY NAME, so the well-formedness gate that resolves PinnedBy to a real test kept passing, and DEAD BY COVERAGE, so nothing anywhere asserted the row's claim. A ledger row can be false for a whole wave under a green pin, which is what TestFRowsAgreeWithTheCommandClassification now makes impossible", + SpecRow: "D7 (RETIRED), D8 row 20", + // The retirement's own evidence: the corpus replay compares `bd + // count`'s answer byte-for-byte over http against the same command + // over a local Dolt workspace, and a count's whole answer is a + // number — a predicate narrowed or widened on the way out prints a + // different integer and nothing else differs. + PinnedBy: pinnedByS3Conformance, + }, + row("F-serve", "serve", "", "`bd serve` refuses against an http workspace", + "the OSS classifier would happily serve it from the opened store, and a bd serve re-serving a remote bd serve is a proxy chain nobody designed: run serve where the database is"), + { + ID: "F-close", Kind: KindRefuse, Command: "close", Capability: "issues.batchClose", + What: "`bd close` is SERVED whole — single id, several ids and --claim-next — over issues:batchClose; it refuses only against a DOWN-LEVEL server that does not advertise issues.batchClose", + Why: "the CLI's close front door routes every id, single-id included, through BatchCloser.CloseBatch, and Lifecycle.Close has zero CLI callers at tip. The wire now carries issues:batchClose, so the whole CloseBatchRequest — multi-item and the atomic ClaimNext included — is one wire call and one server-side transaction; nothing is composed or refused where the capability is present. " + + "Against a server too old to advertise issues.batchClose, servesBatchClose() reads the handshake snapshot and routes around the batch dial entirely, so no Preflight runs and no wire.ErrCapabilityAbsent is raised: the down-level leg's refuseUnservedCloseShape raises the STORE's own *ErrHTTPUnsupported (batchcloser.go), and cmd/bd's renderEscapedHTTPRefusal turns it into the capability-absent taxonomy (case 2) by scanning the served command's own capability list for the first token the server does not advertise — issues.batchClose, which is the token it then names to upgrade to. The single-item, no-ClaimNext shape still composes onto closeIssue in that down-level leg (see L18); the shapes that cannot compose refuse there. The item cap is L-close-cap", + SpecRow: "D8 row 17 (resolved, Wire), D9 L18, D9 L-close-cap", + // The command is served; the down-level refusal is the capability gate's, + // exercised against a server without issues.batchClose. + PinnedBy: refusedFlagMode, + }, + { + ID: "F-partial-id", Kind: KindRefuse, + What: "partial-id resolution refuses with its own taxonomy text", + Why: "SearchIssueIDs has no wire operation, and the client cannot tell a partial id from a full id that does not exist — so the refusal text covers both outcomes rather than falling through to a raw search error", + SpecRow: "D11", + PinnedBy: pinnedByS3Conformance, + }, + } +} diff --git a/internal/httpclient/encode/ledger_fields.go b/internal/httpclient/encode/ledger_fields.go new file mode 100644 index 000000000..30aae447b --- /dev/null +++ b/internal/httpclient/encode/ledger_fields.go @@ -0,0 +1,456 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/ledger_fields.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import "reflect" + +// The per-field half of divergence ledger v1: one row for every request-shape +// field this package's encoder cannot put on the v0 wire, plus the two it +// deliberately drops. +// +// These are instances of L12 — "an inexpressible filter refuses, never drops" — +// enumerated one field at a time, because a class rule that is not enumerated +// is a rule nothing can check. The bijection gate reads them back against +// reflection over the same structs, so a field added upstream lands here or +// fails CI. + +const ( + fieldSpec = "D9 L12, D7, D8" + // fieldPin and dropPin are the same test because it is the same property: + // the sweep populates one field at a time and asserts the behavior the + // table declares, so a refusal that stopped refusing and a drop that + // started sending both fail there. + fieldPin = "TestEncoderHonorsEveryTableDisposition" + dropPin = "TestEncoderHonorsEveryTableDisposition" + dropSpec = "D9 (a degradation not in this table is a bug)" + noWireList = "listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml)" +) + +// briefRetiredWhy is the one retirement story behind the three rows #5586's +// `brief` parameter retired — the ready listing's, the issue listing's, and the +// ready bridge's Lite, which workapi assigns to the same field. +// +// IT IS A CONSTANT BECAUSE IT WAS THREE COPIES, and the three drifted the way +// copies do: the closing sentence stayed true of the WIRE and false of the +// CALLER for a whole wave, in triplicate, and correcting it meant finding all +// three. One string is one thing to keep true. +const briefRetiredWhy = "upstream #5586 published `brief` on GET /v0/beads/ready and GET /v0/beads/issues, which is the retirement path this row named. " + + "Both page encoders send the parameter now — readyTable, listTable and the ready bridge all map it — so the client asks for the projection it was handed and the server leaves the text columns unselected. " + + "The COUNT keeps the drop under E-ReadyRequest.Brief@countReadyWork, because countReadyWork publishes no such parameter and a cardinality has no rows to project. " + + "WHAT DID NOT RETIRE WITH IT IS THE WIRE HALF OF THE MARKER, and only that half: types.Issue.IsLitePartial is `json:\"-\"` and never crosses, so a projected page arrives on the transport byte-identical to a page of genuinely textless rows — the same absence getIssue's brief_deps carries, deferred upstream by #5549. " + + "THE CALLER-VISIBLE AMBIGUITY IS CLOSED, by client wave ga-f352s: `brief` is a parameter to the page decode rather than a field on anything, so httpReader hands it to wireRows (role_reader.go) and this client stamps IsLitePartial on every row of a page it ASKED to be projected — which is precisely what issueops.ListRequest.Brief's own leaf says a wire consumer distinguishes the two by — and never on a hydrated one. `bd list --long --brief` therefore prints \"Description: (omitted by --brief)\" over http exactly as it does locally, and TestHTTPCommentAndBriefRenderEndToEnd pins that line through the real binary" + +func refusal(id string, ty reflect.Type, field, what, why, spec string) Row { + return Row{ + ID: id, Kind: KindRefuse, + Type: ty, Field: field, + What: what, Why: why, SpecRow: spec, PinnedBy: fieldPin, + } +} + +// readyRequestRows are the ready vocabulary's two inexpressible members. +// +// [Removed: a third row, "E-ReadyRequest.ExcludeIDs", stood here for an +// enterprise-only id-exclusion filter. issueops.ReadyRequest carries no +// ExcludeIDs member in OSS (issueops/reader.go), so the row named a struct +// field that does not exist and TestEncoderTableClassifiesEveryRequestField +// failed "names a field that does not exist" against it. The matching table.go +// entry in readyFilterEntries() was removed alongside this row. The separate, +// still-real "E-WorkFilter.ExcludeIDs" row below (workFilterBridgeRows) is +// unaffected: workapi.WorkFilter genuinely carries that field.] +func readyRequestRows() []Row { + return []Row{ + refusal("E-ReadyRequest.MolType", tyReadyRequest, "MolType", + "a molecule-type restriction on ready work refuses", + "neither listReadyWork nor countReadyWork publishes a mol-type parameter, and the ready query applies molecule typing inside — so a dropped restriction would answer with the wider set of every molecule type", + fieldSpec), + refusal("E-ReadyRequest.Offset", tyReadyRequest, "Offset", + "a non-zero Offset on ready work refuses", + "the wire publishes no offset parameter, and the store-backed role refuses a non-zero Offset itself with a typed *ErrUnsupported. A ready request carries no keyset position, so there is no portable way to page ready work at all — a caller that must page pages a ListRequest instead", + fieldSpec+", D12"), + { + ID: "E-ReadyRequest.Brief", Kind: KindRetired, + What: "RETIRED — the ready listing SENDS the projection; only the count still drops it", + Why: briefRetiredWhy, + SpecRow: dropSpec, + PinnedBy: dropPin, + }, + { + // The count's half of the retired row above, and it is a separate + // row rather than a narrowing of that one because the two answer + // different operations: countReadyWork publishes no `brief` at all, + // so its drop survives the parameter that retired the listing's. + ID: "E-ReadyRequest.Brief@countReadyWork", Kind: KindDegrade, + Type: tyReadyRequest, Field: "Brief", + What: "the free-form-text projection is DROPPED on the COUNT, not refused: a cardinality has no rows to project", + Why: briefCountDropWhy, + SpecRow: dropSpec, + PinnedBy: dropPin, + }, + { + ID: "E-ReadyRequest.Limit@countReadyWork", Kind: KindRefuse, + Type: tyReadyRequest, Field: "Limit", + What: "a Limit on a ready COUNT refuses", + Why: "countReadyWork publishes no limit parameter and ReadyCounter.CountReady refuses one itself: a cardinality has no page, and CountReady's identity with the listing it sizes stops being true the moment one is accepted. " + + "An explicit zero is refused with the rest — an unlimited count is the only kind there is", + SpecRow: fieldSpec + ", D8 row 2", + PinnedBy: fieldPin, + }, + } +} + +// listRequestRows are the listing vocabulary's inexpressible members. It is the +// longest population in the ledger, and deliberately so: `bd list` publishes +// far more filters than the v0 listing does, and every one of them is a set +// this client would widen if it dropped it. +func listRequestRows() []Row { + listRefusal := func(field, what, why string) Row { + return refusal("E-ListRequest."+field, tyListRequest, field, what, why, fieldSpec) + } + rows := []Row{ + listRefusal("TitleSearch", "a title search refuses", noWireList), + listRefusal("SpecPrefix", "a spec-id prefix restriction refuses", noWireList), + listRefusal("IDFilter", "an explicit id set on the LISTING refuses", + noWireList+"; the exact-ids question is getIssue's, reached through the SearchIssues bridge's exact-ids shape (D11), not through a listing filter"), + listRefusal("LabelPattern", "a glob label filter refuses", + noWireList+" — listReadyWork does publish label_pattern, which is exactly why the absence here has to refuse rather than fall through"), + listRefusal("LabelRegex", "a regex label filter refuses", + noWireList+" — as for LabelPattern, listReadyWork publishes label_regex and the listing does not"), + listRefusal("TitleContains", "a title substring filter refuses", noWireList), + listRefusal("DescContains", "a description substring filter refuses", noWireList), + listRefusal("NotesContains", "a notes substring filter refuses", noWireList), + listRefusal("ExternalContains", "an external-ref substring filter refuses", noWireList), + listRefusal("ExternalRef", "an exact external-ref filter refuses", noWireList), + listRefusal("UpdatedAfter", "an updated-after bound refuses", noWireList+" — only the created bounds are published"), + listRefusal("UpdatedBefore", "an updated-before bound refuses", noWireList+" — only the created bounds are published"), + listRefusal("ClosedAfter", "a closed-after bound refuses", noWireList), + listRefusal("ClosedBefore", "a closed-before bound refuses", noWireList), + listRefusal("DeferAfter", "a defer-after bound refuses", noWireList), + listRefusal("DeferBefore", "a defer-before bound refuses", noWireList), + listRefusal("DueAfter", "a due-after bound refuses", noWireList), + listRefusal("DueBefore", "a due-before bound refuses", noWireList), + listRefusal("EmptyDesc", "the empty-description predicate refuses", noWireList), + listRefusal("NoAssignee", "the unassigned predicate refuses", + noWireList+" — listReadyWork publishes `unassigned`; the listing does not"), + listRefusal("NoLabels", "the no-labels predicate refuses", noWireList), + listRefusal("Priority", "an exact priority filter refuses", + noWireList+" — listReadyWork publishes `priority`; the listing does not"), + listRefusal("PriorityMin", "a minimum-priority bound refuses", noWireList), + listRefusal("PriorityMax", "a maximum-priority bound refuses", noWireList), + listRefusal("PinnedFlag", "selecting the pinned-FLAG rows refuses", + noWireList+". The pinned STATUS is reachable through `status`; the flag is a separate predicate at any status and has no parameter"), + listRefusal("NoPinnedFlag", "holding the unflagged predicate in place refuses", + noWireList+". It changes nothing on a default listing and NARROWS under `all` or a pinned/hooked status — which is precisely when dropping it would widen the answer"), + listRefusal("ExcludeTypes", "a type exclusion refuses", + noWireList+" — listReadyWork publishes exclude_type; the listing publishes only the four include_* toggles"), + listRefusal("NoParent", "the top-level-only predicate refuses", noWireList), + listRefusal("MolType", "a molecule-type restriction refuses", noWireList), + listRefusal("WispType", "a wisp-type restriction refuses", + noWireList+". The listing now ADMITS the wisp plane — include_ephemeral landed upstream and the encoder sends it (L1 retired) — so this refusal is no longer redundant with an invisible plane: it is the only thing standing between a caller and a listing that returns every wisp type when they named one"), + listRefusal("DeferredFlag", "the deferred predicate refuses", noWireList), + listRefusal("OverdueFlag", "the overdue predicate refuses", noWireList), + listRefusal("ReadyFlag", "switching a listing onto the ready set refuses", + "ReadyFlag is not a filter but a change of QUESTION: it selects the blocker-aware ready query, which reads a narrower filter vocabulary than a ListRequest can describe. Over the wire that question is listReadyWork, a different operation with a different parameter table. "+ + "Routing it there would have to decide, silently, which of this request's fields survive the crossing — so v1 refuses and the retirement path is an explicit route in the store, not a re-encode here"), + listRefusal("IncludeComments", "hydrating every row's comment bodies refuses", + noWireList+". listIssues documents `comments` as always absent on its rows; a caller that needs an issue's comments reads getIssue with include_comments, one issue at a time"), + listRefusal("Offset", "a non-zero Offset refuses", + noWireList+". The portable page is the keyset position, which the pager walks (D8 row 1); the store-backed role refuses a non-zero Offset itself"), + } + return append(rows, + Row{ + ID: "E-ListRequest.SkipLabels", Kind: KindDegrade, + Type: tyListRequest, Field: "SkipLabels", + What: "the label-hydration opt-out is DROPPED, not refused: the wire hydrates labels either way", + Why: "the listing publishes no hydration parameter, so the client cannot ask the server to skip the labels JOIN. Dropping it hands the caller MORE data than it asked for and never fewer — the row set, its order, Parent and the has-more verdict are exactly what they would have been — so it cannot be misread as a narrower or wider answer. " + + "It is a degradation rather than a refusal because refusing would make `bd list --skip-labels` a hard error for a performance flag whose only observable effect over http is that the server pays for a join. The retirement path is a hydration parameter on the wire", + SpecRow: dropSpec, + PinnedBy: dropPin, + }, + Row{ + ID: "E-ListRequest.Brief", Kind: KindRetired, + What: "RETIRED — `bd list` over http sends the projection", + Why: briefRetiredWhy, + SpecRow: dropSpec, + PinnedBy: dropPin, + }, + Row{ + ID: "E-ListRequest.IncludeAllTypes", Kind: KindRefuse, + Type: tyListRequest, Field: "IncludeAllTypes", + What: "the never-hide-a-bead intent refuses", + Why: "it is the UNION of four intents the wire does publish — include_templates, include_gates, include_infra, include_ephemeral — and encoding it as those four would be a client-side restatement of a union whose whole point is that a FIFTH suppression added to workapi is lifted by it automatically. " + + "The day that fifth lands, the restatement silently stops lifting it and the listing hides beads from a caller whose contract is that it hides none. Dropping it narrows the answer for the same reason, so it refuses until the wire publishes the intent itself", + SpecRow: fieldSpec, + PinnedBy: fieldPin, + }, + Row{ + ID: "E-ListRequest.SkipCounts", Kind: KindDegrade, + Type: tyListRequest, Field: "SkipCounts", + What: "the cardinality-hydration opt-out is DROPPED, not refused: the wire hydrates the three counts either way", + Why: "the same reasoning as SkipLabels, and here refusing would be actively wrong: EVERY text rendering of `bd list` sets SkipCounts (cmd/bd/list.go:284, and its proxied twin), so a refusal would kill the default listing over http. " + + "Dropping it means real counts arrive where zeros were expected, and a caller that must read a zero as UNKNOWN is safe reading a true count. The cost is the three aggregate joins — including the reverse-blocker one the embedded planner cannot index — paid on a page that prints none of them", + SpecRow: dropSpec, + PinnedBy: dropPin, + }, + ) +} + +// queryRequestRows: the boolean-query surface publishes almost its whole +// vocabulary, so there is one member left over. +func queryRequestRows() []Row { + return []Row{ + refusal("E-QueryRequest.Offset", tyQueryRequest, "Offset", + "a non-zero Offset on a boolean query refuses", + "queryIssues publishes no offset parameter — the document deliberately omits one, because the two database sources this server can be built on disagree about whether they can honor it — and the store-backed role refuses one uniformly", + fieldSpec), + } +} + +// bridgeWhy is the SearchIssues bridge's whole rule, written once. Every field +// row below is an instance of it. +const bridgeWhy = "the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=. " + + "Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses" + +// issueFilterRows classify every member of types.IssueFilter against the +// SearchIssues bridge. +// +// The three fields the bridge DOES read — IDs, ParentID and Limit — still get +// rows, because each is refused in the shape it does not belong to: an IDs set +// alongside a ParentID is neither shape, and a ParentID or a Limit alongside an +// exact-ids lookup is a filter getIssue cannot apply. +func issueFilterRows() []Row { + bridgeRefusal := func(field string) Row { + return refusal("E-IssueFilter."+field, tyIssueFilter, field, + "a populated IssueFilter."+field+" refuses on the SearchIssues bridge", bridgeWhy, + "D8 (off-role raw methods), D4, D11, D9 L12") + } + rows := make([]Row, 0, len(issueFilterBridgeRefusals)+4) + for _, field := range issueFilterBridgeRefusals { + rows = append(rows, bridgeRefusal(field)) + } + return append(rows, + Row{ + // No Type/Field: this row is about a PAIR of fields, and pinning it + // to either one would make the refusal read as if the other were + // fine on its own. + ID: "E-IssueFilter.shapeConflict", Kind: KindRefuse, + What: "an id set and a ParentID together refuse — the pair is NEITHER expressible shape", + Why: "the exact-ids shape dials getIssue per id and applies no filter at all, so honoring the parent restriction would mean discarding answers client-side; the descendant walk dials listIssues?parent=, which publishes no id filter, so honoring the ids would mean intersecting two answers no single wire call asked for. " + + "Both readings are drops wearing a filter's clothes, so the combination refuses before a shape is chosen", + SpecRow: "D4, D11, D9 L12", + PinnedBy: "TestASearchFilterMatchingNeitherShapeRefuses", + }, + refusal("E-IssueFilter.Limit@exactIDs", tyIssueFilter, "Limit", + "a Limit alongside an id set refuses", + "getIssue answers one row per call, so a Limit could only be applied by discarding answers the caller named explicitly", + "D11"), + Row{ + ID: "E-IssueFilter.IDs@bound", Kind: KindRefuse, + Type: tyIssueFilter, Field: "IDs", + What: "an id set larger than MaxExactIDs refuses", + Why: "the exact-ids shape costs one getIssue per id, so an unbounded set is an unbounded burst at one shared server. The bound is 100 and is a GUESS: open question 6 asks for the real call-site fan-out to be measured before GA", + SpecRow: "D11, open question 6", + PinnedBy: "TestTheExactIDsFanOutIsBounded", + }, + Row{ + ID: "E-IssueFilter.noShape", Kind: KindRefuse, + What: "a raw SearchIssues call matching neither expressible shape refuses", + Why: bridgeWhy + ". A filter naming no ids and no parent — the unbounded `everything` shape included — is not one of them", + SpecRow: "D8 (off-role raw methods), D4, D11, D9 L12", + PinnedBy: "TestASearchFilterMatchingNeitherShapeRefuses", + }, + Row{ + ID: "E-bridge-parent-shape", Kind: KindRetired, + What: "RETIRED — the ParentID-only shape was unreachable from `bd list --parent` as the CLI builds it, and the walk refused over http", + Why: "the escalation this row raised (ga-2ieek) was resolved by spec revision 6b428bf63 as semantic inversion: the wire publishes INTENTS (`all`, `include_templates`, `include_gates`, `include_infra`) rather than materialized exclusions, and the server's role re-derives the exclusions from the same builder against its own authoritative vocabulary. " + + "The bridge therefore inverts the derived members back to intents instead of encoding them, and the objection recorded here — that recognizing the baseline would be an unsanctioned second encoder — is answered by VERIFYING each candidate through workapi.BuildListFilter itself rather than reimplementing it. The live rules are the P-IssueFilter.* population", + SpecRow: "D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek", + PinnedBy: "TestTheParentWalkInvertsTheDerivedDefaults", + }, + ) +} + +// parentWalkRows classify types.IssueFilter against D4's descendant walk, which +// reads the SAME struct as the exact-ids shape and reads it differently. +// +// Three populations, and the split is the whole content of the ga-2ieek +// resolution: +// +// - the six DERIVED DEFAULTS workapi.BuildListFilter populates from the +// intent flags. A value the same builder would have derived for the intents +// being sent is accounted for and sends nothing; every other value refuses +// here. These are the rows the inversion raises by id; +// - the four members the walk carries that decide nothing, DROPPED with the +// argument that says why the difference cannot be read as a narrower or +// wider answer; +// - everything else, refused exactly as it is on the other shape — the walk +// just reaches it from a filter that has more populated than an id lookup +// ever does. +const parentWalkSpec = "D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek" + +func parentWalkRows() []Row { + const pin = "TestTheParentWalkInvertsTheDerivedDefaults" + derived := func(field, what, why string) Row { + return Row{ + ID: "P-IssueFilter." + field, Kind: KindRefuse, + Type: tyIssueFilter, Field: field, + What: what, Why: why, SpecRow: parentWalkSpec, PinnedBy: pin, + } + } + walkRefusal := func(field string) Row { + return Row{ + ID: "P-IssueFilter." + field, Kind: KindRefuse, + Type: tyIssueFilter, Field: field, + What: "a populated IssueFilter." + field + " refuses on the descendant walk", + Why: "listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. " + + "Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly", + SpecRow: parentWalkSpec, PinnedBy: pin, + } + } + drop := func(field, what, why string) Row { + return Row{ + ID: "P-IssueFilter." + field, Kind: KindDegrade, + Type: tyIssueFilter, Field: field, + What: what, Why: why, SpecRow: parentWalkSpec + ", D9", PinnedBy: pin, + } + } + + rows := []Row{ + derived("ExcludeStatus", "a status exclusion that is not the derived default refuses", + "listIssues publishes no exclude_status: the wire publishes the INTENT (`all`) and the server re-derives the exclusions from the same builder against its own authoritative vocabulary, which additionally heals L7's degraded client-side set for the walk. "+ + "An exclusion list no intent reproduces is therefore unstatable, and dropping it would widen the listing to closed work"), + derived("Pinned", "a pinned predicate that is not the derived default refuses", + "the pinned default is the FOURTH derived member and has no parameter of its own: `--pinned` selects the flagged rows and `--no-pinned` holds the unflagged predicate in place under `--all`, and the wire can express neither. "+ + "Its derived value is a function of the `all` intent alone — upstream #5333 stopped an every-status selector from forcing it, so `--status all` and `--all` are now one filter and one wire question — and a value that intent does not reproduce is a user's own predicate, which NARROWS, and that is precisely when dropping it would answer a different question"), + derived("IsTemplate", "a template predicate that is not the derived default refuses", + "listIssues publishes include_templates, an intent, not an is_template predicate. `&false` is what the absent flag derives and sends nothing; nil is what `--include-templates` derives and sends the flag; `&true` selects templates ONLY, which no intent on this operation can say"), + derived("ExcludeTypes", "a type exclusion beyond the derived gate and infra members refuses", + "listIssues publishes include_gates and include_infra — intents — and no exclude_type. The gate member and the whole infra vocabulary are what their absent flags derive; a leftover member is a user's `--exclude-type`, and dropping it would return the type they asked to hide"), + derived("Ephemeral", "an ephemeral predicate that is not the derived default refuses", + "BuildListFilter sets it only for an infra `--type`, from the same flag the walk already encodes; the wire publishes no ephemeral PREDICATE on the listing — include_ephemeral is an intent that ADMITS the plane, not a selector that restricts to it — so any other value is unstatable"), + derived("SkipWisps", "a wisp-merge opt-out that is not the derived default refuses", + "NARROWED by client wave ga-mijra, which closed the client-side gap this row used to record. The walk now encodes include_ephemeral — SkipWisps going false IS that intent, and it is read back off the member the way every other derived default is — so a wisp-inclusive descendant listing crosses instead of refusing, which is the shape gc's TierBoth reads take. "+ + "What still refuses is a SkipWisps no set of intents reproduces: holding the plane out while include_infra or an infra `--type` admits it. BuildListFilter never builds that pair, so it is a hand-made filter rather than a flag combination, and dropping the opt-out would merge a plane the caller asked to skip"), + drop("SortBy", "the walk's sort key is DROPPED", + "findAllDescendants accumulates every level into a map keyed by id, so no per-level order reaches the answer: the walk's own assembly discards it before the caller sees it. This is a drop with nothing to drop, and the rendering order is the tree renderer's"), + drop("SortDesc", "the walk's sort direction is DROPPED", + "the other half of the order findAllDescendants discards; see P-IssueFilter.SortBy"), + drop("SkipLabels", "the label-hydration opt-out is DROPPED", + "the listing publishes no hydration parameter, so the client cannot ask the server to skip the labels join. Dropping it hands the caller MORE data and never fewer rows, so it cannot be misread as a narrower or wider answer"), + drop("SkipCounts", "the cardinality-hydration opt-out is DROPPED", + "the same absence as SkipLabels, and here refusing would be actively wrong: every text rendering of `bd list` sets it, so a refusal would kill the walk's DEFAULT rendering — the one behavior D4 classifies the walk as served in order to keep"), + } + + for _, field := range parentWalkRefusals { + rows = append(rows, walkRefusal(field)) + } + return append(rows, Row{ + // No Type/Field: this row is about the whole recognition failing, not + // about one member. It fires when the builder rejects every candidate + // intent, which means the filter names vocabulary this client cannot + // reproduce at all. + ID: "P-IssueFilter.unrecognized", Kind: KindRefuse, + What: "a descendant-walk filter whose intents this client cannot reproduce at all refuses", + Why: "the inversion proves a candidate by RE-RUNNING workapi.BuildListFilter and comparing the derived members, so a candidate the builder itself rejects — an unknown status, a vocabulary the client's degraded copy does not carry (L7) — is never compared. " + + "When every candidate is rejected that way there is no member to blame, and refusing on the recognition is the only honest answer", + SpecRow: parentWalkSpec + ", D9 L7", + PinnedBy: pin, + }) +} + +// parentWalkRefusals enumerates the IssueFilter members that refuse on the +// descendant walk: everything BuildListFilter can carry that is neither a +// derived default nor a filter listIssues publishes. +// +// Written out rather than derived, for the reason issueFilterBridgeRefusals is: +// a list computed from the struct would absorb a field added upstream, and the +// bijection gate exists to catch exactly that arrival. +var parentWalkRefusals = []string{ + "Priority", "LabelPattern", "LabelRegex", + "TitleSearch", "IDPrefix", "SpecIDPrefix", + "TitleContains", "DescriptionContains", "NotesContains", "ExternalRefContains", "ExternalRef", + "UpdatedAfter", "UpdatedBefore", "ClosedAfter", "ClosedBefore", "StartedAfter", "StartedBefore", + "AfterCreatedAt", "AfterID", "AfterPriority", + "EmptyDescription", "NoAssignee", "NoLabels", "PriorityMin", "PriorityMax", + "SourceRepo", "EphemeralTier", "IsBlocked", "NoParent", "MolType", "WispType", + "Deferred", "DeferAfter", "DeferBefore", "DueAfter", "DueBefore", "Overdue", + "IncludeDependencies", "NoIDShrink", "Offset", "Lite", +} + +// issueFilterBridgeRefusals enumerates the IssueFilter members that refuse in +// BOTH bridge shapes, in declaration order. +// +// It is written out rather than reflected FROM types.IssueFilter on purpose: a +// list derived from the struct would silently absorb a field added upstream, +// which is the one event this whole gate exists to catch. Both the ledger and +// the encoder tables read this one enumeration, so the two cannot disagree. +var issueFilterBridgeRefusals = []string{ + "Status", "Statuses", "Priority", "IssueType", "Assignee", + "Labels", "LabelsAny", "ExcludeLabels", "LabelPattern", "LabelRegex", + "TitleSearch", "IDPrefix", "SpecIDPrefix", + "TitleContains", "DescriptionContains", "NotesContains", "ExternalRefContains", "ExternalRef", + "CreatedAfter", "CreatedBefore", "UpdatedAfter", "UpdatedBefore", + "ClosedAfter", "ClosedBefore", "StartedAfter", "StartedBefore", + "AfterCreatedAt", "AfterID", "AfterPriority", + "EmptyDescription", "NoAssignee", "NoLabels", "PriorityMin", "PriorityMax", + "SourceRepo", "Ephemeral", "EphemeralTier", "Pinned", "IsBlocked", "IsTemplate", + "NoParent", "MolType", "WispType", "ExcludeStatus", "ExcludeTypes", + "Deferred", "DeferAfter", "DeferBefore", "DueAfter", "DueBefore", "Overdue", + "MetadataFields", "HasMetadataKey", + "IncludeDependencies", "SkipLabels", "SkipCounts", "SkipWisps", "NoIDShrink", + "Offset", "SortBy", "SortDesc", "MaxRows", "MaxRowsSource", "Lite", +} + +// workFilterRows classify types.WorkFilter against the reverse ready bridge. +// +// The bridge exists because `bd ready`'s listing is still raw at tip, so the +// client has to map a WorkFilter back onto ready parameters until the front +// door moves onto issueops.Reader. It is deliberately throwaway; what is not +// throwaway is that it refuses every field it cannot express (L12). +func workFilterRows() []Row { + bridge := func(field, what, why string) Row { + return refusal("E-WorkFilter."+field, tyWorkFilter, field, what, why, + "D8 (off-role ready bridge), D9 L12") + } + return []Row{ + { + // The one DEGRADE on this bridge, and it is here rather than among + // the refusals because it is not a filter: it is the same free-form + // text projection ReadyRequest.Brief carries, reached from the + // legacy shape. WorkFilter.Lite IS ReadyRequest.Brief — workapi + // assigns one to the other — so the two dispositions have to agree + // or the same request answers differently depending on which door + // it came in. + ID: "E-WorkFilter.Lite", Kind: KindRetired, + What: "RETIRED — the ready bridge maps Lite onto `brief`, the same parameter ReadyRequest.Brief now sends", + Why: briefRetiredWhy, + SpecRow: dropSpec, + PinnedBy: dropPin, + }, + { + // A DERIVED DEFAULT, not a flat refusal (D4's parent-walk inversion, + // applied here): the one value the server re-derives drops, every + // other refuses. KindRefuse because the disposition is DispInverted, + // which the encoder drives exactly as a refusal — its sentinel value + // is by construction not the derived one. + ID: "E-WorkFilter.Status", Kind: KindRefuse, + Type: tyWorkFilter, Field: "Status", + What: "a ready-work status that is not the derived default refuses; the default (open only) is DERIVED server-side and drops", + Why: "listReadyWork publishes no status parameter: handleReady decodes a status-LESS request and the server re-derives ready work's status through workapi.BuildReadyFilter, which is unconditionally StatusOpen — open work only, the set `bd list --ready` shows. The client sends that one derived value as the absence the server reads it back from, so every real `bd ready` and `bd ready --json` (whose filter BuildReadyFilter always stamps StatusOpen) round-trips to the identical rows. Any other status is unstatable and refuses: a named status would answer over the query's open-only default rather than the set named, and the empty status is the storage layer's own open+in_progress default, which this operation cannot express either", + SpecRow: "D8 (off-role ready bridge), D9 L12, D4 (derived-default inversion, escalation ga-2ieek)", + PinnedBy: fieldPin, + }, + bridge("Statuses", "a multi-status OR set on ready work refuses", + "listReadyWork publishes no status parameter, and an OR-set is neither the server's derived default (open only) nor anything the wire can carry — dropping it would widen the answer to statuses the caller did not ask for, so it refuses alongside a non-default Status (L12)"), + bridge("MoleculeID", "restricting ready work to one molecule's direct children refuses", + "listReadyWork publishes `parent` for the RECURSIVE descendant restriction and nothing for direct membership; the two are different sets, so `parent` is not a substitute"), + bridge("MolType", "a molecule-type restriction on ready work refuses", + "no wire parameter — the same absence E-ReadyRequest.MolType records, reached from the other source shape"), + bridge("WispType", "a wisp-type restriction on ready work refuses", + "listReadyWork publishes include_ephemeral, which admits the wisp plane wholesale, and nothing that selects a wisp TYPE within it"), + bridge("ExcludeIDs", "an id exclusion set on ready work refuses", + "listReadyWork publishes no id-exclusion parameter; the set is what the external-dependency policy decorator (upstream #4753) injects to hide sources behind unsatisfied external blockers, and dropping it would widen the answer to exactly the issues the caller's policy excluded (L12). A server that advertises policy.external_dependencies applies the policy itself, so the client never builds the set for it"), + bridge("Offset", "a non-zero Offset on ready work refuses", + "no wire parameter, and ready work carries no keyset position to page by; see E-ReadyRequest.Offset"), + } +} diff --git a/internal/httpclient/encode/ledger_render.go b/internal/httpclient/encode/ledger_render.go new file mode 100644 index 000000000..e1416c825 --- /dev/null +++ b/internal/httpclient/encode/ledger_render.go @@ -0,0 +1,216 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/ledger_render.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "fmt" + "strings" +) + +// RenderLedgerMarkdown renders divergence ledger v1 as the human-readable +// shipped artifact engdocs/design/http-divergence-ledger.md. +// +// It reads Ledger() — the same machine-checked source the encoder consults and +// the bijection gate holds honest — so the doc cannot enumerate a divergence +// the client does not, nor omit one it does. A golden test regenerates this +// output and fails CI if the committed doc drifts from the source, which is the +// second half of the anti-drift chain: the bijection gate pins the ledger to +// the wire, and the golden test pins this doc to the ledger. +// +// Every row in Ledger() lands in exactly one section here; a row whose id +// matches no known population still renders, in the trailing "Other +// divergences" section, so a new population is loud rather than dropped. +func RenderLedgerMarkdown() string { + rows := Ledger() + + sections := []struct { + title string + blurb string + matches func(id string) bool + }{ + { + "Whole-behavior divergences (D9 ledger)", + "The L-rows the design's D9 table names: whole behaviors that differ over HTTP, each degraded knowingly or refused outright. Retired rows stay so the L-numbers every citation uses keep resolving.", + func(id string) bool { return strings.HasPrefix(id, "L") }, + }, + { + "Write-side refuse-not-drop (D8)", + "Role-request fields on the served writes that the v0 wire publishes no member for. Each refuses rather than forwarding a write shorn of the field — a silently dropped precondition or flag would widen what the write touches.", + func(id string) bool { return strings.HasPrefix(id, "W-") }, + }, + { + "Command and flag refusals (D7)", + "Whole commands, and the flag modes of served commands, that dispatch onto methods the wire does not carry. They refuse early — before RunE — in the user's own command/flag vocabulary.", + func(id string) bool { return strings.HasPrefix(id, "F-") }, + }, + { + "Ready-request fields", + "Members of the ready vocabulary the wire cannot express.", + func(id string) bool { return strings.HasPrefix(id, "E-ReadyRequest") }, + }, + { + "List-request fields", + "The listing publishes far more filters than the v0 wire does; every one the wire lacks refuses rather than dropping, because a dropped list filter widens the page invisibly. Two hydration opt-outs are dropped instead, with the argument for why that cannot be misread as a narrower or wider answer.", + func(id string) bool { return strings.HasPrefix(id, "E-ListRequest") }, + }, + { + "Query-request fields", + "The boolean-query surface publishes almost its whole vocabulary; this is what is left over.", + func(id string) bool { return strings.HasPrefix(id, "E-QueryRequest") }, + }, + { + "Search bridge / IssueFilter (D4, D11)", + "The off-role SearchIssues bridge serves two shapes and no others: the exact-ids fast path and the parent descendant walk. Every other populated IssueFilter member is a filter the bridge would have to drop to answer, so it refuses.", + func(id string) bool { + return strings.HasPrefix(id, "E-IssueFilter") || strings.HasPrefix(id, "E-bridge") + }, + }, + { + "Parent-walk derived defaults (D4)", + "The descendant walk reads the same IssueFilter as the exact-ids shape and reads it differently. The wire publishes intents (all, include_templates, include_gates, include_infra) and the server re-derives the exclusions; the bridge inverts the derived defaults back to intents and refuses anything the inversion cannot account for.", + func(id string) bool { return strings.HasPrefix(id, "P-") }, + }, + { + "Ready bridge / WorkFilter (D8)", + "The throwaway bridge that maps a WorkFilter back onto ready parameters until the front door moves onto issueops.Reader. It refuses every field it cannot express.", + func(id string) bool { return strings.HasPrefix(id, "E-WorkFilter") }, + }, + } + + assigned := make([]bool, len(rows)) + var b strings.Builder + + fmt.Fprint(&b, ledgerDocPreamble) + + var refuse, degrade, retired int + for _, r := range rows { + switch r.Kind { + case KindRefuse: + refuse++ + case KindDegrade: + degrade++ + case KindRetired: + retired++ + } + } + fmt.Fprintf(&b, "## Summary\n\n") + fmt.Fprintf(&b, "%d rows: %d refuse, %d degrade, %d retired.\n\n", + len(rows), refuse, degrade, retired) + + writeSection := func(title, blurb string, idxs []int) { + fmt.Fprintf(&b, "## %s\n\n", title) + if blurb != "" { + fmt.Fprintf(&b, "%s\n\n", blurb) + } + fmt.Fprint(&b, "| ID | Kind | Field / flag | Divergence | Why | Spec | Pinned test |\n") + fmt.Fprint(&b, "|---|---|---|---|---|---|---|\n") + for _, i := range idxs { + r := rows[i] + fmt.Fprintf(&b, "| %s | %s | %s | %s | %s | %s | %s |\n", + cell(r.ID), cell(string(r.Kind)), fieldFlag(r), + cell(r.What), cell(r.Why), cell(r.SpecRow), cell(r.PinnedBy)) + } + fmt.Fprint(&b, "\n") + } + + for _, s := range sections { + var idxs []int + for i, r := range rows { + if !assigned[i] && s.matches(r.ID) { + assigned[i] = true + idxs = append(idxs, i) + } + } + if len(idxs) > 0 { + writeSection(s.title, s.blurb, idxs) + } + } + + var leftover []int + for i := range rows { + if !assigned[i] { + leftover = append(leftover, i) + } + } + if len(leftover) > 0 { + writeSection("Other divergences", + "Rows whose id matched no known population. A new one here means RenderLedgerMarkdown needs a section for it.", + leftover) + } + + return b.String() +} + +// fieldFlag renders the Go request field and the user's flag spelling a row +// carries, as inline code; "—" when the row describes a behavior with neither. +func fieldFlag(r Row) string { + var parts []string + if r.Type != nil { + parts = append(parts, "`"+r.Type.Name()+"."+r.Field+"`") + } + if r.Flag != "" { + parts = append(parts, "`"+r.Flag+"`") + } + if len(parts) == 0 { + return "—" + } + return strings.Join(parts, " ") +} + +// cell makes an arbitrary ledger string safe for one Markdown table cell: +// pipes are escaped so they do not read as column breaks, and every run of +// whitespace (the Why strings are built by concatenation and can carry +// newlines) collapses to a single space. +func cell(s string) string { + s = strings.ReplaceAll(s, "|", "\\|") + return strings.Join(strings.Fields(s), " ") +} + +const ledgerDocPreamble = ` + + + +# bd HTTP mode — the divergence ledger + +This is the shipped, human-readable rendering of divergence ledger v1: every +place ` + "`bd`" + `'s HTTP client mode observably differs from local (embedded/served) +mode, each with its reason and the test that pins it. + +The discipline (design decision D9) is empty-by-default and test-asserted: +**every knowingly-degraded behavior is a ledger row with a pinned test, and a +degradation not in this table is a bug.** ` + "`refuse`" + ` rows fail rather than +proceeding — a dropped filter widens a result set invisibly, the one failure +class no server-side gate can observe — while ` + "`degrade`" + ` rows proceed with a +difference argued to be unmisreadable as a narrower or wider answer than the +caller asked for. + +This file is generated from ` + "`internal/httpclient/encode`" + `'s +` + "`Ledger()`" + `, the machine-readable source the client actually consults. Do not +hand-edit it: change the ledger in Go and regenerate. Two gates keep it honest — +the encoder's reflection **bijection gate** pins the ledger to the wire (a +request field added upstream lands here or fails CI), and the golden test +` + "`TestDivergenceLedgerDocMatchesLedger`" + ` pins this doc to the ledger. The prose +rationale, the decision numbers (D-rows) each entry cites, and the full test-lane +map live in the architecture spec, ` + "`http-client-backend.md`" + `, which is not +included in this repository. + +A handful of rows still carry a ` + "`TODO`" + ` pin: these are the read-display and +pre-run residuals (wisp-in-list, the pretty ` + "`bd ready`" + ` parent-epic map, the +molecule/auto-import pre-run degradations). The +client core is complete; ` + "`ga-b8ddd.12`" + ` (per-request project-id enforcement) +closed the read-display escalation, so pinning the remaining fixture corpus is +deferred work, tracked on ` + "`ga-b8ddd.23`" + ` (the read-display residual) +and ` + "`ga-b8ddd.19`" + ` (the per-id D7 taxonomy). They are refusals or degradations +already in force — the ` + "`TODO`" + ` is on the test that will hold each one, not on +the behavior. + +## Kind + +- **refuse** — the operation fails; the wire cannot express what was asked and + proceeding would silently widen or narrow the answer. +- **degrade** — the operation proceeds with a knowingly different behavior that + cannot be misread as a different answer to the question asked. +- **retired** — a row a later council removed; kept so its L-number keeps + resolving and a re-enumeration can tell "retired" from "never existed". + +` diff --git a/internal/httpclient/encode/ledger_render_test.go b/internal/httpclient/encode/ledger_render_test.go new file mode 100644 index 000000000..f66b1886b --- /dev/null +++ b/internal/httpclient/encode/ledger_render_test.go @@ -0,0 +1,54 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/ledger_render_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "flag" + "os" + "path/filepath" + "testing" +) + +//go:generate go test . -run TestDivergenceLedgerDocMatchesLedger -update-ledger-doc + +var updateLedgerDoc = flag.Bool("update-ledger-doc", false, + "rewrite engdocs/design/http-divergence-ledger.md from the ledger instead of comparing") + +// ledgerDocPath is the shipped artifact, relative to this package directory: +// internal/httpclient/encode -> repo root is three levels up. +var ledgerDocPath = filepath.Join("..", "..", "..", + "engdocs", "design", "http-divergence-ledger.md") + +// TestDivergenceLedgerDocMatchesLedger is the anti-drift half of the ledger's +// well-formedness chain. The bijection gate holds Ledger() honest against the +// wire; this holds the shipped doc honest against Ledger(), so the doc cannot +// describe a divergence set the client does not implement. +// +// It runs in the default (untagged) PR-Core lane with the rest of this package, +// so a ledger edit that forgets to regenerate the doc fails CI on every PR. +// Regenerate with -update-ledger-doc (or go generate ./...). +func TestDivergenceLedgerDocMatchesLedger(t *testing.T) { + want := RenderLedgerMarkdown() + + if *updateLedgerDoc { + if err := os.WriteFile(ledgerDocPath, []byte(want), 0o644); err != nil { + t.Fatalf("writing %s: %v", ledgerDocPath, err) + } + t.Logf("regenerated %s", ledgerDocPath) + return + } + + got, err := os.ReadFile(ledgerDocPath) + if err != nil { + t.Fatalf("reading %s: %v\nregenerate with: go test ./internal/httpclient/encode -run %s -update-ledger-doc", + ledgerDocPath, err, t.Name()) + } + + if string(got) != want { + t.Fatalf("engdocs/design/http-divergence-ledger.md is stale: it no longer matches the ledger in encode.Ledger().\n"+ + "The shipped divergence ledger is generated from source and must not be hand-edited.\n"+ + "Regenerate it with:\n"+ + " go test ./internal/httpclient/encode -run %s -update-ledger-doc\n"+ + "(or: go generate ./internal/httpclient/encode)", t.Name()) + } +} diff --git a/internal/httpclient/encode/oracle_test.go b/internal/httpclient/encode/oracle_test.go new file mode 100644 index 000000000..e50e06dc7 --- /dev/null +++ b/internal/httpclient/encode/oracle_test.go @@ -0,0 +1,281 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/oracle_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "context" + "io" + "net/http" + "net/url" + "sync" + "testing" + + "github.com/steveyegge/beads/internal/httpapi" + "github.com/steveyegge/beads/issueops" + "github.com/steveyegge/beads/memoryops" +) + +// The oracle: a real bd serve, bound to loopback, answering from roles that +// record the request the PRODUCTION decoder built and nothing else. +// +// A real server rather than a call into the decoding helpers, because the +// helpers are unexported and — more to the point — because the properties this +// gate needs are the SERVER's, not a function's: the route table has to accept +// the path, the Host policy has to admit the request, and the +// unknown-parameter rule has to run. A parameter this client sends that the +// operation does not publish is a 400 from that rule, and the 400 is half the +// assertion. +// +// The WHOLE role set because httpapi.Listen requires it rather than a partial +// one — a Config missing one role would bind, answer every other route, and fail +// that one with a nil dereference on a live server. Four of them record and the +// rest are interface stubs this surface never dials, and a stub that IS dialed +// by accident panics rather than answering, which is the loud failure a nil +// would not have been. + +type oracle struct { + base string + + mu sync.Mutex + ready issueops.ReadyRequest + list issueops.ListRequest + get issueops.GetRequest + count issueops.ReadyRequest + query issueops.QueryRequest + issueCount issueops.CountRequest + issueGroup issueops.CountByGroupRequest + visited map[string]bool +} + +func startOracle(t *testing.T) *oracle { + t.Helper() + o := &oracle{visited: map[string]bool{}} + + srv, err := httpapi.Listen(httpapi.Config{ + Addr: "127.0.0.1:0", + Stdout: io.Discard, + Stderr: io.Discard, + + Reader: recordingReader{o}, + ReadyCounter: recordingCounter{o}, + Querier: recordingQuerier{o}, + Counter: recordingIssueCounter{o}, + + Claimer: stubClaimer{}, + ReadyClaimer: stubReadyClaimer{}, + Releaser: stubReleaser{}, + Lifecycle: stubLifecycle{}, + Settings: stubSettings{}, + Stats: stubStats{}, + CycleDetector: stubCycles{}, + EdgeReader: stubEdges{}, + GraphCounter: stubGraphCounter{}, + Relations: stubRelations{}, + Commenter: stubCommenter{}, + BlockingAnnotator: stubBlocking{}, + TreeWalker: stubTree{}, + Sweeper: stubSweeper{}, + Deleter: stubDeleter{}, + BatchCreator: stubBatchCreator{}, + BatchCloser: stubBatchCloser{}, + DependencyEditor: stubDependencyEditor{}, + MetadataCAS: stubMetadataCAS{}, + BatchApplier: stubBatchApplier{}, + Memories: stubMemories{}, + }) + if err != nil { + t.Fatalf("bind the oracle: %v", err) + } + + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan struct{}) + go func() { defer close(done); _ = srv.Serve(ctx) }() + t.Cleanup(func() { cancel(); <-done }) + + o.base = "http://" + srv.Addr() + return o +} + +func (o *oracle) reset() { + o.mu.Lock() + defer o.mu.Unlock() + o.ready, o.list, o.get, o.count, o.query = issueops.ReadyRequest{}, issueops.ListRequest{}, issueops.GetRequest{}, issueops.ReadyRequest{}, issueops.QueryRequest{} + o.issueCount, o.issueGroup = issueops.CountRequest{}, issueops.CountByGroupRequest{} + o.visited = map[string]bool{} +} + +// dial issues the encoded request against the operation's route and reports the +// status. +func (o *oracle) dial(t *testing.T, op Op, encoded Encoded) int { + t.Helper() + + var path string + switch op { + case OpListReadyWork: + path = "/v0/beads/ready" + case OpCountReadyWork: + path = "/v0/beads/ready:count" + case OpListIssues: + path = "/v0/beads/issues" + case OpQueryIssues: + path = "/v0/beads/issues:query" + case OpCountIssues: + path = "/v0/beads/issues:count" + case OpGetIssue: + if len(encoded.PathIDs) != 1 { + t.Fatalf("getIssue needs exactly one path id, got %v", encoded.PathIDs) + } + path = "/v0/beads/issues/" + url.PathEscape(encoded.PathIDs[0]) + default: + t.Fatalf("no route for operation %q", op) + } + + target := o.base + path + if query := encoded.Params.Encode(); query != "" { + target += "?" + query + } + + resp, err := http.Get(target) //nolint:gosec // a loopback oracle bound by this test + if err != nil { + t.Fatalf("dial %s: %v", target, err) + } + defer func() { _ = resp.Body.Close() }() + body, _ := io.ReadAll(resp.Body) + if resp.StatusCode != http.StatusOK { + t.Logf("%s -> %d %s", target, resp.StatusCode, body) + } + return resp.StatusCode +} + +// captured returns the request the server's decoder built for the operation. +// +// It keys on the SHAPE as well as the operation, because countIssues answers +// two of them on one route: `group_by` picks between the scalar method and the +// bucketed one, and the two roles are handed different request types. Reading +// the scalar one back for a grouped case would compare the caller's dimension +// against a request that has nowhere to hold it. +func (o *oracle) captured(t *testing.T, op Op, shape string) any { + t.Helper() + o.mu.Lock() + defer o.mu.Unlock() + if !o.visited[visitKey(op, shape)] { + t.Fatalf("the %s/%s handler never reached its role; the request was refused before decoding", op, shape) + } + switch { + case op == OpListReadyWork: + return o.ready + case op == OpCountReadyWork: + return o.count + case op == OpListIssues: + return o.list + case op == OpQueryIssues: + return o.query + case op == OpCountIssues && shape == "byGroup": + return o.issueGroup + case op == OpCountIssues: + return o.issueCount + case op == OpGetIssue: + return o.get + } + t.Fatalf("nothing captured for operation %q shape %q", op, shape) + return nil +} + +// visitKey names the SERVER-side arm a client shape reaches. +// +// A client shape is usually invisible from here — the two bridges map a legacy +// filter onto an operation the server answers with one handler and one role +// method, so `workFilterBridge` and the primary listing are the same arm. The +// count is the exception the parameter carries: `group_by` picks between +// Counter.Count and Counter.CountByGroup, which are two methods handed two +// request types, so that one shape gets a key of its own. +func visitKey(op Op, shape string) string { + if op == OpCountIssues && shape == "byGroup" { + return string(op) + "/byGroup" + } + return string(op) +} + +type recordingReader struct{ o *oracle } + +func (r recordingReader) Ready(_ context.Context, req issueops.ReadyRequest) (issueops.IssuePage, error) { + r.o.mu.Lock() + defer r.o.mu.Unlock() + r.o.ready, r.o.visited[visitKey(OpListReadyWork, "")] = req, true + return issueops.IssuePage{Items: []*issueops.IssueWithCounts{}}, nil +} + +func (r recordingReader) List(_ context.Context, req issueops.ListRequest) (issueops.IssuePage, error) { + r.o.mu.Lock() + defer r.o.mu.Unlock() + r.o.list, r.o.visited[visitKey(OpListIssues, "")] = req, true + return issueops.IssuePage{Items: []*issueops.IssueWithCounts{}}, nil +} + +func (r recordingReader) Get(_ context.Context, req issueops.GetRequest) (*issueops.IssueDetails, error) { + r.o.mu.Lock() + defer r.o.mu.Unlock() + r.o.get, r.o.visited[visitKey(OpGetIssue, "")] = req, true + return &issueops.IssueDetails{}, nil +} + +type recordingCounter struct{ o *oracle } + +func (c recordingCounter) CountReady(_ context.Context, req issueops.ReadyRequest) (issueops.ReadyCountResult, error) { + c.o.mu.Lock() + defer c.o.mu.Unlock() + c.o.count, c.o.visited[visitKey(OpCountReadyWork, "")] = req, true + return issueops.ReadyCountResult{}, nil +} + +type recordingQuerier struct{ o *oracle } + +func (q recordingQuerier) Query(_ context.Context, req issueops.QueryRequest) (issueops.IssuePage, error) { + q.o.mu.Lock() + defer q.o.mu.Unlock() + q.o.query, q.o.visited[visitKey(OpQueryIssues, "")] = req, true + return issueops.IssuePage{Items: []*issueops.IssueWithCounts{}}, nil +} + +type recordingIssueCounter struct{ o *oracle } + +func (c recordingIssueCounter) Count(_ context.Context, req issueops.CountRequest) (issueops.CountResult, error) { + c.o.mu.Lock() + defer c.o.mu.Unlock() + c.o.issueCount, c.o.visited[visitKey(OpCountIssues, "")] = req, true + return issueops.CountResult{}, nil +} + +func (c recordingIssueCounter) CountByGroup(_ context.Context, req issueops.CountByGroupRequest) (issueops.CountByGroupResult, error) { + c.o.mu.Lock() + defer c.o.mu.Unlock() + c.o.issueGroup, c.o.visited[visitKey(OpCountIssues, "byGroup")] = req, true + return issueops.CountByGroupResult{Groups: map[string]int{}}, nil +} + +// The roles this gate never dials. Each embeds its interface, so the +// Config is complete and a call that should not happen panics on the nil +// embedded value instead of answering something plausible. +type ( + stubClaimer struct{ issueops.Claimer } + stubReadyClaimer struct{ issueops.ReadyClaimer } + stubReleaser struct{ issueops.Releaser } + stubMetadataCAS struct{ issueops.MetadataCAS } + stubBatchApplier struct{ issueops.BatchApplier } + stubLifecycle struct{ issueops.Lifecycle } + stubSettings struct{ issueops.WorkspaceConfig } + stubStats struct{ issueops.StatsReporter } + stubCycles struct{ issueops.CycleDetector } + stubEdges struct{ issueops.EdgeReader } + stubGraphCounter struct{ issueops.GraphCounter } + stubRelations struct{ issueops.Relations } + stubCommenter struct{ issueops.Commenter } + stubBlocking struct{ issueops.BlockingAnnotator } + stubTree struct{ issueops.TreeWalker } + stubSweeper struct{ issueops.Sweeper } + stubDeleter struct{ issueops.Deleter } + stubBatchCreator struct{ issueops.BatchCreator } + stubBatchCloser struct{ issueops.BatchCloser } + stubDependencyEditor struct{ issueops.DependencyEditor } + stubMemories struct{ memoryops.Memories } +) diff --git a/internal/httpclient/encode/parentwalk.go b/internal/httpclient/encode/parentwalk.go new file mode 100644 index 000000000..aa75cb551 --- /dev/null +++ b/internal/httpclient/encode/parentwalk.go @@ -0,0 +1,378 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/parentwalk.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "net/url" + "slices" + "strings" + + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/internal/workapi" + "github.com/steveyegge/beads/issueops" +) + +// D4's `bd list --parent` walk, inverted. +// +// THE PROBLEM. The walk hands the store `bd list`'s whole built filter with only +// ParentID and Limit re-pointed per level (cmd/bd/list_show_filter_modes.go +// findAllDescendants), and workapi.BuildListFilter populates ExcludeStatus, +// Pinned, IsTemplate, ExcludeTypes, Ephemeral and SkipWisps on EVERY default +// listing. So the "ParentID-only shape" D4 originally named can never occur, and +// encoding those members verbatim is impossible anyway: listIssues publishes no +// exclude_status, no exclude_type and no is_template. +// +// THE RESOLUTION (escalation ga-2ieek, spec revision 6b428bf63). The wire +// publishes INTENTS — `all`, `include_templates`, `include_gates`, +// `include_infra` — not materialized exclusions, and the server's own role runs +// the SAME builder against the server's authoritative vocabulary. So the bridge +// inverts: it reads the intents back off the derived members, sends those, and +// lets the server re-derive. That is parity-positive as well as expressible — +// the re-derivation heals L7's degraded client-side vocabulary for the walk. +// +// WHY IT VERIFIES RATHER THAN PATTERN-MATCHES. Recognizing each member with its +// own hand-written rule would be a second encoder of BuildListFilter's +// semantics, and a second copy is a thing that can drift — which is exactly the +// objection recorded against inventing a reverse mapping. So the inversion reads +// the intents off the filter and then RE-RUNS THE REAL BUILDER to prove them: +// the intents are accepted only when the filter they produce carries the same +// derived members as the one in hand. The recognition is therefore not a copy of +// the derivation, it IS the derivation. +// +// ANY MEMBER THE RE-DERIVATION DOES NOT ACCOUNT FOR REFUSES, L12-style, citing +// its own ledger row — a user's `--exclude-type`, a `--pinned`, an +// `--include-templates` the intents cannot reach. + +// ListConfig is the client-side status and type vocabulary the inversion +// recognizes with. It is workapi's own, because the filter being inverted was +// built from exactly this value: passing anything else would make the +// recognition an approximation of the derivation rather than the derivation. +type ListConfig = workapi.ListConfig + +// ZeroVocabulary is the recognition set of an unconfigured workspace: the +// built-in statuses and the default infra types, which is the reading +// BuildListFilter itself gives one. Gates driving the table use it, and so does +// any caller with no store to ask. +func ZeroVocabulary() ListConfig { return ListConfig{} } + +// NewListConfig assembles the recognition vocabulary from the three reads that +// are its only wire-visible source (D4's degraded-vocabulary row, L7). +// +// It exists so the STORE does not have to import workapi to build one. The +// bridge subpackage is the allowlisted home for that dependency and the store is +// not, which is the boundary the design's lint row draws — so the store reads +// the three values through its own settings role and hands them here. +func NewListConfig(customStatuses []types.CustomStatus, customTypes []string, infra map[string]bool) ListConfig { + return ListConfig{CustomStatuses: customStatuses, CustomTypes: customTypes, InfraSet: infra} +} + +// The two stand-ins the re-derivation validates with. +// +// BuildListFilter validates `--status` and `--type` against the workspace +// vocabulary, and that check must NOT run here. The filter in hand already +// passed it on the way in, the value is being forwarded to a server that will +// apply its own AUTHORITATIVE vocabulary, and the client's copy is the degraded +// one (L7) — so re-validating client-side could refuse a table-backed custom +// status the server knows perfectly well. +// +// Substituting is exact rather than approximate because the derived members read +// these two fields only through predicates the stand-ins preserve: status +// matters as ""/"all"/"pinned"/"hooked"/other, and type matters as ""/"gate"/an +// infra name/other. Every "other" derives identically, so one representative +// stands for all of them. +const ( + otherStatus = string(types.StatusOpen) + otherType = "task" +) + +// derivedMember is one member BuildListFilter populates from the intent flags +// rather than from a user's filter, with the ledger row its mismatch cites. +// +// The order is the order the inversion compares in, and it is the order the +// encoder table declares them in, so a filter that diverges in two members +// always refuses on the same one. +var derivedMembers = []struct { + Field string + Ledger string + Equal func(got, want types.IssueFilter) bool +}{ + {"ExcludeStatus", "P-IssueFilter.ExcludeStatus", func(g, w types.IssueFilter) bool { return sameSet(g.ExcludeStatus, w.ExcludeStatus) }}, + {"Pinned", "P-IssueFilter.Pinned", func(g, w types.IssueFilter) bool { return boolPtrEqual(g.Pinned, w.Pinned) }}, + {"IsTemplate", "P-IssueFilter.IsTemplate", func(g, w types.IssueFilter) bool { return boolPtrEqual(g.IsTemplate, w.IsTemplate) }}, + {"ExcludeTypes", "P-IssueFilter.ExcludeTypes", func(g, w types.IssueFilter) bool { return sameSet(g.ExcludeTypes, w.ExcludeTypes) }}, + {"Ephemeral", "P-IssueFilter.Ephemeral", func(g, w types.IssueFilter) bool { return boolPtrEqual(g.Ephemeral, w.Ephemeral) }}, + {"SkipWisps", "P-IssueFilter.SkipWisps", func(g, w types.IssueFilter) bool { return g.SkipWisps == w.SkipWisps }}, +} + +// walkIntents is what one walk filter is recognized as. +type walkIntents struct { + // Status is the user's `--status` value, forwarded verbatim. Empty means + // they named none. + Status string + // AllFlag, IncludeTemplates, IncludeGates, IncludeInfra and + // IncludeEphemeral are the five intent booleans listIssues publishes. + AllFlag bool + IncludeTemplates bool + IncludeGates bool + IncludeInfra bool + // IncludeEphemeral is the PLANE intent, and it arrived last: the listing + // published no way to merge the wisp plane when this inversion was written + // (D9 L1), so a wisp-inclusive walk had nowhere to go and refused. L1 is + // retired and the member is published, so the intent is read back off + // SkipWisps here like every other derived default. + IncludeEphemeral bool +} + +// planParentWalk inverts a descendant-walk filter into listIssues parameters. +func planParentWalk(f types.IssueFilter, cfg ListConfig) (url.Values, error) { + intents, err := recognizeIntents(f, cfg) + if err != nil { + return nil, err + } + + b := newBuilder(OpListIssues, string(SearchParentWalk)) + // The residual sweep runs AFTER the inversion, which is the table's own + // order: the derived members are declared ahead of the plain refusals, so a + // filter that diverges in both refuses on the derived one. + b.refuseInexpressible(f) + + b.str("parent", derefString(f.ParentID)) + + // The intents, in place of the exclusions they produced. + b.str("status", intents.Status) + b.boolean("all", intents.AllFlag) + b.boolean("include_templates", intents.IncludeTemplates) + b.boolean("include_gates", intents.IncludeGates) + b.boolean("include_infra", intents.IncludeInfra) + b.boolean("include_ephemeral", intents.IncludeEphemeral) + + // The explicit user filters, under their documented parameters. + b.strPtr("type", (*string)(f.IssueType)) + b.strPtr("assignee", f.Assignee) + b.list("label", f.Labels) + b.list("label_any", f.LabelsAny) + b.list("exclude_label", f.ExcludeLabels) + b.timestamp("created_before", f.CreatedBefore) + b.timestamp("created_after", f.CreatedAfter) + b.metadata(f.MetadataFields) + b.str("has_metadata_key", f.HasMetadataKey) + + return b.done() +} + +// recognizeIntents reads the intents off f's derived members and proves them by +// re-derivation, or refuses naming the member that does not fit. +// +// EVERY INTENT IS READ, NONE IS SEARCHED FOR. A search over candidate intents +// would find the right answer just as often, but it could not say WHICH member +// was wrong when it found none: every candidate mismatches somewhere, so +// reporting the first one tried would name an arbitrary member and the refusal +// would cite an arbitrary ledger row. Each intent is therefore derived from the +// member that uniquely determines it, ONE candidate is built, and the comparison +// attributes exactly. +// +// `all` is the intent no single member determines: it is read off the absence +// of the status exclusions together with the pinned default. +// +// UPSTREAM #5333 COLLAPSED ONE OF THE READINGS THIS USED TO MAKE. `--status all` +// used to leave the pinned default in place and was told apart from `--all` by +// exactly that; the fix stopped a selector that promises EVERY status from +// silently forcing Pinned=false, so the two spellings now build one identical +// filter and are one question here. What survives is the other direction: a +// pinned default with no status and no exclusions is now reachable only from an +// explicit `--all --no-pinned`, and the wire has no parameter for it, so it +// refuses on P-IssueFilter.Pinned instead of encoding a `status=all` that would +// now ask the server a wider question than the caller did. +func recognizeIntents(f types.IssueFilter, cfg ListConfig) (walkIntents, error) { + refuse := func(row string) (walkIntents, error) { + return walkIntents{}, &RefusedError{Op: OpListIssues, Shape: string(SearchParentWalk), Row: RowByID(row)} + } + + issueType := derefString((*string)(f.IssueType)) + intents := walkIntents{ + Status: explicitStatus(f), + + IncludeTemplates: f.IsTemplate == nil, + IncludeGates: !slices.Contains(f.ExcludeTypes, types.IssueType("gate")), + IncludeInfra: !carriesEveryInfraType(f.ExcludeTypes, cfg), + // SkipWisps is the only trace the plane intent leaves in a built + // filter, so a merged plane is read as `--include-ephemeral` and a + // skipped one as its absence. + IncludeEphemeral: !f.SkipWisps, + } + // An infra `--type`, or the type `gate` itself, suppresses its exclusions on + // its own, so their absence says nothing about the flag. Read it as unset: + // that omits a parameter the server does not need, and the verification + // below rejects the reading if it is ever wrong. + if issueType == "gate" { + intents.IncludeGates = false + } + if cfg.IsInfra(issueType) { + intents.IncludeInfra = false + } + // The same rule for the plane, and it has TWO suppressors rather than one: + // `--include-infra` admits the wisp plane as well as the infra types, and an + // infra `--type` routes to the plane on its own. Either one leaves SkipWisps + // false whatever the ephemeral flag was, so under either of them the pair is + // the same question as the infra intent alone — `--all --no-pinned` and + // `--status all` again — and inventing the second parameter would be a + // distinction the re-derivation cannot see. + if intents.IncludeInfra || cfg.IsInfra(issueType) { + intents.IncludeEphemeral = false + } + + // The derivation's own reading of the status, which decides both the + // exclusion block and the pinned default. + derived := derivationStatus(intents.Status) + switch { + case len(f.ExcludeStatus) > 0: + // Exclusions survive only with no status and no `--all`. + intents.AllFlag = false + case derived != "": + // A named status suppresses the exclusions itself, so `all` shows only + // in the pinned default it also suppresses. + intents.AllFlag = f.Pinned == nil && derived != "pinned" && derived != "hooked" + case f.Pinned == nil: + intents.AllFlag = true + default: + // No status, no exclusions, and the pinned default still in place. Since + // upstream #5333 the only spelling that produces all three is + // `--all --no-pinned`, and the wire can carry neither half of it: `all` + // alone would drop the narrowing, and `status=all` no longer implies it + // server-side either. Refused here rather than read as `--status all` + // and left to the re-derivation below, which would refuse on the same + // member for a reason a reader would have to reconstruct. + return refuse("P-IssueFilter.Pinned") + } + + want, err := workapi.BuildListFilter(issueops.ListRequest{ + ParentID: derefString(f.ParentID), + Status: derived, + IssueType: derivationType(issueType, cfg), + AllFlag: intents.AllFlag, + IncludeTemplates: intents.IncludeTemplates, + IncludeGates: intents.IncludeGates, + IncludeInfra: intents.IncludeInfra, + IncludeEphemeral: intents.IncludeEphemeral, + }, cfg) + if err != nil { + // The stand-ins are drawn from the built-in vocabulary, so the builder + // cannot refuse them for being unknown. Reaching here means it refused + // the SHAPE, which is a client bug rather than a wire limitation — but + // it is still a refusal rather than a panic, because the alternative is + // answering a question this bridge has not understood. + return refuse("P-IssueFilter.unrecognized") + } + if row, mismatched := firstDerivedMismatch(f, want); mismatched { + return refuse(row) + } + return intents, nil +} + +// firstDerivedMismatch reports the ledger row of the first derived member the +// recognized intents do not reproduce. +func firstDerivedMismatch(got, want types.IssueFilter) (string, bool) { + for _, member := range derivedMembers { + if !member.Equal(got, want) { + return member.Ledger, true + } + } + return "", false +} + +// derivationStatus maps a user's status onto the representative the derivation +// behaves identically for. See otherStatus. +func derivationStatus(status string) string { + switch status { + case "", "all", "pinned", "hooked": + return status + default: + return otherStatus + } +} + +// derivationType maps a user's type onto the representative the derivation +// behaves identically for. See otherType. +func derivationType(issueType string, cfg ListConfig) string { + switch { + case issueType == "": + return "" + case issueType == "gate": + return "gate" + case cfg.IsInfra(issueType): + return issueType + default: + return otherType + } +} + +// explicitStatus renders the status intent that produced f's status members. +// +// A single status came from a bare `--status` name; several came from one +// comma-separated value, which is also how the wire's `status` parameter carries +// them (the operation reads it with the comma decoder and the role splits it +// again). Joining and re-splitting is therefore a round trip, not a guess. +func explicitStatus(f types.IssueFilter) string { + if f.Status != nil { + return string(*f.Status) + } + if len(f.Statuses) == 0 { + return "" + } + parts := make([]string, 0, len(f.Statuses)) + for _, s := range f.Statuses { + parts = append(parts, string(s)) + } + return strings.Join(parts, ",") +} + +// carriesEveryInfraType reports whether the exclusions hold the whole +// client-derivable infra vocabulary, which is what `--include-infra` being off +// produces. +// +// EVERY member, not any: a partial overlap is a user's own `--exclude-type` that +// happens to name an infra type, and reading it as the derived default would +// drop the rest of their exclusion silently. +func carriesEveryInfraType(excluded []types.IssueType, cfg ListConfig) bool { + infra := cfg.InfraTypes() + if len(infra) == 0 { + return false + } + for _, t := range infra { + if !slices.Contains(excluded, types.IssueType(t)) { + return false + } + } + return true +} + +// sameSet compares two exclusion lists as SETS. +// +// Order is not part of the meaning and is not even stable on one side: +// ListConfig.InfraTypes ranges a map when the workspace configures its own, so +// the infra members BuildListFilter appends arrive in a different order run to +// run. A slice comparison would make the inversion flaky on exactly the +// workspaces that configured the vocabulary it exists to respect. +func sameSet[T ~string](a, b []T) bool { + if len(a) != len(b) { + return false + } + left, right := slices.Clone(a), slices.Clone(b) + slices.Sort(left) + slices.Sort(right) + return slices.Equal(left, right) +} + +func boolPtrEqual(a, b *bool) bool { + if a == nil || b == nil { + return a == nil && b == nil + } + return *a == *b +} + +func derefString[T ~string](p *T) string { + if p == nil { + return "" + } + return string(*p) +} diff --git a/internal/httpclient/encode/parentwalk_test.go b/internal/httpclient/encode/parentwalk_test.go new file mode 100644 index 000000000..f94ac24b1 --- /dev/null +++ b/internal/httpclient/encode/parentwalk_test.go @@ -0,0 +1,531 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/parentwalk_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "errors" + "net/url" + "reflect" + "testing" + + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/internal/workapi" + "github.com/steveyegge/beads/issueops" +) + +// The gate on D4's parent-walk inversion. +// +// It drives the REAL builder rather than hand-written filters, because that is +// the whole claim being made: `bd list --parent` hands the store whatever +// workapi.BuildListFilter produced for the user's flags, and the inversion says +// it can read the intents back out of it. A test that wrote the filter by hand +// would be checking the inversion against a second guess at the derivation, and +// the two could agree while both were wrong. +// +// The four fixtures the spec's pin list names — default rendering, `--all`, the +// `--include-*` variants, and a residual refusal — are the table below. + +// walkFilter builds what `bd list --parent ` hands the walk: the +// listing's own filter, with the two members findAllDescendants re-points per +// level applied exactly as it applies them. +func walkFilter(t *testing.T, in issueops.ListRequest, cfg ListConfig) types.IssueFilter { + t.Helper() + in.ParentID = "bd-root" + filter, err := workapi.BuildListFilter(in, cfg) + if err != nil { + t.Fatalf("BuildListFilter: %v", err) + } + parent := "bd-root" + filter.ParentID = &parent + filter.Limit = 0 + return filter +} + +// textListing is what every text rendering of `bd list` sets on top of the +// user's flags (cmd/bd/list.go), so the default fixture is the filter the walk +// really receives rather than a tidier one. +func textListing(in issueops.ListRequest) issueops.ListRequest { + in.SkipCounts = true + return in +} + +func TestTheParentWalkInvertsTheDerivedDefaults(t *testing.T) { + cfg := ListConfig{} + + for _, tc := range []struct { + name string + in issueops.ListRequest + want url.Values + }{ + { + // The fixture D4 exists for: a bare `bd list --parent `, whose + // filter carries ExcludeStatus, Pinned, IsTemplate, the gate and + // infra exclusions and SkipWisps — none of which the wire publishes, + // and all of which the server re-derives from their own absence. + name: "the default text rendering sends only the parent", + in: textListing(issueops.ListRequest{}), + want: url.Values{"parent": {"bd-root"}}, + }, + { + name: "--all inverts the dropped status exclusions", + in: textListing(issueops.ListRequest{AllFlag: true}), + want: url.Values{"parent": {"bd-root"}, "all": {"true"}}, + }, + { + // `--status all` reaches the same three absences as `--all` AND, since + // upstream #5333 stopped an every-status selector from forcing the + // pinned default, the same pinned reading too. The two spellings are + // one filter, so they are one wire question. + name: "--status all is the same question as --all", + in: textListing(issueops.ListRequest{Status: "all"}), + want: url.Values{"parent": {"bd-root"}, "all": {"true"}}, + }, + { + name: "the three --include-* flags invert to their intents", + in: textListing(issueops.ListRequest{ + IncludeTemplates: true, IncludeGates: true, IncludeInfra: true, + }), + want: url.Values{ + "parent": {"bd-root"}, + "include_templates": {"true"}, + "include_gates": {"true"}, + "include_infra": {"true"}, + }, + }, + { + name: "--include-gates alone leaves the infra exclusions in place", + in: textListing(issueops.ListRequest{IncludeGates: true}), + want: url.Values{"parent": {"bd-root"}, "include_gates": {"true"}}, + }, + { + // The fourth intent, and the one the walk could not state until + // client wave ga-mijra: a wisp-inclusive descendant listing. Its + // only trace in the built filter is SkipWisps going false, which is + // exactly what the inversion reads it back off. + name: "--include-ephemeral inverts to the plane intent", + in: textListing(issueops.ListRequest{IncludeEphemeral: true}), + want: url.Values{"parent": {"bd-root"}, "include_ephemeral": {"true"}}, + }, + { + // --include-infra admits the plane on its own, so SkipWisps says + // nothing about the ephemeral flag here and the reading is "unset" — + // the same one --type gate gets for the gate intent. The + // re-derivation rejects it if that is ever wrong. + name: "--include-infra alone does not invent an ephemeral intent", + in: textListing(issueops.ListRequest{IncludeInfra: true}), + want: url.Values{"parent": {"bd-root"}, "include_infra": {"true"}}, + }, + { + // And the pair is the SAME QUESTION as --include-infra alone, the + // way `--all --no-pinned` is the same question as `--status all`: + // both flags admit the plane, so the filter they build is one + // filter and the walk says so rather than inventing a distinction + // the re-derivation cannot see. The pairing gc's TierBoth reads + // need is real on the LISTING, which sends what the caller set — + // see ListParams and the served two-plane cases. + name: "--include-ephemeral --include-infra is the same question as --include-infra", + in: textListing(issueops.ListRequest{IncludeEphemeral: true, IncludeInfra: true}), + want: url.Values{"parent": {"bd-root"}, "include_infra": {"true"}}, + }, + { + name: "an explicit status travels verbatim under its own parameter", + in: textListing(issueops.ListRequest{Status: "in_progress"}), + want: url.Values{"parent": {"bd-root"}, "status": {"in_progress"}}, + }, + { + // The multi-status spelling is one comma-separated value on both + // sides, so it round-trips through the same parameter. + name: "a multi-status filter re-joins into the one status parameter", + in: textListing(issueops.ListRequest{Status: "open,in_progress"}), + want: url.Values{"parent": {"bd-root"}, "status": {"open,in_progress"}}, + }, + { + // `--type gate` suppresses the gate exclusion on BOTH sides, so its + // absence must not be read as `--include-gates`. + name: "an explicit gate type suppresses the gate exclusion on both sides", + in: textListing(issueops.ListRequest{IssueType: "gate"}), + want: url.Values{"parent": {"bd-root"}, "type": {"gate"}}, + }, + { + name: "the explicit user filters encode under their documented parameters", + in: textListing(issueops.ListRequest{ + Assignee: "ada", + Labels: []string{"api"}, + LabelsAny: []string{"p0", "p1"}, + ExcludeLabels: []string{"wontfix"}, + HasMetadataKey: "epic", + MetadataFields: map[string]string{"team": "core"}, + }), + want: url.Values{ + "parent": {"bd-root"}, + "assignee": {"ada"}, + "label": {"api"}, + "label_any": {"p0", "p1"}, + "exclude_label": {"wontfix"}, + "has_metadata_key": {"epic"}, + "metadata_field": {"team=core"}, + }, + }, + } { + t.Run(tc.name, func(t *testing.T) { + plan, err := PlanSearch(walkFilter(t, tc.in, cfg), vocab(cfg)) + if err != nil { + t.Fatalf("PlanSearch: %v", err) + } + if plan.Shape != SearchParentWalk { + t.Fatalf("shape = %q, want %q", plan.Shape, SearchParentWalk) + } + if got := plan.Params.Encode(); got != tc.want.Encode() { + t.Errorf("params = %q, want %q", got, tc.want.Encode()) + } + }) + } +} + +// TestTheParentWalkRefusesAResidualFilter is the pin list's refusal case: a flag +// whose effect survives into the filter as something no intent reproduces. +// +// Each of these is a NARROWING the wire cannot state, which is the direction +// that matters — dropping one would answer with rows the user asked to hide. +func TestTheParentWalkRefusesAResidualFilter(t *testing.T) { + cfg := ListConfig{} + + for _, tc := range []struct { + name string + in issueops.ListRequest + row string + }{ + { + // The canonical residual: --exclude-type appends past the derived + // gate and infra members, and listIssues publishes no exclude_type. + name: "--exclude-type", + in: textListing(issueops.ListRequest{ExcludeTypes: []string{"chore"}}), + row: "P-IssueFilter.ExcludeTypes", + }, + { + // --pinned selects the flagged rows, which is a predicate and not an + // intent; it also suppresses the status exclusions, so the refusal + // has to be attributed to Pinned rather than to their absence. + name: "--pinned", + in: textListing(issueops.ListRequest{PinnedFlag: true}), + row: "P-IssueFilter.Pinned", + }, + { + // A residual with a documented parameter is still a residual when + // the parameter is not this operation's: listIssues publishes no + // priority. + name: "--priority", + in: textListing(issueops.ListRequest{Priority: intPtr(1)}), + row: "P-IssueFilter.Priority", + }, + } { + t.Run(tc.name, func(t *testing.T) { + var refusal *RefusedError + plan, err := PlanSearch(walkFilter(t, tc.in, cfg), vocab(cfg)) + if !errors.As(err, &refusal) { + t.Fatalf("encoded as %v without a refusal (err=%v)", plan.Params, err) + } + if !errors.Is(err, ErrRefused) { + t.Error("the refusal does not match ErrRefused") + } + if refusal.Row.ID != tc.row { + t.Errorf("refusal cites %q, want %q", refusal.Row.ID, tc.row) + } + }) + } +} + +// TestTheParentWalkRefusesADerivedMemberNoIntentReaches covers the members the +// CLI cannot produce but the seam can still be handed. +// +// The walk takes a types.IssueFilter, not a set of flags, so "no flag makes +// this" is not a proof that it cannot arrive — a library caller, or a future +// flag, reaches the same seam. Each case starts from a real built filter and +// changes exactly one member, which is what makes the refusal attributable. +func TestTheParentWalkRefusesADerivedMemberNoIntentReaches(t *testing.T) { + cfg := ListConfig{} + base := func() types.IssueFilter { return walkFilter(t, textListing(issueops.ListRequest{}), cfg) } + + for _, tc := range []struct { + name string + mutate func(*types.IssueFilter) + row string + }{ + { + // Templates ONLY. include_templates admits them alongside everything + // else and cannot select them, so this narrows in a direction the + // operation has no way to say. + name: "selecting templates only", + mutate: func(f *types.IssueFilter) { yes := true; f.IsTemplate = &yes }, + row: "P-IssueFilter.IsTemplate", + }, + { + name: "a status exclusion that is not the derived set", + mutate: func(f *types.IssueFilter) { f.ExcludeStatus = []types.Status{types.StatusBlocked} }, + row: "P-IssueFilter.ExcludeStatus", + }, + { + // Half the infra vocabulary is a user's own exclusion that happens to + // name infra types, not the derived default — reading it as the + // default would drop the rest of their exclusion silently. + name: "a partial infra exclusion", + mutate: func(f *types.IssueFilter) { f.ExcludeTypes = []types.IssueType{"gate", "agent"} }, + row: "P-IssueFilter.ExcludeTypes", + }, + { + name: "an ephemeral predicate on a non-infra listing", + mutate: func(f *types.IssueFilter) { yes := true; f.Ephemeral = &yes }, + row: "P-IssueFilter.Ephemeral", + }, + { + // SkipWisps HELD while the type exclusions say the infra vocabulary + // is admitted: BuildListFilter never produces that pair — admitting + // infra admits the plane — so no intent reproduces it and dropping + // the opt-out would merge a plane the caller asked to skip. + name: "holding the wisp plane out while infra is admitted", + mutate: func(f *types.IssueFilter) { + f.ExcludeTypes = nil + f.SkipWisps = true + }, + row: "P-IssueFilter.SkipWisps", + }, + } { + t.Run(tc.name, func(t *testing.T) { + filter := base() + tc.mutate(&filter) + + var refusal *RefusedError + plan, err := PlanSearch(filter, vocab(cfg)) + if !errors.As(err, &refusal) { + t.Fatalf("encoded as %v without a refusal (err=%v)", plan.Params, err) + } + if refusal.Row.ID != tc.row { + t.Errorf("refusal cites %q, want %q", refusal.Row.ID, tc.row) + } + }) + } +} + +// TestTheParentWalkReadsTheAllSpellingsTogetherAndTheNarrowingApart is the +// fourth derived default doing the only job it has left. +// +// It used to separate `--all` from `--status all`. Upstream #5333 removed that +// distinction at the source — an every-status selector no longer forces +// Pinned=false, because doing so hid pinned beads from the one selector that +// promises to hide nothing — so the two spellings now build ONE filter and this +// walk encodes them identically. The case survives inverted: what the pinned +// default still marks is a NARROWING, `--all --no-pinned`, and the wire has no +// parameter for it. Encoding it as `status=all` would have been right before +// #5333 and is now a wider question than the caller asked, so it refuses. +func TestTheParentWalkReadsTheAllSpellingsTogetherAndTheNarrowingApart(t *testing.T) { + cfg := ListConfig{} + for _, tc := range []struct { + name string + in issueops.ListRequest + want string + }{ + {"--all leaves no pinned default", issueops.ListRequest{AllFlag: true}, "all=true&parent=bd-root"}, + {"--status all is now the same filter, so the same params", issueops.ListRequest{Status: "all"}, "all=true&parent=bd-root"}, + } { + t.Run(tc.name, func(t *testing.T) { + plan, err := PlanSearch(walkFilter(t, textListing(tc.in), cfg), vocab(cfg)) + if err != nil { + t.Fatalf("PlanSearch: %v", err) + } + if got := plan.Params.Encode(); got != tc.want { + t.Errorf("params = %q, want %q", got, tc.want) + } + }) + } + + t.Run("--all --no-pinned is a narrowing the wire cannot state", func(t *testing.T) { + var refusal *RefusedError + plan, err := PlanSearch(walkFilter(t, textListing(issueops.ListRequest{AllFlag: true, NoPinnedFlag: true}), cfg), vocab(cfg)) + if !errors.As(err, &refusal) { + t.Fatalf("encoded as %v without a refusal (err=%v)", plan.Params, err) + } + if refusal.Row.ID != "P-IssueFilter.Pinned" { + t.Errorf("refusal cites %q, want P-IssueFilter.Pinned", refusal.Row.ID) + } + }) +} + +// TestTheParentWalkRecognizesAConfiguredVocabulary drives the inversion against +// a workspace that configured its own statuses and infra types. +// +// It is the case the "recognition set IS the derivation" claim is really about: +// the derived exclusions are longer, their order is a map's, and the inversion +// still has to read the same intents back out. A hand-written recognizer would +// have to restate the category rule and the fallback rule to get here. +func TestTheParentWalkRecognizesAConfiguredVocabulary(t *testing.T) { + cfg := ListConfig{ + CustomStatuses: []types.CustomStatus{ + {Name: "shipped", Category: types.CategoryDone}, + {Name: "icebox", Category: types.CategoryFrozen}, + {Name: "reviewing", Category: types.CategoryActive}, + }, + InfraSet: map[string]bool{"agent": true, "role": true, "beacon": true}, + } + + filter := walkFilter(t, textListing(issueops.ListRequest{}), cfg) + // The precondition this case exists for: the derived exclusions really do + // carry the configured vocabulary, so recognizing them is not vacuous. + if len(filter.ExcludeStatus) != 4 || len(filter.ExcludeTypes) != 4 { + t.Fatalf("the configured vocabulary did not reach the filter: exclude_status=%v exclude_types=%v", + filter.ExcludeStatus, filter.ExcludeTypes) + } + + plan, err := PlanSearch(filter, vocab(cfg)) + if err != nil { + t.Fatalf("PlanSearch: %v", err) + } + if got, want := plan.Params.Encode(), (url.Values{"parent": {"bd-root"}}).Encode(); got != want { + t.Errorf("params = %q, want %q", got, want) + } + + // A status this workspace configured is a status the wire carries verbatim, + // and the client must not re-validate it: the server's vocabulary is the + // authoritative one (L7). + plan, err = PlanSearch(walkFilter(t, textListing(issueops.ListRequest{Status: "reviewing"}), cfg), vocab(cfg)) + if err != nil { + t.Fatalf("PlanSearch with a configured status: %v", err) + } + if got := plan.Params.Get("status"); got != "reviewing" { + t.Errorf("status = %q, want the configured value verbatim", got) + } +} + +// TestTheParentWalkSendsNoUnlimitedPage pins the one thing the encoder must +// never emit for this shape: the walk asks for every descendant at each level, +// and `limit=0` is refused outright by a server bound past loopback. Paging to +// exhaustion is the pager's answer, and it owns the parameter. +func TestTheParentWalkSendsNoUnlimitedPage(t *testing.T) { + plan, err := PlanSearch(walkFilter(t, textListing(issueops.ListRequest{}), ListConfig{}), ZeroVocabulary) + if err != nil { + t.Fatalf("PlanSearch: %v", err) + } + if _, ok := plan.Params["limit"]; ok { + t.Errorf("the walk encoded a limit (%v); the pager owns it", plan.Params) + } +} + +// TestTheParentWalkRoundTripsThroughTheServerDecoder closes the loop the +// inversion's whole argument rests on. +// +// The claim is not "these parameters look right". It is that the SERVER, given +// the intents, re-derives the same filter from the same builder — so the walk +// asks the remote store the question the local store was asked. That is what is +// checked here: the encoded parameters go through the production route table and +// query decoder, the ListRequest the server built is read back off a capturing +// role, and THAT is fed through BuildListFilter again. The filter that comes out +// must carry the derived members of the one that went in. +// +// A parameter name this client has wrong is a 400 and fails at the dial. A value +// that decodes to a different intent survives the dial and fails at the +// comparison. Neither can be papered over from this side, because nothing in the +// expectation is written by hand. +func TestTheParentWalkRoundTripsThroughTheServerDecoder(t *testing.T) { + oracle := startOracle(t) + cfg := ListConfig{ + CustomStatuses: []types.CustomStatus{{Name: "shipped", Category: types.CategoryDone}}, + CustomTypes: []string{"agent", "beacon"}, + InfraSet: map[string]bool{"agent": true, "beacon": true}, + } + + assignee := "ada" + for _, tc := range []struct { + name string + in issueops.ListRequest + }{ + {"the default text rendering", textListing(issueops.ListRequest{})}, + {"--all", textListing(issueops.ListRequest{AllFlag: true})}, + {"--status all", textListing(issueops.ListRequest{Status: "all"})}, + {"every --include-* flag", textListing(issueops.ListRequest{IncludeTemplates: true, IncludeGates: true, IncludeInfra: true})}, + {"--include-gates alone", textListing(issueops.ListRequest{IncludeGates: true})}, + {"--include-infra alone", textListing(issueops.ListRequest{IncludeInfra: true})}, + {"--include-ephemeral alone", textListing(issueops.ListRequest{IncludeEphemeral: true})}, + {"--include-ephemeral --include-infra", textListing(issueops.ListRequest{IncludeEphemeral: true, IncludeInfra: true})}, + {"--include-ephemeral with an infra --type", textListing(issueops.ListRequest{IncludeEphemeral: true, IssueType: "agent"})}, + {"--include-templates alone", textListing(issueops.ListRequest{IncludeTemplates: true})}, + {"an explicit status", textListing(issueops.ListRequest{Status: "in_progress"})}, + {"a multi-status filter", textListing(issueops.ListRequest{Status: "open,in_progress"})}, + {"a configured custom status", textListing(issueops.ListRequest{Status: "shipped"})}, + {"--type gate", textListing(issueops.ListRequest{IssueType: "gate"})}, + {"an infra --type", textListing(issueops.ListRequest{IssueType: "agent"})}, + {"a plain --type", textListing(issueops.ListRequest{IssueType: "bug"})}, + {"the explicit user filters", textListing(issueops.ListRequest{ + Assignee: assignee, + Labels: []string{"api", "core"}, + LabelsAny: []string{"p0"}, + ExcludeLabels: []string{"wontfix"}, + MetadataFields: map[string]string{"team": "core"}, + HasMetadataKey: "team", + })}, + } { + t.Run(tc.name, func(t *testing.T) { + sent := walkFilter(t, tc.in, cfg) + + plan, err := PlanSearch(sent, vocab(cfg)) + if err != nil { + t.Fatalf("PlanSearch: %v", err) + } + + oracle.reset() + if status := oracle.dial(t, OpListIssues, Encoded{Params: plan.Params}); status != 200 { + t.Fatalf("the server answered %d for %q", status, plan.Params.Encode()) + } + decoded, ok := oracle.captured(t, OpListIssues, "").(issueops.ListRequest) + if !ok { + t.Fatalf("captured a %T, want an issueops.ListRequest", decoded) + } + + // The server's role runs the same builder against the server's own + // vocabulary; here that is cfg, which is what makes the comparison + // exact rather than approximate. + rebuilt, err := workapi.BuildListFilter(decoded, cfg) + if err != nil { + t.Fatalf("the server's request does not rebuild: %v", err) + } + + if row, mismatched := firstDerivedMismatch(sent, rebuilt); mismatched { + t.Errorf("the server re-derived a different %s:\n sent exclude_status=%v exclude_types=%v pinned=%v is_template=%v ephemeral=%v skip_wisps=%v\n rebuilt exclude_status=%v exclude_types=%v pinned=%v is_template=%v ephemeral=%v skip_wisps=%v", + row, + sent.ExcludeStatus, sent.ExcludeTypes, sent.Pinned, sent.IsTemplate, sent.Ephemeral, sent.SkipWisps, + rebuilt.ExcludeStatus, rebuilt.ExcludeTypes, rebuilt.Pinned, rebuilt.IsTemplate, rebuilt.Ephemeral, rebuilt.SkipWisps) + } + + // The explicit filters are not derived, so the sweep above says + // nothing about them: they have to arrive as themselves. + for _, member := range []struct { + name string + sent, back any + }{ + {"ParentID", canonicalOf(sent.ParentID), canonicalOf(rebuilt.ParentID)}, + {"Status", canonicalOf(sent.Status), canonicalOf(rebuilt.Status)}, + {"Statuses", canonicalOf(sent.Statuses), canonicalOf(rebuilt.Statuses)}, + {"IssueType", canonicalOf(sent.IssueType), canonicalOf(rebuilt.IssueType)}, + {"Assignee", canonicalOf(sent.Assignee), canonicalOf(rebuilt.Assignee)}, + {"Labels", canonicalOf(sent.Labels), canonicalOf(rebuilt.Labels)}, + {"LabelsAny", canonicalOf(sent.LabelsAny), canonicalOf(rebuilt.LabelsAny)}, + {"ExcludeLabels", canonicalOf(sent.ExcludeLabels), canonicalOf(rebuilt.ExcludeLabels)}, + {"MetadataFields", canonicalOf(sent.MetadataFields), canonicalOf(rebuilt.MetadataFields)}, + {"HasMetadataKey", canonicalOf(sent.HasMetadataKey), canonicalOf(rebuilt.HasMetadataKey)}, + } { + if !reflect.DeepEqual(member.sent, member.back) { + t.Errorf("%s: the server rebuilt %#v, the caller sent %#v", member.name, member.back, member.sent) + } + } + }) + } +} + +// canonicalOf reduces a filter member to the comparable shape the round-trip +// sweep uses, so the two gates read a nil slice and an empty one the same way. +func canonicalOf(v any) any { return canonical(reflect.ValueOf(v)) } + +func intPtr(v int) *int { return &v } + +// vocab adapts a recognition set to the lazy accessor PlanSearch takes. The +// laziness is for the resolver's hot path, which reads no vocabulary at all; a +// test that already holds one just hands it back. +func vocab(cfg ListConfig) func() ListConfig { return func() ListConfig { return cfg } } diff --git a/internal/httpclient/encode/roundtrip_test.go b/internal/httpclient/encode/roundtrip_test.go new file mode 100644 index 000000000..fe362734a --- /dev/null +++ b/internal/httpclient/encode/roundtrip_test.go @@ -0,0 +1,589 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/roundtrip_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "fmt" + "net/http" + "net/url" + "reflect" + "sort" + "testing" + "time" + + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/issueops" +) + +// GATE 2: the round trip, with the server's own decoder as the oracle. +// +// Every parameter this package emits is fed to internal/httpapi's PRODUCTION +// handlers — the real route table, the real `query` decoder with its +// unknown-parameter rule, the real request construction — and the request the +// server built is read back off a capturing role. There is no second copy of +// the parameter table on this side of the wire, so there is no twin contract +// that can drift: a name the server does not know is a 400 and fails here, and +// the right name carrying the wrong value decodes to a request that disagrees +// and fails here. +// +// WHAT THE EXPECTATION IS BUILT FROM matters as much as the assertion. It is +// derived MECHANICALLY from the encoder table's declared field correspondence — +// each entry's Decoded name — applied to the caller's own source value, plus +// the values the server is declared to weld (the operation's DispServerFixed +// entries). Hand-writing "what the server should have decoded" would recreate +// the twin this whole design exists to avoid: a mapping error would then be +// written twice and agree with itself. +// +// It is a PURE gate: a loopback listener and sixteen fake roles, no database +// and no fixtures on disk, which is what lets it run in the pure-gate step at +// PR cadence rather than behind a conformance tier. + +func TestEncodedParametersRoundTripThroughTheServerDecoder(t *testing.T) { + oracle := startOracle(t) + exercised := map[string]map[string]bool{} + + cases := roundTripCases() + if len(cases) == 0 { + t.Fatal("no round-trip cases; there is nothing for this gate to check") + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + table, ok := TableFor(tc.op, tc.shape) + if !ok { + t.Fatalf("no encoder table for %s/%s", tc.op, tc.shape) + } + source := reflect.ValueOf(tc.source) + if source.Type() != table.Source { + t.Fatalf("case source is %s, the table takes %s", source.Type(), table.Source) + } + + encoded, err := Encode(tc.op, tc.shape, tc.source) + if err != nil { + t.Fatalf("encode: %v", err) + } + + oracle.reset() + if status := oracle.dial(t, tc.op, encoded); status != http.StatusOK { + t.Fatalf("the server answered %d for %q.\n"+ + "A 400 here is the server turning down a parameter this client sent: an unknown NAME is version skew the encoder table has wrong, an invalid VALUE is a rendering bug.", + status, encoded.Params.Encode()) + } + + want := expectedRequest(t, table, source) + compareRequests(t, table, want, oracle.captured(t, tc.op, tc.shape)) + recordExercised(exercised, table, source) + }) + } + + assertEveryEncodedFieldWasExercised(t, exercised) +} + +// TestTheExactIDsFastPathDialsGetIssue covers the one encoding that is a PATH +// rather than a query string: D11's exact-ids probe, which is what +// ResolvePartialID's fast path becomes over http. It has no single decoded +// request for the sweep above to compare against — n ids are n requests — so it +// is driven here. +func TestTheExactIDsFastPathDialsGetIssue(t *testing.T) { + oracle := startOracle(t) + + ids := []string{"bd-a3f8e9", "bd-a3f8e9.1", "hacker-news-ko4"} + plan, err := PlanSearch(types.IssueFilter{IDs: ids}, ZeroVocabulary) + if err != nil { + t.Fatalf("plan: %v", err) + } + if plan.Shape != SearchExactIDs { + t.Fatalf("shape = %q, want %q", plan.Shape, SearchExactIDs) + } + if len(plan.Params) != 0 { + t.Errorf("the exact-ids shape sent query parameters: %v", plan.Params) + } + if !reflect.DeepEqual(plan.IDs, ids) { + t.Fatalf("plan ids = %v, want %v", plan.IDs, ids) + } + + for _, id := range plan.IDs { + oracle.reset() + if status := oracle.dial(t, OpGetIssue, Encoded{Params: url.Values{}, PathIDs: []string{id}}); status != http.StatusOK { + t.Fatalf("the server answered %d for id %q", status, id) + } + got, ok := oracle.captured(t, OpGetIssue, "").(issueops.GetRequest) + if !ok { + t.Fatalf("captured a %T, want an issueops.GetRequest", got) + } + if got.ID != id { + t.Errorf("the server decoded id %q, want %q", got.ID, id) + } + if got.IncludeComments || got.IncludeDependents { + t.Errorf("the fast path asked for the expensive row lists: %+v", got) + } + } +} + +type roundTripCase struct { + name string + op Op + shape string + source any +} + +func roundTripCases() []roundTripCase { + // Deliberately sub-second: the wire format is RFC 3339 and a bare + // time.RFC3339 layout DROPS the fraction. On a created bound a dropped + // fraction is a silently widened result set, which is precisely the class + // of bug this package exists to make impossible. + subSecond := time.Date(2026, 3, 4, 5, 6, 7, 123456789, time.UTC) + // Deliberately NOT UTC: the encoder normalizes, and an instant that + // survives the crossing only when the caller already held it in UTC is an + // encoder that works by luck. + zoned := time.Date(2025, 12, 31, 23, 59, 59, 0, time.FixedZone("KST", 9*3600)) + + zero, five := 0, 5 + assignee, parent := "agent-7", "bd-epic1" + + readyFilters := issueops.ReadyRequest{ + IssueType: "bug", + Assignee: "agent-7", + Unassigned: true, + + Labels: []string{"alpha", "beta"}, + LabelsAny: []string{"gamma"}, + ExcludeLabels: []string{"delta", "epsilon"}, + LabelPattern: "tech-*", + LabelRegex: "tech-(debt|legacy)", + + // Zero is a real priority, and a value-plus-flag pair has already lost + // P0 once. The pointer has to survive the crossing carrying zero. + Priority: &zero, + ParentID: "bd-epic1", + + IncludeDeferred: true, + IncludeEphemeral: true, + ExcludeTypes: []string{"gate", "molecule"}, + + MetadataFields: map[string]string{"team": "core", "wave": "3"}, + HasMetadataKey: "team", + } + + // The listing's fixture gains the text projection; readyFilters itself must + // NOT, because the countReadyWork case below shares it and that operation + // publishes no `brief` to round-trip. + readyEverything := readyFilters + readyEverything.Sort, readyEverything.Limit = "oldest", &five + readyEverything.Brief = true + + listEverything := issueops.ListRequest{ + Status: "open,in_progress", + IssueType: "bug", + Assignee: "agent-7", + + Labels: []string{"alpha", "beta"}, + LabelsAny: []string{"gamma"}, + ExcludeLabels: []string{"delta", "epsilon"}, + + ParentID: "bd-epic1", + + AllFlag: true, + IncludeTemplates: true, + IncludeGates: true, + IncludeInfra: true, + IncludeEphemeral: true, + + CreatedBefore: &subSecond, + CreatedAfter: &zoned, + + MetadataFields: map[string]string{"team": "core", "wave": "3"}, + HasMetadataKey: "team", + + Brief: true, + Limit: &five, + } + + workEverything := types.WorkFilter{ + // The derived default every real ready filter carries; the encoder drops + // it and the server re-derives it, so it round-trips as the absence of a + // `status` parameter. + Status: types.StatusOpen, + Type: "bug", + Priority: &zero, + Assignee: &assignee, + Unassigned: true, + + Labels: []string{"alpha", "beta"}, + LabelsAny: []string{"gamma"}, + ExcludeLabels: []string{"delta", "epsilon"}, + LabelPattern: "tech-*", + LabelRegex: "tech-(debt|legacy)", + + Limit: 5, + SortPolicy: types.SortPolicyOldest, + ParentID: &parent, + + IncludeDeferred: true, + IncludeEphemeral: true, + ExcludeTypes: []types.IssueType{"gate", "molecule"}, + + MetadataFields: map[string]string{"team": "core", "wave": "3"}, + HasMetadataKey: "team", + + // The bridge maps Lite onto the same `brief` the ready request sends. + Lite: true, + } + + // The count's whole vocabulary at once. Every member is here because the + // operation publishes every member, so this case IS the partition: a + // parameter the server does not know is a 400 and a value it decodes onto + // the wrong field is a mismatch, and one number coming back would show + // neither. + countEverything := issueops.CountRequest{ + Status: "closed", + IssueType: "bug", + Assignee: "agent-7", + + // Zero is a real priority on this request too, and all three bounds are + // pointers for that reason. + Priority: &zero, + PriorityMin: &zero, + PriorityMax: &five, + + Labels: []string{"alpha", "beta"}, + LabelsAny: []string{"gamma"}, + + TitleSearch: "flaky", + // The role splits this string itself, so it has to arrive UNSPLIT — + // spaces and all, which is what the server's own handler forwards. + IDFilter: "bd-a3f8e9, bd-a3f8e9.1,bd-b1", + + TitleContains: "retry", + DescContains: "timeout", + NotesContains: "flake", + + CreatedAfter: &zoned, + CreatedBefore: &subSecond, + UpdatedAfter: &zoned, + UpdatedBefore: &subSecond, + ClosedAfter: &zoned, + ClosedBefore: &subSecond, + + EmptyDesc: true, + NoAssignee: true, + NoLabels: true, + + IncludeInfra: true, + IncludeEphemeral: true, + + MetadataFields: map[string]string{"team": "core", "wave": "3"}, + HasMetadataKey: "team", + } + + // Values that have to survive percent-encoding, a `=` inside a metadata + // VALUE (the server splits on the first one), and a repeated parameter. + awkward := issueops.ReadyRequest{ + Assignee: "a b&c=d+e", + LabelPattern: "a/b?c#d*", + LabelRegex: `^(tech|ops)-[a-z]{2,}$`, + Labels: []string{"needs review", "p0/urgent"}, + MetadataFields: map[string]string{"spec key": "v=1&x", "z": ""}, + HasMetadataKey: "spec key", + } + + cases := []roundTripCase{ + {"listReadyWork/a request naming nothing", OpListReadyWork, "", issueops.ReadyRequest{}}, + {"listReadyWork/every filter, an explicit order and a page", OpListReadyWork, "", readyEverything}, + {"listReadyWork/an explicitly unlimited page", OpListReadyWork, "", issueops.ReadyRequest{Sort: "hybrid", Limit: &zero}}, + {"listReadyWork/the priority policy", OpListReadyWork, "", issueops.ReadyRequest{Sort: "priority"}}, + {"listReadyWork/values that have to be escaped", OpListReadyWork, "", awkward}, + + {"countReadyWork/a count naming nothing", OpCountReadyWork, "", issueops.ReadyRequest{}}, + {"countReadyWork/every filter the listing takes", OpCountReadyWork, "", readyFilters}, + + {"listIssues/a listing naming nothing", OpListIssues, "", issueops.ListRequest{}}, + {"listIssues/every parameter", OpListIssues, "", listEverything}, + {"listIssues/an explicitly unlimited page", OpListIssues, "", issueops.ListRequest{Limit: &zero}}, + {"listIssues/one status, one label", OpListIssues, "", issueops.ListRequest{Status: "closed", Labels: []string{"alpha"}}}, + + {"queryIssues/a query naming nothing", OpQueryIssues, "", issueops.QueryRequest{}}, + {"queryIssues/an expression with operators and parentheses", OpQueryIssues, "", issueops.QueryRequest{ + Expression: "(type=bug OR label=urgent) AND NOT priority<2", + SortBy: "title", Reverse: true, IncludeClosed: true, Limit: &five, + }}, + + {"countIssues/a count naming nothing", OpCountIssues, "", issueops.CountRequest{}}, + {"countIssues/every filter the operation publishes", OpCountIssues, "", countEverything}, + // `all` is a status the count takes literally and the server forwards + // verbatim; it is not the listing's boolean of the same spelling. + {"countIssues/the literal all status", OpCountIssues, "", issueops.CountRequest{Status: "all"}}, + {"countIssues/byGroup/a dimension over an empty predicate", OpCountIssues, "byGroup", issueops.CountByGroupRequest{GroupBy: issueops.CountGroupStatus}}, + {"countIssues/byGroup/a dimension over the whole predicate", OpCountIssues, "byGroup", issueops.CountByGroupRequest{Filter: countEverything, GroupBy: issueops.CountGroupLabel}}, + + {"getIssue/an id alone", OpGetIssue, "", issueops.GetRequest{ID: "bd-a3f8e9"}}, + {"getIssue/both row lists", OpGetIssue, "", issueops.GetRequest{ID: "bd-a3f8e9.1", IncludeComments: true, IncludeDependents: true}}, + {"getIssue/the brief dependency projection", OpGetIssue, "", issueops.GetRequest{ID: "bd-a3f8e9.2", IncludeDependents: true, BriefDeps: true}}, + + {"listReadyWork/workFilterBridge/the derived-default status alone drops", OpListReadyWork, "workFilterBridge", types.WorkFilter{Status: types.StatusOpen}}, + {"listReadyWork/workFilterBridge/every expressible field", OpListReadyWork, "workFilterBridge", workEverything}, + {"listReadyWork/workFilterBridge/an unbounded page keeps the wire's default", OpListReadyWork, "workFilterBridge", types.WorkFilter{Status: types.StatusOpen, Limit: 0, SortPolicy: types.SortPolicyPriority}}, + } + _ = parent + + // The whole published sort vocabulary, one case each: an order accepted and + // then ignored is indistinguishable from one the caller does not understand, + // so the server refuses a value outside the set — and this proves every + // value the client can send is inside it. + for _, policy := range []string{"priority", "created", "updated", "closed", "status", "id", "title", "type", "assignee"} { + cases = append(cases, roundTripCase{ + name: "queryIssues/sort=" + policy, op: OpQueryIssues, + source: issueops.QueryRequest{Expression: "status=open", SortBy: policy}, + }) + } + for _, policy := range []string{"hybrid", "priority", "oldest"} { + cases = append(cases, roundTripCase{ + name: "listReadyWork/sort=" + policy, op: OpListReadyWork, + source: issueops.ReadyRequest{Sort: policy}, + }) + } + return cases +} + +// expectedRequest builds the server-side request the caller's source value +// MEANS, from the table's declared correspondence. +// +// Three populations, in order: the fields the table maps onto parameters, the +// fields the server welds for itself, and the one normalization the encoder +// performs. Nothing here re-derives a parameter name or a value rendering — +// those are exactly what the server is being asked to confirm. +func expectedRequest(t *testing.T, table Table, source reflect.Value) reflect.Value { + t.Helper() + want := reflect.New(table.Target).Elem() + + driven := map[string]bool{} + for _, entry := range table.Fields { + // DispNested rides the same correspondence: the delegated shape is + // encoded by another table, but it lands on a member of THIS target and + // the caller's value is what the server must have decoded there. + if entry.Disposition != DispParam && entry.Disposition != DispPath && entry.Disposition != DispNested { + continue + } + dst := want.FieldByName(entry.Decoded) + if !dst.IsValid() { + t.Fatalf("%s has no field %s", table.Target, entry.Decoded) + } + assignConverted(t, dst, source.FieldByName(entry.Name)) + driven[entry.Decoded] = true + } + + // The values the SERVER pins, taken from the operation's primary table so a + // bridge inherits them rather than restating them: listIssues welds SortBy + // to created order because the cursor is a position in it, and + // countReadyWork pins the order it has no parameter for. + for _, other := range Tables() { + if !other.Primary || other.Op != table.Op || other.Target != table.Target { + continue + } + for _, entry := range other.Fields { + if entry.Disposition != DispServerFixed || driven[entry.Name] { + continue + } + field := want.FieldByName(entry.Name) + if !field.IsValid() || field.Kind() != reflect.String { + t.Fatalf("%s.%s is server-fixed but is not a string field", table.Target, entry.Name) + } + field.SetString(entry.Fixed) + } + } + + // The encoder's own normalization: an absent ready policy is sent as the + // concrete `hybrid` it means, because omitting it would adopt the server's + // `priority` default instead — a different item SET once a limit truncates. + if table.Op == OpListReadyWork { + if policy := want.FieldByName("Sort"); policy.IsValid() && policy.String() == "" { + policy.SetString("hybrid") + } + } + return want +} + +// assignConverted copies one source field onto the server-side field the table +// says it lands on, crossing the pointer and named-type differences the legacy +// filters carry. +// +// The pointer rules are the interesting half. A nil source pointer leaves the +// target at its zero value, because "unset" is what a nil means; a plain zero +// int leaves a target POINTER nil, because the legacy filters spell "no bound" +// as zero and the wire spells it as an absent parameter. +func assignConverted(t *testing.T, dst, src reflect.Value) { + t.Helper() + switch { + case src.Kind() == reflect.Pointer && dst.Kind() != reflect.Pointer: + if src.IsNil() { + return + } + assignConverted(t, dst, src.Elem()) + case dst.Kind() == reflect.Pointer && src.Kind() != reflect.Pointer: + if !populated(src) { + return + } + dst.Set(reflect.New(dst.Type().Elem())) + assignConverted(t, dst.Elem(), src) + case dst.Kind() == reflect.Pointer && src.Kind() == reflect.Pointer: + if src.IsNil() { + return + } + dst.Set(reflect.New(dst.Type().Elem())) + assignConverted(t, dst.Elem(), src.Elem()) + case dst.Kind() == reflect.Slice && src.Kind() == reflect.Slice: + if src.Len() == 0 { + return + } + out := reflect.MakeSlice(dst.Type(), src.Len(), src.Len()) + for i := range src.Len() { + assignConverted(t, out.Index(i), src.Index(i)) + } + dst.Set(out) + default: + if !src.Type().ConvertibleTo(dst.Type()) { + t.Fatalf("cannot carry a %s onto a %s", src.Type(), dst.Type()) + } + dst.Set(src.Convert(dst.Type())) + } +} + +// compareRequests checks the whole server-side request, field by field. +// +// The WHOLE request rather than the mapped fields: a parameter that landed +// somewhere it was not meant to is exactly the bug an encoder makes, and +// checking only the fields the table claims to drive would leave it invisible. +func compareRequests(t *testing.T, table Table, want reflect.Value, got any) { + t.Helper() + gotValue := reflect.ValueOf(got) + if gotValue.Type() != table.Target { + t.Fatalf("the server built a %s, the table targets %s", gotValue.Type(), table.Target) + } + for i := range table.Target.NumField() { + name := table.Target.Field(i).Name + wantField, gotField := canonical(want.Field(i)), canonical(gotValue.Field(i)) + if !reflect.DeepEqual(wantField, gotField) { + t.Errorf("%s.%s: the server decoded %#v, the caller meant %#v", table.Target.Name(), name, gotField, wantField) + } + } +} + +// canonical reduces a request field to a comparable shape. +// +// Instants compare in UTC at nanosecond precision, so a zone the caller +// happened to hold does not read as a difference; an empty slice or map is the +// same as an absent one, because the wire spells both as no parameter at all. A +// nil POINTER stays distinct from a pointed-to zero, which is the distinction +// `limit=0` (unlimited) and an absent limit (the server's default) turn on. +func canonical(v reflect.Value) any { + if v.Type() == reflect.TypeOf(time.Time{}) { + return v.Interface().(time.Time).UTC().Format(time.RFC3339Nano) + } + switch v.Kind() { + case reflect.Pointer: + if v.IsNil() { + return nil + } + return canonical(v.Elem()) + case reflect.Slice: + if v.Len() == 0 { + return nil + } + out := make([]any, v.Len()) + for i := range out { + out[i] = canonical(v.Index(i)) + } + return out + case reflect.Map: + if v.Len() == 0 { + return nil + } + out := map[string]any{} + for iter := v.MapRange(); iter.Next(); { + out[fmt.Sprint(iter.Key().Interface())] = canonical(iter.Value()) + } + return out + case reflect.String: + return v.String() + case reflect.Bool: + return v.Bool() + case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64: + return v.Int() + case reflect.Struct: + // A nested request shape. It is reduced member by member rather than + // compared whole, so the rules above still hold INSIDE it: an instant + // compares in UTC, and an empty slice is the same as an absent one. + // reflect.DeepEqual on the raw struct would read a zone the caller + // happened to hold as a difference the wire never carried. + out := map[string]any{} + for i := range v.NumField() { + field := v.Type().Field(i) + if !field.IsExported() { + continue + } + out[field.Name] = canonical(v.Field(i)) + } + return out + default: + return v.Interface() + } +} + +func recordExercised(exercised map[string]map[string]bool, table Table, source reflect.Value) { + key := tableName(table) + if exercised[key] == nil { + exercised[key] = map[string]bool{} + } + for _, entry := range table.Fields { + if entry.Disposition != DispParam && entry.Disposition != DispPath { + continue + } + if populated(source.FieldByName(entry.Name)) { + exercised[key][entry.Name] = true + } + } +} + +// assertEveryEncodedFieldWasExercised is what makes "cover every encoded field" +// a property rather than an intention. A parameter no case ever populates is a +// parameter this gate does not check, and the sweep passing would say otherwise. +func assertEveryEncodedFieldWasExercised(t *testing.T, exercised map[string]map[string]bool) { + t.Helper() + + // Entries whose encoding has no single decoded request for the sweep to + // compare against, each named with the test that does cover it. A bare table + // name redirects the whole table. + coveredElsewhere := map[string]string{ + "getIssue/searchExactIDs.IDs": "TestTheExactIDsFastPathDialsGetIssue", + // The descendant walk is not a field correspondence and cannot be + // checked as one: two of its source members share the `status` + // parameter, and four of the parameters it sends are INVERSIONS of + // members that carry no parameter at all, so the mechanical expectation + // this sweep builds has nothing to build from. Its round trip is a + // stronger assertion made in its own gate — the server's decoded request + // is fed back through the same builder and the filter that comes out is + // compared with the one that went in. + "listIssues/searchParentWalk": "TestTheParentWalkRoundTripsThroughTheServerDecoder", + } + + for _, table := range Tables() { + key := tableName(table) + if coveredElsewhere[key] != "" { + continue + } + var missing []string + for _, entry := range table.Fields { + if entry.Disposition != DispParam && entry.Disposition != DispPath { + continue + } + if exercised[key][entry.Name] || coveredElsewhere[key+"."+entry.Name] != "" { + continue + } + missing = append(missing, entry.Name) + } + sort.Strings(missing) + if len(missing) > 0 { + t.Errorf("%s: no round-trip case populates %v, so the server never confirmed those parameters", key, missing) + } + } +} diff --git a/internal/httpclient/encode/skew.go b/internal/httpclient/encode/skew.go new file mode 100644 index 000000000..2b7658cd1 --- /dev/null +++ b/internal/httpclient/encode/skew.go @@ -0,0 +1,257 @@ +// 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_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", + "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 +} diff --git a/internal/httpclient/encode/skew_test.go b/internal/httpclient/encode/skew_test.go new file mode 100644 index 000000000..8e6b47b9c --- /dev/null +++ b/internal/httpclient/encode/skew_test.go @@ -0,0 +1,189 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/skew_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "fmt" + "strings" + "testing" +) + +// GATE 5: the skew reverse lookup. +// +// The bijection gate above proves every field reaches a parameter. This one +// proves every parameter reaches back to a FLAG, which is the direction D7's +// third refusal text runs. +// +// The failure it exists to prevent is quiet and specific. A parameter added to +// the wire with no row here still encodes, still sends, and still earns a 400 +// from an older server — the only thing that breaks is the refusal, which +// degrades from "--include-comments is not supported by bd serve at ..." into a +// bare invalid-argument. That is a strictly worse message on exactly the day the +// user most needs a good one, and nothing else in this package would notice. + +func TestEveryWireParameterMapsBackToAFlagOrSaysWhyNot(t *testing.T) { + params := SkewParams() + if len(params) == 0 { + t.Fatal("the encoder table published no parameters; this gate is vacuous") + } + + for _, pf := range params { + if pf.HasFlag { + if pf.Why != "" { + t.Errorf("parameter %q has both a flag (--%s) and a no-flag reason; one of the two tables is wrong", pf.Param, pf.Flag) + } + if strings.HasPrefix(pf.Flag, "-") { + t.Errorf("parameter %q maps to %q; the table holds BARE flag names and the text supplies the dashes", pf.Param, pf.Flag) + } + continue + } + // No flag is a decision, and a decision carries its reason. Without this + // arm the cheapest way to green this gate would be to leave a new + // parameter out of both tables. + if pf.Why == "" { + t.Errorf("parameter %q is on the encoder table with no flag and no reason for having none;\n"+ + "add it to paramFlag if a flag produces it, or to paramNoFlag with why it cannot", pf.Param) + } + } +} + +func TestTheSkewTablesCarryNoRowsTheEncoderNeverSends(t *testing.T) { + // The converse direction. A row for a parameter no table publishes is a rule + // that matches nothing — it would survive a rename of the parameter it was + // written for and go on looking like coverage. + published := map[string]bool{} + for _, pf := range SkewParams() { + published[pf.Param] = true + } + + for param := range paramFlag { + if !published[param] { + t.Errorf("paramFlag names %q, which no encoder table publishes", param) + } + } + for param := range paramNoFlag { + if !published[param] { + t.Errorf("paramNoFlag names %q, which no encoder table publishes", param) + } + } +} + +func TestTheReverseLookupAnswersTheParametersASkewedServerNames(t *testing.T) { + // The mapping itself, spelled out. These are the pairs a 400 from an older + // server actually produces, and getting one of them wrong is invisible until + // a user reads the refusal. + for _, tc := range []struct{ param, flag string }{ + {"include_comments", "include-comments"}, + {"include_dependents", "include-dependents"}, + {"has_metadata_key", "has-metadata-key"}, + {"metadata_field", "metadata-field"}, + {"exclude_type", "exclude-type"}, + {"label_any", "label-any"}, + {"created_before", "created-before"}, + {"include_ephemeral", "include-ephemeral"}, + {"sort", "sort"}, + {"limit", "limit"}, + {"parent", "parent"}, + } { + got, ok := FlagForParam(tc.param) + if !ok { + t.Errorf("FlagForParam(%q) found nothing", tc.param) + continue + } + if got != tc.flag { + t.Errorf("FlagForParam(%q) = %q, want %q", tc.param, got, tc.flag) + } + } +} + +func TestParametersWithNoFlagDoNotInventOne(t *testing.T) { + // `--q` and `--cursor` do not exist. Rendering either would send the user + // looking for a flag that was never there, which is worse than naming the + // parameter, because it reads like the client knows something. + for _, param := range []string{"q", "cursor", "{id}"} { + if flag, ok := FlagForParam(param); ok { + t.Errorf("FlagForParam(%q) invented --%s", param, flag) + } + entry := paramNoFlag[param] + if entry.Why == "" { + t.Errorf("parameter %q has no recorded reason for having no flag", param) + } + // The subject is what the user reads, so it must never be a flag + // spelling and never be empty. + if entry.Subject == "" { + t.Errorf("parameter %q has no subject; case 3 could not name what it refused", param) + } + if strings.HasPrefix(ParameterSubject(param), "--") { + t.Errorf("ParameterSubject(%q) = %q, which reads as a flag", param, ParameterSubject(param)) + } + } +} + +func TestTheCaseThreeRefusalNamesTheFlagTheServerTheVersionAndTheParameter(t *testing.T) { + // D7 case 3, whole. Every one of the four facts is load-bearing: the flag is + // what the user typed, the URL is which server refused (an agent rig has + // several), the version is what makes "upgrade the server" actionable, and + // the parameter is what makes the message diagnosable when the flag mapping + // is the thing that is wrong. + got := UnknownParameterRefusal("include_comments", "http://serve.internal:9099", "1.0.4") + want := `--include-comments is not supported by bd serve at http://serve.internal:9099 (bd_version 1.0.4): parameter "include_comments" is unknown to the server` + if got != want { + t.Errorf("refusal =\n%s\nwant\n%s", got, want) + } + // The shared constant and the renderer are the same string. cmd/bd's + // refusal layer formats these same constants and byte-pins the result; a pin + // against a format that layer also owned would prove only that it agrees + // with itself. + if fmt.Sprintf(UnknownParameterFormat, "--include-comments", "http://serve.internal:9099", "1.0.4", "include_comments") != want { + t.Error("UnknownParameterFormat and UnknownParameterRefusal have drifted apart") + } +} + +func TestBeforeTheHandshakeTheRefusalNamesNoVersionRatherThanAnEmptyOne(t *testing.T) { + // The handshake is lazy (D6), so a case-3 refusal can arrive from a baseline + // operation that never fetched a context. 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. + got := UnknownParameterRefusal("label_regex", "http://serve.internal:9099", "") + want := `--label-regex is not supported by bd serve at http://serve.internal:9099: parameter "label_regex" is unknown to the server` + if got != want { + t.Errorf("refusal =\n%s\nwant\n%s", got, want) + } + if strings.Contains(got, "bd_version") { + t.Errorf("the pre-handshake refusal printed an empty version parenthetical: %s", got) + } + if fmt.Sprintf(UnknownParameterNoVersionFormat, "--label-regex", "http://serve.internal:9099", "label_regex") != want { + t.Error("UnknownParameterNoVersionFormat and UnknownParameterRefusal have drifted apart") + } +} + +func TestASkewSignalAlwaysRendersEvenForAParameterThisClientNeverSent(t *testing.T) { + // The enterprise server's Host-allowlist refusal is the live case: 400 with + // `param: "Host"` for a DNS-named URL (internal/httpapi/server.go:1196). It + // is a request header, not a query parameter, so no flag produced it — and a + // refusal that came back empty here would swallow the one 4xx on this + // surface whose recovery is a serve-side flag. + got := UnknownParameterRefusal("Host", "http://bd.example.invalid:9099", "1.0.4") + want := `the "Host" filter is not supported by bd serve at http://bd.example.invalid:9099 (bd_version 1.0.4): parameter "Host" is unknown to the server` + if got != want { + t.Errorf("refusal =\n%s\nwant\n%s", got, want) + } + if strings.Contains(got, "--") { + t.Errorf("refusal invented a flag for a parameter with none: %s", got) + } + // And the degenerate input, because a server is untrusted text: an empty + // `param` must still produce a sentence rather than a fragment. + if empty := UnknownParameterRefusal("", "http://x", "1.0.4"); empty == "" { + t.Error("an empty param rendered an empty refusal") + } +} + +func TestTheSkewReasonIsTheServersOwnSpelling(t *testing.T) { + // Shared with internal/httpapi's ReasonUnknownParameter (problem.go:139). + // The two refusals that ride `invalid_argument` — unknown_parameter and + // invalid_value — carry opposite recoveries, so the reason is what + // dispatches. A typo here would classify every skew signal as a bad value. + if UnknownParameterReason != "unknown_parameter" { + t.Errorf("UnknownParameterReason = %q", UnknownParameterReason) + } +} diff --git a/internal/httpclient/encode/table.go b/internal/httpclient/encode/table.go new file mode 100644 index 000000000..0dfc5f292 --- /dev/null +++ b/internal/httpclient/encode/table.go @@ -0,0 +1,731 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/table.go@49d1df2f6) +// to OSS beads under the MIT license. +package encode + +import ( + "reflect" + "sync" +) + +// The encoder table: the field-by-field disposition of every read request shape +// this client puts on the v0 wire. +// +// It exists because the encoders below it are hand-written, and a hand-written +// encoder's failure mode is silence — a filter it never learned about is a +// filter it never sends, and the server can only reject parameters it RECEIVES +// (D7). So the encoder is not the record of what it encodes; this is. The +// bijection gate reads it three ways at once: +// +// - against reflection over the source struct, so every populatable field is +// classified here or carries a divergence-ledger row, and an upstream field +// added tomorrow fails CI rather than shipping as a silent drop; +// - against internal/httpapi/spec/openapi.v0.yaml, so every parameter the +// operation publishes is either driven by a field or explicitly reserved; +// - against the encoders themselves, by populating one field at a time and +// asserting the behavior this table declares. +// +// A table with no entries, or a ledger row nothing references, fails the gate +// too: completeness is the gate's own invariant, not something a reader has to +// take on trust. + +// Op names a v0 operation, spelled as its operationId in the document. +type Op string + +const ( + OpListReadyWork Op = "listReadyWork" + OpCountReadyWork Op = "countReadyWork" + OpListIssues Op = "listIssues" + OpQueryIssues Op = "queryIssues" + OpCountIssues Op = "countIssues" + OpGetIssue Op = "getIssue" + + // The write operations carry no encoder table: their requests are JSON + // bodies rather than query strings, so there is no parameter set for the + // bijection gate to read. They are named here anyway because a refusal has + // to say WHICH operation refused, and the alternative is a second spelling + // of an operationId in the store package. + OpClaimIssue Op = "claimIssue" + OpCreateIssue Op = "createIssue" + OpCloseIssue Op = "closeIssue" + OpReopenIssue Op = "reopenIssue" + OpUpdateIssue Op = "updateIssue" + OpAddDependencies Op = "addDependencies" + OpRemoveDependency Op = "removeDependency" + OpBatchCloseIssues Op = "batchCloseIssues" + OpRememberMemory Op = "rememberMemory" + OpForgetMemory Op = "forgetMemory" + OpSweepIssues Op = "sweepIssues" + OpDeleteIssues Op = "deleteIssues" + OpBatchCreateIssues Op = "batchCreateIssues" + OpApplyBatch Op = "applyBatch" + + // countDependencyEdges carries no encoder table either, for a different + // reason: its request is ANCHORED rather than a predicate — four members, + // all four published — so it is built inline beside the three graph reads + // that share its collection. Its refusal still has to name an operation. + OpCountDependencyEdges Op = "countDependencyEdges" +) + +// Disposition is what becomes of one request field on its way to the wire. +type Disposition string + +const ( + // DispParam is encoded as the named query parameter. + DispParam Disposition = "param" + // DispPath is carried in the request path rather than the query string. + DispPath Disposition = "path" + // DispServerFixed is a field the SERVER pins: the client sends nothing and + // the decoded request carries the server's own value. It is not a drop — + // the value is knowable, and the gate asserts it. + DispServerFixed Disposition = "server-fixed" + // DispClientSide has no wire member and is honored by client-side + // machinery — the pager, the sort comparator, the max-rows circuit breaker. + // The gate asserts the encoder emits nothing for it, which is what keeps + // "the client honors this" from quietly becoming "the client ignores this". + DispClientSide Disposition = "client-side" + // DispDropped has no wire member and is deliberately NOT honored. Every one + // carries a divergence-ledger row arguing why the difference cannot be read + // as a narrower or wider answer than the caller asked for. + DispDropped Disposition = "dropped" + // DispRefused has no wire member and FAILS when populated, carrying the + // ledger row that says why. This is the default disposition of anything + // inexpressible: L12, refuse-not-drop. + DispRefused Disposition = "refused" + // DispInverted is a DERIVED DEFAULT: a member the wire publishes no + // parameter for, which the SERVER re-derives from the intent parameters the + // encoder sends in its place (D4's parent-walk inversion, parentwalk.go). + // + // It is its own disposition rather than a param or a refusal because it is + // neither: nothing about the member crosses the wire, and yet a populated + // one is not an error. What decides is the VALUE — the one the same builder + // would have derived for the intents being sent is accounted for, and every + // other value refuses with the row named here. The gate drives it exactly as + // a refusal, because its sentinel value is by construction not a derived + // one. + DispInverted Disposition = "inverted" + // DispNested is a member that is itself a whole request shape, encoded by + // the table over that shape rather than by this one. + // + // countIssues is why it exists: CountByGroupRequest carries the scalar + // predicate BY NAME (`Filter`) plus the dimension, so its table would + // otherwise have to restate twenty-three classifications the count table + // already makes — two copies of one partition, which is the drift every + // other gate here is written to prevent. + // + // It is not a drop and not a param. The gate drives it by populating the + // nested shape whole and asserting the query CHANGED, which is the property + // that matters: a grouped count whose builder forgot the caller's predicate + // answers buckets over the wrong set, and every bucket in it would look + // perfectly plausible. + DispNested Disposition = "nested" +) + +// FieldEntry is one field's disposition. +type FieldEntry struct { + // Name is the Go field on the source struct. + Name string + // Disposition is what becomes of it. + Disposition Disposition + // Param is the wire parameter (DispParam) or the path template segment + // (DispPath). + Param string + // Decoded names the field the SERVER's decoder lands this value on. For the + // request shapes the server shares with the client it is Name; for the two + // bridges — which map a legacy filter onto a role request — it is the + // corresponding member of the server-side type, and stating it here is what + // lets the round-trip gate compare the two without a hand-written twin. + Decoded string + // Fixed is the value the server pins (DispServerFixed). + Fixed string + // Why is required on every disposition but DispParam and DispPath. + Why string + // Ledger is the divergence-ledger row id, required on DispDropped and + // DispRefused and permitted elsewhere where a row is worth citing. + Ledger string +} + +// ReservedParam is a parameter the operation publishes that NO request field +// drives. Each one is a hole in the "every parameter comes from a field" half +// of the bijection, so each carries its reason. +type ReservedParam struct { + Name string + Why string +} + +// Table is one source shape's disposition against one operation. +type Table struct { + // Op is the operation this table encodes for. + Op Op + // Shape names a bridge's arm, and is empty on a primary table. + Shape string + // Source is the struct the caller hands the client. + Source reflect.Type + // Target is the request the server's decoder builds. + Target reflect.Type + // Primary marks the ONE table per operation whose parameter set must equal + // the operation's published parameter set. A bridge maps a legacy filter + // onto a subset of an operation it does not own, so it carries no such + // obligation — and saying that here is what stops a bridge from being read + // as evidence that the operation is fully mapped. + Primary bool + Reserved []ReservedParam + Fields []FieldEntry +} + +// Tables returns the whole encoder table, one entry per (operation, source +// shape) pair. +func Tables() []Table { + return []Table{ + readyTable(), + readyCountTable(), + listTable(), + queryTable(), + countTable(), + countByGroupTable(), + getTable(), + readyBridgeTable(), + searchExactIDsTable(), + searchParentWalkTable(), + } +} + +// TableFor returns the table for one operation and shape. +func TableFor(op Op, shape string) (Table, bool) { + for _, t := range cachedTables() { + if t.Op == op && t.Shape == shape { + return t, true + } + } + return Table{}, false +} + +// cachedTables is what the ENCODER reads, so a per-page walk does not rebuild +// two hundred table entries per request. Tables() keeps building a fresh copy +// for everyone else, which is what stops a caller from editing the table the +// encoder consults. +var cachedTables = sync.OnceValue(Tables) + +// briefCountDropWhy is what remains of the free-form-text projection's old +// three-shape drop after upstream #5586 published `brief` on both PAGE +// operations. The two listings now send it (readyTable, listTable and the ready +// bridge), so this reason is scoped to the COUNT, which publishes no such +// parameter and has no rows to project. +const briefCountDropWhy = "countReadyWork publishes no `brief` and answers a cardinality, so there is nothing to project: the parameter chooses what is HYDRATED and never which rows match, and a count reads neither. " + + "Dropping it is SkipLabels' and SkipCounts' argument exactly — the total is what it would have been — and refusing would make a performance flag a hard error on the one operation where it can cost nothing. " + + "The two page operations retired this drop and send the parameter; a caller that populates Brief for a count is asking a question a cardinality does not have" + +func param(name, wire string) FieldEntry { + return FieldEntry{Name: name, Disposition: DispParam, Param: wire, Decoded: name} +} + +func paramTo(name, wire, decoded string) FieldEntry { + return FieldEntry{Name: name, Disposition: DispParam, Param: wire, Decoded: decoded} +} + +func refused(name, ledger string) FieldEntry { + return FieldEntry{Name: name, Disposition: DispRefused, Ledger: ledger} +} + +func dropped(name, ledger, why string) FieldEntry { + return FieldEntry{Name: name, Disposition: DispDropped, Ledger: ledger, Why: why} +} + +func clientSide(name, why string) FieldEntry { + return FieldEntry{Name: name, Disposition: DispClientSide, Why: why} +} + +func serverFixed(name, fixed, why string) FieldEntry { + return FieldEntry{Name: name, Disposition: DispServerFixed, Fixed: fixed, Why: why} +} + +// readyFilterEntries are the filters listReadyWork and countReadyWork share. +// +// They are one list for the reason internal/httpapi's readyFilters is one +// function: the count answers with the SIZE of the page the listing returns, and +// a filter one of them sent and the other did not would make that identity false +// for any client that set it. +func readyFilterEntries() []FieldEntry { + return []FieldEntry{ + paramTo("IssueType", "type", "IssueType"), + param("Assignee", "assignee"), + param("Unassigned", "unassigned"), + param("Labels", "label"), + param("LabelsAny", "label_any"), + param("ExcludeLabels", "exclude_label"), + param("LabelPattern", "label_pattern"), + param("LabelRegex", "label_regex"), + param("Priority", "priority"), + paramTo("ParentID", "parent", "ParentID"), + refused("MolType", "E-ReadyRequest.MolType"), + param("IncludeDeferred", "include_deferred"), + param("IncludeEphemeral", "include_ephemeral"), + paramTo("ExcludeTypes", "exclude_type", "ExcludeTypes"), + paramTo("MetadataFields", "metadata_field", "MetadataFields"), + param("HasMetadataKey", "has_metadata_key"), + // [Removed: an enterprise-only `refused("ExcludeIDs", ...)` row stood + // here, naming a field issueops.ReadyRequest does not have in OSS + // (confirmed via reflection: TestEncoderTableClassifiesEveryRequestField + // fails "names a field that does not exist"). OSS's ReadyRequest + // (issueops/reader.go) carries no id-exclusion filter at all — unlike + // workapi.WorkFilter, whose own, separate ExcludeIDs refusal stays below + // in readyBridgeTable as "E-WorkFilter.ExcludeIDs". Do not re-add this + // row unless issueops.ReadyRequest grows the field.] + } +} + +func readyTable() Table { + return Table{ + Op: OpListReadyWork, Source: tyReadyRequest, Target: tyReadyRequest, Primary: true, + Fields: append(readyFilterEntries(), + param("Brief", "brief"), + // The sort policy is sent EXPLICITLY, always — including for a + // request that names none. An absent `sort` is "priority" to the + // server and hybrid to the storage layer, and those two answer with + // different item SETS once a limit truncates, so an empty policy is + // encoded as the concrete `hybrid` it means rather than omitted. + paramTo("Sort", "sort", "Sort"), + param("Limit", "limit"), + refused("Offset", "E-ReadyRequest.Offset"), + ), + } +} + +func readyCountTable() Table { + return Table{ + Op: OpCountReadyWork, Source: tyReadyRequest, Target: tyReadyRequest, Primary: true, + Fields: append(readyFilterEntries(), + dropped("Brief", "E-ReadyRequest.Brief@countReadyWork", briefCountDropWhy), + serverFixed("Sort", "priority", + "countReadyWork publishes no `sort`: a cardinality has no order, and the handler sends the listing's own default into the builder so the request stays one the builder accepts. "+ + "Dropping the caller's policy changes no answer — CountReady's total is order-independent by contract"), + refused("Limit", "E-ReadyRequest.Limit@countReadyWork"), + refused("Offset", "E-ReadyRequest.Offset"), + ), + } +} + +func listTable() Table { + return Table{ + Op: OpListIssues, Source: tyListRequest, Target: tyListRequest, Primary: true, + Reserved: []ReservedParam{{ + Name: "cursor", + Why: "the opaque keyset token. It is minted by the SERVER and echoed by the pager from the previous page's next_cursor; no request field encodes one, and a client that minted its own would be inventing a position in an order it cannot observe. " + + "ListRequest's own decoded position (AfterCreatedAt/AfterID) is client-side for exactly that reason — see D8 row 1 and the upstream ask for after_created_at/after_id parameters", + }, { + Name: "sort", + Why: "PAGER-OWNED, like cursor beside it. The operation publishes the display order the upstream ask named, but whether a request may carry it depends on the SHAPE OF THE WALK — a caller-supplied keyset position and an unlimited read must stay on the created-order pager — and on the server advertising issues.list.sort. " + + "None of that is visible to a per-field encoder, so ListRequest.SortBy stays serverFixed here and the key is written by the pager's pushdown leg (list_walk.go sortedPage), which is the only place that can see all four conditions at once", + }}, + Fields: []FieldEntry{ + param("Status", "status"), + paramTo("IssueType", "type", "IssueType"), + param("Assignee", "assignee"), + refused("TitleSearch", "E-ListRequest.TitleSearch"), + refused("SpecPrefix", "E-ListRequest.SpecPrefix"), + refused("IDFilter", "E-ListRequest.IDFilter"), + param("Labels", "label"), + param("LabelsAny", "label_any"), + param("ExcludeLabels", "exclude_label"), + refused("LabelPattern", "E-ListRequest.LabelPattern"), + refused("LabelRegex", "E-ListRequest.LabelRegex"), + refused("TitleContains", "E-ListRequest.TitleContains"), + refused("DescContains", "E-ListRequest.DescContains"), + refused("NotesContains", "E-ListRequest.NotesContains"), + refused("ExternalContains", "E-ListRequest.ExternalContains"), + refused("ExternalRef", "E-ListRequest.ExternalRef"), + paramTo("CreatedBefore", "created_before", "CreatedBefore"), + paramTo("CreatedAfter", "created_after", "CreatedAfter"), + refused("UpdatedAfter", "E-ListRequest.UpdatedAfter"), + refused("UpdatedBefore", "E-ListRequest.UpdatedBefore"), + refused("ClosedAfter", "E-ListRequest.ClosedAfter"), + refused("ClosedBefore", "E-ListRequest.ClosedBefore"), + refused("DeferAfter", "E-ListRequest.DeferAfter"), + refused("DeferBefore", "E-ListRequest.DeferBefore"), + refused("DueAfter", "E-ListRequest.DueAfter"), + refused("DueBefore", "E-ListRequest.DueBefore"), + refused("EmptyDesc", "E-ListRequest.EmptyDesc"), + refused("NoAssignee", "E-ListRequest.NoAssignee"), + refused("NoLabels", "E-ListRequest.NoLabels"), + dropped("SkipLabels", "E-ListRequest.SkipLabels", + "the wire hydrates labels either way; dropping the opt-out costs a join and hands the caller more data, never less"), + dropped("SkipCounts", "E-ListRequest.SkipCounts", + "the wire hydrates the three cardinalities either way. Every text rendering of `bd list` sets this, so refusing would kill the default listing over http"), + param("Brief", "brief"), + refused("IncludeComments", "E-ListRequest.IncludeComments"), + refused("IncludeAllTypes", "E-ListRequest.IncludeAllTypes"), + refused("Priority", "E-ListRequest.Priority"), + refused("PriorityMin", "E-ListRequest.PriorityMin"), + refused("PriorityMax", "E-ListRequest.PriorityMax"), + refused("PinnedFlag", "E-ListRequest.PinnedFlag"), + refused("NoPinnedFlag", "E-ListRequest.NoPinnedFlag"), + param("IncludeTemplates", "include_templates"), + param("IncludeGates", "include_gates"), + param("IncludeInfra", "include_infra"), + param("IncludeEphemeral", "include_ephemeral"), + refused("ExcludeTypes", "E-ListRequest.ExcludeTypes"), + paramTo("ParentID", "parent", "ParentID"), + refused("NoParent", "E-ListRequest.NoParent"), + refused("MolType", "E-ListRequest.MolType"), + refused("WispType", "E-ListRequest.WispType"), + refused("DeferredFlag", "E-ListRequest.DeferredFlag"), + refused("OverdueFlag", "E-ListRequest.OverdueFlag"), + paramTo("MetadataFields", "metadata_field", "MetadataFields"), + param("HasMetadataKey", "has_metadata_key"), + paramTo("AllFlag", "all", "AllFlag"), + refused("ReadyFlag", "E-ListRequest.ReadyFlag"), + serverFixed("SortBy", "created", + "a request that names no `sort` is welded to created order, because the cursor is a keyset position in that order — a first page under `bd list`'s priority-first default would make the second page skip and duplicate rows. "+ + "The operation publishes `sort`, but it is a PAGER-OWNED key (see the Reserved row) rather than a per-field one, so THE ENCODER emits nothing for this field and the decoded request carries the server's own `created` whenever the pager stays on the walk. "+ + "The pager's pushdown leg names the caller's order instead, on the bounded, position-free, capability-advertised requests where the server can serve it in one page; the legs it cannot take keep the client-side comparator and the fetch-to-exhaustion cost L2 now records for them alone"), + clientSide("Reverse", + "unlike SortBy, this one never reaches the wire at all: OSS listIssues publishes no `reverse` parameter under any capability — issues.list.sort (routes.go) gates `sort` alone, and handleListIssues (reads.go) never reads a reverse flag, so there is no pushdown leg for this field to ride. "+ + "[Removed from this table's Reserved set: an enterprise-only `reverse` row previously claimed it was PAGER-OWNED like `sort`, pairing with the upstream ask's sort+reverse pushdown. The published OpenAPI parameter list for GET /v0/beads/issues has no such member, and CapIssuesListSort's own doc says it gates `sort` only — so the row described behavior this OSS server does not serve. ListRequest.Reverse is honored purely by the client-side comparator on every leg (L2), never by the wire, until an upstream ask adds the parameter.]"), + param("Limit", "limit"), + refused("Offset", "E-ListRequest.Offset"), + clientSide("AfterCreatedAt", + "the caller-supplied keyset position is honored by the pager's SKIP-FORWARD WALK (D8 row 1): it pages the created-order wire and discards rows at or before the position. "+ + "The encoder deliberately mints NO created_before jump for it — created_before is strictly exclusive (internal/storage/sqlbuild/filter.go) while the keyset upper bound is inclusive, so a jump computed from an instant whose storage granularity the client cannot observe would silently drop the same-instant tail. That is the drop L3 and L12 exist to prevent, traded for an optimization; the jump becomes safe when the wire publishes after_created_at/after_id (upstream ask)"), + clientSide("AfterID", + "the same position's tie-break, discarded against client-side; the wire carries it only inside the opaque cursor, which the client must not mint"), + clientSide("AfterPriority", + "the priority half of a keyset position minted under sort=priority (upstream #5666); like AfterCreatedAt/AfterID it reaches the wire only inside the opaque cursor, which the client must not mint, so the pager's skip-forward walk discards against it client-side"), + clientSide("MaxRows", + "the wire publishes no max_rows, so the client enforces the cap during page accumulation and synthesizes issueops.ErrTooManyRows — the exact sentinel `bd list` already classifies into exit 2 (D12). The cap bounds WIRE ROWS FETCHED, which is why it can fire where local mode would not (L15)"), + clientSide("MaxRowsSource", + "the cap's attribution, read back by the synthesized refusal's text; it decides no answer (D12)"), + }, + } +} + +func queryTable() Table { + return Table{ + Op: OpQueryIssues, Source: tyQueryRequest, Target: tyQueryRequest, Primary: true, + Fields: []FieldEntry{ + paramTo("Expression", "q", "Expression"), + paramTo("IncludeClosed", "all", "IncludeClosed"), + paramTo("SortBy", "sort", "SortBy"), + param("Reverse", "reverse"), + param("Limit", "limit"), + refused("Offset", "E-QueryRequest.Offset"), + }, + } +} + +// countTable is the issue count's predicate, and it is the one table on this +// surface with NOTHING TO REFUSE. +// +// That is worth stating, because a count is the shape where a dropped filter +// does the most damage: a listing that widened returns rows a caller can look +// at, and a count that widened returns a NUMBER, which carries no evidence of +// the set it came from. So the partition here was measured against the +// document rather than assumed — every one of CountRequest's twenty-three +// members is published by GET /v0/beads/issues:count, and the count's +// vocabulary is total. +// +// THE COUNT'S PLANE VOCABULARY IS NARROWER THAN THE LISTING'S — `include_infra` +// and `include_ephemeral` where listIssues additionally has `include_templates`, +// `include_gates` and `all` — and that narrowing is the ROLE's, not the wire's. +// issueops.CountRequest has no member for those remaining three, so there is no +// field here to refuse: `bd count` and `bd list` answer about different sets on +// EVERY backend, and this client reproduces that difference exactly rather than +// inventing a wire divergence to describe it. What IncludeInfra alone moves is +// four things at once, and the role documents them; a caller that wants a plane +// union the count cannot express is asking a question issueops.Counter does not +// have. +// +// [Corrected: this comment previously claimed CountRequest carried only +// IncludeInfra from the plane vocabulary ("has no member for the other four"), +// and the table below sent no `has_metadata_key` or `include_ephemeral` to +// match. Both are real CountRequest members (issueops/counter.go) and both are +// published by GET /v0/beads/issues:count in the OSS OpenAPI spec, so the +// table was silently dropping two caller-supplied filters on every count +// request. Mapped below as ordinary params; see TestEveryEncoderTableParameterIsPublished.] +func countTable() Table { + return Table{ + Op: OpCountIssues, Source: tyCountRequest, Target: tyCountRequest, Primary: true, + Reserved: []ReservedParam{{ + Name: "group_by", + Why: "the bucketing dimension is not part of the predicate: no member of CountRequest carries it, because a scalar count has none. " + + "It is issueops.CountByGroupRequest.GroupBy, classified by the countIssues/byGroup table beside this one, which carries the same filter by reference rather than by copy", + }}, + Fields: []FieldEntry{ + param("Status", "status"), + paramTo("IssueType", "type", "IssueType"), + param("Assignee", "assignee"), + + param("Priority", "priority"), + paramTo("PriorityMin", "priority_min", "PriorityMin"), + paramTo("PriorityMax", "priority_max", "PriorityMax"), + + param("Labels", "label"), + param("LabelsAny", "label_any"), + + paramTo("TitleSearch", "title", "TitleSearch"), + // The comma-separated string, sent as the caller wrote it: the ROLE + // splits, trims and de-duplicates it, and a client that pre-split it + // would be deciding what an id set means — the same reading the + // server's own handler gives the parameter. + paramTo("IDFilter", "id", "IDFilter"), + + paramTo("TitleContains", "title_contains", "TitleContains"), + paramTo("DescContains", "desc_contains", "DescContains"), + paramTo("NotesContains", "notes_contains", "NotesContains"), + + paramTo("CreatedAfter", "created_after", "CreatedAfter"), + paramTo("CreatedBefore", "created_before", "CreatedBefore"), + paramTo("UpdatedAfter", "updated_after", "UpdatedAfter"), + paramTo("UpdatedBefore", "updated_before", "UpdatedBefore"), + paramTo("ClosedAfter", "closed_after", "ClosedAfter"), + paramTo("ClosedBefore", "closed_before", "ClosedBefore"), + + paramTo("EmptyDesc", "empty_description", "EmptyDesc"), + paramTo("NoAssignee", "no_assignee", "NoAssignee"), + paramTo("NoLabels", "no_labels", "NoLabels"), + + param("IncludeInfra", "include_infra"), + // [Added: OSS publishes `include_ephemeral` on GET + // /v0/beads/issues:count (same plane knob ListRequest.IncludeEphemeral + // already maps on listIssues) and CountRequest carries the matching + // member (issueops/counter.go). The table previously had no entry for + // it at all, silently dropping a caller-supplied filter.] + param("IncludeEphemeral", "include_ephemeral"), + + paramTo("MetadataFields", "metadata_field", "MetadataFields"), + // [Added: OSS publishes `has_metadata_key` on GET + // /v0/beads/issues:count, spelled and meaning the same thing as + // ListRequest.HasMetadataKey/ReadyRequest.HasMetadataKey. Missing + // here for the same reason IncludeEphemeral was: no entry at all.] + param("HasMetadataKey", "has_metadata_key"), + }, + } +} + +// countByGroupTable is the bucketed count: the scalar predicate plus one +// dimension. +// +// It is NOT primary — the count table above owns the operation's parameter set +// — and it classifies two members, because that is all CountByGroupRequest has. +// The predicate travels through the count table by delegation (DispNested) +// rather than by a second enumeration of the same twenty-three fields. +func countByGroupTable() Table { + return Table{ + Op: OpCountIssues, Shape: "byGroup", + Source: tyCountByGroupRequest, Target: tyCountByGroupRequest, + Fields: []FieldEntry{ + {Name: "Filter", Disposition: DispNested, Decoded: "Filter", + Why: "the same predicate a scalar count takes, encoded by the countIssues table. Sharing it rather than restating it is what makes the two questions provably one: a grouped count is a scalar count plus a dimension, and a builder that narrowed one and not the other would bucket a set the caller never asked about"}, + paramTo("GroupBy", "group_by", "GroupBy"), + }, + } +} + +func getTable() Table { + return Table{ + Op: OpGetIssue, Source: tyGetRequest, Target: tyGetRequest, Primary: true, + Fields: []FieldEntry{ + {Name: "ID", Disposition: DispPath, Param: "{id}", Decoded: "ID"}, + param("IncludeDependents", "include_dependents"), + param("IncludeComments", "include_comments"), + param("BriefDeps", "brief_deps"), + }, + } +} + +// readyBridgeTable is the reverse types.WorkFilter -> ready-parameters mapper. +// +// It exists only because `bd ready`'s listing is still raw at tip, and it dies +// with the upstream front-door migration onto issueops.Reader. Until then it is +// the seam's least elegant component, and the only thing keeping it honest is +// that it refuses every field it cannot express rather than answering a wider +// question than was asked (L12). +// +// Status is the one exception, and it is a DERIVED DEFAULT rather than a refusal +// (D4's parent-walk inversion, applied to this bridge's single derived member): +// listReadyWork publishes no `status`, and the server re-derives ready work's +// status from a status-LESS request through workapi.BuildReadyFilter — +// unconditionally StatusOpen. Every real `bd ready` carries exactly that value, +// because BuildReadyFilter stamps it on the filter it always builds, so the +// encoder recognizes StatusOpen as the server's own default and sends nothing. +// Any other status, and any populated Statuses OR-set, still refuses (L12) — the +// refuse-not-drop guard for the hand-built shapes BuildReadyFilter never emits. +func readyBridgeTable() Table { + const statusInversionWhy = "ready work's one derived default: listReadyWork publishes no `status`, and the server re-derives open-only from a status-less request through workapi.BuildReadyFilter (unconditionally StatusOpen), so the encoder sends that value as the absence the server reads it back from (D4 parent-walk inversion)" + return Table{ + Op: OpListReadyWork, Shape: "workFilterBridge", + Source: tyWorkFilter, Target: tyReadyRequest, + Fields: []FieldEntry{ + {Name: "Status", Disposition: DispInverted, Ledger: "E-WorkFilter.Status", Why: statusInversionWhy}, + refused("Statuses", "E-WorkFilter.Statuses"), + paramTo("Type", "type", "IssueType"), + paramTo("Priority", "priority", "Priority"), + paramTo("Assignee", "assignee", "Assignee"), + paramTo("Unassigned", "unassigned", "Unassigned"), + paramTo("Labels", "label", "Labels"), + paramTo("LabelsAny", "label_any", "LabelsAny"), + paramTo("ExcludeLabels", "exclude_label", "ExcludeLabels"), + paramTo("LabelPattern", "label_pattern", "LabelPattern"), + paramTo("LabelRegex", "label_regex", "LabelRegex"), + paramTo("Limit", "limit", "Limit"), + paramTo("SortPolicy", "sort", "Sort"), + paramTo("ParentID", "parent", "ParentID"), + refused("MoleculeID", "E-WorkFilter.MoleculeID"), + refused("MolType", "E-WorkFilter.MolType"), + refused("WispType", "E-WorkFilter.WispType"), + paramTo("IncludeDeferred", "include_deferred", "IncludeDeferred"), + paramTo("IncludeEphemeral", "include_ephemeral", "IncludeEphemeral"), + paramTo("ExcludeTypes", "exclude_type", "ExcludeTypes"), + paramTo("MetadataFields", "metadata_field", "MetadataFields"), + paramTo("HasMetadataKey", "has_metadata_key", "HasMetadataKey"), + paramTo("Lite", "brief", "Brief"), + refused("ExcludeIDs", "E-WorkFilter.ExcludeIDs"), + refused("Offset", "E-WorkFilter.Offset"), + clientSide("MaxRows", + "enforced during page accumulation exactly as ListRequest.MaxRows is, so `bd ready --max-rows` exits 2 over http where it exits 2 locally (D12)"), + clientSide("MaxRowsSource", "the cap's attribution; it decides no answer (D12)"), + }, + } +} + +// searchExactIDsTable is D11's exact-ids fast path: the shape +// ResolvePartialID's first probe takes, special-cased to one getIssue per id. +func searchExactIDsTable() Table { + return Table{ + Op: OpGetIssue, Shape: "searchExactIDs", + Source: tyIssueFilter, Target: tyGetRequest, + Fields: bridgeEntries( + FieldEntry{Name: "IDs", Disposition: DispPath, Param: "{id}", Decoded: "ID", + Why: "one getIssue per id, bounded at MaxExactIDs; a 404 maps to the empty result the resolver expects, so resolution proceeds instead of erroring"}, + refused("ParentID", "E-IssueFilter.shapeConflict"), + refused("Limit", "E-IssueFilter.Limit@exactIDs"), + ), + } +} + +// searchParentWalkTable is D4's hierarchical descendant walk: per-level paged +// listIssues?parent= calls, with the derived-default inversion the ga-2ieek +// escalation resolved the shape contradiction with. +// +// It is written out in full rather than spread from issueFilterBridgeRefusals, +// because this shape is where the two bridges stop agreeing: the walk carries +// `bd list`'s whole built filter, so six of its members are DERIVED defaults +// the server re-derives (DispInverted) and eleven more are explicit user filters +// listIssues publishes parameters for. The exact-ids shape still refuses every +// one of them, which is why the enumeration cannot be shared. +func searchParentWalkTable() Table { + const inversionWhy = "a derived default of workapi.BuildListFilter, re-derived server-side from the intent parameters the encoder sends in its place (D4 parent-walk inversion)" + inverted := func(name, ledger string) FieldEntry { + return FieldEntry{Name: name, Disposition: DispInverted, Ledger: ledger, Why: inversionWhy} + } + walkRefusal := func(name string) FieldEntry { + return refused(name, "P-IssueFilter."+name) + } + return Table{ + Op: OpListIssues, Shape: "searchParentWalk", + Source: tyIssueFilter, Target: tyListRequest, + Fields: []FieldEntry{ + paramTo("ParentID", "parent", "ParentID"), + refused("IDs", "E-IssueFilter.shapeConflict"), + + // The derived defaults, in the order the inversion compares them. + inverted("ExcludeStatus", "P-IssueFilter.ExcludeStatus"), + inverted("Pinned", "P-IssueFilter.Pinned"), + inverted("IsTemplate", "P-IssueFilter.IsTemplate"), + inverted("ExcludeTypes", "P-IssueFilter.ExcludeTypes"), + inverted("Ephemeral", "P-IssueFilter.Ephemeral"), + inverted("SkipWisps", "P-IssueFilter.SkipWisps"), + + // The explicit user filters, under their documented parameters. The + // two status members share one parameter because the wire's `status` + // is the comma-separated spelling BOTH of them came from: a single + // name lands on Status, several land on Statuses, and the operation's + // decoder splits the value back the same way. + paramTo("Status", "status", "Status"), + paramTo("Statuses", "status", "Status"), + paramTo("IssueType", "type", "IssueType"), + paramTo("Assignee", "assignee", "Assignee"), + paramTo("Labels", "label", "Labels"), + paramTo("LabelsAny", "label_any", "LabelsAny"), + paramTo("ExcludeLabels", "exclude_label", "ExcludeLabels"), + paramTo("CreatedBefore", "created_before", "CreatedBefore"), + paramTo("CreatedAfter", "created_after", "CreatedAfter"), + paramTo("MetadataFields", "metadata_field", "MetadataFields"), + paramTo("HasMetadataKey", "has_metadata_key", "HasMetadataKey"), + + clientSide("Limit", + "the walk asks for every descendant at each level (the CLI sets Limit=0 so no level is truncated), and unlimited maps to PAGING TO EXHAUSTION rather than to limit=0, which the server refuses outright off loopback. The pager owns the per-page `limit`"), + clientSide("MaxRows", + "the wire publishes no max_rows, so the pager enforces the cap during page accumulation and synthesizes issueops.ErrTooManyRows — the sentinel `bd list` classifies into exit 2 (D12)"), + clientSide("MaxRowsSource", "the cap's attribution, read back by the synthesized refusal's text; it decides no answer (D12)"), + + dropped("SortBy", "P-IssueFilter.SortBy", + "the walk accumulates every level into a map keyed by id (findAllDescendants), so no per-level order survives into the answer at all — this is a drop with nothing to drop"), + dropped("SortDesc", "P-IssueFilter.SortDesc", + "the same absence as SortBy, from the other half of the same order"), + dropped("SkipLabels", "P-IssueFilter.SkipLabels", + "the wire hydrates labels either way; dropping the opt-out costs a join and hands the caller more data, never less"), + dropped("SkipCounts", "P-IssueFilter.SkipCounts", + "the wire hydrates the three cardinalities either way, and EVERY text rendering of `bd list` sets this — refusing would kill the walk's default rendering, which is the one thing D4 requires it to serve"), + + walkRefusal("Priority"), + walkRefusal("LabelPattern"), + walkRefusal("LabelRegex"), + walkRefusal("TitleSearch"), + walkRefusal("IDPrefix"), + walkRefusal("SpecIDPrefix"), + walkRefusal("TitleContains"), + walkRefusal("DescriptionContains"), + walkRefusal("NotesContains"), + walkRefusal("ExternalRefContains"), + walkRefusal("ExternalRef"), + walkRefusal("UpdatedAfter"), + walkRefusal("UpdatedBefore"), + walkRefusal("ClosedAfter"), + walkRefusal("ClosedBefore"), + walkRefusal("StartedAfter"), + walkRefusal("StartedBefore"), + walkRefusal("AfterCreatedAt"), + walkRefusal("AfterID"), + walkRefusal("AfterPriority"), + walkRefusal("EmptyDescription"), + walkRefusal("NoAssignee"), + walkRefusal("NoLabels"), + walkRefusal("PriorityMin"), + walkRefusal("PriorityMax"), + walkRefusal("SourceRepo"), + walkRefusal("EphemeralTier"), + walkRefusal("IsBlocked"), + walkRefusal("NoParent"), + walkRefusal("MolType"), + walkRefusal("WispType"), + walkRefusal("Deferred"), + walkRefusal("DeferAfter"), + walkRefusal("DeferBefore"), + walkRefusal("DueAfter"), + walkRefusal("DueBefore"), + walkRefusal("Overdue"), + walkRefusal("IncludeDependencies"), + walkRefusal("NoIDShrink"), + walkRefusal("Offset"), + walkRefusal("Lite"), + }, + } +} + +// bridgeEntries prefixes a shape's own entries to the shared IssueFilter +// refusal enumeration. +// +// The enumeration it expands is written out by hand in ledger_fields.go, and it +// derives nothing from the struct — which is what leaves a newly added upstream +// field unclassified and therefore caught. Only the exact-ids shape uses it now: +// the descendant walk stopped sharing the enumeration when D4's inversion gave +// six of those members a derived-default reading and eleven more a documented +// parameter, and a helper that spread one list across two shapes that no longer +// agree would be hiding the disagreement rather than recording it. +func bridgeEntries(shape ...FieldEntry) []FieldEntry { + out := make([]FieldEntry, 0, len(issueFilterBridgeRefusals)+len(shape)) + out = append(out, shape...) + for _, name := range issueFilterBridgeRefusals { + out = append(out, refused(name, "E-IssueFilter."+name)) + } + return out +} diff --git a/internal/httpclient/helpers_test.go b/internal/httpclient/helpers_test.go new file mode 100644 index 000000000..def45f212 --- /dev/null +++ b/internal/httpclient/helpers_test.go @@ -0,0 +1,20 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore test helpers@49d1df2f6) +// to OSS beads under the MIT license. + +package httpclient + +import "testing" + +// ptr returns a pointer to v (test helper lifted alongside credential_test.go). +func ptr[T any](v T) *T { return &v } + +// testTarget builds a minimal, valid Target for tests that only care about +// save/load/remove round-tripping the sidecar and not about any particular +// server identity. It carries no CAFile and no ExpectProjectID, matching the +// "connect with nothing pinned yet" shape — callers that need a specific +// field set (e.g. an absolute CAFile) build their own Target literal instead +// of asking this helper to grow a parameter for every case. +func testTarget(t *testing.T) Target { + t.Helper() + return Target{BaseURL: mustParseURL(t, "https://example.com")} +} diff --git a/internal/httpclient/target.go b/internal/httpclient/target.go new file mode 100644 index 000000000..81a482b23 --- /dev/null +++ b/internal/httpclient/target.go @@ -0,0 +1,156 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/target.go@49d1df2f6) +// to OSS beads under the MIT license. +package httpclient + +import ( + "encoding/json" + "errors" + "fmt" + "net/url" + "os" + "path/filepath" +) + +// TargetFileName is the per-user, untracked activation sidecar that names the +// server this workspace is attached to. metadata.json is git-tracked by design +// and selects the backend; the URL and the identity pin are per-user state and +// live beside it, following the proxied_server_client_info.json precedent +// (design D1). +const TargetFileName = "http_target.json" + +// ErrNotConnected reports a workspace that selects the http backend but has no +// activation sidecar, so there is no server to dial. +var ErrNotConnected = errors.New("no http target configured for this workspace; run `bd connect `") + +// Target is the resolved endpoint for one workspace (design D5). +type Target struct { + // BaseURL is the server mount root (scheme http or https). + BaseURL *url.URL + // ExpectProjectID pins the workspace identity recorded at `bd connect`; "" + // skips the check. It is compared against ContextResponse.project_id at + // handshake (D6). + ExpectProjectID string + // CAFile names a PEM file that becomes the ENTIRE trusted root pool for + // this target — not an addition to the system store — set by + // `bd connect --ca-file `. "" leaves this target on the system + // roots. MUST BE ABSOLUTE: `bd connect` resolves the flag's path with + // filepath.Abs before writing it, and SaveTarget and LoadTarget both + // refuse a relative one rather than resolving it against whatever + // directory bd happens to run in. BEADS_HTTP_CA_FILE (see TransportFor / CAFileEnv), when its + // host-scoped pattern matches this target, overrides this per the + // documented precedence — env beats sidecar, the same rung order the + // bearer ladder uses, but the two disagreeing is a refusal, not a silent + // override. This field exists for a private CA with no name constraints + // (the Gas City Beads Serve CA) that must never be trusted for any host + // but this one, so it must never be installed system-wide or exported via + // SSL_CERT_FILE. + CAFile string +} + +// String renders the target for error text. A zero Target renders empty, which +// is what keeps a backstop refusal from naming a server it never resolved. +func (t Target) String() string { + if t.BaseURL == nil { + return "" + } + return t.BaseURL.String() +} + +// targetFile is the on-disk sidecar. `api` is recorded so a future path major +// can be detected without a handshake; D6 still gates on the server's own +// api_version. +type targetFile struct { + URL string `json:"url"` + ExpectProjectID string `json:"expect_project_id,omitempty"` + API string `json:"api,omitempty"` + // CAFile mirrors Target.CAFile; see that field's doc for the trust model + // and TransportFor for the env-vs-sidecar precedence. + CAFile string `json:"ca_file,omitempty"` +} + +// TargetPath is the sidecar's location for a workspace. +func TargetPath(beadsDir string) string { + return filepath.Join(beadsDir, TargetFileName) +} + +// LoadTarget reads the activation sidecar. It is deliberately the minimal read +// the Open path needs — resolution order (`--server-url`, BEADS_SERVER_URL, the +// provider ladder) and the whole `bd connect` write path are owned elsewhere. +// A missing sidecar is ErrNotConnected, not a nil result: an http workspace +// with no target cannot be opened at all. +func LoadTarget(beadsDir string) (Target, error) { + path := TargetPath(beadsDir) + data, err := os.ReadFile(path) // #nosec G304 - controlled path + if os.IsNotExist(err) { + return Target{}, ErrNotConnected + } + if err != nil { + return Target{}, fmt.Errorf("reading %s: %w", TargetFileName, err) + } + var f targetFile + if err := json.Unmarshal(data, &f); err != nil { + return Target{}, fmt.Errorf("parsing %s: %w", TargetFileName, err) + } + if f.URL == "" { + return Target{}, fmt.Errorf("%s names no url; re-run `bd connect `", TargetFileName) + } + u, err := url.Parse(f.URL) + if err != nil { + return Target{}, fmt.Errorf("parsing url in %s: %w", TargetFileName, err) + } + if u.Scheme != "http" && u.Scheme != "https" { + return Target{}, fmt.Errorf("url in %s has scheme %q; want http or https", TargetFileName, u.Scheme) + } + if err := checkCAFileAbsolute(f.CAFile); err != nil { + return Target{}, err + } + return Target{BaseURL: u, ExpectProjectID: f.ExpectProjectID, CAFile: f.CAFile}, nil +} + +// checkCAFileAbsolute refuses a relative ca_file (see Target.CAFile). LoadTarget +// and SaveTarget share it, so a sidecar can never be written holding a value +// every later load would refuse. +func checkCAFileAbsolute(caFile string) error { + if caFile != "" && !filepath.IsAbs(caFile) { + return fmt.Errorf( + "ca_file in %s is %q, a relative path; it must be absolute, because resolving it against the current directory would pick a different file depending on where bd was run — re-run `bd connect --ca-file` to record an absolute path", + TargetFileName, caFile) + } + return nil +} + +// SaveTarget writes the sidecar 0600, beside metadata.json. It exists so tests +// and the connect command share one encoder; the connect UX itself (gitignore +// coverage, identity verification, conversion consent) is not here. It refuses +// a relative CAFile before writing anything, with LoadTarget's own message. +func SaveTarget(beadsDir string, t Target) error { + if err := checkCAFileAbsolute(t.CAFile); err != nil { + return err + } + f := targetFile{ExpectProjectID: t.ExpectProjectID, API: "v0", CAFile: t.CAFile} + if t.BaseURL != nil { + f.URL = t.BaseURL.String() + } + data, err := json.MarshalIndent(f, "", " ") + if err != nil { + return fmt.Errorf("marshaling %s: %w", TargetFileName, err) + } + if err := os.WriteFile(TargetPath(beadsDir), data, 0o600); err != nil { + return fmt.Errorf("writing %s: %w", TargetFileName, err) + } + return nil +} + +// RemoveTarget deletes the activation sidecar, reporting whether one was there. +// It is `bd connect --clear`'s whole write: detaching is a per-user act, so it +// must never touch the tracked metadata.json that selects the backend. +func RemoveTarget(beadsDir string) (bool, error) { + err := os.Remove(TargetPath(beadsDir)) + if os.IsNotExist(err) { + return false, nil + } + if err != nil { + return false, fmt.Errorf("removing %s: %w", TargetFileName, err) + } + return true, nil +} diff --git a/internal/httpclient/target_test.go b/internal/httpclient/target_test.go new file mode 100644 index 000000000..783c54438 --- /dev/null +++ b/internal/httpclient/target_test.go @@ -0,0 +1,139 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/target_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package httpclient + +import ( + "errors" + "os" + "path/filepath" + "strings" + "testing" +) + +// TestRemoveTarget is `bd connect --clear`'s whole write. Detaching is per-user, +// so it must be exactly one file removal — a workspace still selects whatever +// backend its tracked metadata.json says after it. +func TestRemoveTarget(t *testing.T) { + t.Run("removes the sidecar and nothing else", func(t *testing.T) { + dir := t.TempDir() + metadata := filepath.Join(dir, "metadata.json") + if err := os.WriteFile(metadata, []byte(`{"backend":"http"}`), 0o600); err != nil { + t.Fatalf("seed metadata.json: %v", err) + } + if err := SaveTarget(dir, testTarget(t)); err != nil { + t.Fatalf("SaveTarget: %v", err) + } + + removed, err := RemoveTarget(dir) + if err != nil { + t.Fatalf("RemoveTarget: %v", err) + } + if !removed { + t.Error("RemoveTarget reported nothing removed, but a sidecar was there") + } + if _, err := os.Stat(TargetPath(dir)); !os.IsNotExist(err) { + t.Errorf("sidecar still present: %v", err) + } + body, err := os.ReadFile(metadata) + if err != nil || string(body) != `{"backend":"http"}` { + t.Errorf("metadata.json = %q (%v); --clear must not touch the tracked file", body, err) + } + }) + + t.Run("no sidecar is not an error", func(t *testing.T) { + removed, err := RemoveTarget(t.TempDir()) + if err != nil { + t.Fatalf("RemoveTarget on an unconnected workspace: %v", err) + } + if removed { + t.Error("RemoveTarget reported a removal it did not make") + } + }) +} + +// TestSaveTargetHoldsNoToken pins the one thing the sidecar file format +// guarantees: it is per-user, untracked state naming a server, and a credential +// has no home in it. A URL with embedded userinfo would smuggle one in. +func TestSaveTargetHoldsNoToken(t *testing.T) { + dir := t.TempDir() + if err := SaveTarget(dir, testTarget(t)); err != nil { + t.Fatalf("SaveTarget: %v", err) + } + body, err := os.ReadFile(TargetPath(dir)) + if err != nil { + t.Fatalf("read sidecar: %v", err) + } + for _, field := range []string{"token", "password", "authorization"} { + if strings.Contains(strings.ToLower(string(body)), field) { + t.Errorf("sidecar carries a %q field:\n%s", field, body) + } + } +} + +// TestLoadTargetRejectsRelativeCAFile is finding 3: a relative ca_file in the +// sidecar must be refused with a clear error rather than resolved against +// whatever directory `bd` happens to be run from, which would silently pick a +// different file depending on the caller's cwd. +func TestLoadTargetRejectsRelativeCAFile(t *testing.T) { + dir := t.TempDir() + sidecar := `{"url":"https://example.com","ca_file":"relative/ca.pem"}` + if err := os.WriteFile(TargetPath(dir), []byte(sidecar), 0o600); err != nil { + t.Fatalf("seed sidecar: %v", err) + } + _, err := LoadTarget(dir) + if err == nil { + t.Fatal("LoadTarget accepted a relative ca_file") + } + if !strings.Contains(err.Error(), "relative/ca.pem") { + t.Errorf("error %q does not name the offending path", err) + } + if !strings.Contains(err.Error(), "absolute") { + t.Errorf("error %q does not say the path must be absolute", err) + } +} + +// TestSaveTargetRejectsRelativeCAFile is LoadTarget's refusal on the write +// side: a relative ca_file must never reach the sidecar, where every later +// LoadTarget would refuse it and leave the workspace unopenable. The refusal is +// LoadTarget's own message, and it writes nothing, so the workspace stays +// unconnected rather than holding a sidecar it cannot load. +func TestSaveTargetRejectsRelativeCAFile(t *testing.T) { + dir := t.TempDir() + saveErr := SaveTarget(dir, Target{BaseURL: mustParseURL(t, "https://example.com"), CAFile: "relative/ca.pem"}) + if saveErr == nil { + t.Fatal("SaveTarget accepted a relative ca_file") + } + if _, err := LoadTarget(dir); !errors.Is(err, ErrNotConnected) { + t.Errorf("LoadTarget after the refused save = %v, want ErrNotConnected: nothing may be written", err) + } + + seeded := t.TempDir() + sidecar := `{"url":"https://example.com","ca_file":"relative/ca.pem"}` + if err := os.WriteFile(TargetPath(seeded), []byte(sidecar), 0o600); err != nil { + t.Fatalf("seed sidecar: %v", err) + } + _, loadErr := LoadTarget(seeded) + if loadErr == nil || saveErr.Error() != loadErr.Error() { + t.Errorf("SaveTarget refused with %q; want LoadTarget's own refusal %q", saveErr, loadErr) + } +} + +// TestLoadTargetAcceptsAbsoluteCAFile is the control for the above: an +// absolute ca_file round-trips through LoadTarget unchanged. +func TestLoadTargetAcceptsAbsoluteCAFile(t *testing.T) { + dir := t.TempDir() + abs := filepath.Join(secureTempDir(t), "ca.pem") + if err := os.WriteFile(abs, []byte("whatever"), 0o600); err != nil { + t.Fatalf("seed ca file: %v", err) + } + if err := SaveTarget(dir, Target{BaseURL: mustParseURL(t, "https://example.com"), CAFile: abs}); err != nil { + t.Fatalf("SaveTarget: %v", err) + } + got, err := LoadTarget(dir) + if err != nil { + t.Fatalf("LoadTarget with an absolute ca_file: %v", err) + } + if got.CAFile != abs { + t.Errorf("CAFile = %q, want %q", got.CAFile, abs) + } +} diff --git a/internal/httpclient/wire/BUILD.bazel b/internal/httpclient/wire/BUILD.bazel new file mode 100644 index 000000000..3d520f9c4 --- /dev/null +++ b/internal/httpclient/wire/BUILD.bazel @@ -0,0 +1,60 @@ +load("@rules_go//go:def.bzl", "go_library", "go_test") + +go_library( + name = "wire", + srcs = [ + "client.go", + "credential.go", + "doc.go", + "handshake.go", + "paths.go", + "problem.go", + "revision_tolerance.go", + "stream.go", + "writes.go", + ], + importpath = "github.com/steveyegge/beads/internal/httpclient/wire", + visibility = ["//:__subpackages__"], + deps = [ + "//internal/httpapi/apigen", + "//issueops", + "@org_golang_x_net//http/httpguts", + ], +) + +go_test( + name = "wire_test", + srcs = [ + "client_test.go", + "credential_source_test.go", + "credential_test.go", + "handshake_test.go", + "handshake_wire_revision_test.go", + "helpers_test.go", + "paths_test.go", + "problem_test.go", + "problem_wire_revision_test.go", + "project_stamp_test.go", + "revision_tolerance_test.go", + "skew_test.go", + "stream_test.go", + "vocabulary_test.go", + "writes_batch_cap_test.go", + "writes_twospeed_test.go", + ], + data = [ + "//cmd/bd:go_srcs", + "//internal/httpapi/wireshape:testdata/golden.json", + "//internal/httpclient:go_srcs", + ] + glob(["*.go"]), + embed = [":wire"], + deps = [ + "//internal/httpapi", + "//internal/httpapi/apigen", + "//internal/httpapi/spec", + "//internal/httpclient/encode", + "//internal/types", + "//issueops", + "@in_gopkg_yaml_v3//:yaml_v3", + ], +) diff --git a/internal/httpclient/wire/client.go b/internal/httpclient/wire/client.go new file mode 100644 index 000000000..2c6fd6263 --- /dev/null +++ b/internal/httpclient/wire/client.go @@ -0,0 +1,482 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/client.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "net/url" + "strconv" + "strings" + "time" + + "golang.org/x/net/http/httpguts" +) + +// ProjectIDHeader names the optional per-request workspace-identity stamp this +// client sends, spelled exactly as the server's httpapi.ProjectIDHeader and held +// to it by TestProjectIDHeaderMatchesTheServerConstant. A client that pinned an +// expected project id at `bd connect` stamps every request with it, so a server +// whose identity has drifted refuses the request (400 project_mismatch) before it +// can read or write the wrong workspace, instead of silently answering it. The +// header is redeclared here rather than imported because internal/httpapi is the +// SERVER — importing it would drag the storage engine into every client process. +const ProjectIDHeader = "Bd-Project-Id" + +// WireRevisionHeader names the per-request wire-shape declaration this client +// sends on every request, spelled exactly as the server's own +// httpapi.WireRevisionHeader (held to it by +// TestTheProjectIdentityVocabularyMatchesTheServer). Redeclared rather than +// imported for ProjectIDHeader's reason: internal/httpapi is the SERVER. +const WireRevisionHeader = "Bd-Wire-Revision" + +const ( + // DefaultUserAgent identifies the backend rather than the build. The build + // version lives in package main, which nothing here may import, so the + // activation layer overrides this with the stamped one. + DefaultUserAgent = "bd-http-backend/v0" + // DefaultMaxResponseBytes bounds one response body. A full page of issues + // with long descriptions is a few megabytes; anything at this size is a URL + // pointing at something that is not a bd serve, and reading it into memory + // is the actual damage. + DefaultMaxResponseBytes = 32 << 20 + // DefaultMaxRetryAfter bounds how long a 503's Retry-After may ask for. The + // header is server-controlled input; see retryAfter. + DefaultMaxRetryAfter = 30 * time.Second + // DefaultTimeout is the per-request ceiling for a client this package built. + // A caller's context still wins when it is shorter, and an injected + // *http.Client keeps its own. Exported so a caller that must build its own + // *http.Client — to layer in a custom RoundTripper such as the one + // httpstore.TransportFor returns — can match this default rather than + // silently dropping it. + DefaultTimeout = 60 * time.Second +) + +// Options tunes the client. The zero value is usable: every field falls back to +// the Default* constants above. +type Options struct { + // HTTPClient is used as given except for CheckRedirect, which is always + // forced (see New). Nil builds one. + HTTPClient *http.Client + // UserAgent is sent on every request. + UserAgent string + // MaxResponseBytes bounds one response body. + MaxResponseBytes int64 + // MaxRetryAfter bounds the Retry-After a 503 may ask for. + MaxRetryAfter time.Duration + // ExpectProjectID pins workspace identity, recorded at `bd connect`. The + // handshake compares it against ContextResponse.project_id; "" skips the + // check. + ExpectProjectID string +} + +// Client is one workspace's connection to one bd serve. +// +// It is safe for concurrent use: everything below the handshake cache is +// request-scoped, and the cache takes a mutex. +type Client struct { + base *url.URL + hc *http.Client + creds CredentialProvider + userAgent string + maxBytes int64 + maxRetry time.Duration + + handshake handshakeCache + expectID string +} + +// New builds a client for base. +// +// creds may be nil, which is the tip OSS server's loopback-trust posture: no +// Authorization header is sent and a 401 is never retried, because there is +// nothing to rotate. +func New(base *url.URL, creds CredentialProvider, opts Options) (*Client, error) { + if base == nil { + return nil, errors.New("no server URL") + } + if err := validateBase(base); err != nil { + return nil, err + } + + hc := opts.HTTPClient + if hc == nil { + hc = &http.Client{Timeout: DefaultTimeout} + } else { + clone := *hc + hc = &clone + } + // Forced on the copy, never on the caller's client. A 30x that the stdlib + // followed would replay the Authorization header at whatever host the + // Location named, which is the one thing a bearer token must never do. + hc.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse } + + c := &Client{ + base: normalizeBase(base), + hc: hc, + creds: creds, + userAgent: opts.UserAgent, + maxBytes: opts.MaxResponseBytes, + maxRetry: opts.MaxRetryAfter, + expectID: opts.ExpectProjectID, + } + if c.userAgent == "" { + c.userAgent = DefaultUserAgent + } + if c.maxBytes <= 0 { + c.maxBytes = DefaultMaxResponseBytes + } + if c.maxRetry <= 0 { + c.maxRetry = DefaultMaxRetryAfter + } + // A pinned project id becomes a header value on EVERY request, so a value + // that is not a legal header value has to be caught here, at open, and refused + // LOUDLY — never stamped-and-hoped or silently skipped, which would turn a + // corrupt sidecar into either a per-request transport failure or an unenforced + // workspace. httpguts.ValidHeaderFieldValue is the byte-level RFC 7230 rule + // net/http itself applies; the package's own isControlRune check is layered on + // top of it because that rule is byte-based and misses the multi-byte control + // runes (the C1 block, U+2028/U+2029) an escape-injection would hide in. + if c.expectID != "" && + (!httpguts.ValidHeaderFieldValue(c.expectID) || strings.ContainsFunc(c.expectID, isControlRune)) { + return nil, &InvalidProjectIDError{ServerURL: c.base.Redacted(), ProjectID: c.expectID} + } + return c, nil +} + +// BaseURL is the server mount root this client dials. +func (c *Client) BaseURL() *url.URL { + u := *c.base + return &u +} + +// validateBase refuses the shapes that would make every later URL wrong or +// unsafe. +func validateBase(base *url.URL) error { + switch base.Scheme { + case "http", "https": + default: + return fmt.Errorf("server URL %q: scheme must be http or https", base.Redacted()) + } + if base.Host == "" { + return fmt.Errorf("server URL %q: no host", base.Redacted()) + } + // Refused rather than stripped. A credential in the URL would be echoed by + // every error that names the server, and the sidecar this URL comes from is + // specified to hold no token at all. + if base.User != nil { + return errors.New("server URL carries embedded credentials; put the token in the credential source, not the URL") + } + if base.RawQuery != "" || base.Fragment != "" { + return fmt.Errorf("server URL %q: a query or fragment is not a mount root", base.Redacted()) + } + return nil +} + +func normalizeBase(base *url.URL) *url.URL { + u := *base + // A trailing slash on the mount root would join to a doubled separator. + for len(u.Path) > 1 && u.Path[len(u.Path)-1] == '/' { + u.Path = u.Path[:len(u.Path)-1] + u.RawPath = "" + } + if u.Path == "/" { + u.Path = "" + } + return &u +} + +// Request is one call on the v0 surface: the operation being dialed, where it +// lives, and what it carries. +// +// Path comes from the builders in paths.go and is already escaped. IssueID and +// DependsOnID are not sent — they are what the problem mapper needs to rebuild +// the typed conflicts whose extension members the server leaves out because the +// request already said them. +type Request struct { + Op string + Method string + Path string + Query url.Values + // Body is marshaled as JSON when non-nil. + Body any + + IssueID string + DependsOnID string +} + +// Do issues r and decodes a 2xx body into out, which may be nil for a response +// the caller does not read. +// +// Non-2xx returns *ProblemError, unwrapping to the canonical sentinel for its +// code. Everything before a response — a dial failure, a refused redirect, an +// oversized body — returns its own typed error, because none of those is the +// server answering. +// +// Do does NOT pre-flight. The dispatch layer calls Preflight first, and the +// separation is deliberate: the refusal taxonomy has to refuse a post-baseline +// operation before a request is built at all, and folding the handshake in here +// would make every transport test carry one. +func (c *Client) Do(ctx context.Context, r Request, out any) error { + var body []byte + if r.Body != nil { + var err error + body, err = json.Marshal(r.Body) + if err != nil { + return fmt.Errorf("%s: encoding request body: %w", r.Op, err) + } + } + + u, err := c.resolve(r.Path, r.Query) + if err != nil { + return fmt.Errorf("%s: %w", r.Op, err) + } + + res, err := c.roundTrip(ctx, r, u, body) + if err != nil { + return err + } + + // The rotation window, and the whole of it. The server re-reads its token + // file on a ~1s gate, so a client rolled mid-flight 401s once and succeeds + // on the retry; a second 401 is a credential this server does not accept. + if res.status == http.StatusUnauthorized && c.creds != nil { + retry, err := c.creds.Refresh(ctx) + if err != nil { + // Fail closed: a credential source that errored is not a license to + // send the stale one again, and it is certainly not a license to + // send none. + return fmt.Errorf("%s: refreshing the credential for bd serve at %s: %w", r.Op, c.base.Redacted(), err) + } + if retry { + if res, err = c.roundTrip(ctx, r, u, body); err != nil { + return err + } + } + } + + if res.status < 200 || res.status >= 300 { + prob := mapProblem(c.target(r), res.status, res.header, res.body, c.maxRetry) + // A refused credential should name the ladder rung it came from (design + // D7). The source is a client-side fact the provider knows, not something + // the server said, so it is attached here rather than parsed from the body. + if res.status == http.StatusUnauthorized { + prob.CredentialSource = credentialSource(c.creds) + } + return prob + } + if out == nil { + return nil + } + if len(bytes.TrimSpace(res.body)) == 0 { + return fmt.Errorf("%s: bd serve at %s answered %d with an empty body", r.Op, c.base.Redacted(), res.status) + } + decodeBody := res.body + // A pre-#6053 server's `revision` is still a bare JSON integer; every + // apigen response type that carries one declares it `string`, so decoding + // straight into out would fail with an untyped json.UnmarshalTypeError on + // exactly the servers ClientMinWireRevision exists to keep talking to. See + // revision_tolerance.go. + if revisionBearingResponse(out) && c.serverPredatesRevisionStrings() { + decodeBody = tolerateLegacyRevisionNumbers(decodeBody, out) + } + if err := json.Unmarshal(decodeBody, out); err != nil { + return fmt.Errorf("%s: decoding the response from bd serve at %s: %w", r.Op, c.base.Redacted(), err) + } + return nil +} + +func (c *Client) target(r Request) target { + return target{op: r.Op, serverURL: c.base.Redacted(), issueID: r.IssueID, dependsOnID: r.DependsOnID, expectID: c.expectID} +} + +// credentialSourceReporter is the optional half of a CredentialProvider: a +// provider that can name the ladder rung its current credential came from. It is +// kept off the CredentialProvider interface itself so a no-auth or third-party +// provider that cannot report a source is not forced to — such a provider simply +// yields no name and the 401 reads as it did before. +type credentialSourceReporter interface { + Source() string +} + +// credentialSource is the provider's current credential provenance, or "" when +// there is no provider or it cannot report one. +func credentialSource(cp CredentialProvider) string { + if r, ok := cp.(credentialSourceReporter); ok { + return r.Source() + } + return "" +} + +// resolve joins an already-escaped path and a query onto the base URL. +func (c *Client) resolve(path string, query url.Values) (*url.URL, error) { + if path == "" { + return nil, errors.New("no request path") + } + u := c.base.JoinPath(path) + if len(query) > 0 { + u.RawQuery = query.Encode() + } + return u, nil +} + +type response struct { + status int + header http.Header + body []byte +} + +// roundTrip issues one HTTP request and reads its whole bounded body. +// +// Reading the body here rather than streaming it to the caller is what makes +// the 401 retry above expressible at all: both attempts are then symmetric, and +// the request body is a []byte that can be replayed. The size cap is what makes +// that safe. +func (c *Client) roundTrip(ctx context.Context, r Request, u *url.URL, body []byte) (*response, error) { + var rdr io.Reader + if body != nil { + rdr = bytes.NewReader(body) + } + req, err := http.NewRequestWithContext(ctx, r.Method, u.String(), rdr) + if err != nil { + return nil, fmt.Errorf("%s: %w", r.Op, err) + } + req.Header.Set("Accept", "application/json, application/problem+json") + if body != nil { + req.Header.Set("Content-Type", "application/json") + } + if err := c.stampRequest(ctx, r.Op, req); err != nil { + return nil, err + } + + //nolint:gosec // G704: the URL is the workspace's configured server, resolved from the sidecar or --server-url; dialing it IS the feature. + resp, err := c.hc.Do(req) + if err != nil { + return nil, &ConnectError{Op: r.Op, ServerURL: c.base.Redacted(), Err: err} + } + defer func() { _ = resp.Body.Close() }() + + if resp.StatusCode >= 300 && resp.StatusCode < 400 { + return nil, redirectRefused(r.Op, c.base.Redacted(), resp) + } + + // One byte past the cap, so an oversized body is detected rather than + // silently truncated into a document that happens to parse. + raw, err := io.ReadAll(io.LimitReader(resp.Body, c.maxBytes+1)) + if err != nil { + return nil, &ConnectError{Op: r.Op, ServerURL: c.base.Redacted(), Err: err} + } + if int64(len(raw)) > c.maxBytes { + return nil, &ResponseTooLargeError{Op: r.Op, ServerURL: c.base.Redacted(), Limit: c.maxBytes} + } + return &response{status: resp.StatusCode, header: resp.Header, body: raw}, nil +} + +// stampRequest applies the headers every request on this surface shares: the +// backend User-Agent, the workspace-identity stamp, and the credential. +// +// It is shared by roundTrip and the stream door (stream.go) because both stamp +// the SAME three things — the Accept header and any request body are the only +// parts that differ, and the caller sets those. The Bd-Project-Id stamp rides +// EVERY request through here — the five baseline reads, both attempts of the 401 +// retry, and the watch connect — because a server that has drifted to a +// different project must refuse before it reads or writes rather than answer +// silently against the wrong workspace (projectExempt is false for events:watch, +// so the stream is stamped like everything else). The value was validated at +// New, so Set cannot corrupt the header. +func (c *Client) stampRequest(ctx context.Context, op string, req *http.Request) error { + req.Header.Set("User-Agent", c.userAgent) + // The client's own declared wire shape (see ClientWireRevision's doc), + // stamped on every request including the context fetch itself: a server + // whose min_client_wire_revision has moved past what this build speaks + // refuses with the typed wire_revision_unsupported problem rather than + // silently answering a body this client has already said it cannot decode. + req.Header.Set(WireRevisionHeader, strconv.Itoa(ClientWireRevision)) + if c.expectID != "" { + req.Header.Set(ProjectIDHeader, c.expectID) + } + if c.creds != nil { + if err := c.creds.Authorize(ctx, req); err != nil { + return fmt.Errorf("%s: authorizing the request to bd serve at %s: %w", op, c.base.Redacted(), err) + } + } + return nil +} + +// ConnectError is a failure to get an answer at all: DNS, dial, TLS, a reset +// mid-body, or the caller's own context expiring. It is deliberately not a +// ProblemError — the server said nothing. +type ConnectError struct { + Op string + ServerURL string + Err error +} + +func (e *ConnectError) Error() string { + return fmt.Sprintf("cannot reach bd serve at %s: %v", e.ServerURL, e.Err) +} + +func (e *ConnectError) Unwrap() error { return e.Err } + +// ErrRedirected reports that the server answered with a redirect, which this +// client refuses to follow. +var ErrRedirected = errors.New("bd serve answered with a redirect") + +// RedirectRefusedError is a 3xx this client did not follow. Following it would +// replay the Authorization header at whatever host the Location named; a bd +// serve does not redirect, so a 30x means the URL points at something else — +// a proxy login page, a CDN, an HTTPS upgrade — and saying so beats leaking a +// token to find out. +type RedirectRefusedError struct { + Op string + ServerURL string + Status int + // Location is the redirect target with its query and any userinfo stripped: + // it is server-controlled text on its way into a log line, and the scheme, + // host and path are the whole of what diagnoses this. + Location string +} + +func (e *RedirectRefusedError) Error() string { + if e.Location == "" { + return fmt.Sprintf("%s: bd serve at %s answered %d; redirects are refused", e.Op, e.ServerURL, e.Status) + } + return fmt.Sprintf("%s: bd serve at %s answered %d redirecting to %s; redirects are refused (the URL does not point at a bd serve)", + e.Op, e.ServerURL, e.Status, e.Location) +} + +func (e *RedirectRefusedError) Unwrap() error { return ErrRedirected } + +func redirectRefused(op, serverURL string, resp *http.Response) *RedirectRefusedError { + e := &RedirectRefusedError{Op: op, ServerURL: serverURL, Status: resp.StatusCode} + if loc, err := url.Parse(resp.Header.Get("Location")); err == nil && loc.String() != "" { + loc.User = nil + loc.RawQuery = "" + loc.Fragment = "" + e.Location = loc.Redacted() + } + return e +} + +// ErrResponseTooLarge reports that a response body exceeded the client's cap. +var ErrResponseTooLarge = errors.New("response from bd serve is too large") + +// ResponseTooLargeError is a body past Options.MaxResponseBytes. The cap is +// named in the text because raising it is the only recovery, and because the +// far likelier cause is a URL that does not point at a bd serve at all. +type ResponseTooLargeError struct { + Op string + ServerURL string + Limit int64 +} + +func (e *ResponseTooLargeError) Error() string { + return fmt.Sprintf("%s: response from bd serve at %s exceeds the %d-byte limit", e.Op, e.ServerURL, e.Limit) +} + +func (e *ResponseTooLargeError) Unwrap() error { return ErrResponseTooLarge } diff --git a/internal/httpclient/wire/client_test.go b/internal/httpclient/wire/client_test.go new file mode 100644 index 000000000..4340f4471 --- /dev/null +++ b/internal/httpclient/wire/client_test.go @@ -0,0 +1,349 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/client_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "errors" + "fmt" + "io" + "net/http" + "net/http/httptest" + "net/url" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/internal/types" +) + +func TestEveryRequestCarriesTheUserAgentAndAcceptsBothMediaTypes(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = w.Write([]byte(`{}`)) + }) + var out map[string]any + if err := c.Do(ctx(t), Request{Op: OpGetContext, Method: http.MethodGet, Path: PathContext}, &out); err != nil { + t.Fatalf("Do: %v", err) + } + got := rec.at(t, 0).header + if ua := got.Get("User-Agent"); ua != DefaultUserAgent { + t.Errorf("User-Agent = %q, want %q", ua, DefaultUserAgent) + } + // problem+json has to be acceptable or a strict server could refuse to send + // the very document this client dispatches on. + if accept := got.Get("Accept"); !strings.Contains(accept, "application/problem+json") { + t.Errorf("Accept = %q, want it to include application/problem+json", accept) + } +} + +func TestTheUserAgentIsOverridable(t *testing.T) { + // The build version lives in package main, which this package may not + // import, so the activation layer stamps it in. + c, rec := newTestClient(t, Options{UserAgent: "bd/1.1.0 (http)"}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = w.Write([]byte(`{}`)) + }) + var out map[string]any + if err := c.Do(ctx(t), Request{Op: OpGetContext, Method: http.MethodGet, Path: PathContext}, &out); err != nil { + t.Fatalf("Do: %v", err) + } + if ua := rec.at(t, 0).header.Get("User-Agent"); ua != "bd/1.1.0 (http)" { + t.Errorf("User-Agent = %q", ua) + } +} + +func TestBodiesRoundTripThroughTheCanonicalTypes(t *testing.T) { + // apigen's wire structs are ALIASES of internal/types, so decoding a + // response is decoding into the canonical struct — no second copy of the + // issue shape exists to drift from it. + c, rec := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + if ct := r.Header.Get("Content-Type"); ct != "application/json" { + t.Errorf("request Content-Type = %q", ct) + } + _, _ = io.WriteString(w, `{"already_claimed":false,"issue":{"id":"ga-1","title":"wire the client","status":"in_progress","assignee":"me","priority":1}}`) + }) + + var out apigen.ClaimResponse + err := c.Do(ctx(t), Request{ + Op: OpClaimIssue, + Method: http.MethodPost, + Path: "/v0/beads/issues/ga-1:claim", + Body: apigen.ClaimRequest{Actor: "me"}, + IssueID: "ga-1", + }, &out) + if err != nil { + t.Fatalf("Do: %v", err) + } + + // The compiler is half the assertion: this only builds because + // apigen.Issue IS types.Issue. + var canonical types.Issue = out.Issue + if canonical.ID != "ga-1" || canonical.Title != "wire the client" { + t.Errorf("decoded issue = %+v", canonical) + } + if canonical.Assignee != "me" || canonical.Status != types.StatusInProgress { + t.Errorf("assignee/status did not decode: %q %q", canonical.Assignee, canonical.Status) + } + if body := string(rec.at(t, 0).body); !strings.Contains(body, `"actor":"me"`) { + t.Errorf("request body = %s", body) + } +} + +func TestRedirectsAreRefusedRatherThanFollowed(t *testing.T) { + // A followed 30x replays the Authorization header at whatever host the + // Location named. bd serve does not redirect, so a 30x means the URL points + // at something else and saying so beats leaking a token to find out. + for _, status := range []int{ + http.StatusMovedPermanently, http.StatusFound, http.StatusSeeOther, + http.StatusTemporaryRedirect, http.StatusPermanentRedirect, + } { + t.Run(http.StatusText(status), func(t *testing.T) { + elsewhere := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { + t.Error("the redirect target was dialed") + })) + t.Cleanup(elsewhere.Close) + + creds := &staticToken{tokens: []string{"secret-token"}} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Location", elsewhere.URL+"/login?token=leaked") + w.WriteHeader(status) + }) + + err := c.Do(ctx(t), Request{Op: OpListIssues, Method: http.MethodGet, Path: PathIssues}, &struct{}{}) + if !errors.Is(err, ErrRedirected) { + t.Fatalf("err = %v, want ErrRedirected", err) + } + var redirect *RedirectRefusedError + if !errors.As(err, &redirect) { + t.Fatalf("err is %T, want *RedirectRefusedError", err) + } + if redirect.Status != status { + t.Errorf("Status = %d, want %d", redirect.Status, status) + } + // The Location travels into a log line, so the query — which is + // where a bounce-through-a-login-page puts its secrets — is + // stripped. + if strings.Contains(redirect.Error(), "leaked") { + t.Errorf("the redirect query survived into the error: %v", redirect) + } + if !strings.Contains(redirect.Location, "/login") { + t.Errorf("Location = %q, want the path kept for diagnosis", redirect.Location) + } + if rec.count() != 1 { + t.Errorf("made %d requests, want 1", rec.count()) + } + }) + } +} + +func TestAnInjectedClientKeepsItsSettingsButNotItsRedirectPolicy(t *testing.T) { + // Forcing CheckRedirect on the caller's own *http.Client would silently + // change its behavior everywhere else it is used. + followed := &http.Client{} + base, err := url.Parse("http://127.0.0.1:1/") + if err != nil { + t.Fatalf("parse: %v", err) + } + c, err := New(base, nil, Options{HTTPClient: followed}) + if err != nil { + t.Fatalf("New: %v", err) + } + if followed.CheckRedirect != nil { + t.Error("New mutated the caller's http.Client") + } + if c.hc.CheckRedirect == nil { + t.Error("the client's copy follows redirects") + } +} + +func TestResponsesAreReadUnderAByteCap(t *testing.T) { + const cap = 512 + cases := []struct { + name string + size int + wantErr bool + }{ + {"under the cap", cap - 64, false}, + {"exactly the cap", cap, false}, + {"one byte over", cap + 1, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + // A JSON string padded to exactly the wanted size, so the "at the + // cap" case still parses and the assertion is about the cap rather + // than about the parser. + pad := strings.Repeat("x", tc.size-len(`{"v":""}`)) + body := fmt.Sprintf(`{"v":"%s"}`, pad) + c, _ := newTestClient(t, Options{MaxResponseBytes: cap}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = io.WriteString(w, body) + }) + var out struct { + V string `json:"v"` + } + err := c.Do(ctx(t), Request{Op: OpListIssues, Method: http.MethodGet, Path: PathIssues}, &out) + if tc.wantErr { + if !errors.Is(err, ErrResponseTooLarge) { + t.Fatalf("err = %v, want ErrResponseTooLarge", err) + } + var tooLarge *ResponseTooLargeError + if !errors.As(err, &tooLarge) || tooLarge.Limit != cap { + t.Errorf("err = %v, want the cap named", err) + } + return + } + if err != nil { + t.Fatalf("Do: %v", err) + } + if len(out.V) != len(pad) { + t.Errorf("body was truncated: got %d bytes, want %d", len(out.V), len(pad)) + } + }) + } +} + +func TestAnOversizedProblemBodyIsStillRefusedRatherThanParsed(t *testing.T) { + // The cap is on the transport, not on the success path: a hostile or broken + // server must not be able to spend the client's memory by failing. + c, _ := newTestClient(t, Options{MaxResponseBytes: 256}, nil, func(w http.ResponseWriter, _ *http.Request) { + problemJSON(w, http.StatusInternalServerError, `{"status":500,"code":"internal","detail":"`+strings.Repeat("x", 4096)+`"}`) + }) + err := c.Do(ctx(t), Request{Op: OpGetStats, Method: http.MethodGet, Path: PathStats}, &struct{}{}) + if !errors.Is(err, ErrResponseTooLarge) { + t.Fatalf("err = %v, want ErrResponseTooLarge", err) + } +} + +func TestTheContextTravelsWithTheRequest(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + <-r.Context().Done() + }) + cancelled, cancel := context.WithCancel(context.Background()) + go cancel() + err := c.Do(cancelled, Request{Op: OpListIssues, Method: http.MethodGet, Path: PathIssues}, &struct{}{}) + if !errors.Is(err, context.Canceled) { + t.Fatalf("err = %v, want context.Canceled", err) + } + var connect *ConnectError + if !errors.As(err, &connect) { + t.Fatalf("err is %T, want *ConnectError", err) + } +} + +func TestAnUnreachableServerIsItsOwnErrorClass(t *testing.T) { + // Not a ProblemError: the server said nothing, so there is no code to + // dispatch on and the refusal taxonomy must not try. + base, err := url.Parse("http://127.0.0.1:1") + if err != nil { + t.Fatalf("parse: %v", err) + } + c, err := New(base, nil, Options{}) + if err != nil { + t.Fatalf("New: %v", err) + } + err = c.Do(ctx(t), Request{Op: OpHealth, Method: http.MethodGet, Path: PathHealth}, &struct{}{}) + var connect *ConnectError + if !errors.As(err, &connect) { + t.Fatalf("err is %T (%v), want *ConnectError", err, err) + } + var problem *ProblemError + if errors.As(err, &problem) { + t.Error("a dial failure classified as a server refusal") + } + if !strings.Contains(connect.Error(), "cannot reach bd serve at") { + t.Errorf("Error() = %q", connect.Error()) + } +} + +func TestAnUndecodableSuccessBodyFails(t *testing.T) { + cases := []struct { + name string + body string + }{ + {"empty", ""}, + {"whitespace", " \n"}, + {"not json", "hello"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = io.WriteString(w, tc.body) + }) + var out apigen.ContextResponse + err := c.Do(ctx(t), Request{Op: OpGetContext, Method: http.MethodGet, Path: PathContext}, &out) + if err == nil { + t.Fatal("a 200 that is not the documented shape was accepted") + } + if !strings.Contains(err.Error(), OpGetContext) { + t.Errorf("err = %q, want the operation named", err) + } + }) + } +} + +func TestAResponseNobodyReadsNeedsNoBody(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNoContent) + }) + if err := c.Do(ctx(t), Request{Op: OpForgetMemory, Method: http.MethodDelete, Path: PathMemories + "/k"}, nil); err != nil { + t.Fatalf("Do: %v", err) + } +} + +func TestTheBaseURLIsValidatedAtConstruction(t *testing.T) { + cases := []struct { + name string + raw string + }{ + {"no scheme", "//example.invalid/"}, + {"wrong scheme", "ftp://example.invalid/"}, + {"file scheme", "file:///tmp/beads"}, + {"no host", "http:///v0"}, + // A credential in the URL would be echoed by every error naming the + // server, and the sidecar it comes from is specified to hold no token. + {"embedded credentials", "https://user:hunter2@example.invalid/"}, + {"query", "https://example.invalid/?db=x"}, + {"fragment", "https://example.invalid/#frag"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + u, err := url.Parse(tc.raw) + if err != nil { + t.Fatalf("parse %q: %v", tc.raw, err) + } + c, err := New(u, nil, Options{}) + if err == nil { + t.Fatalf("New(%q) returned a client (%v)", tc.raw, c.BaseURL()) + } + if strings.Contains(err.Error(), "hunter2") { + t.Errorf("the password survived into the error: %v", err) + } + }) + } + if _, err := New(nil, nil, Options{}); err == nil { + t.Error("New(nil) returned no error") + } +} + +func TestATrailingSlashOnTheMountRootDoesNotDoubleTheSeparator(t *testing.T) { + var got string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + got = r.URL.Path + _, _ = w.Write([]byte(`{}`)) + })) + t.Cleanup(srv.Close) + for _, suffix := range []string{"", "/", "///"} { + u, err := url.Parse(srv.URL + suffix) + if err != nil { + t.Fatalf("parse: %v", err) + } + c, err := New(u, nil, Options{HTTPClient: srv.Client()}) + if err != nil { + t.Fatalf("New: %v", err) + } + if err := c.Do(ctx(t), Request{Op: OpListIssues, Method: http.MethodGet, Path: PathIssues}, &struct{}{}); err != nil { + t.Fatalf("Do: %v", err) + } + if got != "/v0/beads/issues" { + t.Errorf("base %q produced path %q", srv.URL+suffix, got) + } + } +} diff --git a/internal/httpclient/wire/credential.go b/internal/httpclient/wire/credential.go new file mode 100644 index 000000000..e4e2234ec --- /dev/null +++ b/internal/httpclient/wire/credential.go @@ -0,0 +1,43 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/credential.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "net/http" +) + +// CredentialProvider authorizes outbound requests. +// +// Implementations must be safe for concurrent use, must never log or persist a +// secret, and must FAIL CLOSED: a configured source that errors aborts the +// request rather than silently downgrading to a lower rung of the ladder. That +// is the postgres credential ladder's rule +// (internal/storage/postgres/credential.go), and it is the difference between a +// misconfigured token file and an unauthenticated request nobody noticed. +// +// The interface is declared here rather than in the store package the design +// sketches it in (engdocs/design/http-client-backend.md, D5) because this is the +// only layer that consumes it; the store package aliases it, so there is still +// one type. +type CredentialProvider interface { + // Authorize adds credentials to req (Authorization: Bearer, DPoP, ...). + // A no-auth deployment — the loopback-trust OSS server, which has no token + // file at all — returns nil without modifying req. + // + // The error must not carry the credential: it travels into the client's own + // error text, which reaches logs and terminals. + Authorize(ctx context.Context, req *http.Request) error + + // Refresh is consulted after exactly one 401 on an authorized request. + // Returning retry=true re-issues that request once, through Authorize + // again; returning retry=false surfaces the 401 as it stands. + // + // This is the client half of the server's token-rotation contract + // (internal/httpapi/auth.go: the token file is re-read on a ~1s gate, so + // rotation is write {new,old}, roll the clients, drop old). A client that + // rolled mid-flight 401s once and succeeds on the retry. One retry is the + // whole window: a second 401 is a credential this server does not accept, + // and retrying it again would only turn a clear refusal into a loop. + Refresh(ctx context.Context) (retry bool, err error) +} diff --git a/internal/httpclient/wire/credential_source_test.go b/internal/httpclient/wire/credential_source_test.go new file mode 100644 index 000000000..7028e658c --- /dev/null +++ b/internal/httpclient/wire/credential_source_test.go @@ -0,0 +1,97 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/credential_source_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "errors" + "net/http" + "strings" + "testing" +) + +// sourcedToken is a CredentialProvider that can name the rung its credential came +// from — the optional Source() half the wire client consults on a 401 (design +// D7). staticToken deliberately does not implement it, so the two together cover +// both branches of credentialSource. +type sourcedToken struct { + token string + source string + retry bool + refreshN int +} + +func (s *sourcedToken) Authorize(_ context.Context, req *http.Request) error { + if s.token != "" { + req.Header.Set("Authorization", "Bearer "+s.token) + } + return nil +} + +func (s *sourcedToken) Refresh(context.Context) (bool, error) { + s.refreshN++ + return s.retry, nil +} + +func (s *sourcedToken) Source() string { return s.source } + +func TestARefusedCredentialNamesItsSource(t *testing.T) { + // The 401 the operator sees must say WHICH source held the credential the + // server refused, so they know what to rotate or fix rather than guessing + // across three rungs. + creds := &sourcedToken{token: "wrong", source: "BEADS_HTTP_TOKEN", retry: false} + c, _ := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + unauthenticated(w) + }) + + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("err = %v, want ErrUnauthenticated", err) + } + if !strings.Contains(err.Error(), "credential from BEADS_HTTP_TOKEN") { + t.Errorf("401 does not name the credential source:\n%s", err) + } + // The provenance slug is safe; the credential itself must never appear. + if strings.Contains(err.Error(), "wrong") { + t.Errorf("the credential leaked into the 401 text: %v", err) + } +} + +func TestThe401AfterTheRotationRetryStillNamesTheSource(t *testing.T) { + // The source has to survive the one rotation retry: a client that rolled its + // credential and still 401s wants the rung named on the FINAL answer, not + // dropped because a retry happened. + creds := &sourcedToken{token: "rotated", source: "the credentials file [10.0.0.5:8080]", retry: true} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + unauthenticated(w) + }) + + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("err = %v, want ErrUnauthenticated", err) + } + if rec.count() != 2 { + t.Fatalf("made %d requests, want the one retry then the refusal", rec.count()) + } + if !strings.Contains(err.Error(), "credential from the credentials file [10.0.0.5:8080]") { + t.Errorf("the post-retry 401 does not name the source:\n%s", err) + } +} + +func TestA401FromAProviderWithNoSourceIsUnadorned(t *testing.T) { + // A provider that cannot report a source — the no-auth posture, or a + // third-party provider — must not force a clause. The 401 reads as it did + // before, and nothing panics on the missing capability. + creds := &staticToken{tokens: []string{"tok"}, retry: false} + c, _ := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + unauthenticated(w) + }) + + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("err = %v, want ErrUnauthenticated", err) + } + if strings.Contains(err.Error(), "credential from") { + t.Errorf("a sourceless provider still produced a source clause: %v", err) + } +} diff --git a/internal/httpclient/wire/credential_test.go b/internal/httpclient/wire/credential_test.go new file mode 100644 index 000000000..a0b074288 --- /dev/null +++ b/internal/httpclient/wire/credential_test.go @@ -0,0 +1,236 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/credential_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "errors" + "io" + "net/http" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/httpapi/apigen" +) + +func unauthenticated(w http.ResponseWriter) { + w.Header().Set("WWW-Authenticate", "Bearer") + problemJSON(w, http.StatusUnauthorized, `{"status":401,"code":"unauthenticated","detail":"missing or invalid bearer token","request_id":"r"}`) +} + +func TestTheCredentialIsPresentedOnEveryRequest(t *testing.T) { + creds := &staticToken{tokens: []string{"tok-1"}} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + _, _ = io.WriteString(w, `{}`) + }) + for range 2 { + if err := c.Do(ctx(t), listIssues(), &struct{}{}); err != nil { + t.Fatalf("Do: %v", err) + } + } + for i := range 2 { + if got := rec.at(t, i).header.Get("Authorization"); got != "Bearer tok-1" { + t.Errorf("request %d Authorization = %q", i, got) + } + } +} + +func TestNoProviderMeansNoAuthorizationHeader(t *testing.T) { + // The tip OSS server's loopback-trust posture: there is no token file, and + // sending a header it never configured would be noise at best. + c, rec := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = io.WriteString(w, `{}`) + }) + if err := c.Do(ctx(t), listIssues(), &struct{}{}); err != nil { + t.Fatalf("Do: %v", err) + } + if got := rec.at(t, 0).header.Get("Authorization"); got != "" { + t.Errorf("Authorization = %q, want none", got) + } +} + +func TestA401IsRetriedExactlyOnceThroughRefresh(t *testing.T) { + // The client half of the server's rotation contract: the token file is + // re-read on a ~1s gate, so rotation is write {new,old}, roll the clients, + // drop old — and a client rolled mid-flight 401s once and succeeds on the + // retry. + creds := &staticToken{tokens: []string{"stale", "rotated"}, retry: true} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, r *http.Request) { + if r.Header.Get("Authorization") != "Bearer rotated" { + unauthenticated(w) + return + } + _, _ = io.WriteString(w, `{"has_more":false,"items":[]}`) + }) + + var page apigen.IssuesPage + if err := c.Do(ctx(t), listIssues(), &page); err != nil { + t.Fatalf("Do: %v", err) + } + if rec.count() != 2 { + t.Fatalf("made %d requests, want 2", rec.count()) + } + if got := rec.at(t, 0).header.Get("Authorization"); got != "Bearer stale" { + t.Errorf("first attempt used %q", got) + } + // The retry goes back through Authorize, which is what makes the rotated + // credential reach the wire at all. + if got := rec.at(t, 1).header.Get("Authorization"); got != "Bearer rotated" { + t.Errorf("retry used %q", got) + } + if creds.refreshN != 1 { + t.Errorf("Refresh called %d times, want 1", creds.refreshN) + } +} + +func TestASecondUnauthenticatedAnswerIsNotRetriedAgain(t *testing.T) { + // One retry is the whole rotation window. A second 401 is a credential this + // server does not accept, and retrying it again would turn a clear refusal + // into a loop against an authentication endpoint. + creds := &staticToken{tokens: []string{"wrong"}, retry: true} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + unauthenticated(w) + }) + + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("err = %v, want ErrUnauthenticated", err) + } + if rec.count() != 2 { + t.Errorf("made %d requests, want exactly 2", rec.count()) + } + if creds.refreshN != 1 { + t.Errorf("Refresh called %d times, want 1", creds.refreshN) + } +} + +func TestRefreshDecliningSurfacesThe401AsItStands(t *testing.T) { + // A provider that knows it has nothing new — a static token from the + // environment — declines, and the refusal reaches the caller unchanged + // rather than costing a second round trip. + creds := &staticToken{tokens: []string{"static"}, retry: false} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + unauthenticated(w) + }) + + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("err = %v, want ErrUnauthenticated", err) + } + if rec.count() != 1 { + t.Errorf("made %d requests, want 1", rec.count()) + } + if creds.refreshN != 1 { + t.Errorf("Refresh called %d times, want 1", creds.refreshN) + } +} + +func TestAFailingRefreshFailsClosed(t *testing.T) { + // A configured source that errored is not a license to send the stale + // credential again, and certainly not to send none. + creds := &staticToken{tokens: []string{"stale"}, err: errors.New("token file is unreadable")} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + unauthenticated(w) + }) + + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if err == nil { + t.Fatal("a failing credential refresh was swallowed") + } + if !strings.Contains(err.Error(), "token file is unreadable") { + t.Errorf("err = %q, want the source's own failure named", err) + } + if strings.Contains(err.Error(), "stale") { + t.Errorf("the credential survived into the error: %v", err) + } + if rec.count() != 1 { + t.Errorf("made %d requests, want 1", rec.count()) + } +} + +func TestNoProviderMeansNoRotationWindow(t *testing.T) { + // A 401 from a server this client has no credential for is a deployment + // mismatch, not a rotation: there is nothing to refresh and nothing to retry. + c, rec := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + unauthenticated(w) + }) + if err := c.Do(ctx(t), listIssues(), &struct{}{}); !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("err = %v, want ErrUnauthenticated", err) + } + if rec.count() != 1 { + t.Errorf("made %d requests, want 1", rec.count()) + } +} + +func TestOnlyA401OpensTheRotationWindow(t *testing.T) { + // Every other refusal is about the request, so re-sending it with a fresh + // credential would just earn the same answer twice. + for _, status := range []int{400, 403, 404, 409, 500, 503} { + creds := &staticToken{tokens: []string{"tok"}, retry: true} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + problemJSON(w, status, `{"status":0,"code":"internal"}`) + }) + _ = c.Do(ctx(t), listIssues(), &struct{}{}) + if rec.count() != 1 { + t.Errorf("status %d made %d requests, want 1", status, rec.count()) + } + if creds.refreshN != 0 { + t.Errorf("status %d consulted Refresh", status) + } + } +} + +func TestTheRetriedRequestReplaysItsBody(t *testing.T) { + // The retry re-issues the SAME request. A body streamed straight from the + // caller would be spent by the first attempt and the second would post + // nothing — which on a write is a silent half-application. + creds := &staticToken{tokens: []string{"stale", "rotated"}, retry: true} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, r *http.Request) { + if r.Header.Get("Authorization") != "Bearer rotated" { + unauthenticated(w) + return + } + _, _ = io.WriteString(w, `{"already_claimed":false,"issue":{"id":"ga-1"}}`) + }) + + var out apigen.ClaimResponse + err := c.Do(ctx(t), Request{ + Op: OpClaimIssue, + Method: http.MethodPost, + Path: "/v0/beads/issues/ga-1:claim", + Body: apigen.ClaimRequest{Actor: "agent-7"}, + IssueID: "ga-1", + }, &out) + if err != nil { + t.Fatalf("Do: %v", err) + } + if rec.count() != 2 { + t.Fatalf("made %d requests, want 2", rec.count()) + } + first, second := string(rec.at(t, 0).body), string(rec.at(t, 1).body) + if first != second || !strings.Contains(second, `"actor":"agent-7"`) { + t.Errorf("bodies differ across the retry: %q then %q", first, second) + } +} + +func TestAnAuthorizeFailureNeverReachesTheWire(t *testing.T) { + // Fail closed at the earliest point: a request that could not be authorized + // must not be sent unauthenticated to find out what happens. + creds := &failingAuthorize{err: errors.New("no token source is configured")} + c, rec := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + t.Error("an unauthorized request was dialed") + _, _ = io.WriteString(w, `{}`) + }) + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if err == nil || !strings.Contains(err.Error(), "no token source is configured") { + t.Fatalf("err = %v, want the provider's failure", err) + } + if rec.count() != 0 { + t.Errorf("made %d requests, want 0", rec.count()) + } +} + +type failingAuthorize struct{ err error } + +func (f *failingAuthorize) Authorize(context.Context, *http.Request) error { return f.err } +func (f *failingAuthorize) Refresh(context.Context) (bool, error) { return false, nil } diff --git a/internal/httpclient/wire/doc.go b/internal/httpclient/wire/doc.go new file mode 100644 index 000000000..adb9d55a3 --- /dev/null +++ b/internal/httpclient/wire/doc.go @@ -0,0 +1,37 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/doc.go@49d1df2f6) +// to OSS beads under the MIT license. +// Package wire is the transport core of the `http` storage backend: one +// base-URL client that speaks the v0 surface `bd serve` publishes +// (internal/httpapi/spec/openapi.v0.yaml), and nothing else. +// +// It owns four things and deliberately owns no more: +// +// - The TRANSPORT. One request, one bounded response, JSON in and JSON out +// of the canonical types. Redirects are refused rather than followed, so a +// 30x can never replay the Authorization header to another host, and every +// response body is read under a byte cap, so a wrong URL answering with a +// tarball is an error instead of the client's whole heap. +// - The CREDENTIAL seam. CredentialProvider is the interface the activation +// layer implements; this package consumes it and implements the client +// half of the server's rotation contract — exactly one retry after one 401. +// - The PROBLEM mapping. Every non-2xx is an RFC 9457 problem+json document, +// and `code` is the only member this package dispatches on. Each code maps +// to the canonical issueops sentinel the local store would have returned +// for the same refusal, so a caller classifies a remote refusal with the +// same errors.Is/errors.As arm it already uses locally. +// - The CAPABILITY handshake. GET /v0/beads/context once per client, an +// api_version gate, a workspace-identity check, and the two-speed +// pre-flight policy: the five baseline operations dispatch straight, every +// post-baseline operation consults the cached capability list first. +// +// What it does NOT own: the storage.DoltStorage implementation, the request +// encoders that turn issueops requests into query parameters (internal/httpclient/encode; +// see engdocs/design/http-divergence-ledger.md for the full divergence +// inventory), the refusal taxonomy's user-facing text, and the default +// endpoint/credential sources. Those are separate packages that consume this +// one. +// +// The package carries no build tag: it compiles and its unit gates run in the +// default PR lane regardless of which storage backend a given `bd` build +// wires in at the command layer. +package wire diff --git a/internal/httpclient/wire/handshake.go b/internal/httpclient/wire/handshake.go new file mode 100644 index 000000000..0a7f450ec --- /dev/null +++ b/internal/httpclient/wire/handshake.go @@ -0,0 +1,565 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/handshake.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "errors" + "fmt" + "net/http" + "slices" + "strings" + "sync" + + "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/issueops" +) + +// APIVersion is the path major this client speaks. ContextResponse.api_version +// must equal it exactly: the wire is versioned by path, so a server answering +// anything else is a server this client cannot address at all. +const APIVersion = "v0" + +// baselineOps are the five operations that dispatch WITHOUT a pre-flight. +// +// They exist in every v0 release — they are the first slice — so consulting +// capabilities before them buys nothing and costs a round trip on the hot +// work-distribution path. Their errors classify by problem code like everything +// else. +// +// claimIssue is first-slice too, but it is deliberately NOT here (ga-b8ddd.11). +// A claim is a WRITE, and the handshake carries the project-identity gate; +// exempting the claim let it land against a server whose identity no longer +// matched the workspace — a silent cross-project write. Forcing its handshake +// runs the gate before the claim, at the price of one round trip every other +// write already pays. issues.claim is first-slice on every v0 server, so the +// forced handshake never turns a working claim into a capability refusal. +var baselineOps = map[string]bool{ + OpHealth: true, + OpGetContext: true, + OpListReadyWork: true, + OpListIssues: true, + OpGetIssue: true, +} + +// opCapability is the token each operation contributes to +// ContextResponse.capabilities. The two identity operations contribute none: +// liveness and the handshake itself are not gated by the list they publish. +// +// TestCapabilityTableMatchesTheServerRouteTable proves this table set-equal +// with the server's own, so an operation added upstream cannot arrive here +// unclassified. +var opCapability = map[string]string{ + OpHealth: "", + OpGetContext: "", + OpListReadyWork: "ready.list", + OpCountReadyWork: "ready.count", + OpGetStats: "stats.get", + OpListIssues: "issues.list", + OpQueryIssues: "issues.query", + OpGetIssue: "issues.get", + OpClaimIssue: "issues.claim", + OpCloseIssue: "issues.close", + OpReopenIssue: "issues.reopen", + OpUpdateIssue: "issues.update", + OpSweepIssues: "issues.sweep", + OpDeleteIssues: "issues.delete", + OpBatchCreateIssues: "issues.batchCreate", + OpBatchCloseIssues: "issues.batchClose", + // The three operations the wire wave published while this client was being + // built. They are CLASSIFIED, not wired: the client has no accessor behind + // any of them yet, so its refusals stand — but an operation the server + // advertises and this table does not know is one the pre-flight would dial + // blind, which is the failure the set-equality gate exists to stop. The + // tokens land here in the sync that absorbs the wave; the accessors land in + // the client waves that follow. + OpClaimNextIssue: "issues.claimNext", + OpReleaseIssue: "issues.release", + OpCountIssues: "issues.count", + OpCreateIssue: "issues.create", + OpApplyBatch: "issues.batchApply", + OpCompareAndSetMetadata: "issues.casMetadata", + OpListEvents: "events.list", + OpWatchEvents: "events.watch", + OpListSettings: "config.list", + OpGetSetting: "config.get", + OpSetSetting: "config.set", + OpUnsetSetting: "config.unset", + OpListDependencies: "dependencies.list", + OpListBlockingAnnotations: "dependencies.blocking", + OpGetDependencyTree: "dependencies.tree", + OpCountDependencyEdges: "dependencies.count", + OpListRelatedIssues: "issues.related", + OpAddComment: "issues.addComment", + OpListDependencyCycles: "dependencies.cycles", + OpAddDependencies: "dependencies.add", + OpRemoveDependency: "dependencies.remove", + OpListMemories: "memories.list", + OpRememberMemory: "memories.remember", + OpGetMemory: "memories.get", + OpForgetMemory: "memories.forget", +} + +// CapProjectEnforce is the behavior capability the server advertises to announce +// per-request Bd-Project-Id enforcement, spelled exactly as httpapi's constant of +// the same name (held to it by TestProjectEnforceCapabilityMatchesTheServer). +// Unlike the per-operation tokens in opCapability it gates no route: it names a +// server-wide behavior, not an operation. The client does not consult it before +// stamping — the stamp is always sent and an older server simply ignores an +// unknown header — but it rides in the same ContextResponse.capabilities list, so +// the capability-union parity gate must account for it. +const CapProjectEnforce = "project.enforce" + +// CapListSort is the behavior capability announcing that listIssues honors +// `sort` and `reverse`, spelled exactly as httpapi's constant of the same name +// (held to it by TestTheProjectIdentityVocabularyMatchesTheServer). Like +// CapProjectEnforce it gates no route — listIssues has its own operation token +// — it names a property of that operation, so it rides here rather than on +// opCapability. +// +// Nothing in this package reads it yet: the server surface ships first and the +// client that pushes a sort down follows. It is declared now because the +// capability-union parity gate compares this client's whole vocabulary with the +// server's, so the mirror is what makes the two land together. +const CapListSort = "issues.list.sort" + +// CapBatchApplyLarge is the behavior capability announcing that issues.batchApply +// accepts a batch larger than the compiled-in floor (100 items), up to the +// raised ceiling (1000), spelled exactly as httpapi's constant of the same name +// (held to it by TestTheBatchCapVocabularyMatchesTheServer). Like CapListSort it +// names a property of an existing operation — issues.batchApply already has its +// own per-operation token in opCapability — rather than a route of its own, so +// it rides here. +// +// Preflight reads this one: a batch over 100 items refuses locally with a typed +// capability error BEFORE any network call unless the handshake snapshot +// advertises it, in which case the ceiling is 1000. The cap is never a bare +// compiled constant for that reason — it is always read off the snapshot this +// token gates. +const CapBatchApplyLarge = "issues.batchApplyLarge" + +// CapExternalDependencies is the CONDITIONAL behavior capability announcing +// that the ready, claim and close operations of this server apply bd's +// external-dependency policy themselves, spelled exactly as httpapi's constant +// of the same name (held to it by TestExternalDependencyCapabilityMatchesTheServer). +// +// It is not in behaviorCapabilities because it is not a property of the build: +// httpapi advertises it only when the serving process composed its roles through +// the policy layer, so httpapi.Capabilities() — the build-level list the parity +// gate compares against — never contains it. The store reads it to answer +// storage.ServerEnforcedPolicy, which is what decides whether this client layers +// the policy itself. +const CapExternalDependencies = "policy.external_dependencies" + +// ClientWireRevision is the wire shape this client was built to speak and +// decode, mirroring internal/httpapi/wire_revision.go's CurrentWireRevision. +// It is sent as the Bd-Wire-Revision request header on every request +// (Client.stampRequest), so a server whose own min_client_wire_revision has +// moved past it refuses with the typed wire_revision_unsupported problem +// (problem.go's WireRevisionUnsupportedError) instead of answering with a +// shape this build was never compiled to read. It doubles as the upper bound +// of the handshake gate below: nothing compiled against revision 2 can +// promise to decode revision 3. +const ClientWireRevision = 2 + +// ClientMinWireRevision is the oldest SERVER-reported wire_revision this +// client tolerates — the other half of DESIGN.txt sec 4's "Client rule": +// handshake once per Store and gate on api_version == "v0" AND wire_revision +// within [client_min, client_max]. It is 0, not 2, because a decoded 0 means +// only that the server omitted ContextResponse.wire_revision entirely: 0 and +// 1 are permanently retired values no server implementing the member will +// ever legitimately send (see that field's doc comment), and the one thing a +// server old enough to omit it can still do is answer revision/expected_version +// tokens as bare JSON integers rather than the decimal strings upstream #6053 +// standardized — a shape this package tolerates on both halves of the wire: +// problem.go's legacyRevisionFields on the error path, and +// revision_tolerance.go's serverPredatesRevisionStrings on every success-path +// response type that carries a `revision` member. There is therefore nothing +// on the low end for this client to refuse. +const ClientMinWireRevision = 0 + +// checkWireRevision applies the handshake half of the Client rule to a decoded +// ContextResponse, returning the typed skew refusal when the server's wire +// shape falls outside what this client build can speak, or nil when it is +// safe to proceed. +// +// Two independent conditions trigger it: the server's own +// min_client_wire_revision already exceeds what this client declares (so +// every request would earn the same wire_revision_unsupported 400 the +// Bd-Wire-Revision header invites — refusing here spends no round trip +// learning what the handshake already answered), or the server's own +// wire_revision is past ClientWireRevision (a future, non-additive wire +// change this build predates). A decoded wire_revision of 0 never trips the +// second check on its own: per ClientMinWireRevision's doc, that is the +// "omitted" signal, not a value above range. +func (c *Client) checkWireRevision(body apigen.ContextResponse) error { + switch { + case body.MinClientWireRevision > ClientWireRevision: + return &WireRevisionSkewError{ + ServerURL: c.base.Redacted(), + BdVersion: stripControlRunes(body.BdVersion), + ClientWireRevision: ClientWireRevision, + ServerWireRevision: body.WireRevision, + MinClientWireRevision: body.MinClientWireRevision, + } + case body.WireRevision > ClientWireRevision: + return &WireRevisionSkewError{ + ServerURL: c.base.Redacted(), + BdVersion: stripControlRunes(body.BdVersion), + ClientWireRevision: ClientWireRevision, + ServerWireRevision: body.WireRevision, + MinClientWireRevision: body.MinClientWireRevision, + } + default: + return nil + } +} + +// ErrWireRevisionSkew reports a handshake-time wire-shape mismatch this client +// cannot safely proceed past. See WireRevisionSkewError. +var ErrWireRevisionSkew = errors.New("bd serve speaks a wire revision this client does not") + +// WireRevisionSkewError is DESIGN.txt sec 4's Client rule, violated: the +// server's wire shape is outside [ClientMinWireRevision, ClientWireRevision]. +// It is raised by Handshake itself, from a 200 ContextResponse, which is what +// separates it from WireRevisionUnsupportedError (problem.go) — that one is +// the SERVER refusing a request with a 400 after reading this client's own +// declared Bd-Wire-Revision header; this one is the CLIENT declining to +// proceed after reading the server's. +type WireRevisionSkewError struct { + ServerURL string + BdVersion string + // ClientWireRevision is this build's own declared revision. + ClientWireRevision int + // ServerWireRevision is the server's ContextResponse.wire_revision, decoded + // as-is (0 means the server omitted the member; see ClientMinWireRevision). + ServerWireRevision int + // MinClientWireRevision is the server's ContextResponse.min_client_wire_revision. + MinClientWireRevision int +} + +func (e *WireRevisionSkewError) Error() string { + if e.MinClientWireRevision > e.ClientWireRevision { + return fmt.Sprintf("bd serve at %s (bd_version %s) requires a client wire revision of at least %d; this client speaks %d", + e.ServerURL, e.BdVersion, e.MinClientWireRevision, e.ClientWireRevision) + } + return fmt.Sprintf("bd serve at %s (bd_version %s) speaks wire revision %d, newer than any shape this client build knows how to decode (max %d)", + e.ServerURL, e.BdVersion, e.ServerWireRevision, e.ClientWireRevision) +} + +func (e *WireRevisionSkewError) Unwrap() error { return ErrWireRevisionSkew } + +// behaviorCapabilities mirrors the server's own behavior-token set (httpapi's +// behaviorCapabilities): the advertised tokens that name a server-wide behavior +// rather than an operation. TestCapabilityTableMatchesTheServerRouteTable proves +// union(opCapability tokens, this) set-equal with httpapi.Capabilities(), which is +// what makes the server change and this client change land together: the parity +// test goes red the moment one ships without the other. +var behaviorCapabilities = []string{CapProjectEnforce, CapBatchApplyLarge, CapListSort} + +// CapabilityFor reports the capability token gating op, and whether op is on +// this client's map at all. An operation with no token — liveness, the +// handshake — reports ("", true). +func CapabilityFor(op string) (string, bool) { + token, ok := opCapability[op] + return token, ok +} + +// IsBaseline reports whether op dispatches without a capability pre-flight. +func IsBaseline(op string) bool { return baselineOps[op] } + +// Snapshot is the parsed handshake: one ContextResponse and its capability list +// indexed for lookup. +type Snapshot struct { + Context apigen.ContextResponse + caps map[string]struct{} +} + +// Has reports whether the server advertised token. +func (s *Snapshot) Has(token string) bool { + _, ok := s.caps[token] + return ok +} + +// Capabilities is the advertised token list, sorted, as a copy. +func (s *Snapshot) Capabilities() []string { + out := make([]string, 0, len(s.caps)) + for token := range s.caps { + out = append(out, token) + } + slices.Sort(out) + return out +} + +type handshakeCache struct { + mu sync.Mutex + snap *Snapshot +} + +// Health drives the liveness probe. It is the one operation served with no +// credential, and it stays 200 while the database is wedged — so a green health +// check says the process is up and nothing more. +func (c *Client) Health(ctx context.Context) error { + var out apigen.Health + return c.Do(ctx, Request{Op: OpHealth, Method: http.MethodGet, Path: PathHealth}, &out) +} + +// GetContext fetches the startup snapshot with no caching and no gates. Callers +// that want the process-wide, gated, identity-checked one want Handshake. +func (c *Client) GetContext(ctx context.Context) (apigen.ContextResponse, error) { + var out apigen.ContextResponse + err := c.Do(ctx, Request{Op: OpGetContext, Method: http.MethodGet, Path: PathContext}, &out) + return out, err +} + +// Handshake fetches the context once and caches it for the life of the client, +// applying the two gates that must not be skipped: api_version equality and, if +// the workspace recorded one, project identity. +// +// The fetch is lazy — it happens on the first post-baseline dispatch, not at +// open — so a `bd ready` against a server that serves only the baseline costs +// no extra round trip. A FAILED handshake is not cached: a server that was down +// when the first post-baseline command ran must not poison the rest of the +// process. +func (c *Client) Handshake(ctx context.Context) (*Snapshot, error) { + c.handshake.mu.Lock() + defer c.handshake.mu.Unlock() + if c.handshake.snap != nil { + return c.handshake.snap, nil + } + + body, err := c.GetContext(ctx) + if err != nil { + return nil, err + } + if body.ApiVersion != APIVersion { + return nil, &APIVersionError{ServerURL: c.base.Redacted(), Got: body.ApiVersion, Want: APIVersion} + } + // The Client rule's other half (DESIGN.txt sec 4), run right after the + // api_version gate and before the identity gate: a server this client + // cannot decode is not a server worth reporting a wrong-project diagnosis + // against either, and api_version is the coarser, cheaper check of the two. + if err := c.checkWireRevision(body); err != nil { + return nil, err + } + if c.expectID != "" && body.ProjectId != c.expectID { + // These three are server-controlled and end up in an error rendered to a + // terminal — often through a per-id write sink (bd close/reopen/update) + // that bypasses the CLI's display-layer strip — so their control runes are + // removed at construction, the same source-layer strip mapProblem applies. + // RepoRoot renders via %s (raw); Got and Database render via %q (already + // escaped), stripped too so a future Error() change cannot reintroduce the + // leak. Expected is the workspace's own pinned id, not server-controlled. + // + // repo_root is OPTIONAL on the wire, so the generated member is a pointer; + // an absent one is the empty string here, which is exactly what Error() + // already reads as "that server disclosed no root" (it omits the whole + // parenthetical when Database and RepoRoot are both empty). + return nil, &ProjectMismatchError{ + ServerURL: c.base.Redacted(), + Expected: c.expectID, + Got: stripControlRunes(body.ProjectId), + Database: stripControlRunes(body.Database), + RepoRoot: stripControlRunes(deref(body.RepoRoot)), + } + } + + caps := make(map[string]struct{}, len(body.Capabilities)) + for _, token := range body.Capabilities { + caps[token] = struct{}{} + } + c.handshake.snap = &Snapshot{Context: body, caps: caps} + return c.handshake.snap, nil +} + +// ServerContext is the handshake as the STORE's transport seam spells it: one +// gated, cached, identity-checked snapshot per process. +// +// It exists so a *Client satisfies that seam directly rather than through an +// adapter every build would have to write identically. The pointer is into the +// cache and the caller must treat it as read-only — the same rule Handshake's +// Snapshot carries, for the same reason. +func (c *Client) ServerContext(ctx context.Context) (*apigen.ContextResponse, error) { + snap, err := c.Handshake(ctx) + if err != nil { + return nil, err + } + return &snap.Context, nil +} + +// Preflight applies the two-speed policy to op, and is the call every dispatch +// site makes before building a request. +// +// A baseline operation returns immediately. Every other operation forces the +// handshake and checks its token, because an unrouted path on an older server +// answers a bare 404 that is INDISTINGUISHABLE from an entity's not_found — the +// version-skew signal would arrive spelled as "no such issue". Consulting the +// advertised list is the only way to tell the two apart, and it has to happen +// before the dial. +func (c *Client) Preflight(ctx context.Context, op string) error { + token, known := CapabilityFor(op) + if !known { + return fmt.Errorf("no such v0 operation %q", op) + } + if IsBaseline(op) || token == "" { + return nil + } + snap, err := c.Handshake(ctx) + if err != nil { + return err + } + if snap.Has(token) { + return nil + } + // BdVersion is server-controlled and reaches the case-2 taxonomy text AND a + // per-id write sink that bypasses the display-layer strip, so its control runes + // are removed at construction (Op and Capability are this client's own known + // strings; Capabilities is a token-membership set, never rendered as free text). + return &CapabilityError{ + Op: op, + Capability: token, + ServerURL: c.base.Redacted(), + BdVersion: stripControlRunes(snap.Context.BdVersion), + Capabilities: snap.Capabilities(), + } +} + +// ErrCapabilityAbsent reports that the server does not advertise the capability +// an operation needs. +var ErrCapabilityAbsent = errors.New("bd serve does not advertise the capability this operation needs") + +// CapabilityError is the typed form of that refusal. It carries what the +// refusal taxonomy's case-2 text names — the server, its version, and the +// tokens it DOES advertise — so the rendering layer parses nothing. +type CapabilityError struct { + Op string + Capability string + ServerURL string + BdVersion string + Capabilities []string +} + +func (e *CapabilityError) Error() string { + return fmt.Sprintf("bd serve at %s (bd_version %s) does not advertise capability %q, which %s requires", + e.ServerURL, e.BdVersion, e.Capability, e.Op) +} + +func (e *CapabilityError) Unwrap() error { return ErrCapabilityAbsent } + +// NewCapabilityError builds the capability-absent refusal for a behavior the +// caller checked itself, off a handshake it already holds, rather than for an +// operation Preflight checked. The server-controlled version is stripped of +// control runes the way Preflight strips it, because the refusal reaches a +// terminal through sinks that bypass the display-layer strip. +func NewCapabilityError(op, token, serverURL string, ctx *apigen.ContextResponse) *CapabilityError { + e := &CapabilityError{Op: op, Capability: token, ServerURL: serverURL} + if ctx != nil { + e.BdVersion = stripControlRunes(ctx.BdVersion) + e.Capabilities = append([]string(nil), ctx.Capabilities...) + slices.Sort(e.Capabilities) + } + return e +} + +// ErrAPIVersion reports a server on a path major this client cannot address. +var ErrAPIVersion = errors.New("bd serve speaks a different api_version") + +// APIVersionError names both versions, because neither alone tells an operator +// which side to move. +type APIVersionError struct { + ServerURL string + Got string + Want string +} + +func (e *APIVersionError) Error() string { + return fmt.Sprintf("bd serve at %s serves api_version %q; this client speaks %q", e.ServerURL, e.Got, e.Want) +} + +func (e *APIVersionError) Unwrap() error { return ErrAPIVersion } + +// ErrInvalidProjectID reports that the workspace's pinned project id is not a +// value that can be sent as the Bd-Project-Id header on every request. +var ErrInvalidProjectID = errors.New("pinned project id is not a valid header value") + +// InvalidProjectIDError is the loud refusal New raises when the pinned project id +// cannot be stamped. The id comes from the workspace's sidecar, recorded by +// `bd connect`, and it is stamped on EVERY request — so a corrupt one is caught +// once, at open, rather than skipped (which would leave the workspace unenforced) +// or deferred to a per-request transport failure. The offending value is rendered +// %q so its own bad bytes — the reason it is invalid — cannot inject into the +// error text on its way to a terminal. +type InvalidProjectIDError struct { + ServerURL string + ProjectID string +} + +func (e *InvalidProjectIDError) Error() string { + return fmt.Sprintf("the project id %q pinned for the workspace connected to bd serve at %s is not a valid %s header value; re-run bd connect to re-record the workspace's identity from its sidecar", + e.ProjectID, e.ServerURL, ProjectIDHeader) +} + +func (e *InvalidProjectIDError) Unwrap() error { return ErrInvalidProjectID } + +// ErrProjectMismatch reports that the server owns a different workspace. +var ErrProjectMismatch = errors.New("bd serve owns a different workspace") + +// ProjectMismatchRecovery is the one action that resolves a wrong-server +// mismatch: point the workspace back at the server that owns it. There is no +// local database to reconcile — bd doctor and bd bootstrap have nothing to fix +// on an http workspace — so reconnecting IS the whole recovery. It is exported +// so cmd/bd's pre-write identity check can render the same guidance the +// post-baseline read path already surfaces (design D1/D6) without restating the +// string in a second place that could drift. +const ProjectMismatchRecovery = "re-run bd connect against the server that owns this workspace" + +// ProjectMismatchError is the wrong-server diagnostic. It names both project +// ids AND the server's own database and repo root, because "the ids differ" does +// not tell an operator WHICH wrong server answered — and on a shared host that +// is the whole question. +type ProjectMismatchError struct { + ServerURL string + Expected string + Got string + Database string + RepoRoot string +} + +func (e *ProjectMismatchError) Error() string { + var b strings.Builder + fmt.Fprintf(&b, "bd serve at %s owns project %q, but this workspace expects %q", e.ServerURL, e.Got, e.Expected) + if e.Database != "" || e.RepoRoot != "" { + fmt.Fprintf(&b, " (that server serves database %q from %s)", e.Database, e.RepoRoot) + } + b.WriteString("; " + ProjectMismatchRecovery) + return b.String() +} + +func (e *ProjectMismatchError) Unwrap() error { return ErrProjectMismatch } + +// BatchTooLargeError is a locally-refused issues:batchApply plan: the item +// count exceeds issueops.MaxApplyBatchItems, the absolute ceiling every v0 +// server enforces regardless of capability (internal/httpapi's +// maxApplyBatchItems). ApplyBatch (writes.go) raises it before any network +// call — never dialing a plan this large — the same way Preflight never +// dials an operation the server has not advertised. It lives here rather +// than beside ApplyBatch because every exported method in writes.go is swept +// by TestEveryOperationMethodRoutesThroughTheSharedDispatch as an operation +// dispatch method; this type's two methods are not one. +// +// It unwraps to issueops.ErrValidation, the sentinel a server's own 400 on +// the same oversized plan would classify as, had the request been allowed to +// reach it. +type BatchTooLargeError struct { + Op string + ServerURL string + Count int + Limit int +} + +func (e *BatchTooLargeError) Error() string { + return fmt.Sprintf("%s: a plan of %d items exceeds the %d-item ceiling bd serve at %s enforces; split it into requests of %d or fewer", + e.Op, e.Count, e.Limit, e.ServerURL, e.Limit) +} + +func (e *BatchTooLargeError) Unwrap() error { return issueops.ErrValidation } diff --git a/internal/httpclient/wire/handshake_test.go b/internal/httpclient/wire/handshake_test.go new file mode 100644 index 000000000..c59231d89 --- /dev/null +++ b/internal/httpclient/wire/handshake_test.go @@ -0,0 +1,261 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/handshake_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "errors" + "io" + "net/http" + "strings" + "sync" + "testing" +) + +// contextBody is a ContextResponse carrying whatever capability list the case +// needs. The other members are what a real single-workspace server publishes. +func contextBody(apiVersion, projectID string, capabilities ...string) string { + quoted := make([]string, 0, len(capabilities)) + for _, token := range capabilities { + quoted = append(quoted, `"`+token+`"`) + } + return `{"api_version":"` + apiVersion + `","backend":"dolt","bd_version":"1.1.0",` + + `"beads_dir":"/srv/repo/.beads","capabilities":[` + strings.Join(quoted, ",") + `],` + + `"database":"beads","dolt_mode":"embedded","project_id":"` + projectID + `",` + + `"repo_root":"/srv/repo","schema_version":7}` +} + +func serveContext(body string) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != PathContext { + problemJSON(w, http.StatusNotFound, `{"status":404,"code":"not_found"}`) + return + } + _, _ = io.WriteString(w, body) + } +} + +func TestGetContextDecodesTheWholeSnapshot(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1", "issues.list", "issues.get"))) + got, err := c.GetContext(ctx(t)) + if err != nil { + t.Fatalf("GetContext: %v", err) + } + if got.ApiVersion != "v0" || got.ProjectId != "proj-1" || got.BdVersion != "1.1.0" { + t.Errorf("decoded %+v", got) + } + if got.Database != "beads" || deref(got.RepoRoot) != "/srv/repo" || got.SchemaVersion != 7 { + t.Errorf("diagnostic members did not decode: %+v", got) + } + if len(got.Capabilities) != 2 { + t.Errorf("capabilities = %v", got.Capabilities) + } +} + +func TestTheHandshakeIsFetchedOncePerClient(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1", "issues.list"))) + for range 3 { + if _, err := c.Handshake(ctx(t)); err != nil { + t.Fatalf("Handshake: %v", err) + } + } + if rec.count() != 1 { + t.Errorf("made %d context fetches, want 1", rec.count()) + } +} + +func TestConcurrentHandshakesStillFetchOnce(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1", "issues.list"))) + var wg sync.WaitGroup + for range 8 { + wg.Add(1) + go func() { + defer wg.Done() + if _, err := c.Handshake(ctx(t)); err != nil { + t.Errorf("Handshake: %v", err) + } + }() + } + wg.Wait() + if rec.count() != 1 { + t.Errorf("made %d context fetches, want 1", rec.count()) + } +} + +func TestAFailedHandshakeIsNotCached(t *testing.T) { + // A server that was down when the first post-baseline command ran must not + // poison the rest of the process. + var attempts int + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + attempts++ + if attempts == 1 { + problemJSON(w, 503, `{"status":503,"code":"db_unavailable"}`) + return + } + _, _ = io.WriteString(w, contextBody("v0", "proj-1", "issues.list")) + }) + if _, err := c.Handshake(ctx(t)); !errors.Is(err, ErrDBUnavailable) { + t.Fatalf("err = %v, want ErrDBUnavailable", err) + } + snap, err := c.Handshake(ctx(t)) + if err != nil { + t.Fatalf("second Handshake: %v", err) + } + if !snap.Has("issues.list") { + t.Error("the recovered handshake carries no capabilities") + } +} + +func TestTheAPIVersionIsGated(t *testing.T) { + // The wire is versioned by path, so a server on another major is a server + // this client cannot address at all — not one it can degrade against. + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBody("v1", "proj-1", "issues.list"))) + _, err := c.Handshake(ctx(t)) + if !errors.Is(err, ErrAPIVersion) { + t.Fatalf("err = %v, want ErrAPIVersion", err) + } + // Neither version alone tells an operator which side to move. + msg := err.Error() + if !strings.Contains(msg, `"v1"`) || !strings.Contains(msg, `"v0"`) { + t.Errorf("Error() = %q, want both versions named", msg) + } +} + +func TestWorkspaceIdentityIsCheckedAtTheHandshake(t *testing.T) { + t.Run("a match passes", func(t *testing.T) { + c, _ := newTestClient(t, Options{ExpectProjectID: "proj-1"}, nil, + serveContext(contextBody("v0", "proj-1", "issues.list"))) + if _, err := c.Handshake(ctx(t)); err != nil { + t.Fatalf("Handshake: %v", err) + } + }) + + t.Run("no recorded identity skips the check", func(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "somebody-else", "issues.list"))) + if _, err := c.Handshake(ctx(t)); err != nil { + t.Fatalf("Handshake: %v", err) + } + }) + + t.Run("a mismatch names which wrong server answered", func(t *testing.T) { + c, _ := newTestClient(t, Options{ExpectProjectID: "proj-1"}, nil, + serveContext(contextBody("v0", "proj-2", "issues.list"))) + _, err := c.Handshake(ctx(t)) + if !errors.Is(err, ErrProjectMismatch) { + t.Fatalf("err = %v, want ErrProjectMismatch", err) + } + // "The ids differ" does not say WHICH wrong server answered, and on a + // shared host that is the whole question. + msg := err.Error() + for _, want := range []string{"proj-1", "proj-2", "beads", "/srv/repo", "bd connect"} { + if !strings.Contains(msg, want) { + t.Errorf("Error() = %q, want %q in it", msg, want) + } + } + }) +} + +func TestBaselineOperationsPreflightWithoutDialing(t *testing.T) { + // The five baseline operations exist in every v0 release, so the extra + // round trip on the hot work-distribution path buys nothing. claimIssue is + // first-slice too but is no longer exempt — it is a write and forces the + // identity handshake (ga-b8ddd.11) — so it is not in this set. + c, rec := newTestClient(t, Options{}, nil, func(http.ResponseWriter, *http.Request) { + t.Error("a baseline pre-flight dialed the server") + }) + for _, op := range []string{OpHealth, OpGetContext, OpListReadyWork, OpListIssues, OpGetIssue} { + if !IsBaseline(op) { + t.Errorf("%s is not classified baseline", op) + } + if err := c.Preflight(ctx(t), op); err != nil { + t.Errorf("Preflight(%s): %v", op, err) + } + } + if rec.count() != 0 { + t.Errorf("made %d requests, want 0", rec.count()) + } +} + +func TestPostBaselineOperationsConsultTheCapabilityListBeforeDialing(t *testing.T) { + // An unrouted path on an older server answers a bare 404 that is + // indistinguishable from an entity's not_found, so the skew signal would + // arrive spelled as "no such issue". The list is the only way to tell. + all := make([]string, 0, len(opCapability)) + for op := range opCapability { + if !IsBaseline(op) { + all = append(all, op) + } + } + served := make([]string, 0, len(all)) + for _, op := range all { + token, _ := CapabilityFor(op) + served = append(served, token) + } + + c, rec := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1", served...))) + for _, op := range all { + if err := c.Preflight(ctx(t), op); err != nil { + t.Errorf("Preflight(%s): %v", op, err) + } + } + if rec.count() != 1 { + t.Errorf("made %d context fetches for %d operations, want 1", rec.count(), len(all)) + } +} + +func TestAnAbsentCapabilityRefusesWithWhatTheTaxonomyNeeds(t *testing.T) { + // Taxonomy case 2: a mapped command against an older server. Everything the + // rendered text names travels on the typed error, so the render layer parses + // nothing. + c, _ := newTestClient(t, Options{}, nil, + serveContext(contextBody("v0", "proj-1", "issues.list", "issues.get", "ready.list"))) + + err := c.Preflight(ctx(t), OpAddDependencies) + if !errors.Is(err, ErrCapabilityAbsent) { + t.Fatalf("err = %v, want ErrCapabilityAbsent", err) + } + var absent *CapabilityError + if !errors.As(err, &absent) { + t.Fatalf("err is %T, want *CapabilityError", err) + } + if absent.Capability != "dependencies.add" || absent.Op != OpAddDependencies { + t.Errorf("refusal = %+v", absent) + } + if absent.BdVersion != "1.1.0" { + t.Errorf("BdVersion = %q", absent.BdVersion) + } + want := []string{"issues.get", "issues.list", "ready.list"} + if len(absent.Capabilities) != len(want) { + t.Fatalf("Capabilities = %v, want %v", absent.Capabilities, want) + } + for i, token := range want { + // Sorted, so the refusal text is stable enough to byte-pin upstream. + if absent.Capabilities[i] != token { + t.Errorf("Capabilities = %v, want %v", absent.Capabilities, want) + } + } +} + +func TestPreflightRefusesAnOperationThisClientDoesNotKnow(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1"))) + if err := c.Preflight(ctx(t), "teleportIssue"); err == nil { + t.Error("an operation off the map pre-flighted clean") + } + if _, known := CapabilityFor("teleportIssue"); known { + t.Error("CapabilityFor reported an unknown operation as known") + } +} + +func TestHealthIsTheLivenessProbe(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != PathHealth { + t.Errorf("health dialed %q", r.URL.Path) + } + _, _ = io.WriteString(w, `{"status":"ok"}`) + }) + if err := c.Health(ctx(t)); err != nil { + t.Fatalf("Health: %v", err) + } + if rec.count() != 1 { + t.Errorf("made %d requests, want 1", rec.count()) + } +} diff --git a/internal/httpclient/wire/handshake_wire_revision_test.go b/internal/httpclient/wire/handshake_wire_revision_test.go new file mode 100644 index 000000000..aa46f8ab0 --- /dev/null +++ b/internal/httpclient/wire/handshake_wire_revision_test.go @@ -0,0 +1,122 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). +package wire + +import ( + "errors" + "strconv" + "strings" + "testing" +) + +// contextBodyWithWireRevision is contextBody plus the two wire-shape members +// task #2 reads. wireRevision/minClientWireRevision of 0 renders the member +// omitted entirely rather than a literal 0, matching what a pre-#6053 server +// (one that predates ContextResponse.wire_revision) actually sends — the +// permanently-retired-value rule (ContextResponse.WireRevision's doc) means a +// server that HAS the field never legitimately sends a literal 0 either, so +// this helper cannot accidentally construct a body a real server would. +func contextBodyWithWireRevision(apiVersion, projectID string, wireRevision, minClientWireRevision int, capabilities ...string) string { + base := contextBody(apiVersion, projectID, capabilities...) + // contextBody always closes with `"schema_version":7}`; splice the two + // extra members in before the closing brace rather than hand-rolling the + // whole document a second time. + const suffix = `"schema_version":7}` + if len(base) < len(suffix) || base[len(base)-len(suffix):] != suffix { + panic("contextBody shape changed; update contextBodyWithWireRevision") + } + head := base[:len(base)-1] // drop the closing brace + extra := "" + if wireRevision != 0 { + extra += `,"wire_revision":` + strconv.Itoa(wireRevision) + } + if minClientWireRevision != 0 { + extra += `,"min_client_wire_revision":` + strconv.Itoa(minClientWireRevision) + } + return head + extra + "}" +} + +func TestHandshakeAcceptsAnOmittedWireRevision(t *testing.T) { + // A server that predates the field omits it; the decoded zero value must + // read as "in range," never as a skew to refuse. + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBodyWithWireRevision("v0", "proj-1", 0, 0, "issues.list"))) + if _, err := c.Handshake(ctx(t)); err != nil { + t.Fatalf("Handshake: %v", err) + } +} + +func TestHandshakeAcceptsTheClientsOwnWireRevisionExactly(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBodyWithWireRevision("v0", "proj-1", ClientWireRevision, 0, "issues.list"))) + if _, err := c.Handshake(ctx(t)); err != nil { + t.Fatalf("Handshake: %v", err) + } +} + +func TestHandshakeRefusesWhenTheServersFloorExceedsThisClient(t *testing.T) { + // min_client_wire_revision above what this build speaks: the server + // requires a newer client than this one. + c, _ := newTestClient(t, Options{}, nil, + serveContext(contextBodyWithWireRevision("v0", "proj-1", ClientWireRevision, ClientWireRevision+1, "issues.list"))) + _, err := c.Handshake(ctx(t)) + if !errors.Is(err, ErrWireRevisionSkew) { + t.Fatalf("err = %v, want ErrWireRevisionSkew", err) + } + var skew *WireRevisionSkewError + if !errors.As(err, &skew) { + t.Fatalf("err is %T, want *WireRevisionSkewError", err) + } + if skew.MinClientWireRevision != ClientWireRevision+1 { + t.Errorf("MinClientWireRevision = %d, want %d", skew.MinClientWireRevision, ClientWireRevision+1) + } + if skew.ClientWireRevision != ClientWireRevision { + t.Errorf("ClientWireRevision = %d, want %d", skew.ClientWireRevision, ClientWireRevision) + } + msg := err.Error() + if !strings.Contains(msg, strconv.Itoa(ClientWireRevision+1)) { + t.Errorf("Error() = %q, want it to name the server's floor", msg) + } +} + +func TestHandshakeRefusesWhenTheServersOwnWireRevisionIsNewerThanThisClient(t *testing.T) { + // wire_revision ahead of this client, with a floor this client still + // clears: this client cannot safely decode a shape newer than its own. + future := ClientWireRevision + 5 + c, _ := newTestClient(t, Options{}, nil, + serveContext(contextBodyWithWireRevision("v0", "proj-1", future, 0, "issues.list"))) + _, err := c.Handshake(ctx(t)) + if !errors.Is(err, ErrWireRevisionSkew) { + t.Fatalf("err = %v, want ErrWireRevisionSkew", err) + } + var skew *WireRevisionSkewError + if !errors.As(err, &skew) { + t.Fatalf("err is %T, want *WireRevisionSkewError", err) + } + if skew.ServerWireRevision != future { + t.Errorf("ServerWireRevision = %d, want %d", skew.ServerWireRevision, future) + } +} + +func TestHandshakeWireRevisionGateRunsBeforeTheIdentityGate(t *testing.T) { + // A server whose wire shape this client cannot speak is not a server worth + // reporting a wrong-project diagnosis against either: the skew error must + // win even when the project id ALSO disagrees. + c, _ := newTestClient(t, Options{ExpectProjectID: "proj-1"}, nil, + serveContext(contextBodyWithWireRevision("v0", "proj-2", ClientWireRevision, ClientWireRevision+1, "issues.list"))) + _, err := c.Handshake(ctx(t)) + if !errors.Is(err, ErrWireRevisionSkew) { + t.Fatalf("err = %v, want ErrWireRevisionSkew (not a project-mismatch)", err) + } + if errors.Is(err, ErrProjectMismatch) { + t.Fatal("err also satisfies ErrProjectMismatch; the wire-revision gate must win outright, not merely run first") + } +} + +func TestEveryRequestStampsTheClientsDeclaredWireRevision(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, serveContext(contextBodyWithWireRevision("v0", "proj-1", ClientWireRevision, 0, "issues.list"))) + if _, err := c.Handshake(ctx(t)); err != nil { + t.Fatalf("Handshake: %v", err) + } + got := rec.at(t, 0).header.Get(WireRevisionHeader) + if got != strconv.Itoa(ClientWireRevision) { + t.Errorf("%s header = %q, want %q", WireRevisionHeader, got, strconv.Itoa(ClientWireRevision)) + } +} diff --git a/internal/httpclient/wire/helpers_test.go b/internal/httpclient/wire/helpers_test.go new file mode 100644 index 000000000..cded7dfe1 --- /dev/null +++ b/internal/httpclient/wire/helpers_test.go @@ -0,0 +1,132 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/helpers_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "io" + "net/http" + "net/http/httptest" + "net/url" + "sync" + "testing" +) + +// The whole suite is httptest servers with canned bytes: no Dolt, no bd serve, +// no subprocess. That is deliberate, and it is what lets this layer own the +// entire branch matrix — every problem code, both retry outcomes, both +// polarities of every presence-discriminated extension member — at PR cadence +// (engdocs/TESTING.md §2: lower layers own the branch matrix before anything +// defers to a slower lane). + +// recorder captures what the client actually put on the wire. +type recorder struct { + mu sync.Mutex + reqs []recorded +} + +type recorded struct { + method string + path string + rawPath string + rawQuery string + header http.Header + body []byte +} + +func (r *recorder) add(req *http.Request) { + body, _ := io.ReadAll(req.Body) + r.mu.Lock() + defer r.mu.Unlock() + r.reqs = append(r.reqs, recorded{ + method: req.Method, + path: req.URL.Path, + rawPath: req.URL.EscapedPath(), + rawQuery: req.URL.RawQuery, + header: req.Header.Clone(), + body: body, + }) +} + +func (r *recorder) count() int { + r.mu.Lock() + defer r.mu.Unlock() + return len(r.reqs) +} + +func (r *recorder) at(t *testing.T, i int) recorded { + t.Helper() + r.mu.Lock() + defer r.mu.Unlock() + if i >= len(r.reqs) { + t.Fatalf("wanted request %d, only %d were made", i, len(r.reqs)) + } + return r.reqs[i] +} + +// newTestClient stands up a server around h and returns a client aimed at it. +func newTestClient(t *testing.T, opts Options, creds CredentialProvider, h http.HandlerFunc) (*Client, *recorder) { + t.Helper() + rec := &recorder{} + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + rec.add(r) + h(w, r) + })) + t.Cleanup(srv.Close) + + base, err := url.Parse(srv.URL) + if err != nil { + t.Fatalf("parse test server URL: %v", err) + } + if opts.HTTPClient == nil { + opts.HTTPClient = srv.Client() + } + c, err := New(base, creds, opts) + if err != nil { + t.Fatalf("New: %v", err) + } + return c, rec +} + +// problemJSON is the shape the server writes for every non-2xx. +func problemJSON(w http.ResponseWriter, status int, body string) { + w.Header().Set("Content-Type", "application/problem+json; charset=utf-8") + w.WriteHeader(status) + _, _ = io.WriteString(w, body) +} + +// staticToken is the smallest CredentialProvider that exercises the interface: +// it authorizes with whatever token it currently holds, and Refresh advances to +// the next one exactly as a rotated token file would. +type staticToken struct { + tokens []string + refreshN int + retry bool + err error +} + +func (s *staticToken) Authorize(_ context.Context, req *http.Request) error { + if len(s.tokens) == 0 { + return nil + } + req.Header.Set("Authorization", "Bearer "+s.tokens[0]) + return nil +} + +func (s *staticToken) Refresh(context.Context) (bool, error) { + s.refreshN++ + if s.err != nil { + return false, s.err + } + if s.retry && len(s.tokens) > 1 { + s.tokens = s.tokens[1:] + } + return s.retry, nil +} + +func ctx(t *testing.T) context.Context { + t.Helper() + c, cancel := context.WithCancel(context.Background()) + t.Cleanup(cancel) + return c +} diff --git a/internal/httpclient/wire/paths.go b/internal/httpclient/wire/paths.go new file mode 100644 index 000000000..097e5534f --- /dev/null +++ b/internal/httpclient/wire/paths.go @@ -0,0 +1,221 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/paths.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "fmt" + "net/url" + "strings" +) + +// The operation ids, spelled exactly as the document's operationId values and +// as internal/httpapi's Op* constants. They are redeclared here rather than +// imported because internal/httpapi is the SERVER — importing it would drag the +// storage engine into every process that only wants to talk to one. +// TestOperationIdsMatchTheServerRouteTable is the seam that keeps the two +// spellings from drifting. +const ( + OpHealth = "health" + OpGetContext = "getContext" + OpListReadyWork = "listReadyWork" + OpCountReadyWork = "countReadyWork" + OpGetStats = "getStats" + OpListIssues = "listIssues" + OpQueryIssues = "queryIssues" + OpGetIssue = "getIssue" + OpClaimIssue = "claimIssue" + OpCloseIssue = "closeIssue" + OpReopenIssue = "reopenIssue" + OpUpdateIssue = "updateIssue" + OpSweepIssues = "sweepIssues" + OpDeleteIssues = "deleteIssues" + OpBatchCreateIssues = "batchCreateIssues" + OpBatchCloseIssues = "batchCloseIssues" + OpClaimNextIssue = "claimNextIssue" + OpReleaseIssue = "releaseIssue" + OpCountIssues = "countIssues" + OpCreateIssue = "createIssue" + OpApplyBatch = "applyBatch" + OpCompareAndSetMetadata = "compareAndSetMetadata" + OpListEvents = "listEvents" + OpWatchEvents = "watchEvents" + OpListSettings = "listSettings" + OpGetSetting = "getSetting" + OpSetSetting = "setSetting" + OpUnsetSetting = "unsetSetting" + OpListDependencies = "listDependencies" + OpListBlockingAnnotations = "listBlockingAnnotations" + OpGetDependencyTree = "getDependencyTree" + OpCountDependencyEdges = "countDependencyEdges" + OpListRelatedIssues = "listRelatedIssues" + OpAddComment = "addComment" + OpListDependencyCycles = "listDependencyCycles" + OpAddDependencies = "addDependencies" + OpRemoveDependency = "removeDependency" + OpListMemories = "listMemories" + OpRememberMemory = "rememberMemory" + OpGetMemory = "getMemory" + OpForgetMemory = "forgetMemory" +) + +// The paths that carry no caller-supplied segment. A path with one is built by +// the functions below, because an id has to be escaped before it can be joined. +const ( + PathHealth = "/healthz" + PathContext = "/v0/beads/context" + PathReady = "/v0/beads/ready" + PathReadyCount = "/v0/beads/ready:count" + PathStats = "/v0/beads/stats" + PathIssues = "/v0/beads/issues" + PathIssuesQuery = "/v0/beads/issues:query" + PathIssuesCount = "/v0/beads/issues:count" + PathIssuesSweep = "/v0/beads/issues:sweep" + PathIssuesDelete = "/v0/beads/issues:delete" + PathIssuesBatchCreate = "/v0/beads/issues:batchCreate" + PathIssuesBatchClose = "/v0/beads/issues:batchClose" + PathIssuesClaimNext = "/v0/beads/issues:claimNext" + PathIssuesBatchApply = "/v0/beads/issues:batchApply" + PathSettings = "/v0/beads/config" + PathEvents = "/v0/beads/events" + PathEventsWatch = "/v0/beads/events:watch" + PathDependencies = "/v0/beads/dependencies" + PathDependenciesCount = "/v0/beads/dependencies:count" + PathDependenciesBlocking = "/v0/beads/dependencies/blocking" + PathDependenciesTree = "/v0/beads/dependencies/tree" + PathDependenciesCycles = "/v0/beads/dependencies/cycles" + PathDependenciesAdd = "/v0/beads/dependencies:add" + PathDependenciesRemove = "/v0/beads/dependencies:remove" + PathMemories = "/v0/beads/memories" +) + +// The custom methods that ride on the issue-detail segment. The server splits +// them back off the segment its wildcard matched (internal/httpapi/routes.go, +// customMethodTarget), so the suffix must be the LAST thing in that segment and +// its colon must be literal — which is the whole reason escapeSegment escapes a +// colon inside the id itself. +const ( + MethodClaim = ":claim" + MethodClose = ":close" + MethodReopen = ":reopen" + MethodRelease = ":release" + MethodCASMetadata = ":casMetadata" +) + +// The sub-resource collections that hang off the issue-detail path. Unlike a +// custom method these are ORDINARY segments after the id, so the server routes +// them with a literal rather than through the custom-method dispatcher — but the +// id in front of them is still one wildcard-matched segment, which is why they +// go through the same escape. +const ( + SubresourceComments = "comments" + SubresourceRelated = "related" +) + +// IssuePath is the issue-detail path: GET reads it, PATCH updates it. +func IssuePath(id string) (string, error) { + seg, err := escapeSegment("issue id", id) + if err != nil { + return "", err + } + return PathIssues + "/" + seg, nil +} + +// IssueMethodPath is the issue-detail path with a custom method appended to the +// final segment: /v0/beads/issues/{id}:claim and its two siblings. +func IssueMethodPath(id, method string) (string, error) { + switch method { + case MethodClaim, MethodClose, MethodReopen, MethodRelease, MethodCASMetadata: + default: + return "", fmt.Errorf("no custom method %q on the issue resource", method) + } + base, err := IssuePath(id) + if err != nil { + return "", err + } + return base + method, nil +} + +// IssueCommentsPath is the comment collection an issue owns: the POST that +// appends one comment to its thread. +// +// There is no GET here on purpose. The wire publishes no comment page — the +// thread is read through `GET /v0/beads/issues/{id}?include_comments=true` — so +// a read helper on this path would name a route that does not exist. +func IssueCommentsPath(id string) (string, error) { + return issueSubresourcePath(id, SubresourceComments) +} + +// IssueRelatedPath is the neighbor read anchored on one issue. +func IssueRelatedPath(id string) (string, error) { + return issueSubresourcePath(id, SubresourceRelated) +} + +// issueSubresourcePath joins a literal collection onto the escaped issue +// segment. +// +// The escape matters MORE here than on the detail path, not less, and it is +// worth saying why the sub-resource does not make it safe: a slash in the id +// would push the literal onto a third segment, so `/comments` would no longer be +// the collection this request named. The server's wildcard matches exactly one +// segment, so that request 404s rather than writing to another anchor's thread — +// but only because the path shape is what it is, and escapeSegment is what keeps +// it that way for every id. +func issueSubresourcePath(id, collection string) (string, error) { + base, err := IssuePath(id) + if err != nil { + return "", err + } + return base + "/" + collection, nil +} + +// SettingPath is the single-setting read path. +func SettingPath(key string) (string, error) { + seg, err := escapeSegment("setting key", key) + if err != nil { + return "", err + } + return PathSettings + "/" + seg, nil +} + +// MemoryPath is the single-memory path, shared by the read and the delete. +// +// Memory keys are the widest segment on this surface — the document allows +// spaces, dots and unicode — so this is the escape that earns its keep. +func MemoryPath(key string) (string, error) { + seg, err := escapeSegment("memory key", key) + if err != nil { + return "", err + } + return PathMemories + "/" + seg, nil +} + +// escapeSegment percent-escapes one caller-supplied path segment. +// +// url.PathEscape is the start of the job and not the end of it. Two characters +// it deliberately leaves alone are load-bearing here: +// +// ':' is legal in a path segment, so PathEscape keeps it — but on THIS +// surface a trailing `:verb` is a custom method the server splits off the +// segment. An id ending in ":claim" would be read as a claim of a shorter +// id, and one containing any colon makes the split ambiguous. It travels +// escaped. +// '.' survives too, and the joins below run through path.Join, which RESOLVES +// "." and ".." — a segment that is one of them would climb out of its own +// collection. Only the whole-segment case can do that, so only it is +// rewritten. +// +// An empty segment is refused rather than escaped: it would join to the +// collection path and turn a read of one resource into a read of all of them. +func escapeSegment(kind, s string) (string, error) { + if s == "" { + return "", fmt.Errorf("empty %s", kind) + } + seg := strings.ReplaceAll(url.PathEscape(s), ":", "%3A") + switch seg { + case ".": + seg = "%2E" + case "..": + seg = "%2E%2E" + } + return seg, nil +} diff --git a/internal/httpclient/wire/paths_test.go b/internal/httpclient/wire/paths_test.go new file mode 100644 index 000000000..abeddc981 --- /dev/null +++ b/internal/httpclient/wire/paths_test.go @@ -0,0 +1,253 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/paths_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "net/http" + "net/url" + "strings" + "testing" +) + +func TestIssuePathEscapesTheIDIntoOneSegment(t *testing.T) { + cases := []struct { + name string + id string + want string + }{ + {"ordinary id", "ga-93nh1", "/v0/beads/issues/ga-93nh1"}, + // A slash would otherwise split the id across two segments and address + // a route that does not exist. + {"slash", "a/b", "/v0/beads/issues/a%2Fb"}, + // The one PathEscape leaves alone: a colon inside the id is + // indistinguishable from a custom-method suffix once it is on the wire. + {"colon", "ga-1:claim", "/v0/beads/issues/ga-1%3Aclaim"}, + {"space and unicode", "a bé", "/v0/beads/issues/a%20b%C3%A9"}, + {"newline", "a\nb", "/v0/beads/issues/a%0Ab"}, + {"percent", "50%", "/v0/beads/issues/50%25"}, + // path.Join resolves these, so as a whole segment they must travel + // escaped or they climb out of the collection. + {"dot", ".", "/v0/beads/issues/%2E"}, + {"dotdot", "..", "/v0/beads/issues/%2E%2E"}, + {"dot inside an id is ordinary", "ga-1.2", "/v0/beads/issues/ga-1.2"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got, err := IssuePath(tc.id) + if err != nil { + t.Fatalf("IssuePath(%q): %v", tc.id, err) + } + if got != tc.want { + t.Errorf("IssuePath(%q) = %q, want %q", tc.id, got, tc.want) + } + }) + } +} + +func TestEscapedSegmentsRoundTripBackToTheID(t *testing.T) { + // The escaping is only correct if the server decodes it to the id we meant. + for _, id := range []string{"ga-93nh1", "a/b", "ga-1:claim", "a bé", "..", ".", "50%", "a\nb"} { + path, err := IssuePath(id) + if err != nil { + t.Fatalf("IssuePath(%q): %v", id, err) + } + seg := path[strings.LastIndex(path, "/")+1:] + got, err := url.PathUnescape(seg) + if err != nil { + t.Fatalf("unescape %q: %v", seg, err) + } + if got != id { + t.Errorf("segment for %q decodes to %q", id, got) + } + } +} + +func TestEmptySegmentsAreRefusedRatherThanJoined(t *testing.T) { + // An empty segment would collapse a single-resource read into a read of the + // whole collection, which is the same request with a very different answer. + if _, err := IssuePath(""); err == nil { + t.Error("IssuePath(\"\") returned no error") + } + if _, err := SettingPath(""); err == nil { + t.Error("SettingPath(\"\") returned no error") + } + if _, err := MemoryPath(""); err == nil { + t.Error("MemoryPath(\"\") returned no error") + } + if _, err := IssueMethodPath("", MethodClaim); err == nil { + t.Error("IssueMethodPath(\"\", :claim) returned no error") + } + if _, err := IssueCommentsPath(""); err == nil { + t.Error("IssueCommentsPath(\"\") returned no error") + } + if _, err := IssueRelatedPath(""); err == nil { + t.Error("IssueRelatedPath(\"\") returned no error") + } +} + +// TestIssueSubresourcePathsEscapeTheAnchorIntoOneSegment covers the two paths +// whose collection name comes AFTER the id, which is the shape no other path on +// this surface has. +// +// The literal suffix is what makes the escaping load-bearing in a second way: an +// unescaped slash in the id would not merely address a missing route, it would +// make `/comments` land under a DIFFERENT anchor than the caller named — and the +// server's wildcard matches one segment, so the request would 404 rather than +// write to the wrong thread. Both failure modes are closed by the same escape. +func TestIssueSubresourcePathsEscapeTheAnchorIntoOneSegment(t *testing.T) { + for _, tc := range []struct { + name string + id string + comments, rel string + }{ + {"ordinary id", "ga-93nh1", "/v0/beads/issues/ga-93nh1/comments", "/v0/beads/issues/ga-93nh1/related"}, + {"slash", "a/b", "/v0/beads/issues/a%2Fb/comments", "/v0/beads/issues/a%2Fb/related"}, + {"colon", "ga-1:claim", "/v0/beads/issues/ga-1%3Aclaim/comments", "/v0/beads/issues/ga-1%3Aclaim/related"}, + {"dotdot", "..", "/v0/beads/issues/%2E%2E/comments", "/v0/beads/issues/%2E%2E/related"}, + } { + t.Run(tc.name, func(t *testing.T) { + got, err := IssueCommentsPath(tc.id) + if err != nil { + t.Fatalf("IssueCommentsPath(%q): %v", tc.id, err) + } + if got != tc.comments { + t.Errorf("IssueCommentsPath(%q) = %q, want %q", tc.id, got, tc.comments) + } + got, err = IssueRelatedPath(tc.id) + if err != nil { + t.Fatalf("IssueRelatedPath(%q): %v", tc.id, err) + } + if got != tc.rel { + t.Errorf("IssueRelatedPath(%q) = %q, want %q", tc.id, got, tc.rel) + } + }) + } +} + +func TestIssueMethodPathBuildsTheSuffixIntoTheFinalSegment(t *testing.T) { + cases := []struct { + method string + want string + }{ + {MethodClaim, "/v0/beads/issues/ga-1:claim"}, + {MethodClose, "/v0/beads/issues/ga-1:close"}, + {MethodReopen, "/v0/beads/issues/ga-1:reopen"}, + {MethodRelease, "/v0/beads/issues/ga-1:release"}, + } + for _, tc := range cases { + got, err := IssueMethodPath("ga-1", tc.method) + if err != nil { + t.Fatalf("IssueMethodPath(ga-1, %s): %v", tc.method, err) + } + if got != tc.want { + t.Errorf("IssueMethodPath(ga-1, %s) = %q, want %q", tc.method, got, tc.want) + } + } +} + +func TestIssueMethodPathKeepsTheSuffixUnambiguous(t *testing.T) { + // The server splits the custom method off the segment its wildcard matched, + // so exactly one literal colon may survive: the suffix's. + got, err := IssueMethodPath("ga-1:close", MethodClaim) + if err != nil { + t.Fatalf("IssueMethodPath: %v", err) + } + if got != "/v0/beads/issues/ga-1%3Aclose:claim" { + t.Fatalf("got %q", got) + } + if strings.Count(got[strings.LastIndex(got, "/"):], ":") != 1 { + t.Errorf("more than one literal colon in the final segment: %q", got) + } +} + +func TestIssueMethodPathRefusesAnUnpublishedCustomMethod(t *testing.T) { + if _, err := IssueMethodPath("ga-1", ":delete"); err == nil { + t.Error("an unpublished custom method returned no error") + } +} + +func TestCollectionPathsMatchTheDocument(t *testing.T) { + // The dependency and memory operations are collection-level: their custom + // methods are literal segments, not suffixes on a wildcard. + want := map[string]string{ + PathDependencies: "/v0/beads/dependencies", + PathDependenciesBlocking: "/v0/beads/dependencies/blocking", + PathDependenciesTree: "/v0/beads/dependencies/tree", + PathDependenciesCycles: "/v0/beads/dependencies/cycles", + PathDependenciesAdd: "/v0/beads/dependencies:add", + PathDependenciesRemove: "/v0/beads/dependencies:remove", + PathMemories: "/v0/beads/memories", + PathIssuesSweep: "/v0/beads/issues:sweep", + PathIssuesDelete: "/v0/beads/issues:delete", + PathIssuesBatchCreate: "/v0/beads/issues:batchCreate", + PathIssuesQuery: "/v0/beads/issues:query", + PathReadyCount: "/v0/beads/ready:count", + PathIssuesCount: "/v0/beads/issues:count", + PathDependenciesCount: "/v0/beads/dependencies:count", + } + for got, expected := range want { + if got != expected { + t.Errorf("path constant = %q, want %q", got, expected) + } + } +} + +func TestMemoryAndSettingKeysAreEscapedIntoOneSegment(t *testing.T) { + // Memory keys are the widest segment on this surface: the document allows + // spaces, dots and unicode. + got, err := MemoryPath("notes/2026 planning.md") + if err != nil { + t.Fatalf("MemoryPath: %v", err) + } + if got != "/v0/beads/memories/notes%2F2026%20planning.md" { + t.Errorf("MemoryPath = %q", got) + } + got, err = SettingPath("types.infra") + if err != nil { + t.Fatalf("SettingPath: %v", err) + } + if got != "/v0/beads/config/types.infra" { + t.Errorf("SettingPath = %q", got) + } +} + +func TestTheURLTheServerSeesKeepsTheEscapingAndTheMountRoot(t *testing.T) { + // The end-to-end statement the escaping exists to make: whatever the id, the + // server's router sees one segment and decodes it back to the id, under + // whatever prefix the base URL mounts the surface at. + var gotPath, gotRaw, gotID string + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + gotPath, gotRaw = r.URL.EscapedPath(), r.URL.RawQuery + gotID = strings.TrimPrefix(r.URL.Path, "/mount/v0/beads/issues/") + _, _ = w.Write([]byte(`{}`)) + }) + mounted := c.BaseURL().JoinPath("/mount/") + c, err := New(mounted, nil, Options{HTTPClient: c.hc}) + if err != nil { + t.Fatalf("New: %v", err) + } + + path, err := IssueMethodPath("a/b:x", MethodClaim) + if err != nil { + t.Fatalf("IssueMethodPath: %v", err) + } + var out map[string]any + if err := c.Do(ctx(t), Request{ + Op: OpClaimIssue, + Method: http.MethodPost, + Path: path, + Query: url.Values{"actor": {"me"}}, + }, &out); err != nil { + t.Fatalf("Do: %v", err) + } + + if want := "/mount/v0/beads/issues/a%2Fb%3Ax:claim"; gotPath != want { + t.Errorf("escaped path = %q, want %q", gotPath, want) + } + if gotID != "a/b:x:claim" { + t.Errorf("decoded final segment = %q, want %q", gotID, "a/b:x:claim") + } + if gotRaw != "actor=me" { + t.Errorf("query = %q, want actor=me", gotRaw) + } +} diff --git a/internal/httpclient/wire/problem.go b/internal/httpclient/wire/problem.go new file mode 100644 index 000000000..db2371718 --- /dev/null +++ b/internal/httpclient/wire/problem.go @@ -0,0 +1,838 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/problem.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "encoding/json" + "errors" + "fmt" + "net/http" + "slices" + "strconv" + "strings" + "time" + "unicode" + + "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/issueops" +) + +// The refusals with no analog in the local store's vocabulary, because each is +// a statement about a SERVER rather than about the workspace. Everything else +// in the code table maps to the canonical issueops sentinel the embedded store +// would have returned for the same refusal, so a caller classifies a remote +// refusal with the errors.Is arm it already has. +var ( + // ErrInvalidCursor is a cursor this server did not issue, cannot decode, or + // issued under a different internal version. The recovery is to restart + // paging without it, which is why it is not folded into ErrValidation: a + // stale cursor is a normal client situation, not a client bug. + ErrInvalidCursor = errors.New("cursor is not valid for this server; restart paging") + // ErrUnauthenticated is a missing, malformed or unrecognized credential on + // a server that was configured with one. It never carries the credential or + // any hint of which of the three it was — the server refuses to say, and + // repeating a guess here would undo that. + ErrUnauthenticated = errors.New("bd serve refused the credential") + // ErrBusy is retryable contention: the server's transaction retry budget was + // exhausted, or its in-flight limit was saturated. + ErrBusy = errors.New("bd serve is busy") + // ErrDBUnavailable is a retryable failure to reach the served database. + ErrDBUnavailable = errors.New("bd serve cannot reach its database") + // ErrServerFault is an unexpected server-side failure. Its detail is a fixed + // string by design, so ProblemError.RequestID is the only handle on the log + // line that has the real error. + ErrServerFault = errors.New("bd serve failed") + // ErrBadRequest is the 4xx default branch: a code this client does not know, + // on a status class that says the request was wrong. Failing loud is the + // documented posture — an unknown 4xx is a client bug, and retrying or + // degrading past one hides it. + ErrBadRequest = errors.New("bd serve refused the request") + + // The journal codes. This client dials no journal operation — httpstore + // carries no EventsJournal accessor, so nothing here can produce a request + // that earns one of these — and they are on the code table anyway, because + // the vocabulary gate is set-equality with the document rather than with + // what this client happens to reach today. A code the document publishes + // and this table omitted would take the 4xx default branch and be reported + // as a client bug on the day the journal accessor lands. + + // ErrEventsJournalDisabled is the served workspace having its journal OFF. + // The recovery is entirely the operator's — set `events-journal true` and + // restart the server — so it is not folded into ErrValidation, which would + // send a caller looking at its own request. + ErrEventsJournalDisabled = errors.New("bd serve: the events journal is not enabled on the served workspace") + // ErrEventsWatchSaturated is the server already holding as many open + // journal streams as it will. It is NOT ErrBusy despite the shared 503: + // busy says the database is congested and the same request will work + // shortly, this says a bounded resource is fully subscribed by connections + // that may last hours, and the caller has a recovery busy does not offer — + // the paged read, which holds nothing between requests. + ErrEventsWatchSaturated = errors.New("bd serve: no journal stream slots are free") + // ErrPreconditionFailed is a compare-and-set guard that missed on an + // operation whose contract is that a miss refuses everything. It is the + // fallback for the shape the server did not name: when `param` says which + // guard missed, the table answers with the issueops sentinel the embedded + // store would have returned for the same miss. + ErrPreconditionFailed = errors.New("bd serve: a precondition on the request did not hold") + // ErrEventsJournalTruncated is a journal read whose checkpoint has fallen + // below the retained window. ProblemError carries the window itself + // (Since/Floor/Head), because the recovery is a decision the consumer makes + // from those three numbers rather than from this sentence. + ErrEventsJournalTruncated = errors.New("bd serve: the journal checkpoint is below the retained window") + + // ErrUnknownItemCode is the PER-ITEM analog of the 4xx default branch above: + // a BatchCloseItemError.code this client does not recognize. Per-item codes + // grow additively exactly as Problem.code does — the schema tells clients to + // default-branch on an unknown one — so an unfamiliar code must not hard-fail + // the whole batch. It lands as a TYPED per-item outcome instead, so a caller + // tells "this item was refused for a reason my client is too old to name" + // from a success rather than reading it as one. + ErrUnknownItemCode = errors.New("bd serve refused a batch-close item with a code this client does not recognize") +) + +// UnknownItemCodeError is the typed carrier for that per-item refusal. It keeps +// the code verbatim and the server's optional detail so a renderer can show what +// it could not classify, and unwraps to ErrUnknownItemCode so errors.Is reaches +// it. Both strings are server-controlled, so the layer that builds one strips +// their control runes the way mapProblem strips every other wire field. +type UnknownItemCodeError struct { + IssueID string + Code string + Detail string +} + +func (e *UnknownItemCodeError) Error() string { + if e.Detail != "" { + return fmt.Sprintf("issue %s: bd serve refused it with an unrecognized batch-close code %q: %s", e.IssueID, e.Code, e.Detail) + } + return fmt.Sprintf("issue %s: bd serve refused it with an unrecognized batch-close code %q", e.IssueID, e.Code) +} + +func (e *UnknownItemCodeError) Unwrap() error { return ErrUnknownItemCode } + +// ProblemError is a non-2xx answer from bd serve, decoded from its RFC 9457 +// problem+json body. +// +// It carries the whole envelope because the layers above reconstruct typed +// refusals and user-facing text from it: `code` is the dispatch key, `param` +// and `reason` turn a 400 back into the flag that produced it, `request_id` is +// what makes a 5xx actionable, and the extension members are the typed +// discriminators the server reads inside the refusing transaction. +// +// The extension members are POINTERS because presence is load-bearing on three +// of them: `open_children` separates the two not_closable refusals, `issue_id` +// separates a hierarchy conflict from a plain scheduling cycle, and +// `blocker_is_ancestor` is emitted in both polarities and so cannot use absence +// to mean false. +type ProblemError struct { + // Op is the operation id that was dialed, and ServerURL the base URL it was + // dialed against. Neither comes off the wire; both are what the refusal + // taxonomy needs to name the server in its text. + Op string + ServerURL string + + Status int + Code string + Title string + Detail string + Param string + Reason string + RequestID string + + // CredentialSource names the ladder rung whose credential the server refused, + // set only on a 401 and only when the provider can report it (design D7). It + // is a provenance label — an env var name, a command's env var, or the + // credentials file [host:port] — never the credential itself, so it is safe + // in error text bound for logs and terminals. + CredentialSource string + + // RetryAfter is the server's Retry-After header, already bounded (see + // Options.MaxRetryAfter). Zero when the header was absent, unparseable or + // in the past. + RetryAfter time.Duration + + Assignee *string + IssueStatus *string + OpenChildren *int + ExistingType *string + RequestedType *string + IssueID *string + BlockerID *string + BlockerIsAncestor *bool + + // The compare-and-set guard's two sides, with `precondition_failed`. `param` + // says WHICH guard missed and these say what the request asked for and what + // the row was found holding, split BY TYPE rather than carried as one + // polymorphic pair — a member that is "a version or a status or an + // assignee" is a schema alternation, and this document spells three typed + // pairs instead. + // + // They are pointers for the reason every pointer here is one: PRESENCE is + // load-bearing on all six. An `expected_*` echoes the request, so its + // absence means the operation carried no such guard — and 0 and "" are both + // real guards, so neither zero value can stand in for absence. An `actual_*` + // is present only where the refusing operation can REPORT what it found: an + // all-or-nothing operation rolls its transaction back, and a value read + // after the fact would describe a row the refusal never saw, so absence + // there means "this server cannot tell you", never "it found zero". + // + // THE VERSIONS ARE CARRIED AS THE STRINGS THE WIRE SPELLS THEM IN. Since + // upstream #6053 every revision token on the surface is a decimal string + // (types.RevisionToken), never a JSON number, so nothing on this path can + // round one. They are deliberately NOT parsed back to int64 here: the token + // is opaque and equality-only, `expected_version` is the ECHO of what the + // request sent (a caller comparing it to its own guard compares + // types.RevisionToken(guard) to it), and `actual_version` is a diagnostic — + // the contract says to compose the next guard from a `revision` a WRITE + // answered with, never from a refusal. Parsing on the refusal path could + // only turn a well-formed 409 into a decode failure or drop a member whose + // presence is load-bearing, and nothing in this package reads them + // numerically. They are stripped like every other server-controlled string. + ExpectedVersion *string + ActualVersion *string + ExpectedStatus *string + ActualStatus *string + ExpectedAssignee *string + ActualAssignee *string + + // The batch-item members, on a refusal from an operation whose items are + // HETEROGENEOUS and may be named — issues:batchApply is the whole + // population. They are the only place the offender exists: that operation + // is all or nothing, so a refusal carries no per-item result array for a + // client to find it in, and the server reads these off the role's own typed + // *issueops.ItemError inside the transaction that refused. + // + // PRESENCE IS LOAD-BEARING ON ALL OF THEM, which is why the index is a + // pointer and not an int: 0 is the FIRST ITEM and a real answer, so a bare + // int could not tell it from a refusal that named no item at all. Key and + // IssueID are absent for real states rather than gaps — not every item + // carries a key, and a create whose id was never minted has none to report. + // + // ItemIssueID is deliberately NOT ProblemError.IssueID, and the divergence + // is the server's rather than a spelling choice here: IssueID's PRESENCE + // discriminates the dependency_cycle hierarchy refusal from the plain + // scheduling one, so a batch reusing it would fire that discriminator on + // refusals it says nothing about. + ItemIndex *int + ItemKind *string + ItemKey *string + ItemIssueID *string + // DeclaredLater tells the two unresolvable-key diagnoses apart: true is an + // ORDERING mistake — the key IS declared, by a later item, and a key + // reaches backward only — and false is a key nothing in the request + // declares, which is a typo or a missing item. It is emitted in BOTH + // polarities, so it is a pointer for the reason BlockerIsAncestor is one: + // absence has to mean "this refusal was not about a key", never false. + DeclaredLater *bool + + // The journal-truncation window, with `events_journal_truncated`: the + // checkpoint the window begins after, the lowest seq still retained, and the + // highest seq ever assigned. + // + // They are carried rather than folded into the sentinel because that + // sentinel is storage.EventsJournalTruncatedError, and this package + // deliberately imports no storage — the whole point of respelling the + // operation ids here is that a process talking to a bd serve does not link + // the engine. A consumer with a journal accessor rebuilds the typed error + // from these three; without them the recovery (resume from floor-1 and + // accept the gap, or re-baseline) would have to be parsed out of prose. + Since *int64 + Floor *int64 + Head *int64 + + // Err is the canonical sentinel this code maps to. It is what Unwrap + // returns, so errors.Is and errors.As reach it. + Err error +} + +func (e *ProblemError) Error() string { + var b strings.Builder + fmt.Fprintf(&b, "%s: bd serve at %s answered %d", e.Op, e.ServerURL, e.Status) + if e.Code != "" { + fmt.Fprintf(&b, " %s", e.Code) + } + if e.Detail != "" { + fmt.Fprintf(&b, ": %s", e.Detail) + } + // The 5xx detail is a fixed string per code and says nothing about the + // underlying failure, so the correlation id is the client's only handle on + // the one server log line that has it. + if e.Status >= 500 && e.RequestID != "" { + fmt.Fprintf(&b, " (request_id %s)", e.RequestID) + } + // Naming the rung the refused credential came from is what turns "the server + // said 401" into something the operator can act on: it says WHICH source to + // rotate or fix (design D7). The server never says which of missing, + // malformed or unrecognized it was, and this does not guess — it reports only + // the client-side provenance of the credential it presented. + if e.Status == http.StatusUnauthorized && e.CredentialSource != "" { + fmt.Fprintf(&b, " (credential from %s)", e.CredentialSource) + } + return b.String() +} + +func (e *ProblemError) Unwrap() error { return e.Err } + +// Retryable reports whether the server said to come back. Only the 503 class +// says so: an unknown 4xx is a client bug and every other 5xx is a fault the +// same request will earn again. +func (e *ProblemError) Retryable() bool { + return e.Status == http.StatusServiceUnavailable || + errors.Is(e.Err, ErrBusy) || errors.Is(e.Err, ErrDBUnavailable) +} + +// ReasonProjectMismatch is the Problem `reason` the server sets on a refusal of +// a Bd-Project-Id stamp for the wrong workspace, spelled exactly as the server's +// httpapi.ReasonProjectMismatch (held to it by +// TestProjectMismatchReasonMatchesTheServerConstant). It is the discriminator +// mapProblem reads to build the typed *ProjectMismatchError, ahead of the code +// table: the code is the generic invalid_argument, so reason is the only thing +// that tells this wrong-server refusal from a malformed-argument one. +const ReasonProjectMismatch = "project_mismatch" + +// ReasonWireRevisionUnsupported is the Problem `reason` the server sets when +// this client's declared Bd-Wire-Revision header named a revision below the +// server's own min_client_wire_revision, spelled exactly as the server's +// httpapi.ReasonWireRevisionUnsupported (held to it by +// TestTheProjectIdentityVocabularyMatchesTheServer). Like ReasonProjectMismatch +// it rides the generic invalid_argument code, so reason is the only thing that +// tells this refusal apart from an ordinary malformed argument. +const ReasonWireRevisionUnsupported = "wire_revision_unsupported" + +// ErrWireRevisionUnsupported reports that bd serve refused this client's +// declared Bd-Wire-Revision header as older than the revision it now +// requires. See WireRevisionUnsupportedError. +var ErrWireRevisionUnsupported = errors.New("bd serve requires a newer client wire revision than this client declared") + +// WireRevisionUnsupportedError is the per-request mirror of the handshake's +// own gate (wire.WireRevisionSkewError, handshake.go): the server has read +// this client's declared Bd-Wire-Revision header (wire.ClientWireRevision, +// stamped on every request by Client.stampRequest) and refused it as below +// the floor it enforces now. Unlike WireRevisionSkewError — raised locally, +// from a 200 ContextResponse, when THIS client decides the SERVER's wire +// shape is one it cannot speak — this one is the SERVER's own refusal, and it +// can arrive on any request, including the context fetch the handshake +// itself makes (ContextResponse.MinClientWireRevision's doc: "raised ... on +// GET /v0/beads/context too"), in which case it surfaces through +// Client.Handshake exactly the way any other *ProblemError from GetContext +// does — no separate handling is needed there. +type WireRevisionUnsupportedError struct { + ServerURL string + BdVersion string + // ClientWireRevision is this build's own declared revision, which is what + // was refused. + ClientWireRevision int + // MinClientWireRevision is the server's own floor, from the refusal's + // min_wire_revision extension member. + MinClientWireRevision int + // ServerWireRevision is the server's own current wire_revision, from the + // refusal's wire_revision extension member. + ServerWireRevision int +} + +func (e *WireRevisionUnsupportedError) Error() string { + return fmt.Sprintf("bd serve at %s (bd_version %s) requires a client wire revision of at least %d; this client declared %d", + e.ServerURL, e.BdVersion, e.MinClientWireRevision, e.ClientWireRevision) +} + +func (e *WireRevisionUnsupportedError) Unwrap() error { return ErrWireRevisionUnsupported } + +// target names the ids the wire's conflict members leave out. The server does +// not echo the issue a claim refused or the edge a dependency_exists collided +// with — the request already said — so the caller supplies them and the +// reconstructed sentinel comes out whole. +type target struct { + op string + serverURL string + issueID string + dependsOnID string + // expectID is the workspace's own pinned project id (Client.expectID), which + // the wire never carries — it is a client-side fact. A project_mismatch + // refusal names the server's own id in server_project_id; pairing it with this + // expected id is what lets the typed *ProjectMismatchError say BOTH sides of + // the disagreement without the client parsing the refusal's prose. + expectID string +} + +// mapProblem decodes an RFC 9457 body and maps it onto the canonical sentinel +// for its code. +// +// `code` is the ONLY dispatch key, per the document: a code carries one frozen +// status, so reading the status instead would be a second, weaker copy of the +// same table. The status is consulted for exactly one thing — the default +// branch for a code this client has never heard of, which is how the vocabulary +// stays additive. +func mapProblem(t target, status int, header http.Header, body []byte, maxRetryAfter time.Duration) *ProblemError { + var p apigen.Problem + // A non-2xx that is not problem+json at all is a real case: a proxy, a load + // balancer or a stray server on the port answers with HTML. It falls through + // to the status-class default branch with an empty code, which is exactly + // what an unrecognized code does. + _ = json.Unmarshal(body, &p) + + // Every string that comes off the wire here is server-controlled and ends up + // in an error rendered to a terminal or a log line — often through a %v sink + // that never touches the CLI's output-boundary strip (bd close/show/reopen/ + // update write each per-id failure straight to os.Stderr). So the control + // runes are removed HERE, the moment the bytes become a typed error, and both + // the direct fields AND the extension members the typed conflicts are + // reconstructed from below (sentinelFor) are cleaned — an issue id echoed by a + // dependency-cycle conflict is as server-controlled as the detail string. The + // pointer members keep their presence, which is load-bearing discrimination on + // three of them. Tab and newline are stripped too (unlike the display-layer + // strip): a problem field is a single value with no legitimate framing. + e := &ProblemError{ + Op: t.op, + ServerURL: t.serverURL, + Status: status, + Code: stripControlRunes(p.Code), + Title: stripControlRunes(p.Title), + Detail: stripControlRunes(deref(p.Detail)), + Param: stripControlRunes(deref(p.Param)), + Reason: stripControlRunes(deref(p.Reason)), + RequestID: stripControlRunes(p.RequestId), + RetryAfter: retryAfter(header, maxRetryAfter), + Assignee: stripControlRunesPtr(p.Assignee), + IssueStatus: stripControlRunesPtr(p.IssueStatus), + OpenChildren: p.OpenChildren, + ExistingType: stripControlRunesPtr(p.ExistingType), + RequestedType: stripControlRunesPtr(p.RequestedType), + IssueID: stripControlRunesPtr(p.IssueId), + BlockerID: stripControlRunesPtr(p.BlockerId), + BlockerIsAncestor: p.BlockerIsAncestor, + Since: p.Since, + Floor: p.Floor, + Head: p.Head, + // The guard pair. All six are strings on the wire — the two versions + // are decimal revision tokens (types.RevisionToken) and are carried as + // the strings the server spelled, see the field comment — and all six + // are stripped like every other server-controlled field, keeping their + // PRESENCE, which is the state that discriminates. + ExpectedVersion: stripControlRunesPtr(p.ExpectedVersion), + ActualVersion: stripControlRunesPtr(p.ActualVersion), + ExpectedStatus: stripControlRunesPtr(p.ExpectedStatus), + ActualStatus: stripControlRunesPtr(p.ActualStatus), + ExpectedAssignee: stripControlRunesPtr(p.ExpectedAssignee), + ActualAssignee: stripControlRunesPtr(p.ActualAssignee), + // The batch-item members. The three strings are stripped like every + // other server-controlled field and keep their presence; the index and + // the ordering discriminator travel as the generated pointers, which is + // what keeps a zero index and a false polarity apart from absence. + ItemIndex: p.ItemIndex, + ItemKind: stripControlRunesPtr(p.ItemKind), + ItemKey: stripControlRunesPtr(p.ItemKey), + ItemIssueID: stripControlRunesPtr(p.ItemIssueId), + DeclaredLater: p.DeclaredLater, + } + legacyRevisionFields(body, e) + + // The wrong-server arm, discriminated on REASON and taken BEFORE the code + // table. A project_mismatch is spelled invalid_argument on the wire, so the + // code table would map it to ErrValidation and lose the whole signal; the + // reason is what tells it apart. It is the one refusal that carries + // server_project_id — the id the server actually serves — which is stripped + // here at the decode boundary like every other server-controlled field and is + // deliberately NOT a generic ProblemError member: it exists only to build this + // typed error, paired with the workspace's own expected id, and unwraps + // ErrProjectMismatch so cmd/bd renders one recovery block for both this + // per-request path and the handshake identity gate. Database and RepoRoot are + // left empty: this refusal discloses only the server's id, not its location. + if e.Reason == ReasonProjectMismatch { + e.Err = &ProjectMismatchError{ + ServerURL: t.serverURL, + Expected: t.expectID, + Got: stripControlRunes(deref(p.ServerProjectId)), + } + return e + } + + // The other document-level arm, discriminated the same way and for the + // same reason: wire_revision_unsupported rides the generic + // invalid_argument code too, so reason is what tells it apart. The three + // extension members it alone carries are read straight off the problem — + // stripped like every other server-controlled field — rather than folded + // into the generic ProblemError, because this refusal is a statement about + // the SERVER's wire shape, not about the request's arguments. + if e.Reason == ReasonWireRevisionUnsupported { + e.Err = &WireRevisionUnsupportedError{ + ServerURL: t.serverURL, + BdVersion: stripControlRunes(deref(p.BdVersion)), + ClientWireRevision: ClientWireRevision, + MinClientWireRevision: deref(p.MinWireRevision), + ServerWireRevision: deref(p.WireRevision), + } + return e + } + + e.Err = sentinelFor(e, t) + return e +} + +// decodeRevisionToken reads a revision-bearing problem member that may be +// encoded either as the decimal string every server since upstream #6053 +// uses (types.RevisionToken) or as the bare JSON integer a server old enough +// to omit ContextResponse.wire_revision entirely still sends (see +// ClientMinWireRevision's doc: a decoded 0 means the server omitted the +// member, and 0 is exactly the pre-#6053 integer-token generation). Both +// shapes name the same opaque token — this client never parses either one +// back to int64 (ProblemError.ExpectedVersion's doc) — so tolerating the +// older shape here is only about surviving the decode, never about deriving a +// number from it. +func decodeRevisionToken(raw json.RawMessage) (string, bool) { + if len(raw) == 0 || string(raw) == "null" { + return "", false + } + var s string + if err := json.Unmarshal(raw, &s); err == nil { + return s, true + } + var n json.Number + if err := json.Unmarshal(raw, &n); err == nil { + return n.String(), true + } + return "", false +} + +// revisionNeedsFallback reports whether a *string revision field still needs +// legacyRevisionFields' integer-tolerant recovery. A genuinely absent member +// decodes to nil, as expected — but encoding/json's indirect() allocates a +// pointer to the zero value ("") for a *string field BEFORE it discovers the +// JSON value's type doesn't match, when the member IS present with the wrong +// shape (a bare integer). That pre-allocation means a type-mismatched field +// comes out of the primary json.Unmarshal(body, &p) as a non-nil pointer to +// "", not nil — so checking only for nil here would never recover exactly the +// one case this fallback exists for. No legitimate server response uses a +// literal empty-string revision token (ProblemError.ExpectedVersion's doc: +// both are opaque, server-defined, non-numeric tokens an operation always +// names when it fires at all), so treating "" the same as nil costs nothing. +func revisionNeedsFallback(p *string) bool { + return p == nil || *p == "" +} + +// legacyRevisionFields backfills expected_version/actual_version when the +// primary decode above left them needing fallback (see revisionNeedsFallback). +// That happens exactly when a pre-#6053 server sent one as a bare JSON +// integer rather than the decimal string every server since has used: +// json.Unmarshal(body, &p) already tolerates the mismatch (a bad field does +// not abort decoding the rest, and mapProblem deliberately discards that +// error), so the only member actually lost is the one with the wrong shape — +// and that is exactly what this recovers, from the same bytes, by parsing the +// two revision keys alone and accepting either shape. +func legacyRevisionFields(body []byte, e *ProblemError) { + if !revisionNeedsFallback(e.ExpectedVersion) && !revisionNeedsFallback(e.ActualVersion) { + return + } + var raw struct { + ExpectedVersion json.RawMessage `json:"expected_version"` + ActualVersion json.RawMessage `json:"actual_version"` + } + if json.Unmarshal(body, &raw) != nil { + return + } + if revisionNeedsFallback(e.ExpectedVersion) { + if v, ok := decodeRevisionToken(raw.ExpectedVersion); ok { + v = stripControlRunes(v) + e.ExpectedVersion = &v + } + } + if revisionNeedsFallback(e.ActualVersion) { + if v, ok := decodeRevisionToken(raw.ActualVersion); ok { + v = stripControlRunes(v) + e.ActualVersion = &v + } + } +} + +// codeSentinel is the whole problem-code vocabulary this client knows, and the +// canonical error each code becomes. +// +// It is a table rather than a switch so the vocabulary is ENUMERABLE: +// TestTheCodeTableIsSetEqualWithTheDocumentedVocabulary walks it against the +// `x-bd-codes` rows of the shipped OpenAPI document, in both directions, which +// a switch statement could not be held to. +var codeSentinel = map[string]func(*ProblemError, target) error{ + "invalid_argument": func(*ProblemError, target) error { return issueops.ErrValidation }, + "invalid_cursor": func(*ProblemError, target) error { return ErrInvalidCursor }, + "unauthenticated": func(*ProblemError, target) error { return ErrUnauthenticated }, + "not_found": func(*ProblemError, target) error { return issueops.ErrNotFound }, + "already_exists": func(*ProblemError, target) error { return issueops.ErrAlreadyExists }, + "busy": func(*ProblemError, target) error { return ErrBusy }, + "db_unavailable": func(*ProblemError, target) error { return ErrDBUnavailable }, + "internal": func(*ProblemError, target) error { return ErrServerFault }, + + // The journal codes, on the table for the reason stated beside their + // sentinels: set-equality with the document, not with what this client + // reaches today. + "events_journal_disabled": func(*ProblemError, target) error { return ErrEventsJournalDisabled }, + "events_journal_truncated": func(*ProblemError, target) error { return ErrEventsJournalTruncated }, + "events_watch_saturated": func(*ProblemError, target) error { return ErrEventsWatchSaturated }, + + // `param` names WHICH guard missed, in the same spelling a 400 on the same + // operation would use, so the client answers with the issueops sentinel the + // embedded store returns for that miss and a caller classifies both + // backends with one errors.Is arm. An unrecognized (or absent) param takes + // the generic sentinel rather than guessing one of the three. + // + // The MEMBER is read off the end of the param rather than compared whole, + // because a batch operation qualifies it by the item that carried the + // guard: `items[1].update.expected_version` is the same member as + // `expected_version` and means the same miss. A whole-string comparison + // answered the generic sentinel for every guarded item in a plan, which is + // a caller told "a precondition failed" where a local backend tells it + // WHICH — see paramMember. + "precondition_failed": func(e *ProblemError, _ target) error { + switch paramMember(e.Param) { + case "expected_version": + return issueops.ErrVersionMismatch + case "expected_status": + return issueops.ErrStatusMismatch + case "expected_assignee": + return issueops.ErrAssigneeMismatch + default: + return ErrPreconditionFailed + } + }, + + "already_claimed": func(e *ProblemError, t target) error { + return claimConflict(e, t, issueops.ErrAlreadyClaimed) + }, + "not_claimable": func(e *ProblemError, t target) error { + return claimConflict(e, t, issueops.ErrNotClaimable) + }, + + // Member PRESENCE is the discriminator the server documents: the + // open-children refusal carries the count, the live-blocker one carries + // nothing. Reading `detail` to tell them apart is exactly what the extension + // member exists to prevent. + "not_closable": func(e *ProblemError, t target) error { + if e.OpenChildren != nil { + return &issueops.CloseOpenChildrenError{IssueID: refusedIssueID(e, t), OpenChildren: *e.OpenChildren} + } + return issueops.ErrCloseBlocked + }, + + // not_releasable is the RELEASE's refusal, and it is REACHED: httpReleaser + // dials issues:release (releaser.go, client wave ga-f352s) and nine of the + // eleven Releaser contracts run through this mapping on the served tier. + // + // It was on this table BEFORE it was reachable, for the journal codes' + // reason — set-equality with the document rather than with what this client + // happens to dial — and that is worth keeping now that the wait is over: a + // code the document publishes and this table omitted would take the 4xx + // default branch and be reported as a client bug on the day an accessor + // started earning it. + // + // The role splits the refusal in two where the wire does not: ErrNotClaimed + // for a row holding no claim, ErrNotReleasable for a status that will not + // accept one. One code covers both by the server's own deliberate choice + // (see httpapi's CodeNotReleasable), and it carries no member that tells + // them apart, so this maps to the STATUS sentinel — the wider of the two, + // and the one whose message does not assert a fact the wire never sent. + "not_releasable": func(*ProblemError, target) error { return issueops.ErrNotReleasable }, + + // [Added: OSS publishes notes_overwrite_refused (internal/httpapi/problem.go + // CodeNotesOverwrite, status 409) for an update whose Patch.Notes would + // replace existing notes without an explicit overwrite flag. This code had + // no entry at all, so a server sending it fell through to the 4xx default + // and reported as an undifferentiated client bug instead of the typed + // sentinel callers already switch on locally.] + "notes_overwrite_refused": func(*ProblemError, target) error { return issueops.ErrNotesOverwrite }, + + // The same rule again: `issue_id` present means the edge named the issue's + // own ancestor or descendant, absent means a plain scheduling cycle. The + // three hierarchy members travel together and rebuild the typed error whole + // — including BlockerIsAncestor's false polarity, which is why the wire + // sends the boolean rather than omitting it. + "dependency_cycle": func(e *ProblemError, _ target) error { + if e.IssueID != nil { + return &issueops.DependencyHierarchyConflictError{ + IssueID: *e.IssueID, + BlockerID: deref(e.BlockerID), + BlockerIsAncestor: deref(e.BlockerIsAncestor), + } + } + return issueops.ErrDependencyCycle + }, + + // The endpoints are not on the wire — the request already said them — so + // they come from the caller and the typed error comes out whole. A batch add + // that refused on one of many edges leaves them empty, because the wire does + // not say WHICH edge collided. + "dependency_exists": func(e *ProblemError, t target) error { + return &issueops.DependencyTypeConflictError{ + IssueID: t.issueID, + DependsOnID: t.dependsOnID, + ExistingType: deref(e.ExistingType), + RequestedType: deref(e.RequestedType), + } + }, +} + +// Codes lists the problem codes this client maps, sorted. Anything outside it +// takes the status-class default branch. +func Codes() []string { + out := make([]string, 0, len(codeSentinel)) + for code := range codeSentinel { + out = append(out, code) + } + slices.Sort(out) + return out +} + +func sentinelFor(e *ProblemError, t target) error { + if row, ok := codeSentinel[e.Code]; ok { + return row(e, t) + } + + // The default branch. Adding a code is not a breaking change, so a client + // that hard-failed on an unknown one would break on every server newer than + // itself; falling back to the status class is what makes the vocabulary + // additive. + switch { + case e.Status == http.StatusUnauthorized: + // A 401 is authentication whether or not the answer carried a problem + // document, and it must be classified BEFORE the 4xx default. bd serve's + // own 401 arrives with a code and never reaches here; what does is a 401 + // from something in FRONT of it — a gateway or a proxy edge rejecting an + // expired credential before the request ever reaches bd — which answers + // with its own html or nothing at all. Falling through to ErrBadRequest + // told the caller its REQUEST was malformed, which sends an operator + // looking at flags for a credential to rotate. + return ErrUnauthenticated + case e.Status == http.StatusServiceUnavailable: + return ErrBusy + case e.Status >= 500: + return ErrServerFault + case e.Status >= 400: + return ErrBadRequest + default: + // A 1xx or 3xx reaching here is not a problem document at all. 3xx is + // refused before this point (redirects are not followed), so this is the + // unreachable arm — it fails as a server fault rather than as success. + return ErrServerFault + } +} + +// claimConflict rebuilds *issueops.ClaimConflictError from the two extension +// members the refusing transaction read. The wrapped sentinel is what +// errors.Is matches, so a caller that only wants "someone else has it" needs no +// errors.As at all. +func claimConflict(e *ProblemError, t target, sentinel error) error { + return &issueops.ClaimConflictError{ + IssueID: refusedIssueID(e, t), + Assignee: deref(e.Assignee), + Status: issueops.Status(deref(e.IssueStatus)), + Err: sentinel, + } +} + +// refusedIssueID names the row a reconstructed conflict is about. +// +// The REQUEST is the first source and stays the first source: the conflict +// members the server leaves out are the ones the request already said, which is +// what target exists for. But a BATCH names as many rows as it has items, so +// there is no single request id to supply — and on that operation the server +// publishes the one it acted on as `item_issue_id`, read inside the refusing +// transaction. Without this fallback every conflict rebuilt from a plan named +// the empty string, which reads as "the server did not say" when the server +// said it plainly. +func refusedIssueID(e *ProblemError, t target) string { + if t.issueID != "" { + return t.issueID + } + return deref(e.ItemIssueID) +} + +// paramMember reads the offending MEMBER off a problem's `param`. +// +// A single-resource operation spells it bare (`expected_version`); a batch +// qualifies it by the item that carried it (`items[1].update.expected_version`) +// so a client can find the offender in a request it composed. The member is the +// last dotted segment either way, and reading it is what lets one code table +// serve both spellings. +func paramMember(param string) string { + if i := strings.LastIndex(param, "."); i >= 0 { + return param[i+1:] + } + return param +} + +// retryAfter reads the header RFC 9110 defines in two spellings and bounds it. +// +// The bound is not politeness: the header is server-controlled input, and an +// unbounded honor is a server (or anything that can answer as one) parking the +// caller's process for as long as it likes. A value past the bound is clamped +// rather than dropped, because the server still meant "not immediately". +// +// Honoring it means bounding it and handing it to the caller — this layer never +// sleeps and never resends. Half of this surface is non-idempotent custom-method +// POSTs (claim, close, sweep, delete, the dependency writes), and a transport +// that slept and resent one of those on a 503 would double-apply a write whose +// first attempt may well have committed before the server ran out of slots. +// Which 503s are safe to come back to is the dispatch layer's question, and it +// is the layer that knows the answer. +func retryAfter(header http.Header, max time.Duration) time.Duration { + raw := strings.TrimSpace(header.Get("Retry-After")) + if raw == "" { + return 0 + } + var d time.Duration + if secs, err := strconv.Atoi(raw); err == nil { + d = time.Duration(secs) * time.Second + } else if at, err := http.ParseTime(raw); err == nil { + d = time.Until(at) + } else { + return 0 + } + if d < 0 { + return 0 + } + if max > 0 && d > max { + return max + } + return d +} + +func deref[T any](p *T) T { + if p == nil { + var zero T + return zero + } + return *p +} + +// stripControlRunes removes every control rune from a server-controlled problem +// field: category Cc — the C0 block, DEL and the C1 block, where ESC 0x1B and CSI +// 0x9B live — plus the U+2028/U+2029 line and paragraph separators. It mirrors the +// server's own actor rule (httpapi's isControlChar) and, unlike the CLI's +// display-layer strip, keeps nothing back: a problem field is a single value, so +// tab and newline in one are as much an injection as an escape introducer. This +// is the source-of-truth layer — it makes a decoded *ProblemError safe in EVERY +// field before it reaches any of the many stderr sinks that render it via %v. +func stripControlRunes(s string) string { + if !strings.ContainsFunc(s, isControlRune) { + return s + } + return strings.Map(func(r rune) rune { + if isControlRune(r) { + return -1 + } + return r + }, s) +} + +// stripControlRunesPtr strips a pointer member in place-safe fashion, preserving +// nil. Presence is load-bearing on three of the extension members (an explicit +// value versus an absent one discriminates two refusals), so a cleaned value is +// returned through a fresh pointer and an absent one stays absent. +func stripControlRunesPtr(p *string) *string { + if p == nil { + return nil + } + s := stripControlRunes(*p) + return &s +} + +func isControlRune(r rune) bool { + return unicode.IsControl(r) || r == '\u2028' || r == '\u2029' +} diff --git a/internal/httpclient/wire/problem_test.go b/internal/httpclient/wire/problem_test.go new file mode 100644 index 000000000..cf22b0009 --- /dev/null +++ b/internal/httpclient/wire/problem_test.go @@ -0,0 +1,789 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/problem_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "errors" + "fmt" + "io" + "net/http" + "strings" + "testing" + "time" + + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/issueops" +) + +// refuseWith answers every request with one canned problem document and returns +// the error the client made of it. +func refuseWith(t *testing.T, status int, body string, headers map[string]string, r Request, opts ...func(*Options)) error { + t.Helper() + o := Options{} + for _, fn := range opts { + fn(&o) + } + c, _ := newTestClient(t, o, nil, func(w http.ResponseWriter, _ *http.Request) { + for k, v := range headers { + w.Header().Set(k, v) + } + problemJSON(w, status, body) + }) + return c.Do(ctx(t), r, &struct{}{}) +} + +func listIssues() Request { + return Request{Op: OpListIssues, Method: http.MethodGet, Path: PathIssues} +} + +// TestEveryProblemCodeMapsToItsSentinel walks the whole frozen v0 vocabulary at +// tip — the eleven upstream codes plus the enterprise tree's `unauthenticated` +// — with each code on the status the server freezes it to. +func TestEveryProblemCodeMapsToItsSentinel(t *testing.T) { + cases := []struct { + code string + status int + body string + want error + }{ + {"invalid_argument", 400, `{"status":400,"code":"invalid_argument","detail":"unknown parameter","param":"sort","reason":"unknown_parameter","request_id":"r1"}`, issueops.ErrValidation}, + {"invalid_cursor", 400, `{"status":400,"code":"invalid_cursor","detail":"restart paging","request_id":"r2"}`, ErrInvalidCursor}, + {"unauthenticated", 401, `{"status":401,"code":"unauthenticated","detail":"missing or invalid bearer token","request_id":"r3"}`, ErrUnauthenticated}, + {"not_found", 404, `{"status":404,"code":"not_found","detail":"no issue or wisp with that id","request_id":"r4"}`, issueops.ErrNotFound}, + {"already_claimed", 409, `{"status":409,"code":"already_claimed","assignee":"other","issue_status":"in_progress","request_id":"r5"}`, issueops.ErrAlreadyClaimed}, + {"not_claimable", 409, `{"status":409,"code":"not_claimable","issue_status":"closed","request_id":"r6"}`, issueops.ErrNotClaimable}, + {"not_closable (open children)", 409, `{"status":409,"code":"not_closable","open_children":3,"request_id":"r7"}`, issueops.ErrCloseOpenChildren}, + {"not_closable (blocked)", 409, `{"status":409,"code":"not_closable","request_id":"r8"}`, issueops.ErrCloseBlocked}, + {"dependency_cycle (scheduling)", 409, `{"status":409,"code":"dependency_cycle","request_id":"r9"}`, issueops.ErrDependencyCycle}, + {"dependency_exists", 409, `{"status":409,"code":"dependency_exists","existing_type":"blocks","requested_type":"related","request_id":"r10"}`, nil}, + {"busy", 503, `{"status":503,"code":"busy","detail":"the server is busy; retry shortly","request_id":"r11"}`, ErrBusy}, + {"db_unavailable", 503, `{"status":503,"code":"db_unavailable","detail":"database temporarily unavailable; retry","request_id":"r12"}`, ErrDBUnavailable}, + {"internal", 500, `{"status":500,"code":"internal","detail":"internal server error","request_id":"r13"}`, ErrServerFault}, + } + for _, tc := range cases { + t.Run(tc.code, func(t *testing.T) { + err := refuseWith(t, tc.status, tc.body, nil, listIssues()) + + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T (%v), want *ProblemError", err, err) + } + if problem.Status != tc.status { + t.Errorf("Status = %d, want %d", problem.Status, tc.status) + } + if problem.RequestID == "" { + t.Error("RequestId did not survive the decode") + } + if tc.want != nil && !errors.Is(err, tc.want) { + t.Errorf("err does not match %v: %v", tc.want, err) + } + // The dependency_exists row has no plain sentinel: it is a typed + // error whose members ARE the refusal. + if tc.code == "dependency_exists" { + var conflict *issueops.DependencyTypeConflictError + if !errors.As(err, &conflict) { + t.Fatalf("err is %T, want *issueops.DependencyTypeConflictError", err) + } + } + }) + } +} + +func TestClaimConflictsReconstructFromTheirExtensionMembers(t *testing.T) { + // The holder and the status are read inside the transaction that lost the + // compare-and-set; the client rebuilds the typed error from them instead of + // parsing the refusal's prose. + cases := []struct { + name string + body string + sentinel error + assignee string + status types.Status + }{ + { + name: "already claimed", + body: `{"status":409,"code":"already_claimed","assignee":"agent-7","issue_status":"in_progress"}`, + sentinel: issueops.ErrAlreadyClaimed, + assignee: "agent-7", + status: types.StatusInProgress, + }, + { + // Empty assignee is the documented shape when the refusal was about + // the status rather than a foreign holder. + name: "not claimable", + body: `{"status":409,"code":"not_claimable","issue_status":"closed"}`, + sentinel: issueops.ErrNotClaimable, + assignee: "", + status: types.StatusClosed, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + err := refuseWith(t, 409, tc.body, nil, Request{ + Op: OpClaimIssue, Method: http.MethodPost, + Path: "/v0/beads/issues/ga-1:claim", IssueID: "ga-1", + }) + + var conflict *issueops.ClaimConflictError + if !errors.As(err, &conflict) { + t.Fatalf("err is %T (%v), want *issueops.ClaimConflictError", err, err) + } + // The id is not on the wire — the request already said it — so the + // client supplies it and the sentinel comes out whole. + if conflict.IssueID != "ga-1" { + t.Errorf("IssueID = %q, want ga-1", conflict.IssueID) + } + if conflict.Assignee != tc.assignee { + t.Errorf("Assignee = %q, want %q", conflict.Assignee, tc.assignee) + } + if conflict.Status != tc.status { + t.Errorf("Status = %q, want %q", conflict.Status, tc.status) + } + if !errors.Is(err, tc.sentinel) { + t.Errorf("the wrapped sentinel does not match %v", tc.sentinel) + } + }) + } +} + +func TestNotClosableUsesOpenChildrenPresenceAsTheDiscriminator(t *testing.T) { + // One code, two refusals. Member PRESENCE tells them apart; `detail` is + // never read. + t.Run("present means open children", func(t *testing.T) { + err := refuseWith(t, 409, `{"status":409,"code":"not_closable","open_children":4}`, nil, Request{ + Op: OpCloseIssue, Method: http.MethodPost, + Path: "/v0/beads/issues/ga-1:close", IssueID: "ga-1", + }) + var openChildren *issueops.CloseOpenChildrenError + if !errors.As(err, &openChildren) { + t.Fatalf("err is %T (%v), want *issueops.CloseOpenChildrenError", err, err) + } + if openChildren.OpenChildren != 4 || openChildren.IssueID != "ga-1" { + t.Errorf("reconstructed %+v", openChildren) + } + if !errors.Is(err, issueops.ErrCloseOpenChildren) { + t.Error("the wrapped sentinel does not match ErrCloseOpenChildren") + } + }) + + t.Run("absent means a live blocker", func(t *testing.T) { + err := refuseWith(t, 409, `{"status":409,"code":"not_closable","detail":"issue is blocked"}`, nil, Request{ + Op: OpCloseIssue, Method: http.MethodPost, + Path: "/v0/beads/issues/ga-1:close", IssueID: "ga-1", + }) + if !errors.Is(err, issueops.ErrCloseBlocked) { + t.Fatalf("err = %v, want ErrCloseBlocked", err) + } + var openChildren *issueops.CloseOpenChildrenError + if errors.As(err, &openChildren) { + t.Error("a live-blocker refusal classified as open children") + } + }) + + t.Run("zero is present, not absent", func(t *testing.T) { + // The pointer is what carries presence: a count of zero must not read + // as the other refusal. + err := refuseWith(t, 409, `{"status":409,"code":"not_closable","open_children":0}`, nil, Request{ + Op: OpCloseIssue, Method: http.MethodPost, Path: "/v0/beads/issues/ga-1:close", IssueID: "ga-1", + }) + if !errors.Is(err, issueops.ErrCloseOpenChildren) { + t.Fatalf("err = %v, want ErrCloseOpenChildren", err) + } + }) +} + +func TestDependencyCycleUsesIssueIDPresenceAsTheDiscriminator(t *testing.T) { + // The hierarchy refusal and the scheduling cycle share one code because they + // share one recovery. The typed distinction rides on the extension members. + t.Run("absent means a plain scheduling cycle", func(t *testing.T) { + err := refuseWith(t, 409, `{"status":409,"code":"dependency_cycle","detail":"would create a cycle"}`, nil, Request{ + Op: OpAddDependencies, Method: http.MethodPost, Path: PathDependenciesAdd, + }) + if !errors.Is(err, issueops.ErrDependencyCycle) { + t.Fatalf("err = %v, want ErrDependencyCycle", err) + } + var hierarchy *issueops.DependencyHierarchyConflictError + if errors.As(err, &hierarchy) { + t.Error("a scheduling cycle classified as a hierarchy conflict") + } + }) + + // Both polarities: the boolean is emitted when false, so absence never + // means false and the reconstruction has to prove it in both directions. + for _, ancestor := range []bool{true, false} { + t.Run("hierarchy conflict, blocker_is_ancestor="+boolText(ancestor), func(t *testing.T) { + body := `{"status":409,"code":"dependency_cycle","issue_id":"ga-child","blocker_id":"ga-parent","blocker_is_ancestor":` + boolText(ancestor) + `}` + err := refuseWith(t, 409, body, nil, Request{ + Op: OpAddDependencies, Method: http.MethodPost, Path: PathDependenciesAdd, + }) + var hierarchy *issueops.DependencyHierarchyConflictError + if !errors.As(err, &hierarchy) { + t.Fatalf("err is %T (%v), want *issueops.DependencyHierarchyConflictError", err, err) + } + want := &issueops.DependencyHierarchyConflictError{ + IssueID: "ga-child", BlockerID: "ga-parent", BlockerIsAncestor: ancestor, + } + if *hierarchy != *want { + t.Errorf("reconstructed %+v, want %+v", hierarchy, want) + } + // The message is what `bd dep add` prints, and the two polarities + // say opposite things. + if hierarchy.Error() != want.Error() { + t.Errorf("message = %q, want %q", hierarchy.Error(), want.Error()) + } + }) + } +} + +func TestDependencyExistsCarriesBothEdgeTypes(t *testing.T) { + err := refuseWith(t, 409, `{"status":409,"code":"dependency_exists","existing_type":"blocks","requested_type":"related"}`, nil, Request{ + Op: OpAddDependencies, Method: http.MethodPost, Path: PathDependenciesAdd, + IssueID: "ga-1", DependsOnID: "ga-2", + }) + var conflict *issueops.DependencyTypeConflictError + if !errors.As(err, &conflict) { + t.Fatalf("err is %T (%v), want *issueops.DependencyTypeConflictError", err, err) + } + want := &issueops.DependencyTypeConflictError{ + IssueID: "ga-1", DependsOnID: "ga-2", ExistingType: "blocks", RequestedType: "related", + } + if *conflict != *want { + t.Errorf("reconstructed %+v, want %+v", conflict, want) + } +} + +func TestUnknownCodesFallBackToTheStatusClass(t *testing.T) { + // Adding a code is not a breaking change, so a client that hard-failed on an + // unknown one would break against every server newer than itself. + cases := []struct { + name string + status int + body string + want error + retryable bool + }{ + {"unknown 400", 400, `{"status":400,"code":"quota_exhausted"}`, ErrBadRequest, false}, + {"unknown 409", 409, `{"status":409,"code":"lease_conflict"}`, ErrBadRequest, false}, + {"unknown 429", 429, `{"status":429,"code":"too_many_requests"}`, ErrBadRequest, false}, + {"unknown 503", 503, `{"status":503,"code":"draining"}`, ErrBusy, true}, + {"unknown 500", 500, `{"status":500,"code":"panicked"}`, ErrServerFault, false}, + {"unknown 502 with no code at all", 502, `bad gateway`, ErrServerFault, false}, + {"a 504 from a proxy that is not a problem document", 504, ``, ErrServerFault, false}, + // A 401 is authentication whichever layer answered it. bd serve's own + // carries a code; these two are what an edge in FRONT of it returns when + // it rejects a credential before the request arrives — and the 4xx + // default used to call both of them a bad request, sending an operator + // to look at flags for a token to rotate. + {"401 with no code at all", 401, `401 Unauthorized`, ErrUnauthenticated, false}, + {"401 from an edge with no body", 401, ``, ErrUnauthenticated, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + err := refuseWith(t, tc.status, tc.body, nil, listIssues()) + if !errors.Is(err, tc.want) { + t.Fatalf("err = %v, want %v", err, tc.want) + } + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if problem.Retryable() != tc.retryable { + t.Errorf("Retryable() = %v, want %v", problem.Retryable(), tc.retryable) + } + }) + } +} + +func TestCodeIsTheOnlyDispatchKey(t *testing.T) { + // A code carries one frozen status, so reading the status instead would be a + // second, weaker copy of the table. A code arriving on the wrong status still + // classifies by the code. + err := refuseWith(t, http.StatusInternalServerError, `{"status":500,"code":"not_found"}`, nil, listIssues()) + if !errors.Is(err, issueops.ErrNotFound) { + t.Fatalf("err = %v, want ErrNotFound", err) + } + if errors.Is(err, ErrServerFault) { + t.Error("the status class overrode a code this client knows") + } +} + +func TestRequestIDIsSurfacedOn5xx(t *testing.T) { + // The 5xx detail is a fixed string per code by design, so the correlation id + // is the client's only handle on the log line that has the real error. + err := refuseWith(t, 500, `{"status":500,"code":"internal","detail":"internal server error","request_id":"01JABCDEF"}`, nil, listIssues()) + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if problem.RequestID != "01JABCDEF" { + t.Errorf("RequestID = %q", problem.RequestID) + } + if got := problem.Error(); !strings.Contains(got, "01JABCDEF") { + t.Errorf("Error() = %q, want the request_id in it", got) + } + + // A 4xx's detail already reflects the caller's own input, so the id is + // carried but does not clutter the sentence. + err = refuseWith(t, 404, `{"status":404,"code":"not_found","detail":"no issue or wisp with that id","request_id":"01JXYZ"}`, nil, listIssues()) + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if problem.RequestID != "01JXYZ" { + t.Errorf("RequestID = %q", problem.RequestID) + } + if strings.Contains(problem.Error(), "01JXYZ") { + t.Errorf("Error() = %q, want the 4xx sentence without the request_id", problem.Error()) + } +} + +func TestRetryAfterIsParsedAndBounded(t *testing.T) { + cases := []struct { + name string + header string + max time.Duration + want time.Duration + }{ + {"delta seconds", "5", 30 * time.Second, 5 * time.Second}, + {"the saturation value", "1", 30 * time.Second, time.Second}, + {"absent", "", 30 * time.Second, 0}, + {"garbage", "soon", 30 * time.Second, 0}, + {"negative", "-5", 30 * time.Second, 0}, + // Server-controlled input: an unbounded honor is a server parking the + // caller's process for as long as it likes. + {"past the bound is clamped, not dropped", "3600", 30 * time.Second, 30 * time.Second}, + {"a date in the past", "Mon, 02 Jan 2006 15:04:05 GMT", 30 * time.Second, 0}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + headers := map[string]string{} + if tc.header != "" { + headers["Retry-After"] = tc.header + } + err := refuseWith(t, 503, `{"status":503,"code":"busy"}`, headers, listIssues(), + func(o *Options) { o.MaxRetryAfter = tc.max }) + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if problem.RetryAfter != tc.want { + t.Errorf("RetryAfter = %v, want %v", problem.RetryAfter, tc.want) + } + if !problem.Retryable() { + t.Error("a 503 did not report as retryable") + } + }) + } +} + +func TestARetryAfterDateInTheFutureIsHonoredAndBounded(t *testing.T) { + future := time.Now().Add(10 * time.Second).UTC().Format(http.TimeFormat) + err := refuseWith(t, 503, `{"status":503,"code":"db_unavailable"}`, + map[string]string{"Retry-After": future}, listIssues()) + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + // Second-granularity formatting plus the round trip make an exact + // comparison meaningless; the bound and the sign are the contract. + if problem.RetryAfter <= 0 || problem.RetryAfter > DefaultMaxRetryAfter { + t.Errorf("RetryAfter = %v, want a positive value at or under %v", problem.RetryAfter, DefaultMaxRetryAfter) + } +} + +func TestParamAndReasonSurviveForTheSkewTaxonomy(t *testing.T) { + // The version-skew signal: a newer CLI flag against an older server. The + // refusal taxonomy maps `param` back to the flag that produced it, so both + // members have to arrive typed rather than as prose. + err := refuseWith(t, 400, + `{"status":400,"code":"invalid_argument","param":"sort","reason":"unknown_parameter","detail":"unknown parameter \"sort\""}`, + nil, listIssues()) + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if problem.Param != "sort" || problem.Reason != "unknown_parameter" { + t.Errorf("param/reason = %q/%q", problem.Param, problem.Reason) + } + if !errors.Is(err, issueops.ErrValidation) { + t.Error("invalid_argument did not map to ErrValidation") + } +} + +// TestPreconditionFailuresCarryBothSidesOfTheGuard is the decode half of the +// compare-and-set wave: a 409 precondition_failed says WHICH guard missed in +// `param` and — where the refusing operation can report it — what the request +// asked for and what the row was found holding. +// +// Both halves have to survive the decode. `param` alone tells a caller which +// member to recompose; the expected/actual pair is what lets it recompose the +// member WITHOUT a second read, and dropping it would leave "re-read the row and +// try again" as the only recovery on a surface whose refusal already carried the +// answer. +// +// THE VERSIONS ARE DECIMAL STRINGS ON THE WIRE AND ARE CARRIED AS SUCH. Live +// tokens run past 5e17, where an IEEE-754 double's ulp is already 64, which is +// why upstream #6053 spells every revision token as a string +// (types.RevisionToken): a JSON number would hand a lossy consumer a value NEAR +// the token that is not it, and the corruption would show up as a +// precondition_failed on the NEXT request. The case drives a token in that +// range and pins that the strings come through verbatim — the ProblemError does +// not parse them back, because they are an echo and a diagnostic, not a value +// to compose the next guard from (see the field comment). +func TestPreconditionFailuresCarryBothSidesOfTheGuard(t *testing.T) { + const expected = int64(576460752303423487) // 2^59 - 1: a float64 cannot hold it + const actual = int64(576460752303423489) + + t.Run("version", func(t *testing.T) { + body := fmt.Sprintf(`{"status":409,"code":"precondition_failed","param":"expected_version",`+ + `"expected_version":%q,"actual_version":%q}`, types.RevisionToken(expected), types.RevisionToken(actual)) + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if !errors.Is(err, issueops.ErrVersionMismatch) { + t.Errorf("param expected_version did not map to ErrVersionMismatch: %v", err) + } + if p.ExpectedVersion == nil || *p.ExpectedVersion != types.RevisionToken(expected) { + t.Errorf("ExpectedVersion = %s, want %q verbatim", renderVersion(p.ExpectedVersion), types.RevisionToken(expected)) + } + if p.ActualVersion == nil || *p.ActualVersion != types.RevisionToken(actual) { + t.Errorf("ActualVersion = %s, want %q verbatim", renderVersion(p.ActualVersion), types.RevisionToken(actual)) + } + }) + + t.Run("status and assignee", func(t *testing.T) { + body := `{"status":409,"code":"precondition_failed","param":"expected_assignee",` + + `"expected_assignee":"","actual_assignee":"holder",` + + `"expected_status":"open","actual_status":"in_progress"}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if !errors.Is(err, issueops.ErrAssigneeMismatch) { + t.Errorf("param expected_assignee did not map to ErrAssigneeMismatch: %v", err) + } + // The EMPTY expected assignee is the guard that says "only if nobody + // holds it", so its presence is load-bearing: a decode that collapsed it + // into absence would report a refusal the request never made. + if p.ExpectedAssignee == nil { + t.Error("ExpectedAssignee is absent; the empty string is a real guard and the server echoed it") + } else if *p.ExpectedAssignee != "" { + t.Errorf("ExpectedAssignee = %q, want the empty guard", *p.ExpectedAssignee) + } + for member, got := range map[string]*string{ + "actual_assignee": p.ActualAssignee, + "expected_status": p.ExpectedStatus, + "actual_status": p.ActualStatus, + } { + if got == nil { + t.Errorf("%s was dropped by the decode", member) + } + } + }) + + t.Run("an operation that cannot report what it found says so by absence", func(t *testing.T) { + // `actual_version` is present only where the refusing operation can + // report it: an all-or-nothing operation rolls its transaction back, so + // a value read afterwards would describe a row the refusal never saw. + // Absence means "this server cannot tell you", never "it found zero". + body := `{"status":409,"code":"precondition_failed","param":"expected_version","expected_version":"0"}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if p.ActualVersion != nil { + t.Errorf("ActualVersion = %q for a refusal that reported none; absent is not zero", *p.ActualVersion) + } + if p.ExpectedVersion == nil { + t.Fatal("ExpectedVersion is absent; \"0\" is a legal token and the server echoed it") + } + if *p.ExpectedVersion != "0" { + t.Errorf("ExpectedVersion = %q, want the echoed \"0\"", *p.ExpectedVersion) + } + }) + + t.Run("the strings are stripped like every other server-controlled field", func(t *testing.T) { + body := `{"status":409,"code":"precondition_failed","param":"expected_status",` + + `"expected_status":"open\u009b31m","actual_status":"done\u001b]0;x\u0007",` + + `"expected_assignee":"a\u0000","actual_assignee":"b\u2028"}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + for name, got := range map[string]*string{ + "ExpectedStatus": p.ExpectedStatus, "ActualStatus": p.ActualStatus, + "ExpectedAssignee": p.ExpectedAssignee, "ActualAssignee": p.ActualAssignee, + } { + if got == nil { + t.Errorf("%s was dropped by the decode", name) + continue + } + if strings.ContainsFunc(*got, isControlRune) { + t.Errorf("%s still carries a control rune: %q", name, *got) + } + } + }) +} + +// renderVersion prints a row-version guard THROUGH the pointer, so a failure +// message shows the token rather than the address of one — which is the +// difference between reading a corrupted value and reading a heap pointer. +func renderVersion(v *string) string { + if v == nil { + return "absent" + } + return fmt.Sprintf("%q", *v) +} + +// TestProblemDecodeStripsControlCharactersFromEveryField is the source-of-truth +// layer of the two-layer terminal-injection defense. A *ProblemError must leave +// the wire safe in EVERY server-controlled field — the direct ones AND the +// extension members the typed conflicts are reconstructed from — because many +// stderr sinks render it via %v with no display-layer strip (bd close/show/reopen/ +// update write each per-id failure straight to os.Stderr). The earlier per-field +// strip covered only detail/title/param/reason; these cases pin code, request_id +// and the reconstructed conflict's issue ids too. +func TestProblemDecodeStripsControlCharactersFromEveryField(t *testing.T) { + t.Run("direct fields including code and request_id", func(t *testing.T) { + body := `{"status":500,"code":"internal\u009b31m","title":"t\u009b","detail":"boom\u001b]0;x\u0007","param":"sort\u0000","reason":"r\u2028x","request_id":"req-\u009b1"}` + err := refuseWith(t, 500, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + for name, got := range map[string]string{ + "Code": p.Code, "Title": p.Title, "Detail": p.Detail, + "Param": p.Param, "Reason": p.Reason, "RequestID": p.RequestID, + } { + if strings.ContainsFunc(got, isControlRune) { + t.Errorf("%s still carries a control rune: %q", name, got) + } + } + // The whole rendered error is what a %v sink prints; it must be clean. + if strings.ContainsFunc(err.Error(), isControlRune) { + t.Errorf("ProblemError.Error() carries a control rune: %q", err.Error()) + } + }) + + t.Run("reconstructed dependency-cycle issue ids", func(t *testing.T) { + body := `{"status":409,"code":"dependency_cycle","issue_id":"bd-1\u009b31m","blocker_id":"bd-2\u001b]0;x\u0007","blocker_is_ancestor":true}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var hc *issueops.DependencyHierarchyConflictError + if !errors.As(err, &hc) { + t.Fatalf("err is %T, want *DependencyHierarchyConflictError", err) + } + if strings.ContainsFunc(hc.IssueID, isControlRune) || strings.ContainsFunc(hc.BlockerID, isControlRune) { + t.Errorf("reconstructed conflict carries a control rune: issue=%q blocker=%q", hc.IssueID, hc.BlockerID) + } + if strings.ContainsFunc(hc.Error(), isControlRune) { + t.Errorf("conflict Error() carries a control rune: %q", hc.Error()) + } + }) +} + +// TestHandshakeErrorsStripControlCharacters is the handshake-family half of the +// decode-layer strip. CapabilityError and ProjectMismatchError are built in +// handshake.go, NOT through mapProblem, so they carry their own source-layer strip: +// a hostile server's bd_version or repo_root must not reach a per-id write sink +// (bd close/reopen/update) with a live escape sequence in it. +func TestHandshakeErrorsStripControlCharacters(t *testing.T) { + t.Run("CapabilityError bd_version", func(t *testing.T) { + // Advertises only issues.list; bd close needs issues.close, and the + // bd_version carries a CSI. Pre-flighting closeIssue forces the refusal. + body := `{"api_version":"v0","backend":"dolt","bd_version":"9.9\u009b31m","beads_dir":"/srv/.beads","capabilities":["issues.list"],"database":"beads","dolt_mode":"embedded","project_id":"p","repo_root":"/srv","schema_version":7}` + c, _ := newTestClient(t, Options{}, nil, serveContext(body)) + err := c.Preflight(ctx(t), OpCloseIssue) + + var capErr *CapabilityError + if !errors.As(err, &capErr) { + t.Fatalf("err is %T (%v), want *CapabilityError", err, err) + } + if strings.ContainsFunc(capErr.BdVersion, isControlRune) { + t.Errorf("BdVersion carries a control rune: %q", capErr.BdVersion) + } + if strings.ContainsFunc(err.Error(), isControlRune) { + t.Errorf("CapabilityError.Error() carries a control rune: %q", err.Error()) + } + }) + + t.Run("ProjectMismatchError repo_root, database and got", func(t *testing.T) { + // The pinned id differs from the server's, so the handshake refuses with a + // wrong-server diagnostic whose repo_root/database/project_id carry escapes. + body := `{"api_version":"v0","backend":"dolt","bd_version":"1.1.0","beads_dir":"/srv/.beads","capabilities":["issues.list"],"database":"db\u009bX","dolt_mode":"embedded","project_id":"other\u001b]0;x\u0007","repo_root":"/srv\u009b/repo","schema_version":7}` + c, _ := newTestClient(t, Options{ExpectProjectID: "mine"}, nil, serveContext(body)) + _, err := c.Handshake(ctx(t)) + + var pm *ProjectMismatchError + if !errors.As(err, &pm) { + t.Fatalf("err is %T (%v), want *ProjectMismatchError", err, err) + } + for name, got := range map[string]string{"Got": pm.Got, "Database": pm.Database, "RepoRoot": pm.RepoRoot} { + if strings.ContainsFunc(got, isControlRune) { + t.Errorf("%s carries a control rune: %q", name, got) + } + } + if strings.ContainsFunc(err.Error(), isControlRune) { + t.Errorf("ProjectMismatchError.Error() carries a control rune: %q", err.Error()) + } + }) +} + +func TestARefusalNeverEchoesTheCredential(t *testing.T) { + const token = "s3cr3t-bearer-token" + creds := &staticToken{tokens: []string{token}} + c, _ := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("WWW-Authenticate", "Bearer") + problemJSON(w, 401, `{"status":401,"code":"unauthenticated","detail":"missing or invalid bearer token","request_id":"r"}`) + }) + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("err = %v, want ErrUnauthenticated", err) + } + if strings.Contains(err.Error(), token) { + t.Fatalf("the token survived into the error text: %v", err) + } +} + +func TestTheProblemBodyIsReadWhateverTheContentType(t *testing.T) { + // A proxy that rewrites Content-Type must not cost the client its typed + // classification; `code` is what dispatches, not the media type. + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(404) + _, _ = io.WriteString(w, `{"status":404,"code":"not_found"}`) + }) + if err := c.Do(ctx(t), listIssues(), &struct{}{}); !errors.Is(err, issueops.ErrNotFound) { + t.Fatalf("err = %v, want ErrNotFound", err) + } +} + +func boolText(b bool) string { + if b { + return "true" + } + return "false" +} + +// TestBatchItemMembersSurviveTheDecode is the batch-apply half of the guard +// pair above, and it exists because those members are the ONLY place the +// offender exists on an all-or-nothing operation: the request either applied +// every item or none, so there is no per-item result array a client could find +// it in. +// +// PRESENCE IS LOAD-BEARING ON ALL FIVE, in two different directions. +// `item_index` 0 is the first item and a real answer, so a decode that modelled +// it as a bare int could not tell "the first item refused" from "no item was +// named". `item_key` and `item_issue_id` are absent for real states rather than +// gaps — not every item has a key, and a create whose id was never minted has +// no id to report. And `declared_later` is emitted in BOTH polarities, so its +// absence says the refusal was not about a key at all rather than saying false. +func TestBatchItemMembersSurviveTheDecode(t *testing.T) { + t.Run("every member present, including a zero index", func(t *testing.T) { + body := `{"status":409,"code":"precondition_failed","param":"items[0].update.expected_version",` + + `"item_index":0,"item_kind":"update","item_key":"root","item_issue_id":"bd-7"}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if p.ItemIndex == nil { + t.Fatal("ItemIndex is absent; 0 is the first item and a real answer") + } + if *p.ItemIndex != 0 { + t.Errorf("ItemIndex = %d, want 0", *p.ItemIndex) + } + for name, got := range map[string]struct { + have *string + want string + }{ + "ItemKind": {p.ItemKind, "update"}, + "ItemKey": {p.ItemKey, "root"}, + "ItemIssueID": {p.ItemIssueID, "bd-7"}, + } { + if got.have == nil { + t.Errorf("%s was dropped by the decode", name) + continue + } + if *got.have != got.want { + t.Errorf("%s = %q, want %q", name, *got.have, got.want) + } + } + }) + + t.Run("an unnamed item leaves the two optional members absent", func(t *testing.T) { + body := `{"status":400,"code":"invalid_argument","param":"items[2]","item_index":2,"item_kind":"dep_add"}` + err := refuseWith(t, 400, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if p.ItemKey != nil { + t.Errorf("ItemKey = %q for an item that named nothing symbolically; absent is a real state here", *p.ItemKey) + } + if p.ItemIssueID != nil { + t.Errorf("ItemIssueID = %q for a refusal that resolved no id", *p.ItemIssueID) + } + }) + + t.Run("declared_later is read in both polarities", func(t *testing.T) { + for _, tc := range []struct { + body string + want *bool + }{ + {`{"status":400,"code":"invalid_argument","item_index":1,"item_key":"late","declared_later":true}`, problemBoolPtr(true)}, + {`{"status":400,"code":"invalid_argument","item_index":1,"item_key":"typo","declared_later":false}`, problemBoolPtr(false)}, + {`{"status":400,"code":"invalid_argument","param":"limit"}`, nil}, + } { + err := refuseWith(t, 400, tc.body, nil, listIssues()) + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + switch { + case tc.want == nil && p.DeclaredLater != nil: + t.Errorf("DeclaredLater = %v on a refusal that was not about a key; absence is the third state", + *p.DeclaredLater) + case tc.want != nil && p.DeclaredLater == nil: + t.Error("DeclaredLater was dropped; it is emitted in both polarities and never omitted to mean false") + case tc.want != nil && *p.DeclaredLater != *tc.want: + t.Errorf("DeclaredLater = %v, want %v", *p.DeclaredLater, *tc.want) + } + } + }) + + t.Run("the strings are stripped like every other server-controlled field", func(t *testing.T) { + body := `{"status":400,"code":"invalid_argument","item_index":0,` + + `"item_kind":"create\u009b31m","item_key":"k\u0000","item_issue_id":"bd-1\u2028"}` + err := refuseWith(t, 400, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + for name, got := range map[string]*string{ + "ItemKind": p.ItemKind, "ItemKey": p.ItemKey, "ItemIssueID": p.ItemIssueID, + } { + if got == nil { + t.Errorf("%s was dropped by the decode", name) + continue + } + if strings.ContainsFunc(*got, isControlRune) { + t.Errorf("%s still carries a control rune: %q", name, *got) + } + } + }) +} + +func problemBoolPtr(b bool) *bool { return &b } diff --git a/internal/httpclient/wire/problem_wire_revision_test.go b/internal/httpclient/wire/problem_wire_revision_test.go new file mode 100644 index 000000000..6a1ba74f9 --- /dev/null +++ b/internal/httpclient/wire/problem_wire_revision_test.go @@ -0,0 +1,132 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). +package wire + +import ( + "errors" + "strings" + "testing" + + "github.com/steveyegge/beads/issueops" +) + +// TestWireRevisionUnsupportedReasonBuildsTheTypedError pins the per-request +// mirror of the handshake gate: a 400 invalid_argument whose reason is +// wire_revision_unsupported must decode to *WireRevisionUnsupportedError, not +// fall through to the generic ErrValidation the bare invalid_argument code +// would otherwise map to (reason is the only thing telling the two apart, +// exactly as it is for project_mismatch). +func TestWireRevisionUnsupportedReasonBuildsTheTypedError(t *testing.T) { + body := `{"status":400,"code":"invalid_argument","reason":"wire_revision_unsupported",` + + `"bd_version":"1.9.0","min_wire_revision":3,"wire_revision":3}` + err := refuseWith(t, 400, body, nil, listIssues()) + + if !errors.Is(err, ErrWireRevisionUnsupported) { + t.Fatalf("err = %v, want it to wrap ErrWireRevisionUnsupported", err) + } + if errors.Is(err, issueops.ErrValidation) { + t.Fatal("err also satisfies the generic ErrValidation; reason must take priority over the code table") + } + var wru *WireRevisionUnsupportedError + if !errors.As(err, &wru) { + t.Fatalf("err is %T, want *WireRevisionUnsupportedError", err) + } + if wru.BdVersion != "1.9.0" { + t.Errorf("BdVersion = %q, want 1.9.0", wru.BdVersion) + } + if wru.MinClientWireRevision != 3 || wru.ServerWireRevision != 3 { + t.Errorf("MinClientWireRevision=%d ServerWireRevision=%d, want 3 and 3", wru.MinClientWireRevision, wru.ServerWireRevision) + } + if wru.ClientWireRevision != ClientWireRevision { + t.Errorf("ClientWireRevision = %d, want this build's own %d", wru.ClientWireRevision, ClientWireRevision) + } + // err.Error() renders the generic ProblemError text (operation/status/code); + // the typed sentinel's own message — the one naming the bd_version and + // revision numbers — only comes from calling Error() on the unwrapped + // *WireRevisionUnsupportedError itself. + msg := wru.Error() + for _, want := range []string{"1.9.0", "3"} { + if !strings.Contains(msg, want) { + t.Errorf("wru.Error() = %q, want %q in it", msg, want) + } + } +} + +// TestWireRevisionUnsupportedReasonRidesTheGenericCode proves the dispatch key +// really is reason-before-code: the HTTP status and `code` here are the same +// ones an ordinary malformed-argument refusal would use. +func TestWireRevisionUnsupportedReasonRidesTheGenericCode(t *testing.T) { + body := `{"status":400,"code":"invalid_argument","param":"not_this","reason":"wire_revision_unsupported"}` + err := refuseWith(t, 400, body, nil, listIssues()) + var wru *WireRevisionUnsupportedError + if !errors.As(err, &wru) { + t.Fatalf("err is %T, want *WireRevisionUnsupportedError even though code is the generic invalid_argument", err) + } +} + +// TestLegacyRevisionTokensSurviveAsBareIntegers is the pre-#6053 tolerance: +// a server old enough to predate the decimal-string revision token spelling +// sends expected_version/actual_version as bare JSON integers. The generated +// Problem types them *string, so the primary decode silently drops a +// type-mismatched field (mapProblem discards json.Unmarshal's error) -- +// legacyRevisionFields must recover it from the same bytes. +func TestLegacyRevisionTokensSurviveAsBareIntegers(t *testing.T) { + body := `{"status":409,"code":"precondition_failed","param":"expected_version",` + + `"expected_version":42,"actual_version":43}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if !errors.Is(err, issueops.ErrVersionMismatch) { + t.Errorf("param expected_version did not map to ErrVersionMismatch: %v", err) + } + if p.ExpectedVersion == nil || *p.ExpectedVersion != "42" { + t.Fatalf("ExpectedVersion = %s, want \"42\" recovered from the bare integer", renderVersion(p.ExpectedVersion)) + } + if p.ActualVersion == nil || *p.ActualVersion != "43" { + t.Fatalf("ActualVersion = %s, want \"43\" recovered from the bare integer", renderVersion(p.ActualVersion)) + } +} + +// TestLegacyRevisionFieldsDoesNotOverrideAProperlyDecodedString proves the +// fallback is additive only: when the primary decode already produced a +// string (the shape every server since #6053 sends), legacyRevisionFields +// must not touch it. +func TestLegacyRevisionFieldsDoesNotOverrideAProperlyDecodedString(t *testing.T) { + body := `{"status":409,"code":"precondition_failed","param":"expected_version",` + + `"expected_version":"7","actual_version":"8"}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if p.ExpectedVersion == nil || *p.ExpectedVersion != "7" { + t.Fatalf("ExpectedVersion = %s, want \"7\"", renderVersion(p.ExpectedVersion)) + } + if p.ActualVersion == nil || *p.ActualVersion != "8" { + t.Fatalf("ActualVersion = %s, want \"8\"", renderVersion(p.ActualVersion)) + } +} + +// TestLegacyRevisionFieldsLeavesAbsenceAlone proves the fallback does not +// manufacture a value the server never sent: an operation that cannot report +// actual_version at all (the "an operation that cannot report what it found +// says so by absence" case the string-shape test already pins) must stay nil +// through the integer-tolerant path too. +func TestLegacyRevisionFieldsLeavesAbsenceAlone(t *testing.T) { + body := `{"status":409,"code":"precondition_failed","param":"expected_version","expected_version":42}` + err := refuseWith(t, 409, body, nil, listIssues()) + + var p *ProblemError + if !errors.As(err, &p) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if p.ExpectedVersion == nil || *p.ExpectedVersion != "42" { + t.Fatalf("ExpectedVersion = %s, want \"42\"", renderVersion(p.ExpectedVersion)) + } + if p.ActualVersion != nil { + t.Errorf("ActualVersion = %q, want nil: the server reported none", *p.ActualVersion) + } +} diff --git a/internal/httpclient/wire/project_stamp_test.go b/internal/httpclient/wire/project_stamp_test.go new file mode 100644 index 000000000..2e463c82c --- /dev/null +++ b/internal/httpclient/wire/project_stamp_test.go @@ -0,0 +1,215 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/project_stamp_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "encoding/json" + "errors" + "net/http" + "net/url" + "strings" + "testing" + + "github.com/steveyegge/beads/issueops" +) + +// The client half of ga-b8ddd.12: the per-request Bd-Project-Id stamp, its +// validation at open, and the wrong-server refusal it earns. These are pure +// httptest cases like the rest of the wire suite, so the whole branch matrix — +// stamped/unstamped, both retry attempts, valid/invalid id, the reason arm and +// its control-rune strip — is owned at PR cadence. + +const stampExpectID = "proj-workspace-alpha" + +// TestEveryRequestCarriesTheProjectStamp is the headline of the stamping half: +// the id rides on the shared roundTrip, so it must appear on a baseline read, the +// identity handshake and a write alike — the point of ga-b8ddd.12 is that even the +// five unpinned baseline reads now carry it. +func TestEveryRequestCarriesTheProjectStamp(t *testing.T) { + c, rec := newTestClient(t, Options{ExpectProjectID: stampExpectID}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = w.Write([]byte(`{}`)) + }) + for _, r := range []Request{ + {Op: OpListIssues, Method: http.MethodGet, Path: PathIssues}, + {Op: OpGetContext, Method: http.MethodGet, Path: PathContext}, + {Op: OpClaimIssue, Method: http.MethodPost, Path: "/v0/beads/issues/x:claim", Body: map[string]string{"actor": "a"}, IssueID: "x"}, + } { + if err := c.Do(ctx(t), r, &struct{}{}); err != nil { + t.Fatalf("%s: %v", r.Op, err) + } + } + if rec.count() != 3 { + t.Fatalf("made %d requests, want 3", rec.count()) + } + for i := 0; i < rec.count(); i++ { + if got := rec.at(t, i).header.Get(ProjectIDHeader); got != stampExpectID { + t.Errorf("request %d (%s) stamped %q, want %q", i, rec.at(t, i).method, got, stampExpectID) + } + } +} + +// TestNoExpectedProjectIDSendsNoStamp is the backward-compatibility contract: a +// workspace that pinned no id (the tip OSS server's loopback-trust posture) sends +// no header at all, so an older server is addressed exactly as before. +func TestNoExpectedProjectIDSendsNoStamp(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = w.Write([]byte(`{}`)) + }) + if err := c.Do(ctx(t), Request{Op: OpListIssues, Method: http.MethodGet, Path: PathIssues}, &struct{}{}); err != nil { + t.Fatalf("Do: %v", err) + } + if _, present := rec.at(t, 0).header[http.CanonicalHeaderKey(ProjectIDHeader)]; present { + t.Errorf("an unpinned client sent %s: %q", ProjectIDHeader, rec.at(t, 0).header.Get(ProjectIDHeader)) + } +} + +// TestBothAttemptsOfThe401RetryCarryTheStamp pins the stamp onto the replay, not +// just the first attempt: the retry rebuilds the request after a credential +// refresh, and the stamp is a property of the request. +func TestBothAttemptsOfThe401RetryCarryTheStamp(t *testing.T) { + creds := &staticToken{tokens: []string{"stale", "fresh"}, retry: true} + var n int + c, rec := newTestClient(t, Options{ExpectProjectID: stampExpectID}, creds, func(w http.ResponseWriter, _ *http.Request) { + n++ + if n == 1 { + problemJSON(w, http.StatusUnauthorized, `{"status":401,"code":"unauthenticated"}`) + return + } + _, _ = w.Write([]byte(`{}`)) + }) + if err := c.Do(ctx(t), Request{Op: OpListIssues, Method: http.MethodGet, Path: PathIssues}, &struct{}{}); err != nil { + t.Fatalf("Do: %v", err) + } + if rec.count() != 2 { + t.Fatalf("made %d requests, want 2 (the 401 and its retry)", rec.count()) + } + for i := 0; i < 2; i++ { + if got := rec.at(t, i).header.Get(ProjectIDHeader); got != stampExpectID { + t.Errorf("attempt %d stamped %q, want %q", i, got, stampExpectID) + } + } +} + +// TestNewRefusesAnUnstampableProjectID is the validate-at-open contract: a pinned +// id that cannot be a header value is refused LOUDLY at New, never stamped-and- +// hoped or silently skipped. The ids are built with string(rune(...)) so the +// control runes are unambiguous in source. The C1 (U+009B) and line-separator +// (U+2028) cases are the ones the byte-level httpguts check misses and the +// rune-level isControlRune check catches, which is why both layers are required. +func TestNewRefusesAnUnstampableProjectID(t *testing.T) { + base := mustParseURL(t, "http://127.0.0.1:1/") + for _, tc := range []struct { + name string + bad rune + }{ + {"NUL", 0x00}, + {"escape introducer", 0x1b}, + {"newline", 0x0a}, + {"C1 CSI the byte check misses", 0x9b}, + {"line separator", 0x2028}, + } { + t.Run(tc.name, func(t *testing.T) { + id := "proj" + string(tc.bad) + "id" + c, err := New(base, nil, Options{ExpectProjectID: id}) + if err == nil { + t.Fatalf("New accepted an unstampable id %q (client %v)", id, c.BaseURL()) + } + if !errors.Is(err, ErrInvalidProjectID) { + t.Fatalf("err = %v, want ErrInvalidProjectID", err) + } + var invalid *InvalidProjectIDError + if !errors.As(err, &invalid) { + t.Fatalf("err is %T, want *InvalidProjectIDError", err) + } + // The bad bytes are the reason it is invalid; they must not reach a + // terminal live. %q rendering escapes them. + if strings.ContainsFunc(invalid.Error(), isControlRune) { + t.Errorf("the refusal leaked a live control rune: %q", invalid.Error()) + } + }) + } + // A clean id opens fine — the check is a gate, not a wall. + if _, err := New(base, nil, Options{ExpectProjectID: "proj-ok-123"}); err != nil { + t.Errorf("New refused a valid id: %v", err) + } +} + +// mismatchBody builds the wire body for a project_mismatch refusal, JSON-encoding +// serverProjectID so any control runes in it are properly escaped on the wire — +// exactly as the server's own encoder would emit them. +func mismatchBody(t *testing.T, serverProjectID string) string { + t.Helper() + raw, err := json.Marshal(map[string]any{ + "status": 400, + "code": "invalid_argument", + "param": ProjectIDHeader, + "reason": ReasonProjectMismatch, + "server_project_id": serverProjectID, + "detail": "the stamp names a project this server does not serve", + }) + if err != nil { + t.Fatalf("marshal the mismatch body: %v", err) + } + return string(raw) +} + +// TestAProjectMismatchMapsToTheTypedWrongServerError is the reason-discriminated +// arm: a 400 whose reason is project_mismatch becomes *ProjectMismatchError with +// both ids, not the generic ErrValidation the invalid_argument code would map to. +func TestAProjectMismatchMapsToTheTypedWrongServerError(t *testing.T) { + const expected = "proj-workspace-beta" + const serverOwns = "proj-the-other-one" + err := refuseWith(t, 400, mismatchBody(t, serverOwns), nil, listIssues(), func(o *Options) { o.ExpectProjectID = expected }) + + if !errors.Is(err, ErrProjectMismatch) { + t.Fatalf("err = %v, want ErrProjectMismatch", err) + } + var mismatch *ProjectMismatchError + if !errors.As(err, &mismatch) { + t.Fatalf("err is %T, want *ProjectMismatchError", err) + } + if mismatch.Expected != expected { + t.Errorf("Expected = %q, want the workspace's %q", mismatch.Expected, expected) + } + if mismatch.Got != serverOwns { + t.Errorf("Got = %q, want the server's %q", mismatch.Got, serverOwns) + } + // Database/RepoRoot are deliberately empty on the per-request path: this + // refusal discloses only the server's id, not its location. + if mismatch.Database != "" || mismatch.RepoRoot != "" { + t.Errorf("the per-request mismatch disclosed a location: db=%q root=%q", mismatch.Database, mismatch.RepoRoot) + } + // The reason arm ran ahead of the code table, so this did NOT fall through to + // the invalid_argument sentinel. + if errors.Is(err, issueops.ErrValidation) { + t.Errorf("the wrong-server refusal classified as a plain validation error") + } +} + +// TestTheServerProjectIDIsStrippedAtTheWireBoundary: server_project_id is +// server-controlled, so its control runes are removed where every other problem +// field's are — before the typed error can reach a %v stderr sink. +func TestTheServerProjectIDIsStrippedAtTheWireBoundary(t *testing.T) { + dirty := "evil" + string(rune(0x9b)) + "31m" + string(rune(0x1b)) + "]0;x" + string(rune(0x07)) + err := refuseWith(t, 400, mismatchBody(t, dirty), nil, listIssues(), func(o *Options) { o.ExpectProjectID = "proj-clean" }) + + var mismatch *ProjectMismatchError + if !errors.As(err, &mismatch) { + t.Fatalf("err is %T, want *ProjectMismatchError", err) + } + if strings.ContainsFunc(mismatch.Got, isControlRune) { + t.Errorf("Got still carries a control rune: %q", mismatch.Got) + } + if strings.ContainsFunc(mismatch.Error(), isControlRune) { + t.Errorf("the rendered wrong-server error carries a control rune: %q", mismatch.Error()) + } +} + +func mustParseURL(t *testing.T, raw string) *url.URL { + t.Helper() + u, err := url.Parse(raw) + if err != nil { + t.Fatalf("parse %q: %v", raw, err) + } + return u +} diff --git a/internal/httpclient/wire/revision_tolerance.go b/internal/httpclient/wire/revision_tolerance.go new file mode 100644 index 000000000..82001d839 --- /dev/null +++ b/internal/httpclient/wire/revision_tolerance.go @@ -0,0 +1,206 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). +package wire + +import ( + "bytes" + "encoding/json" + + "github.com/steveyegge/beads/internal/httpapi/apigen" +) + +// revisionKey is the one JSON member this file ever rewrites. It never touches +// `expected_version`: that member is request-side only (the client sends it, +// never decodes it), so the response-decode gap this file closes does not +// reach it. +const revisionKey = "revision" + +// itemsKey is ApplyBatchResponse's one array of nested revision-bearing +// objects (apigen.ApplyItemResult). No other covered type below carries a +// nested object with a `revision` of its own: every other member here is a +// plain, top-level one, and tolerateLegacyRevisionNumbers rewrites nothing +// that is not reached through exactly this key or the top level. +const itemsKey = "items" + +// revisionBearingResponse reports whether out is one of the apigen response +// types carrying the optimistic-concurrency `revision` member — the member +// this client always decodes as a JSON string (the post-#6053 decimal-token +// shape, upstream's own fix for the fact that the token spans the full 64-bit +// range and a JSON number would round past 2^53). A server that predates +// #6053 answers the same member as a bare JSON integer under the same +// `api_version: "v0"`, and the handshake has no signal for that move — a +// pre-#6053 server's `ContextResponse` omits `wire_revision` exactly the way +// every other old server does, so the one place left to tolerate the shape is +// here, at the reader, on the small, explicit set of types that carry it. +// +// The set is exactly the schemas internal/httpapi/wireshape's digest records +// with a `revision` member (TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember +// pins this against the same golden.json TestWireShapeDigest guards, so a new +// revision-bearing schema cannot slip past both without the coverage test +// failing first): +// +// - apigen.ApplyBatchResponse: no top-level `revision` of its own, but each +// of its `items` is an apigen.ApplyItemResult, which does carry one — see +// tolerateLegacyRevisionNumbers' items handling below. +// - apigen.CloseIssueResponse, apigen.ReleaseIssueResponse, +// apigen.ReopenIssueResponse, apigen.UpdateIssueResponse: a top-level +// `revision` each. +// - apigen.IssueDetails (an alias for types.IssueDetails: GET +// /v0/beads/issues/{id}'s body): also a top-level `revision`. getIssue is +// a BASELINE operation (dispatched before any post-baseline call would +// have forced the handshake that populates serverPredatesRevisionStrings' +// cache), which is why that gate treats "no cached handshake at all" as +// "tolerate" rather than "skip" — see its doc comment. +// +// Keeping the set explicit (rather than walking every response body looking +// for a stray "revision" key) means a type added later that happens to reuse +// the word for something else — a schema version, a cache generation — is not +// silently coerced; a new revision-bearing response type must be added here +// deliberately, the same discipline problem.go's legacyRevisionFields already +// keeps on the error path. +func revisionBearingResponse(out any) bool { + switch out.(type) { + case *apigen.ApplyBatchResponse, + *apigen.CloseIssueResponse, + *apigen.ReleaseIssueResponse, + *apigen.ReopenIssueResponse, + *apigen.UpdateIssueResponse, + *apigen.IssueDetails: + return true + default: + return false + } +} + +// serverPredatesRevisionStrings reports whether the cached handshake saw a +// server old enough that its `revision`/`expected_version` tokens may still +// be bare JSON integers: one that omitted `ContextResponse.wire_revision` +// entirely, which ClientMinWireRevision's doc pins as meaning exactly that (0 +// and 1 are permanently retired values no server implementing the field will +// ever legitimately send). +// +// No cached handshake at all answers true too (review follow-up: it used to +// answer false, on the reasoning that every revision-bearing response type +// belongs to a non-baseline write, so the handshake forced ahead of it would +// already be cached — true for every one of them EXCEPT apigen.IssueDetails, +// whose operation, getIssue, is itself a baseline op that can dispatch with no +// handshake ever cached). Answering true unconditionally here is safe exactly +// because tolerateLegacyRevisionNumbers' rewrite is scoped to the few +// documented positions a legacy integer can actually appear at (see its doc +// comment) rather than a generic walk: running it against a modern server's +// already-string-shaped response, or with no handshake evidence either way, +// costs one structural no-op walk and touches nothing. +func (c *Client) serverPredatesRevisionStrings() bool { + c.handshake.mu.Lock() + defer c.handshake.mu.Unlock() + return c.handshake.snap == nil || c.handshake.snap.Context.WireRevision == 0 +} + +// tolerateLegacyRevisionNumbers rewrites a bare-JSON-number value held at +// body's top-level "revision" key, and — only when out is +// *apigen.ApplyBatchResponse — at the "revision" key of each element of its +// top-level "items" array, into that number's decimal-string spelling: the +// shape every apigen response type above declares the member as. It returns +// body unchanged (the same slice) when nothing needed rewriting, so a modern +// server's already-string-shaped response pays one no-op decode and nothing +// else. +// +// IT NEVER RECURSES BEYOND THOSE TWO DOCUMENTED POSITIONS (review HIGH: +// data corruption). An earlier version of this file walked every nested +// object and array looking for a stray "revision" key, which reached +// CloseIssueResponse.issue.metadata and every other caller-owned JSON blob +// this client passes through opaquely — a user's own metadata shaped like +// `{"revision":3}` came back with that value silently turned into a string, +// and serverPredatesRevisionStrings' gate (WireRevision == 0, or now no +// handshake at all) covers every legacy AND unhandshaked request, not just +// the narrow pre-#6053 population the rewrite exists for. Scoping the rewrite +// to exactly the documented wire positions — never descending into `issue`, +// `metadata`, or any other nested object the response carries — is what makes +// answering true unconditionally above safe: there is no longer a nested +// object this function would touch by accident. +func tolerateLegacyRevisionNumbers(body []byte, out any) []byte { + var obj map[string]json.RawMessage + if err := json.Unmarshal(body, &obj); err != nil { + return body + } + changed := false + if v, ok := obj[revisionKey]; ok && isBareJSONNumber(v) { + obj[revisionKey] = quoteJSONNumber(v) + changed = true + } + if _, ok := out.(*apigen.ApplyBatchResponse); ok { + if rewritten, ok := rewriteItemRevisions(obj[itemsKey]); ok { + obj[itemsKey] = rewritten + changed = true + } + } + if !changed { + return body + } + rewritten, err := json.Marshal(obj) + if err != nil { + return body + } + return rewritten +} + +// rewriteItemRevisions rewrites the top-level "revision" key of each element +// of items (ApplyBatchResponse.items, each an apigen.ApplyItemResult) that +// holds a bare JSON number. It reports ok == false when items is absent, +// malformed, or needed no rewriting at all, in which case the caller must +// leave the original bytes alone. +// +// Like tolerateLegacyRevisionNumbers itself, this never looks past each +// item's own top-level members: ApplyItemResult carries no nested object of +// its own a legacy integer could hide inside, but even if a future field +// added one, only "revision" at this exact level is ever a candidate. +func rewriteItemRevisions(raw json.RawMessage) (json.RawMessage, bool) { + if len(bytes.TrimSpace(raw)) == 0 { + return nil, false + } + var items []map[string]json.RawMessage + if err := json.Unmarshal(raw, &items); err != nil { + return nil, false + } + changed := false + for _, item := range items { + if v, ok := item[revisionKey]; ok && isBareJSONNumber(v) { + item[revisionKey] = quoteJSONNumber(v) + changed = true + } + } + if !changed { + return nil, false + } + rewritten, err := json.Marshal(items) + if err != nil { + return nil, false + } + return rewritten, true +} + +// isBareJSONNumber reports whether val's first non-space byte starts a JSON +// number rather than a string, object, array, boolean or null. +func isBareJSONNumber(val json.RawMessage) bool { + trimmed := bytes.TrimSpace(val) + if len(trimmed) == 0 { + return false + } + c := trimmed[0] + return c == '-' || (c >= '0' && c <= '9') +} + +// quoteJSONNumber renders a raw JSON number token as a quoted JSON string +// holding its exact decimal digits — byte-for-byte, never round-tripped +// through an int64 or float64, so a token outside either range still survives +// unchanged. +func quoteJSONNumber(val json.RawMessage) json.RawMessage { + trimmed := bytes.TrimSpace(val) + quoted, err := json.Marshal(string(trimmed)) + if err != nil { + // trimmed is already a well-formed JSON number token (isBareJSONNumber's + // caller only reaches here on that path), so a plain string of its bytes + // can never fail to marshal. + return val + } + return quoted +} diff --git a/internal/httpclient/wire/revision_tolerance_test.go b/internal/httpclient/wire/revision_tolerance_test.go new file mode 100644 index 000000000..28a31660f --- /dev/null +++ b/internal/httpclient/wire/revision_tolerance_test.go @@ -0,0 +1,327 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). +package wire + +import ( + "encoding/json" + "net/http" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/httpapi/apigen" +) + +// serveLegacyServer fakes a server old enough to predate #6053: its context +// response omits wire_revision entirely (contextBodyWithWireRevision's 0 +// renders it omitted, matching ClientMinWireRevision's doc), and its write +// and getIssue responses still carry `revision` as a bare JSON integer rather +// than the decimal-string shape every apigen response type now declares. +// getIssueBody may be "" for a test that never dispatches getIssue. +func serveLegacyServer(t *testing.T, readyBody, closeBody, getIssueBody string) http.HandlerFunc { + t.Helper() + return func(w http.ResponseWriter, r *http.Request) { + switch { + case r.URL.Path == PathContext: + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(contextBodyWithWireRevision("v0", "", 0, 0, "issues.list", "ready.list", "issues.close", "issues.get"))) + case r.URL.Path == PathReady: + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(readyBody)) + case strings.HasSuffix(r.URL.Path, MethodClose): + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(closeBody)) + case r.Method == http.MethodGet && strings.HasPrefix(r.URL.Path, PathIssues+"/") && getIssueBody != "": + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(getIssueBody)) + default: + problemJSON(w, http.StatusNotFound, `{"status":404,"code":"not_found"}`) + } + } +} + +// getIssue dispatches getIssue directly: there is no GetIssue wrapper method +// on *Client yet (S3), but getIssue is a first-slice, known capability token +// (opCapability's "issues.get"), so Request/dispatch already support it. +func getIssue(t *testing.T, c *Client, id string) (*apigen.IssueDetails, error) { + t.Helper() + path, err := IssuePath(id) + if err != nil { + t.Fatalf("IssuePath: %v", err) + } + var out apigen.IssueDetails + err = c.dispatch(ctx(t), Request{Op: OpGetIssue, Method: http.MethodGet, Path: path}, &out) + return &out, err +} + +// TestListReadyWorkAgainstAPreSixZeroFiveThreeServer is the read half of HIGH +// #2's coverage: ready.list's response carries no `revision` member at all, so +// a server old enough to omit wire_revision from its handshake must not need +// any tolerance here — this pins that the baseline read path is simply +// unaffected by the legacy-server detection this file adds. +func TestListReadyWorkAgainstAPreSixZeroFiveThreeServer(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, + serveLegacyServer(t, `{"has_more":false,"items":[]}`, `{"revision":42}`, "")) + + page, err := c.ListReadyWork(ctx(t), nil) + if err != nil { + t.Fatalf("ListReadyWork against a pre-#6053 server: %v", err) + } + if page.HasMore || len(page.Items) != 0 { + t.Fatalf("ListReadyWork: got %+v, want an empty page", page) + } +} + +// TestCloseIssueAgainstAPreSixZeroFiveThreeServer is the guarded-write half: +// CloseIssueRequest carries ExpectedVersion, and the fake server answers the +// close with a bare-integer `revision` — the shape a server that predates +// #6053 actually sends, and the shape apigen.CloseIssueResponse.Revision +// (declared `string`) could not decode before this file's fix. Before the +// fix this failed with an untyped json.UnmarshalTypeError; this pins that it +// now decodes, carrying the token's exact decimal digits. CloseIssue is never +// a baseline op, so dispatch's Preflight forces the handshake ahead of Do — +// this is therefore also the "with a prior handshake" case. +func TestCloseIssueAgainstAPreSixZeroFiveThreeServer(t *testing.T) { + expected := "7" + c, rec := newTestClient(t, Options{}, nil, + serveLegacyServer(t, `{"has_more":false,"items":[]}`, `{"revision":99}`, "")) + + resp, err := c.CloseIssue(ctx(t), "be-1", apigen.CloseIssueRequest{ + Actor: "agent-1", + ExpectedVersion: &expected, + }) + if err != nil { + t.Fatalf("CloseIssue against a pre-#6053 server: %v", err) + } + if resp.Revision != "99" { + t.Errorf("Revision = %q, want \"99\" (the bare integer's exact decimal spelling)", resp.Revision) + } + if rec.count() != 2 { + t.Fatalf("expected one context request and one close request, got %d requests", rec.count()) + } +} + +// TestCloseIssueAgainstAModernServerIsUntouched proves the rewrite never fires +// against a server that already sends the decimal-string shape: the handshake +// carries a real wire_revision, so serverPredatesRevisionStrings is false and +// tolerateLegacyRevisionNumbers never runs. +func TestCloseIssueAgainstAModernServerIsUntouched(t *testing.T) { + expected := "7" + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + switch { + case r.URL.Path == PathContext: + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(contextBodyWithWireRevision("v0", "", ClientWireRevision, 0, "issues.close"))) + case strings.HasSuffix(r.URL.Path, MethodClose): + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"revision":"99"}`)) + default: + problemJSON(w, http.StatusNotFound, `{"status":404,"code":"not_found"}`) + } + }) + + resp, err := c.CloseIssue(ctx(t), "be-1", apigen.CloseIssueRequest{ + Actor: "agent-1", + ExpectedVersion: &expected, + }) + if err != nil { + t.Fatalf("CloseIssue against a modern server: %v", err) + } + if resp.Revision != "99" { + t.Errorf("Revision = %q, want \"99\"", resp.Revision) + } +} + +// TestGetIssueAgainstAPreSixZeroFiveThreeServerWithNoPriorHandshake is review +// follow-up HIGH-a's missing-type coverage, the no-handshake-cached half: +// getIssue is a BASELINE operation (baselineOps[OpGetIssue]), so Preflight +// never forces a handshake for it, and a client that has made no other call +// yet dispatches it with c.handshake.snap == nil. Before this fix, +// serverPredatesRevisionStrings answered false in exactly this state — "no +// evidence this is a legacy server" — so apigen.IssueDetails's bare-integer +// `revision` was never tolerated at all for a cold client's first call. It +// must now decode, because the gate treats "no snapshot" as "tolerate" and +// the rewrite itself is scoped (HIGH-b) to be safe either way. +func TestGetIssueAgainstAPreSixZeroFiveThreeServerWithNoPriorHandshake(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, + serveLegacyServer(t, "", "", `{"id":"be-1","revision":7}`)) + + details, err := getIssue(t, c, "be-1") + if err != nil { + t.Fatalf("getIssue against a pre-#6053 server with no prior handshake: %v", err) + } + if details.Revision != "7" { + t.Errorf("Revision = %q, want \"7\"", details.Revision) + } + if rec.count() != 1 { + t.Fatalf("getIssue is baseline: expected exactly one request (no forced handshake), got %d", rec.count()) + } +} + +// TestGetIssueAgainstAPreSixZeroFiveThreeServerWithPriorHandshake is the same +// coverage with a handshake already cached (forced here by a prior +// Handshake() call, the way a real session that already made a non-baseline +// call would arrive at a later getIssue): serverPredatesRevisionStrings now +// reads WireRevision == 0 off the cached snapshot instead of seeing no +// snapshot at all, and must still tolerate. +func TestGetIssueAgainstAPreSixZeroFiveThreeServerWithPriorHandshake(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, + serveLegacyServer(t, "", "", `{"id":"be-1","revision":7}`)) + + if _, err := c.Handshake(ctx(t)); err != nil { + t.Fatalf("Handshake: %v", err) + } + + details, err := getIssue(t, c, "be-1") + if err != nil { + t.Fatalf("getIssue against a pre-#6053 server with a cached handshake: %v", err) + } + if details.Revision != "7" { + t.Errorf("Revision = %q, want \"7\"", details.Revision) + } + if rec.count() != 2 { + t.Fatalf("expected one context request and one getIssue request, got %d", rec.count()) + } +} + +// TestCloseIssueLegacyRewriteNeverTouchesIssueMetadata is review follow-up +// HIGH-b's regression coverage. tolerateLegacyRevisionNumbers used to walk +// every nested object and array in the body looking for a bare-number +// "revision" key; that reached CloseIssueResponse.issue.metadata — a blob +// this client passes through opaquely for the caller, which may itself hold +// a member literally named "revision" at any depth as ordinary user data. +// The rewrite must now touch only the body's own top-level "revision", never +// descending into `issue` at all, so a metadata document with "revision" keys +// at several nesting depths comes back byte-for-byte identical to what the +// legacy server sent. +func TestCloseIssueLegacyRewriteNeverTouchesIssueMetadata(t *testing.T) { + const metadata = `{"revision":3,"n":[{"revision":4}],"deep":{"inner":{"revision":5}}}` + legacyBody := `{"already_closed":false,"issue":{"id":"be-1","metadata":` + metadata + `},"open_children":0,"revision":42}` + + expected := "7" + c, _ := newTestClient(t, Options{}, nil, + serveLegacyServer(t, "", legacyBody, "")) + + resp, err := c.CloseIssue(ctx(t), "be-1", apigen.CloseIssueRequest{ + Actor: "agent-1", + ExpectedVersion: &expected, + }) + if err != nil { + t.Fatalf("CloseIssue against a pre-#6053 server: %v", err) + } + if resp.Revision != "42" { + t.Errorf("Revision = %q, want \"42\" (the top-level bare integer, rewritten)", resp.Revision) + } + if got := string(resp.Issue.Metadata); got != metadata { + t.Errorf("Issue.Metadata = %s, want it byte-for-byte unchanged at %s (metadata must never be rewritten)", got, metadata) + } +} + +// TestApplyBatchLegacyItemRevisionsAreRewritten is ApplyBatchResponse's own +// half of HIGH #2: it carries no top-level `revision` of its own, but each of +// its `items` is an apigen.ApplyItemResult, which does — tolerateLegacyRevisionNumbers +// rewrites exactly that nested position (and nothing else nested) when out is +// *apigen.ApplyBatchResponse. +func TestApplyBatchLegacyItemRevisionsAreRewritten(t *testing.T) { + legacyBody := `{"items":[` + + `{"kind":"create","issue_id":"be-1","changed":true,"revision":10},` + + `{"kind":"close","issue_id":"be-2","changed":true,"revision":11}` + + `]}` + + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + switch { + case r.URL.Path == PathContext: + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(contextBodyWithWireRevision("v0", "", 0, 0, "issues.batchApply"))) + case r.URL.Path == PathIssuesBatchApply: + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(legacyBody)) + default: + problemJSON(w, http.StatusNotFound, `{"status":404,"code":"not_found"}`) + } + }) + + resp, err := c.ApplyBatch(ctx(t), ApplyBatchRequest{}) + if err != nil { + t.Fatalf("ApplyBatch against a pre-#6053 server: %v", err) + } + if len(resp.Items) != 2 { + t.Fatalf("Items = %+v, want 2", resp.Items) + } + if resp.Items[0].Revision != "10" || resp.Items[1].Revision != "11" { + t.Errorf("Items revisions = %q, %q, want \"10\", \"11\"", resp.Items[0].Revision, resp.Items[1].Revision) + } +} + +// revisionSchemaCoverage maps every apigen schema name +// internal/httpapi/wireshape's golden digest records as carrying a `revision` +// member to a representative value revisionBearingResponse must recognize. +// +// "ApplyItemResult" is the one entry with no case of its own in +// revisionBearingResponse's type switch: it is never decoded as Do's own +// `out` (it only ever appears nested inside ApplyBatchResponse.Items), so its +// coverage is ApplyBatchResponse's own case there, plus +// tolerateLegacyRevisionNumbers' separate items[] handling — +// TestApplyBatchLegacyItemRevisionsAreRewritten above is what actually proves +// that half; this map only proves revisionBearingResponse itself still says +// "yes" for the type that carries it. +var revisionSchemaCoverage = map[string]any{ + "ApplyItemResult": &apigen.ApplyBatchResponse{}, + "CloseIssueResponse": &apigen.CloseIssueResponse{}, + "IssueDetails": &apigen.IssueDetails{}, + "ReleaseIssueResponse": &apigen.ReleaseIssueResponse{}, + "ReopenIssueResponse": &apigen.ReopenIssueResponse{}, + "UpdateIssueResponse": &apigen.UpdateIssueResponse{}, +} + +// TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember is +// review follow-up HIGH-a's exhaustiveness guard. It derives the set of +// schemas a legacy server's bare-integer `revision` can appear on from the +// same committed golden digest TestWireShapeDigest +// (internal/httpapi/wireshape) guards against drift, rather than hand-listing +// schema names a second time — the grep this file's first version was +// written against missed apigen.IssueDetails precisely because it is a type +// alias for types.IssueDetails, invisible to a grep for "type \w+ struct.* +// revision". A schema that gains a `revision` member later and is not added +// to revisionSchemaCoverage now fails HERE, rather than only showing up as a +// silent decode failure against a real legacy server. +func TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember(t *testing.T) { + path := filepath.Join("..", "..", "httpapi", "wireshape", "testdata", "golden.json") + data, err := os.ReadFile(path) + if err != nil { + t.Fatalf("reading the wireshape golden digest: %v", err) + } + var digest struct { + Entries []struct { + Schema string `json:"schema"` + Member string `json:"member"` + } `json:"entries"` + } + if err := json.Unmarshal(data, &digest); err != nil { + t.Fatalf("unmarshaling the wireshape golden digest: %v", err) + } + + seen := map[string]bool{} + for _, e := range digest.Entries { + if e.Member != "revision" { + continue + } + seen[e.Schema] = true + out, covered := revisionSchemaCoverage[e.Schema] + if !covered { + t.Errorf("golden.json schema %q carries a `revision` member with no entry in revisionSchemaCoverage; add one, and extend revisionBearingResponse (or document why it needs no legacy-integer tolerance)", e.Schema) + continue + } + if !revisionBearingResponse(out) { + t.Errorf("revisionSchemaCoverage says %q is covered by %T, but revisionBearingResponse(%T) returned false", e.Schema, out, out) + } + } + if len(seen) == 0 { + t.Fatal("golden.json parsing found no schema with a `revision` member; the fixture moved or this test's assumptions about its shape broke") + } + for schema := range revisionSchemaCoverage { + if !seen[schema] { + t.Errorf("revisionSchemaCoverage lists %q, but golden.json has no entry for it with member \"revision\" anymore; remove the stale entry", schema) + } + } +} diff --git a/internal/httpclient/wire/skew_test.go b/internal/httpclient/wire/skew_test.go new file mode 100644 index 000000000..6cf0465af --- /dev/null +++ b/internal/httpclient/wire/skew_test.go @@ -0,0 +1,752 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/skew_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "errors" + "go/ast" + "go/parser" + "go/token" + "io" + "net/http" + "os" + "path/filepath" + "slices" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/httpclient/encode" + "github.com/steveyegge/beads/issueops" +) + +// The version-skew matrix. +// +// Everything here is a DOCTORED server: a hand-built ContextResponse or a canned +// problem+json describing a bd serve that is older, newer, or subtly wrong in a +// way no real binary in the fixture cache is. That is the point. The released +// binaries in the cross-version smoke lane can only be the versions that were +// actually cut; this file is where the branch matrix lives, because a doctored +// context can be a server that never shipped and a released one cannot be a +// server that has not shipped YET. +// +// The split is the design's (test-lane map, the skew rows): the deterministic, +// in-process half runs at PR cadence here, and the released-binary composition +// half runs in cross-version-smoke.yml. Neither substitutes for the other — +// this half owns the branches, that half owns the reality check. +// +// Three skew directions are covered, and they fail in different ways: +// +// newer CLI, older server the client sends something the server never had. +// A capability it does not advertise is D7 case 2, +// caught BEFORE the dial; a parameter it does not +// know is D7 case 3, caught in the 400 that comes +// back. +// older CLI, newer server the server sends something the client never had. +// Every one of these must be IGNORED — an unknown +// response member, an unknown capability token, an +// unknown problem code — because the wire's +// additivity is the whole reason a client older than +// its server keeps working. +// wrong server entirely the identity gates: api_version and project_id. + +// firstSliceTokens is what a v0 server from the first slice advertises: the four +// gated operations of the six-operation first release (`bd-serve-v0.md`, "The +// surface"). health and getContext contribute no token. +// +// It is spelled out rather than derived, because deriving it from the client's +// own baseline set would make the fixture agree with the code under test by +// construction — the exact way a skew fixture goes vacuous. +var firstSliceTokens = []string{"issues.claim", "issues.get", "issues.list", "ready.list"} + +// allTokens is the tip server's advertised set, taken from this client's own +// map. Set-equality with the SERVER's list is the vocabulary gate's job +// (TestCapabilityTableMatchesTheServerRouteTable); here it is just "a server +// that has everything". +func allTokens() []string { + out := make([]string, 0, len(opCapability)) + for _, token := range opCapability { + if token != "" { + out = append(out, token) + } + } + slices.Sort(out) + return out +} + +func postBaselineOps() []string { + out := make([]string, 0, len(opCapability)) + for op := range opCapability { + if !IsBaseline(op) { + out = append(out, op) + } + } + slices.Sort(out) + return out +} + +func TestAgainstAFirstSliceServerEveryPostBaselineOperationRefusesWithCaseTwoData(t *testing.T) { + // The headline skew case: today's CLI against the server that shipped first. + // Twenty-six operations did not exist there, and every one of them has to + // refuse from the advertised list rather than dial and read a bare 404 as + // "no such issue". + c, rec := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1", firstSliceTokens...))) + + // Partition the post-baseline set by whether the first-slice server already + // serves the operation. claimIssue is the one post-baseline op gated on a + // first-slice token (issues.claim): forcing its handshake (ga-b8ddd.11) adds + // the identity gate, but because that token IS advertised it preflights clean + // against even the oldest server — no capability-compat risk. Everything else + // post-baseline is a genuinely newer operation the first slice never served. + var compat, refused []string + for _, op := range postBaselineOps() { + token, _ := CapabilityFor(op) + if slices.Contains(firstSliceTokens, token) { + compat = append(compat, op) + } else { + refused = append(refused, op) + } + } + if len(compat) != 1 || compat[0] != OpClaimIssue { + t.Fatalf("post-baseline ops on a first-slice token = %v, want exactly [claimIssue]", compat) + } + // The dimension is pinned so the matrix cannot shrink silently: the first + // slice served six operations and the tip surface has forty-one, so + // thirty-five of them are things a first-slice server has never heard of. The + // wire wave moved this from twenty-seven to thirty — claimNext, release and + // count — wave 2 to thirty-two, adding the dependency-edge count and the + // related read, and the mini-sync to thirty-five: the comment write and the + // two config writes. Each is an operation a first-slice server never served + // and this client does not yet dial, which is exactly the shape the refusal + // matrix is about. + if len(refused) != 35 { + t.Fatalf("the post-baseline set has %d operations a first-slice server never served, want 35", len(refused)) + } + + // The compat op forces the handshake yet preflights clean: issues.claim is on + // the first-slice server's advertised list, so the gate never becomes a refusal. + for _, op := range compat { + if err := c.Preflight(ctx(t), op); err != nil { + t.Errorf("Preflight(%s) against a first-slice server = %v, want nil (issues.claim is first-slice)", op, err) + } + } + + for _, op := range refused { + token, _ := CapabilityFor(op) + err := c.Preflight(ctx(t), op) + + var absent *CapabilityError + if !errors.As(err, &absent) { + t.Errorf("Preflight(%s) = %v (%T), want *CapabilityError", op, err, err) + continue + } + // D7 case 2 names three things, and the typed error has to carry all + // three or the render layer starts parsing prose for them. + if absent.Capability != token { + t.Errorf("Preflight(%s) refused on capability %q, want %q", op, absent.Capability, token) + } + if absent.BdVersion != "1.1.0" { + t.Errorf("Preflight(%s) carries bd_version %q, want the server's", op, absent.BdVersion) + } + if absent.ServerURL == "" || !strings.HasPrefix(absent.ServerURL, "http") { + t.Errorf("Preflight(%s) carries server URL %q", op, absent.ServerURL) + } + if !slices.Equal(absent.Capabilities, firstSliceTokens) { + t.Errorf("Preflight(%s) carries %v, want the server's advertised %v", op, absent.Capabilities, firstSliceTokens) + } + if !errors.Is(err, ErrCapabilityAbsent) { + t.Errorf("Preflight(%s) does not unwrap to ErrCapabilityAbsent", op) + } + } + + // One context fetch for the whole matrix: the refusals are answered from the + // cache, not by re-asking a server that already said no. + if rec.count() != 1 { + t.Errorf("made %d context fetches, want 1", rec.count()) + } +} + +func TestEachOperationRefusesOnItsOwnTokenAndNoOtherOperationsToken(t *testing.T) { + // The holdout matrix: for every post-baseline operation, a doctored server + // that advertises the whole vocabulary EXCEPT that operation's token. + // + // This is what catches a mis-wired opCapability row that a "server has + // everything" and a "server has nothing" fixture both miss: two operations + // sharing a token, or an operation pointed at a neighbour's, still pass both + // extremes and fail exactly here. + every := allTokens() + + for _, op := range postBaselineOps() { + token, _ := CapabilityFor(op) + held := make([]string, 0, len(every)) + for _, candidate := range every { + if candidate != token { + held = append(held, candidate) + } + } + + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1", held...))) + + var absent *CapabilityError + if err := c.Preflight(ctx(t), op); !errors.As(err, &absent) { + t.Errorf("holding back %q: Preflight(%s) = %v, want a refusal", token, op, err) + } else if absent.Capability != token { + t.Errorf("holding back %q: Preflight(%s) refused on %q", token, op, absent.Capability) + } + + // And nothing else moved: every other operation still serves against the + // same doctored server. + for _, other := range postBaselineOps() { + if other == op { + continue + } + if err := c.Preflight(ctx(t), other); err != nil { + t.Errorf("holding back %q broke an unrelated operation: Preflight(%s) = %v", token, other, err) + } + } + } +} + +func TestABaselineOperationDispatchesEvenWhenTheServerAdvertisesNoTokenForIt(t *testing.T) { + // The doctored route table, missing arm: a server whose advertised list has + // none of the baseline tokens. + // + // The two-speed policy says the five baseline operations dispatch without + // consulting the list AT ALL, and that has to survive a server that says + // nothing about them — a trimmed deployment, a capability list built from a + // route table someone pruned, or simply a context this client mis-decoded. + // Gating them on the list would turn the hot work-distribution path off on + // the strength of a field that is not the contract for it. claimIssue is not + // in this set: it forces the handshake now (ga-b8ddd.11), so it would dial. + c, rec := newTestClient(t, Options{}, nil, func(http.ResponseWriter, *http.Request) { + t.Error("a baseline pre-flight dialed a server whose list omits its token") + }) + for _, op := range []string{OpHealth, OpGetContext, OpListReadyWork, OpListIssues, OpGetIssue} { + if err := c.Preflight(ctx(t), op); err != nil { + t.Errorf("Preflight(%s) against a server advertising nothing: %v", op, err) + } + } + if rec.count() != 0 { + t.Errorf("made %d requests, want 0", rec.count()) + } +} + +func TestAServerAdvertisingOperationsThisClientDoesNotKnowIsToleratedWhole(t *testing.T) { + // The doctored route table, extra arm: a NEWER server, advertising tokens for + // post-baseline operations this client has never heard of. + // + // Older CLI against newer server is the additive direction, and the rule is + // that an unknown token is inert. It must not fail the handshake, must not + // disturb the operations this client does know, and must still appear in the + // advertised list a refusal prints — the user is entitled to see that the + // server offers things their binary cannot reach. + future := append(allTokens(), "issues.teleport", "beads.prophesy", "memories.forget.v2") + slices.Sort(future) + + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBody("v0", "proj-1", future...))) + + snap, err := c.Handshake(ctx(t)) + if err != nil { + t.Fatalf("Handshake against a newer server: %v", err) + } + if !slices.Equal(snap.Capabilities(), future) { + t.Errorf("Capabilities() = %v, want the server's own %v", snap.Capabilities(), future) + } + for _, op := range postBaselineOps() { + if err := c.Preflight(ctx(t), op); err != nil { + t.Errorf("Preflight(%s) against a newer server: %v", op, err) + } + } + // An operation the client does not know still refuses at the pre-flight, + // even though the SERVER advertises it: this client cannot build a request + // for an operation it has no path or encoder for, and pretending otherwise + // would turn an unknown operation into an unrouted dial. + if err := c.Preflight(ctx(t), "teleportIssue"); err == nil { + t.Error("an operation this client does not know pre-flighted clean because the server advertised one") + } +} + +func TestAFuturisticContextDecodesAndGatesOnApiVersionAlone(t *testing.T) { + // Additive content on a v0 context: members this client's struct does not + // have, a bd_version from the future, a schema_version well past anything + // shipped. None of the three is a feature contract — the capability list is + // — so all three have to be inert. + body := `{"api_version":"v0","backend":"dolt","bd_version":"9.9.9",` + + `"beads_dir":"/srv/repo/.beads","capabilities":["issues.list","issues.get"],` + + `"database":"beads","dolt_mode":"embedded","project_id":"proj-1",` + + `"repo_root":"/srv/repo","schema_version":9001,` + + `"replication_lag_ms":12,"tenant":{"id":"acme","tier":"gold"},"features":["wisps","convoys"]}` + + c, _ := newTestClient(t, Options{ExpectProjectID: "proj-1"}, nil, serveContext(body)) + snap, err := c.Handshake(ctx(t)) + if err != nil { + t.Fatalf("Handshake against a futuristic v0 server: %v", err) + } + if snap.Context.BdVersion != "9.9.9" || snap.Context.SchemaVersion != 9001 { + t.Errorf("diagnostic members did not decode: %+v", snap.Context) + } + if !snap.Has("issues.list") || snap.Has("issues.update") { + t.Errorf("capabilities decoded wrong alongside unknown members: %v", snap.Capabilities()) + } + // And the list is still the contract: a token the futuristic server did NOT + // advertise refuses, however new the server claims to be. + if err := c.Preflight(ctx(t), OpUpdateIssue); !errors.Is(err, ErrCapabilityAbsent) { + t.Errorf("Preflight(updateIssue) = %v, want a capability refusal", err) + } +} + +func TestTheApiVersionGateRefusesEveryNonV0Spelling(t *testing.T) { + // The wire is versioned by PATH, so the gate is equality and not a range + // check: a "v0.1" is not a v0 this client can address, and a server that + // answers an empty api_version is not answering the question. + for _, version := range []string{"v1", "v2", "v0.1", "V0", "0", "", "v0 "} { + c, _ := newTestClient(t, Options{}, nil, serveContext(contextBody(version, "proj-1", "issues.list"))) + _, err := c.Handshake(ctx(t)) + if !errors.Is(err, ErrAPIVersion) { + t.Errorf("api_version %q: err = %v, want ErrAPIVersion", version, err) + continue + } + var mismatch *APIVersionError + if !errors.As(err, &mismatch) { + t.Errorf("api_version %q: err is %T, want *APIVersionError", version, err) + continue + } + if mismatch.Got != version || mismatch.Want != APIVersion { + t.Errorf("api_version %q: error carries got=%q want=%q", version, mismatch.Got, mismatch.Want) + } + } +} + +func TestTheApiVersionGateRunsBeforeTheIdentityGate(t *testing.T) { + // Ordering matters for the message, not for the outcome. A server on another + // major will also have a different project_id, and reporting THAT would send + // an operator to re-run bd connect against a server no bd connect can help + // them with. + c, _ := newTestClient(t, Options{ExpectProjectID: "proj-1"}, nil, + serveContext(contextBody("v1", "proj-2", "issues.list"))) + _, err := c.Handshake(ctx(t)) + if !errors.Is(err, ErrAPIVersion) { + t.Fatalf("err = %v, want the api_version gate to fire first", err) + } + if errors.Is(err, ErrProjectMismatch) { + t.Error("the identity gate fired on a server this client cannot address at all") + } +} + +func TestTheWrongServerDiagnosticNamesEveryFactD6Requires(t *testing.T) { + // D6's wrong-server checklist, whole: both project ids, plus the server's own + // database and repo_root. On a shared host running several bd serve + // processes, "the ids differ" identifies nothing — the database and the repo + // root are what say WHICH one answered. + c, _ := newTestClient(t, Options{ExpectProjectID: "proj-mine"}, nil, + serveContext(contextBody("v0", "proj-theirs", "issues.list"))) + _, err := c.Handshake(ctx(t)) + + var mismatch *ProjectMismatchError + if !errors.As(err, &mismatch) { + t.Fatalf("err is %T, want *ProjectMismatchError", err) + } + for field, got := range map[string]string{ + "Expected": mismatch.Expected, + "Got": mismatch.Got, + "Database": mismatch.Database, + "RepoRoot": mismatch.RepoRoot, + "ServerURL": mismatch.ServerURL, + } { + if got == "" { + t.Errorf("ProjectMismatchError.%s is empty", field) + } + } + msg := mismatch.Error() + for _, want := range []string{"proj-mine", "proj-theirs", "beads", "/srv/repo", "bd connect"} { + if !strings.Contains(msg, want) { + t.Errorf("Error() = %q, missing %q", msg, want) + } + } + + // A server that publishes neither diagnostic still produces a whole sentence + // rather than a dangling parenthetical — the members are optional on the + // wire, and a degraded diagnostic is not a broken one. + bare := `{"api_version":"v0","bd_version":"1.1.0","capabilities":[],"project_id":"proj-theirs"}` + c2, _ := newTestClient(t, Options{ExpectProjectID: "proj-mine"}, nil, serveContext(bare)) + _, err2 := c2.Handshake(ctx(t)) + if !errors.Is(err2, ErrProjectMismatch) { + t.Fatalf("err = %v, want ErrProjectMismatch", err2) + } + if strings.Contains(err2.Error(), `database ""`) { + t.Errorf("the degraded diagnostic printed empty members: %s", err2.Error()) + } +} + +func TestAnUnknownProblemCodeTakesTheDefaultBranchOfItsStatusClass(t *testing.T) { + // Older CLI, newer server, error path. Adding a problem code is not a + // breaking change on this wire, so a client that hard-failed on an unknown + // one would break against every server newer than itself. + // + // The unit-level probe of sentinelFor covers the table; this covers the + // crossing — a code arriving in a real body, over a real connection, in each + // status class that has a rule. + for _, tc := range []struct { + name string + status int + body string + want error + }{ + {"a 4xx the client has never heard of", 409, `{"status":409,"code":"tenant_quota_exceeded","detail":"quota"}`, ErrBadRequest}, + {"a 400 with a future reason", 400, `{"status":400,"code":"malformed_expression","param":"q","reason":"unparseable"}`, ErrBadRequest}, + {"a 503 the client has never heard of", 503, `{"status":503,"code":"failing_over","detail":"draining"}`, ErrBusy}, + {"a 5xx the client has never heard of", 502, `{"status":502,"code":"upstream_gone"}`, ErrServerFault}, + {"a non-problem body from something that is not a bd serve", 404, `404`, ErrBadRequest}, + } { + t.Run(tc.name, func(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + problemJSON(w, tc.status, tc.body) + }) + err := c.Do(ctx(t), listIssues(), &struct{}{}) + if !errors.Is(err, tc.want) { + t.Fatalf("err = %v, want %v", err, tc.want) + } + // The envelope still arrives typed. A default-branched code is not a + // discarded response: request_id is what makes the server's log line + // findable, and it is the only handle on a code nobody here knows. + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if problem.Status != tc.status { + t.Errorf("Status = %d, want %d", problem.Status, tc.status) + } + }) + } +} + +func TestAnUnknownResponseMemberDoesNotBreakADecode(t *testing.T) { + // The same additivity on the success path. A server that grew a member is a + // server this client keeps reading; refusing the decode would make every + // forward-compatible response a hard failure. + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + _, _ = io.WriteString(w, `{"status":"ok","uptime_s":41,"leader":"node-3"}`) + }) + if err := c.Health(ctx(t)); err != nil { + t.Fatalf("Health against a server with extra members: %v", err) + } +} + +func TestTheUnknownParameterSignalCrossesTheWireAndRendersCaseThree(t *testing.T) { + // The whole case-3 mechanism, end to end: a newer CLI's parameter, an older + // server's 400, the typed members that survive it, and the reverse lookup + // through the encoder table that turns the parameter back into the flag the + // user typed. + // + // The encode import is test-only and deliberate. Production code in this + // package must not depend on the encoder — the transport does not know what + // a flag is — but the two halves of case 3 live in different packages, and + // something has to prove they meet. + for _, tc := range []struct { + param, want string + }{ + {"include_comments", `--include-comments is not supported by bd serve at %s (bd_version 1.1.0): parameter "include_comments" is unknown to the server`}, + {"include_dependents", `--include-dependents is not supported by bd serve at %s (bd_version 1.1.0): parameter "include_dependents" is unknown to the server`}, + {"exclude_type", `--exclude-type is not supported by bd serve at %s (bd_version 1.1.0): parameter "exclude_type" is unknown to the server`}, + {"has_metadata_key", `--has-metadata-key is not supported by bd serve at %s (bd_version 1.1.0): parameter "has_metadata_key" is unknown to the server`}, + } { + t.Run(tc.param, func(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == PathContext { + _, _ = io.WriteString(w, contextBody("v0", "proj-1", allTokens()...)) + return + } + problemJSON(w, 400, `{"status":400,"code":"invalid_argument","param":"`+tc.param+ + `","reason":"unknown_parameter","detail":"unknown parameter \"`+tc.param+`\""}`) + }) + + err := c.Do(ctx(t), listIssues(), &struct{}{}) + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + // The reason is what separates skew from a bad value: both ride + // invalid_argument, and their recoveries are opposite. + if problem.Reason != encode.UnknownParameterReason { + t.Fatalf("reason = %q, want %q", problem.Reason, encode.UnknownParameterReason) + } + if !errors.Is(err, issueops.ErrValidation) { + t.Error("the skew signal did not classify as a validation refusal") + } + + snap, err := c.Handshake(ctx(t)) + if err != nil { + t.Fatalf("Handshake: %v", err) + } + got := encode.UnknownParameterRefusal(problem.Param, problem.ServerURL, snap.Context.BdVersion) + want := strings.Replace(tc.want, "%s", problem.ServerURL, 1) + if got != want { + t.Errorf("case-3 refusal =\n%s\nwant\n%s", got, want) + } + // D7's standing rule for every refusal text: the user's vocabulary, + // never the client's internals. + if strings.Contains(got, "listIssues") || strings.Contains(got, "ListRequest") { + t.Errorf("the refusal leaked client vocabulary: %s", got) + } + }) + } +} + +func TestAnInvalidValueIsNotReadAsVersionSkew(t *testing.T) { + // The converse of the case above, and the reason the reason member exists. + // `invalid_value` on a parameter the server DOES know means the argument is + // wrong; rendering it as case 3 would tell a user to upgrade a server that is + // working correctly. + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + problemJSON(w, 400, `{"status":400,"code":"invalid_argument","param":"sort","reason":"invalid_value","detail":"unknown sort key"}`) + }) + err := c.Do(ctx(t), listIssues(), &struct{}{}) + var problem *ProblemError + if !errors.As(err, &problem) { + t.Fatalf("err is %T, want *ProblemError", err) + } + if problem.Reason == encode.UnknownParameterReason { + t.Fatalf("reason = %q; a bad value must not classify as skew", problem.Reason) + } +} + +// TestNoFeatureBranchesOnBdVersionOrSchemaVersion is D6's other rule, and the +// only one in this package that no behavioral test can reach. +// +// "Clients never branch on bd_version for features (the capability list is the +// contract; bd_version appears only in error text) and never on schema_version +// (documented diagnostic-only)". A violation would not fail any test here — it +// would work perfectly against every server in the fixture cache and then +// mis-gate the first server whose version string is shaped differently, which is +// exactly the class of bug version strings are famous for. +// +// So the gate is structural, and it turns on a distinction the rule itself +// makes: the members may be DISPLAYED — copied into an error, formatted into a +// message, guarded by "do I have one to show" — but never used to DECIDE. +// Displaying is not branching, which is what keeps the refusal-UX layer's +// `bd_version` text legal while a version comparison stays fatal. +// +// SCOPE. Three groups, because the members travel: the wire package that decodes +// them, the store package that copies them into refusals, and the cmd/bd files +// that consume a handshake. Sweeping only this package is what an earlier +// revision did, and it left the store package — which reads snap.BdVersion in +// production — completely unguarded while the role wave was about to land more +// snapshot-consuming code exactly there. +func TestNoFeatureBranchesOnBdVersionOrSchemaVersion(t *testing.T) { + fset := token.NewFileSet() + total := 0 + + for _, scope := range diagnosticSweepScopes() { + files, sawAnyFile := parseSweepScope(t, fset, scope) + if len(files) == 0 { + if scope.only != nil && sawAnyFile { + // The directory parsed real, non-test .go files, but none of + // them import the http client yet. That is the honest state + // of cmd/bd during S2: the store/dial wiring that makes + // cmd/bd a consumer is deferred to S3 (see the httpclient + // lift commit's message). It is not the "path moved" failure + // this gate otherwise guards — that failure mode is an empty + // directory read, handled below — so there is nothing to + // sweep here yet and that is fine. + // + // TODO(S3): once cmd/bd wires the store/dial seam to this + // client, this branch's cmd/bd scope stops being vacuous — + // drop this `continue` (or tighten it) so the sweep actually + // covers cmd/bd's own bd_version/schema_version reads instead + // of silently passing on an empty intersection. + continue + } + // A relative path that stopped resolving is the failure mode this + // gate cannot survive quietly: zero files walk clean. + t.Errorf("%s (%s): swept no files; the scope's path has moved and this gate went vacuous", scope.label, scope.dir) + continue + } + for _, file := range files { + total += checkDiagnosticUse(t, fset, file) + } + } + + // And the sweep has to have SEEN the members somewhere, or a rename would + // leave every scope green by matching nothing at all. + if total == 0 { + t.Fatal("the sweep found no reference to BdVersion or SchemaVersion anywhere; " + + "either the members were renamed or the scopes no longer contain the client") + } +} + +type sweepScope struct { + label string + dir string + // only, when set, keeps just the files this scope cares about. + only func(*ast.File) bool +} + +// diagnosticSweepScopes names every place a handshake member can be read. +// +// The cmd/bd entry is selected by IMPORT rather than by filename. The rule is +// about code that consumes a handshake, and "imports the http client" is exactly +// that set — mechanically determined, so a file the refusal-UX layer adds +// tomorrow is swept the day it reaches for the store. Selecting by filename +// prefix would miss it, and sweeping all of cmd/bd would drag in bd's own +// version tracking, which branches on bd's version because that is its entire +// job. +func diagnosticSweepScopes() []sweepScope { + return []sweepScope{ + {label: "the wire transport", dir: "."}, + {label: "the http store", dir: ".."}, + { + label: "cmd/bd's http-client consumers", + dir: filepath.Join("..", "..", "..", "cmd", "bd"), + only: importsHTTPClient, + }, + } +} + +func importsHTTPClient(file *ast.File) bool { + for _, spec := range file.Imports { + path := strings.Trim(spec.Path.Value, `"`) + if strings.Contains(path, "internal/httpclient") { + return true + } + } + return false +} + +// parseSweepScope parses every non-test .go file in scope.dir and applies +// scope.only. It also reports sawAnyFile: whether the directory yielded any +// parseable file at all BEFORE the only filter ran, so the caller can tell +// "the path is broken" (sawAnyFile false) apart from "the path is fine but +// nothing here is a consumer yet" (sawAnyFile true, out empty). +func parseSweepScope(t *testing.T, fset *token.FileSet, scope sweepScope) (out map[string]*ast.File, sawAnyFile bool) { + t.Helper() + // Build constraints are deliberately not honored: this test is untagged, and + // the enterprise-only files are precisely the ones that consume a handshake. + // Parsing is text, so they are swept either way. + pkgs, err := parser.ParseDir(fset, scope.dir, func(fi os.FileInfo) bool { + return !strings.HasSuffix(fi.Name(), "_test.go") + }, 0) + if err != nil { + t.Fatalf("%s (%s): parse: %v", scope.label, scope.dir, err) + } + out = map[string]*ast.File{} + for _, pkg := range pkgs { + for name, file := range pkg.Files { + sawAnyFile = true + if scope.only != nil && !scope.only(file) { + continue + } + out[name] = file + } + } + return out, sawAnyFile +} + +// isDiagnosticRef matches a read of either member. +// +// Selector and bare identifier alike, because the value gets passed around: the +// connect report takes it as a plain `bdVersion string` parameter, and a +// comparison there is the same mistake as a comparison on the field. Exact, +// case-insensitive name equality keeps JSONSchemaVersion, LastBdVersion and +// trackBdVersion out of it. +func isDiagnosticRef(n ast.Node) bool { + name := "" + switch ref := n.(type) { + case *ast.SelectorExpr: + name = ref.Sel.Name + case *ast.Ident: + name = ref.Name + default: + return false + } + switch strings.ToLower(name) { + case "bdversion", "schemaversion": + return true + } + return false +} + +func diagnosticRefs(n ast.Node) []ast.Node { + var found []ast.Node + ast.Inspect(n, func(inner ast.Node) bool { + if inner == nil { + return false + } + if isDiagnosticRef(inner) { + found = append(found, inner) + // Do not descend: the selector's own X is not a second reference. + return false + } + return true + }) + return found +} + +// isPresenceGuard reports a comparison that asks "is there one to show" rather +// than "which one is it". +// +// `e.BdVersion != ""` is how a renderer omits a version it does not have, and +// D6's rule is about deciding on the VALUE. Allowing the zero comparison is what +// lets the refusal-UX layer print the version without this gate calling it a +// feature branch; anything compared against an actual version is still fatal. +func isPresenceGuard(expr *ast.BinaryExpr) bool { + if expr.Op != token.EQL && expr.Op != token.NEQ { + return false + } + other := func(side ast.Expr) bool { + lit, ok := side.(*ast.BasicLit) + if !ok { + return false + } + return lit.Value == `""` || lit.Value == "0" + } + if len(diagnosticRefs(expr.X)) > 0 && other(expr.Y) { + return true + } + return len(diagnosticRefs(expr.Y)) > 0 && other(expr.X) +} + +func checkDiagnosticUse(t *testing.T, fset *token.FileSet, file *ast.File) int { + t.Helper() + + // Every reference that sits inside an allowed presence guard, so the + // condition check below can tell one from a real branch. + allowed := map[ast.Node]bool{} + ast.Inspect(file, func(n ast.Node) bool { + if expr, ok := n.(*ast.BinaryExpr); ok && isPresenceGuard(expr) { + for _, ref := range diagnosticRefs(expr) { + allowed[ref] = true + } + } + return true + }) + + report := func(pos token.Pos, what string) { + t.Errorf("%s: %s (D6: the capability list is the feature contract; these members are diagnostic-only)", + fset.Position(pos), what) + } + + ast.Inspect(file, func(n ast.Node) bool { + switch stmt := n.(type) { + case *ast.BinaryExpr: + switch stmt.Op { + case token.EQL, token.NEQ, token.LSS, token.GTR, token.LEQ, token.GEQ: + if len(diagnosticRefs(stmt)) > 0 && !isPresenceGuard(stmt) { + report(stmt.Pos(), "a comparison decides on a diagnostic-only member; a version string is not a capability check") + } + } + case *ast.IfStmt: + for _, ref := range diagnosticRefs(stmt.Cond) { + if !allowed[ref] { + report(stmt.Pos(), "an `if` branches on a diagnostic-only member") + break + } + } + case *ast.SwitchStmt: + if stmt.Tag != nil && len(diagnosticRefs(stmt.Tag)) > 0 { + report(stmt.Pos(), "a `switch` dispatches on a diagnostic-only member") + } + } + return true + }) + + return len(diagnosticRefs(file)) +} diff --git a/internal/httpclient/wire/stream.go b/internal/httpclient/wire/stream.go new file mode 100644 index 000000000..bf6fb3cbb --- /dev/null +++ b/internal/httpclient/wire/stream.go @@ -0,0 +1,521 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/stream.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "bufio" + "bytes" + "context" + "errors" + "fmt" + "io" + "mime" + "net/http" + "net/url" + "strconv" + "sync/atomic" + "time" +) + +// The STREAMING door, the one operation on this surface that cannot go through +// Do. +// +// Do reads the whole body under a per-request timeout so the 401 retry can +// replay a []byte, and both are exactly wrong for a stream: GET +// /v0/beads/events:watch holds a text/event-stream open for as long as the +// consumer wants it, so there is no whole body to read and no fixed timeout to +// read it under. This file is the second door — its own http client with no +// timeout, an SSE parser over the live body, and an idle deadline standing in +// for the timeout Do relies on. +// +// THE CONNECT HALF IS Do's, though, and deliberately so. Everything up to the +// 200 and its text/event-stream header — the 400s, the 409, the 410, the 503 — +// is an ordinary problem response the server sends BEFORE a single stream byte +// (internal/httpapi/events_watch.go), so this door reuses roundTrip's own +// pieces: the shared request stamp, redirectRefused, the bounded error-body +// read, mapProblem. Only once the stream is open does the vocabulary become +// SSE. + +// watchIdleTimeout is how long a stream may go silent before this client +// declares it dead and fails loudly. +// +// The server heartbeats a comment line every ~20s (internal/httpapi's +// watchHeartbeat) precisely so an idle connection through a NAT or a proxy keeps +// producing bytes; three heartbeats of total silence is a connection that has +// half-died without either end being told — the classic way a stream stops +// delivering while both sides believe it is up. Sixty seconds is long enough +// that one missed heartbeat is not mistaken for a dead peer and short enough +// that a consumer's stall is measured in a minute rather than in hours. +// +// It is a var rather than a const so the stream tests can drive the timeout in +// milliseconds instead of waiting a real minute for it. +var watchIdleTimeout = 60 * time.Second + +// truncatedEventName is the ONE named event this stream emits: a prune that +// raced an open stream, carrying the same problem document the connect-time 410 +// would have. Every other event is unnamed — the default `message` type — which +// is what lets a consumer read "an event I do not recognize" as "stop". +const truncatedEventName = "truncated" + +// StreamEvent is one dispatched SSE event: a journal record (unnamed) or the +// `truncated` event (named), with the record's seq and the server's most recent +// reconnection advisory. +type StreamEvent struct { + // Seq is the record's sequence number, from the `id:` field. It is the same + // value the record's own JSON carries; a consumer that resumes uses it as + // the next `since`. + Seq int64 + // Name is "" for a record and truncatedEventName for the truncation event. + Name string + // Data is the event's `data:` payload, multi-line values joined with '\n'. + // For a record it is the EventRecord JSON; for the truncation it is the + // problem document. + Data []byte + // Retry is the server's most recent `retry:` advisory, or 0 if none has + // arrived. A consumer that reconnects honors it as the delay before doing so. + Retry time.Duration +} + +// EventStream is one open text/event-stream response, parsed one dispatched +// event at a time. +// +// It is NOT safe for concurrent use: Next reads and parses on the caller's +// goroutine, which is exactly the single-goroutine delivery the Watcher role +// promises. Close is the only method safe to call from another goroutine, to +// abort a blocked Next. +type EventStream struct { + op string + serverURL string + body io.ReadCloser + reader *bufio.Reader + maxBytes int64 + + // parentCtx is the CALLER's context, read only to classify a read failure: + // a read that failed because the caller canceled is theirs, one that failed + // because the idle timer canceled the request is this stream's. + parentCtx context.Context + // cancel cancels the REQUEST's derived context, which is what the idle timer + // and Close both pull to unblock a parked read. + cancel context.CancelFunc + + idledOut atomic.Bool + retry time.Duration + // closed is atomic to honor the documented cross-goroutine idempotency of + // Close: the flag is read and set from any goroutine racing an abort against + // the caller's own Close, so it matches idledOut rather than trusting a plain + // bool the race detector would flag. + closed atomic.Bool +} + +// WatchEvents opens the journal stream from since, in ONE connect. +// +// It builds the request exactly as roundTrip does — the shared stamp, so the +// Bd-Project-Id the workspace pinned rides this request like every other — with +// Accept: text/event-stream and since as a required query parameter on every +// connect. It sends NO Last-Event-ID: this client rebuilds `since` on every +// reconnect from the seq it last delivered, which the server treats as +// equivalent to the header a browser's EventSource would resend. +// +// A 401 is retried once, exactly as Do retries it: one credential refresh and +// one reconnect, because a GET carries no body to replay and the server's token +// re-read is on a ~1s gate. Everything else the server can answer before the +// stream opens comes back as the typed error roundTrip would have produced. +func (c *Client) WatchEvents(ctx context.Context, since int64) (*EventStream, error) { + q := url.Values{} + // FormatInt, not Itoa: since is an int64 and a resume can sit anywhere in the + // range, so a 32-bit conversion would silently wrap a large checkpoint. + q.Set("since", strconv.FormatInt(since, 10)) + u, err := c.resolve(PathEventsWatch, q) + if err != nil { + return nil, fmt.Errorf("%s: %w", OpWatchEvents, err) + } + + hc := c.streamClient() + + stream, err := c.dialStream(ctx, hc, u) + if err != nil && c.creds != nil { + var prob *ProblemError + if errors.As(err, &prob) && prob.Status == http.StatusUnauthorized { + retry, rerr := c.creds.Refresh(ctx) + if rerr != nil { + // Fail closed, exactly as Do does: a credential source that errored + // is not a license to send the stale one again. + return nil, fmt.Errorf("%s: refreshing the credential for bd serve at %s: %w", OpWatchEvents, c.base.Redacted(), rerr) + } + if retry { + stream, err = c.dialStream(ctx, hc, u) + } + } + } + return stream, err +} + +// streamClient clones the client's http.Client with the timeout removed. +// +// A stream has no bounded length, so the 60-second per-request timeout that +// makes Do's whole-body read safe would kill every stream at one minute. The +// clone preserves Transport and the forced CheckRedirect — a redirect on a +// bearer connection is refused, never followed — and swaps only Timeout, so the +// stream's liveness is the idle deadline's job and its cancellation is the +// caller's context. +func (c *Client) streamClient() *http.Client { + hc := *c.hc + hc.Timeout = 0 + return &hc +} + +// dialStream performs one connect and returns either a live stream or the typed +// error the server answered with before the stream opened. +func (c *Client) dialStream(ctx context.Context, hc *http.Client, u *url.URL) (*EventStream, error) { + streamCtx, cancel := context.WithCancel(ctx) + + req, err := http.NewRequestWithContext(streamCtx, http.MethodGet, u.String(), nil) + if err != nil { + cancel() + return nil, fmt.Errorf("%s: %w", OpWatchEvents, err) + } + req.Header.Set("Accept", "text/event-stream") + if err := c.stampRequest(streamCtx, OpWatchEvents, req); err != nil { + cancel() + return nil, err + } + + //nolint:gosec // G704: the URL is the workspace's configured server; dialing it IS the feature. + resp, err := hc.Do(req) + if err != nil { + cancel() + return nil, &ConnectError{Op: OpWatchEvents, ServerURL: c.base.Redacted(), Err: err} + } + + if resp.StatusCode >= 300 && resp.StatusCode < 400 { + _ = resp.Body.Close() + cancel() + return nil, redirectRefused(OpWatchEvents, c.base.Redacted(), resp) + } + + if resp.StatusCode < 200 || resp.StatusCode >= 300 { + // The connect-time refusals are ordinary problem responses with a bounded + // body, so this reads and maps them exactly as roundTrip does. + raw, _ := io.ReadAll(io.LimitReader(resp.Body, c.maxBytes+1)) + _ = resp.Body.Close() + cancel() + prob := mapProblem(c.target(Request{Op: OpWatchEvents}), resp.StatusCode, resp.Header, raw, c.maxRetry) + if resp.StatusCode == http.StatusUnauthorized { + prob.CredentialSource = credentialSource(c.creds) + } + return nil, prob + } + + // A 2xx that is not text/event-stream is not a bd serve stream — a proxy, a + // gateway, or a different server answering on the port. Refused rather than + // parsed, so a consumer does not sit on a connection that will never frame a + // record. + if !isEventStream(resp.Header.Get("Content-Type")) { + _ = resp.Body.Close() + cancel() + return nil, &NotEventStreamError{Op: OpWatchEvents, ServerURL: c.base.Redacted(), ContentType: resp.Header.Get("Content-Type")} + } + + return &EventStream{ + op: OpWatchEvents, + serverURL: c.base.Redacted(), + body: resp.Body, + reader: bufio.NewReader(resp.Body), + maxBytes: c.maxBytes, + parentCtx: ctx, + cancel: cancel, + }, nil +} + +// isEventStream reports whether a Content-Type names an SSE body, ignoring the +// charset parameter the server sends with it. +func isEventStream(contentType string) bool { + mediaType, _, err := mime.ParseMediaType(contentType) + return err == nil && mediaType == "text/event-stream" +} + +// Retry is the server's most recent reconnection advisory, or 0. The Watcher +// role reads it after a stream drops to decide how long to wait before +// reconnecting. +func (s *EventStream) Retry() time.Duration { return s.retry } + +// Close aborts a blocked Next and releases the connection. It is idempotent and +// safe to call from another goroutine. +// +// The one-shot is a CompareAndSwap, not a read-then-write, so two goroutines that +// race Close — the Watcher role closing a drained stream while an idle timer's +// abort path is unwinding, say — cancel the context and close the body exactly +// once between them, which is what the idempotency contract above promises. +func (s *EventStream) Close() { + if !s.closed.CompareAndSwap(false, true) { + return + } + s.cancel() + _ = s.body.Close() +} + +// Next reads and returns the next dispatched event. +// +// It loops over SSE lines, accumulating one event's fields until a blank line +// dispatches it. Comment lines (heartbeats) and frames that carry only a +// `retry:` or an `id:` — which SSE dispatches as no message — are absorbed here +// so the caller sees only events that carry data. A read that outlives the idle +// deadline, that the caller cancels, or that the connection drops surfaces as an +// error; a per-event size cap refuses a frame larger than the client's bound. +func (s *EventStream) Next() (StreamEvent, error) { + var ev sseEvent + for { + line, err := s.readLine() + if err != nil { + return StreamEvent{}, s.classifyReadErr(err) + } + line = trimLineEnd(line) + + if len(line) == 0 { + // The blank line dispatches. A frame with no data carries only a retry + // advisory or an id and fires no message in SSE, so it is folded into + // the next event rather than returned. + if len(ev.data) == 0 { + ev = sseEvent{} + continue + } + return StreamEvent{Seq: ev.seq, Name: ev.name, Data: ev.data, Retry: s.retry}, nil + } + + if line[0] == ':' { + // A comment — the heartbeat. It carries nothing, and reading it already + // reset the idle deadline, which is its whole purpose. + continue + } + + field, value := splitSSEField(line) + if err := s.applyField(&ev, field, value); err != nil { + return StreamEvent{}, err + } + } +} + +// sseEvent is one event's fields, accumulated by Next until a blank line +// dispatches them. +type sseEvent struct { + data []byte + name string + seq int64 + // size is every field value read for this event, which is what the + // per-event cap measures. + size int64 +} + +// applyField folds one SSE field line into ev, refusing the event once its +// values pass the per-event cap. Every field's value counts against the cap, +// not just data's. retry is the one field that is not the event's: it is a +// stream-wide advisory, so it lands on s. +func (s *EventStream) applyField(ev *sseEvent, field, value string) error { + ev.size += int64(len(value)) + if ev.size > s.maxBytes { + return s.tooLarge() + } + switch field { + case "event": + ev.name = value + case "data": + if len(ev.data) > 0 { + ev.data = append(ev.data, '\n') + } + ev.data = append(ev.data, value...) + if int64(len(ev.data)) > s.maxBytes { + return s.tooLarge() + } + case "id": + if n, perr := strconv.ParseInt(value, 10, 64); perr == nil { + ev.seq = n + } + case "retry": + if ms, perr := strconv.ParseInt(value, 10, 64); perr == nil && ms >= 0 { + s.retry = time.Duration(ms) * time.Millisecond + } + } + return nil +} + +// readLine reads one SSE line, bounded by the per-event cap and armed with the +// idle deadline. +// +// The read is wrapped in a fresh time.AfterFunc so that no bytes for +// watchIdleTimeout cancels the request's derived context, which unblocks the +// parked read; the timer is stopped the instant the line returns, so a stream +// delivering normally never trips it. ReadSlice rather than ReadString keeps a +// pathological line with no newline from growing an unbounded buffer: it is read +// in fragments and refused the moment the accumulated bytes pass the cap. +// +// The deadline is an INTER-BYTE idle, not a per-line transfer budget: it is +// re-armed on every fragment that made byte progress, so a large single line +// that keeps moving — arriving across many ErrBufferFull fragments — never idles +// out while bytes flow, and only a stream that goes genuinely silent for +// watchIdleTimeout between fragments does. +func (s *EventStream) readLine() ([]byte, error) { + timer := time.AfterFunc(watchIdleTimeout, func() { + s.idledOut.Store(true) + s.cancel() + }) + defer timer.Stop() + + var buf []byte + for { + frag, err := s.reader.ReadSlice('\n') + if len(frag) > 0 { + // Byte progress: this fragment is not silence, so re-arm the deadline to + // measure the gap until the NEXT bytes rather than the whole transfer. + timer.Reset(watchIdleTimeout) + } + buf = append(buf, frag...) + if int64(len(buf)) > s.maxBytes { + return nil, s.tooLarge() + } + if errors.Is(err, bufio.ErrBufferFull) { + continue + } + if err != nil { + if len(buf) > 0 && errors.Is(err, io.EOF) { + // A final line with no trailing newline: return it, and let the + // next read report the EOF. + return buf, nil + } + return buf, err + } + return buf, nil + } +} + +// classifyReadErr turns a read failure into the error the caller should see. +// +// The order is deliberate: the caller's own cancellation wins, because a stream +// the caller stopped is not a drop to reconnect from. Then an idle timeout, +// which canceled the request but is this client's decision and not the +// caller's. Everything else — an EOF, a reset — is the connection dropping, +// which the Watcher role reconnects from. +func (s *EventStream) classifyReadErr(err error) error { + if s.parentCtx.Err() != nil { + return s.parentCtx.Err() + } + if s.idledOut.Load() { + return &StreamIdleError{Op: s.op, ServerURL: s.serverURL, Idle: watchIdleTimeout} + } + return err +} + +func (s *EventStream) tooLarge() error { + return &StreamEventTooLargeError{Op: s.op, ServerURL: s.serverURL, Limit: s.maxBytes} +} + +// trimLineEnd strips the trailing newline and an optional preceding carriage +// return, so a server that framed with CRLF parses like one that framed with LF. +func trimLineEnd(line []byte) []byte { + line = bytes.TrimSuffix(line, []byte("\n")) + line = bytes.TrimSuffix(line, []byte("\r")) + return line +} + +// splitSSEField splits an SSE line into its field name and value, dropping one +// optional space after the colon. A line with no colon is a field with an empty +// value, per the SSE grammar. +func splitSSEField(line []byte) (string, string) { + i := bytes.IndexByte(line, ':') + if i < 0 { + return string(line), "" + } + value := line[i+1:] + if len(value) > 0 && value[0] == ' ' { + value = value[1:] + } + return string(line[:i]), string(value) +} + +// ErrNotEventStream reports that a 2xx answer to the watch connect was not a +// text/event-stream body, which means the URL does not point at a bd serve. +var ErrNotEventStream = errors.New("bd serve did not answer the watch with an event stream") + +// NotEventStreamError names the media type that came back instead, because on a +// shared host that is what says WHAT answered — a JSON API, an HTML login page, +// a proxy's own 200. +type NotEventStreamError struct { + Op string + ServerURL string + ContentType string +} + +func (e *NotEventStreamError) Error() string { + if e.ContentType == "" { + return fmt.Sprintf("%s: bd serve at %s answered the watch 2xx with no content type; a stream must be text/event-stream", e.Op, e.ServerURL) + } + return fmt.Sprintf("%s: bd serve at %s answered the watch with content type %q, not text/event-stream (the URL does not point at a bd serve)", e.Op, e.ServerURL, e.ContentType) +} + +func (e *NotEventStreamError) Unwrap() error { return ErrNotEventStream } + +// ErrStreamIdle reports that an open stream went silent past the idle deadline. +var ErrStreamIdle = errors.New("bd serve stream went silent") + +// StreamIdleError is a stream that produced no bytes — not even a heartbeat — +// for watchIdleTimeout. The connection is treated as dead: the recovery is a +// reconnect, which the Watcher role performs from the last delivered seq. +type StreamIdleError struct { + Op string + ServerURL string + Idle time.Duration +} + +func (e *StreamIdleError) Error() string { + return fmt.Sprintf("%s: bd serve at %s sent no data for %s; the stream is silent past three heartbeats and treated as dead", e.Op, e.ServerURL, e.Idle) +} + +func (e *StreamIdleError) Unwrap() error { return ErrStreamIdle } + +// ErrStreamPoisoned reports that an open stream carried a payload this client +// cannot follow, discovered MID-STREAM: a record whose JSON will not decode, or +// an event past the per-event bound. It is a PROTOCOL fault, not a transport +// drop — the resume checkpoint would re-fetch the same poisoned record on every +// reconnect — so the Watcher role STOPS on it rather than reconnecting into an +// unbounded loop pinned on the same bad record. A consumer dispatches on it to +// tell a poisoned feed from a transient disconnect it never sees. +var ErrStreamPoisoned = errors.New("bd serve stream carried a record this client cannot follow") + +// StreamEventTooLargeError is one SSE event past the client's per-event bound. +// It reuses ErrResponseTooLarge because the recovery is the same — raise the cap, +// or recognize that the far likelier cause is a URL that is not a bd serve — and +// the per-event bound is what the whole-body cap is on the paged reads. +type StreamEventTooLargeError struct { + Op string + ServerURL string + Limit int64 +} + +func (e *StreamEventTooLargeError) Error() string { + return fmt.Sprintf("%s: a single event from bd serve at %s exceeds the %d-byte limit", e.Op, e.ServerURL, e.Limit) +} + +func (e *StreamEventTooLargeError) Unwrap() error { return ErrResponseTooLarge } + +// NewEventStreamReader wraps an already-open SSE body for a backend test that +// feeds canned frames without standing up an HTTP server. +// +// Production opens a stream through WatchEvents, which owns the connect and the +// idle-deadline plumbing; this constructor is the seam a stub-tier test uses to +// drive the Watcher role's reconnect and delivery logic against scripted bytes. +// The parent context is Background — a byte reader never blocks, so the idle +// timer never fires — and Close still closes the reader the test handed in. +func NewEventStreamReader(body io.ReadCloser, maxBytes int64) *EventStream { + _, cancel := context.WithCancel(context.Background()) + if maxBytes <= 0 { + maxBytes = DefaultMaxResponseBytes + } + return &EventStream{ + op: OpWatchEvents, + serverURL: "test", + body: body, + reader: bufio.NewReader(body), + maxBytes: maxBytes, + parentCtx: context.Background(), + cancel: cancel, + } +} diff --git a/internal/httpclient/wire/stream_test.go b/internal/httpclient/wire/stream_test.go new file mode 100644 index 000000000..961a9fec1 --- /dev/null +++ b/internal/httpclient/wire/stream_test.go @@ -0,0 +1,386 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/stream_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "encoding/json" + "errors" + "io" + "net/http" + "strings" + "sync" + "sync/atomic" + "testing" + "time" +) + +// The streaming door's branch matrix, in the same httptest idiom the rest of +// this package uses: canned SSE bytes, no bd serve, no Dolt. The connect half +// reuses roundTrip's own machinery, so what is genuinely new here is the SSE +// parser and the idle deadline — and both are exercised against frames a real +// server writes (internal/httpapi/events_watch.go) and against the malformed +// ones only a doctored server can send. + +// writeSSEHeader opens a text/event-stream response and returns its flusher. +func writeSSEHeader(t *testing.T, w http.ResponseWriter) http.Flusher { + t.Helper() + fl, ok := w.(http.Flusher) + if !ok { + t.Fatal("the test server's ResponseWriter cannot flush; a stream cannot be tested") + } + w.Header().Set("Content-Type", "text/event-stream; charset=utf-8") + w.WriteHeader(http.StatusOK) + fl.Flush() + return fl +} + +func writeSSE(t *testing.T, w http.ResponseWriter, body string) { + t.Helper() + fl := writeSSEHeader(t, w) + _, _ = io.WriteString(w, body) + fl.Flush() +} + +func TestWatchParsesRecordsMultiLineDataAndComments(t *testing.T) { + // One connection carrying every frame shape the server emits: the opening + // retry advisory, a heartbeat comment, a record, and a record whose payload + // arrives across two data lines. The parser has to skip the first two, honor + // the retry, and join the multi-line data with a single newline. + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + writeSSE(t, w, + "retry: 3000\n\n"+ + ": heartbeat\n\n"+ + "id: 5\ndata: {\"seq\":5}\n\n"+ + "id: 6\ndata: line1\ndata: line2\n\n") + }) + + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents: %v", err) + } + defer stream.Close() + + first, err := stream.Next() + if err != nil { + t.Fatalf("first Next: %v", err) + } + if first.Seq != 5 || string(first.Data) != `{"seq":5}` { + t.Errorf("first event = {seq:%d data:%q}, want {5 {\"seq\":5}}", first.Seq, first.Data) + } + if first.Retry != 3*time.Second { + t.Errorf("retry = %s, want the advertised 3s: a `retry:` frame carries the reconnection delay", first.Retry) + } + + second, err := stream.Next() + if err != nil { + t.Fatalf("second Next: %v", err) + } + if second.Seq != 6 || string(second.Data) != "line1\nline2" { + t.Errorf("second event = {seq:%d data:%q}, want {6 line1\\nline2}: multi-line data joins with a newline", second.Seq, second.Data) + } + + if _, err := stream.Next(); err == nil { + t.Error("a closed stream's Next returned no error") + } +} + +func TestWatchIdleTimeoutFiresAfterThreeHeartbeatsOfSilence(t *testing.T) { + restore := watchIdleTimeout + watchIdleTimeout = 50 * time.Millisecond + t.Cleanup(func() { watchIdleTimeout = restore }) + + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + writeSSE(t, w, "retry: 3000\n\n") + // Go silent: no records, no heartbeats. A half-dead NAT looks exactly like + // this. Hold the connection until the client's idle timer cancels it. + <-r.Context().Done() + }) + + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents: %v", err) + } + defer stream.Close() + + done := make(chan error, 1) + go func() { + _, nerr := stream.Next() + done <- nerr + }() + select { + case err := <-done: + if !errors.Is(err, ErrStreamIdle) { + t.Errorf("a silent stream's Next = %v, want ErrStreamIdle", err) + } + case <-time.After(5 * time.Second): + t.Fatal("Next did not return on a silent stream; the idle deadline never fired") + } +} + +func TestWatchIdleDeadlineIsInterByteNotPerLine(t *testing.T) { + restore := watchIdleTimeout + watchIdleTimeout = 300 * time.Millisecond + t.Cleanup(func() { watchIdleTimeout = restore }) + + // One large single data line, delivered in fragments each well within the idle + // window but whose TOTAL transfer exceeds it. A per-line transfer deadline + // would kill this actively-moving stream at 300ms; an inter-byte idle deadline, + // re-armed on every fragment that made byte progress, must let it complete. + // The chunk is larger than the parser's read buffer so each one forces an + // ErrBufferFull fragment — the exact point the deadline has to re-arm. + const chunks = 8 + const chunkSize = 8192 + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + fl := writeSSEHeader(t, w) + _, _ = io.WriteString(w, "id: 1\ndata: ") + fl.Flush() + payload := strings.Repeat("x", chunkSize) + for i := 0; i < chunks; i++ { + time.Sleep(50 * time.Millisecond) + _, _ = io.WriteString(w, payload) + fl.Flush() + } + _, _ = io.WriteString(w, "\n\n") + fl.Flush() + }) + + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents: %v", err) + } + defer stream.Close() + + type result struct { + ev StreamEvent + err error + } + done := make(chan result, 1) + go func() { + ev, nerr := stream.Next() + done <- result{ev, nerr} + }() + select { + case got := <-done: + if got.err != nil { + t.Fatalf("a slow-but-progressing large line = %v, want it delivered: the idle deadline must be inter-byte, not a per-line transfer budget", got.err) + } + if want := chunks * chunkSize; len(got.ev.Data) != want { + t.Errorf("delivered %d data bytes, want %d: the whole progressing line", len(got.ev.Data), want) + } + case <-time.After(5 * time.Second): + t.Fatal("Next never returned on a progressing stream") + } +} + +func TestStreamCloseIsIdempotentUnderConcurrency(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, r *http.Request) { + writeSSE(t, w, "id: 1\ndata: {\"seq\":1}\n\n") + // Hold the connection open so Close has a live body to close and a parked + // request to cancel; it unblocks when the client's Close cancels the request. + <-r.Context().Done() + }) + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents: %v", err) + } + + // Race many concurrent Close calls. The CAS one-shot must let exactly one win + // the cancel-and-close and no-op the rest, with no data race on the closed flag + // — the whole point of moving it off a plain bool. Run under -race to catch a + // regression. + const n = 16 + var wg sync.WaitGroup + wg.Add(n) + start := make(chan struct{}) + for i := 0; i < n; i++ { + go func() { + defer wg.Done() + <-start + stream.Close() + }() + } + close(start) + wg.Wait() + + // A further Close after they all return is still safe and still a no-op. + stream.Close() +} + +func TestWatchRefreshesTheCredentialOnceOnA401(t *testing.T) { + creds := &staticToken{tokens: []string{"stale", "fresh"}, retry: true} + var connects atomic.Int64 + c, _ := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, r *http.Request) { + n := connects.Add(1) + token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ") + if n == 1 { + if token != "stale" { + t.Errorf("first connect carried token %q, want the stale one", token) + } + problemJSON(w, http.StatusUnauthorized, `{"status":401,"code":"unauthenticated"}`) + return + } + if token != "fresh" { + t.Errorf("the retry carried token %q, want the refreshed one", token) + } + writeSSE(t, w, "id: 1\ndata: {\"seq\":1}\n\n") + }) + + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents after a 401 refresh: %v", err) + } + defer stream.Close() + + ev, err := stream.Next() + if err != nil { + t.Fatalf("Next after the refreshed reconnect: %v", err) + } + if ev.Seq != 1 { + t.Errorf("delivered seq %d, want 1", ev.Seq) + } + if creds.refreshN != 1 { + t.Errorf("refreshed %d times, want exactly one", creds.refreshN) + } + if got := connects.Load(); got != 2 { + t.Errorf("made %d connects, want 2 (the 401 and the refreshed retry)", got) + } +} + +func TestWatchDoesNotRefreshTwiceOnAPersistent401(t *testing.T) { + creds := &staticToken{tokens: []string{"a", "b"}, retry: true} + var connects atomic.Int64 + c, _ := newTestClient(t, Options{}, creds, func(w http.ResponseWriter, _ *http.Request) { + connects.Add(1) + problemJSON(w, http.StatusUnauthorized, `{"status":401,"code":"unauthenticated"}`) + }) + + _, err := c.WatchEvents(ctx(t), 0) + if !errors.Is(err, ErrUnauthenticated) { + t.Fatalf("a persistent 401 = %v, want ErrUnauthenticated", err) + } + if got := connects.Load(); got != 2 { + t.Errorf("made %d connects, want 2: the refresh is once and only once", got) + } +} + +func TestWatchRefusesARedirect(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Location", "https://elsewhere.example/login") + w.WriteHeader(http.StatusFound) + }) + _, err := c.WatchEvents(ctx(t), 0) + if !errors.Is(err, ErrRedirected) { + t.Fatalf("a redirected watch = %v, want ErrRedirected: a bd serve does not redirect", err) + } +} + +func TestWatchStampsTheProjectIDOnTheStreamRequest(t *testing.T) { + c, rec := newTestClient(t, Options{ExpectProjectID: "proj-1"}, nil, func(w http.ResponseWriter, r *http.Request) { + if got := r.Header.Get(ProjectIDHeader); got != "proj-1" { + t.Errorf("stream request carried %s=%q, want proj-1: events:watch is project-stamp-ENFORCED", ProjectIDHeader, got) + } + writeSSE(t, w, "id: 1\ndata: {}\n\n") + }) + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents: %v", err) + } + defer stream.Close() + if got := rec.at(t, 0).header.Get(ProjectIDHeader); got != "proj-1" { + t.Errorf("the recorded stream request carried %s=%q, want proj-1", ProjectIDHeader, got) + } + // And the required since parameter rides every connect. + if q := rec.at(t, 0).rawQuery; !strings.Contains(q, "since=0") { + t.Errorf("the stream request query was %q, want it to carry since=0", q) + } +} + +func TestWatchConnectRefusalsMapToTheThreeSentinels(t *testing.T) { + for _, tc := range []struct { + name string + status int + body string + want error + }{ + {"disabled", http.StatusConflict, `{"status":409,"code":"events_journal_disabled"}`, ErrEventsJournalDisabled}, + {"truncated", http.StatusGone, `{"status":410,"code":"events_journal_truncated","since":40,"floor":51,"head":99}`, ErrEventsJournalTruncated}, + {"saturated", http.StatusServiceUnavailable, `{"status":503,"code":"events_watch_saturated"}`, ErrEventsWatchSaturated}, + } { + t.Run(tc.name, func(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + problemJSON(w, tc.status, tc.body) + }) + _, err := c.WatchEvents(ctx(t), 0) + if !errors.Is(err, tc.want) { + t.Fatalf("connect %d = %v, want %v", tc.status, err, tc.want) + } + if tc.want == ErrEventsJournalTruncated { + var prob *ProblemError + if !errors.As(err, &prob) { + t.Fatalf("a 410 = %T, want *ProblemError carrying the window", err) + } + if prob.Since == nil || prob.Floor == nil || prob.Head == nil { + t.Errorf("the truncation carried window {since:%v floor:%v head:%v}, want all three", prob.Since, prob.Floor, prob.Head) + } + } + }) + } +} + +func TestWatchTruncatedEventSurfacesItsNameAndProblem(t *testing.T) { + problem := `{"code":"events_journal_truncated","since":40,"floor":51,"head":99}` + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + writeSSE(t, w, "retry: 60000\n\nevent: truncated\ndata: "+problem+"\n\n") + }) + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents: %v", err) + } + defer stream.Close() + + ev, err := stream.Next() + if err != nil { + t.Fatalf("Next for the truncated event: %v", err) + } + if ev.Name != truncatedEventName { + t.Errorf("event name = %q, want %q: the one named event on this stream", ev.Name, truncatedEventName) + } + if ev.Retry != 60*time.Second { + t.Errorf("retry = %s, want the 60s the server raises in front of a truncation", ev.Retry) + } + var decoded struct { + Since, Floor, Head int64 + } + if err := json.Unmarshal(ev.Data, &decoded); err != nil { + t.Fatalf("the truncated event's data did not parse as a problem: %v", err) + } + if decoded.Since != 40 || decoded.Floor != 51 || decoded.Head != 99 { + t.Errorf("window = {%d %d %d}, want {40 51 99}", decoded.Since, decoded.Floor, decoded.Head) + } +} + +func TestWatchRefusesAnOversizedEvent(t *testing.T) { + c, _ := newTestClient(t, Options{MaxResponseBytes: 64}, nil, func(w http.ResponseWriter, _ *http.Request) { + writeSSE(t, w, "id: 1\ndata: "+strings.Repeat("x", 200)+"\n\n") + }) + stream, err := c.WatchEvents(ctx(t), 0) + if err != nil { + t.Fatalf("WatchEvents: %v", err) + } + defer stream.Close() + if _, err := stream.Next(); !errors.Is(err, ErrResponseTooLarge) { + t.Errorf("an event past the per-event cap = %v, want ErrResponseTooLarge", err) + } +} + +func TestWatchRefusesANonEventStreamAnswer(t *testing.T) { + c, _ := newTestClient(t, Options{}, nil, func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusOK) + _, _ = io.WriteString(w, `{"status":"ok"}`) + }) + _, err := c.WatchEvents(ctx(t), 0) + if !errors.Is(err, ErrNotEventStream) { + t.Fatalf("a 2xx that is not a stream = %v, want ErrNotEventStream", err) + } +} diff --git a/internal/httpclient/wire/vocabulary_test.go b/internal/httpclient/wire/vocabulary_test.go new file mode 100644 index 000000000..7569e7502 --- /dev/null +++ b/internal/httpclient/wire/vocabulary_test.go @@ -0,0 +1,284 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/vocabulary_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "errors" + "slices" + "testing" + + "gopkg.in/yaml.v3" + + "github.com/steveyegge/beads/internal/httpapi" + "github.com/steveyegge/beads/internal/httpapi/spec" +) + +// The drift gates. Everything above proves the client BEHAVES; these three prove +// its three tables still describe the surface it is a client of. They are pure — +// no server, no database, no build tag — which is what lets them run in the +// unconditional PR job rather than in a tier only some pushes reach. +// +// They are the only place this package touches internal/httpapi. Production code +// deliberately does not: importing the server would drag the storage engine into +// every process that only wants to talk to one. + +func TestOperationIdsMatchTheServerRouteTable(t *testing.T) { + // One row per operation, so a renamed operationId fails to compile here + // before it fails on the wire at runtime. + pairs := []struct{ mine, theirs string }{ + {OpHealth, httpapi.OpHealth}, + {OpGetContext, httpapi.OpGetContext}, + {OpListReadyWork, httpapi.OpListReadyWork}, + {OpCountReadyWork, httpapi.OpCountReadyWork}, + {OpGetStats, httpapi.OpGetStats}, + {OpListIssues, httpapi.OpListIssues}, + {OpQueryIssues, httpapi.OpQueryIssues}, + {OpGetIssue, httpapi.OpGetIssue}, + {OpClaimIssue, httpapi.OpClaimIssue}, + {OpCloseIssue, httpapi.OpCloseIssue}, + {OpReopenIssue, httpapi.OpReopenIssue}, + {OpUpdateIssue, httpapi.OpUpdateIssue}, + {OpSweepIssues, httpapi.OpSweepIssues}, + {OpDeleteIssues, httpapi.OpDeleteIssues}, + {OpBatchCreateIssues, httpapi.OpBatchCreateIssues}, + {OpBatchCloseIssues, httpapi.OpBatchCloseIssues}, + {OpClaimNextIssue, httpapi.OpClaimNextIssue}, + {OpReleaseIssue, httpapi.OpReleaseIssue}, + {OpCountIssues, httpapi.OpCountIssues}, + {OpListSettings, httpapi.OpListSettings}, + {OpGetSetting, httpapi.OpGetSetting}, + {OpSetSetting, httpapi.OpSetSetting}, + {OpUnsetSetting, httpapi.OpUnsetSetting}, + {OpListDependencies, httpapi.OpListDependencies}, + {OpListBlockingAnnotations, httpapi.OpListBlockingAnnotations}, + {OpGetDependencyTree, httpapi.OpGetDependencyTree}, + {OpCountDependencyEdges, httpapi.OpCountDependencyEdges}, + {OpListRelatedIssues, httpapi.OpListRelatedIssues}, + {OpAddComment, httpapi.OpAddComment}, + {OpListDependencyCycles, httpapi.OpListDependencyCycles}, + {OpAddDependencies, httpapi.OpAddDependencies}, + {OpRemoveDependency, httpapi.OpRemoveDependency}, + {OpListMemories, httpapi.OpListMemories}, + {OpRememberMemory, httpapi.OpRememberMemory}, + {OpGetMemory, httpapi.OpGetMemory}, + {OpForgetMemory, httpapi.OpForgetMemory}, + {OpCreateIssue, httpapi.OpCreateIssue}, + {OpApplyBatch, httpapi.OpApplyBatch}, + {OpCompareAndSetMetadata, httpapi.OpCompareAndSetMetadata}, + {OpListEvents, httpapi.OpListEvents}, + {OpWatchEvents, httpapi.OpWatchEvents}, + } + + // The table is a HAND LIST, and a hand list's failure mode is omission: a new + // operation that never got a row here is an operation whose id this client + // could spell differently from the server forever, and every row above would + // still pass. Counting it against the capability map — which the route-table + // gate below already holds set-equal with the server's own — is what makes + // the omission fail instead of going unnoticed. + // + // The two identity operations are the difference: they carry no capability + // token (liveness and the handshake are not gated by the list they publish), + // so they are on this table and not in that map. + if got, want := len(pairs), len(opCapability); got != want { + t.Errorf("the identity table has %d rows against %d operations on the capability map; "+ + "a new operation needs a row here as well as a token there", got, want) + } + + for _, tc := range pairs { + if tc.mine != tc.theirs { + t.Errorf("operation id %q, server says %q", tc.mine, tc.theirs) + } + if _, known := CapabilityFor(tc.mine); !known { + t.Errorf("operation %q is not on the capability map", tc.mine) + } + } +} + +func TestCapabilityTableMatchesTheServerRouteTable(t *testing.T) { + // Set equality against the tokens the server actually advertises, so an + // operation added upstream with a capability cannot arrive here unclassified — + // the pre-flight would then dial it blind and get the bare 404 that is + // ambiguous with an entity's not_found. The server's advertised set is the + // UNION of its per-operation tokens and its server-wide BEHAVIOR tokens + // (project.enforce), so the client's side of the comparison is the same union: + // opCapability's tokens plus behaviorCapabilities. This is also the sync- + // atomicity gate — if the server's project-enforce change landed without this + // client's behaviorCapabilities mirror, the two sets diverge and this fails. + var mine []string + for op, token := range opCapability { + if token == "" { + // Liveness and the handshake itself are not gated by the list they + // publish. + if op != OpHealth && op != OpGetContext { + t.Errorf("operation %q has no capability token", op) + } + continue + } + mine = append(mine, token) + } + mine = append(mine, behaviorCapabilities...) + slices.Sort(mine) + + theirs := httpapi.Capabilities() + if !slices.Equal(mine, theirs) { + t.Errorf("capability tokens differ.\nclient: %v\nserver: %v", mine, theirs) + } +} + +// TestTheProjectIdentityVocabularyMatchesTheServer holds the three constants this +// client mirrors from internal/httpapi — the stamp header, the behavior +// capability and the mismatch reason — set-equal with the server's own, so a +// rename on either side fails to compile or fails here rather than silently on the +// wire. They are redeclared rather than imported for the reason paths.go states: +// internal/httpapi is the SERVER, and importing it would drag the storage engine +// into every client process. +func TestTheProjectIdentityVocabularyMatchesTheServer(t *testing.T) { + if ProjectIDHeader != httpapi.ProjectIDHeader { + t.Errorf("ProjectIDHeader = %q, server says %q", ProjectIDHeader, httpapi.ProjectIDHeader) + } + if CapProjectEnforce != httpapi.CapProjectEnforce { + t.Errorf("CapProjectEnforce = %q, server says %q", CapProjectEnforce, httpapi.CapProjectEnforce) + } + if CapListSort != httpapi.CapIssuesListSort { + t.Errorf("CapListSort = %q, server says %q", CapListSort, httpapi.CapIssuesListSort) + } + if CapBatchApplyLarge != httpapi.CapBatchApplyLarge { + t.Errorf("CapBatchApplyLarge = %q, server says %q", CapBatchApplyLarge, httpapi.CapBatchApplyLarge) + } + if ReasonProjectMismatch != string(httpapi.ReasonProjectMismatch) { + t.Errorf("ReasonProjectMismatch = %q, server says %q", ReasonProjectMismatch, httpapi.ReasonProjectMismatch) + } + if WireRevisionHeader != httpapi.WireRevisionHeader { + t.Errorf("WireRevisionHeader = %q, server says %q", WireRevisionHeader, httpapi.WireRevisionHeader) + } + if ReasonWireRevisionUnsupported != string(httpapi.ReasonWireRevisionUnsupported) { + t.Errorf("ReasonWireRevisionUnsupported = %q, server says %q", ReasonWireRevisionUnsupported, httpapi.ReasonWireRevisionUnsupported) + } + // ClientWireRevision is this build's OWN declared revision, not a mirror of + // a server constant — but in this repo client and server ship from the same + // commit, so the two are held in LOCKSTEP: ClientWireRevision must equal + // httpapi.CurrentWireRevision exactly, not merely satisfy <=. A real + // deployment can run an older client against a newer server (that is the + // whole reason ClientMinWireRevision and the wire_revision_unsupported + // refusal exist), but THIS package's own declared revision has no excuse to + // lag the server it ships beside — a PR that bumps CurrentWireRevision + // without also bumping ClientWireRevision has shipped a client that cannot + // decode its own paired server's new shape, which is exactly the gap the + // two checks below catch from both directions: strictly newer is one kind + // of bug (a shape this build cannot possibly have been compiled to decode, + // since CurrentWireRevision is the newest that exists), and merely + // different-in-either-direction is the lockstep rule's own general case. + if ClientWireRevision > httpapi.CurrentWireRevision { + t.Errorf("ClientWireRevision = %d, which is newer than the server's own CurrentWireRevision %d", ClientWireRevision, httpapi.CurrentWireRevision) + } + if ClientWireRevision != httpapi.CurrentWireRevision { + t.Errorf("ClientWireRevision = %d, server's CurrentWireRevision = %d; this client's declared revision has drifted from the one it was built against", ClientWireRevision, httpapi.CurrentWireRevision) + } + // The behavior mirror is exactly the server's, so the union above cannot pass + // by coincidence — a behavior token on one side only would fail here. The + // literal is spelled out member by member rather than compared against the + // server's own slice: a mirror checked against the thing it mirrors passes + // however both of them move. + if !slices.Equal(behaviorCapabilities, []string{httpapi.CapProjectEnforce, httpapi.CapBatchApplyLarge, httpapi.CapIssuesListSort}) { + t.Errorf("behaviorCapabilities = %v, want the server's project.enforce, issues.batchApplyLarge and issues.list.sort tokens", behaviorCapabilities) + } +} + +func TestEveryBaselineOperationIsOnTheCapabilityMap(t *testing.T) { + // The two-speed policy is only sound if the baseline set is a subset of the + // operations this client knows at all: a baseline op missing from the map + // would pre-flight as an unknown operation instead of skipping. + for op := range baselineOps { + if _, known := CapabilityFor(op); !known { + t.Errorf("baseline operation %q is not on the capability map", op) + } + } + if len(baselineOps) != 5 { + t.Errorf("baseline set has %d operations, want five (claimIssue is first-slice but gated as a write, ga-b8ddd.11)", len(baselineOps)) + } +} + +func TestTheCodeTableIsSetEqualWithTheDocumentedVocabulary(t *testing.T) { + documented := documentedCodes(t) + mapped := Codes() + + if !slices.Equal(documented, mapped) { + t.Errorf("problem-code vocabulary differs.\ndocument: %v\nclient: %v", documented, mapped) + } + + // The other half of the claim: being ON the table has to mean the code + // reaches a row rather than the status-class default branch. 418 is frozen to + // no code, so a code that fell through would answer with the 4xx default. + for _, code := range mapped { + got := sentinelFor(&ProblemError{Code: code, Status: 418}, target{}) + if errors.Is(got, ErrBadRequest) { + t.Errorf("code %q is on the table but falls through to the default branch", code) + } + } + // And the converse, so the probe above is meaningful. + if got := sentinelFor(&ProblemError{Code: "no_such_code", Status: 418}, target{}); !errors.Is(got, ErrBadRequest) { + t.Errorf("an unmapped code did not take the default branch: %v", got) + } +} + +func TestEveryDocumentedCodeCarriesTheStatusTheServerFroze(t *testing.T) { + // The client dispatches on `code` alone, which is only safe because the + // server freezes one status per code. If that ever stopped being true, the + // default branch's status-class fallback would be reading a status that no + // longer means anything. + for _, code := range documentedCodes(t) { + if httpapi.Code(code).Status() == 0 { + t.Errorf("code %q has no frozen status on the server", code) + } + } +} + +// documentedCodes collects every `x-bd-codes` entry in the shipped OpenAPI +// document — the per-operation vocabulary rows and the shared component +// responses alike — sorted and deduplicated. +func documentedCodes(t *testing.T) []string { + t.Helper() + var doc any + if err := yaml.Unmarshal(spec.OpenAPIV0(), &doc); err != nil { + t.Fatalf("parse the embedded openapi document: %v", err) + } + seen := map[string]struct{}{} + var walk func(any) + walk = func(node any) { + switch n := node.(type) { + case map[string]any: + for key, value := range n { + if key == "x-bd-codes" { + list, ok := value.([]any) + if !ok { + t.Fatalf("x-bd-codes is %T, want a list", value) + } + for _, item := range list { + code, ok := item.(string) + if !ok { + t.Fatalf("x-bd-codes entry is %T, want a string", item) + } + seen[code] = struct{}{} + } + continue + } + walk(value) + } + case []any: + for _, item := range n { + walk(item) + } + } + } + walk(doc) + + if len(seen) == 0 { + t.Fatal("no x-bd-codes rows found; the document's shape changed and this gate is now vacuous") + } + out := make([]string, 0, len(seen)) + for code := range seen { + out = append(out, code) + } + slices.Sort(out) + return out +} diff --git a/internal/httpclient/wire/writes.go b/internal/httpclient/wire/writes.go new file mode 100644 index 000000000..561cfa080 --- /dev/null +++ b/internal/httpclient/wire/writes.go @@ -0,0 +1,566 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/writes.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "net/http" + "net/url" + + "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/issueops" +) + +// defaultApplyBatchItemCap is the item cap this client enforces against a +// server that does NOT advertise CapBatchApplyLarge — the original, +// always-supported shape every v0 server answers regardless of build. It is +// deliberately not the only cap this client ever applies: see ApplyBatch, +// which reads the handshake snapshot on every call and raises the ceiling to +// issueops.MaxApplyBatchItems the moment the server says it can take it. A +// compiled constant used UNCONDITIONALLY is exactly what task #3 forbids — +// this one is the floor a server might not have raised, not the client's own +// opinion of where the line should be. +const defaultApplyBatchItemCap = 100 + +// The v0 write operations, one method per operationId. +// +// Each one preflights ITSELF. Do deliberately does not — a transport test must +// be able to drive one request without standing up a handshake — but the +// capability check is not a policy the CALLER should be able to forget: an +// unrouted path on an older server answers a bare 404 that reads as "no such +// issue", and D6 requires the advertised list to be consulted before the dial. +// The layer that knows an operation's id is the layer that can never omit it, +// so it lives here rather than in each role's dispatch site. +// +// The request carries IssueID and DependsOnID where the operation has them. +// They are not sent: the problem mapper needs them to rebuild the typed +// conflicts whose extension members the server leaves out because the request +// already said them (see problem.go's target). + +// ClaimIssue claims one issue. Unlike the other first-slice operations it is +// NOT exempt from the pre-flight (ga-b8ddd.11): a claim is a write, and the +// dispatch below forces the handshake so the project-identity gate runs before +// the claim can land. issues.claim is first-slice on every v0 server, so that +// gate costs one handshake round trip and never refuses a claim on capability. +func (c *Client) ClaimIssue(ctx context.Context, id string, body apigen.ClaimRequest) (*apigen.ClaimResponse, error) { + path, err := IssueMethodPath(id, MethodClaim) + if err != nil { + return nil, err + } + var out apigen.ClaimResponse + r := Request{Op: OpClaimIssue, Method: http.MethodPost, Path: path, Body: body, IssueID: id} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// CreateIssue creates one issue, with its parent, its explicit edges and its +// waits-for gate, as one transaction. +// +// A PLAIN COLLECTION POST, and the response is the bare issue rather than an +// envelope: this operation creates one member of the collection its path names, +// so what comes back is the member — the row as STORED, carrying the id the +// server minted, the status it defaulted and the timestamps it persisted. +// +// It carries no IssueID, unlike the four operations that name one in their path. +// A create's id may not exist yet, and the problem mapper's target exists to +// rebuild conflicts the server left endpoints out of because the REQUEST said +// them — a create's `already_exists` is about an id the caller may never have +// spelled, so supplying one here would name a row this request did not choose. +// The role puts the caller's own id back where there was one. +func (c *Client) CreateIssue(ctx context.Context, body apigen.CreateIssueRequest) (*apigen.Issue, error) { + var out apigen.Issue + r := Request{Op: OpCreateIssue, Method: http.MethodPost, Path: PathIssues, Body: body} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// ReleaseIssue gives the claim on one issue back, and is the claim's inverse on +// the same custom-method dispatcher. +// +// It carries IssueID like the four operations that name one in their path, and +// on this one the reconstruction it feeds is not decorative: the ownership fence +// answers `already_claimed`, whose typed *issueops.ClaimConflictError is rebuilt +// from the request's id plus the members the server sends. Leaving the id off +// would name the empty string in a refusal about a specific row. +// +// The RESPONSE carries the post-release revision beside the issue, because +// types.Issue.RowVersion is `json:"-"` and the token cannot ride the row. The +// role stitches the two back together; see httpReleaser.Release. +func (c *Client) ReleaseIssue(ctx context.Context, id string, body apigen.ReleaseIssueRequest) (*apigen.ReleaseIssueResponse, error) { + path, err := IssueMethodPath(id, MethodRelease) + if err != nil { + return nil, err + } + var out apigen.ReleaseIssueResponse + r := Request{Op: OpReleaseIssue, Method: http.MethodPost, Path: path, Body: body, IssueID: id} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// AddComment appends one comment to the thread an issue owns. +// +// A PLAIN COLLECTION POST onto a SUB-RESOURCE, which is a shape no other method +// here has: the path names the collection (`/issues/{id}/comments`) rather than +// the resource, and what comes back is the member — the comment row as stored, +// with the id the insert minted and created_at at the column's own precision. +// That is the single create's posture, one level down. +// +// It carries IssueID for the ANCHOR rather than for a conflict: this operation +// raises none — a thread is append-only and the write touches no field of the +// issue — so the id travels only so a refusal names the row the request named. +func (c *Client) AddComment(ctx context.Context, id string, body apigen.AddCommentRequest) (*apigen.Comment, error) { + path, err := IssueCommentsPath(id) + if err != nil { + return nil, err + } + var out apigen.Comment + r := Request{Op: OpAddComment, Method: http.MethodPost, Path: path, Body: body, IssueID: id} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// ClaimNextIssue takes the next ready issue the filter admits, as ONE act. +// +// IT NAMES NO ID BECAUSE IT NAMES NO ROW, which is what makes it a +// collection-level custom method rather than a mode of issues/{id}:claim: the +// caller asks a question and the server's role picks the answer, inside the +// transaction that commits it. +// +// THE FILTER IS THE QUERY AND THE ACTOR IS THE BODY, which is the operation's +// split rather than this method's arrangement of it. The filter vocabulary is +// GET /v0/beads/ready's and goes through the same server-side decode, so a body +// object would be a second expression of one predicate; the actor is provenance +// that lands in a column, and this surface has always carried that in a body. +// +// It carries no IssueID for CreateIssue's reason, one step further along: there +// is no id the caller could have supplied, so a refusal has none to name. The +// operation raises no per-row conflict anyway — a row a racing agent already +// took is simply not in the set the claim scanned. +func (c *Client) ClaimNextIssue(ctx context.Context, params url.Values, body apigen.ClaimNextRequest) (*apigen.ClaimNextResponse, error) { + var out apigen.ClaimNextResponse + r := Request{Op: OpClaimNextIssue, Method: http.MethodPost, Path: PathIssuesClaimNext, Query: params, Body: body} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// CloseIssue closes one issue. +func (c *Client) CloseIssue(ctx context.Context, id string, body apigen.CloseIssueRequest) (*apigen.CloseIssueResponse, error) { + path, err := IssueMethodPath(id, MethodClose) + if err != nil { + return nil, err + } + var out apigen.CloseIssueResponse + r := Request{Op: OpCloseIssue, Method: http.MethodPost, Path: path, Body: body, IssueID: id} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// ReopenIssue reopens one issue. +func (c *Client) ReopenIssue(ctx context.Context, id string, body apigen.ReopenIssueRequest) (*apigen.ReopenIssueResponse, error) { + path, err := IssueMethodPath(id, MethodReopen) + if err != nil { + return nil, err + } + var out apigen.ReopenIssueResponse + r := Request{Op: OpReopenIssue, Method: http.MethodPost, Path: path, Body: body, IssueID: id} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// UpdateGuards are updateIssue's three compare-and-set preconditions, as the +// caller hands them to the transport. +// +// EVERY MEMBER IS A POINTER AND NIL MEANS ABSENT. That is not a style choice on +// any of the three: `expected_version` 0 is a legal token — the migration-0054 +// backfill left rows holding it — and `expected_assignee` "" is a legal guard, +// the one that says "only if nobody holds it". A zero value is a REQUEST on +// both, so the only encoding that can express "no guard" is the absent member, +// and `omitempty` on a pointer omits exactly the nil. +// +// It is a type of its own rather than three arguments because they travel +// together and mean one thing, and because a fourth parameter of the same +// primitive type beside `actor` is the shape a caller transposes. +type UpdateGuards struct { + // ExpectedVersion is the row's `revision`, compared for equality alone. It + // is a STRING on the wire — the token's decimal spelling, rendered by + // types.RevisionToken from the int64 the role holds — because the token + // spans the full 64-bit range and a JSON number would be rounded past 2^53 + // by any IEEE-754-double consumer. The server refuses a bare number on this + // member with a 400, so the int64 never reaches the body. + ExpectedVersion *string `json:"expected_version,omitempty"` + // ExpectedStatus is the status the request guards on, spelled as the + // workspace's own vocabulary. + ExpectedStatus *string `json:"expected_status,omitempty"` + // ExpectedAssignee is the assignee the request guards on. A pointer to the + // empty string guards on UNASSIGNED and is a different request from nil. + ExpectedAssignee *string `json:"expected_assignee,omitempty"` +} + +// updateBody is updateIssue's request body as this client has to build it. +// +// It is deliberately NOT apigen.UpdateIssueRequest. That type spells the patch +// as pointer members with `omitempty`, which collapses two different requests +// into one document: on this operation a member's PRESENCE is the signal to +// write it and an explicit null on one of the four nullable members is the +// CLEAR, so an omitted member and a null member must be distinguishable — and a +// nil pointer under `omitempty` is neither. The patch therefore arrives already +// decided by its builder, and this layer marshals it verbatim. +// +// The GUARDS are embedded rather than spelled again, so their json tags — and +// the absent-is-not-zero rule those tags encode — have one definition. +// +// The RESPONSE stays apigen's: nothing about reading one is ambiguous. +type updateBody struct { + Actor string `json:"actor"` + Patch map[string]any `json:"patch"` + UpdateGuards +} + +// UpdateIssue patches one issue. It is the only PATCH on this surface: the +// operation's pattern equals its spec path, so no custom-method suffix is +// involved and the id is an ordinary escaped segment. +// +// The guards ride BESIDE the patch, at the body's top level, which is where the +// server reads them: one smuggled into the patch document would be an unknown +// member of `patch` and a 400. +func (c *Client) UpdateIssue(ctx context.Context, id, actor string, patch map[string]any, guards UpdateGuards) (*apigen.UpdateIssueResponse, error) { + path, err := IssuePath(id) + if err != nil { + return nil, err + } + var out apigen.UpdateIssueResponse + body := updateBody{Actor: actor, Patch: patch, UpdateGuards: guards} + r := Request{Op: OpUpdateIssue, Method: http.MethodPatch, Path: path, Body: body, IssueID: id} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// CompareAndSetMetadata swaps one metadata key of one issue if and only if it +// currently holds the request's `expected`, and reports what it found either +// way. +// +// IT IS THE ONE WRITE HERE WHOSE REFUSAL IS A SUCCESS. A lost race answers 200 +// with `swapped: false` and the value that refused the swap, so there is no 409 +// for the problem mapper to classify and nothing about the verdict reaches this +// layer at all: the caller dispatches on the body. That is deliberate on the +// server's side — a conflict code would put the ordinary path of a retry loop +// into the error channel, and the value the loop needs next would have to +// travel in a problem extension member. +// +// It carries IssueID like the four operations that name one in their path: the +// resource is one row, and a conflict the problem mapper rebuilds for it should +// name the row the request named. +func (c *Client) CompareAndSetMetadata(ctx context.Context, id string, body apigen.CompareAndSetMetadataRequest) (*apigen.CompareAndSetMetadataResponse, error) { + path, err := IssueMethodPath(id, MethodCASMetadata) + if err != nil { + return nil, err + } + var out apigen.CompareAndSetMetadataResponse + r := Request{Op: OpCompareAndSetMetadata, Method: http.MethodPost, Path: path, Body: body, IssueID: id} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// AddDependencies asserts a set of edges as one transaction. +// +// issueID and dependsOnID name the SINGLE edge a one-edge request carries, and +// are empty for a multi-edge one. That is not a shortcut: the wire's +// dependency_exists refusal does not say which edge collided, so a batch's +// reconstructed conflict has to leave its endpoints empty — and inventing the +// first edge's ids there would name the wrong pair. +func (c *Client) AddDependencies(ctx context.Context, body apigen.AddDependenciesRequest) (*apigen.AddDependenciesResponse, error) { + r := Request{Op: OpAddDependencies, Method: http.MethodPost, Path: PathDependenciesAdd, Body: body} + if len(body.Edges) == 1 { + r.IssueID = body.Edges[0].IssueId + r.DependsOnID = body.Edges[0].DependsOnId + } + var out apigen.AddDependenciesResponse + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// RemoveDependency removes exactly one edge. +func (c *Client) RemoveDependency(ctx context.Context, body apigen.RemoveDependencyRequest) (*apigen.RemoveDependencyResponse, error) { + r := Request{ + Op: OpRemoveDependency, Method: http.MethodPost, Path: PathDependenciesRemove, Body: body, + IssueID: body.IssueId, DependsOnID: body.DependsOnId, + } + var out apigen.RemoveDependencyResponse + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// SweepIssues clears the closed beads of one tier. +// +// It carries no IssueID, unlike the operations above: a sweep names no +// resource — it describes a SET and the server resolves it — so there is +// nothing for the problem mapper to rebuild a per-issue conflict from. +func (c *Client) SweepIssues(ctx context.Context, body apigen.SweepRequest) (*apigen.SweepResult, error) { + r := Request{Op: OpSweepIssues, Method: http.MethodPost, Path: PathIssuesSweep, Body: body} + var out apigen.SweepResult + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// DeleteIssues erases the named beads. +// +// The ids travel in the BODY rather than the path, so no id is escaped here: +// this is a collection-level custom method, and one request deletes many rows +// as one transaction. +func (c *Client) DeleteIssues(ctx context.Context, body apigen.DeleteIssuesRequest) (*apigen.DeleteIssuesResult, error) { + r := Request{Op: OpDeleteIssues, Method: http.MethodPost, Path: PathIssuesDelete, Body: body} + var out apigen.DeleteIssuesResult + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// BatchCreateIssues creates every issue in the body, or none of them. +func (c *Client) BatchCreateIssues(ctx context.Context, body apigen.BatchCreateRequest) (*apigen.BatchCreateResponse, error) { + r := Request{Op: OpBatchCreateIssues, Method: http.MethodPost, Path: PathIssuesBatchCreate, Body: body} + var out apigen.BatchCreateResponse + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// BatchCloseIssues closes a set of issues the request names as ONE act, and is +// the write side of `bd close a b c`. It is NOT all-or-nothing: a refused id is +// a per-item outcome inside a 200, so the response carries one entry per item +// and the survivors still commit. +// +// The response's TOP level goes through the existing problem mapper like every +// other operation: a 400 (bad body), a 503 (busy) or a 5xx is the method's own +// typed error. The per-item outcomes inside a 200 are the CALLER's to walk — +// each BatchCloseItemError carries its own code — because the close vocabulary a +// per-item refusal answers with is the role's, not the transport's. +func (c *Client) BatchCloseIssues(ctx context.Context, body apigen.BatchCloseRequest) (*apigen.BatchCloseResponse, error) { + var out apigen.BatchCloseResponse + r := Request{Op: OpBatchCloseIssues, Method: http.MethodPost, Path: PathIssuesBatchClose, Body: body} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// ApplyUpdateItem is one `update` item of a plan, as this client has to build +// it. +// +// It is deliberately NOT apigen.ApplyUpdateItem, for updateBody's reason and +// only that reason: the patch is a DOCUMENT rather than a struct, because on +// this member — as on PATCH /v0/beads/issues/{id} — presence is the signal to +// write a field and an explicit null on one of the four nullable members is the +// CLEAR, and a struct of pointers with `omitempty` collapses those two states +// into one. The builder is encodeApplyPatch; this layer marshals what it +// decided. +// +// Every other member is spelled exactly as apigen.ApplyUpdateItem spells it, +// and the write-ledger gate classifies this shape against THAT type so a member +// published upstream and missing here cannot go unnoticed. +type ApplyUpdateItem struct { + Target apigen.Ref `json:"target"` + Patch map[string]any `json:"patch"` + // The guard trio, per item and pointers for UpdateGuards' reason: "0" is a + // legal row version and "" is the guard that says "only if nobody holds + // it", so absent has to stay absent on all three. The version is the + // token's decimal string, spelled by types.RevisionToken, for the reason + // UpdateGuards.ExpectedVersion gives. + ExpectedVersion *string `json:"expected_version,omitempty"` + ExpectedStatus *string `json:"expected_status,omitempty"` + ExpectedAssignee *string `json:"expected_assignee,omitempty"` + ForceClosePolicy *bool `json:"force_close_policy,omitempty"` + ForceAssigneeTransfer *bool `json:"force_assignee_transfer,omitempty"` +} + +// ApplyItem is one item of a plan: a `kind` and exactly one payload naming it. +// +// THE TAG IS ENFORCED BY THE CALLER and cannot be enforced here, which is the +// document's own doctrine rather than an omission on this side: the schema +// carries four optional payload members and a required tag rather than a schema +// alternation, so nothing in any generated type stops a request carrying two +// payloads or a payload the kind does not name. The role builds these, and it +// refuses all three disagreements before the dial. +type ApplyItem struct { + Kind string `json:"kind"` + Create *apigen.ApplyCreateItem `json:"create,omitempty"` + Update *ApplyUpdateItem `json:"update,omitempty"` + Close *apigen.ApplyCloseItem `json:"close,omitempty"` + DepAdd *apigen.ApplyDepAddItem `json:"dep_add,omitempty"` +} + +// ApplyBatchRequest is issues:batchApply's body, carrying the item type above. +type ApplyBatchRequest struct { + Actor string `json:"actor"` + Items []ApplyItem `json:"items"` + Provenance *string `json:"provenance,omitempty"` + ForceIDPrefix *bool `json:"force_id_prefix,omitempty"` + SkipPerEdgeCycleCheck *bool `json:"skip_per_edge_cycle_check,omitempty"` +} + +// ApplyBatch applies an ordered, heterogeneous plan as ONE transaction, or +// applies none of it. +// +// IT IS THE WIDEST WRITE ON THIS SURFACE and the only one that is all-or-nothing +// across several verbs. That shapes what this layer can carry: there are no +// per-item outcomes to walk on a refusal — an item that refused took the whole +// request down, and every other item's outcome would be a statement about a +// transaction that rolled back — so the offender travels in the problem +// document's `item_*` members instead, which the mapper decodes and the role +// rebuilds into an *issueops.ItemError. +// +// It carries no IssueID and no DependsOnID, for the batch add's reason and then +// some: the request names as many rows as it has items, so a conflict the +// problem mapper rebuilt from ONE of them would name an arbitrary row. The role +// puts the offender back from `item_issue_id`, which the server reads inside the +// refusing transaction. +func (c *Client) ApplyBatch(ctx context.Context, body ApplyBatchRequest) (*apigen.ApplyBatchResponse, error) { + // The batch cap, read off the handshake snapshot rather than a bare + // compiled constant (task #3): a server that has not raised its own + // ceiling only ever promised the original 100-item shape, and sending it + // more would earn a 400 this client can refuse before paying the round + // trip for. Handshake is cached after the first call, so this costs no + // extra dial on the common path — ApplyBatch is never a baseline + // operation, so Preflight below would force the same fetch anyway. + snap, err := c.Handshake(ctx) + if err != nil { + return nil, err + } + limit := defaultApplyBatchItemCap + if snap.Has(CapBatchApplyLarge) { + limit = issueops.MaxApplyBatchItems + } + if n := len(body.Items); n > limit { + if !snap.Has(CapBatchApplyLarge) && n <= issueops.MaxApplyBatchItems { + // Raising the ceiling would admit this plan: the exact "a + // capability it does not advertise" shape the skew matrix already + // covers (D7 case 2), caught here before the dial instead of read + // back off the 400 an unaware server would otherwise answer with + // its own un-raised cap. + return nil, NewCapabilityError(OpApplyBatch, CapBatchApplyLarge, c.base.Redacted(), &snap.Context) + } + // Over the absolute ceiling even with the capability present: no + // token any server could advertise raises this further, so it is a + // validation refusal rather than a skew one — see BatchTooLargeError. + return nil, &BatchTooLargeError{Op: OpApplyBatch, ServerURL: c.base.Redacted(), Count: n, Limit: issueops.MaxApplyBatchItems} + } + + var out apigen.ApplyBatchResponse + r := Request{Op: OpApplyBatch, Method: http.MethodPost, Path: PathIssuesBatchApply, Body: body} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// RememberMemory stores one memory. An absent key asks the server to derive +// one, which is why the body's Key is a pointer all the way down: an empty +// string and an omitted member mean different things here. +func (c *Client) RememberMemory(ctx context.Context, body apigen.RememberRequest) (*apigen.RememberedMemory, error) { + r := Request{Op: OpRememberMemory, Method: http.MethodPost, Path: PathMemories, Body: body} + var out apigen.RememberedMemory + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// RecallMemory reads one memory. A miss — including a row stored as the empty +// string — is a 404, which the problem mapper turns into issueops.ErrNotFound; +// the memory role converts that to its own Found-false result, because +// memoryops has deliberately no ErrNotFound. +func (c *Client) RecallMemory(ctx context.Context, key string) (*apigen.Memory, error) { + path, err := MemoryPath(key) + if err != nil { + return nil, err + } + var out apigen.Memory + r := Request{Op: OpGetMemory, Method: http.MethodGet, Path: path} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// ForgetMemory removes one memory and answers with the value it removed, read +// in the deletion's own transaction. +func (c *Client) ForgetMemory(ctx context.Context, key string) (*apigen.Memory, error) { + path, err := MemoryPath(key) + if err != nil { + return nil, err + } + var out apigen.Memory + r := Request{Op: OpForgetMemory, Method: http.MethodDelete, Path: path} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// ListMemories enumerates the memory plane. The narrowing parameter is spelled +// `search` — not `q`, which is queryIssues' spelling. +func (c *Client) ListMemories(ctx context.Context, search string) (*apigen.MemoriesPage, error) { + var query url.Values + if search != "" { + query = url.Values{"search": []string{search}} + } + var out apigen.MemoriesPage + r := Request{Op: OpListMemories, Method: http.MethodGet, Path: PathMemories, Query: query} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// ListReadyWork reads one page of the ready front. +// +// It lives beside the writes because the composed ReadyClaimer is what needed it +// first, and that is now a fact about ONE LEG rather than about the wire: +// ClaimNextIssue above dials the operation where the server advertises it, and +// the composition — this read followed by claimIssue — survives only as the +// down-level leg for a server older than #5510. The reader role wants the same +// operation, and this method is the one it uses: there must never be a second +// spelling of one operation on this client, which is why a read sits in a file +// of writes rather than being copied into one. +func (c *Client) ListReadyWork(ctx context.Context, params url.Values) (*apigen.ReadyPage, error) { + var out apigen.ReadyPage + r := Request{Op: OpListReadyWork, Method: http.MethodGet, Path: PathReady, Query: params} + if err := c.dispatch(ctx, r, &out); err != nil { + return nil, err + } + return &out, nil +} + +// dispatch is preflight-then-Do, the pairing every operation method above owes +// and none of them may skip. +func (c *Client) dispatch(ctx context.Context, r Request, out any) error { + if err := c.Preflight(ctx, r.Op); err != nil { + return err + } + return c.Do(ctx, r, out) +} diff --git a/internal/httpclient/wire/writes_batch_cap_test.go b/internal/httpclient/wire/writes_batch_cap_test.go new file mode 100644 index 000000000..c023b090b --- /dev/null +++ b/internal/httpclient/wire/writes_batch_cap_test.go @@ -0,0 +1,133 @@ +// Written fresh for OSS beads S2 (no bd-enterprise source copied). +package wire + +import ( + "errors" + "testing" + + "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/issueops" +) + +// applyBatchRequestOfSize builds the smallest valid ApplyBatchRequest with n +// items -- a plain create apiece, since ApplyBatch's own cap logic never looks +// past len(body.Items). +func applyBatchRequestOfSize(n int) ApplyBatchRequest { + items := make([]ApplyItem, n) + for i := range items { + items[i] = ApplyItem{Kind: string(apigen.ApplyItemKindCreate), Create: &apigen.ApplyCreateItem{Title: "t"}} + } + return ApplyBatchRequest{Actor: "w", Items: items} +} + +// This suite is task #3's own behavior, separate from the generic two-speed +// gate writes_twospeed_test.go already proves for OpApplyBatch (whether the +// OPERATION "issues.batchApply" is routed at all). Here the operation is +// always routed; what is under test is the ITEM-COUNT ceiling ApplyBatch +// enforces for itself, off issues.batchApplyLarge, before ever dialing +// PathIssuesBatchApply. + +// withBatchApply advertises issues.batchApply (so Preflight never refuses) +// plus whatever else the caller wants layered on top. +func withBatchApply(extra ...string) []string { + return append([]string{"issues.batchApply"}, extra...) +} + +func TestApplyBatchAtOrUnderTheFloorSucceedsWithoutTheCapability(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, serveEverything(contextBody("v0", "proj-1", withBatchApply()...))) + if _, err := c.ApplyBatch(ctx(t), applyBatchRequestOfSize(defaultApplyBatchItemCap)); err != nil { + t.Fatalf("ApplyBatch at the floor (%d items): %v", defaultApplyBatchItemCap, err) + } + // One handshake (cached across Handshake-then-Preflight) plus the batch + // apply itself. + if rec.count() != 2 { + t.Fatalf("made %d requests, want 2 (context, then the batch apply)", rec.count()) + } + if got := rec.at(t, 1).path; got != PathIssuesBatchApply { + t.Errorf("second request = %q, want %q", got, PathIssuesBatchApply) + } +} + +func TestApplyBatchOverTheFloorWithoutTheCapabilityRefusesBeforeDialing(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, serveEverything(contextBody("v0", "proj-1", withBatchApply()...))) + n := defaultApplyBatchItemCap + 1 + _, err := c.ApplyBatch(ctx(t), applyBatchRequestOfSize(n)) + + var capErr *CapabilityError + if !errors.As(err, &capErr) { + t.Fatalf("err = %v (%T), want *CapabilityError", err, err) + } + if capErr.Capability != CapBatchApplyLarge { + t.Errorf("Capability = %q, want %q", capErr.Capability, CapBatchApplyLarge) + } + // Only the handshake's own context fetch; the batch-apply endpoint must + // never be dialed once the item count alone is enough to refuse. + if rec.count() != 1 { + t.Fatalf("made %d requests, want only the handshake", rec.count()) + } + if got := rec.at(t, 0).path; got != PathContext { + t.Errorf("only request = %q, want %q", got, PathContext) + } +} + +func TestApplyBatchAtTheRaisedCeilingSucceedsWithTheCapability(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, + serveEverything(contextBody("v0", "proj-1", withBatchApply(CapBatchApplyLarge)...))) + n := issueops.MaxApplyBatchItems + if _, err := c.ApplyBatch(ctx(t), applyBatchRequestOfSize(n)); err != nil { + t.Fatalf("ApplyBatch at the raised ceiling (%d items) with %s advertised: %v", n, CapBatchApplyLarge, err) + } + if rec.count() != 2 { + t.Fatalf("made %d requests, want 2 (context, then the batch apply)", rec.count()) + } + if got := rec.at(t, 1).path; got != PathIssuesBatchApply { + t.Errorf("second request = %q, want %q", got, PathIssuesBatchApply) + } +} + +func TestApplyBatchBetweenTheFloorAndTheCeilingWithTheCapabilitySucceeds(t *testing.T) { + // A count the floor alone would refuse, admitted once the server raises + // its own ceiling -- the capability actually changing the outcome, not + // just being present. + c, _ := newTestClient(t, Options{}, nil, + serveEverything(contextBody("v0", "proj-1", withBatchApply(CapBatchApplyLarge)...))) + n := defaultApplyBatchItemCap + 1 + if _, err := c.ApplyBatch(ctx(t), applyBatchRequestOfSize(n)); err != nil { + t.Fatalf("ApplyBatch at %d items with %s advertised: %v", n, CapBatchApplyLarge, err) + } +} + +func TestApplyBatchOverTheAbsoluteCeilingRefusesRegardlessOfTheCapability(t *testing.T) { + for _, tc := range []struct { + name string + capabilities []string + }{ + {"capability absent", withBatchApply()}, + {"capability present", withBatchApply(CapBatchApplyLarge)}, + } { + t.Run(tc.name, func(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, serveEverything(contextBody("v0", "proj-1", tc.capabilities...))) + n := issueops.MaxApplyBatchItems + 1 + _, err := c.ApplyBatch(ctx(t), applyBatchRequestOfSize(n)) + + var tooLarge *BatchTooLargeError + if !errors.As(err, &tooLarge) { + t.Fatalf("err = %v (%T), want *BatchTooLargeError", err, err) + } + if tooLarge.Count != n { + t.Errorf("Count = %d, want %d", tooLarge.Count, n) + } + if tooLarge.Limit != issueops.MaxApplyBatchItems { + t.Errorf("Limit = %d, want %d (no token raises this further)", tooLarge.Limit, issueops.MaxApplyBatchItems) + } + if !errors.Is(err, issueops.ErrValidation) { + t.Error("err does not satisfy issueops.ErrValidation; over the absolute ceiling is a validation refusal, not a skew one") + } + // No token any server advertises raises this further, so this must + // never reach the batch-apply endpoint either. + if rec.count() != 1 { + t.Fatalf("made %d requests, want only the handshake", rec.count()) + } + }) + } +} diff --git a/internal/httpclient/wire/writes_twospeed_test.go b/internal/httpclient/wire/writes_twospeed_test.go new file mode 100644 index 000000000..da2799032 --- /dev/null +++ b/internal/httpclient/wire/writes_twospeed_test.go @@ -0,0 +1,399 @@ +// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/wire/writes_twospeed_test.go@49d1df2f6) +// to OSS beads under the MIT license. +package wire + +import ( + "context" + "errors" + "go/ast" + "go/parser" + "go/token" + "io" + "net/http" + "net/url" + "slices" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/httpapi/apigen" +) + +// The TWO-SPEED POLICY at the WRITE door. +// +// The store has one door for reads — (*Store).dispatch — and +// TestEveryDispatchSiteHonorsTheTwoSpeedPolicy proves nothing reaches the +// transport around it. The write roles do not use that door: they hold a typed +// WriteWire and call ClaimIssue, CloseIssue, UpdateIssue and the rest, each of +// which builds its own request here. So the property the read test proves for +// the store has to be proved AGAIN, one layer down, for these methods — and it +// is a different proof, because there is no single call site to point at. +// +// Two halves, because either alone is satisfiable by a mistake: +// +// behavioral an operation whose token the server does not advertise must +// refuse BEFORE its own request is made. Observed at the server, +// not at a spy: what matters is that the path was never dialed. +// structural every operation method routes through c.dispatch rather than +// c.Do. A method that preflighted by hand would satisfy the +// behavioral half today and drift the first time someone copies +// it, which is exactly how the sixth of six such methods gets +// written without the preflight. +// +// The failure this prevents is the one D6 names: an unrouted path on an older +// server answers a bare 404, and a 404 on this surface reads as "no such +// issue". A write that skipped the preflight would tell a user their issue does +// not exist when the truth is that their server cannot close issues. + +// writeOp is one operation method as the roles reach it. The call drives the +// real method with the smallest arguments it accepts; nothing here inspects the +// result, because the question is only which requests reached the server. +type writeOp struct { + name string + call func(context.Context, *Client) error +} + +func writeOps() []writeOp { + return []writeOp{ + {OpClaimIssue, func(ctx context.Context, c *Client) error { + _, err := c.ClaimIssue(ctx, "bd-1", apigen.ClaimRequest{Actor: "w"}) + return err + }}, + // The only write here that carries a QUERY, and the only one that names + // no resource: the filter that chooses the row is the ready listing's + // vocabulary spelled as a query string. + {OpClaimNextIssue, func(ctx context.Context, c *Client) error { + _, err := c.ClaimNextIssue(ctx, url.Values{"sort": []string{"hybrid"}}, apigen.ClaimNextRequest{Actor: "w"}) + return err + }}, + {OpCloseIssue, func(ctx context.Context, c *Client) error { + _, err := c.CloseIssue(ctx, "bd-1", apigen.CloseIssueRequest{Actor: "w"}) + return err + }}, + {OpReopenIssue, func(ctx context.Context, c *Client) error { + _, err := c.ReopenIssue(ctx, "bd-1", apigen.ReopenIssueRequest{Actor: "w"}) + return err + }}, + {OpReleaseIssue, func(ctx context.Context, c *Client) error { + _, err := c.ReleaseIssue(ctx, "bd-1", apigen.ReleaseIssueRequest{Actor: "w"}) + return err + }}, + {OpAddComment, func(ctx context.Context, c *Client) error { + _, err := c.AddComment(ctx, "bd-1", apigen.AddCommentRequest{Author: "w", Text: "t"}) + return err + }}, + {OpUpdateIssue, func(ctx context.Context, c *Client) error { + _, err := c.UpdateIssue(ctx, "bd-1", "w", map[string]any{"title": "t"}, UpdateGuards{}) + return err + }}, + {OpCreateIssue, func(ctx context.Context, c *Client) error { + _, err := c.CreateIssue(ctx, apigen.CreateIssueRequest{Actor: "w", Title: "t"}) + return err + }}, + {OpCompareAndSetMetadata, func(ctx context.Context, c *Client) error { + _, err := c.CompareAndSetMetadata(ctx, "bd-1", apigen.CompareAndSetMetadataRequest{Actor: "w", Key: "k"}) + return err + }}, + {OpAddDependencies, func(ctx context.Context, c *Client) error { + _, err := c.AddDependencies(ctx, apigen.AddDependenciesRequest{ + Actor: "w", + Edges: []apigen.DependencyEdge{{IssueId: "bd-1", DependsOnId: "bd-2", Type: "blocks"}}, + }) + return err + }}, + {OpRemoveDependency, func(ctx context.Context, c *Client) error { + _, err := c.RemoveDependency(ctx, apigen.RemoveDependencyRequest{ + Actor: "w", IssueId: "bd-1", DependsOnId: "bd-2", + }) + return err + }}, + {OpSweepIssues, func(ctx context.Context, c *Client) error { + _, err := c.SweepIssues(ctx, apigen.SweepRequest{Tier: apigen.Ephemeral}) + return err + }}, + {OpDeleteIssues, func(ctx context.Context, c *Client) error { + _, err := c.DeleteIssues(ctx, apigen.DeleteIssuesRequest{Ids: []string{"bd-1"}}) + return err + }}, + {OpBatchCreateIssues, func(ctx context.Context, c *Client) error { + _, err := c.BatchCreateIssues(ctx, apigen.BatchCreateRequest{ + Actor: "w", Items: []apigen.BatchCreateItem{{Title: "t"}}, + }) + return err + }}, + {OpBatchCloseIssues, func(ctx context.Context, c *Client) error { + _, err := c.BatchCloseIssues(ctx, apigen.BatchCloseRequest{ + Actor: "w", Items: []apigen.BatchCloseItem{{Id: "bd-1"}}, + }) + return err + }}, + {OpApplyBatch, func(ctx context.Context, c *Client) error { + _, err := c.ApplyBatch(ctx, ApplyBatchRequest{ + Actor: "w", + Items: []ApplyItem{{ + Kind: string(apigen.ApplyItemKindCreate), + Create: &apigen.ApplyCreateItem{Title: "t"}, + }}, + }) + return err + }}, + {OpRememberMemory, func(ctx context.Context, c *Client) error { + _, err := c.RememberMemory(ctx, apigen.RememberRequest{}) + return err + }}, + {OpGetMemory, func(ctx context.Context, c *Client) error { + _, err := c.RecallMemory(ctx, "k") + return err + }}, + {OpForgetMemory, func(ctx context.Context, c *Client) error { + _, err := c.ForgetMemory(ctx, "k") + return err + }}, + {OpListMemories, func(ctx context.Context, c *Client) error { + _, err := c.ListMemories(ctx, "") + return err + }}, + {OpListReadyWork, func(ctx context.Context, c *Client) error { + _, err := c.ListReadyWork(ctx, url.Values{}) + return err + }}, + } +} + +func (op writeOp) run(t *testing.T, c *Client) error { + t.Helper() + return op.call(ctx(t), c) +} + +func TestEveryWriteOperationPreflightsBeforeItDials(t *testing.T) { + ops := writeOps() + if len(ops) == 0 { + t.Fatal("no write operations are classified; there is nothing for this gate to check") + } + + every := allTokens() + for _, op := range ops { + token, known := CapabilityFor(op.name) + if !known { + t.Errorf("%s is not on the capability map", op.name) + continue + } + if IsBaseline(op.name) { + // Not a skipped case: the baseline half has its own gate below, and + // a subtest that only ever skips is the shape this whole wiring + // exists to eliminate. + continue + } + t.Run(op.name, func(t *testing.T) { + // A server that advertises the whole vocabulary EXCEPT this + // operation's token. The holdout matters: a "server has nothing" + // fixture passes even for a method wired to a neighbour's token. + held := make([]string, 0, len(every)) + for _, candidate := range every { + if candidate != token { + held = append(held, candidate) + } + } + c, rec := newTestClient(t, Options{}, nil, serveEverything(contextBody("v0", "proj-1", held...))) + + err := op.run(t, c) + var absent *CapabilityError + if !errors.As(err, &absent) { + t.Fatalf("%s against a server that does not advertise %q = %v (%T), want a *CapabilityError", + op.name, token, err, err) + } + if absent.Capability != token { + t.Errorf("%s refused on capability %q, want %q", op.name, absent.Capability, token) + } + + // The half that is the whole point: the operation's own request was + // never made. Only the handshake reached the server. + if rec.count() != 1 { + t.Fatalf("%s made %d requests, want only the handshake", op.name, rec.count()) + } + if got := rec.at(t, 0).path; got != PathContext { + t.Errorf("%s dialed %q before refusing; an unrouted path on an older server answers a bare 404, "+ + "which is indistinguishable from an entity's not_found (D6)", op.name, got) + } + }) + } +} + +// TestEveryBaselineWriteOperationDialsWithoutConsultingTheList is the other +// polarity, and it is not symmetric decoration: the two-speed policy exists to +// keep the hot work-distribution path off a second round trip, so a baseline +// operation that started preflighting would be a real regression that the test +// above cannot see. +func TestEveryBaselineWriteOperationDialsWithoutConsultingTheList(t *testing.T) { + var baseline int + for _, op := range writeOps() { + if !IsBaseline(op.name) { + continue + } + baseline++ + t.Run(op.name, func(t *testing.T) { + // A server advertising NOTHING. A baseline operation still dials. + c, rec := newTestClient(t, Options{}, nil, serveEverything(contextBody("v0", "proj-1"))) + if err := op.run(t, c); err != nil { + t.Fatalf("%s against a server advertising nothing: %v", op.name, err) + } + if rec.count() != 1 { + t.Fatalf("%s made %d requests, want exactly its own", op.name, rec.count()) + } + if got := rec.at(t, 0).path; got == PathContext { + t.Errorf("%s fetched the context first; a baseline operation must not", op.name) + } + }) + } + // listReadyWork is the ONE baseline operation the write door reaches (the + // composed ClaimNext is its only caller here). claimIssue used to be the + // second, but ga-b8ddd.11 pulled it out of baselineOps: a claim is a write, + // and the handshake it now forces is what runs the project-identity gate + // before it. So claimIssue is exercised by + // TestEveryWriteOperationPreflightsBeforeItDials instead, which stays green + // because that PR keeps ClaimIssue routing through c.dispatch. The baseline + // set is now five — the four reads plus getContext/health liveness — and + // none of them is a write. + if baseline != 1 { + t.Errorf("%d baseline write operations, want 1; the baseline set moved and this gate's premise with it", baseline) + } +} + +// TestEveryOperationMethodRoutesThroughTheSharedDispatch is the structural half. +// +// writes.go's own comment states the rule — "each one preflights ITSELF... the +// capability check is not a policy the CALLER should be able to forget" — and +// the way it is kept is that every method calls c.dispatch, which is +// preflight-then-Do and nothing else. A method reaching c.Do directly would skip +// the preflight silently; only the behavioral half above would catch it, and +// only for the operations someone remembered to table. +// +// SCOPE CAVEAT: this reads writes.go alone, by design — every operation method +// lives there today, and confining the scan is what lets it assert "exactly one +// dispatch, no bare Do" per method without tripping over the handshake's own +// Do calls in handshake.go. The blind spot is the price: an operation method +// added to a DIFFERENT file escapes this gate entirely. The behavioral half is +// the backstop — a method that skipped the preflight would dial an unadvertised +// path in TestEveryWriteOperationPreflightsBeforeItDials — but only if it was +// also added to writeOps(), which TestEveryOperationMethodIsCoveredByTheTwoSpeedTable +// enforces for the methods in this file and cannot for one outside it. A new +// operation belongs in writes.go; put it elsewhere and both gates need widening. +func TestEveryOperationMethodRoutesThroughTheSharedDispatch(t *testing.T) { + file := parseWritesFile(t) + + var checked int + for _, decl := range file.Decls { + fn, ok := decl.(*ast.FuncDecl) + if !ok || fn.Recv == nil || !fn.Name.IsExported() { + continue + } + checked++ + var dispatches, dials int + ast.Inspect(fn, func(n ast.Node) bool { + sel, ok := n.(*ast.SelectorExpr) + if !ok { + return true + } + switch sel.Sel.Name { + case "dispatch": + dispatches++ + case "Do": + dials++ + } + return true + }) + if dials > 0 { + t.Errorf("%s calls Do directly; it must go through dispatch, which is the preflight-then-Do pairing "+ + "none of these methods may skip", fn.Name.Name) + } + if dispatches != 1 { + t.Errorf("%s makes %d dispatch calls, want exactly 1", fn.Name.Name, dispatches) + } + } + if checked == 0 { + t.Fatal("found no exported operation methods in writes.go; the file moved and this gate went vacuous") + } +} + +// TestEveryOperationMethodIsCoveredByTheTwoSpeedTable keeps the table above from +// going stale by omission. A method added to writes.go tomorrow with no entry +// here would be a write door nothing checks, and the structural gate alone +// cannot say whether its token is the right one. +func TestEveryOperationMethodIsCoveredByTheTwoSpeedTable(t *testing.T) { + var tabled []string + for _, op := range writeOps() { + tabled = append(tabled, op.name) + } + + file := parseWritesFile(t) + for _, decl := range file.Decls { + fn, ok := decl.(*ast.FuncDecl) + if !ok || fn.Recv == nil || !fn.Name.IsExported() { + continue + } + op := operationDispatched(fn) + if op == "" { + t.Errorf("%s dispatches no recognizable Op constant; the table cannot be checked against it", fn.Name.Name) + continue + } + if !slices.Contains(tabled, op) { + t.Errorf("writes.go's %s dispatches %s, which no writeOps() entry drives", fn.Name.Name, op) + } + } +} + +// operationDispatched reads the Op the method's Request literal names, as the +// identifier it is spelled with (`OpCloseIssue`), resolved through the package's +// own constants. +func operationDispatched(fn *ast.FuncDecl) string { + var found string + ast.Inspect(fn, func(n ast.Node) bool { + kv, ok := n.(*ast.KeyValueExpr) + if !ok { + return true + } + key, ok := kv.Key.(*ast.Ident) + if !ok || key.Name != "Op" { + return true + } + if ident, ok := kv.Value.(*ast.Ident); ok { + found = opConstants()[ident.Name] + } + return false + }) + return found +} + +func parseWritesFile(t *testing.T) *ast.File { + t.Helper() + file, err := parser.ParseFile(token.NewFileSet(), "writes.go", nil, parser.SkipObjectResolution) + if err != nil { + t.Fatalf("parse writes.go: %v", err) + } + return file +} + +// serveEverything answers the context with body and every other path with an +// empty JSON object, which decodes into any of this client's response types. +func serveEverything(body string) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == PathContext { + _, _ = io.WriteString(w, body) + return + } + _, _ = io.WriteString(w, `{}`) + } +} + +// opConstants maps the Go identifier of each operation constant to its value, so +// the AST scan above can turn `OpCloseIssue` into "closeIssue" without a second +// hand-kept copy of the pairing. +func opConstants() map[string]string { + out := map[string]string{} + for op := range opCapability { + // The identifier is Op + the operationId with an upper-case initial. + out["Op"+strings.ToUpper(op[:1])+op[1:]] = op + } + // The two identity operations are on the map with an empty token, so the + // loop above already covered them. + return out +} diff --git a/tools/bazel/go_srcs.py b/tools/bazel/go_srcs.py index 1386f6143..763e46264 100755 --- a/tools/bazel/go_srcs.py +++ b/tools/bazel/go_srcs.py @@ -40,6 +40,7 @@ PACKAGES = ( "cmd/bd", # //cmd/bd:bd_test (capability registry, journal, serve scans) "cmd/bd/doctor", # //cmd/bd:bd_test (events-journal construction scan) "cmd/bd/doctor/fix", # //cmd/bd:bd_test (events-journal construction scan) + "internal/httpclient", # //internal/httpclient/wire:wire_test (handshake/skew AST sweep) "internal/types", # role facade alias targets "issueops", # //backend/conformance (role facade census) "journalops", # //backend/conformance (role facade census)