pi_block_device 0.1.0

Asynchronous copy-on-write block storage abstractions
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
//! # pi_block_device
//!
//! 本 crate 定义异步写时复制块设备的稳定公共接口,并提供基于文件系统的 FileBlockStore。
//! 写入通过单写者事务完成,提交后方可读取。文件实现使用追加日志恢复状态;恢复会
//! 截断 Active 段的完整冗余尾部并删除未引用孤儿文件。提交结果不确定时实例要求恢复。
//! `release_blocks` 可原子释放普通块和大块,并在 durable 发布后通过进程内退休队列延迟
//! 删除不再受固定快照或读取缓冲保护的文件。
//!
//! ## 碎片整理与空间回收
//!
//! 块设备不解析块内引用,也不会在后台自动搬迁仍存活的数据。外部整理器应先从一个
//! 固定 [`ReadSnapshot`] 选择稀疏段并读取其中的存活块,再通过普通 [`WriteTransaction`]
//! 分配和写入替代块、重写上层引用或根,最后调用 [`WriteTransaction::release_blocks`]
//! 逻辑释放旧块并提交。这样整理操作与普通业务写入共享相同的顺序校验和 durable 协议,
//! 不需要独立的整理会话。
//!
//! 逻辑释放不等于立即删除物理文件。只有当提交后的 State 已不再引用整个段或大块时,
//! 文件后端才会在 durable 发布之后把对应路径登记到退休队列。退休 worker 还会检查当前
//! State、固定快照和已返回读取缓冲持有的路径 lease;所有保护解除后才执行 unlink。
//! 日志 rotate、checkpoint 和 archive 属于日志维护,不会代替上述数据搬迁流程。
//!
//! 指标仍为零值占位;Windows 目录同步对平台不支持的错误采用 best effort。

#![deny(missing_docs)]

use smallvec::SmallVec;

mod file;

/// 基于文件系统与追加日志的块存储实现。
pub use file::FileBlockStore;

/// BlockId 低四位的级别掩码。
const LEVEL_MASK: u64 = 0x0f;
/// 普通块段版本字段掩码。
const SEGMENT_VERSION_MASK: u64 = 0x0fff_ffff;
/// 表示独立大块的特殊级别。
const LARGE_LEVEL: u8 = 15;
/// 保留的大块编号上界哨兵。
const MAX_LARGE_BLOCK_ID: u64 = (1_u64 << 60) - 1;
/// 以 KiB 表示的普通块槽位尺寸。
const SLOT_SIZES: [u64; 15] = [4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384, 512];

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
/// V1 日志记录的只读序号;公开值始终可读取,Null 仅供 crate 内持久状态使用。
pub struct RecordSeq(pub(crate) u32);

impl RecordSeq {
    /// V1 持久格式中表示“尚未发生”的 Null 序号。
    pub(crate) const NULL: Self = Self(u32::MAX);

    /// 校验并构造有效日志序号。
    pub(crate) fn new(value: u32) -> std::io::Result<Self> {
        if value == 0 || value == u32::MAX {
            Err(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                "invalid record sequence",
            ))
        } else {
            Ok(Self(value))
        }
    }

    /// 校验 64 位日志序号可无损表示且属于 V1 有效业务序号范围。
    pub(crate) fn try_from_u64(value: u64) -> std::io::Result<Self> {
        let value = u32::try_from(value).map_err(|_| {
            std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                "record sequence exceeds V1 range",
            )
        })?;
        Self::new(value)
    }

    /// 返回底层日志序号值。
    pub fn get(self) -> u32 {
        self.0
    }

    /// 返回该值是否为 crate 内持久格式使用的 Null 序号。
    pub fn is_null(self) -> bool {
        self == Self::NULL
    }
}

/// 持久提交成功后的业务记录序号与维护结果。
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct CommitResult {
    /// 表示业务状态已持久发布的日志记录序号。
    business_record_seq: RecordSeq,
    /// 提交后维护工作的执行结果。
    maintenance: MaintenanceResult,
}

impl CommitResult {
    /// 从已验证的业务记录序号和维护结果构造提交结果。
    pub(crate) fn new(business_record_seq: RecordSeq, maintenance: MaintenanceResult) -> Self {
        Self {
            business_record_seq,
            maintenance,
        }
    }

    /// 返回持久发布业务状态的日志记录序号。
    pub fn business_record_seq(&self) -> RecordSeq {
        self.business_record_seq
    }

