query

type ColumnDef struct {
	// Name is the row key this column reads from and the default header label.
	Name string `json:"name" yaml:"name"`

	// Label overrides the column header. Defaults to a prettified Name.
	Label string `json:"label,omitempty" yaml:"label,omitempty"`

	// Type is the semantic type used for formatting. Defaults to string.
	Type ColumnType `json:"type,omitempty" yaml:"type,omitempty"`

	// Kind enables specialized table behavior. In particular, timestamp marks
	// the column used by the table's date-range control.
	Kind ColumnKind `json:"kind,omitempty" yaml:"kind,omitempty"`

	// Format overrides the clicky format string (e.g. "date", "bytes",
	// "duration", "currency"). When empty it is derived from Type.
	Format string `json:"format,omitempty" yaml:"format,omitempty"`

	// Unit is an optional display unit (e.g. "ms", "MiB").
	Unit string `json:"unit,omitempty" yaml:"unit,omitempty"`

	// Width is an optional max display width in characters.
	Width int `json:"width,omitempty" yaml:"width,omitempty"`

	// CEL is an optional expression computing the cell value from the row.
	// The row is exposed as `row` in the CEL environment.
	CEL string `json:"cel,omitempty" yaml:"cel,omitempty"`

	// Hidden excludes the column from rendered output while keeping it available
	// to CEL and processors.
	Hidden bool `json:"hidden,omitempty" yaml:"hidden,omitempty"`
}

type ColumnKind string

type ColumnType string

type Event struct {
	SessionID string    `json:"sessionId"`
	Sequence  int64     `json:"sequence"`
	Time      time.Time `json:"time"`
	Row       Row       `json:"row,omitempty"`
	Rows      []Row     `json:"rows,omitempty"`
	Error     string    `json:"error,omitempty"`
}

type ParamDef struct {
	// Name is the parameter key, referenced in the query as `{{.params.<Name>}}`.
	Name string `json:"name" yaml:"name"`

	// Label is the human-facing name for the FilterBar. Defaults to Name.
	Label string `json:"label,omitempty" yaml:"label,omitempty"`

	// Type drives validation/coercion. Defaults to string.
	Type ParamType `json:"type,omitempty" yaml:"type,omitempty"`

	// Role maps the parameter to a first-class table control. Empty defaults to
	// filter. A profile can rename the pager parameters by assigning limit and
	// offset roles; time-from/time-to form one server-backed date-range picker.
	Role ParamRole `json:"role,omitempty" yaml:"role,omitempty"`

	// Default is used when no value is supplied.
	Default any `json:"default,omitempty" yaml:"default,omitempty"`

	// Options enumerates the allowed values (an enum). When set, a supplied value
	// must be one of these.
	Options []string `json:"options,omitempty" yaml:"options,omitempty"`

	// Required fails execution when no value (and no Default) is supplied.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`

	// Description is shown as the FilterBar tooltip.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Template optionally rewrites the resolved value; "{value}" is replaced with
	// the supplied value (e.g. "{value}-api").
	Template string `json:"template,omitempty" yaml:"template,omitempty"`
}

type ParamRole string

type ParamType string

type Processor interface {
	// Type is the registry key (e.g. "sqlite.merge", "sqlite.recon").
	Type() string

	// Process transforms in according to spec and returns the new Result.
	Process(ctx context.Context, spec ProcessorSpec, in *Result) (*Result, error)
}

type ProcessorSpec struct {
	// Type is the registered processor key (e.g. "sqlite.merge", "sqlite.recon").
	Type string `json:"type" yaml:"type"`

	// Config is the processor-specific configuration.
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
}

