recordstore

type AppendResult struct {
	Window   Window `json:"window"`
	Skipped  int64  `json:"skipped"`
	Replaced int64  `json:"replaced,omitempty"`
}

type Backend interface {
	// Append adds rows to stream, creating it under kind when it does not
	// exist, and returns the window the rows were numbered into. Appending to
	// an existing stream under a different kind is an error.
	//
	// A keyed kind (KindOptions.Key) skips every row whose key the stream
	// already holds, atomically with the append, and numbers only the rows it
	// keeps; a batch naming one key twice is refused whole. A kind that
	// replaces stored rows (OnConflictReplace) instead removes each stored row
	// the append names by key and numbers every appended row; a backend that
	// cannot refuses such a kind with ErrUnsupported. A kind retaining
	// rows (RetainRows) slides the stream's expiry to the backend ttl from now
	// and trims the rows appended longer than that ago, in the same write.
	Append(ctx context.Context, stream, kind string, rows []Row) (AppendResult, error)

	// Meta describes stream, or returns ErrNotFound.
	Meta(ctx context.Context, stream string) (Meta, error)

	// Scan calls fn with every row after afterSeq, in seq order, stopping at
	// the first error fn returns. A scan from below the stream's low seq starts
	// at the low seq. An unknown stream is ErrNotFound.
	Scan(ctx context.Context, stream string, afterSeq int64, fn func(seq int64, row Row) error) error

	// Trim removes the rows appended before before — every append up to the
	// last one made before it — and returns the stream's metadata after. The
	// rows kept keep their seqs, the low seq moves to the first of them, and
	// the keys of the rows removed may be appended again. An unknown stream is
	// ErrNotFound.
	Trim(ctx context.Context, stream string, before time.Time) (Meta, error)

	// Expire removes stream ttl from now, rows appended later included. The
	// ttl must be positive; an unknown stream is ErrNotFound.
	Expire(ctx context.Context, stream string, ttl time.Duration) error

	// Seal marks stream complete (Meta.Sealed): every later Append to it fails
	// with ErrSealed, while Scan, Trim and Expire still apply. Sealing a sealed
	// stream does nothing; an unknown stream is ErrNotFound. The seal ends with
	// the stream, so an id reused after expiry starts unsealed.
	Seal(ctx context.Context, stream string) error

	// Delete removes one stream and its rows immediately. An unknown stream is ErrNotFound.
	Delete(ctx context.Context, stream string) error

	Close() error
}

type BackendKind string

type Batch struct {
	ID       string       `json:"id"`
	Producer Producer     `json:"producer"`
	Schemas  []KindSchema `json:"-"`
	Entries  []BatchEntry `json:"entries"`
}

type BatchAppender interface {
	AppendBatch(ctx context.Context, batch Batch) (BatchResult, error)
	BatchOutcome(ctx context.Context, id string) (BatchResult, bool, error)
}

type BatchEntry struct {
	Op     BatchOp `json:"op"`
	Stream string  `json:"stream"`

	// Kind and Rows are an append's. Seal seals the stream after the append,
	// in the same entry.
	Kind string `json:"kind,omitempty"`
	Rows []Row  `json:"-"`
	Seal bool   `json:"seal,omitempty"`

	// Generation, when set, fences the entry to that incarnation of the
	// stream: any other one, or none, fails the entry as not found. A reopen
	// requires it.
	Generation string `json:"generation,omitempty"`

	// TTL is an expire's, and Before a trim's.
	TTL    time.Duration `json:"ttl,omitempty"`
	Before time.Time     `json:"before,omitzero"`
}

type BatchError struct {
	Code    BatchErrorCode `json:"code"`
	Message string         `json:"message"`
}

type BatchErrorCode string

type BatchOp string

type BatchResult struct {
	ID      string        `json:"id"`
	Entries []EntryResult `json:"entries"`
}

type ChangeSource interface {
	WatchChanges(ctx context.Context, changed func()) error
}

type CompactRule struct {
	Where     string
	OlderThan time.Duration
}

type EntryResult struct {
	Append *AppendResult `json:"append,omitempty"`
	Meta   *Meta         `json:"meta,omitempty"`
	Error  *BatchError   `json:"error,omitempty"`
}

type ImportRequest struct {
	Source Meta
	First  int64
	Rows   []Row

	// Seqs is the source seq of each row, increasing from First. Nil numbers
	// Rows contiguously from First. Only a kind that replaces stored rows may
	// skip seqs, since only there did the source leave them behind.
	Seqs []int64
}

type Index interface {
	Backend

	// Prepare reconciles the storage for source's kind and returns the indexed
	// incarnation of its stream. A derived index removes an older generation
	// under the same stream id and reports it absent.
	Prepare(ctx context.Context, source Meta) (indexed Meta, found bool, err error)

	// Import stores request.Rows under their source seqs. First must be the seq
	// after the indexed stream's high seq, or for a stream the index does not
	// hold yet the source's low seq; a gap or different generation fails.
	Import(ctx context.Context, request ImportRequest) (Window, error)

	// TrimBelow mirrors a source trim: it drops the indexed rows below lowSeq,
	// and moves an indexed stream that had not reached lowSeq up to it empty.
	TrimBelow(ctx context.Context, stream string, lowSeq int64) (Meta, error)

	// Derived reports whether the index can discard rows and rebuild them from
	// a separate source.
	Derived() bool

	// SetExpiry mirrors the source's absolute expiry. Nil keeps the indexed
	// stream while its source exists.
	SetExpiry(ctx context.Context, stream string, expiresAt *time.Time) error

	// DeleteSeqs mirrors a source compaction: it drops the indexed rows at
	// seqs and records the source's compaction count.
	DeleteSeqs(ctx context.Context, stream string, seqs []int64, compactions int64) (Meta, error)
}

