跳转到内容
标准库Zig 0.17.0官方原文
源码std/zip.zig

第 1 行

ZIP 文件格式规范位于: https://pkwaredownloads.blob.core.windows.net/pem/APPNOTE.txt

注意,此文件使用缩写“cd”表示“中央目录”。

std.zip.builtin

常量

第 6 行

std.zip.central_file_header_sig

常量

第 22 行

std.zip.CentralDirectoryFileHeader

容器

第 51 行

字段

signature: [4]u8 align(1)
version_made_by: u16 align(1)
version_needed_to_extract: u16 align(1)
flags: GeneralPurposeFlags align(1)
compression_method: CompressionMethod align(1)
last_modification_time: u16 align(1)
last_modification_date: u16 align(1)
crc32: u32 align(1)
compressed_size: u32 align(1)
uncompressed_size: u32 align(1)
filename_len: u16 align(1)
extra_len: u16 align(1)
comment_len: u16 align(1)
disk_number: u16 align(1)
internal_file_attributes: u16 align(1)
external_file_attributes: u32 align(1)
local_file_header_offset: u32 align(1)

std.zip.CompressionMethod

容器

第 16 行

字段

store = 0
deflate = 8
_

std.zip.Diagnostics

容器

第 587 行

字段

allocator: std.mem.Allocator
root_dir: []const u8 = ""

所有提取文件的公共根目录,如果存在。

saw_first_file: bool = false

std.zip.Diagnostics.deinit

函数

第 595 行

pub fn deinit(self: *Diagnostics) void

参数

self: *Diagnostics

std.zip.Diagnostics.nextFilename

函数

第 603 行

pub fn nextFilename(self: *Diagnostics, name: []const u8) error{OutOfMemory}!void

参数

self: *Diagnostics
name: []const u8

错误

OutOfMemory

std.zip.end_locator64_sig

常量

第 26 行

std.zip.end_record_sig

常量

第 24 行

std.zip.end_record64_sig

常量

第 25 行

std.zip.EndLocator64

容器

第 84 行

字段

signature: [4]u8 align(1)
zip64_disk_count: u32 align(1)
record_file_offset: u64 align(1)
total_disk_count: u32 align(1)

std.zip.EndRecord

容器

第 91 行

字段

signature: [4]u8 align(1)
disk_number: u16 align(1)
central_directory_disk_number: u16 align(1)
record_count_disk: u16 align(1)
record_count_total: u16 align(1)
central_directory_size: u32 align(1)
central_directory_offset: u32 align(1)
comment_len: u16 align(1)

std.zip.EndRecord.findBuffer

函数

第 111 行

TODO: 审查此逻辑

pub fn findBuffer(buffer: []const u8) FindBufferError!EndRecord

参数

buffer: []const u8

错误

ZipNoEndRecord
ZipTruncated

std.zip.EndRecord.FindBufferError

错误集合

第 108 行

错误

ZipNoEndRecord
ZipTruncated

std.zip.EndRecord.findFile

函数

第 126 行

pub fn findFile(fr: *File.Reader) FindFileError!EndRecord

参数

fr: *File.Reader

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

PermissionDenied StatError
ReadFailed
SocketUnconnected UnendingError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable SeekError
WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

ZipNoEndRecord

std.zip.EndRecord.FindFileError

错误集合

第 120 行

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

PermissionDenied StatError
ReadFailed
SocketUnconnected UnendingError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable SeekError
WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

ZipNoEndRecord

std.zip.EndRecord.need_zip64

函数

第 101 行

pub fn need_zip64(self: EndRecord) bool

参数

self: EndRecord

std.zip.EndRecord64

容器

第 71 行

字段

signature: [4]u8 align(1)
end_record_size: u64 align(1)
version_made_by: u16 align(1)
version_needed_to_extract: u16 align(1)
disk_number: u32 align(1)
central_directory_disk_number: u32 align(1)
record_count_disk: u64 align(1)
record_count_total: u64 align(1)
central_directory_size: u64 align(1)
central_directory_offset: u64 align(1)

std.zip.extract

函数

第 628 行

将压缩文件解压到给定 dest 目录。

pub fn extract(dest: Io.Dir, fr: *File.Reader, options: ExtractOptions) !void

参数

dest: Io.Dir
fr: *File.Reader
options: ExtractOptions

std.zip.ExtractOptions

容器

第 619 行

字段

allow_backslashes: bool = false

允许 zip 内文件名使用反斜杠。传给平台 API 前,会将反斜杠规范化为正斜杠。

