persistence

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package persistence 提供会话持久化接缝:Flush Checkpoint + Batch Window + Crash Repair。

对齐上游:packages/session/session-persistence + storage/jsonl

设计要点:

  • Persistence 接口(locate/load/inspect/append/list/snapshot)统一屏蔽具体后端;
  • JSONLBackend 将 SessionEvent 逐行追加写入文件,支持 Flush Checkpoint;
  • 【H02 锁分片】按 SessionID 的哈希值映射到 N 个独立 shard,每个 shard 拥有独立 mutex + 事件缓冲,避免单全局锁的跨会话争用;
  • 【H02 异步批量写入】每个 shard 内置后台 writer goroutine + ticker 时间窗口, Append 仅入队(纳秒级),达到数量阈值或时间窗口后统一落盘,显著减少 syscall 与文件 open/close 次数;
  • 崩溃恢复(Crash Repair):加载时若发现孤儿 turn/end(在断点处只写了 turn/start 等但未配对),自动补写 turn/end{reason:interrupted} 关闭,并保留已写入的 chunk/tool/call 事件。

Index

Constants

View Source
const (
	// DefaultShardCount 默认分片数(2 的幂有利于位运算取模)。
	// 会话数多、并发写入高的场景可通过 WithShardCount 调大。
	DefaultShardCount = 16
	// DefaultFlushInterval 默认异步 flush 的时间窗口(毫秒)。
	// 到达窗口即把当前 shard 缓冲中所有会话的数据一次性落盘。
	DefaultFlushInterval = 100 * time.Millisecond
)

Variables

This section is empty.

Functions

func ResetJSONLIOStats

func ResetJSONLIOStats()

ResetJSONLIOStats 归零(仅测试 / Benchmark ResetTimer 后使用;生产不要乱调)。

Types

type JSONLBackend

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

JSONLBackend 是基于 JSONL 文件的持久化后端。

H02 结构:

dir 根目录
batchSize 每条会话达到该事件数即触发 flush(与时间窗口 OR 关系)
flushInterval 时间窗口
shards 分片数组(固定长度,按哈希取模分配)
shardMask 位运算取模掩码(len(shards)-1,要求 shard 数为 2 的幂)
flushCh 后台 writer 收到信号即执行一次分片级 flush
closeOnce/closeCh Close 生命周期(关闭所有后台 writer)
wg 后台 goroutine 等待组,Close 会等待全部 writer 退出

func NewJSONL

func NewJSONL(dir string, batchSize int, opts ...Option) (*JSONLBackend, error)

NewJSONL 创建 JSONL 持久化后端(目录不存在则创建)。

batchSize:单会话缓冲事件数,达到该数量立即触发 flush(配合时间窗口做 OR 逻辑)。 batchSize<=0 时默认值 1。

可通过 Option 调整分片数与 flush 时间窗口;不传则使用 DefaultShardCount / DefaultFlushInterval。

func (*JSONLBackend) Append

Append 实现 Persistence:事件进入目标分片的会话缓冲; 若该会话缓冲达到 batchSize,触发该 shard 的立即 flush。 正常情况下函数在纳秒级返回,落盘由后台 writer 异步完成(H02 核心)。

func (*JSONLBackend) Close

func (j *JSONLBackend) Close() error

Close 关闭持久化后端:停止所有后台 writer,flush 残留缓冲,等待 goroutine 退出。 多次调用安全。关闭后继续 Append 行为未定义(应视为不可用)。

func (*JSONLBackend) Flush

func (j *JSONLBackend) Flush(ctx context.Context, id brand.SessionID) error

Flush 实现 Persistence:同步等待指定会话缓冲落盘完成。 实现方式:

  1. 从目标 shard 中"偷走"该会话的缓冲;
  2. 在 sh.writeMu 保护下写文件(与后台 flushShard 串行,无并发交错)。

调用者通常在 turn/end checkpoint 时使用,保证重要时点数据持久化。

func (*JSONLBackend) FlushAll

func (j *JSONLBackend) FlushAll(ctx context.Context) error

FlushAll 强制 flush 全部会话缓冲(进程退出前或测试中调用)。 实现:按 shard 顺序 steal 全部分片缓冲并同步写入。

func (*JSONLBackend) List

func (j *JSONLBackend) List(ctx context.Context) ([]brand.SessionID, error)

List 实现 Persistence:列出全部会话目录。

func (*JSONLBackend) Load

Load 实现 Persistence:读取头部 + 事件行,并执行崩溃修复。 Load 不经过分片缓冲(缓冲里的是"未落盘"数据),因此应先 Flush(ctx, id) 或 FlushAll 后再 Load 才能看到最近 Append 结果;如只读历史数据则无需调用。

func (*JSONLBackend) Locate

func (j *JSONLBackend) Locate(ctx context.Context, id brand.SessionID) (string, error)

Locate 实现 Persistence。

func (*JSONLBackend) SaveHeader

func (j *JSONLBackend) SaveHeader(ctx context.Context, h *session.SessionHeader) error

SaveHeader 写入(或覆盖)会话头部。

func (*JSONLBackend) ShardCount

func (j *JSONLBackend) ShardCount() int

ShardCount 返回实际分片数(用于测试/观测)。

func (*JSONLBackend) Snapshot

func (j *JSONLBackend) Snapshot(ctx context.Context, id brand.SessionID) (int, error)

Snapshot 实现 Persistence:返回会话事件数(已落盘 + 当前缓冲)。 为了返回"真实全量",会先对目标会话执行一次同步 Flush。

type JSONLIOStats

type JSONLIOStats struct {
	PooledBufferHits     uint64 `json:"pooledBufferHits"`
	MarshaledBytes       uint64 `json:"marshaledBytes"`
	MarshaledEvents      uint64 `json:"marshaledEvents"`
	HeaderMarshaledBytes uint64 `json:"headerMarshaledBytes"`
}

JSONLIOStats 快照返回 H05 性能统计(线程安全)。

func ReadJSONLIOStats

func ReadJSONLIOStats() JSONLIOStats

ReadJSONLIOStats 读取当前 H05 统计快照。

type Option

type Option func(*jsonlOptions)

Option 是 JSONLBackend 的配置选项(函数式选项模式)。

func WithFlushInterval

func WithFlushInterval(d time.Duration) Option

WithFlushInterval 设置异步 flush 的时间窗口。

func WithShardCount

func WithShardCount(n int) Option

WithShardCount 设置分片数量(建议为 2 的幂;非 2 的幂会向上取整到最近的 2 幂)。

type Persistence

type Persistence interface {
	// Locate 返回会话文件的持久化路径。
	Locate(ctx context.Context, id brand.SessionID) (string, error)
	// Load 加载会话头部与全部事件。
	Load(ctx context.Context, id brand.SessionID) (*session.SessionHeader, []session.SessionEvent, error)
	// Append 追加一条事件(batch window 缓冲)。
	Append(ctx context.Context, id brand.SessionID, ev session.SessionEvent) error
	// Flush 强制将缓冲事件写入磁盘(checkpoint)。
	Flush(ctx context.Context, id brand.SessionID) error
	// Snapshot 返回指定会话当前事件数。
	Snapshot(ctx context.Context, id brand.SessionID) (int, error)
	// List 列出全部已持久化会话 ID。
	List(ctx context.Context) ([]brand.SessionID, error)
}

Persistence 是会话持久化统一接口。

Directories

Path Synopsis
Package sqlite 提供 SQLite 持久化后端 + FTS5 索引(任务 S03)。
Package sqlite 提供 SQLite 持久化后端 + FTS5 索引(任务 S03)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL