Documentation
¶
Overview ¶
Package omnisearch owns every `$search` URL: the server-rendered results page and the JSON the header omnibar consumes.
A query is free text plus any number of `key:value` qualifiers. One selector answers it, and names where the answer came from — the chain, or a configured indexer. Indexer-backed selectors exist only when one is configured. See gno.land/adr/pr6231_gnoweb_indexer.md.
Index ¶
- Constants
- Variables
- func NewPageView(data SearchData) *components.View
- func QueryTerm(u *weburl.GnoURL) string
- type ClientAdapter
- type Deps
- type Directory
- type Filter
- type FilterKeyword
- type Group
- type Handler
- type Indexer
- type IndexerStatus
- type KeywordGroup
- type Limiter
- type Query
- type RailLink
- type Result
- type ResultKind
- type Scope
- type SearchData
- type Selector
- type Source
Constants ¶
const ( // MaxQueryLen fits a couple of qualifiers plus a bech32 address. MaxQueryLen = 256 // Past a handful, qualifiers stop narrowing and start being free work. MaxFilters = 8 // Below MinTermLen a query matches most of the chain. MinTermLen = 2 // MaxResults caps one group: relevant, not exhaustive. MaxResults = 20 )
Input bounds. A search box is attacker-controlled and every resolver turns its terms into a chain or indexer query, so it is screened before any fetch. Mirrors ADR-003 §Resource bounds.
const ( FilterAuthor = "author" FilterIn = "in" FilterIs = "is" )
Narrowing qualifiers refine a search without choosing what is searched. Listed so an unrecognised one is reported as a typo, not ignored.
const ( CompleteNamespace = "namespace" CompletePath = "path" )
The lists the omnibar already holds, which it suggests a filter's values from.
const ( // GroupText searches text: rendered pages, deployed source. GroupText = "text" // GroupLookup finds one thing by its key: a transaction, a block. GroupLookup = "lookup" // GroupNarrow is the narrowing qualifiers. GroupNarrow = "narrow" )
The keyword lists group the keywords that work anywhere by what they do. The scope already groups those about a package.
const OmnisearchViewType = components.SearchViewType
OmnisearchViewType tags the body view.
Variables ¶
var ( // ErrQueryTooLong reports a `q` over MaxQueryLen. ErrQueryTooLong = errors.New("query too long") // ErrTooManyFilters reports more than MaxFilters qualifiers. ErrTooManyFilters = errors.New("too many search qualifiers") // ErrQueryInvalid rejects rather than strips: the value round-trips into // HTML and log lines, where a CR or LF is someone else's bug. ErrQueryInvalid = errors.New("query contains control characters") )
Functions ¶
func NewPageView ¶
func NewPageView(data SearchData) *components.View
NewPageView wraps the results page so callers in gnoweb's Get pipeline can compose it inside IndexLayout via the standard (status, *components.View) return shape.
Types ¶
type ClientAdapter ¶
type ClientAdapter interface {
Realm(ctx context.Context, path, args string) ([]byte, error)
Doc(ctx context.Context, path string, height int64) (*doc.JSONDocumentation, error)
ListFiles(ctx context.Context, path string, height int64) ([]string, error)
}
ClientAdapter is the subset of gnoweb.ClientAdapter this feature consumes, declared locally to avoid a back import (gnoweb imports omnisearch).
type Deps ¶
type Deps struct {
// Client answers the chain-backed selectors. Required.
Client ClientAdapter
// Directory lists realm and package paths for the discovery search.
// Required.
Directory Directory
// Indexer answers the indexer-backed selectors. Optional: nil means no
// indexer is configured and those selectors do not exist.
Indexer Indexer
// Domain is the chain's domain (e.g. "gno.land"), used to turn a gnoweb
// path into the fully qualified package path the chain indexes under.
Domain string
// Limiter bounds the per-IP request rate. Optional; nil disables the
// check.
Limiter Limiter
Logger *slog.Logger
}
Deps is a struct of interfaces so each field is independently mockable.
type Directory ¶
type Directory interface {
// Paths returns the realm and package paths, and whether the node capped
// the listing. Truncation travels with the answer because a silent cap
// is how a search comes to say "no such realm" about one that exists.
Paths(ctx context.Context) (realms, packages []string, truncated bool, err error)
}
Directory lists the chain's paths. Shaped after gnoweb's RealmDirectory so the wire-in passes the instance /search.json already uses, singleflight and semaphore included — qpaths is the most expensive RPC gnoweb makes.
type FilterKeyword ¶
type FilterKeyword struct {
Name string `json:"name"`
Hint string `json:"hint"`
Label string `json:"label"`
Help string `json:"help"`
Scope Scope `json:"scope"`
Group string `json:"group"`
Source Source `json:"source"`
// Values is every value the filter takes, when there are few.
Values []string `json:"values,omitempty"`
// Complete names the list the omnibar suggests values from.
Complete string `json:"complete,omitempty"`
}
FilterKeyword describes a narrowing qualifier for the keyword lists: the results page's and the omnibar's, so both offer the same ones.
type Group ¶
type Group struct {
Label string
Source Source
Results []Result
// Err renders as a failure rather than being dropped: "could not ask" is
// not "nothing matched".
Err error
// Truncated marks a partial answer: more may exist than Results holds.
// Notice says why, in the reader's terms.
Truncated bool
Notice string
}
Group is one answered subject: several for a discovery search, one when a selector chose the subject.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler owns every `$search` URL.
func New ¶
New validates required deps and returns a Handler. The selector table is built once: which selectors exist is a property of the deployment.
func (*Handler) Handle ¶
func (h *Handler) Handle(ctx context.Context, w http.ResponseWriter, r *http.Request, u *weburl.GnoURL) (int, *components.View)
Handle is the entry point for every `$search` URL. A nil view return means the body has already been written.
type Indexer ¶
type Indexer interface {
LatestBlockHeight(ctx context.Context) (int, error)
TxByHash(ctx context.Context, hash string) (*indexer.Tx, error)
RecentByPackage(ctx context.Context, pkgPath string, limit int) ([]indexer.Tx, error)
RecentByAddress(ctx context.Context, addr string, limit int) ([]indexer.Tx, error)
Deploys(ctx context.Context, pkgPath string, limit int) ([]indexer.Tx, error)
SourceContains(ctx context.Context, text, author string, limit int) ([]indexer.Tx, error)
DeploysImporting(ctx context.Context, pkgPath string, limit int) ([]indexer.Tx, error)
Block(ctx context.Context, height int) (*indexer.Block, error)
}
Indexer is the subset of *indexer.Client this feature consumes. A nil Indexer is the feature switch: New registers the indexer-backed selectors only when one is present.
type IndexerStatus ¶
type IndexerStatus struct {
LastBlock int
// Err makes the footer say the freshness is unknown rather than omit it.
Err error
}
IndexerStatus is the provenance footer: indexer results are not consensus data, so the reader gets how far behind it is. Not the endpoint, which is often a host the reader cannot reach.
type KeywordGroup ¶
KeywordGroup heads one group of the keyword lists.
type Limiter ¶
Limiter is the admission check applied before any fetch. It takes the request, not an address: which address to trust depends on which proxies to trust, and that rule belongs with the limiter. Nil disables the check.
type Query ¶
type Query struct {
// Raw is the validated input, as typed; Text is what is left once the
// qualifiers are removed.
Raw string
Text string
Filters []Filter
// PkgPath is gnoweb-relative ("/r/demo/boards"), the form Doc/ListFiles
// take and every href is built from. ChainPath is the same package
// domain-qualified, the form the chain and the indexer use. Not
// interchangeable.
PkgPath string
ChainPath string
// contains filtered or unexported fields
}
Query is a parsed search input: any number of `key:value` qualifiers plus the free text left over.
func ParseQuery ¶
ParseQuery validates and tokenises a raw `q` value. Each qualifier splits on its FIRST colon only: a value may legitimately contain one.
func (*Query) HasBareWord ¶
HasBareWord matches a no-argument selector typed as a bare word.
type Result ¶
type Result struct {
Title string
Detail string
// Opaque says Detail ends in an address or a hash, which a reader tells
// by both ends: that word is cut in its middle. Prose is left whole.
Opaque bool
// Kind says what the row names, for what its link cannot tell.
Kind ResultKind
// Href is typed so escaping is enforced by construction. Empty when the
// row has no destination.
Href template.URL
// Tags are short badges. Provenance is not among them — it belongs to
// the group, and Group.Source carries it once.
Tags []string
}
Result is one row in the results list.
type ResultKind ¶
type ResultKind int
ResultKind is what a row names when its link does not say: a transaction links to the package it touched, a block or a standard library import nowhere. The zero value leaves it to the link.
const ( KindTx ResultKind = iota + 1 KindBlock KindImport )
type SearchData ¶
type SearchData struct {
Query string
// QueryIsLabel: the query is a bare keyword its group's heading already
// names, so the title does not repeat it.
QueryIsLabel bool
// PkgPath is the scoped package, gnoweb-relative; empty when the URL
// names none.
PkgPath string
// PagePath is the package the query names, by in: or by the page. A
// search that ignores the package clears PkgPath, not this: the keywords
// about it still work there.
PagePath string
// WholeChainHref, set on a scoped discovery search, repeats it without
// the scope.
WholeChainHref string
Groups []Group
// Selectors is the honest inventory of what this deployment can answer.
Selectors []*Selector
// UnknownFilter names a qualifier that is neither a selector nor a
// narrowing keyword, so the page can say so instead of showing nothing.
UnknownFilter string
// Indexer is set only when an indexer-backed group ran; nil drops the
// provenance footer entirely.
Indexer *IndexerStatus
// RailTitle and RailLinks are what the rail offers under the counts: the
// package's keywords on a package page, a few queries to try when there
// is no answer. Empty otherwise: the counts are enough.
RailTitle string
RailLinks []RailLink
}
SearchData is the render payload for templates/page.html — field names must match the template.
func (SearchData) HasErrors ¶
func (d SearchData) HasErrors() bool
HasErrors reports a group that could not answer: "Nothing matched." under "Could not answer" would contradict it.
func (SearchData) HasResults ¶
func (d SearchData) HasResults() bool
HasResults tells "nothing matched" from "nothing was asked".
type Selector ¶
type Selector struct {
// Name is the qualifier key, e.g. "tx" in `tx:9f2a`.
Name string
// Hint is the form shown in the omnibar's suggestion list.
Hint string
// Label heads the selector's results group; Help says what it does,
// beside the hint in the keyword lists.
Label string
Help string
Scope Scope
// Group heads the keyword in the keyword lists, when its scope is global.
Group string
// Source is stamped by register from the table the selector is in, not
// by the literal. See Handler.register.
Source Source
// Bare marks a selector typed without a colon (`imports`, `activity`).
Bare bool
// MinTerm raises MinTermLen where the term's selectivity sets the cost.
MinTerm int
// PageOnly keeps a fan-out selector off the per-keystroke JSON path.
PageOnly bool
// Accepts matches a value this selector answers when it is typed alone,
// without its key: a pasted address is an `account:` search. The JSON
// answer carries it, so the omnibar asks the server for the same input.
Accepts *regexp.Regexp
// contains filtered or unexported fields
}
Selector chooses what a query searches. Exactly one runs per query — running all of them would turn one keystroke into a dozen queries.