diagnostics: ?*Diagnostics = null
verify_checksums: bool = false

std.zip.ExtraHeader

容器

第 27 行

字段

zip64_info = 0x1
_

std.zip.File

别名

第 11 行

别名目标 std.Io.File

std.zip.FileExtents

容器

第 184 行

字段

uncompressed_size: u64
compressed_size: u64
local_file_header_offset: u64

std.zip.filenameInRoot

函数

第 581 行

fn filenameInRoot(filename: []const u8, root: []const u8) bool

参数

filename: []const u8
root: []const u8

std.zip.flate

别名

第 14 行

别名目标 std.compress.flate

std.zip.GeneralPurposeFlags

容器

第 32 行

字段

encrypted: bool
_: u15

std.zip.Io

别名

第 10 行

别名目标 std.Io

std.zip.is_le

常量

第 7 行

std.zip.isBadFilename

函数

第 167 行

fn isBadFilename(filename: []const u8) bool

参数

filename: []const u8

std.zip.isMaxInt

函数

第 180 行

fn isMaxInt(uint: anytype) bool

std.zip.Iterator

容器

第 228 行

字段

input: *File.Reader
cd_record_count: u64
cd_zip_offset: u64
cd_size: u64
cd_record_index: u64 = 0
cd_record_offset: u64 = 0

std.zip.Iterator.Entry

容器

第 403 行

字段

version_needed_to_extract: u16
flags: GeneralPurposeFlags
compression_method: CompressionMethod
last_modification_time: u16
last_modification_date: u16
header_zip_offset: u64
crc32: u32
filename_len: u32
compressed_size: u64
uncompressed_size: u64
file_offset: u64

std.zip.Iterator.Entry.extract

函数

第 539 行

pub fn extract( self: Entry, stream: *File.Reader, options: ExtractOptions, filename_buf: []u8, dest: Io.Dir, ) !void

参数

self: Entry
stream: *File.Reader
options: ExtractOptions
filename_buf: []u8
dest: Io.Dir

std.zip.Iterator.Entry.extractTo

函数

第 442 行

pub fn extractTo(self: Entry, stream: *File.Reader, w: *Writer) !void

参数

self: Entry
stream: *File.Reader
w: *Writer

std.zip.Iterator.Entry.getFilename

函数

第 416 行

pub fn getFilename(self: Entry, stream: *File.Reader, filename_buf: []u8, options: ExtractOptions) ![]u8

参数

self: Entry
stream: *File.Reader
filename_buf: []u8
options: ExtractOptions

std.zip.Iterator.init

函数

第 238 行

pub fn init(input: *File.Reader) !Iterator

参数

input: *File.Reader

std.zip.Iterator.next

函数

第 322 行

pub fn next(self: *Iterator) !?Entry

参数

self: *Iterator

std.zip.local_file_header_sig

常量

第 23 行

std.zip.LocalFileHeader

容器

第 37 行

字段

signature: [4]u8 align(1)
version_needed_to_extract: u16 align(1)
flags: GeneralPurposeFlags align(1)
compression_method: CompressionMethod align(1)
last_modification_time: u16 align(1)
last_modification_date: u16 align(1)
crc32: u32 align(1)
compressed_size: u32 align(1)
uncompressed_size: u32 align(1)
filename_len: u16 align(1)
extra_len: u16 align(1)

std.zip.Reader

别名

第 13 行

别名目标 std.Io.Reader

std.zip.readZip64FileExtents

函数

第 190 行

fn readZip64FileExtents(comptime T: type, header: T, extents: *FileExtents, data: []u8) !void

参数

T: type
header: T
extents: *FileExtents
data: []u8

std.zip.std

别名

第 9 行

别名目标 std

std.zip.testing

别名

第 642 行

别名目标 std.testing

std.zip.Writer

别名

第 12 行

别名目标 std.Io.Writer

源码

std/zip.zig

//! ZIP 文件格式规范位于:
//!    https://pkwaredownloads.blob.core.windows.net/pem/APPNOTE.txt
//!
//! 注意,此文件使用缩写“cd”表示“中央目录”。

const builtin = @import("builtin");
const is_le = builtin.target.cpu.arch.endian() == .little;

const std = @import("std");
const Io = std.Io;
const File = std.Io.File;
const Writer = std.Io.Writer;
const Reader = std.Io.Reader;
const flate = std.compress.flate;

pub const CompressionMethod = enum(u16) {
    store = 0,
    deflate = 8,
    _,
};