type Profile struct {
	// Name identifies the Profile (e.g. "SQL Server trace").
	Name string `json:"profile" yaml:"profile"`

	// Namespace scopes Kubernetes secret/configmap lookups and workload URLs used
	// by inline provider connections. When empty, the caller's namespace is used.
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Provider selects and configures the backend the Profile reads from.
	Provider ProviderConfig `json:"provider" yaml:"provider"`

	// Query is the provider-native query (SQL, PromQL, HTTP path, etc.). It may
	// reference declared params as `{{.params.<name>}}` (or `$(...)`), which are
	// rendered before the provider runs.
	Query string `json:"query,omitempty" yaml:"query,omitempty"`

	// Params declares the server-side filter parameters the Profile accepts. Their
	// resolved values are templated into Query (and context sub-queries) and drive
	// the per-profile FilterBar schema.
	Params []ParamDef `json:"params,omitempty" yaml:"params,omitempty"`

	// Columns declares the output columns in display order. When empty, the
	// provider's raw row keys are used.
	Columns []ColumnDef `json:"columns,omitempty" yaml:"columns,omitempty"`

	// Processors are post-query steps (e.g. sqlite merge/recon) applied in order.
	Processors []ProcessorSpec `json:"processors,omitempty" yaml:"processors,omitempty"`

	// Context defines secondary queries whose single result becomes a named side
	// object on the Result (e.g. Policy, Plan, Integrations).
	Context map[string]SubQuery `json:"context,omitempty" yaml:"context,omitempty"`

	// Output lists the render targets (e.g. table, html, xlsx, json).
	Output []string `json:"output,omitempty" yaml:"output,omitempty"`

	// Render selects how the frontend presents the result. "table" (the default,
	// when empty) uses the generic data table; "logs" maps the columns onto the
	// canonical LogsTable view (timestamp/level/pod/logger/thread/message, plus an
	// optional duration column) for trace/log profiles. Filtering stays server-side
	// via Params regardless of render mode.
	Render string `json:"render,omitempty" yaml:"render,omitempty"`

	// Trace declares the Profile as a long-running streaming session with
	// explicit setup/teardown; the provider must implement StreamProvider.
	// Mutually exclusive with Top.
	Trace *TraceSpec `json:"trace,omitempty" yaml:"trace,omitempty"`

	// Top declares the Profile as interval-sampled: the engine re-executes the
	// query per tick and each snapshot replaces the last. Mutually exclusive
	// with Trace.
	Top *TopSpec `json:"top,omitempty" yaml:"top,omitempty"`
}

type ProfileKind string

type Provider interface {
	// Type is the registry key (e.g. "sql", "http", "prometheus").
	Type() string

	// Execute runs req against the backend and returns the raw rows.
	Execute(ctx context.Context, req ProviderRequest) ([]Row, error)
}

type ProviderConfig struct {
	// Type is the registered provider key (e.g. "sql", "http", "prometheus").
	Type string `json:"type" yaml:"type"`

	// Connection references a connection (connection://name) or an inline DSN/URL.
	Connection string `json:"connection,omitempty" yaml:"connection,omitempty"`

	// Options carries provider-specific knobs.
	Options map[string]any `json:"options,omitempty" yaml:"options,omitempty"`
}

type ProviderRequest struct {
	// Connection references a connection (connection://name) or an inline DSN/URL.
	Connection string

	// Query is the provider-native query string.
	Query string

	// Options carries provider-specific knobs from ProviderConfig.Options.
	Options map[string]any

	// MaxRows is an execution hint for bounded callers such as an interactive
	// page. Streaming providers may use it to avoid opening a backend cursor
	// when one finite request can satisfy the caller. Zero means unbounded.
	MaxRows int
}

type QueryModel struct {
	// Table name
	Table string

	// Custom functions to map fields to clauses
	// Example: map["custom_field"] = func(ctx, tx, val) { ... custom query logic ... }
	Custom map[string]func(ctx context.Context, tx *gorm.DB, val string) (*gorm.DB, error)

	// List of jsonb columns that store a map.
	// These columns can be addressed using dot notation to access the JSON fields directly
	// Example: tags.cluster or tags.namespace.
	JSONMapColumns []string

	// List of columns that can be addressed on the search query.
	// Any other fields will be treated as a property lookup.
	Columns []string

	// Alias maps fields from the search query to the table columns
	// Example: map["created"] = "created_at"
	Aliases map[string]string

	// True when the table has a "tags" column
	HasTags bool

	// True when the table has a "labels" column
	HasLabels bool

	// True when the table has properties column
	HasProperties bool

	// FieldMapper maps the value of these fields
	// Example: map["created_at"] = DateMapper
	FieldMapper map[string]func(ctx context.Context, id string) (any, error)
}