    /// 返回提交后维护工作的执行结果。
    pub fn maintenance(&self) -> &MaintenanceResult {
        &self.maintenance
    }
}

/// 持久提交完成后维护工作的结果。
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum MaintenanceResult {
    /// 当前提交不需要执行维护工作。
    NotNeeded,
    /// 维护工作已成功持久化。
    Completed {
        /// 表示维护状态已持久发布的日志记录序号。
        record_seq: RecordSeq,
    },
    /// 维护工作失败,并报告存储是否仍可继续服务。
    Failed {
        /// 稳定、可拥有的维护错误分类。
        error: MaintenanceError,
        /// 维护失败后的存储服务状态。
        store_status: MaintenanceStoreStatus,
    },
}

/// 维护工作失败的稳定分类。
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum MaintenanceError {
    /// 无法准备维护工作所需的状态或资源。
    PreparationFailed,
    /// 无法追加维护工作的持久记录。
    AppendFailed,
}

/// 维护失败后存储实例的可服务状态。
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum MaintenanceStoreStatus {
    /// 存储仍可安全继续服务。
    Ready,
    /// 存储已被围栏,必须恢复后才能继续服务。
    RecoveryRequired,
}

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
/// 普通段的只读 28 位非零版本号。
pub struct SegmentVersion(pub(crate) u32);

impl SegmentVersion {
    /// 校验并构造可编码的普通段版本。
    pub(crate) fn new(value: u32) -> std::io::Result<Self> {
        if value == 0 || value > SEGMENT_VERSION_MASK as u32 {
            Err(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                "invalid segment version",
            ))
        } else {
            Ok(Self(value))
        }
    }

    /// 返回底层段版本值。
    pub fn get(self) -> u32 {
        self.0
    }
}

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
/// 独立大块的只读非零编号。
pub struct LargeBlockId(pub(crate) u64);