pub const central_file_header_sig = [4]u8{ 'P', 'K', 1, 2 };
pub const local_file_header_sig = [4]u8{ 'P', 'K', 3, 4 };
pub const end_record_sig = [4]u8{ 'P', 'K', 5, 6 };
pub const end_record64_sig = [4]u8{ 'P', 'K', 6, 6 };
pub const end_locator64_sig = [4]u8{ 'P', 'K', 6, 7 };
pub const ExtraHeader = enum(u16) {
    zip64_info = 0x1,
    _,
};

const GeneralPurposeFlags = packed struct(u16) {
    encrypted: bool,
    _: u15,
};

pub const LocalFileHeader = extern struct {
    signature: [4]u8 align(1),
    version_needed_to_extract: u16 align(1),
    flags: GeneralPurposeFlags align(1),
    compression_method: CompressionMethod align(1),
    last_modification_time: u16 align(1),
    last_modification_date: u16 align(1),
    crc32: u32 align(1),
    compressed_size: u32 align(1),
    uncompressed_size: u32 align(1),
    filename_len: u16 align(1),
    extra_len: u16 align(1),
};

pub const CentralDirectoryFileHeader = extern struct {
    signature: [4]u8 align(1),
    version_made_by: u16 align(1),
    version_needed_to_extract: u16 align(1),
    flags: GeneralPurposeFlags align(1),
    compression_method: CompressionMethod align(1),
    last_modification_time: u16 align(1),
    last_modification_date: u16 align(1),
    crc32: u32 align(1),
    compressed_size: u32 align(1),
    uncompressed_size: u32 align(1),
    filename_len: u16 align(1),
    extra_len: u16 align(1),
    comment_len: u16 align(1),
    disk_number: u16 align(1),
    internal_file_attributes: u16 align(1),
    external_file_attributes: u32 align(1),
    local_file_header_offset: u32 align(1),
};

pub const EndRecord64 = extern struct {
    signature: [4]u8 align(1),
    end_record_size: u64 align(1),
    version_made_by: u16 align(1),
    version_needed_to_extract: u16 align(1),
    disk_number: u32 align(1),
    central_directory_disk_number: u32 align(1),
    record_count_disk: u64 align(1),
    record_count_total: u64 align(1),
    central_directory_size: u64 align(1),
    central_directory_offset: u64 align(1),
};

pub const EndLocator64 = extern struct {
    signature: [4]u8 align(1),
    zip64_disk_count: u32 align(1),
    record_file_offset: u64 align(1),
    total_disk_count: u32 align(1),
};

pub const EndRecord = extern struct {
    signature: [4]u8 align(1),
    disk_number: u16 align(1),
    central_directory_disk_number: u16 align(1),
    record_count_disk: u16 align(1),
    record_count_total: u16 align(1),
    central_directory_size: u32 align(1),
    central_directory_offset: u32 align(1),
    comment_len: u16 align(1),

    pub fn need_zip64(self: EndRecord) bool {
        return isMaxInt(self.record_count_disk) or
            isMaxInt(self.record_count_total) or
            isMaxInt(self.central_directory_size) or
            isMaxInt(self.central_directory_offset);
    }

    pub const FindBufferError = error{ ZipNoEndRecord, ZipTruncated };

    /// TODO: 审查此逻辑
    pub fn findBuffer(buffer: []const u8) FindBufferError!EndRecord {
        const pos = std.mem.findLast(u8, buffer, &end_record_sig) orelse return error.ZipNoEndRecord;
        if (pos + @sizeOf(EndRecord) > buffer.len) return error.EndOfStream;
        const record_ptr: *EndRecord = @ptrCast(buffer[pos..][0..@sizeOf(EndRecord)]);
        var record = record_ptr.*;
        if (!is_le) std.mem.byteSwapAllFields(EndRecord, &record);
        return record;
    }

    pub const FindFileError = File.Reader.SizeError || File.SeekError || File.Reader.Error || error{
        ZipNoEndRecord,
        EndOfStream,
        ReadFailed,
    };

    pub fn findFile(fr: *File.Reader) FindFileError!EndRecord {
        const end_pos = try fr.getSize();

        var buf: [@sizeOf(EndRecord) + std.math.maxInt(u16)]u8 = undefined;
        const record_len_max = @min(end_pos, buf.len);
        var loaded_len: u32 = 0;
        var comment_len: u16 = 0;
        while (true) {
            const record_len: u32 = @as(u32, comment_len) + @sizeOf(EndRecord);
            if (record_len > record_len_max)
                return error.ZipNoEndRecord;

            if (record_len > loaded_len) {
                const new_loaded_len = @min(loaded_len + 300, record_len_max);
                const read_len = new_loaded_len - loaded_len;

                try fr.seekTo(end_pos - @as(u64, new_loaded_len));
                const read_buf: []u8 = buf[buf.len - new_loaded_len ..][0..read_len];
                fr.interface.readSliceAll(read_buf) catch |err| switch (err) {
                    error.ReadFailed => return fr.err.?,
                    error.EndOfStream => |e| return e,
                };
                loaded_len = new_loaded_len;
            }

            const record_bytes = buf[buf.len - record_len ..][0..@sizeOf(EndRecord)];
            if (std.mem.eql(u8, record_bytes[0..4], &end_record_sig) and
                std.mem.readInt(u16, record_bytes[20..22], .little) == comment_len)
            {
                const record: *align(1) EndRecord = @ptrCast(record_bytes.ptr);
                if (!is_le) std.mem.byteSwapAllFields(EndRecord, record);
                return record.*;
            }

            if (comment_len == std.math.maxInt(u16))
                return error.ZipNoEndRecord;
            comment_len += 1;
        }
    }
};

