README
¶
mod/archive
mod/archive turns a downloaded release archive into a staged file tree. It does not decide which versions to mirror
and it does not commit durable state. Its job is to parse archive formats safely, enforce archive limits, and produce
staged entries and blob files for mod/rescan and mod/storage.
Place in the runtime
flowchart TB
source["downloaded archive"] --> archive["mod/archive"]
archive --> checks["format, paths, limits"]
checks --> spool["staged blobs"]
spool --> rescan["mod/rescan"]
rescan --> storage["mod/storage"]
Responsibilities
- Read
zip,tar, andtar.gzinputs. - Reject path traversal, unsafe names, unsupported entry types, and size-limit violations.
- Drop symlink entries whose targets would escape the staged tree.
- Write blob payloads into the caller-provided spool directory.
- Return canonical staged entries with path, mode, hash, and size.
- Preserve enough error detail for rescan diagnostics.
Contracts
- Archive extraction is bounded by configured compressed size, unpacked size, file count, path length, and per-file size limits.
- Symlinks are represented as entries with link target bytes only after the target passes the archive tree check. Unsafe symlink targets are omitted from the staged tree and reported in the extraction result.
- The package must not trust archive metadata without checking the actual bytes read.
- The output tree is staged, not published.
mod/storage.PublishStagedis the durability boundary.
Important files
obj.go: archive object and public extraction entry.zip.go,tar.go: format-specific readers.write.go: staged blob writing and hash calculation.helper.go: path and mode helpers.
Operational notes
Archive parsing is an abuse boundary. Keep new format support conservative and make every new entry type explicit. Silent best-effort extraction is not acceptable because the result becomes package-manager input. Symlink drops are the only tolerated partial extraction path: the unsafe link is excluded, while the remaining tree can still be validated by rescan and storage.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BlobSourceInterface ¶
type BlobSourceInterface interface {
UseBlob(ctx context.Context, hashObj core.HashObj, useFunc func([]byte) error) error
}
BlobSourceInterface serves a blob by hash; useFunc is invoked exactly once, synchronously.
type FormatType ¶
type FormatType string
FormatType is an archive format; see the Format constants.
const ( // FormatZip is the zip format. FormatZip FormatType = "zip" // FormatTar is the tar format. FormatTar FormatType = "tar" // FormatTarGz is the tar.gz format. FormatTarGz FormatType = "tar.gz" )
func (FormatType) String ¶
func (obj FormatType) String() string
String returns the textual format representation.
type LimitsObj ¶
type LimitsObj struct {
MaxArchiveSize uint64
MaxArchiveUnpackedSize uint64
MaxArchiveFileBytes uint64
MaxArchiveFiles uint
MaxArchivePathBytes uint
}
LimitsObj contains caps against zip/tar bombs and abuse: compressed and unpacked size, file size and count, and path length. All non-size fields are required; 0 in size fields means unlimited.
type Obj ¶
type Obj struct {
// contains filtered or unexported fields
}
Obj is the archive extract/write engine; it keeps anti-bomb and anti-traversal limits and is immutable after New.
func (*Obj) Extract ¶
Extract unpacks an archive into temporary blobs under anti-bomb and anti-traversal limits. On error the created blobs are deleted and no result is returned.
func (*Obj) Write ¶
func (obj *Obj) Write(ctx context.Context, requestObj WriteRequestObj) (WriteResultObj, error)
Write builds an archive from the validated entry list under limits. Output is deterministic: fixed mode/time, sorted paths, rejected conflicts, duplicates and symlink targets.
func (*Obj) WriteTree ¶
func (obj *Obj) WriteTree(ctx context.Context, requestObj WriteTreeRequestObj) (WriteResultObj, error)
WriteTree reads the tree by hash from Source and builds the archive via Write.
type RequestObj ¶
type RequestObj struct {
Key string
Version string
Format FormatType
SourcePath string
SourceSizeBytes uint64
SpoolPath string
// contains filtered or unexported fields
}
RequestObj is an extraction request: format, source path, and spool directory for temporary blobs.
type ResultObj ¶
type ResultObj struct {
Entries []core.StagedEntryObj
Blobs []core.StagedBlobObj
DroppedSymlinks []string
}
ResultObj is the extraction result: canonical tree entry paths and deduplicated staged blobs.
type TreeSourceInterface ¶
type TreeSourceInterface interface {
BlobSourceInterface
ReadTree(ctx context.Context, treeHashObj core.HashObj) ([]core.TreeEntryObj, error)
}
TreeSourceInterface adds reading a version tree by hash.
type WriteRequestObj ¶
type WriteRequestObj struct {
Format FormatType
Writer io.Writer
Entries []core.TreeEntryObj
Source BlobSourceInterface
}
WriteRequestObj describes writing an archive from a ready-made list of entries.
type WriteResultObj ¶
WriteResultObj records the entry count and the actually written body size.
type WriteTreeRequestObj ¶
type WriteTreeRequestObj struct {
Format FormatType
Writer io.Writer
TreeHash core.HashObj
Source TreeSourceInterface
}
WriteTreeRequestObj describes writing an archive by tree hash; entries are read from Source.
Source Files