Offset and MaxRows were mirror-image splits: the unit-of-work seam honored
Offset and refused MaxRows; the two store legs did the opposite. Three contract
cases absorbed that with an "either HONORED or REFUSED with a typed
*ErrUnsupported" disjunction.
A contract that asserts a capability is either honored or refused is not pinning
semantics — it is ratifying a split. All three are gone, along with
assertReaderUnsupported. Converging upward rather than uow-matches-server is the
owner's one ratified exception, because the server refusing MaxRows was a
capability gap rather than a semantics choice.
Offset now runs in the shared page epilogue on every leg rather than in whichever
seam could render it: the skip must happen in the caller's display order, which
is not SQL-expressible for --sort id, and a row the database skips is a row the
query matched.
Two bugs fixed under it.
The panic: domain/db rendered LIMIT 18446744073709551615 OFFSET k for an
unbounded query, and Dolt sized a buffer from limit+offset and returned a
recovered makeslice panic instead of rows. The contract case had been shaped
around it, bounding every request, with a comment calling it a storage-seam bug
that predates the role. It now drives the unbounded shape.
The breaker hole, found by review: proxied bd list --watch with an offset and a
cap counted the cap against post-skip rows while the page route counted
pre-skip, so the same flags produced opposite verdicts — L=10, k=2, M=3 over 5
rows returned a page on one route and ErrTooManyRows on the other. Newly
reachable since 3b2385922 removed the proxied --max-rows rejection ahead of the
watch dispatch, and it falsified the comment claiming no caller combines an
offset with a cap.
MaxRows semantics are now ratified and documented: the cap counts the rows the
query TOUCHED (offset+limit), not the rows the caller receives. A skipped row is
still a matched row. Review reported the Limit+Offset == MaxRows boundary as an
off-by-one; measured under those semantics the code was already correct and the
doc was wrong, so the fix was the doc plus pinning the behaviour.
A seventh cannot-fail test was caught mid-slice: an unreachable "under a
defensive cap" branch in searchWindowFor absorbed the exact regression the new
MaxRows-behind-offset arm exists to catch, and the mutation returned
INCONCLUSIVE. Removed.
Equivalence of the epilogue skip to a SQL OFFSET was checked rather than
assumed. One narrow uncovered exception stands: under --sort title, SQL
collation and Go byte-compare can disagree on non-ASCII and then pick different
skip sets. Conformance seeds ASCII.
148 lines
7.8 KiB
Go
148 lines
7.8 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
)
|
|
|
|
// QueryRequest describes one boolean-expression query: the question `bd query`
|
|
// asks, plus the page it wants back.
|
|
//
|
|
// THE EXPRESSION IS THE PREDICATE, and that is what makes this request unlike
|
|
// every other one here. CountRequest, ListRequest and ReadyRequest spell their
|
|
// predicate as FIELDS — one per filter, ANDed together — and a caller composes
|
|
// them by setting more of them. This request carries a SENTENCE, in the query
|
|
// mini-language `bd query` publishes, and that language has OR, NOT and
|
|
// parentheses, which no conjunction of fields can express. Parsing, evaluation
|
|
// and the choice of how to execute the result all happen inside; a caller says
|
|
// what it wants matched and never how the match is shaped.
|
|
type QueryRequest struct {
|
|
// Expression is the query, in the language `bd query --help` documents:
|
|
// field comparisons (`status=open`, `priority>1`, `created>7d`) combined
|
|
// with AND, OR, NOT and parentheses.
|
|
//
|
|
// It is parsed INSIDE. An expression that is blank, unparseable, or that
|
|
// names a field or operator the language does not have is ErrValidation
|
|
// naming the fault, never an empty page: a caller that misspelled a field
|
|
// and got zero rows back has no way to tell that from a store with nothing
|
|
// in it.
|
|
Expression string
|
|
|
|
// IncludeClosed admits closed issues, which the query otherwise hides.
|
|
//
|
|
// THE HIDING IS CONDITIONAL, and the condition is part of this contract
|
|
// because both front doors have always applied it: closed rows are
|
|
// excluded UNLESS this is set, or unless the expression itself compares
|
|
// `status`. So `status=closed` answers with closed rows on its own, and
|
|
// `NOT status=open` does too — an expression that has an opinion about
|
|
// status keeps it, and only an expression with none gets the default. The
|
|
// flag `bd query --all` sets is this one.
|
|
IncludeClosed bool
|
|
|
|
// SortBy names the display order and Reverse inverts it, over the same
|
|
// vocabulary ListRequest.SortBy takes. Empty leaves the rows in the order
|
|
// the query returned them.
|
|
//
|
|
// WHAT THE ORDER IS APPLIED TO depends on what bounded the query, and the
|
|
// difference is worth stating because it is observable. The order is
|
|
// applied to the rows the QUERY bounded, then the page is cut from them —
|
|
// the epilogue `bd list` runs (workapi.FinishPage). For a
|
|
// filter-expressible query the database applied Limit, so the order sorts
|
|
// the page. For a PREDICATE query nothing bounded the query — see
|
|
// Querier.Query — so the order sorts the whole matching set and the page
|
|
// is its head. `bd list` has the same split for the same reason: a sort
|
|
// SQL cannot express fetches everything and trims afterwards.
|
|
SortBy string
|
|
Reverse bool
|
|
|
|
// Limit bounds the page the caller RECEIVES. Nil means the shared query
|
|
// default; 0 means unlimited. It is a pointer so that "unset" and
|
|
// "explicitly unlimited" stay distinguishable, which is what lets one
|
|
// constant serve both surfaces. A negative Limit is ErrValidation rather
|
|
// than a synonym for unlimited: two spellings of "no bound" is one more
|
|
// than a caller can check for.
|
|
Limit *int
|
|
|
|
// Offset skips the first N MATCHING rows, on EVERY implementation and for
|
|
// EVERY shape of expression, exactly as ListRequest.Offset does. A
|
|
// negative Offset is ErrValidation everywhere.
|
|
//
|
|
// IT IS UNIFORM, not per-expression, and that is a decision rather than an
|
|
// accident of the seams. One body renders SQL OFFSET for a
|
|
// filter-expressible query and the other reaches past the skipped rows and
|
|
// drops them in Go; both skip in Go for a predicate query, which is
|
|
// unbounded and has nothing to push down. Which shape an expression takes
|
|
// is decided by the evaluator, not by the caller, so an Offset that
|
|
// behaved differently for `type=bug OR type=task` than for `type=bug`
|
|
// would be unpredictable from the outside. One answer everywhere is the
|
|
// only checkable promise.
|
|
//
|
|
// IT SKIPS MATCHES — never candidate rows. A skip
|
|
// applied before the predicate would discard rows the predicate would have
|
|
// rejected anyway and hand back a short page, which is the failure that
|
|
// made `bd query --offset` refuse OR queries outright.
|
|
//
|
|
// AN OFFSET WITH A SortBy IS ErrValidation, at every backend. The order is
|
|
// applied to the rows the query BOUNDED (see SortBy), so under a page
|
|
// bound each page is sorted for itself: a walk with an offset would neither
|
|
// visit every row nor visit any row once. Refusing the combination is the
|
|
// only answer that is true on both shapes of query; accepting it would mean
|
|
// publishing a walk that silently is not one.
|
|
Offset int
|
|
}
|
|
|
|
// Querier answers boolean-expression queries: the operation `bd query`
|
|
// performs, and — like Counter, Reader and ReadyCounter — a role with its own
|
|
// accessor. A new capability gets a new role interface and its own accessor;
|
|
// never append a method here.
|
|
//
|
|
// IT IS ITS OWN ROLE RATHER THAN A SHAPE OF Reader.List because the two take
|
|
// predicates that are not the same KIND of thing. A ListRequest is a
|
|
// conjunction: every field it carries narrows the answer, and there is no
|
|
// arrangement of them that expresses "type=bug OR label=urgent", let alone
|
|
// "NOT (priority<2 AND assignee=none)". Handing this expression to List would
|
|
// mean either adding a free-text member to ListRequest — a field the other
|
|
// eleven callers must ignore, on the request type this library's largest
|
|
// surface already shares — or teaching List a second execution mode. The
|
|
// question is different, so the role is.
|
|
//
|
|
// EQUALLY, IT IS NOT A RAW QUERY PASSTHROUGH. The language has no SQL in it:
|
|
// no table names, no joins, no ORDER BY, no way to name a column the
|
|
// vocabulary does not publish. It is a closed set of fields over one row
|
|
// shape, which is why a role can promise anything about it at all.
|
|
type Querier interface {
|
|
// Query returns the page of issues the expression matches.
|
|
//
|
|
// THE PREDICATE IS EVALUATED AGAINST THE WHOLE CANDIDATE SET. That
|
|
// sentence is the point of this method and the fix it shipped with.
|
|
//
|
|
// An expression the storage filter vocabulary can express — a comparison,
|
|
// a chain of ANDs, a NOT over status or type, an OR over labels — is
|
|
// executed by the database, which applies Limit itself. Every other
|
|
// expression is a PREDICATE query: the database is asked for the base
|
|
// filters the expression implies and the predicate is applied to the rows
|
|
// in Go. For those, the query is issued UNBOUNDED and the predicate sees
|
|
// every candidate row, so the page is the first Limit MATCHES of the
|
|
// complete matching set.
|
|
//
|
|
// It was not always. Both front doors used to bound that query at
|
|
// max(3*Limit, 100) rows and filter what came back, so a match beyond that
|
|
// window was absent from the page AND unreported by has-more: an OR query
|
|
// over a workspace of any size returned an arbitrary prefix of its answer
|
|
// and called it complete. The window is gone. What it cost is stated
|
|
// rather than hidden: a predicate query reads every row its base filters
|
|
// admit, so a broad expression over a large workspace is a large read.
|
|
//
|
|
// HasMore is true exactly when the page is shorter than the matching set,
|
|
// which for a predicate query it can now compute rather than guess.
|
|
//
|
|
// An expression that matches nothing is an empty page and a nil error —
|
|
// Items is never nil on a successful call. There is no ErrNotFound here:
|
|
// a question about a set has an answer even when the set is empty.
|
|
//
|
|
// Querying is a READ. Nothing here records a history entry, fires a
|
|
// completion hook or changes a row, and a refusal changes nothing either.
|
|
// Deterministic request-validation failures match ErrValidation, and
|
|
// result values are unspecified when error is non-nil. Implementations
|
|
// never mutate caller-owned request values.
|
|
Query(ctx context.Context, req QueryRequest) (IssuePage, error)
|
|
}
|