fn isBadFilename(filename: []const u8) bool {
    if (filename.len == 0 or filename[0] == '/')
        return true;

    var it = std.mem.splitScalar(u8, filename, '/');
    while (it.next()) |part| {
        if (std.mem.eql(u8, part, ".."))
            return true;
    }

    return false;
}

fn isMaxInt(uint: anytype) bool {
    return uint == std.math.maxInt(@TypeOf(uint));
}

const FileExtents = struct {
    uncompressed_size: u64,
    compressed_size: u64,
    local_file_header_offset: u64,
};

fn readZip64FileExtents(comptime T: type, header: T, extents: *FileExtents, data: []u8) !void {
    var data_offset: usize = 0;
    if (isMaxInt(header.uncompressed_size)) {
        if (data_offset + 8 > data.len)
            return error.ZipBadCd64Size;
        extents.uncompressed_size = std.mem.readInt(u64, data[data_offset..][0..8], .little);
        data_offset += 8;
    }
    if (isMaxInt(header.compressed_size)) {
        if (data_offset + 8 > data.len)
            return error.ZipBadCd64Size;
        extents.compressed_size = std.mem.readInt(u64, data[data_offset..][0..8], .little);
        data_offset += 8;
    }

    switch (T) {
        CentralDirectoryFileHeader => {
            if (isMaxInt(header.local_file_header_offset)) {
                if (data_offset + 8 > data.len)
                    return error.ZipBadCd64Size;
                extents.local_file_header_offset = std.mem.readInt(u64, data[data_offset..][0..8], .little);
                data_offset += 8;
            }
            if (isMaxInt(header.disk_number)) {
                if (data_offset + 4 > data.len)
                    return error.ZipInvalid;
                const disk_number = std.mem.readInt(u32, data[data_offset..][0..4], .little);
                if (disk_number != 0)
                    return error.ZipMultiDiskUnsupported;
                data_offset += 4;
            }
            if (data_offset > data.len)
                return error.ZipBadCd64Size;
        },
        else => {},
    }
}

