orion-accessor 0.6.0

Unified accessor layer for HTTP, Git, and local resources with redirect rules, proxy control, and env-aware templating.
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
use anyhow::{Context, Result};
use indicatif::{ProgressBar, ProgressStyle};
use std::collections::HashMap;
use std::fs::File;

use std::path::{Path, PathBuf};
use walkdir::WalkDir;

/// 基于 tar -xzf 算法实现的解压函数
///
/// 该函数会显示一个进度条,展示解压进度,包括:
/// - 已处理的字节数
/// - 总字节数
/// - 处理速度 (字节/秒)
/// - 预估剩余时间
/// - 当前正在处理的文件路径和大小
///
/// # 参数
/// * `archive_path` - 压缩文件路径 (.tar.gz 文件)
/// * `output_dir` - 解压目标目录
///
/// # 示例
/// ```
/// use orion_accessor::archive::decompress;
///
/// // 解压文件并显示进度条
/// // decompress("archive.tar.gz", "/tmp/extract").unwrap();
/// ```
///
/// # 注意事项
/// - 进度条会在控制台实时更新
/// - 解压完成后会显示完成消息
/// - 进度基于压缩文件大小,反映实际解压工作量
pub fn decompress(archive_path: impl AsRef<Path>, output_dir: impl AsRef<Path>) -> Result<()> {
    let archive_path = archive_path.as_ref();
    let output_dir = output_dir.as_ref();

    // 确保输出目录存在
    std::fs::create_dir_all(output_dir)
        .with_context(|| format!("创建输出目录失败: {}", output_dir.display()))?;

    // 获取压缩文件的总大小用于进度显示
    let archive_size = std::fs::metadata(archive_path)
        .with_context(|| format!("获取压缩文件元数据失败: {}", archive_path.display()))?
        .len();

    // 创建进度条
    let pb = ProgressBar::new(archive_size);
    pb.set_style(
        ProgressStyle::default_bar()
            .template(
                "{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {bytes}/{total_bytes} ({bytes_per_sec}) {eta} {msg}",
            )
            .unwrap()
            .progress_chars("#>-"),
    );
    pb.set_message("准备解压...");

    // 打开 tar.gz 文件
    let file = File::open(archive_path)
        .with_context(|| format!("无法打开压缩文件: {}", archive_path.display()))?;

    // 创建 Gzip 解码器
    let decoder = flate2::read::GzDecoder::new(file);

    // 创建 tar 归档读取器
    let mut archive = tar::Archive::new(decoder);

    // 手动处理每个条目以显示进度
    decompress_with_progress(&mut archive, output_dir, &pb)
        .with_context(|| format!("解压文件失败: {}", archive_path.display()))?;

    // 完成进度条
    pb.finish_with_message("解压完成");

    Ok(())
}

/// 压缩目录为 tar.gz 文件
///
/// 该函数会显示一个进度条,展示压缩进度,包括:
/// - 已处理的字节数
/// - 总字节数
/// - 处理速度 (字节/秒)
/// - 预估剩余时间
/// - 当前正在处理的文件路径和大小
///
/// # 参数
/// * `source_dir` - 要压缩的目录
/// * `output_path` - 输出的 .tar.gz 文件路径
///
/// # 示例
/// ```
/// use orion_accessor::archive::compress;
///
/// // 压缩目录并显示进度条
/// // compress("/path/to/source", "/path/to/archive.tar.gz").unwrap();
/// ```
///
/// # 注意事项
/// - 会自动跳过隐藏文件和目录(以 . 开头的文件)
/// - 进度条会在控制台实时更新
/// - 压缩完成后会显示完成消息
/// - 进度基于数据量(字节)而非文件数量,更准确地反映实际工作量
pub fn compress(source_dir: impl AsRef<Path>, output_path: impl AsRef<Path>) -> Result<()> {
    let source_dir = source_dir.as_ref();
    let output_path = output_path.as_ref();

    // 确保源目录存在
    if !source_dir.exists() || !source_dir.is_dir() {
        anyhow::bail!("源目录不存在: {}", source_dir.display());
    }

    // 统计要压缩的总数据量(字节)
    let total_bytes = count_total_bytes_in_directory(source_dir)?;

    // 创建进度条
    let pb = ProgressBar::new(total_bytes);
    pb.set_style(
        ProgressStyle::default_bar()
            .template(
                "{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {bytes}/{total_bytes} ({bytes_per_sec}) {eta} {msg}",
            )
            .unwrap()
            .progress_chars("#>-"),
    );
    pb.set_message("准备压缩...");

    // 创建输出文件
    let file = File::create(output_path)
        .with_context(|| format!("创建输出文件失败: {}", output_path.display()))?;

    // 创建 Gzip 编码器
    let encoder = flate2::write::GzEncoder::new(file, flate2::Compression::default());

    // 创建 tar 归档写入器
    let mut tar = tar::Builder::new(encoder);

    // 手动递归添加目录内容以显示进度
    compress_with_progress(&mut tar, source_dir, &pb, &mut HashMap::new())
        .with_context(|| format!("添加目录到压缩文件失败: {}", source_dir.display()))?;

    // 完成进度条
    pb.finish_with_message("压缩完成");

    // 确保所有数据都写入完成
    tar.finish().with_context(|| "完成压缩文件写入失败")?;

    Ok(())
}

