engine

type Approval struct {
	// Class is "read" or "read-pii".
	Class  string
	Header string
	// Note is the agent's reason (untrusted: the console escapes it).
	Note     string
	Body     []string
	Warnings []string
	// NeverAuto marks the console's own approval screen as one no auto
	// mode takes. In hub mode the ticket's never_auto flag is the
	// profile's auto rule's (auto.read, auto.unmask, auto.lookup:
	// logconsole), not this field.
	NeverAuto bool
	// Clear is the clear view of the screen's record (secrets and
	// redactions kept), for the console's own terminal only: the
	// console shows it when its clear-results switch (Ctrl-O) is on.
	// It never reaches the agent, nor a hub's masked screen: in hub mode
	// it goes sealed to the pinned devices only (the clear screen).
	Clear []string
	// HubBody, when set, replaces Body on the hub's masked screen: the
	// lines of Body that hold a clear value are left out of it (an
	// approved lookup's values). Body stays the console's screen and the
	// clear screen sealed to the devices.
	HubBody []string
	// Hash is the keyed plan hash the approval binds (HMAC under K_ref),
	// and Inputs its keyed input digests by name: what a hub ticket is
	// bound to (plans.Binding). Moving names the inputs a renewal cannot
	// check without reading the record again. None of them ever reaches
	// the agent.
	Hash   string
	Inputs map[string]string
	Moving []string
}

type Approver func(ctx context.Context, a Approval) error

type BudgetStatus struct {
	Local  *ClassBudget `json:"local,omitempty"`
	Remote *ClassBudget `json:"remote,omitempty"`
	// Sources is each source's own budget left.
	Sources []SourceBudget `json:"sources"`
	// LookupsLeft is the distinct values the console may still look up
	// this hour, for every peer together (-1: no limit).
	LookupsLeft int `json:"lookups_left"`
	// LookupsLeftPeer is what the calling peer (its uid) may still look
	// up this hour: its own limit within the console's (-1: no limit).
	// Absent outside an agent's call (the console's :status).
	LookupsLeftPeer *int `json:"lookups_left_peer,omitempty"`
	// Scans is the approved scans in progress on the console, every
	// peer's (at most MaxScans).
	Scans int `json:"scans"`
}

type Budgets struct {
	// LocalBytesPerHour and RemoteBytesPerHour bound the bytes processed
	// (plan-based, granule-rounded; remote: the bytes fetched) per rolling
	// hour, by each source and by the console's sources of that kind.
	LocalBytesPerHour, RemoteBytesPerHour int64
	// RemoteRequestsPerMinute paces the requests of free calls to a remote
	// backend (per source and per console).
	RemoteRequestsPerMinute int
	// MetricQueriesPerHour bounds the server-side metric queries of
	// counts answered by a remote backend.
	MetricQueriesPerHour int
	// LookupsPerHour and LookupsPerHourPerUID bound the distinct values
	// log.lookup resolves per rolling hour, for the console and for one
	// peer uid.
	LookupsPerHour, LookupsPerHourPerUID int
}

type ClassBudget struct {
	BytesPerHour      int64 `json:"bytes_per_hour"`
	BytesLeft         int64 `json:"bytes_left"`
	RequestsLeft      *int  `json:"requests_left_this_minute,omitempty"`
	MetricLeft        *int  `json:"metric_queries_left,omitempty"`
	RequestsPerMinute int   `json:"requests_per_minute,omitempty"`
}

type ClearMasker interface {
	MaskClear(source string, ev parse.Event) (mask.Record, map[string]string)
}

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

type ContextQuery struct {
	Ref    string   `json:"ref"`
	Before int      `json:"before,omitempty"`
	After  int      `json:"after,omitempty"`
	Fields []string `json:"fields,omitempty"`
}

type ContextResult struct {
	Epoch   string            `json:"epoch"`
	Records []json.RawMessage `json:"records"`
	Target  int               `json:"target"`
	// Complete is false when the output cap dropped the records farthest
	// from the target.
	Complete       bool    `json:"complete"`
	Scanned        Scanned `json:"scanned"`
	Masking        Masking `json:"masking"`
	MaskedFailures int     `json:"masked_failures,omitempty"`
}

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