pub const Iterator = struct {
    input: *File.Reader,

    cd_record_count: u64,
    cd_zip_offset: u64,
    cd_size: u64,

    cd_record_index: u64 = 0,
    cd_record_offset: u64 = 0,

    pub fn init(input: *File.Reader) !Iterator {
        const end_record = try EndRecord.findFile(input);

        if (!isMaxInt(end_record.record_count_disk) and end_record.record_count_disk > end_record.record_count_total)
            return error.ZipDiskRecordCountTooLarge;

        if (end_record.disk_number != 0 or end_record.central_directory_disk_number != 0)
            return error.ZipMultiDiskUnsupported;

        {
            const counts_valid = !isMaxInt(end_record.record_count_disk) and !isMaxInt(end_record.record_count_total);
            if (counts_valid and end_record.record_count_disk != end_record.record_count_total)
                return error.ZipMultiDiskUnsupported;
        }

        var result: Iterator = .{
            .input = input,
            .cd_record_count = end_record.record_count_total,
            .cd_zip_offset = end_record.central_directory_offset,
            .cd_size = end_record.central_directory_size,
        };
        if (!end_record.need_zip64()) return result;

        const locator_end_offset: u64 = @as(u64, end_record.comment_len) + @sizeOf(EndRecord) + @sizeOf(EndLocator64);
        const stream_len = try input.getSize();

        if (locator_end_offset > stream_len)
            return error.ZipTruncated;
        try input.seekTo(stream_len - locator_end_offset);
        const locator = input.interface.takeStruct(EndLocator64, .little) catch |err| switch (err) {
            error.ReadFailed => return input.err.?,
            error.EndOfStream => |e| return e,
        };
        if (!std.mem.eql(u8, &locator.signature, &end_locator64_sig))
            return error.ZipBadLocatorSig;
        if (locator.zip64_disk_count != 0)
            return error.ZipUnsupportedZip64DiskCount;
        if (locator.total_disk_count != 1)
            return error.ZipMultiDiskUnsupported;

        try input.seekTo(locator.record_file_offset);

        const record64 = input.interface.takeStruct(EndRecord64, .little) catch |err| switch (err) {
            error.ReadFailed => return input.err.?,
            error.EndOfStream => |e| return e,
        };

        if (!std.mem.eql(u8, &record64.signature, &end_record64_sig))
            return error.ZipBadEndRecord64Sig;

        if (record64.end_record_size < @sizeOf(EndRecord64) - 12)
            return error.ZipEndRecord64SizeTooSmall;
        if (record64.end_record_size > @sizeOf(EndRecord64) - 12)
            return error.ZipEndRecord64UnhandledExtraData;

        if (record64.version_needed_to_extract > 45)
            return error.ZipUnsupportedVersion;

        {
            const is_multidisk = record64.disk_number != 0 or
                record64.central_directory_disk_number != 0 or
                record64.record_count_disk != record64.record_count_total;
            if (is_multidisk)
                return error.ZipMultiDiskUnsupported;
        }

        if (isMaxInt(end_record.record_count_total)) {
            result.cd_record_count = record64.record_count_total;
        } else if (end_record.record_count_total != record64.record_count_total)
            return error.Zip64RecordCountTotalMismatch;

        if (isMaxInt(end_record.central_directory_offset)) {
            result.cd_zip_offset = record64.central_directory_offset;
        } else if (end_record.central_directory_offset != record64.central_directory_offset)
            return error.Zip64CentralDirectoryOffsetMismatch;

        if (isMaxInt(end_record.central_directory_size)) {
            result.cd_size = record64.central_directory_size;
        } else if (end_record.central_directory_size != record64.central_directory_size)
            return error.Zip64CentralDirectorySizeMismatch;

        return result;
    }

    pub fn next(self: *Iterator) !?Entry {
        if (self.cd_record_index == self.cd_record_count) {
            if (self.cd_record_offset != self.cd_size)
                return if (self.cd_size > self.cd_record_offset)
                    error.ZipCdOversized
                else
                    error.ZipCdUndersized;

            return null;
        }

        const header_zip_offset = self.cd_zip_offset + self.cd_record_offset;
        const input = self.input;
        try input.seekTo(header_zip_offset);
        const header = input.interface.takeStruct(CentralDirectoryFileHeader, .little) catch |err| switch (err) {
            error.ReadFailed => return input.err.?,
            error.EndOfStream => |e| return e,
        };
        if (!std.mem.eql(u8, &header.signature, &central_file_header_sig))
            return error.ZipBadCdOffset;

        self.cd_record_index += 1;
        self.cd_record_offset += @sizeOf(CentralDirectoryFileHeader) + header.filename_len + header.extra_len + header.comment_len;

        // 注意:检查 version_needed_to_extract 似乎没有帮助;例如
        // https://github.com/ninja-build/ninja/releases/download/v1.12.0/ninja-linux.zip
        // 中的 zip 文件使用未记载的版本 788,但仍可正常解压。

        if (header.flags.encrypted)
            return error.ZipEncryptionUnsupported;
        // TODO: 检查/验证更多标志
        if (header.disk_number != 0)
            return error.ZipMultiDiskUnsupported;

        var extents: FileExtents = .{
            .uncompressed_size = header.uncompressed_size,
            .compressed_size = header.compressed_size,
            .local_file_header_offset = header.local_file_header_offset,
        };

        if (header.extra_len > 0) {
            var extra_buf: [std.math.maxInt(u16)]u8 = undefined;
            const extra = extra_buf[0..header.extra_len];

            try input.seekTo(header_zip_offset + @sizeOf(CentralDirectoryFileHeader) + header.filename_len);
            input.interface.readSliceAll(extra) catch |err| switch (err) {
                error.ReadFailed => return input.err.?,
                error.EndOfStream => |e| return e,
            };

            var extra_offset: usize = 0;
            while (extra_offset + 4 <= extra.len) {
                const header_id = std.mem.readInt(u16, extra[extra_offset..][0..2], .little);
                const data_size = std.mem.readInt(u16, extra[extra_offset..][2..4], .little);
                const end = extra_offset + 4 + data_size;
                if (end > extra.len)
                    return error.ZipBadExtraFieldSize;
                const data = extra[extra_offset + 4 .. end];
                switch (@as(ExtraHeader, @fromBackingInt(@intCast(header_id)))) {
                    .zip64_info => try readZip64FileExtents(CentralDirectoryFileHeader, header, &extents, data),
                    else => {}, // 忽略
                }
                extra_offset = end;
            }
        }

        return .{
            .version_needed_to_extract = header.version_needed_to_extract,
            .flags = header.flags,
            .compression_method = header.compression_method,
            .last_modification_time = header.last_modification_time,
            .last_modification_date = header.last_modification_date,
            .header_zip_offset = header_zip_offset,
            .crc32 = header.crc32,
            .filename_len = header.filename_len,
            .compressed_size = extents.compressed_size,
            .uncompressed_size = extents.uncompressed_size,
            .file_offset = extents.local_file_header_offset,
        };
    }

    pub const Entry = struct {
        version_needed_to_extract: u16,
        flags: GeneralPurposeFlags,
        compression_method: CompressionMethod,
        last_modification_time: u16,
        last_modification_date: u16,
        header_zip_offset: u64,
        crc32: u32,
        filename_len: u32,
        compressed_size: u64,
        uncompressed_size: u64,
        file_offset: u64,

        pub fn getFilename(self: Entry, stream: *File.Reader, filename_buf: []u8, options: ExtractOptions) ![]u8 {
            if (filename_buf.len < self.filename_len)
                return error.ZipInsufficientBuffer;
            switch (self.compression_method) {
                .store, .deflate => {},
                else => return error.UnsupportedCompressionMethod,
            }
            const filename = filename_buf[0..self.filename_len];
            {
                try stream.seekTo(self.header_zip_offset + @sizeOf(CentralDirectoryFileHeader));
                try stream.interface.readSliceAll(filename);
            }

            if (options.allow_backslashes) {
                std.mem.replaceScalar(u8, filename, '\\', '/');
            } else {
                if (std.mem.findScalar(u8, filename, '\\')) |_|
                    return error.ZipFilenameHasBackslash;
            }

            if (isBadFilename(filename))
                return error.ZipBadFilename;

            return filename;
        }

        pub fn extractTo(self: Entry, stream: *File.Reader, w: *Writer) !void {
            switch (self.compression_method) {
                .store, .deflate => {},
                else => return error.UnsupportedCompressionMethod,
            }

            const local_data_header_offset: u64 = local_data_header_offset: {
                const local_header = blk: {
                    try stream.seekTo(self.file_offset);
                    break :blk try stream.interface.takeStruct(LocalFileHeader, .little);
                };
                if (!std.mem.eql(u8, &local_header.signature, &local_file_header_sig))
                    return error.ZipBadFileOffset;
                if (local_header.version_needed_to_extract != self.version_needed_to_extract)
                    return error.ZipMismatchVersionNeeded;
                if (local_header.last_modification_time != self.last_modification_time)
                    return error.ZipMismatchModTime;
                if (local_header.last_modification_date != self.last_modification_date)
                    return error.ZipMismatchModDate;

                if (@as(u16, @bitCast(local_header.flags)) != @as(u16, @bitCast(self.flags)))
                    return error.ZipMismatchFlags;
                if (local_header.crc32 != 0 and local_header.crc32 != self.crc32)
                    return error.ZipMismatchCrc32;
                var extents: FileExtents = .{
                    .uncompressed_size = local_header.uncompressed_size,
                    .compressed_size = local_header.compressed_size,
                    .local_file_header_offset = 0,
                };
                if (local_header.extra_len > 0) {
                    var extra_buf: [std.math.maxInt(u16)]u8 = undefined;
                    const extra = extra_buf[0..local_header.extra_len];

                    {
                        try stream.seekTo(self.file_offset + @sizeOf(LocalFileHeader) + local_header.filename_len);
                        try stream.interface.readSliceAll(extra);
                    }

                    var extra_offset: usize = 0;
                    while (extra_offset + 4 <= local_header.extra_len) {
                        const header_id = std.mem.readInt(u16, extra[extra_offset..][0..2], .little);
                        const data_size = std.mem.readInt(u16, extra[extra_offset..][2..4], .little);
                        const end = extra_offset + 4 + data_size;
                        if (end > local_header.extra_len)
                            return error.ZipBadExtraFieldSize;
                        const data = extra[extra_offset + 4 .. end];
                        switch (@as(ExtraHeader, @fromBackingInt(@intCast(header_id)))) {
                            .zip64_info => try readZip64FileExtents(LocalFileHeader, local_header, &extents, data),
                            else => {}, // 忽略
                        }
                        extra_offset = end;
                    }
                }

                if (extents.compressed_size != 0 and
                    extents.compressed_size != self.compressed_size)
                    return error.ZipMismatchCompLen;
                if (extents.uncompressed_size != 0 and
                    extents.uncompressed_size != self.uncompressed_size)
                    return error.ZipMismatchUncompLen;

                if (local_header.filename_len != self.filename_len)
                    return error.ZipMismatchFilenameLen;

                break :local_data_header_offset @as(u64, local_header.filename_len) +
                    @as(u64, local_header.extra_len);
            };

            const local_data_file_offset: u64 =
                @as(u64, self.file_offset) +
                @as(u64, @sizeOf(LocalFileHeader)) +
                local_data_header_offset;
            try stream.seekTo(local_data_file_offset);

            // TODO 根据 self.compressed_size 限制

            switch (self.compression_method) {
                .store => {
                    stream.interface.streamExact64(w, self.uncompressed_size) catch |err| switch (err) {
                        error.ReadFailed => |e| return stream.err orelse e,
                        error.WriteFailed => |e| return e,
                        error.EndOfStream => return error.ZipDecompressTruncated,
                    };
                },
                .deflate => {
                    var flate_buffer: [flate.max_window_len]u8 = undefined;
                    var decompress: flate.Decompress = .init(&stream.interface, .raw, &flate_buffer);
                    decompress.reader.streamExact64(w, self.uncompressed_size) catch |err| switch (err) {
                        error.ReadFailed => |e| return decompress.err orelse (stream.err orelse e),
                        error.WriteFailed => |e| return e,
                        error.EndOfStream => return error.ZipDecompressTruncated,
                    };
                },
                else => return error.UnsupportedCompressionMethod,
            }
        }

        pub fn extract(
            self: Entry,
            stream: *File.Reader,
            options: ExtractOptions,
            filename_buf: []u8,
            dest: Io.Dir,
        ) !void {
            const io = stream.io;

            const filename = try self.getFilename(stream, filename_buf, options);

            // 所有以 '/' 结尾的条目均为目录
            if (filename[filename.len - 1] == '/') {
                if (self.uncompressed_size != 0)
                    return error.ZipBadDirectorySize;
                try dest.createDirPath(io, filename[0 .. filename.len - 1]);
                return;
            }

            const out_file = blk: {
                if (std.fs.path.dirname(filename)) |dirname| {
                    var parent_dir = try dest.createDirPathOpen(io, dirname, .{});
                    defer parent_dir.close(io);

                    const basename = std.fs.path.basename(filename);
                    break :blk try parent_dir.createFile(io, basename, .{ .exclusive = true });
                }
                break :blk try dest.createFile(io, filename, .{ .exclusive = true });
            };
            defer out_file.close(io);
            var out_file_buffer: [1024]u8 = undefined;
            var file_writer = out_file.writer(io, &out_file_buffer);
            self.extractTo(stream, &file_writer.interface) catch |err| switch (err) {
                error.WriteFailed => |e| return file_writer.err orelse e,
                else => return err,
            };
            try file_writer.end();
        }
    };
};

