grafana

type Annotation struct {
	Time     time.Time
	Title    string
	Text     string
	Enabled  bool
	ShowLine bool
	Tags     []string
}

type AnnotationsHandler interface {
	// ServeAnnotations
	ServeAnnotations(ctx context.Context, res AnnotationsResponse, req *AnnotationsRequest) error
}

type AnnotationsHandlerFunc func(context.Context, AnnotationsResponse, *AnnotationsRequest) error

type AnnotationsRequest struct {
	From       time.Time
	To         time.Time
	Name       string
	Datasource string
	IconColor  string
	Query      string
	Enable     bool
}

type AnnotationsResponse interface {
	// WriteAnnotation writes an annotation to the response. The method may be
	// called multiple times.
	WriteAnnotation(Annotation)
}

type Column struct {
	Text string     `json:"text"`
	Type ColumnType `json:"type,omitempty"`
	Sort bool       `json:"sort,omitempty"`
	Desc bool       `json:"desc,omitempty"`
}

type ColumnType string

type Handler interface {
	AnnotationsHandler
	QueryHandler
	SearchHandler
}

type QueryHandler interface {
	// ServeQuery is expected to reply with a list of data points for the given
	// "target" and time range (or a set of rows for table requests).
	//
	// Note: my understanding is that "target" is some kind of identifier that
	// describes some data set in the source (like a SQL query for example), but
	// it's treated as an opaque blob of data by Grafana itself.
	ServeQuery(ctx context.Context, res QueryResponse, req *QueryRequest) error
}

type QueryHandlerFunc func(context.Context, QueryResponse, *QueryRequest) error

type QueryRequest struct {
	From          time.Time
	To            time.Time
	Interval      time.Duration
	Targets       []Target
	MaxDataPoints int
}

type QueryResponse interface {
	// Timeserie returns a TimeserieWriter which can be used to output the
	// datapoint in response to a timeserie request.
	Timeserie(target string) TimeserieWriter

	// Table returns a TableWriter which can be used to output the rows in
	// response to a table request.
	Table(columns ...Column) TableWriter
}

type SearchHandler interface {
	// ServeSearch is expected to implement the search functionality of a
	// Grafana data source.
	//
	// Note: It's not really clear how search is implemented, I think the
	// "target" field in the request is some kind of prefix or keyword to
	// use to return a list of potential matches that can be used in a /query
	// request.
	ServeSearch(ctx context.Context, res SearchResponse, req *SearchRequest) error
}

type SearchHandlerFunc func(context.Context, SearchResponse, *SearchRequest) error

type SearchRequest struct {
	Target string
}

type SearchResponse interface {
	// WriteTarget writes target in the response, the method may be called
	// multiple times.
	WriteTarget(target string)

	// WriteTargetValue writes the pair of target and value in the response,
	// the method may be called multiple times.
	WriteTargetValue(target string, value any)
}

type TableWriter interface {
	WriteRow(values ...any)
}

type Target struct {
	Query string     `json:"target"`
	RefID string     `json:"refId"`
	Type  TargetType `json:"type"`
}

type TargetType string

type TimeserieWriter interface {
	WriteDatapoint(value float64, time time.Time)
}