storage

type Direction string

type ListLogEntriesRequest struct {
	Path     StreamPath
	StreamID StreamID
	Order    Direction
	// Cursor 为 0 时从这个方向的起点读；非零时从它之后读，不含它本身。
	Cursor Ordinal
	Limit  int
}

type ListRecordsRequest struct {
	Namespace string
	// Start 是 Key 范围下界（含），两种排序都生效；为空时没有下界。
	Start RecordKey
	// End 是 Key 范围上界（不含）；为空时没有上界。
	End    RecordKey
	Order  Order
	Cursor RecordCursor
	Limit  int
	// Filter 先筛选再排序分页；整组与 Key 范围及游标取 AND。
	Filter RecordFilter
}

type LogEntry struct {
	Ordinal Ordinal
	// UpdatedAt 是追加时的 Unix 毫秒，由 LogStorage 分配；日志追加后不再修改，这个时间就是保存时间。
	UpdatedAt int64
	Payload   json.RawMessage
}

type LogEntryInfo struct {
	Ordinal   Ordinal
	UpdatedAt int64
}

type LogStorage interface {
	// Append 把一批 Payload（至少一条）一次写入并 fsync，按顺序返回分到的顺序号和追加时间，同一批的追加时间相同；
	// 崩溃时可能只写入这批的一部分。
	Append(ctx context.Context, path StreamPath, streamID StreamID, payloads ...json.RawMessage) ([]LogEntryInfo, error)
	// Delete 删除指定路径下的一条 Stream；Stream 不存在时什么都不做。
	Delete(ctx context.Context, path StreamPath, streamID StreamID) error
	// DeletePath 删除 path 下全部 Stream；path 不存在时什么都不做。
	DeletePath(ctx context.Context, path StreamPath) error
	// List 按方向分页；这个方向还有更多时 Next 为本页最后一个 Ordinal，否则为 0。
	List(ctx context.Context, request ListLogEntriesRequest) (Page[LogEntry, Ordinal], error)
	// GetStreamPaths 返回含有这个 StreamID 的全部 Path，按字节序升序；一个都没有时返回空切片。
	GetStreamPaths(ctx context.Context, streamID StreamID) ([]StreamPath, error)
}

type Order struct {
	By        OrderBy   `json:"by,omitempty"`
	Direction Direction `json:"direction,omitempty"`
}

type OrderBy string

type Ordinal uint64

type Page[T any, C comparable] struct {
	Items []T
	Next  C
}

type Record struct {
	Key RecordKey
	// UpdatedAt 是最后一次写入的 Unix 毫秒，由写入方给出。
	UpdatedAt int64
	Payload   json.RawMessage
}

type RecordCursor struct {
	Key       RecordKey
	UpdatedAt int64
}

type RecordField struct {
	Name            string
	PayloadJSONPath []string
}

type RecordFilter struct {
	Logic      RecordFilterLogic
	Conditions []RecordFilterCondition
}

type RecordFilterCondition struct {
	Field    string
	Operator RecordFilterOperator
	// Values 在 in 时至少一项，命中任意一项即匹配；contains 时恰好一项，按普通子串匹配。
	Values []string
}

type RecordFilterLogic string

type RecordFilterOperator string

type RecordKey string

type RecordNamespace struct {
	Name   string
	Fields []RecordField
	// IndexedFields 里每个字段都建立字段值、UpdatedAt、Key 的联合索引，字段必须已在 Fields 里声明。
	IndexedFields []string
}

type RecordStorage interface {
	// Set 原样保存 record 的 Key、UpdatedAt 和 Payload；UpdatedAt 由调用方给出，必须大于 0。
	Set(ctx context.Context, namespace string, record Record) error
	// MSet 批量写入同一 namespace，每条使用自己的 UpdatedAt；同一批里重复的 Key 以后一条为准；失败时可能已经写入部分记录。
	MSet(ctx context.Context, namespace string, records []Record) error
	// Get 读取指定记录，同时返回是否找到。
	Get(ctx context.Context, namespace string, key RecordKey) (Record, bool, error)
	// MGet 返回找到的 Record；不同 Key 的结果可能来自不同写入时刻。
	MGet(ctx context.Context, namespace string, keys []RecordKey) (map[RecordKey]Record, error)
	// Delete 删除指定记录，记录不存在时不报错。
	Delete(ctx context.Context, namespace string, key RecordKey) error
	// DeleteRange 删除 [start, end) 内的记录，end 为空时不设上界。
	DeleteRange(ctx context.Context, namespace string, start, end RecordKey) error
	// List 按 Order 分页；还有下一页时 Next 为本页最后一条的位置。
	List(ctx context.Context, request ListRecordsRequest) (Page[Record, RecordCursor], error)
}

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

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

type StreamID string

type StreamPath string