// 如果 `filename` 以 `root` 开头且其后紧跟正斜杠,则返回 true。
fn filenameInRoot(filename: []const u8, root: []const u8) bool {
    return (filename.len >= root.len + 1) and
        (filename[root.len] == '/') and
        std.mem.eql(u8, filename[0..root.len], root);
}

pub const Diagnostics = struct {
    allocator: std.mem.Allocator,

    /// 所有提取文件的公共根目录,如果存在。
    root_dir: []const u8 = "",

    saw_first_file: bool = false,

    pub fn deinit(self: *Diagnostics) void {
        self.allocator.free(self.root_dir);
        self.* = undefined;
    }

    // 此函数假定 name 是 zip 文件中的文件名,并且已确认不以
    // 斜杠开头,反斜杠已统一为正斜杠,且目录
    // 始终以斜杠结尾。
    pub fn nextFilename(self: *Diagnostics, name: []const u8) error{OutOfMemory}!void {
        if (!self.saw_first_file) {
            self.saw_first_file = true;
            std.debug.assert(self.root_dir.len == 0);
            const root_len = std.mem.findScalar(u8, name, '/') orelse return;
            std.debug.assert(root_len > 0);
            self.root_dir = try self.allocator.dupe(u8, name[0..root_len]);
        } else if (self.root_dir.len > 0) {
            if (!filenameInRoot(name, self.root_dir)) {
                self.allocator.free(self.root_dir);
                self.root_dir = "";
            }
        }
    }
};