/// 统计目录中的总字节数
fn count_total_bytes_in_directory(dir: &Path) -> Result<u64> {
    let mut total_bytes = 0;
    for entry in WalkDir::new(dir)
        .into_iter()
        .filter_entry(|e| !is_hidden(e))
    {
        let entry = entry.with_context(|| "遍历目录失败")?;
        let path = entry.path();

        // 跳过根目录本身
        if path == dir {
            continue;
        }

        if entry.file_type().is_file() {
            // 统计文件大小
            let metadata = entry
                .metadata()
                .with_context(|| format!("获取文件元数据失败: {}", path.display()))?;
            total_bytes += metadata.len();
        } else if entry.file_type().is_dir() {
            // 每个目录额外增加 1024 字节的权重
            total_bytes += 1024;
        }
    }
    Ok(total_bytes)
}

/// 检查文件或目录是否是隐藏的
fn is_hidden(entry: &walkdir::DirEntry) -> bool {
    entry
        .file_name()
        .to_str()
        .map(|s| s.starts_with('.'))
        .unwrap_or(false)
}

/// 带进度指示的压缩函数
fn compress_with_progress(
    tar: &mut tar::Builder<flate2::write::GzEncoder<File>>,
    source_dir: &Path,
    pb: &ProgressBar,
    visited: &mut HashMap<PathBuf, bool>,
) -> Result<()> {
    for entry in WalkDir::new(source_dir)
        .into_iter()
        .filter_entry(|e| !is_hidden(e))
    {
        let entry = entry.with_context(|| "遍历目录失败")?;
        let path = entry.path();

        // 跳过根目录本身
        if path == source_dir {
            continue;
        }

        // 避免重复处理
        if visited.contains_key(path) {
            continue;
        }
        visited.insert(path.to_path_buf(), true);

        let relative_path = path
            .strip_prefix(source_dir)
            .with_context(|| format!("计算相对路径失败: {}", path.display()))?;

        if entry.file_type().is_file() {
            // 添加文件并更新进度
            let mut file =
                File::open(path).with_context(|| format!("无法打开文件: {}", path.display()))?;
            let metadata = file
                .metadata()
                .with_context(|| format!("获取文件元数据失败: {}", path.display()))?;
            let file_size = metadata.len();

            pb.set_message(format!(
                "正在压缩: {} ({})",
                relative_path.display(),
                format_bytes(file_size)
            ));
            tar.append_file(relative_path, &mut file)
                .with_context(|| format!("添加文件失败: {}", path.display()))?;

            // 更新进度 - 文件的实际字节数
            pb.inc(file_size);
        } else if entry.file_type().is_dir() {
            // 添加目录
            tar.append_dir(relative_path, path)
                .with_context(|| format!("添加目录失败: {}", path.display()))?;

            // 更新进度 - 目录的权重 (1024 字节)
            pb.inc(1024);
        }
    }
    Ok(())
}

/// 格式化字节大小为人类可读格式
fn format_bytes(bytes: u64) -> String {
    const UNITS: &[&str] = &["B", "KB", "MB", "GB", "TB"];
    let mut bytes = bytes as f64;
    let mut unit_index = 0;

    while bytes >= 1024.0 && unit_index < UNITS.len() - 1 {
        bytes /= 1024.0;
        unit_index += 1;
    }

    if unit_index == 0 {
        format!("{} {}", bytes as u64, UNITS[unit_index])
    } else {
        format!("{:.1} {}", bytes, UNITS[unit_index])
    }
}