type IndexDef struct {
	Columns []string
}

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

type KindOptions struct {
	// Key names a string column whose value identifies a row within a stream.
	// A keyed stream holds each key once; OnConflict says what an append of a
	// stored key does. Empty leaves the kind unkeyed, where every row appended
	// is stored.
	Key string

	// Retention says how long a stream keeps its rows.
	Retention Retention

	// OnConflict says what an append of a key the stream holds does. Replace
	// needs a Key.
	OnConflict OnConflict

	// TimeColumn names the datetime column a stream's rows are read newest
	// first by. A backend that indexes rows indexes (stream, time desc, seq),
	// the order every profile of the kind pages in.
	TimeColumn string

	// Indexes are the column lists a backend that indexes rows indexes, each
	// after the stream id, since every read is of one stream or a few. A
	// backend keeps every index a kind ever declared.
	Indexes []IndexDef

	// Dynamic makes a backend that stores rows by column add a column for
	// every key a row brings that the kind does not declare, typed by
	// InferColumnType; a value of another type later is ErrSchemaMismatch.
	// Other backends store every key anyway.
	Dynamic bool

	// MaxDynamicColumns caps the columns a dynamic kind may infer; an append
	// needing more is ErrCapacity. Zero is 256.
	MaxDynamicColumns int

	// Compact are the rules a store whose seqs can skip drops rows by when it
	// compacts; a store whose seqs cannot refuses the kind with
	// ErrUnsupported.
	Compact []CompactRule

	// Compressed names columns a backend storing rows by column keeps
	// compressed. SQL cannot compare what is inside one, so each must be a
	// text or structured column that is not the key, the time column or
	// indexed, and that offers no filter — a string column's filter must be
	// switched off explicitly. For large payloads read whole.
	Compressed []string
}

type KindSchema struct {
	Kind    string
	Columns []query.ColumnDef
	Options KindOptions
}

type MergeOptions struct {
	Where         string
	DeleteSources bool
}

type Merger interface {
	Merge(ctx context.Context, target string, sources []string, options MergeOptions) (AppendResult, error)
}

type Meta struct {
	Stream     string `json:"stream"`
	Kind       string `json:"kind"`
	Generation string `json:"generation"`

	// Total is how many rows the stream holds and HighSeq the seq of the last
	// one; LowSeq is a lower bound of the first one's seq. Seqs only grow, but
	// a kind that replaces stored rows leaves the replaced rows' seqs behind,
	// so its stream may skip seqs and hold fewer than HighSeq-LowSeq+1 rows.
	// All three are reported because an index mirroring the stream may lag. An
	// empty stream has LowSeq HighSeq+1.
	Total   int64 `json:"total"`
	LowSeq  int64 `json:"lowSeq"`
	HighSeq int64 `json:"highSeq"`

	UpdatedAt time.Time `json:"updatedAt"`

	// ExpiresAt is when the stream is removed, or nil when it is kept until
	// something expires it.
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`

	// Capped reports that an append was refused for capacity: the stream is
	// complete up to HighSeq and missing whatever that append carried.
	Capped bool `json:"capped,omitempty"`

	// Compactions counts the compactions that dropped rows from the middle of
	// the stream; an index mirroring it drops the same rows when the count
	// changes.
	Compactions int64 `json:"compactions,omitempty"`

	// Sealed reports that the writer declared the stream complete for now.
	// A reader that has read through HighSeq is done until an explicit Reopen;
	// readers revisiting a stream must fetch Meta again.
	Sealed bool `json:"sealed,omitempty"`
}

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

type NotifierOptions struct {
	// RecheckInterval is how often a waiter re-reads its stream's metadata
	// while no append wakes it. Appends made through the Notifier wake waiters
	// at once; the recheck is what notices what no append announces — a stream
	// expired, trimmed away or removed by the backend itself. Required.
	RecheckInterval time.Duration
}

type OnConflict int

type Producer struct {
	Instance string `json:"instance"`
	Seq      int64  `json:"seq"`
	PID      int    `json:"pid,omitempty"`
	Host     string `json:"host,omitempty"`
	Build    string `json:"build,omitempty"`
}

type Reopener interface {
	Reopen(ctx context.Context, stream, generation string) error
}

type Retention int

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

type RouterOptions struct {
	// Route names the route a call's context belongs to — the tenant, the
	// environment — and fails for a context that carries none.
	Route func(ctx context.Context) (string, error)

	// Open opens one route's backend. It is called once per route, and again
	// only after Forget drops it. The backend it returns must belong to that
	// route alone: never shared with another route, and never the index a
	// registry reads, or one route's streams become readable through another.
	Open func(ctx context.Context, route string) (Backend, error)
}

type Row = query.Row

type SchemaResolver func(kind string) (KindSchema, error)

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

type Settings struct {
	// Prefix is the property prefix the settings were read under; errors about
	// a setting name the key under it.
	Prefix string

	// Backend is the backend asked for, or empty for the caller's default.
	Backend           BackendKind
	Dir               string
	TTL               time.Duration
	NDJSONMaxBytes    int64
	NDJSONKeepStreams int
}

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

type Submitter func(ctx context.Context, batch Batch) (BatchResult, error)

type Window struct {
	From int64 `json:"from"`
	To   int64 `json:"to"`
}