impl LargeBlockId {
    /// 校验并构造可分配的大块编号。
    pub(crate) fn new(value: u64) -> std::io::Result<Self> {
        if value == 0 || value >= MAX_LARGE_BLOCK_ID {
            Err(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                "invalid large block id",
            ))
        } else {
            Ok(Self(value))
        }
    }

    /// 返回底层大块编号。
    pub fn get(self) -> u64 {
        self.0
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
/// 编码普通段槽位或独立大块位置的稳定块标识。
pub struct BlockId(
    /// 冻结的 64 位编码:低 4 位为级别,其余位按普通块或大块布局解释。
    u64,
);

/// 初始化时生成并持久化的 128 位设备身份。
pub struct DeviceId(
    /// 持久化到检查点并用于校验日志结构链的 16 字节身份。
    [u8; 16],
);

impl DeviceId {
    /// 返回设备身份的原始字节。
    pub fn as_bytes(&self) -> &[u8; 16] {
        &self.0
    }
}

/// 描述设备声明支持的可选能力。
pub struct BlockDeviceCapabilities {
    /// 压缩能力标志。
    compression: bool,
    /// 加密能力标志。
    encryption: bool,
    /// 数据校验和能力标志。
    data_checksums: bool,
}

impl BlockDeviceCapabilities {
    /// 返回是否支持压缩。
    pub fn compression(&self) -> bool {
        self.compression
    }

    /// 返回是否支持加密。
    pub fn encryption(&self) -> bool {
        self.encryption
    }

    /// 返回是否支持数据校验和。
    pub fn data_checksums(&self) -> bool {
        self.data_checksums
    }
}

/// 设备指标快照;文件实现当前返回零值占位。
pub struct BlockDeviceMetricsSnapshot {
    /// 已使用字节数。
    used_bytes: u64,
    /// 空闲字节数。
    free_bytes: u64,
    /// 可供调用方使用的字节数。
    available_bytes: Option<u64>,
    /// 读取操作计数。
    read_ops: u64,
    /// 读取字节计数。
    read_bytes: u64,
    /// 写入操作计数。
    write_ops: u64,
    /// 写入字节计数。
    write_bytes: u64,
    /// 成功提交计数。
    commit_ok: u64,
    /// 失败提交计数。
    commit_failed: u64,
    /// 恢复计数。
    recovery_count: u64,
    /// 回收字节计数。
    reclaimed_bytes: u64,
}

impl BlockDeviceMetricsSnapshot {
    /// 返回已用字节数。
    pub fn used_bytes(&self) -> u64 {
        self.used_bytes
    }

    /// 返回空闲字节数。
    pub fn free_bytes(&self) -> u64 {
        self.free_bytes
    }

    /// 返回可用字节数,未知时为 None。
    pub fn available_bytes(&self) -> Option<u64> {
        self.available_bytes
    }

    /// 返回读取操作数。
    pub fn read_ops(&self) -> u64 {
        self.read_ops
    }

    /// 返回读取字节数。
    pub fn read_bytes(&self) -> u64 {
        self.read_bytes
    }

    /// 返回写入操作数。
    pub fn write_ops(&self) -> u64 {
        self.write_ops
    }

    /// 返回写入字节数。
    pub fn write_bytes(&self) -> u64 {
        self.write_bytes
    }

    /// 返回成功提交数。
    pub fn commit_ok(&self) -> u64 {
        self.commit_ok
    }

    /// 返回失败提交数。
    pub fn commit_failed(&self) -> u64 {
        self.commit_failed
    }

    /// 返回恢复次数。
    pub fn recovery_count(&self) -> u64 {
        self.recovery_count
    }

    /// 返回回收字节数。
    pub fn reclaimed_bytes(&self) -> u64 {
        self.reclaimed_bytes
    }
}

/// 块分配所携带的待写内容。
pub struct WriteInput {
    /// 块的逻辑字节;普通块会补零至完整槽位。
    pub data: Vec<u8>,
}

/// 绑定到特定存储与事务的待写块凭证。
pub struct AllocatedBlock {
    /// 最终块标识。
    block: BlockId,
    /// 尚待 write_batch 消费的原始输入。
    _input: WriteInput,
    /// 创建凭证的存储实例身份。
    _store_identity: u64,
    /// 创建凭证的事务身份。
    _transaction_identity: u64,
}

impl AllocatedBlock {
    /// 返回最终块标识。
    pub fn block_id(&self) -> BlockId {
        self.block
    }

    /// 构造绑定到存储和事务的分配凭证。
    pub(crate) fn new(
        block: BlockId,
        input: WriteInput,
        store_identity: u64,
        transaction_identity: u64,
    ) -> Self {
        Self {
            block,
            _input: input,
            _store_identity: store_identity,
            _transaction_identity: transaction_identity,
        }
    }

    /// 消费凭证并取回校验与写入所需字段。
    pub(crate) fn into_parts(self) -> (BlockId, WriteInput, u64, u64) {
        (
            self.block,
            self._input,
            self._store_identity,
            self._transaction_identity,
        )
    }
}

/// 非空的命名根名称。
pub struct RootName(
    /// 已验证为非空的 UTF-8 名称;内容按字节保留。
    String,
);

impl RootName {
    /// 校验并创建非空根名称。
    ///
    /// # Errors
    ///
    /// `value` 为空时返回 [`BlockStoreError::RootNameEmpty`]。
    pub fn new(value: String) -> Result<Self, BlockStoreError> {
        if value.is_empty() {
            Err(BlockStoreError::RootNameEmpty)
        } else {
            Ok(Self(value))
        }
    }

    /// 返回名称字符串视图。
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// 从已由持久状态验证的非空字符串构造名称。
    pub(crate) fn from_validated(value: String) -> Self {
        Self(value)
    }
}

/// 指向一个已提交块的根版本。
pub struct RootVersion {
    /// 该根在固定快照中引用的已验证 `BlockId`。
    block: BlockId,
}

impl RootVersion {
    /// 从已验证块构造根版本。
    pub(crate) fn new(block: BlockId) -> Self {
        Self { block }
    }

    /// 返回根版本引用的块。
    pub fn block(&self) -> BlockId {
        self.block
    }
}

/// 名称及其目标根版本的快照值。
pub struct NamedRoot {
    /// 绑定名称。
    name: RootName,
    /// 绑定或匿名项所含根版本。
    root: RootVersion,
}

impl NamedRoot {
    /// 从已验证名称和根块构造快照缓存项。
    pub(crate) fn new(name: RootName, block: BlockId) -> Self {
        Self {
            name,
            root: RootVersion::new(block),
        }
    }

    /// 返回绑定名称。
    pub fn name(&self) -> &RootName {
        &self.name
    }

    /// 返回目标根版本。
    pub fn root(&self) -> &RootVersion {
        &self.root
    }
}

/// 没有任何名称绑定的根版本快照值。
pub struct AnonymousRoot {
    /// 未被任何名称指向的根版本。
    root: RootVersion,
}

impl AnonymousRoot {
    /// 从已验证根块构造匿名根缓存项。
    pub(crate) fn new(block: BlockId) -> Self {
        Self {
            root: RootVersion::new(block),
        }
    }

    /// 返回目标根版本。
    pub fn root(&self) -> &RootVersion {
        &self.root
    }
}

/// 段在固定快照中的持久状态。
pub enum SegmentState {
    /// 仍可在尾部追加槽位。
    Active,
    /// 已封存,不再原地追加。
    Sealed,
}

/// 仅在创建它的存储实例和快照中有效的段标识。
pub struct SegmentId {
    /// 创建此标识的进程内存储实例身份。
    store_identity: u64,
    /// 创建段标识的快照身份。
    snapshot_identity: u64,
    /// 编码级别和版本的内部段键。
    segment_key: u64,
}

impl SegmentId {
    /// 组合存储身份、快照身份和内部段键;仅由快照构建器调用。
    pub(crate) fn new(store_identity: u64, snapshot_identity: u64, segment_key: u64) -> Self {
        Self {
            store_identity,
            snapshot_identity,
            segment_key,
        }
    }

    /// 返回创建该标识的存储实例身份。
    pub(crate) fn store_identity(&self) -> u64 {
        self.store_identity
    }

    /// 返回创建该标识的固定快照身份。
    pub(crate) fn snapshot_identity(&self) -> u64 {
        self.snapshot_identity
    }

    /// 返回由级别和版本编码的内部段键。
    pub(crate) fn segment_key(&self) -> u64 {
        self.segment_key
    }
}

/// 固定快照中的段布局与存活统计。
pub struct SegmentInfo {
    /// 绑定到当前存储与快照作用域的段标识。
    segment: SegmentId,
    /// 普通段级别,范围为 `0..=14`。
    level: u8,
    /// 该级别单个槽位的字节数。
    slot_size: u64,
    /// 曾分配槽位数;有效索引范围为 `0..frontier`。
    frontier: u64,
    /// 快照位图中置位的存活槽位数量。
    live_count: u64,
    /// 快照时段处于 [`SegmentState::Active`] 或 [`SegmentState::Sealed`]。
    state: SegmentState,
}

impl SegmentInfo {
    /// 从已验证的内部段记录构造公开快照值。
    ///
    /// `slot_size` 以字节计,`live_count <= frontier`,且 `segment` 必须属于
    /// 将持有此值的快照。
    pub(crate) fn new(
        segment: SegmentId,
        level: u8,
        slot_size: u64,
        frontier: u64,
        live_count: u64,
        state: SegmentState,
    ) -> Self {
        Self {
            segment,
            level,
            slot_size,
            frontier,
            live_count,
            state,
        }
    }

    /// 返回绑定到创建此 `SegmentInfo` 的存储实例和固定快照的 [`SegmentId`]。
    pub fn segment(&self) -> SegmentId {
        SegmentId {
            store_identity: self.segment.store_identity,
            snapshot_identity: self.segment.snapshot_identity,
            segment_key: self.segment.segment_key,
        }
    }

    /// 返回槽位级别。
    pub fn level(&self) -> u8 {
        self.level
    }

    /// 返回槽位字节数。
    pub fn slot_size(&self) -> u64 {
        self.slot_size
    }

    /// 返回分配前沿。
    pub fn frontier(&self) -> u64 {
        self.frontier
    }

    /// 返回存活槽位数。
    pub fn live_count(&self) -> u64 {
        self.live_count
    }

    /// 返回段状态。
    pub fn state(&self) -> SegmentState {
        match &self.state {
            SegmentState::Active => SegmentState::Active,
            SegmentState::Sealed => SegmentState::Sealed,
        }
    }
}

/// 提供设备身份、块尺寸与能力信息。
pub trait BlockDeviceInfo {
    /// 返回持久设备身份。
    ///
    /// # Panics
    ///
    /// 实现若无法取得已经发布的设备状态,可以选择 panic;具体实现应记录条件。
    fn device_id(&self) -> DeviceId;
    /// 返回设备要求的基础对齐字节数,同时也是支持的最小普通槽位尺寸。
    fn base_block_size(&self) -> u64;
    /// 返回全部普通块槽位尺寸。
    fn supported_block_sizes(&self) -> &'static [u64];
    /// 返回设备能力。
    fn capabilities(&self) -> BlockDeviceCapabilities;
}

/// 提供设备指标快照。
pub trait BlockDeviceMetrics {
    /// 返回指标快照;文件实现目前为零值占位。
    fn metrics(&self) -> BlockDeviceMetricsSnapshot;
}

#[allow(async_fn_in_trait)]
/// 提供按块标识异步读取的设备接口。
pub trait AsyncBlockDevice: BlockDeviceInfo + BlockDeviceMetrics + Send + Sync + 'static {
    /// 成功读取后持有稳定字节视图的缓冲类型。
    type ReadBuf: AsRef<[u8]> + Send + 'static;

    /// 读取已提交块;返回缓冲在设备句柄释放后仍保持有效。
    ///
    /// # Errors
    ///
    /// - [`BlockStoreError::InvalidBlockId`]:编码字段或读取范围无法安全表示。
    /// - [`BlockStoreError::BlockNotCommitted`]:块属于仍未提交的分配。
    /// - [`BlockStoreError::BlockNotFound`]:标识未出现在已提交状态或已不存活。
    /// - [`BlockStoreError::BlockCorrupted`]:状态声明的范围超出物理文件。
    /// - [`BlockStoreError::Io`]:打开、metadata、seek、read 或映射失败。
    /// - [`BlockStoreError::RecoveryRequired`]:实例已被围栏或状态锁不可用。
    async fn read(&self, block: BlockId) -> Result<Self::ReadBuf, BlockStoreError>;
}

