source

type AroundMeter interface {
	AroundMeasured(ctx context.Context, ref RawRef, before, after int) ([]RawRecord, int64, error)
}

type Byteplan struct {
	Chunks []Chunk
}

type Chunk struct {
	Source string
	// Stream identifies the stream (a file identity, a remote stream).
	Stream string
	// Granules are consecutive and in stream order (the engine's split of
	// a descending remote slice holds its parts newest first: remote
	// granules are read one at a time).
	Granules []Granule
	// Bytes is the number of bytes processing the chunk costs: the
	// granules' bytes, plus for a compressed stream the decompressed bytes
	// before the first granule that must be read and discarded.
	Bytes int64
	// Version is the stream's state the plan was made on (e.g. its size at
	// open); a scan of a chunk whose stream changed incompatibly fails
	// with ErrStale.
	Version string
}

type CountQuery struct {
	Range    Range
	Selector Selector
	// By are line fields, ByLabels labels; a row's Vals are the By values
	// then the ByLabels values.
	By       []string
	ByLabels []string
	// Bucket is a whole number of minutes (0: one bucket for the range).
	Bucket time.Duration
}

type CountResult struct {
	Rows []CountRow
	// Untimed counts indexed records without a time in matching
	// granules (not in any bucket).
	Untimed int64
	// Residual is the plan of the granules the index does not hold: the
	// caller scans them and adds their counts.
	Residual Byteplan
	// IndexedFrom, IndexedUntil: see Schema.
	IndexedFrom, IndexedUntil time.Time
}

type CountRow struct {
	Bucket time.Time
	Vals   []string
	N      int64
}

type Counter interface {
	IndexCounts(ctx context.Context, q CountQuery) (CountResult, error)
}

type FieldInfo struct {
	Name string
	// Label is set for a label of the source's frame (a Loki stream
	// label, a docker container or stream), unset for a line field.
	Label   bool
	Trusted bool
	// Values are the trusted field's distinct values (raw, masked by the
	// caller), when the source knows them and they are few.
	Values []string
}

type Granule struct {
	// Start and End are stream offsets [Start, End): records whose first
	// line starts there.
	Start, End int64
	// Indexed is set when the local index holds this granule; From, To
	// and Records are then exact (From/To zero when it holds no timed
	// record). For a granule that is not indexed they are unknown.
	Indexed  bool
	From, To time.Time
	Records  int64
	// Bytes is the planned cost of the granule (its length for a byte
	// stream); 0 when unknown before the fetch (a remote time slice,
	// charged by the bytes actually fetched).
	Bytes int64
}

type Iterator interface {
	// Next returns the next record, or io.EOF after the last one.
	Next() (RawRecord, error)
	// Processed returns the bytes processed so far (read, decompressed,
	// discarded).
	Processed() int64
	Close() error
}

type Limiter interface {
	Wait(ctx context.Context) error
}

type Range struct {
	From, To time.Time
}

type RawRecord struct {
	Ref   RawRef
	Event parse.Event
	// Granule identifies the granule the record belongs to, as the source
	// numbers them (file: the absolute granule number of the stream; other
	// sources document theirs).
	Granule int
}

type RawRef struct {
	Source string
	Stream string
	Offset int64
	Length int64
}

type Schema struct {
	Kind    string
	Format  string
	Fields  []FieldInfo
	Streams int
	// Bytes is the estimated size of the source's data.
	Bytes int64
	// Oldest and Newest bound the source's records, when known.
	Oldest, Newest time.Time
	// IndexedFrom is the start of the newest contiguous indexed span:
	// every record from IndexedFrom on (before IndexedUntil when set: a
	// growing file's newest lines are being indexed) is in the local
	// index, allowing a minute of timestamp disorder. Zero when nothing can
	// be claimed. It describes what the index holds: counts may still scan
	// part of that range (a grown granule goes to the residual whole).
	IndexedFrom, IndexedUntil time.Time
	// FullyIndexed is set when every granule is indexed.
	FullyIndexed bool
}

type Selector struct {
	Terms []Term
}

type Source interface {
	Name() string
	Kind() string
	Describe(ctx context.Context) (Schema, error)
	// Plan returns the chunks that may hold records of r matching sel.
	// It reads no record content beyond what identifying a stream needs.
	Plan(ctx context.Context, r Range, sel Selector) (Byteplan, error)
	Scan(ctx context.Context, c Chunk) (Iterator, error)
	// Reread returns the record at ref, or ErrStale when the stream no
	// longer holds it.
	Reread(ctx context.Context, ref RawRef) (RawRecord, error)
	// Around returns up to before records before ref, the record itself
	// and up to after records after it, from ref's stream.
	Around(ctx context.Context, ref RawRef, before, after int) ([]RawRecord, error)
}

type Splitter interface {
	// Split returns the granules g is cut into, in stream order, covering
	// exactly [g.Start, g.End) (their bounds a function of g only), or nil
	// when g is at the narrowest width the source pages.
	Split(g Granule) []Granule
}

type Term struct {
	Field string
	// Label is set for a term on a label of the source's frame (Loki
	// stream labels, journald and docker attributes: parse.Event.Attrs),
	// unset for a line field. They are separate namespaces: a source
	// applies a term only in its own one.
	Label  bool
	Op     string // "=", "!=", "in"
	Values []string
}