/// 使用进度条进行解压的辅助函数
///
/// 该函数会手动处理tar归档中的每个条目,并实时更新进度条,显示:
/// - 当前正在处理的文件路径和大小
/// - 已处理的字节数
/// - 处理速度
/// - 预估剩余时间
///
/// # 参数
/// * `archive` - tar归档读取器
/// * `output_dir` - 解压目标目录
/// * `pb` - 进度条
fn decompress_with_progress<R: std::io::Read>(
    archive: &mut tar::Archive<R>,
    output_dir: &Path,
    pb: &ProgressBar,
) -> Result<()> {
    let entries = archive.entries().with_context(|| "无法读取归档条目")?;

    // 遍历每个归档条目
    for entry in entries {
        let mut entry = entry.with_context(|| "无法读取归档条目")?;

        // 获取文件路径和大小,避免借用冲突
        let path_display = {
            let path = entry.path().with_context(|| "无法获取条目路径")?;
            path.display().to_string()
        };
        let file_size = entry.size();

        // 更新进度条消息,显示当前处理的文件
        pb.set_message(format!(
            "解压: {} ({})",
            path_display,
            format_bytes(file_size)
        ));

        // 解压当前条目
        entry
            .unpack_in(output_dir)
            .with_context(|| format!("解压条目失败: {path_display}"))?;

        // 更新进度条(基于压缩文件大小)
        // 由于我们无法精确知道已解压的字节数,我们使用压缩文件的大小作为进度基准
        // 这里我们假设每个条目处理完成后,进度条会相应更新
        // 实际上,进度条会根据读取的字节数自动更新
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;
    use tempfile::tempdir;

    #[test]
    fn test_compress_decompress_roundtrip() {
        let temp_dir = tempdir().unwrap();
        let source_dir = temp_dir.path().join("source");
        let archive_path = temp_dir.path().join("test.tar.gz");
        let extract_dir = temp_dir.path().join("extract");

        // 创建测试文件
        fs::create_dir_all(&source_dir).unwrap();
        fs::write(source_dir.join("test.txt"), "Hello, World!").unwrap();
        fs::create_dir_all(source_dir.join("subdir")).unwrap();
        fs::write(source_dir.join("subdir").join("nested.txt"), "Nested file").unwrap();

        // 测试压缩
        compress(&source_dir, &archive_path).unwrap();
        assert!(archive_path.exists());

        // 测试解压
        decompress(&archive_path, &extract_dir).unwrap();

        // 验证解压结果
        assert!(extract_dir.join("test.txt").exists());
        assert!(extract_dir.join("subdir").join("nested.txt").exists());

        assert_eq!(
            fs::read_to_string(extract_dir.join("test.txt")).unwrap(),
            "Hello, World!"
        );
        assert_eq!(
            fs::read_to_string(extract_dir.join("subdir").join("nested.txt")).unwrap(),
            "Nested file"
        );
    }

    #[test]
    fn test_decompress_nonexistent_file() {
        let temp_dir = tempdir().unwrap();
        let result = decompress("nonexistent.tar.gz", temp_dir.path());
        assert!(result.is_err());
    }

    #[test]
    fn test_compress_nonexistent_directory() {
        let temp_dir = tempdir().unwrap();
        let archive_path = temp_dir.path().join("test.tar.gz");
        let result = compress("nonexistent_directory", &archive_path);
        assert!(result.is_err());
    }

    #[test]
    fn test_compress_empty_directory() {
        let temp_dir = tempdir().unwrap();
        let source_dir = temp_dir.path().join("empty");
        let archive_path = temp_dir.path().join("empty.tar.gz");
        let extract_dir = temp_dir.path().join("extract_empty");

        // 创建空目录
        fs::create_dir_all(&source_dir).unwrap();

        // 测试压缩空目录
        compress(&source_dir, &archive_path).unwrap();
        assert!(archive_path.exists());

        // 测试解压
        decompress(&archive_path, &extract_dir).unwrap();

        // 验证解压结果
        assert!(extract_dir.exists());
    }

    #[test]
    fn test_compress_with_special_files() {
        let temp_dir = tempdir().unwrap();
        let source_dir = temp_dir.path().join("special");
        let archive_path = temp_dir.path().join("special.tar.gz");
        let extract_dir = temp_dir.path().join("extract_special");

        // 创建测试文件和特殊文件
        fs::create_dir_all(&source_dir).unwrap();
        fs::write(source_dir.join("normal.txt"), "Normal file").unwrap();

        // 创建子目录
        fs::create_dir_all(source_dir.join("subdir")).unwrap();
        fs::write(source_dir.join("subdir").join("file.txt"), "Subdir file").unwrap();

        // 测试压缩
        compress(&source_dir, &archive_path).unwrap();
        assert!(archive_path.exists());

        // 测试解压
        decompress(&archive_path, &extract_dir).unwrap();

        // 验证解压结果
        assert!(extract_dir.join("normal.txt").exists());
        assert!(extract_dir.join("subdir").exists());
        assert!(extract_dir.join("subdir").join("file.txt").exists());

        assert_eq!(
            fs::read_to_string(extract_dir.join("normal.txt")).unwrap(),
            "Normal file"
        );
        assert_eq!(
            fs::read_to_string(extract_dir.join("subdir").join("file.txt")).unwrap(),
            "Subdir file"
        );
    }

    #[test]
    fn test_decompress_to_existing_directory() {
        let temp_dir = tempdir().unwrap();
        let source_dir = temp_dir.path().join("source");
        let archive_path = temp_dir.path().join("test.tar.gz");
        let extract_dir = temp_dir.path().join("existing");

        // 创建源文件
        fs::create_dir_all(&source_dir).unwrap();
        fs::write(source_dir.join("test.txt"), "Test content").unwrap();

        // 创建已存在的目标目录
        fs::create_dir_all(&extract_dir).unwrap();
        fs::write(extract_dir.join("existing.txt"), "Existing content").unwrap();

        // 压缩
        compress(&source_dir, &archive_path).unwrap();

        // 解压到已存在的目录
        decompress(&archive_path, &extract_dir).unwrap();

        // 验证解压结果
        assert!(extract_dir.join("test.txt").exists());
        assert!(extract_dir.join("existing.txt").exists());

        assert_eq!(
            fs::read_to_string(extract_dir.join("test.txt")).unwrap(),
            "Test content"
        );
        assert_eq!(
            fs::read_to_string(extract_dir.join("existing.txt")).unwrap(),
            "Existing content"
        );
    }
}