markbase/docs/fskit-research/FSKIT_API.md

# FSKit API 详细文档 ⭐⭐⭐⭐⭐

## 1. FSKit Framework 结构

**Framework位置**：`/System/Library/Frameworks/FSKit.framework`

**核心组件**：
- UnaryFilesystemExtension
- FSUnaryFileSystem
- FSVolume
- FSItem
- FSBlockDevice

---

## 2. UnaryFilesystemExtension（入口点）

**定义**：文件系统扩展入口点，相当于 kernel module init

**Swift API**：
```swift
import FSKit

class UnaryFilesystemExtension {
    // 系统调用，启动文件系统
    func start() -> Bool
    
    // 系统调用，停止文件系统
    func stop()
    
    // 返回文件系统实现
    func filesystem() -> FSUnaryFileSystem
}
```

**生命周期**：
```
1. 用户激活 Extension (System Settings)
2. macOS 调用 start()
3. 文件系统初始化
4. 返回 FSUnaryFileSystem 实例
5. macOS 调用 stop() (deactivate)
```

---

## 3. FSUnaryFileSystem（文件系统）

**定义**：文件系统核心类，管理卷和文件系统操作

**Swift API**：
```swift
class FSUnaryFileSystem {
    // 文件系统名称
    var name: String
    
    // 文件系统版本
    var version: String
    
    // 初始化文件系统
    func initialize() -> Bool
    
    // 清理文件系统
    func cleanup()
    
    // 创建卷（相当于 dataset）
    func createVolume(name: String, device: FSBlockDevice?) -> FSVolume
    
    // 删除卷
    func deleteVolume(volume: FSVolume)
    
    // 查询卷
    func queryVolumes() -> [FSVolume]
}
```

**协议 FSUnaryFileSystemOperations**：
```swift
protocol FSUnaryFileSystemOperations {
    // 启动文件系统
    func start() -> Bool
    
    // 停止文件系统
    func stop()
    
    // 处理挂载请求
    func handleMountRequest(request: FSMountRequest) -> FSVolume?
    
    // 处理卸载请求
    func handleUnmountRequest(volume: FSVolume)
}
```

---

## 4. FSVolume（卷管理）

**定义**：卷实例，相当于 ZFS dataset 或传统文件系统分区

**Swift API**：
```swift
class FSVolume {
    // 卷名称
    var name: String
    
    // 卷 ID
    var id: UUID
    
    // 所属文件系统
    var filesystem: FSUnaryFileSystem
    
    // 卷状态
    var state: FSVolumeState
    
    // 块设备（可选）
    var blockDevice: FSBlockDevice?
    
    // 根目录项
    var rootItem: FSItem
}
```

**协议 FSVolume.Operations**：
```swift
protocol FSVolumeOperations {
    // 文件操作
    func lookup(path: String) -> FSItem?
    func create(path: String, type: FSItemType) -> FSItem?
    func remove(item: FSItem) -> Bool
    func rename(item: FSItem, newPath: String) -> Bool
    
    // 读写操作
    func read(item: FSItem, offset: Int, size: Int) -> Data?
    func write(item: FSItem, offset: Int, data: Data) -> Int
    
    // 目录操作
    func readdir(directory: FSItem) -> [FSItem]
    func mkdir(path: String) -> FSItem?
    func rmdir(directory: FSItem) -> Bool
    
    // 属性操作
    func getattr(item: FSItem) -> FSItemAttributes
    func setattr(item: FSItem, attributes: FSItemAttributes) -> Bool
    
    // 扩展属性
    func getxattr(item: FSItem, name: String) -> Data?
    func setxattr(item: FSItem, name: String, value: Data) -> Bool
    func listxattr(item: FSItem) -> [String]
    func removexattr(item: FSItem, name: String) -> Bool
    
    // 锁定操作
    func lock(item: FSItem, operation: FSLockOperation) -> Bool
    func unlock(item: FSItem) -> Bool
    
    // 符号链接和硬链接
    func symlink(path: String, target: String) -> FSItem?
    func link(item: FSItem, newPath: String) -> FSItem?
    func readlink(item: FSItem) -> String?
}
```

---

## 5. FSItem（文件/目录项）

**定义**：文件系统项（文件、目录、符号链接等）

**Swift API**：
```swift
class FSItem {
    // 项 ID
    var id: UUID
    
    // 项名称
    var name: String
    
    // 项类型
    var type: FSItemType
    
    // 所属卷
    var volume: FSVolume
    
    // 父目录
    var parent: FSItem?
    
    // 文件大小
    var size: Int
    
    // 属性
    var attributes: FSItemAttributes
}

enum FSItemType {
    case file          // 文件
    case directory     // 目录
    case symlink       // 符号链接
    case hardlink      // 硬链接
    case special       // 特殊文件
}
```

---

## 6. FSBlockDevice（块设备）

**定义**：块设备访问接口，对 ZFS 极重要