#[allow(async_fn_in_trait)]
/// 提供固定快照和单写者事务的块存储接口。
pub trait BlockStore {
    /// 固定只读快照类型。
    type Snapshot: ReadSnapshot;
    /// 独占写事务类型。
    type Transaction: WriteTransaction;

    /// 打开当前已提交状态的固定快照;后续提交不会改变该快照。
    ///
    /// # Errors
    ///
    /// 实例被围栏、状态锁中毒或快照身份耗尽时返回
    /// [`BlockStoreError::RecoveryRequired`]。
    fn open_snapshot(&self) -> Result<Self::Snapshot, BlockStoreError>;
    /// 获取单写者事务。
    ///
    /// # Errors
    ///
    /// 已有写者时返回 [`BlockStoreError::WriteTransactionBusy`];实例已被围栏或
    /// 内部状态不可用时返回 [`BlockStoreError::RecoveryRequired`]。
    async fn begin_write(&self) -> Result<Self::Transaction, BlockStoreError>;
}

/// 表示不随后续提交变化的只读状态快照。
pub trait ReadSnapshot: Send + Sync + 'static {
    /// 命名根迭代器。
    type NamedRoots<'a>: Iterator<Item = &'a NamedRoot>
    where
        Self: 'a;
    /// 匿名根迭代器。
    type AnonymousRoots<'a>: Iterator<Item = &'a AnonymousRoot>
    where
        Self: 'a;
    /// 段信息迭代器。
    type SegmentInfos<'a>: Iterator<Item = &'a SegmentInfo>
    where
        Self: 'a;
    /// 指定段内存活块迭代器。
    type LiveBlocks<'a>: Iterator<Item = BlockId>
    where
        Self: 'a;

    /// 枚举所有名称绑定。
    fn list_named_roots(&self) -> Self::NamedRoots<'_>;
    /// 枚举没有名称绑定的根。
    fn list_anonymous_roots(&self) -> Self::AnonymousRoots<'_>;
    /// 按名称查询绑定。
    fn get_named_root(&self, name: &RootName) -> Option<&NamedRoot>;
    /// 按块标识查询根版本。
    fn get_root(&self, block: BlockId) -> Option<&RootVersion>;
    /// 枚举快照中的段。
    fn segment_infos(&self) -> Self::SegmentInfos<'_>;
    /// 枚举指定段的存活块。
    ///
    /// # Errors
    ///
    /// [`SegmentId`] 来自其他存储、其他快照,或内部段键不存在时返回
    /// [`BlockStoreError::SegmentNotFound`]。
    fn live_blocks(&self, segment: SegmentId) -> Result<Self::LiveBlocks<'_>, BlockStoreError>;
}