type CountQuery struct {
	Query
	// Bucket is a duration ("5m"); empty: one bucket for the range.
	Bucket string `json:"bucket,omitempty"`
	// By groups by up to two trusted or pseudonymised line fields, and
	// ByLabels by source labels (Loki stream labels, journald and docker
	// attributes); at most MaxBy in all. A group's key holds the By
	// values, then the ByLabels values.
	By       []string `json:"by,omitempty"`
	ByLabels []string `json:"by_labels,omitempty"`
	// ByPattern also groups by the Template of the masked message (the
	// last key; null without a message). It counts as one of MaxBy and is
	// never served from the index.
	ByPattern bool `json:"by_pattern,omitempty"`
	// FirstLast adds each group's first and last timestamp.
	FirstLast bool `json:"first_last,omitempty"`
	// contains filtered or unexported fields
}

type CountResult struct {
	Epoch        string     `json:"epoch"`
	Groups       []Group    `json:"groups"`
	Untimed      int64      `json:"untimed,omitempty"`
	Complete     bool       `json:"complete"`
	CoveredUntil *time.Time `json:"covered_until,omitempty"`
	Cursor       string     `json:"cursor,omitempty"`
	Scanned      Scanned    `json:"scanned"`
	// FromIndex is set when the local index answered (part of) the
	// count; IndexedFrom is where the index starts.
	FromIndex      bool       `json:"from_index,omitempty"`
	IndexedFrom    *time.Time `json:"indexed_from,omitempty"`
	IndexedUntil   *time.Time `json:"indexed_until,omitempty"`
	MaskedFailures int        `json:"masked_failures,omitempty"`
	// A count whose groups do not fit one answer (Limits.MaxOutput) is
	// paged once it is whole: each page holds the next groups, in order,
	// from GroupsFrom of GroupsTotal, and a cursor to the rest (complete
	// on the last). A partial count (its scan goes on) shows the first
	// groups that fit, Truncated set, and OmittedGroups and OmittedN
	// what it left out for now.
	GroupsFrom    int   `json:"groups_from,omitempty"`
	GroupsTotal   int   `json:"groups_total,omitempty"`
	Truncated     bool  `json:"truncated,omitempty"`
	OmittedGroups int   `json:"omitted_groups,omitempty"`
	OmittedN      int64 `json:"omitted_n,omitempty"`
}

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

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	// Span is the JSON path of the offending part of the query.
	Span string `json:"span,omitempty"`
	// Estimate is the plan estimate of an over-budget call.
	Estimate *Estimate `json:"estimate,omitempty"`
	// contains filtered or unexported fields
}

type Estimate struct {
	Bytes    int64         `json:"bytes"`
	Granules int           `json:"granules"`
	Range    time.Duration `json:"range_ns"`
}

type ExposureCount func(epoch string, pseudonyms []string) (counts []int, exact bool, since time.Time)

type Group struct {
	Bucket time.Time  `json:"bucket"`
	Key    []*string  `json:"key,omitempty"` // masked values; null when absent
	N      int64      `json:"n"`
	First  *time.Time `json:"first,omitempty"`
	Last   *time.Time `json:"last,omitempty"`
}

type Limits struct {
	// Range of a query with text, regex or masked-field predicates.
	LocalRange, RemoteRange time.Duration
	// CountRange of a trusted-field-only count, RemoteCountRange of one a
	// remote source answers with its own counts (0: CountRange).
	CountRange, RemoteCountRange time.Duration
	// Bytes a call's plan may cost (admission).
	LocalBytes, RemoteBytes int64
	// Records per page (ceiling of limit) and output bytes per page.
	MaxRecords int
	MaxOutput  int
	// Deadline of one call.
	Deadline time.Duration
}

type LookupQuery struct {
	Kind   string   `json:"kind"`
	Values []string `json:"values"`
	Reason string   `json:"reason,omitempty"`
}

type LookupResult struct {
	Epoch      string   `json:"epoch"`
	Kind       string   `json:"kind"`
	Pseudonyms []string `json:"pseudonyms"`
}

type Lookuper interface {
	Lookup(kind, value string) (string, error)
	DetectorKinds() []string
}

type MaskFunc func(ev parse.Event)

type Masker interface {
	Mask(source string, ev parse.Event) mask.Record
	Text(s string) string
	// TrustedValue masks a trusted value read outside a record (index
	// values, values compared with trusted fields) as Mask masks a
	// trusted leaf at that path.
	TrustedValue(source, path, v string) string
	Epoch() string
}

type Masking struct {
	Kinds []string `json:"kinds"`
}

