storage

type Filter struct {
	Since, Until time.Time
	Device       string
	// Name matches the entry's name exactly, canonically.
	Name string
	// Blocked, when set, selects only blocked or only unblocked entries.
	Blocked *bool
	// Limit caps the rows returned. Zero selects [DefaultLimit]; a query log
	// has no natural size and an unbounded read of one is how a management API
	// runs a server out of memory.
	Limit int
	// Offset skips rows, for paging.
	Offset int
}

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

type MemoryOptions struct {
	// Retention bounds what is kept. The zero policy selects
	// [DefaultRetention]; keeping everything is [Unlimited], which has to be
	// said rather than fallen into — see [RetentionPolicy].
	Retention RetentionPolicy `json:"retention"`
	Clock     clock.Clock     `json:"-"`
}

type QueryEntry struct {
	// At is when the query was answered.
	At time.Time `json:"at"`
	// Device and Client identify who asked. Device is the stable identifier
	// something above the resolver assigned; Client is the address observed.
	Device string `json:"device,omitempty"`
	Client string `json:"client,omitempty"`
	// Name, Type and Class are the question, with Name canonical.
	Name  string `json:"name"`
	Type  string `json:"type"`
	Class string `json:"class,omitempty"`
	// RCode is the answer's response code, as a mnemonic rather than a number
	// so that a log stays readable without a lookup table.
	RCode string `json:"rcode"`
	// Source says where the answer came from: cache, upstream, stale, local.
	Source string `json:"source"`
	// Upstream names the provider that answered, empty when none was asked.
	Upstream string `json:"upstream,omitempty"`
	// Blocked reports a policy answer, and Rule the rule responsible.
	Blocked bool   `json:"blocked,omitempty"`
	Rule    string `json:"rule,omitempty"`
	// Duration is the whole resolution.
	Duration time.Duration `json:"duration"`
	// Answers is how many records came back, which is what distinguishes an
	// empty NOERROR from a real one at a glance.
	Answers int `json:"answers"`
}

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

type RecorderOptions struct {
	// Store receives the batches. Required.
	Store Store
	// Buffer, Batch and FlushInterval take the defaults above when zero.
	Buffer        int           `json:"buffer"`
	Batch         int           `json:"batch"`
	FlushInterval time.Duration `json:"flush_interval"`

	Clock  clock.Clock  `json:"-"`
	Logger *slog.Logger `json:"-"`
}

type RecorderStats struct {
	Recorded uint64 `json:"recorded"`
	Written  uint64 `json:"written"`
	// Dropped is entries refused because the buffer was full. Non-zero means
	// the store is slower than the query rate.
	Dropped uint64 `json:"dropped"`
	// Failed is entries the store rejected.
	Failed uint64 `json:"failed"`
	// Pending is entries queued but not yet written.
	Pending int `json:"pending"`
}

type RetentionPolicy struct {
	// MaxAge discards entries older than this. Zero means no age limit.
	MaxAge time.Duration `json:"max_age"`
	// MaxEntries discards the oldest beyond this count. Zero means no count
	// limit.
	MaxEntries int `json:"max_entries"`
	// contains filtered or unexported fields
}

type Stat struct {
	Key   string `json:"key"`
	Count uint64 `json:"count"`
}

type Store interface {
	// Append records entries. It may buffer, and it may return before anything
	// is durable — see [Recorder], which is what the engine actually writes
	// through and which never blocks a query.
	Append(ctx context.Context, entries ...QueryEntry) error

	// Query reads entries matching f, newest first.
	Query(ctx context.Context, f Filter) ([]QueryEntry, error)

	// Count reports how many entries match f, ignoring Limit and Offset.
	Count(ctx context.Context, f Filter) (uint64, error)

	// TopNames and TopDevices are the two aggregates every DNS dashboard shows.
	// They are named methods rather than a general GROUP BY because a store
	// backed by a real database can answer them with an index, and one backed
	// by a map can answer them without inventing a query planner.
	TopNames(ctx context.Context, f Filter, n int) ([]Stat, error)
	TopDevices(ctx context.Context, f Filter, n int) ([]Stat, error)

	// Prune deletes entries outside the retention policy and reports how many
	// went. A store enforces retention itself; this exists so a caller can
	// force it and learn the result.
	Prune(ctx context.Context) (int, error)

	// Close releases the store. It is idempotent.
	Close() error
}