TsDB2/DB/core/header_page.go

package core

import (
	"encoding/binary"
	"fmt"
	"time"
	"unsafe"

	"git.ycl.pub/yl32940/TsDB2/DB/core/page"
)

// 编译期断言: 钉死 HeaderPage 的盘上布局 —— 字段重排/增删都会在这里编译失败,
// 而不是让 analyzer 的硬编码偏移静默读错。
//
// 布局分组 (v11 重排, 全部标量字段 8 字节对齐、零对齐填充):
//
//	[0,16)    标识与分配: Magic/Version/PageSize/NextFreePage
//	[16,48)   时间与事务: CreateTime/ModifyTime/NextTxnID/GlobalFlags (8 字节标量)
//	[48,76)   表/空闲链/WAL: TablePage/TableCount/FreePageStart/FreePageEnd/
//	          FreePageCount/FirstWALPage/LastWALPage (4 字节标量, 两两紧邻无填充)
//	[76,332)  扩展: ExtConfigHdr[8] (预留) + HeaderCrc uint32 (偏移 84,
//	          整页 XXH32 校验, 写入前由 PrepareWrite 生成) + ExtConfig[244]
//	[332,4096) 介绍区: Comment[3764] — 占满头页余下全部空间 (建库默认写入
//	          当前版本的功能介绍与修复点, 见 VersionComment; 用户可用
//	          DB.SetComment 改写, 上限即本字段容量)
//
// 8 字节标量全部排在前半段 (偏移 16~48), 4 字节标量排在后半段 (偏移 48~76),
// 任何字段后面都不留填充字节。
var (
	// 整体头页结构体必须严格等于4K
	_ [PageSize4K - unsafe.Sizeof(HeaderPage{})]struct{}
	_ [unsafe.Sizeof(HeaderPage{}) - PageSize4K]struct{}

	// FreePageEnd 紧跟 FreePageStart，间隔4字节
	_ [unsafe.Offsetof(HeaderPage{}.FreePageEnd) - (unsafe.Offsetof(HeaderPage{}.FreePageStart) + 4)]struct{}

	// 锁定各个字段偏移
	_ [16]byte  = [unsafe.Offsetof(HeaderPage{}.CreateTime)]byte{}
	_ [24]byte  = [unsafe.Offsetof(HeaderPage{}.ModifyTime)]byte{}
	_ [32]byte  = [unsafe.Offsetof(HeaderPage{}.NextTxnID)]byte{}
	_ [40]byte  = [unsafe.Offsetof(HeaderPage{}.GlobalFlags)]byte{}
	_ [84]byte  = [unsafe.Offsetof(HeaderPage{}.HeaderCrc)]byte{}
	_ [332]byte = [unsafe.Offsetof(HeaderPage{}.Comment)]byte{}

	// Comment 区域大小校验
	_ [PageSize4K - 332]byte = [unsafe.Sizeof(HeaderPage{}.Comment)]byte{}
)

// 数据库全局头页（PageID=0 固定）
type HeaderPage struct {
	Magic         [4]byte // 0    魔术字，识别文件类型
	Version       uint32  // 4    版本
	PageSize      uint32  // 8    每页大小（比如 4096）
	NextFreePage  uint32  // 12   下一个可用空闲页
	CreateTime    int64   // 16   建库时间 (纳秒)
	ModifyTime    int64   // 24   最近修改时间 (纳秒)
	NextTxnID     uint64  // 32   下一个事务 ID
	GlobalFlags   uint64  // 40   全局状态
	TablePage     uint32  // 48   【唯一重要】表链起始页ID
	TableCount    uint32  // 52   表数量
	FreePageStart uint32  // 56   空闲页链表头
	FreePageEnd   uint32  // 60   空闲页链表尾 (0 = 空闲链为空)。
	// 不变量: FreePageStart == 0 当且仅当 FreePageEnd == 0,
	// 两者必须同生同灭 (摘链/还链处维护)。
	FreePageCount uint32 // 64   空闲页数量
	FirstWALPage  uint32 // 68   未恢复的 WAL 链首页 ID (0=无待恢复WAL)
	LastWALPage   uint32 // 72   WAL 链尾页 ID (追加写入用)

	//将来以后可以是 前 4 字节：`ExtVer` 扩展区版本号 后 4 字节：`ExtFlags` 扩展特性标记位 `ExtVer == 0`：旧库，
	//`ExtConfig`区域未初始化，忽略解析 `ExtVer >=1`：按对应版本解析 244 字节扩展配置 ExtFlags- `bit0`：数据库只读标记
	//- `bit1`：启用页级独立校验（除头页 CRC 外，普通数据页单独校验）
	//- `bit2`：启用数据压缩
	//- `bit3`：启用加密，密钥索引放在 ExtConfig 里面
	//- `bit4`：WAL 持久化模式标记
	//- 其余 bit 预留，未来新增特性
	ExtConfigHdr [8]byte // 76   扩展配置: 头 8 字节 (预留, 保持 84 前不动) 扩展配置
	HeaderCrc    uint32  // 84   整页 XXH32 校验 (写入前由 PrepareWrite 生成;
	//      旧 v11 库该字段为 0 = 无校验, 首次写头页自动生成)
	ExtConfig [244]byte              // 88   扩展配置其余
	Comment   [PageSize4K - 332]byte // 332  数据库介绍区 (3764B, 占满整页余下空间;
	//      建库默认写入 VersionComment, 可用 DB.SetComment 改写)
}