type Options struct {
	Sources map[string]source.Source
	// Trusted reports a trusted line field (label unset) or a trusted
	// label (label set) of a source. They are separate namespaces: a
	// trusted label never makes a line field of the same name trusted.
	Trusted func(src, name string, label bool) bool
	Masker  Masker
	Sealer  *Sealer
	Cost    *CostModel
	// PolicyFP is the fingerprint of the approved policy in force.
	PolicyFP func() string
	// Detect reports a query value a detector flags.
	Detect func(string) bool
	// NameMasked reports a clear path the masker shows masked.
	NameMasked func(src, path string) bool
	Limits     Limits
	// Prefilter (opt-in, refused on production by the config) skips
	// masking a record whose clear text cannot contain a needle.
	Prefilter bool
	// Workers mask in parallel (the console runs with --cpus min(2,
	// nproc)); the cost model is per call, so it is calibrated with the
	// same count.
	Workers int
	Now     func() time.Time
	// TailPoll is the interval between a tail's polls (DefaultTailPoll).
	TailPoll time.Duration
	// Budgets are the rolling budgets (zero: DefaultBudgets).
	Budgets Budgets
	// ScanTTL, ScanDeadline, ScanBytes and ScanRange bound an approved
	// scan: its lifetime from the approval (DefaultScanTTL), the
	// deadline of each of its calls (DefaultScanDeadline, and never past
	// scanCallBudget from the request), the bytes and the range of its
	// whole plan (DefaultScanBytes, DefaultScanRange). The deadline is a
	// fixed bound, not calibrated: what a call does within it is (run
	// admits each group of granules on the calibrated cost model).
	ScanTTL      time.Duration
	ScanDeadline time.Duration
	ScanBytes    int64
	ScanRange    time.Duration
	// ScanRequestsPerMinute paces an approved scan's remote requests (0:
	// none beyond the source's own in-flight cap; design R6-P2).
	ScanRequestsPerMinute int
	// Unmask is "approved" to serve log.unmask on a read-pii approval;
	// anything else ("never", the default) refuses it.
	Unmask string
	// LookupApproved makes every log.lookup a read-pii approval.
	LookupApproved bool
	// Production marks the approval screens of a production profile.
	Production bool
	// MaxCalls bounds the agent calls the engine runs at once
	// (DefaultMaxCalls when 0); a call over it is refused with E_BUSY.
	MaxCalls int
	// contains filtered or unexported fields
}

type PatternGroup struct {
	Pattern   string     `json:"pattern"`
	N         int64      `json:"n"`
	BaselineN *int64     `json:"baseline_n,omitempty"`
	First     *time.Time `json:"first,omitempty"`
	Last      *time.Time `json:"last,omitempty"`
}

type PatternsQuery struct {
	Query
	// Top is the number of patterns returned (DefaultTop, at most MaxTop).
	Top int `json:"top,omitempty"`
	// Baseline, when set, is an offset ("24h"): the same window that much
	// earlier is counted too, for each pattern's baseline count and the
	// new and gone lists. It is at least the window's length (the windows
	// never overlap).
	Baseline string `json:"baseline,omitempty"`
	// contains filtered or unexported fields
}

type PatternsResult struct {
	Epoch string `json:"epoch"`
	// Patterns are the top patterns of the window, most frequent first.
	Patterns []PatternGroup `json:"patterns"`
	// Distinct is the number of distinct patterns of the window, Records
	// the records counted (with a message), NoText the matching records
	// without one.
	Distinct int   `json:"distinct"`
	Records  int64 `json:"records"`
	NoText   int64 `json:"no_text,omitempty"`
	// Untimed counts the matching untimed records of the window's plan.
	Untimed int64 `json:"untimed,omitempty"`
	// Truncated is set when the window or the baseline had more distinct
	// patterns than MaxGroups (or MaxGroupBytes): the rest count under
	// Other, in their own group (counted in Distinct). New is then left
	// empty when the baseline is truncated, Gone when the window is.
	Truncated bool `json:"truncated,omitempty"`
	// With a baseline: New are the top patterns absent from it, Gone the
	// top patterns of the baseline absent from the window.
	BaselineFrom   *time.Time     `json:"baseline_from,omitempty"`
	BaselineTo     *time.Time     `json:"baseline_to,omitempty"`
	New            []PatternGroup `json:"new,omitempty"`
	Gone           []PatternGroup `json:"gone,omitempty"`
	Complete       bool           `json:"complete"`
	CoveredUntil   *time.Time     `json:"covered_until,omitempty"`
	Cursor         string         `json:"cursor,omitempty"`
	Scanned        Scanned        `json:"scanned"`
	MaskedFailures int            `json:"masked_failures,omitempty"`
}

type Peer struct {
	UID int
	// Token is the hash of the agent's token (lea's requester token,
	// plans.HashToken), "" when the agent sends none. An approved scan is bound to
	// it as to the uid: another agent of the same uid, with another token,
	// neither re-attaches to it nor continues it.
	Token   string
	Approve Approver
}