#[allow(async_fn_in_trait)]
/// 表示独占写入权限的事务。
pub trait WriteTransaction {
    /// 分配最终 [`BlockId`] 并返回事务绑定凭证。分配不执行物理写入,也不提交块;
    /// 调用方还必须调用 [`WriteTransaction::write_batch`] 和 [`WriteTransaction::commit`]。
    ///
    /// # Errors
    ///
    /// 空输入返回 [`BlockStoreError::InvalidWriteInput`];空间不足返回
    /// [`BlockStoreError::NoSpace`];编号耗尽返回 [`BlockStoreError::SegmentVersionExhausted`]
    /// 或 [`BlockStoreError::LargeBlockIdExhausted`];关闭或围栏返回
    /// [`BlockStoreError::WriteTransactionClosed`] 或 [`BlockStoreError::RecoveryRequired`];
    /// 后端创建物理容器失败可返回 [`BlockStoreError::Io`]。
    fn alloc(&mut self, input: WriteInput) -> Result<AllocatedBlock, BlockStoreError>;
    /// 物理写入一批已分配块;每个凭证只能写一次。
    ///
    /// future 在物理写之后被取消时,实现必须关闭事务并保留未提交语义。
    ///
    /// # Errors
    ///
    /// 凭证归属错误返回 [`BlockStoreError::AllocatedBlockNotOwned`];重复写返回
    /// [`BlockStoreError::AllocatedBlockAlreadyWritten`];编码/偏移无效返回
    /// [`BlockStoreError::InvalidBlockId`];物理失败返回 [`BlockStoreError::Io`] 并关闭事务;
    /// 关闭或围栏返回 [`BlockStoreError::WriteTransactionClosed`] 或
    /// [`BlockStoreError::RecoveryRequired`]。取消发生在物理写后时事务也必须关闭。
    async fn write_batch(
        &mut self,
        blocks: SmallVec<[AllocatedBlock; 8]>,
    ) -> Result<(), BlockStoreError>;
    /// 将块加入事务最终根集合;实现可把块归属、已写与存活性验证延迟到提交。
    ///
    /// # Errors
    ///
    /// 立即可能返回 [`BlockStoreError::WriteTransactionClosed`] 或
    /// [`BlockStoreError::RecoveryRequired`];块未写在提交时返回
    /// [`BlockStoreError::AllocatedBlockNotWritten`],目标不存在或不可作为根返回
    /// [`BlockStoreError::RootNotFound`]。
    fn add_root_version(&mut self, block: BlockId) -> Result<(), BlockStoreError>;
    /// 创建名称绑定;同名最终绑定应立即失败,目标是否属于最终根集合可延迟到提交。
    ///
    /// # Errors
    ///
    /// 同名绑定立即返回 [`BlockStoreError::RootNameAlreadyBound`];关闭或围栏返回
    /// [`BlockStoreError::WriteTransactionClosed`] 或 [`BlockStoreError::RecoveryRequired`];
    /// 最终目标缺失在提交时返回 [`BlockStoreError::NamedBindingTargetNotFound`]。
    fn create_named_binding(
        &mut self,
        name: RootName,
        target: BlockId,
    ) -> Result<(), BlockStoreError>;
    /// 删除名称绑定。
    ///
    /// # Errors
    ///
    /// 名称不存在立即返回 [`BlockStoreError::NamedBindingNotFound`];关闭或围栏返回
    /// [`BlockStoreError::WriteTransactionClosed`] 或 [`BlockStoreError::RecoveryRequired`]。
    fn remove_named_binding(&mut self, name: &RootName) -> Result<(), BlockStoreError>;
    /// 暂存根删除;实现应按事务最终绑定状态验证是否仍被命名。
    ///
    /// # Errors
    ///
    /// 重复删除立即返回 [`BlockStoreError::RootAlreadyDeleted`];关闭或围栏返回
    /// [`BlockStoreError::WriteTransactionClosed`] 或 [`BlockStoreError::RecoveryRequired`];
    /// 根不存在或仍有名称在提交时返回 [`BlockStoreError::RootNotFound`] 或
    /// [`BlockStoreError::RootStillNamed`]。
    fn delete_root_version(&mut self, target: BlockId) -> Result<(), BlockStoreError>;
    /// 在事务最终状态中批量释放已提交块。文件后端先分类并验证整个普通块/大块批次,
    /// 再原子更新 candidate;普通槽位只清除存活位图,不回退 `frontier` 或复用旧空洞。
    /// 空 Sealed 段会移除,空 Active 段会替换为新版本空 Active 段。物理文件仅在
    /// durable 发布后进入进程内退休队列,并等待固定快照和精确路径读取 lease 解除后删除。
    ///
    /// # 碎片整理
    ///
    /// 调用方负责从固定快照选择整理候选,把仍存活的数据复制到本事务新分配的块,
    /// 按自身块格式重写上层引用或根,再释放旧块。实现不会解析块内容或自动发现块内引用,
    /// 因此调用方必须保证最终没有未体现在根集合中的引用仍指向待释放块。
    ///
    /// 此方法只暂存逻辑释放。段或大块从持久 State 移除并 durable 发布后,物理路径才进入
    /// 退休队列;活动快照和读取缓冲可继续延迟实际 unlink。
    ///
    /// # Errors
    ///
    /// 待提交分配返回 [`BlockStoreError::BlockNotCommitted`];不存在或越界返回
    /// [`BlockStoreError::BlockNotFound`];已死亡、同批重复或同事务重复释放返回
    /// [`BlockStoreError::BlockAlreadyReleased`];事务关闭或实例围栏分别返回
    /// [`BlockStoreError::WriteTransactionClosed`] 或 [`BlockStoreError::RecoveryRequired`]。
    /// 若最终根仍引用已释放块,提交返回 [`BlockStoreError::InvalidWriteInput`]。
    fn release_blocks(&mut self, blocks: Vec<BlockId>) -> Result<(), BlockStoreError>;
    /// 持久提交事务并发布最终状态,成功时返回业务 Delta 的精确日志序号和维护结果。
    ///
    /// 碎片整理事务与普通业务事务使用同一提交路径。维护结果类型为提交关联的日志或安全
    /// 回收维护预留表达能力;当前文件后端在业务提交成功后返回
    /// [`MaintenanceResult::NotNeeded`],日志 rotate/checkpoint/archive 由后台异步调度,
    /// 且不会自动复制稀疏段中的存活块。
    ///
    /// durable 移交前取消等价于明确中止;移交后实现必须继续内部提交或把实例
    /// 围栏为需要恢复,不能把不确定结果当作失败回滚。
    ///
    /// # Errors
    ///
    /// [`BlockStoreError::AllocatedBlockNotWritten`] 表示存在未写分配;
    /// [`BlockStoreError::NamedBindingTargetNotFound`]、[`BlockStoreError::RootStillNamed`]、
    /// [`BlockStoreError::RootNotFound`] 表示最终根/名称验证失败;
    /// [`BlockStoreError::CommitFailed`] 表示明确未持久成功;
    /// [`BlockStoreError::CommitStatusUnknown`] 表示可能已经生效;
    /// [`BlockStoreError::RecoveryRequired`] 表示实例不能继续安全服务。收到
    /// `CommitStatusUnknown` 后不得假定未生效并直接重试同一逻辑操作。
    /// 成功后事务保持为已关闭状态,后续操作返回
    /// [`BlockStoreError::WriteTransactionClosed`]。
    async fn commit(&mut self) -> Result<CommitResult, BlockStoreError>;
}