// CalcHeaderCrc 计算整页 4096 字节的 XXH32。计算期间临时把 HeaderCrc 字段
// 清零 (CRC 的覆盖范围是"除 CRC 自身外的整页"), 算完恢复原值 —— 本方法
// 不改变结构体状态, 可随意调用。
//
// 序列化方式与 ReadHeader/writeHeaderLocked 一致 (unsafe 直映, 小端机
// 内存布局即盘上布局), 所以这里算出的值与盘上字节严格对应。
func (h *HeaderPage) CalcHeaderCrc() uint32 {
	buf := (*[PageSize4K]byte)(unsafe.Pointer(h))[:]
	off := int(unsafe.Offsetof(HeaderPage{}.HeaderCrc))
	saved := binary.LittleEndian.Uint32(buf[off : off+4])
	binary.LittleEndian.PutUint32(buf[off:off+4], 0)
	crc := XXH32(buf)
	binary.LittleEndian.PutUint32(buf[off:off+4], saved)
	return crc
}

// Validate 打开数据库时的头页校验。
//
//   - Magic 必查;
//   - CRC: 版本 11 且 HeaderCrc == 0 视为【旧 v11 库】—— 该字段在旧库里是
//     ExtConfig 预留区, 恒为 0 —— 跳过校验, 首次 PrepareWrite 会自动生成
//     CRC (版本号不变, 同号文件自动升级出校验能力);
//     其余情况 (v11 已带 CRC, 或未来 v12+) 一律校验, 不匹配返回错误。
func (h *HeaderPage) Validate() error {
	if h.Magic != Magic {
		return fmt.Errorf("invalid database file: bad magic %v, expected %v", h.Magic, Magic)
	}
	if h.Version == Version && h.HeaderCrc == 0 {
		return nil // 旧 v11: 无 CRC, 跳过
	}
	if got := h.CalcHeaderCrc(); got != h.HeaderCrc {
		return fmt.Errorf("头页 CRC 校验失败: 期望 %08x, 实际 %08x —— 文件可能损坏或不是 VRTX 数据库", h.HeaderCrc, got)
	}
	return nil
}

// PrepareWrite 头页落盘前调用: 计算整页 XXH32 写入 HeaderCrc 字段。
//
// 所有头页写都汇聚在 File.writeHeaderLocked 一处, 该方法在那里被统一调用,
// 因此任何路径 (Commit / 页分配 / SetComment / VACUUM ...) 出盘的头页
// CRC 都是最新的。对旧 v11 库, 这一步同时就是"自动生成 CRC"的升级点。
func (h *HeaderPage) PrepareWrite() {
	h.HeaderCrc = h.CalcHeaderCrc()
}