type Pred struct {
	Field string          `json:"field,omitempty"`
	Label string          `json:"label,omitempty"`
	Op    string          `json:"op"`
	Value json.RawMessage `json:"value,omitempty"`
	// contains filtered or unexported fields
}

type Query struct {
	Sources []string  `json:"sources,omitempty"`
	From    time.Time `json:"from"`
	To      time.Time `json:"to"`
	// Last, when set, resolves the range at validation: [now-Last, now).
	Last   string   `json:"last,omitempty"`
	Where  []Pred   `json:"where,omitempty"`
	Text   string   `json:"text,omitempty"`
	Regex  string   `json:"regex,omitempty"`
	Fields []string `json:"fields,omitempty"`
	Limit  int      `json:"limit,omitempty"`
	// Order is "asc" (default) or "desc": pages follow it within each
	// stream; each call's matches are sorted, while streams of several
	// sources follow each other rather than being merged by time.
	Order  string `json:"order,omitempty"`
	Cursor string `json:"cursor,omitempty"`
	// contains filtered or unexported fields
}

type ScanInfo struct {
	ID         string    `json:"id"`
	ExpiresAt  time.Time `json:"expires_at"`
	Reattached bool      `json:"reattached,omitempty"`
	// Resumed: the re-attached scan went on after the last page it
	// answered. A page whose answer the agent did not get is not sent
	// again.
	Resumed bool `json:"resumed,omitempty"`
	// Done: the plan is exhausted and the scan ended.
	Done bool `json:"done"`
}

type ScanQuery struct {
	Tool   string          `json:"tool"`
	Query  json.RawMessage `json:"query"`
	Reason string          `json:"reason,omitempty"`
}

type ScanResult struct {
	Scan   ScanInfo `json:"scan"`
	Tool   string   `json:"tool"`
	Result any      `json:"result"`
}

type Scanned struct {
	Bytes    int64 `json:"bytes"`
	Records  int64 `json:"records"`
	Granules int   `json:"granules"`
}

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

type SearchResult struct {
	Epoch        string            `json:"epoch"`
	Records      []json.RawMessage `json:"records"`
	Complete     bool              `json:"complete"`
	CoveredUntil *time.Time        `json:"covered_until,omitempty"`
	Cursor       string            `json:"cursor,omitempty"`
	Scanned      Scanned           `json:"scanned"`
	Masking      Masking           `json:"masking"`
	// MaskedFailures counts records withheld whole because masking
	// failed. With the opt-in pre-filter and a needle in the query (text
	// or contains), it is not counted and stays 0: only the records
	// holding the needles are masked, so the count would tell which
	// failing records hold them (prefilter.go, docs/usage.md).
	MaskedFailures int `json:"masked_failures,omitempty"`
}

type SourceBudget struct {
	Name      string `json:"name"`
	BytesLeft int64  `json:"bytes_left"`
}

type TailQuery struct {
	Sources  []string `json:"sources,omitempty"`
	Where    []Pred   `json:"where,omitempty"`
	Text     string   `json:"text,omitempty"`
	Regex    string   `json:"regex,omitempty"`
	Fields   []string `json:"fields,omitempty"`
	Duration string   `json:"duration,omitempty"` // default and ceiling 50s
	Max      int      `json:"max,omitempty"`
}

type TailResult struct {
	Epoch          string            `json:"epoch"`
	Records        []json.RawMessage `json:"records"`
	Complete       bool              `json:"complete"`
	Scanned        Scanned           `json:"scanned"`
	Masking        Masking           `json:"masking"`
	MaskedFailures int               `json:"masked_failures,omitempty"`
}

type TraceQuery struct {
	Sources []string `json:"sources,omitempty"`
	// ID is a clear id (as the agent saw it in a result) or a pseudonym
	// ⟦kind:ID⟧.
	ID   string    `json:"id"`
	From time.Time `json:"from"`
	To   time.Time `json:"to"`
	// Last, when set, resolves the range at validation (see Query).
	Last   string   `json:"last,omitempty"`
	Fields []string `json:"fields,omitempty"`
	Limit  int      `json:"limit,omitempty"`
	Cursor string   `json:"cursor,omitempty"`
}

type UnmaskQuery struct {
	Ref        string   `json:"ref"`
	Pseudonyms []string `json:"pseudonyms"`
	Reason     string   `json:"reason"`
}

type UnmaskResult struct {
	Epoch  string        `json:"epoch"`
	Values []UnmaskValue `json:"values"`
}

type UnmaskValue struct {
	Pseudonym string `json:"pseudonym"`
	Value     string `json:"value"`
}