# ManagedLibDeflate

**Repository Path**: netcasewqs/managed-lib-deflate

## Basic Information

- **Project Name**: ManagedLibDeflate
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ManagedLibDeflate

> ⚠️ **0.x 阶段公共 API 不承诺稳定。** `0.2.0-beta` 将引入大量破坏性变更（详见 发布计划 §2.2）。生产环境请等待 `1.0.0`。

libdeflate 的**纯托管 C#** 移植——DEFLATE / zlib 压缩与解压，**零原生依赖**，SIMD 加速。

## 这是什么

`ManagedLibDeflate` 是 [libdeflate](https://github.com/ebiggers/libdeflate)（C 语言高性能 DEFLATE 库）的纯 C# 移植版。与 `LibDeflate.Native` 等原生绑定包不同，它：

- ✅ **零原生依赖**：不 P/Invoke 任何 native DLL，纯 IL，开箱即用，AOT 友好
- ✅ **SIMD 加速**：使用 `System.Runtime.Intrinsics`（Vector256 / Vector512）加速匹配与拷贝
- ✅ **多目标框架**：`net8.0` 与 `net10.0`
- ✅ **API 简洁**：`Compress` / `Decompress` 核心方法，语义与 libdeflate 原版一致

## 支持矩阵

| 维度 | 支持 |
|------|------|
| 目标框架 | `net8.0`、`net10.0` |
| 操作系统 | Windows / Linux / macOS（随 .NET 运行时） |
| 压缩格式 | DEFLATE（raw）、zlib（Gzip 已纳入路线图，0.1 未实现） |
| API 稳定性 | ⚠️ 0.x 不承诺稳定；`1.0.0` 起冻结并遵循 SemVer |

## 安装

```bash
dotnet add package ManagedLibDeflate
```

## 快速上手

> 以下示例变量均显式标注类型，便于一眼看清调用约定。所有 `Compress` / `Decompress` 方法接收 `ReadOnlySpan<byte>` 输入与 `Span<byte>` 输出，由调用方预分配输出缓冲区（与 libdeflate 原版语义一致）。

### 解压 raw DEFLATE

```csharp
using System.IO;
using ManagedLibDeflate;

// 1) 输入：raw DEFLATE 字节（无 zlib 头）。byte[] → ReadOnlySpan<byte>
byte[] compressedBytes = File.ReadAllBytes("data.deflate");
ReadOnlySpan<byte> compressed = compressedBytes.AsSpan();

// 2) 输出：预分配缓冲区 Span<byte>，容量须 ≥ 解压后长度（此处示例 1 MiB）
Span<byte> output = new byte[1024 * 1024];

// 3) 解压：返回实际写入 output 的字节数
LibDeflateDecompressor decompressor = new();
int actualBytes = decompressor.Decompress(compressed, output);
```

### 解压（用静态实例，免构造）

```csharp
// 参数类型与实例方法完全一致：compressed: ReadOnlySpan<byte>，output: Span<byte>
byte[] compressedBytes = File.ReadAllBytes("data.deflate");
ReadOnlySpan<byte> compressed = compressedBytes.AsSpan();
Span<byte> output = new byte[1024 * 1024];

int actualBytes = LibDeflateDecompressor.DecompressStatic(compressed, output);
```

### 压缩为 raw DEFLATE

```csharp
using System.IO;
using ManagedLibDeflate;

// 源数据：ReadOnlySpan<byte>
byte[] srcBytes = File.ReadAllBytes("data.bin");
ReadOnlySpan<byte> src = srcBytes.AsSpan();

// 压缩级别 6（1=最快 … 12=最强）；构造器返回 LibDeflateCompressor
LibDeflateCompressor compressor = new(level: 6);

// 预分配输出缓冲区：容量 = 压缩上界（务必用 CompressBound 计算，避免溢出）
int bound = LibDeflateCompressor.CompressBound(src.Length);
byte[] dst = new byte[bound];

// 压缩：返回写入 dst 的字节数
int compressedLen = compressor.Compress(src, dst);

// 截取有效部分（dst 容量为上界，有效数据仅前 compressedLen 字节）
byte[] result = dst.AsSpan(0, compressedLen).ToArray();
```

### 压缩为 zlib 格式（2 字节头 + Adler-32 校验）

```csharp
// 参数类型与 Compress 一致：src: ReadOnlySpan<byte>，dst: Span<byte>
int compressedLen = compressor.CompressZlib(src, dst);
```

### 流式压缩 / 解压（同步）

```csharp
using System.IO;
using ManagedLibDeflate;

// —— 压缩 ——
byte[] src = File.ReadAllBytes("data.bin");
MemoryStream outStream = new();
using (LibDeflateStream zs = new(outStream, CompressionLevel.Optimal))
{
    zs.Write(src, 0, src.Length);
}
byte[] compressed = outStream.ToArray();

// —— 解压 ——
byte[] output = new byte[1024 * 1024];   // Span<byte> 或 byte[] 均可
MemoryStream inStream = new(compressed);
using LibDeflateStream zs = new(inStream, CompressionMode.Decompress);
zs.Read(output, 0, output.Length);
```

### 流式压缩 / 解压（异步 + Pipelines）

`LibDeflateStream` 同时提供 `WriteAsync` / `ReadAsync` / `FlushAsync` / `DisposeAsync` 重写（底层 I/O 真正异步；压缩/解压为 CPU 密集的同步计算，不靠 `Task.Run` 伪装），以及两条 `System.IO.Pipelines` 助手，让"生产者读源 I/O"与"消费者压缩/写目标 I/O"在不同 Task 上重叠执行：

```csharp
using System.IO;
using System.Threading;
using ManagedLibDeflate;

// —— 异步压缩（WriteAsync / DisposeAsync 真正让出线程等待 I/O）——
byte[] src = File.ReadAllBytes("data.bin");
MemoryStream outStream = new();
await using (LibDeflateStream zs = new(outStream, CompressionLevel.Optimal))
{
    await zs.WriteAsync(src, CancellationToken.None);
}
byte[] compressed = outStream.ToArray();

// —— Pipelines 重叠助手（读源 I/O 与压缩/写目标 I/O 并行）——
await LibDeflateStream.CompressViaPipeAsync(
    source: File.OpenRead("data.bin"),
    destination: File.Create("data.deflate"),
    level: CompressionLevel.Optimal);
```

> 0.1 已包含 `LibDeflateStream` 的**同步**与**异步**两套 API，以及 `CompressViaPipeAsync` / `DecompressViaPipeAsync` Pipelines 助手。后续 `0.2.0-beta`（A10）计划将其重构为独立的 `LibDeflatePipeline` 类型，公开 API 面可能调整（0.x 不承诺稳定）。

## API 速览

### `LibDeflateDecompressor`

| 成员 | 说明 |
|------|------|
| `Decompress(ReadOnlySpan<byte> input, Span<byte> output)` | 解压 raw DEFLATE，返回写入字节数 |
| `static DecompressStatic(ReadOnlySpan<byte> input, Span<byte> output)` | 用线程静态实例解压（免构造） |

### `LibDeflateCompressor : IDisposable`

| 成员 | 说明 |
|------|------|
| `LibDeflateCompressor(int level = 1, CompressionLevel strategy = CompressionLevel.Optimal)` | 构造压缩器 |
| `Compress(ReadOnlySpan<byte> src, Span<byte> dst)` | 压缩为 raw DEFLATE，返回压缩字节数 |
| `CompressZlib(ReadOnlySpan<byte> src, Span<byte> dst)` | 压缩为 zlib 格式（含头与校验） |
| `static CompressBound(int srcLen)` | 计算压缩输出上限，用于预分配缓冲区 |
| `Dispose()` | 释放资源 |

### 压缩级别

| level | 说明 |
|-------|------|
| 0 | 仅存储（不压缩） |
| 1 | 最快（ht matchfinder） |
| 2-4 | 贪心（greedy） |
| 5-7 | 惰性（lazy） |
| 8-12 | 惰性2（lazy2） |

### `LibDeflateStream : Stream`（同步 + 异步，0.1）

| 成员 | 说明 |
|------|------|
| `LibDeflateStream(Stream, CompressionLevel, bool leaveOpen = false)` | 构造压缩流 |
| `LibDeflateStream(Stream, CompressionMode, bool leaveOpen = false)` | 构造压缩 / 解压流 |
| `Write` / `Read` / `Flush` + 标准 `Stream` 重写 | 同步流式读写 |
| `WriteAsync` / `ReadAsync` / `FlushAsync` / `DisposeAsync` 重写 | 异步流式读写（底层 I/O 真正异步） |
| `static CompressViaPipeAsync(Stream source, Stream destination, CompressionLevel level, ...)` | Pipelines 重叠压缩助手 |
| `static DecompressViaPipeAsync(Stream source, Stream destination, ...)` | Pipelines 重叠解压助手 |

### `CompressionFormat` 枚举

`Deflate` / `Zlib`。0.1 仅暴露 `Deflate` 与 `Zlib` 两项；`Gzip` 计划在 `0.2.0-beta`（A6）随统一的 `Compress(src, dst, format)` 入口一并加入。

## 版本与路线图

| 版本 | 定位 |
|------|------|
| `0.1.0-alpha`（当前） | 发布链路验证，公共 API 最小面 |
| `0.2.0-beta` | 一次性 API 破坏性总成（A1–A6、A11） |
| `1.0.0` | API 冻结，SemVer 生效，稳定版 |

完整逐版本接口清单与时间线见发布计划（内部规划文档，随本地 `internal/` 仓库维护，不发布到 GitHub）。

## 许可

MIT