MB-65018 add custom_filter/custom_score query nodes with context-driven callback hooks

[maneuvertomars]

This PR adds two new query node types in Bleve: custom_filter and custom_score, both wrapping an inner query.
Execution is embedding-driven via request-scoped context hooks (CustomFilterFactory / CustomScoreFactory) so Bleve remains engine-agnostic.
custom_filter applies per-hit keep/drop logic through FilteringSearcher; custom_score applies per-hit score mutation through ScoreMutatingSearcher.

[coveralls]

coverage: 52.636% (-0.06%) from 52.691%
when pulling 6aea7ea on MB-65018
into f7b13b9 on master.

[CascadingRadium]

I would argue that passing a callback function in the context object is very flaky, and difficult for library users to add directly to their application.

Also if no FilterHook is defined we should not error out i feel and just do unfiltered search.

Why not try this?

func (q *CustomFilterQuery) Searcher(ctx context.Context, i index.IndexReader, m mapping.IndexMapping, options search.SearcherOptions) (search.Searcher, error) {
	// Build the inner searcher first; custom filtering wraps its output.
	childSearcher, err := q.QueryVal.Searcher(ctx, i, m, options)
	if err != nil {
		return nil, err
	}
    // Check if the factor hook is registered
    if FilterHook == nil {
        // No filtering hook registered => no filtering to be done
        // Just return the child searcher itself
        return childSearcher, nil
    }
    filterFunc, err := filterFactory(q.Source, q.Params, q.Fields)
	if err != nil {
		return nil, err
	}
}

[maneuvertomars]

I think we should fail fast here rather than silently bypass custom_filter/custom_score. If a query explicitly contains a custom node and no hook is registered, returning the child searcher would change query semantics and produce incorrect results. The context-carried hook is intentional so the execution runtime stays request-scoped and embedder-defined, while Bleve remains generic.

[CascadingRadium]

Query as the param name perhaps?

[CascadingRadium]

Is a nil Fields param value valid?

[maneuvertomars]

Yes, nil/empty Fields is valid by design. It means no stored fields are loaded into doc.fields; I clarified that in the field comments.

[CascadingRadium]

Since a nil or empty source is invalid we should not have omitempty

[CascadingRadium]

to allow for easier extensibility of the struct, we can have a local copy of the struct here right?

type inner struct {
	Query  Query                  `json:"query"`
	Fields []string               `json:"fields,omitempty"`
	Params map[string]interface{} `json:"params,omitempty"`
	Source string                 `json:"source"`
}

return util.MarshalJSON(struct {
	CustomFilter inner `json:"custom_filter"`
}{
	CustomFilter: inner{
		Query:  q.QueryVal,
		Fields: q.Fields,
		Params: q.Params,
		Source: q.Source,
	},
})

[maneuvertomars]

Makes sense. I switched MarshalJSON() to use a typed local wrapper so the JSON shape stays explicit and easier to extend.

[CascadingRadium]

Instead of having these types and having library users pass in a function in context, consider this.

var (
  filterFactory CustomFilterFactory
  scoreFactory  CustomScoreFactory
)

func SetFilterFactory(f CustomFilterFactory) {
    filterFactory = f
}

func SetScoreFactory(f CustomScoreFactory) {
    scoreFactory = f
}

// usage from a bleve API POV 

```go
bleve.SetFilterFactory(f)
bleve.SetFilterFactory(f)
// can avoid context overhead entirely

[maneuvertomars]

That would make the hook registration package-global in Bleve, whereas the current design keeps the execution hook request-scoped and explicit at search time. I’d prefer avoiding Bleve-level global mutable state here; the context handoff is small, aligns with existing search-time context usage, and keeps the embedder control per request.

[CascadingRadium]

ditto, same as before - can avoid context ops by a simple global var init.

[maneuvertomars]

Same reasoning here. I’d prefer keeping this request-scoped rather than introducing Bleve-level global mutable hooks. The context lookup cost is negligible relative to search/execution, and the current design keeps the embedder control explicit per request.