// newPageWithReader 分配新页：优先从空闲链表头取, 否则递增分配。
// 必须带读盘能力 —— 空闲链的 next 存在页头 PageHdr.NextPage, 不读页就摘不下来。
//
// writePage 用来把摘到的页擦成"干净空白页"(可为 nil, 表示调用方自己保证整页覆写)。
//
// 为什么擦页必须发生在这个入口:
//   - 空闲链上的页是回收来的, 而 recycleChain 是 O(1) 拼接 —— 只改写链尾 1 页,
//     链内页的正文一个字节都不动 (逐页覆写就把 O(1) 打回 O(n), DropTable 的堆链、
//     提交后的整条 WAL 链正是靠它才不慢)。于是这些页在盘上留着它上一世的内容:
//     典型是 WAL 页 (Type=7、UseSize=16384、NextPage 还指着旧 WAL 链)。
//   - 分配方拿到页号后只要有一次"先读后写", 读到的就是这些残存字节。历史上
//     IndexMetaPage.Init 正是这么把整页 WAL 残留当成 IndexMeta 数组解析出 91 条垃圾
//     元数据 (EntryPage=16777216), 最终让 DROP TABLE 拿着垃圾页号去 FreePage:
//     写到几十 GB 偏移、稀疏文件暴涨到 40GB、DROP 假死 52s。
//   - 这条不变量以前靠"每个调用点自己记得整页覆写"维持 (当时十几个调用点确实都做到了),
//     但它散在十几个地方, 违约的代价是静默的数据错乱而不是报错。现在收到唯一入口上:
//     凡是 NewPage 交出的页, 盘上/池里一定是"全 0 + 自述页号"。
//
// 为什么用 writePage (= File.WritePage, 走缓冲池) 而不是直写盘:
// 调用方紧接着的整页写入会覆盖池里同一份缓存, 因此不额外产生物理 IO, 顺带把池里
// 可能残留的陈旧副本一并覆盖; 未启用缓冲池时退化为一次直写 (每页一次, 不是每行一次)。
func (header *HeaderPage) newPageWithReader(readPage func(uint32, []byte) error,
	writePage func(uint32, []byte) error) uint32 {

	var pid uint32
	if header.FreePageStart != 0 {
		pid = header.FreePageStart
		buf := make([]byte, PageSize)
		if err := readPage(pid, buf); err == nil {
			// 空闲页与其它页一样符合 PageHdr: 下一个空闲页 ID 存在页头的 NextPage
			next := page.HdrOf(buf).NextPage
			header.FreePageStart = next
			if next == 0 {
				// 摘完链表就空了, 尾指针必须跟着清零, 否则留下悬垂尾指针
				header.FreePageEnd = 0
			}
			header.FreePageCount--
		} else {
			// 读失败，回退到递增分配
			pid = header.NextFreePage
			header.NextFreePage++
		}
	} else {
		pid = header.NextFreePage
		header.NextFreePage++
	}

	if writePage != nil {
		// 页头只留自述页号 (Type=0 未定型、UseSize=页头长), 其余字节全 0。
		// 自述页号不是可有可无的: loadMetas / Init 这类"读盘重建"的路径会校验
		// Hdr.PageID == pageID, 靠它挡住"页号复用错了"的误读。
		clean := make([]byte, PageSize)
		page.HdrOf(clean).Init(0, pid)
		_ = writePage(pid, clean)
	}
	return pid
}

// recyclePage 回收一个页到空闲链表（头插, 只写 1 页）。
//
// 页统一符合 PageHdr: 空闲链指针写在页头的 NextPage (偏移 12), 不再占用偏移 0
// 的 Type/RefCount 字段。这样空闲页仍是一张"正规页", 而且堆页/索引链的 NextPage
// 与空闲链的 NextPage 是同一个字段 —— 整条链可以 O(1) 拼接到空闲链上。
func (header *HeaderPage) recyclePage(pageID uint32, savePage func(uint32, []byte) error) {
	buf := make([]byte, PageSize)
	hdr := page.HdrOf(buf)
	hdr.PageID = pageID
	hdr.NextPage = header.FreePageStart
	header.FreePageStart = pageID
	if header.FreePageEnd == 0 {
		// 原空闲链为空: 这一页既是头也是尾
		header.FreePageEnd = pageID
	}
	header.FreePageCount++
	_ = savePage(pageID, buf)
}