#[derive(Debug)]
/// 块存储操作可能返回的错误。
pub enum BlockStoreError {
    /// 底层 I/O 操作失败。
    Io(
        /// 保留错误种类、消息及 `source` 链的底层 I/O 错误。
        std::io::Error,
    ),
    /// 块标识编码或算术范围无效。
    InvalidBlockId,
    /// 合法块标识在已提交状态中不存在。
    BlockNotFound,
    /// 块仍属于未提交事务。
    BlockNotCommitted,
    /// 持久状态与物理文件长度或内容布局不一致。
    BlockCorrupted,
    /// 写入输入为空或不符合约束。
    InvalidWriteInput,
    /// 分配凭证不属于当前事务。
    AllocatedBlockNotOwned,
    /// 同一分配凭证已写入。
    AllocatedBlockAlreadyWritten,
    /// 事务存在尚未写入的分配。
    AllocatedBlockNotWritten,
    /// 目标块已释放,或同一释放批次/事务重复指定该块。
    BlockAlreadyReleased,
    /// 段不存在或段标识不属于当前快照。
    SegmentNotFound,
    /// 根不存在或新根目标不可接受。
    RootNotFound,
    /// 同一事务重复删除根。
    RootAlreadyDeleted,
    /// 待删除根仍有名称引用。
    RootStillNamed,
    /// 根名称为空。
    RootNameEmpty,
    /// 名称已绑定。
    RootNameAlreadyBound,
    /// 待删除名称绑定不存在。
    NamedBindingNotFound,
    /// 名称最终目标不在根集合。
    NamedBindingTargetNotFound,
    /// 已有写事务占用单写者门禁。
    WriteTransactionBusy,
    /// 事务已关闭或写入被取消。
    WriteTransactionClosed,
    /// 当前布局无法继续分配。
    NoSpace,
    /// 段版本高水位耗尽。
    SegmentVersionExhausted,
    /// 大块编号高水位耗尽。
    LargeBlockIdExhausted,
    /// 提交明确失败且未持久生效。
    CommitFailed,
    /// 提交可能已持久化,结果无法确定。
    CommitStatusUnknown,
    /// 实例已被安全围栏,必须重新打开恢复。
    RecoveryRequired,
    /// 恢复时记录、布局或清理失败。
    RecoveryFailed,
    /// Delta 或未来完整 checkpoint 超过 codec 配置上限、append-log envelope 上限,或长度计算溢出。
    RecordTooLarge,
    /// 持久格式版本高于当前实现。
    UnsupportedFormat,
}

