Documentation
¶
Overview ¶
Package returnplan is the schema-free core of response shaping (`Request.Return`): the path grammar, the compiled selection plan and its digest, and the per-node verdict a pruner or wire encoder asks while walking a response.
It imports the standard library only (TestReturnPlan_ImportBoundary), so the public `types` package can carry a *Plan in an unexported field without growing a dependency, and both the no-execute descriptor layer and the engine can share it. Schema knowledge — which paths exist, which an instance hides, which data columns a request produces — lives in internal/descriptor (ResolveReturn), never here.
Index ¶
Constants ¶
const DigestPrefix = "rp1:"
DigestPrefix versions the digest scheme ("rp1:" + sha256 hex).
const PresetCustom = "custom"
PresetCustom is the Plan.Preset of a block that names no preset but selects (include) or carves (exclude) explicitly.
Variables ¶
This section is empty.
Functions ¶
func SetApplier ¶
func SetApplier(a Applier)
SetApplier installs the applier. Called once, from package types' init.
func SetRowEncoder ¶
func SetRowEncoder(e RowEncoder)
SetRowEncoder installs the row encoder. Called once, from package types' init.
Types ¶
type Applier ¶
Applier prunes target (a *types.Response) under p in place, attaches p to it so its wire encoder honours the plan, and returns the Open include paths that matched no concrete node. ok is false when target is not a type the applier knows.
type Path ¶
type Path struct {
Segments []Segment
// Open is set by the schema resolver when the path steps through a
// map key or an open (`any`) value, whose keys predict cannot know:
// at runtime such an include may match nothing (the
// PULSE_RETURN_PATH_UNMATCHED warning). Not part of the canonical
// form.
Open bool
}
Path is a parsed Return path.
func Apply ¶
Apply runs the installed applier; ok is false when none is installed or it does not know target's type.
func Parse ¶
Parse reads one path. The grammar:
path = name *( "." name / "[*]" ) name = 1*char [ "*" ] / "*" ; char: anything but . [ ] *
A path starts with a name (the Response root is an object). `[*]` is the only array step — no numeric index. `*` may appear only as the last character of a name, where it makes that segment a prefix glob. Whitespace is part of a name; nothing is trimmed.
func (Path) Matches ¶
Matches reports whether the pattern selects exactly the concrete node at c: same depth, every segment covering c's.
type Plan ¶
type Plan struct {
// Preset is the preset name the block resolved from, PresetCustom
// for an explicit include / exclude without one.
Preset string
// Include, Exclude and Keep are canonical: deduplicated, sorted by
// spelling, with every path another one already covers removed, an
// include an exclude covers removed, an exclude that touches no
// include or keep path removed, and a keep path an include covers
// removed.
Include []Path
Exclude []Path
Keep []Path
// Precision is the wire float significant-digit count, 0 unlimited.
Precision int
// Exact lists the REQUEST-DERIVED precision exemptions: nodes (and
// their subtrees) whose floats carry integer semantics for this
// request — a count aggregation's data column, a count crosstab
// cell — written at full precision even when Precision is set. The
// resolver fills it (internal/descriptor/return_resolve.go); the
// response-type exemptions that hold for every request live beside
// the encoder (types/return_shape.go, precisionExempt). Derived from
// the request, never part of the selection, so outside the digest.
Exact []Path
// SelectsAll reports that Include covers every top-level key of the
// root, so the root itself is selected whole.
SelectsAll bool
// Digest identifies the resolved selection (Include, Exclude, Keep,
// Precision — not the preset name), so equivalent spellings share
// it.
Digest string
}
Plan is a resolved Return selection. Build one with New; the zero value selects nothing.
A concrete response node is emitted iff no Exclude path matches it or an ancestor, and either an Include path matches it or an ancestor (the whole subtree), or it is an ancestor of something an Include path selects (emitted as a container holding only selected children), or a Keep path matches it exactly and its parent is emitted. Keep paths are the "retained unless excluded" nested `warnings` slots: kept wherever their parent object appears, never conjured on their own.
func New ¶
New canonicalizes include / exclude / keep and computes the digest. rootKeys is every visible top-level key of the root object; an include set covering all of them selects the root whole.
type RowEncoder ¶
RowEncoder writes one result row (a streamed row, or one element of a Response's `data`) as its wire form under owner's plan — owner is the *types.Response the row belongs to (its plan is unexported). A nil owner, or one carrying no non-identity plan, writes the row exactly as the unshaped encoder does. Installed by package types at init, for the same reason as the Applier.
type Segment ¶
type Segment struct {
// Name is the JSON key, or the glob PREFIX when Glob is set (so
// `effect_*` is Name "effect_" with Glob true; `*` alone is Name ""
// with Glob true). Empty for an Index segment.
Name string
// Glob marks a suffix `*` map-key glob.
Glob bool
// Index marks the `[*]` array wildcard.
Index bool
}
Segment is one step of a path: an object or map key (Name, optionally a suffix-glob prefix when Glob is set) or an array step (Index, the `[*]` wildcard over every element).
type SyntaxError ¶
SyntaxError reports a malformed path. Reason is short stable prose.
func (*SyntaxError) Error ¶
func (e *SyntaxError) Error() string
type Verdict ¶
type Verdict struct {
// Keep is false when the node is absent on the wire.
Keep bool
// Whole means the node's whole subtree is emitted untouched: the
// caller need not descend. Keep && !Whole means descend and ask for
// each child.
Whole bool
}
Verdict is the plan's answer for one concrete node.
Source Files