tracing

type Capabilities struct {
	Live       bool `json:"live,omitempty"`
	Historical bool `json:"historical,omitempty"`
	Follow     bool `json:"follow,omitempty"`
}

type Checkpointer[P, R any] interface {
	Checkpoint(ctx dbcontext.Context, params P, records Emitter[R]) error
}

type Emitter[R any] interface {
	// Emit waits while the session's buffer is full, and returns ctx's error
	// once it is done.
	Emit(ctx context.Context, record R) error
	// TryEmit never waits: a record a full buffer cannot take is dropped and
	// counted, so a handler called on someone else's goroutine never stalls it.
	TryEmit(record R) bool
	// Report replaces the kind's own summary of its capture, what it counts
	// beyond the records it emits, such as events its source lost. The
	// session shows the latest report with its progress and keeps the last.
	Report(summary any)
	// Warn adds a warning the session ends with.
	Warn(message string)
	// Describe names the session by what the capture set up on its source,
	// with the statements or settings that set it up. A session records them
	// once, as it starts running, so only a Preparer's Prepare describes it.
	Describe(handle string, metadata ...query.SessionMetadata)
	// Export hands the processes the capture observes an environment
	// variable, such as the address of a proxy it listens on. A session
	// records its exports once, as it starts running, so only a Preparer's
	// Prepare exports: a name that is no environment variable name, or one
	// exported twice, refuses the start, and an export once the capture runs
	// is left out and warns the session. A host reads them from the session's
	// status (query.SessionStatus.Exports) as soon as Runtime.Start returns.
	Export(name, value string)
}

type ExportFormat struct {
	Name string `json:"name"`
	Ext  string `json:"ext"`
	MIME string `json:"mime"`
}

type Exporter[R any] interface {
	Formats() []ExportFormat
	// Export writes rows, a window's records as Records reads them back, in
	// format, one of Formats.
	Export(format string, rows iter.Seq[R], w io.Writer) error
}

type Handler[P, R any] struct {
	// contains filtered or unexported fields
}

type KindInfo struct {
	Name         string             `json:"name"`
	Title        string             `json:"title"`
	Capabilities Capabilities       `json:"capabilities"`
	Params       *rpc.OpenAPISchema `json:"params"`
	Columns      []query.ColumnDef  `json:"columns"`
	// ExportFormats are the formats a window of the kind's records downloads
	// in, NDJSON first.
	ExportFormats []ExportFormat `json:"exportFormats"`
}

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

type Preparer[P, R any] interface {
	Prepare(ctx dbcontext.Context, params P, records Emitter[R]) (prepared dbcontext.Context, release func() error, err error)
}

type Records[R any] interface {
	Scan(ctx context.Context, afterSeq int64, fn func(seq int64, record R) error) error
}

type Runtime struct {
	Kinds    *Kinds
	Sessions *query.SessionRegistry
	Probes   *probe.Manager
	// Results is the store the captures' records are committed to, opened
	// with Kinds.RegisterResultTypes.
	Results *recordresults.Results

	// PollEvery is how often a running capture's records are committed.
	// Zero is a second.
	PollEvery time.Duration
	// BufferRows caps the records a capture holds before they are committed.
	// Zero is 10,000; it is never more than one sample of the probe commits.
	BufferRows int
	// BufferBytes caps the bytes of records a capture holds before they are
	// committed, measured by their keys and text. Zero is 64MiB.
	BufferBytes int
	// contains filtered or unexported fields
}

type StartRequest struct {
	Kind   string
	Params json.RawMessage
	// StopAt ends the capture; nil runs it for the registry's longest duration.
	StopAt    *time.Time
	Labels    map[string]string
	Principal string
	RestartOf string
}

type Summarizer[R any] interface {
	Summarize(rows iter.Seq[R]) (map[string]any, error)
}

type Summary struct {
	Emitted      int64 `json:"emitted"`
	Deduplicated int64 `json:"deduplicated,omitempty"`
	Dropped      int64 `json:"dropped,omitempty"`
	Unencodable  int64 `json:"unencodable,omitempty"`
	Collapsed    int64 `json:"collapsed,omitempty"`
	// Report is the kind's own summary, as it last reported it.
	Report any `json:"report,omitempty"`
}

type TraceHandler[P, R any] interface {
	// Params are the defaults a session starts from; P's type is the params
	// form a client renders.
	Params() P
	// Schema declares how R's records are stored and read: its title, time
	// and key columns, indexes. R's own columns are reflected from its fields.
	Schema() recordresults.ResultType[R]
	// Handle captures until ctx is done, or until its source is exhausted,
	// emitting each record. It may read back the records it already emitted.
	Handle(ctx dbcontext.Context, params P, records Emitter[R], store Records[R]) error
}

type TracePlugin interface {
	// Title is the kind's human name.
	Title() string
	// Params is the JSON schema of the kind's params, with their defaults: the
	// form a client renders to start a capture.
	Params() (*rpc.OpenAPISchema, error)
	// Schema is the record-store schema the kind's records are stored under
	// when it is registered as kind.
	Schema(kind string) (recordstore.KindSchema, error)
	Capabilities() Capabilities
	// ValidateParams decodes params as a session start would, refusing what
	// the session would refuse.
	ValidateParams(params json.RawMessage) error
	// ExportFormats are the formats the kind's records download in: NDJSON,
	// then those of a kind that is an Exporter.
	ExportFormats() []ExportFormat
	// contains filtered or unexported methods
}

type TraceRef struct {
	Kind     string `json:"kind"`
	Stream   string `json:"stream"`
	AfterSeq int64  `json:"afterSeq,omitempty"`
	ToSeq    int64  `json:"toSeq,omitempty"`
}

type Truncation struct {
	Truncated []string `json:"truncated,omitempty" pretty:"label=Truncated"`
}

type Validator interface {
	Validate() error
}