**Swift API**：
```swift
class FSBlockDevice {
    // 设备路径
    var path: String
    
    // 设备大小
    var size: Int
    
    // 设备 ID
    var id: UUID
    
    // 块大小
    var blockSize: Int
    
    // 读取块
    func readBlock(offset: Int, size: Int) -> Data?
    
    // 写入块
    func writeBlock(offset: Int, data: Data) -> Bool
    
    // 刷新缓存
    func flush()
    
    // 设备信息
    func getInfo() -> FSBlockDeviceInfo
}
```

**关键特性**：
- ✅ **直接块设备访问**（pread/pwrite）
- ✅ **设备路径**: /dev/disk18, /dev/disk19, etc
- ✅ **支持多个设备**（RAID-Z, mirror）
- ✅ **异步 I/O**（可选）
- ✅ **Direct I/O**（可选）

---

## 7. FSItemAttributes（属性）

**定义**：文件/目录属性

**Swift API**：
```swift
struct FSItemAttributes {
    // 标准 POSIX 属性
    var mode: Int          // 权限模式
    var uid: Int           // 用户 ID
    var gid: Int           // 组 ID
    var size: Int          // 文件大小
    var nlink: Int         // 链接数
    var atime: Date        // 访问时间
    var mtime: Date        // 修改时间
    var ctime: Date        // 创建时间
    var flags: Int         // 标志位
    
    // macOS 特定属性
    var finderInfo: Data   // Finder 信息
    var extendedFlags: Int // 扩展标志
}
```

---

## 8. FSMountRequest（挂载请求）

**定义**：用户挂载请求处理

**Swift API**：
```swift
class FSMountRequest {
    // 挂载路径
    var mountPath: String
    
    // 设备路径
    var devicePath: String?
    
    // 挂载选项
    var options: FSMountOptions
    
    // 用户 ID
    var uid: Int
    
    // 进程 ID
    var pid: Int
}

struct FSMountOptions {
    var readOnly: Bool
    var noExec: Bool
    var noSuid: Bool
    var noDev: Bool
    var synchronous: Bool
    var noBrowse: Bool
}
```

---

## 9. FSKit 挂载流程

**完整流程**：
```
1. 用户挂载命令:
   mount -F -t MyFS disk18 /mnt/test

2. macOS 处理:
   - 解析挂载参数
   - 创建 FSMountRequest
   - 调用 FSUnaryFileSystemOperations.handleMountRequest()
   
3. 文件系统处理:
   - 解析 FSMountRequest
   - 访问块设备（disk18）
   - 创建 FSVolume 实例
   - 返回 FSVolume
   
4. macOS 完成:
   - 注册 FSVolume
   - 创建挂载点
   - 激活卷操作
   
5. 用户操作:
   - read/write/readdir 等操作
   - macOS → FSVolume.Operations
   
6. 卸载:
   umount /mnt/test
   - macOS → FSUnaryFileSystemOperations.handleUnmountRequest()
```

---

## 10. FSKit Extension 激活

**用户激活流程**：
```
1. System Settings → General → Login Items & Extensions
2. 找到文件系统扩展（MyFS Extension）
3. 启用扩展
4. macOS 加载 Extension
5. 调用 UnaryFilesystemExtension.start()
6. Extension 返回 FSUnaryFileSystem
7. 文件系统可用
```

**权限要求**：
- 需要 root 或管理员权限激活
- Apple Developer 证书签名（生产）
- 沙箱化运行（安全）

---

## 11. FSKit vs Kernel VFS 对比

| FSKit API | Kernel VFS | 功能 |
|-----------|-----------|------|
| UnaryFilesystemExtension | kernel module init | 入口点 |
| FSUnaryFileSystem | filesystem type | 文件系统类型 |
| FSVolume | superblock | 卷管理 |
| FSVolume.Operations | file_operations | 文件操作 |
| FSItem | dentry/inode | 文件项 |
| FSBlockDevice | block_device | 块设备 |
| FSItemAttributes | inode attributes | 属性 |

---

## 12. FSKit 限制和特性

**支持**：
- ✅ 文件/目录操作
- ✅ 扩展属性（xattr）
- ✅ 符号链接/硬链接
- ✅ 文件锁定
- ✅ 块设备访问
- ✅ 异步 I/O
- ✅ Direct I/O
- ✅ Unicode 文件名
- ✅ 大文件支持

**不支持**：
- ❌ IOCTL（不通过 FSKit）
- ❌ BMAP（不通过 FSKit）
- ❌ 设备文件（字符/块设备）
- ❌ 网络文件系统特性（某些）

---

## 13. FSKit 最佳实践

**1. 用户态设计**：
- 所有代码运行在用户态
- 无 kernel code
- 使用 Swift/C 用户态库

**2. 块设备访问**：
- FSBlockDevice API
- pread/pwrite 用户态 I/O
- Direct I/O 优化性能

**3. 性能优化**：
- 用户态缓存（类似 ARC）
- 批量操作
- Async I/O

**4. 安全考虑**：
- Apple sandbox 模型
- 权限检查
- 用户态崩溃隔离

---