Documentation
¶
Overview ¶
Package container 提供 OFD 文档容器的索引、安全读取、逻辑包视图及 ZIP 压缩和规模预算。
Index ¶
- Constants
- Variables
- func ApplyCompressionLevel(w *zip.Writer, level int)
- func CheckSize(name string, size, maxEntryBytes, maxTotalBytes int64, remaining *int64) error
- func EntryMethod(name string, mode CompressionMode) uint16
- func NormalizeCompressionLevel(level int) (int, error)
- func ValidateEntryName(name string) error
- func ValidateLimits(limits Limits) error
- type CompressionMode
- type Entry
- type LimitWriter
- type Limits
- type Package
- func NewVirtual(entries []Entry, open func(string) (io.ReadCloser, error), closer io.Closer) (*Package, error)
- func OpenBytes(data []byte) (*Package, error)
- func OpenFile(filename string) (*Package, error)
- func OpenReader(reader io.Reader) (*Package, error)
- func OpenReaderAt(reader io.ReaderAt, size int64) (*Package, error)
- func (p *Package) Close() error
- func (p *Package) Entries() []Entry
- func (p *Package) Has(fileName string) bool
- func (p *Package) InputSize() int64
- func (p *Package) Lookup(fileName string) (Entry, bool)
- func (p *Package) Open(fileName string) (io.ReadCloser, error)
- func (p *Package) OpenEntry(entry Entry) (io.ReadCloser, error)
- func (p *Package) Read(fileName string) ([]byte, error)
- func (p *Package) ReadLimit(fileName string, limit int64) ([]byte, error)
- func (p *Package) ReadXML(fileName string, target any) error
- func (p *Package) ReadXMLLimit(fileName string, target any, limit int64) error
- func (p *Package) WalkEntries(fn func(Entry) bool) error
- type PackageSource
Constants ¶
const ( // DefaultMaxEntries 是默认的最大条目数。 DefaultMaxEntries = 10000 // DefaultMaxEntryBytes 是默认的单条解压上限（64MB）。 DefaultMaxEntryBytes = int64(64 << 20) // DefaultMaxTotalBytes 是默认的解压总字节上限（512MB）。 DefaultMaxTotalBytes = int64(512 << 20) )
const DefaultCompressionLevel = 5
DefaultCompressionLevel 是 DEFLATE 的默认压缩级别，与 klauspost zip 的 默认一致。级别越高压缩率越高、写入越慢。
Variables ¶
var ( // ErrReadLimitExceeded 表示读取的解压后内容超过了大小限制。 ErrReadLimitExceeded = errors.New("读取内容超过大小限制") // ErrPackageClosed 表示 ZIP 包已经关闭。 ErrPackageClosed = errors.New("ZIP 包已经关闭") )
Functions ¶
func ApplyCompressionLevel ¶
ApplyCompressionLevel 在 zip.Writer 上按级别注册 DEFLATE 压缩器，必须 在第一次创建 Deflate 条目之前调用。level 为 0 或默认级别时保持 klauspost 的默认实现，不注册。调用方应先通过 NormalizeCompressionLevel 校验级别。
func EntryMethod ¶
func EntryMethod(name string, mode CompressionMode) uint16
EntryMethod 返回 ZIP 条目的压缩方式。mode 为 "store" 或 "deflate" 时 强制指定；其他值按扩展名自动选择：本身已压缩的格式使用 Store，其余使用 Deflate。
func NormalizeCompressionLevel ¶
NormalizeCompressionLevel 校验 DEFLATE 压缩级别：0 表示使用默认级别 DefaultCompressionLevel，显式范围 1（最快）到 9（最紧凑）。返回实际 应使用的压缩级别。
func ValidateEntryName ¶
ValidateEntryName 校验 OFD 包条目的相对路径是否安全：非空、不以斜杠开头、 不含反斜杠或 NUL，且清理后保持原样（不含 . 或 .. 片段）。该函数不检查同名重复。
Types ¶
type CompressionMode ¶
type CompressionMode string
CompressionMode 表示 OFD ZIP 条目的压缩策略。
const ( // CompressionAuto 对已压缩格式使用 Store，其他文件使用 Deflate。 CompressionAuto CompressionMode = "auto" // CompressionDeflate 对所有条目使用 Deflate。 CompressionDeflate CompressionMode = "deflate" // CompressionStore 对所有条目使用 Store。 CompressionStore CompressionMode = "store" )
func NormalizeCompression ¶
func NormalizeCompression(mode CompressionMode) (CompressionMode, error)
NormalizeCompression 返回合法化的压缩策略：空值使用 CompressionAuto， 不支持的值返回错误。
type Entry ¶
type Entry struct {
// Virtual 表示元数据描述的是逻辑条目，不对应实际 ZIP 文件头。
Virtual bool
// SizeUnknown 和 Locked 仅用于部分解锁的逻辑视图。
SizeUnknown bool
Locked bool
// Name 是 ZIP 条目的原始名称。
Name string
// Path 是去除开头斜杠后的包内查找路径。
Path string
// CompressedSize 是条目的压缩后大小。
CompressedSize uint64
// UncompressedSize 是条目的解压后大小。
UncompressedSize uint64
// Method 是 ZIP 压缩方法编号。
Method uint16
// CRC32 是条目的 CRC-32 校验值。
CRC32 uint32
// Modified 是条目的修改时间。
Modified time.Time
// Mode 是条目的文件模式。
Mode fs.FileMode
// IsDir 表示条目是否为目录。
IsDir bool
// contains filtered or unexported fields
}
Entry 描述 OFD ZIP 包中的一个条目。
type LimitWriter ¶
type LimitWriter struct {
// contains filtered or unexported fields
}
LimitWriter 在复制过程中同时限制单条与总解压字节数，防止声明的解压 大小与实际不符（如 zip bomb）。
func NewLimitWriter ¶
func NewLimitWriter(writer io.Writer, name string, entryRemaining, maxTotal int64, totalRemaining *int64) *LimitWriter
NewLimitWriter 返回带限制的 writer；totalRemaining 指向调用方的总预算， 每次写入后同步扣减。
type Limits ¶
type Limits struct {
// MaxEntries 是允许搬运的最大条目数，0 表示默认 10000。
MaxEntries int
// MaxEntryBytes 是单个条目解压后的最大字节数，0 表示默认 64MB。
MaxEntryBytes int64
// MaxTotalBytes 是所有条目解压后的总字节上限，0 表示默认 512MB。
MaxTotalBytes int64
}
Limits 限制 OFD 包读写的规模，避免恶意或异常文档造成的解压放大。
type Package ¶
type Package struct {
// contains filtered or unexported fields
}
Package 提供 OFD ZIP 包的条目索引和内容读取能力。
func NewVirtual ¶
func NewVirtual(entries []Entry, open func(string) (io.ReadCloser, error), closer io.Closer) (*Package, error)
NewVirtual 创建不可变的包访问视图。元数据及其 Virtual 标记由调用方提供， 每次打开条目均返回新的读取器。closer 释放当前视图的租约， 不影响同一数据源的其他视图。
func OpenReader ¶
OpenReader 从读取器中读取全部数据并打开 OFD ZIP 包。 调用方仍负责关闭传入的 reader。
func OpenReaderAt ¶
OpenReaderAt 从随机访问读取器打开 OFD ZIP 包，无需把数据整体复制到内存。 size 必须是数据的完整字节长度。调用方仍负责关闭底层 reader。
func (*Package) Close ¶
Close 关闭由 OpenFile 创建的 ZIP 包，并释放其文件句柄。 对 OpenBytes 和 OpenReader 创建的对象，Close 没有额外操作。
func (*Package) Lookup ¶
Lookup 查找指定名称的 ZIP 条目元数据。 如果多个条目规范化后路径相同，返回 ZIP 中最后出现的条目；全部条目可通过 Entries 获取。
func (*Package) Open ¶
func (p *Package) Open(fileName string) (io.ReadCloser, error)
Open 打开 ZIP 包内的条目，返回解压后的读取器。
func (*Package) OpenEntry ¶
func (p *Package) OpenEntry(entry Entry) (io.ReadCloser, error)
OpenEntry 打开 Entries 返回的指定 ZIP 条目。 与 Open 不同，OpenEntry 不会因条目名称重复而切换到其他条目。
func (*Package) ReadXMLLimit ¶
ReadXMLLimit 解析 ZIP 包内的 XML 文件，并限制最大字节数。 limit 为 0 时表示不限制。
type PackageSource ¶
PackageSource 提供由使用方持有的逻辑 OFD 包租约。 关闭返回的包不得关闭同一数据源的其他租约。
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package entrywriter 提供带规模限制与确定性选项的 OFD ZIP 条目写入器， 供 ZIP 级处理工具（如 pkg/merge、pkg/replace）复用。
|
Package entrywriter 提供带规模限制与确定性选项的 OFD ZIP 条目写入器， 供 ZIP 级处理工具（如 pkg/merge、pkg/replace）复用。 |