pub const ExtractOptions = struct {
    /// 允许 zip 内文件名使用反斜杠。传给平台 API 前,会将反斜杠规范化为正斜杠。
    ///
    allow_backslashes: bool = false,
    diagnostics: ?*Diagnostics = null,
    verify_checksums: bool = false,
};

/// 将压缩文件解压到给定 `dest` 目录。
pub fn extract(dest: Io.Dir, fr: *File.Reader, options: ExtractOptions) !void {
    if (options.verify_checksums) @panic("TODO unimplemented");

    var iter = try Iterator.init(fr);

    var filename_buf: [std.fs.max_path_bytes]u8 = undefined;
    while (try iter.next()) |entry| {
        try entry.extract(fr, options, &filename_buf, dest);
        if (options.diagnostics) |d| {
            try d.nextFilename(filename_buf[0..entry.filename_len]);
        }
    }
}

const testing = std.testing;

test "extractTo" {
    const io = testing.io;
    var tmp = testing.tmpDir(.{});
    defer tmp.cleanup();

    try tmp.dir.writeFile(io, .{
        .sub_path = "test.zip",
        .data = @embedFile("zip/testdata/test.zip"),
    });

    var file = try tmp.dir.openFile(io, "test.zip", .{});
    defer file.close(io);
    var read_buf: [512]u8 = undefined;
    var reader = file.reader(io, &read_buf);

    const Expected = struct {
        contents: []const u8,
        compression: CompressionMethod,
    };
    const expected_map = std.StaticStringMap(Expected).initComptime(.{
        .{ "deflate.txt", Expected{ .contents = "aaaaaaaaaaaaaaaaaaaaaaaa\n", .compression = .deflate } },
        .{ "store.txt", Expected{ .contents = "hello world\n", .compression = .store } },
        .{ "dir/", Expected{ .contents = "", .compression = .store } },
    });

    var iter = try Iterator.init(&reader);
    var num_entries: usize = 0;
    while (try iter.next()) |entry| {
        var filename_buf: [256]u8 = undefined;
        const filename = try entry.getFilename(&reader, &filename_buf, .{});
        const expected = expected_map.get(filename) orelse {
            std.debug.print("found unexpected filename: {f}\n", .{std.ascii.hexEscape(filename, .lower)});
            return error.UnexpectedFilename;
        };
        var buf: [256]u8 = undefined;
        var w: Writer = .fixed(&buf);
        try entry.extractTo(&reader, &w);
        try testing.expectEqualStrings(expected.contents, w.buffered());
        try testing.expectEqual(expected.compression, entry.compression_method);
        num_entries += 1;
    }
    try testing.expectEqual(expected_map.kvs.len, num_entries);
}

test "output buffers too small" {
    const io = testing.io;
    var tmp = testing.tmpDir(.{});
    defer tmp.cleanup();

    try tmp.dir.writeFile(io, .{
        .sub_path = "test.zip",
        .data = @embedFile("zip/testdata/test.zip"),
    });

    var file = try tmp.dir.openFile(io, "test.zip", .{});
    defer file.close(io);
    var read_buf: [512]u8 = undefined;
    var reader = file.reader(io, &read_buf);

    var iter = try Iterator.init(&reader);
    var num_entries: usize = 0;
    while (try iter.next()) |entry| {
        try testing.expectError(
            error.ZipInsufficientBuffer,
            entry.getFilename(&reader, &.{}, .{}),
        );

        if (entry.uncompressed_size <= 1) continue;

        var buf: [1]u8 = undefined;
        var w: Writer = .fixed(&buf);
        try testing.expectError(
            error.WriteFailed,
            entry.extractTo(&reader, &w),
        );
        num_entries += 1;
    }
    try std.testing.expect(num_entries > 0);
}