type RegistryOptions struct {
	// MaxSessions caps concurrently active (starting/running) sessions.
	MaxSessions int // default 5

	// MaxDuration caps any session's run duration.
	MaxDuration time.Duration // default 15m

	// MaxEvents caps any session's ring buffer.
	MaxEvents int // default 10000

	// RetainDone is how many terminal sessions stay in memory before the
	// oldest are pruned.
	RetainDone int // default 50

	// OnEvent/OnTransition are installed on every session started through
	// ExecuteStream — the persistence hooks.
	OnEvent      func(Event)
	OnTransition func(SessionInfo)
}

type Result struct {
	// Profile is the name of the Profile that produced this Result.
	Profile string `json:"profile,omitempty" yaml:"profile,omitempty"`

	// Rows are the primary tabular records.
	Rows []Row `json:"rows" yaml:"rows"`

	// Context holds named side objects keyed by SubQuery name.
	Context map[string]any `json:"context,omitempty" yaml:"context,omitempty"`
}

type Row = map[string]any

type RowIterator interface {
	Next() bool
	Row() Row
	Err() error
	Close() error
}

type SampleResult struct {
	Rows          []Row       `json:"rows"`
	Columns       []ColumnDef `json:"columns"`
	RenderedQuery string      `json:"renderedQuery"`
	Truncated     bool        `json:"truncated,omitempty"`
	DurationMS    float64     `json:"durationMs"`
}

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

type SessionInfo struct {
	ID         string         `json:"id"`
	Profile    string         `json:"profile"`
	Kind       ProfileKind    `json:"kind"`
	State      SessionState   `json:"state"`
	Params     map[string]any `json:"params,omitempty"`
	Error      string         `json:"error,omitempty"`
	EventCount int64          `json:"eventCount"`
	StartedAt  time.Time      `json:"startedAt"`
	StoppedAt  *time.Time     `json:"stoppedAt,omitempty"`
}

type SessionOptions struct {
	ID      string
	Profile Profile
	Params  map[string]any

	// MaxEvents caps the in-memory ring buffer (already clamped by the caller).
	MaxEvents int

	// OnEvent is called synchronously for every emitted event (before ring
	// eviction can drop it) — the persistence hook.
	OnEvent func(Event)

	// OnTransition is called synchronously after every state change.
	OnTransition func(SessionInfo)
}

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

type SessionState string

type StreamProvider interface {
	Provider

	// Stream runs req, calling emit for each row until ctx is cancelled or the
	// source ends. It blocks; a nil return means the source ended normally.
	Stream(ctx context.Context, req ProviderRequest, emit func(Row)) error
}

type StreamingProvider interface {
	Provider
	OpenRows(ctx context.Context, req ProviderRequest) (RowIterator, error)
}

type SubQuery struct {
	Provider ProviderConfig `json:"provider" yaml:"provider"`
	Query    string         `json:"query,omitempty" yaml:"query,omitempty"`
}

type TopSpec struct {
	// Interval is the sampling period (default 5s, floor 1s).
	Interval types.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`

	// MaxDuration bounds the session; the server may clamp it lower.
	MaxDuration types.Duration `json:"maxDuration,omitempty" yaml:"maxDuration,omitempty"`

	// SortBy names the column each snapshot is sorted by (descending).
	SortBy string `json:"sortBy,omitempty" yaml:"sortBy,omitempty"`

	// Limit truncates each snapshot after sorting.
	Limit int `json:"limit,omitempty" yaml:"limit,omitempty"`
}

type TraceSpec struct {
	// MaxDuration bounds the session; the server may clamp it lower.
	MaxDuration types.Duration `json:"maxDuration,omitempty" yaml:"maxDuration,omitempty"`

	// MaxEvents caps the in-memory event ring buffer.
	MaxEvents int `json:"maxEvents,omitempty" yaml:"maxEvents,omitempty"`
}