Documentation
¶
Overview ¶
Package returnshape applies a resolved `return` plan to a finished Response. It is the runtime half of response shaping: the facade resolves the plan (internal/descriptor.ResolveReturn — the pass predict runs) and calls Apply on the response it is about to hand back. Apply works on ONE Response, so every surface that returns responses (Process today; Compose slots, chain stages and streamed rows next) shapes through it. ApplyComposed and ApplyChain are the multi-response roots built on it.
Shaping runs at the OUTERMOST facade only, never inside Service.Process: Compose overlays and chain stages re-enter the service and read the finished, unshaped responses.
Index ¶
- func Apply(resp *types.Response, plan *returnplan.Plan)
- func ApplyChain(out *types.ChainResponse, stagePlans []*returnplan.Plan)
- func ApplyComposed(out *types.ComposedResponse, slotPlans []*returnplan.Plan, ...)
- func MarshalRow(resp *types.Response, row map[string]any) ([]byte, error)
- func MarshalStreamRow(iter any, row map[string]any) ([]byte, error)
- type RowIter
- func (it *RowIter) Close() error
- func (it *RowIter) Components() *types.ResponseComponents
- func (it *RowIter) MarshalRow(row map[string]any) ([]byte, error)
- func (it *RowIter) Metadata() *types.ResponseMetadata
- func (it *RowIter) Next(ctx context.Context) (map[string]any, bool, error)
- func (it *RowIter) Returned() *types.ReturnedMarker
- func (it *RowIter) Warnings() []*types.ResponseWarning
- type Source
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Apply ¶
func Apply(resp *types.Response, plan *returnplan.Plan)
Apply shapes resp under plan in place. A nil or identity plan changes nothing (the byte-identity fast path). Otherwise every excluded slot is pruned from the Go value, the plan is attached so the response's MarshalJSON writes only the selected parts, an Open include that matched nothing raises PULSE_RETURN_PATH_UNMATCHED on resp.Warnings (unless the plan excludes warnings), and resp.Returned stamps the selection.
func ApplyChain ¶
func ApplyChain(out *types.ChainResponse, stagePlans []*returnplan.Plan)
ApplyChain shapes a finished chain in place: stage i under stagePlans[i]. Call it only after the WHOLE chain (and its overlay barrier) completed, so no later stage reads pruned rows. Final aliases the last stage, so it follows the last stage's plan; it is never shaped twice.
func ApplyComposed ¶
func ApplyComposed(out *types.ComposedResponse, slotPlans []*returnplan.Plan, top *returnplan.Plan)
ApplyComposed shapes a finished Compose result in place: slot i under slotPlans[i] (Apply; a missing or nil plan leaves the slot whole) and the top-level overlays under top, the Compose-level plan rooted at ComposedResponse. Call it only after the overlay and multiplicity folds, so every layer was computed from the unshaped slots. A non-identity top plan stamps ComposedResponse.Returned; the top level has no warnings slot, so an unmatched Open include there is not reported.
func MarshalRow ¶
MarshalRow writes row, one element of resp.Data (or a row streamed under resp's plan), as its wire form: under resp's plan when it was shaped (precision applied; the row is assumed already pruned), else exactly types.MarshalFinite(row).
func MarshalStreamRow ¶
MarshalStreamRow writes a row drawn from iter: through iter's MarshalRow when it has one (the shaped iterator, or a wrapper that forwards to it), else exactly types.MarshalFinite(row) — so an unshaped stream is byte-identical.
Types ¶
type RowIter ¶
type RowIter struct {
// contains filtered or unexported fields
}
RowIter shapes a streamed Process under a resolved, non-identity plan — the streaming arm of Apply:
- every row is a deep CLONE of the inner iterator's row (a streaming iterator may reuse its maps) pruned exactly as a buffered shaped response prunes one `data` element; when the plan excludes `data` the stream yields no rows (the inner iterator is still drained, so its terminal parts complete);
- Components and Metadata are shaped COPIES — the inner iterator's running state is never touched, so an excluded mergeable operator keeps accumulating; an excluded slot is nil. The shaped Components carries the plan, so its JSON equals the buffered shaped response's `components` (precision included);
- Returned stamps the selection, and only once the stream is exhausted (terminal flush).
Precision is wire-only: rows stay full float64 in Go, and MarshalRow writes one at the plan's precision.
func (*RowIter) Components ¶
func (it *RowIter) Components() *types.ResponseComponents
Components returns the inner components shaped under the plan (nil when excluded); see RowIter. Cached per inner pointer, so a buffered inner is shaped once.
func (*RowIter) MarshalRow ¶
MarshalRow writes one row this iterator yielded at the plan's precision (count columns exact, NaN / ±Inf null).
func (*RowIter) Metadata ¶
func (it *RowIter) Metadata() *types.ResponseMetadata
Metadata returns the inner metadata shaped under the plan (nil when excluded).
func (*RowIter) Returned ¶
func (it *RowIter) Returned() *types.ReturnedMarker
Returned is the selection marker, nil until the stream is exhausted.
func (*RowIter) Warnings ¶
func (it *RowIter) Warnings() []*types.ResponseWarning
Warnings forwards the inner iterator's run-time warnings (nil when it has none, or when the plan excludes `warnings` — the buffered shaped response drops them the same way).
type Source ¶
type Source interface {
Next(ctx context.Context) (map[string]any, bool, error)
Close() error
Metadata() *types.ResponseMetadata
Components() *types.ResponseComponents
}
Source is the method set of service.RowIter, restated so this package need not import the service (a service.RowIter satisfies it, and the shaped RowIter below satisfies service.RowIter in turn).
func NewRowIter ¶
func NewRowIter(inner Source, plan *returnplan.Plan) Source
NewRowIter wraps inner under plan. A nil or identity plan returns inner unchanged (the byte-identity fast path) — the result is then whatever inner is.
Source Files