二进制格式——产品格式(TierWAL / Kv / TimeSeries / Blob)
分册:总览与通用约定 | Log 族 | Ring 族 | 段元组/索引/快照 | TierVolume | 产品格式 | Meta 家族·Mirror·版本元数据 | 网络线格式
3. 产品格式(Products)
3.1 TierWAL 数据帧 + opaque 容器
raft 条目载荷帧前缀(9B,TierWalRaftStore 层):[Term 8B LE][Kind 1B][entry content …]——index 由 WAL 起点 + 顺序计数推导,帧内零 index。
TierWAL opaque 容器(WalOpaqueHeader,v1.1 = 64B 定长头 + raft meta 预留区):
[Magic 4B][Version 2B][Flags 2B][TailIndex 8B][TailAddress 16B][HeadIndex 8B][HeadAddress 16B][ArchivedIndex 8B][可选编解码扩展段 16B][raft meta …]
0 4 6-7 8 16 32 40 56 64 80
| 偏移 | 宽度 | 字段 | 含义 |
|---|---|---|---|
| 0 | 4 | MagicValue | 0x44484C57 "WLHD" |
| 4 | 2 | Version | 0x0101(v1.1) |
| 6 | 2 | Flags | bit0 = 编解码描述符扩展段在位(紧随 64B 头的 16B WalCodecDescriptorSection——压缩/加密卷持久配置;bit0=0 时容器与缺省卷逐字节一致) |
| 8 | 8 | TailIndex | 最后一条已分配 entry index(持久化水位) |
| 16 | 16 | TailAddress | 尾 index 对应 record 地址 |
| 32 | 8 | HeadIndex | 头截断边界 index |
| 40 | 16 | HeadAddress | 头边界地址 |
| 56 | 8 | ArchivedIndex | 归档持久水位(sink 已确认收讫最大 index——留存/截断水位闸) |
| 64 | 16? | 编解码扩展段 | Flags bit0=1 时在位(16B) |
| — | var | raft meta | 原样追加(内容零知识;容量 = MetaOpaqueBytes − 64 − (扩展段在位 ? 16 : 0)) |
⚠ 注意:定位锚点(每 AnchorInterval=1024 条一个 [index→addr])是纯内存结构,不落盘
(恢复随顺序重放重建)——opaque 只记 head/tail/archived 三水位。
⚠ 注意:段 anchor 表(24B/条 = index 8B + LogicalAddress 16B,每 AnchorInterval=1024 条一个)是纯内存结构,不落盘(恢复从头顺序扫重建)——opaque 只记 head/tail 两个锚点。
TierWAL raft 元数据 opaque(RaftStoreMeta,41B,Products.Net):[Version 1B][Term 8B][VotedFor 16B][AppliedIndex 8B][SnapshotIndex 8B]。
TierWAL 快照传输格式:Header 14B([Magic 4B "WTHD"][Version 2B][SnapshotIndex 8B]);Payload 帧 [PayloadLength 4B][payload];Footer 24B([Magic 4B "WTFT"][EntryCount 8B][TotalPayload 8B][Crc32C 4B],CRC32C 增量覆盖 Header+全部 payload 帧字节)。
源码:Products/Wal/WalOpaqueHeader.cs、WalOpaqueLayout.cs、WalSnapshotFormat.cs、Products.Net/RaftStore/TierWalRaftStore.Layouts.cs:40-71。
3.2 Kv 值帧 + KvVersionOpaque
KvValueFrameHeader(9B):[Tag 1B = 0xC8][ExpiryTicks 8B LE] + payload。ExpiryTicks = UTC Ticks(0 = 无过期)。全量封装不变式:经 TierKv 写入的一切值都带帧(无 TTL = ticks 0)——读侧嗅探 tag 无歧义。
KvVersionOpaque(24B,Ring opaque meta):
[0..8) HighWater 8B LE 已分配最高版本
[8..12) Magic 4B LE 0x544B5631 "TKV1"(代际守卫)
[12..16) SweepSegId 4B LE 过期回收扫描水位 SegId(<0 = 未持久化态)
[16..24) SweepOffset 8B LE 扫描水位 Offset
旧 12B 块兼容(仅 HighWater+Magic)。版本随 2PC Prepare 同块原子落盘。
源码:Products/Kv/KvValueFraming.cs、KvVersionAllocator.cs。
3.3 TimeSeries 键 / envelope / 水位
TimeKey(16B,单序列):[Timestamp 8B][Tiebreaker 8B] LE。Ring record key = (Timestamp, 0);索引 key = (Timestamp, addr.Offset)。
DenseTimeKey(20B,dense 多序列):[SeriesId 4B uint][Timestamp 8B][Tiebreaker 8B](SeriesId 领先 → 单树逐序列键域连续)。
TTS1 envelope 头(21B,单序列):[Magic 4B "TTS1"=0x31535454][Flags 1B][Timestamp 8B][Seq 8B] + payload;Flags bit0 HAS_SEQ(0x1)。
TTS2 envelope 头(25B,dense):[Magic 4B "TTS2"=0x32535454][Flags 1B][SeriesId 4B][Timestamp 8B][Seq 8B] + payload。两模式 magic 换代互不误读。
TimeSeriesWatermarkState(40B,VersionedMetadata payload):[0..8) TrimmedUntilTimestamp 8 [8..12) TrimmedSegId 4 [12..16) TrimmedExtension 4 [16..24) TrimmedOffset 8 [24..32) SampleCount 8 [32..40) WatermarkEpoch 8。
DenseSeriesWatermarkBlock(36B/条):[SeriesId 4][TrimmedUntilTimestamp 8][TrimmedSegId 4][TrimmedExtension 4][TrimmedOffset 8][SampleCount 8]。
Dense 水位文档:[默认槽 40B(seriesId 0)][BlockCount 4B][n × 36B 块]。
源码:Products/TimeSeries/TimeKey.cs、DenseTimeKey.cs、TimeSeriesEnvelope.cs、TimeSeriesWatermark.cs、DenseSeriesWatermark.cs。
3.4 Blob 对象表帧
{name}.blob.meta 上基于 StreamSnapshot 的版本链记录帧流(每条登记/删除/标损 = 一帧):
[StreamFrameHeader 14B][BlobObjectEntryPayload 48B + 对齐补零][StreamFrameFooter 28B]
BlobObjectEntryPayload(48B):
| 偏移 | 宽度 | 字段 |
|---|---|---|
| 0 | 4 | ObjectIdSegId |
| 4 | 4 | ObjectIdExtension |
| 8 | 8 | ObjectIdOffset |
| 16 | 8 | Length |
| 24 | 8 | FrameLength |
| 32 | 8 | CreatedTicks |
| 40 | 8 | StateAndReserved(低字节 = BlobState,高 7B 恒 0) |
帧头/帧尾 = 2.10 的 StreamFrameHeader/Footer(CRC64 帧级自校验)。帧扇区对齐不变式(物理 = 逻辑布局,重启恒等映射读回成立)。恢复 = meta O(1) 水位 + 定步长逐帧重放(步长不齐 fail-fast)。
源码:Products/Blob/BlobObjectTable.cs(FrameHeaderSize=14、FrameFooterSize=28、PayloadSize=48)。