// recycleChain 把一条已经用 PageHdr.NextPage 串好的整链 (head…tail) 整体挂到
// 空闲链表尾。O(1): 只改写「原空闲链尾」1 页 + 更新头页, 既不逐页遍历也不逐页覆零。
//
// 前提: head…tail 每页的 next 都写在 PageHdr.NextPage, 且 tail.NextPage == 0。
// count 是该链的页数, 由构造方 (WAL 写入时) 或遍历方 (崩溃恢复时) 顺手统计而来 ——
// 正因为链长已知, 这里才能不遍历就把 FreePageCount 加对。
//
// 为什么挂链尾而不是头插: 刚回收的大块 (比如整张被 DROP 的表) 排在空闲链后段,
// 空闲链头的分配前沿不动, 语义也更接近「把这些页排队等着复用」。
func (header *HeaderPage) recycleChain(head, tail uint32, count uint32,
	readPage func(uint32, []byte) error, savePage func(uint32, []byte) error) error {
	if head == 0 || tail == 0 || count == 0 {
		return nil
	}
	if header.FreePageEnd != 0 {
		// 原空闲链尾 → 新链头, 两条链就此接成一条
		buf := make([]byte, PageSize)
		if err := readPage(header.FreePageEnd, buf); err != nil {
			return err
		}
		page.HdrOf(buf).NextPage = head
		if err := savePage(header.FreePageEnd, buf); err != nil {
			return err
		}
	} else {
		// 原空闲链为空: 这条链就是整条空闲链
		header.FreePageStart = head
	}
	header.FreePageEnd = tail
	header.FreePageCount += count
	return nil
}

// recycleChainWithCache 整链还链 + 刷新被改写页的缓冲池副本。
//
// recycleChain 用 savePage (=WritePageDirect) 改写「原空闲链尾」, 绕过了 BufferPool;
// 那一页在池里可能还留着干净旧副本, 之后任何走 ReadPage 的读取都会拿到错内容 ——
// 所以从盘读回、同步一次缓存。链内其它页的 next 没被改动, 池里的副本仍然准确,
// 不必逐页刷新 (逐页刷新就等于把 O(1) 又变回 O(n) 了)。
func recycleChainWithCache(ff *File, header *HeaderPage, head, tail, count uint32) error {
	if count == 0 {
		return nil
	}
	oldTail := header.FreePageEnd
	if err := header.recycleChain(head, tail, count, ff.readPageDisk, ff.WritePageDirect); err != nil {
		return err
	}
	if oldTail != 0 {
		syncBuf := make([]byte, PageSize)
		if err := ff.readPageDisk(oldTail, syncBuf); err == nil {
			ff.SyncCache(oldTail, syncBuf)
		}
	}
	return nil
}

func newHeader(desc string) (*HeaderPage, error) {
	// 未提供介绍 → 默认写入当前版本的功能介绍与修复点 (VersionComment)
	if desc == "" {
		desc = VersionComment
	}
	var comment [PageSize4K - 332]byte

	// 1. 安全判断：防止描述超长
	if len(desc) > len(comment) {
		return nil, fmt.Errorf("描述字符串长度 %d 超过最大限制 %d", len(desc), len(comment))
	}
	copy(comment[:], desc)

	// 2. 初始化头部（全部正确赋值，无遗漏、无坑）
	return &HeaderPage{
		Magic:         Magic,                 // 魔数
		Version:       Version,               // 版本
		PageSize:      PageSize,              // 页大小
		NextFreePage:  2,                     // 下一个分配页从 2 开始（0=header, 1=table page 已预留）
		TablePage:     0,                     // 初始无表
		TableCount:    0,                     // 表数量=0
		CreateTime:    time.Now().UnixNano(), // 纳秒时间戳
		ModifyTime:    time.Now().UnixNano(),
		FreePageStart: 0,            // 初始无空闲页
		FreePageCount: 0,            // 空闲页数量=0
		GlobalFlags:   0,            // 无标志
		NextTxnID:     1,            // 事务 ID 从 1 开始 (0 保留, 便于 WAL 页首页判定)
		ExtConfigHdr:  [8]byte{0},   // 扩展配置 前 4 字节：`ExtVer` 扩展区版本号 后 4 字节：`ExtFlags` 扩展特性标记位
		ExtConfig:     [244]byte{0}, // 清空扩展配置
		Comment:       comment,      // 数据库描述
	}, nil
}