debug

type Debug interface {
	WriteBytes(data []byte)
	Write(data string)
	Writef(format string, args ...any)
}

type DebugKind uint16

type Reader interface {
	// Return a list of all sources in the order they were written.
	Sources() []string

	// Return the earliest and latest timestamps in the log.
	TimeRange() (time.Time, time.Time)

	Sample(fn func(ts time.Time, kind DebugKind, source string, data []byte) error) error

	// Guaranteed to iterate over all entries in the order they were written.
	Each(fn func(ts time.Time, kind DebugKind, source string, data []byte) error) error

	// Guaranteed to iterate over all entries for a given source in the order they were written.
	EachSource(source string, fn func(ts time.Time, kind DebugKind, data []byte) error) error

	// Guaranteed to iterate over all entries that match the search criteria in the order they were written.
	Search(opts SearchOptions, fn func(ts time.Time, kind DebugKind, source string, data []byte) error) error

	// Return the number of entries that match the search criteria.
	Count(opts SearchOptions) (int, error)
}

type SearchOptions struct {
	// The start and end timestamps to search within.
	Start time.Time
	End   time.Time

	// LimitStart only returns the first N entries after the start timestamp.
	// If both LimitStart and LimitEnd are set then an error is returned.
	LimitStart int64

	// LimitEnd only returns the last N entries before the end timestamp.
	// If both LimitStart and LimitEnd are set then an error is returned.
	LimitEnd int64

	// Only return entries for the given sources.
	Sources []string
}

type Writer interface {
	io.WriterAt
	io.Closer
}

type WriterTo interface {
	WriteTo(w io.WriterAt) (n int64, err error)
}