recordresults

type HierarchyColumns struct {
	ID     string
	Parent string
}

type OpenOptions struct {
	// Prefix and ConnectionName name the result profiles and the index
	// connection, as RegistryOptions does.
	Prefix         string
	ConnectionName string

	// Settings say where the files live and how long a stream is kept. With no
	// Source, Settings.Backend is the local store to open, sqlite or ndjson —
	// resolve it first (Settings.Resolve).
	Settings recordstore.Settings

	// Source is a backend the caller routes itself, typically a
	// recordstore.Router over a kv store per tenant, or nil to open
	// Settings.Backend locally. A Source is always mirrored into a derived
	// index of its own, never into a file a route could also write, so one
	// route's streams cannot be read through another. Open owns Source: Close,
	// or a failed Open, closes it.
	Source recordstore.Backend

	// Schemas is the kind catalog the index and Register share. Pass one when
	// Source opens stores of its own that need it — a route's local sqlite
	// file resolves kinds the registry declares; nil makes a fresh one.
	Schemas *recordstore.Schemas

	// Register declares the result types the registry serves.
	Register func(*Registry) error
}

type RegisteredResultType struct {
	Kind    string `json:"kind"`
	Title   string `json:"title"`
	Profile string `json:"profile"`

	Views []RegisteredResultView `json:"views,omitempty"`
}

type RegisteredResultView struct {
	Name    string `json:"name"`
	Title   string `json:"title"`
	Profile string `json:"profile"`
}

type Registry struct {
	// contains filtered or unexported fields
}

type RegistryOptions struct {
	// Prefix names every result profile <prefix>/<kind>, and namespaces the
	// index connection.
	Prefix string

	// Schemas is the kind catalog Index resolves kinds through.
	// RegisterResultType fills it.
	Schemas *recordstore.Schemas

	// Index is the sqlite file result profiles read. It must have been opened
	// with Schemas.Kind as its schema.
	Index *sqlite.Backend

	// Source is the authoritative backend result streams are written to. The
	// registry constructs the Indexer that mirrors it into Index, so preparation
	// and profile reads cannot accidentally name different indexes. A result
	// type that follows its streams (ResultType.Follow) needs a
	// *recordstore.Notifier here, which captures must append through.
	Source recordstore.Backend

	// ConnectionName names the index's virtual connection,
	// connection://<prefix>/<name>.
	ConnectionName string
}

type ResultType[T any] struct {
	// Kind is the stream kind, and the last segment of the profile name.
	Kind string

	// Title is the human name of the result type.
	Title string

	// TimeColumn, when set, names T's datetime column: it becomes the table's
	// timestamp, the rows are ordered newest first, and the profile takes a
	// from/to time window over it in place of the column's own filter. Without
	// it rows are in seq order and there is no time window.
	TimeColumn string

	// DefaultFrom is where the time window starts when a request names no
	// from — date math such as now-12h, or RFC3339. Empty leaves the window
	// open, so a request with no from reads the whole stream. It needs a
	// TimeColumn.
	DefaultFrom string

	// KeyColumn, when set, names T's string column identifying a row within a
	// stream: a stream holds each key once, and appending a row whose key it
	// already holds skips the row (recordstore.KindOptions.Key).
	KeyColumn string

	// Retention says how long a stream of the type keeps its rows
	// (recordstore.KindOptions.Retention).
	Retention recordstore.Retention

	// Follow lets a session tail the type's streams: its profile reads through
	// the ProviderType provider, which streams each appended row, rather than
	// plain sqlite. Only a type whose rows each stand alone should follow — one
	// listed as the latest row per id would stream superseded rows.
	Follow bool

	// SearchColumns, when set, names T's text columns (string or JSON) a
	// search matches: the profile takes a search-role param q, and keeps the
	// rows where any of them contains its text, ignoring case.
	SearchColumns []string

	// Hierarchy identifies an invocation and its caller for root-only reads.
	Hierarchy *HierarchyColumns

	// Views are SQL profiles over the type's streams, each served as
	// <prefix>/<kind>/<view>. They read the index exactly as the type's own
	// profile does, but never follow, search or read roots only.
	Views []ResultView
}

type ResultView struct {
	// Name is a SQL identifier: the last segment of the view's profile,
	// <prefix>/<kind>/<name>, and the CTE a view using it reads.
	Name  string `yaml:"name"`
	Title string `yaml:"title"`

	// Uses names views of the same type compiled in first, AS MATERIALIZED.
	Uses []string `yaml:"uses,omitempty"`

	// Query is a SELECT, optionally WITH …, over stream_rows and the views it
	// uses. A view aggregates with GROUP BY: a correlated join or anti-join over
	// a stream of a hundred thousand rows runs for minutes.
	Query string `yaml:"query"`

	// Params are the view's own, in addition to stream, afterSeq and toSeq.
	Params []query.ParamDef `yaml:"params,omitempty"`

	Columns []query.ColumnDef `yaml:"columns"`

	// Order must end in a unique column, which is what pages it.
	Order query.Order `yaml:"order"`
}

type Results struct {
	// Backend is what a capture appends its rows to. Appending through it wakes
	// every session following the stream.
	Backend *recordstore.Notifier

	// Registry serves the result types over the index.
	Registry *Registry
	// contains filtered or unexported fields
}

type StoreLocation struct {
	Backend recordstore.BackendKind `json:"backend"`
	Host    string                  `json:"host,omitempty"`
	File    string                  `json:"file,omitempty"`
}

type StreamRef struct {
	Stream string `json:"stream"`
	Kind   string `json:"kind"`

	// Generation is the incarnation of the stream the seqs belong to.
	Generation string `json:"generation"`

	// Low and High are the committed seq bounds when the ref was taken.
	Low  int64 `json:"low"`
	High int64 `json:"high"`

	// From and To are the inclusive seq window the ref names: a step's
	// checkpoint, or Low..High.
	From int64 `json:"from"`
	To   int64 `json:"to"`

	Total     int64      `json:"total"`
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`

	Store StoreLocation `json:"store"`
}