impl PartialEq for BlockStoreError {
    /// 比较错误分类;`Io` 还比较 kind 与显示消息。
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::Io(left), Self::Io(right)) => {
                left.kind() == right.kind() && left.to_string() == right.to_string()
            }
            (Self::Io(_), _) | (_, Self::Io(_)) => false,
            _ => std::mem::discriminant(self) == std::mem::discriminant(other),
        }
    }
}

impl Eq for BlockStoreError {}

impl std::fmt::Display for BlockStoreError {
    /// 输出 `Io` 的底层消息,其他分类输出 variant 名。
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Io(source) => write!(formatter, "I/O error: {source}"),
            _ => write!(formatter, "{self:?}"),
        }
    }
}

impl std::error::Error for BlockStoreError {
    /// 仅 `Io` 暴露底层错误为 source。
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io(source) => Some(source),
            _ => None,
        }
    }
}

impl TryFrom<u64> for BlockId {
    /// 原始编码无效时返回的错误类型。
    type Error = BlockStoreError;

    /// 验证保留编码后从原始 64 位值构造 `BlockId`。
    fn try_from(raw: u64) -> Result<Self, Self::Error> {
        let level = (raw & LEVEL_MASK) as u8;
        let high_bits = raw >> 4;
        let valid = if level == LARGE_LEVEL {
            high_bits != 0 && high_bits != MAX_LARGE_BLOCK_ID
        } else {
            high_bits & SEGMENT_VERSION_MASK != 0
        };

        valid
            .then_some(Self(raw))
            .ok_or(BlockStoreError::InvalidBlockId)
    }
}

