Table of Contents

二进制格式——产品格式(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)。