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
- func ResetJSONLIOStats()
- type JSONLBackend
- func (j *JSONLBackend) Append(ctx context.Context, id brand.SessionID, ev session.SessionEvent) error
- func (j *JSONLBackend) Close() error
- func (j *JSONLBackend) Flush(ctx context.Context, id brand.SessionID) error
- func (j *JSONLBackend) FlushAll(ctx context.Context) error
- func (j *JSONLBackend) List(ctx context.Context) ([]brand.SessionID, error)
- func (j *JSONLBackend) Load(ctx context.Context, id brand.SessionID) (*session.SessionHeader, []session.SessionEvent, error)
- func (j *JSONLBackend) Locate(ctx context.Context, id brand.SessionID) (string, error)
- func (j *JSONLBackend) SaveHeader(ctx context.Context, h *session.SessionHeader) error
- func (j *JSONLBackend) ShardCount() int
- func (j *JSONLBackend) Snapshot(ctx context.Context, id brand.SessionID) (int, error)
- type JSONLIOStats
- type Option
- type Persistence
Constants ¶
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 ¶
func (j *JSONLBackend) Append(ctx context.Context, id brand.SessionID, ev session.SessionEvent) error
Append 实现 Persistence:事件进入目标分片的会话缓冲; 若该会话缓冲达到 batchSize,触发该 shard 的立即 flush。 正常情况下函数在纳秒级返回,落盘由后台 writer 异步完成(H02 核心)。
func (*JSONLBackend) Close ¶
func (j *JSONLBackend) Close() error
Close 关闭持久化后端:停止所有后台 writer,flush 残留缓冲,等待 goroutine 退出。 多次调用安全。关闭后继续 Append 行为未定义(应视为不可用)。
func (*JSONLBackend) Flush ¶
Flush 实现 Persistence:同步等待指定会话缓冲落盘完成。 实现方式:
- 从目标 shard 中"偷走"该会话的缓冲;
- 在 sh.writeMu 保护下写文件(与后台 flushShard 串行,无并发交错)。
调用者通常在 turn/end checkpoint 时使用,保证重要时点数据持久化。
func (*JSONLBackend) FlushAll ¶
func (j *JSONLBackend) FlushAll(ctx context.Context) error
FlushAll 强制 flush 全部会话缓冲(进程退出前或测试中调用)。 实现:按 shard 顺序 steal 全部分片缓冲并同步写入。
func (*JSONLBackend) Load ¶
func (j *JSONLBackend) Load(ctx context.Context, id brand.SessionID) (*session.SessionHeader, []session.SessionEvent, error)
Load 实现 Persistence:读取头部 + 事件行,并执行崩溃修复。 Load 不经过分片缓冲(缓冲里的是"未落盘"数据),因此应先 Flush(ctx, id) 或 FlushAll 后再 Load 才能看到最近 Append 结果;如只读历史数据则无需调用。
func (*JSONLBackend) SaveHeader ¶
func (j *JSONLBackend) SaveHeader(ctx context.Context, h *session.SessionHeader) error
SaveHeader 写入(或覆盖)会话头部。
func (*JSONLBackend) ShardCount ¶
func (j *JSONLBackend) ShardCount() int
ShardCount 返回实际分片数(用于测试/观测)。
type JSONLIOStats ¶
type JSONLIOStats struct {
PooledBufferHits uint64 `json:"pooledBufferHits"`
MarshaledBytes uint64 `json:"marshaledBytes"`
MarshaledEvents uint64 `json:"marshaledEvents"`
HeaderMarshaledBytes uint64 `json:"headerMarshaledBytes"`
}
JSONLIOStats 快照返回 H05 性能统计(线程安全)。
type Option ¶
type Option func(*jsonlOptions)
Option 是 JSONLBackend 的配置选项(函数式选项模式)。
func WithFlushInterval ¶
WithFlushInterval 设置异步 flush 的时间窗口。
func WithShardCount ¶
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 是会话持久化统一接口。