impl From<BlockId> for u64 {
    /// 无损取回冻结的 64 位编码。
    fn from(block_id: BlockId) -> Self {
        block_id.0
    }
}

impl BlockId {
    /// 从已由内部状态验证的原始值构造块标识。
    pub(crate) fn from_raw_unchecked(raw: u64) -> Self {
        Self(raw)
    }

    /// 返回槽位级别。
    pub fn level(self) -> u8 {
        (self.0 & LEVEL_MASK) as u8
    }

    /// 返回普通 `BlockId` 编码中的持久段版本;独立大块返回 `None`。
    pub fn segment_version(self) -> Option<u32> {
        (self.level() != LARGE_LEVEL).then_some(((self.0 >> 4) & SEGMENT_VERSION_MASK) as u32)
    }

    /// 返回普通块在段内的槽位索引;独立大块返回 `None`。
    pub fn block_index(self) -> Option<u32> {
        (self.level() != LARGE_LEVEL).then_some((self.0 >> 32) as u32)
    }

    /// 返回独立大块编号;普通块返回 `None`。
    pub fn large_block_id(self) -> Option<u64> {
        (self.level() == LARGE_LEVEL).then_some(self.0 >> 4)
    }

    /// 返回普通块级别对应的槽位字节数;独立大块返回 `None`。
    pub fn slot_size(self) -> Option<u64> {
        SLOT_SIZES
            .get(usize::from(self.level()))
            .map(|size_kib| size_kib * 1024)
    }
}