Documentation
¶
Index ¶
Constants ¶
const ( // TOCTarName is the name of the JSON file in the tar archive in the // table of contents gzip stream. TOCTarName = "stargz.index.json" // // The footer is an empty gzip stream with no compression and an Extra // header of the form "%016xSTARGZ", where the 64 bit hex-encoded // number is the offset to the gzip stream of JSON TOC. // // 51 comes from: // // 10 bytes gzip header // 2 bytes XLEN (length of Extra field) = 26 (4 bytes header + 16 hex digits + len("STARGZ")) // 2 bytes Extra: SI1 = 'S', SI2 = 'G' // 2 bytes Extra: LEN = 22 (16 hex digits + len("STARGZ")) // 22 bytes Extra: subfield = fmt.Sprintf("%016xSTARGZ", offsetOfTOC) // 5 bytes flate header // 8 bytes gzip footer // (End of the eStargz blob) // // NOTE: For Extra fields, subfield IDs SI1='S' SI2='G' is used for eStargz. FooterSize = 51 // TOCJSONDigestAnnotation is an annotation for an image layer. This stores the // digest of the TOC JSON. // This annotation is valid only when it is specified in `.[]layers.annotations` // of an image manifest. TOCJSONDigestAnnotation = "containerd.io/snapshot/stargz/toc.digest" // StoreUncompressedSizeAnnotation is an additional annotation key for eStargz to enable lazy // pulling on containers/storage. Stargz Store is required to expose the layer's uncompressed size // to the runtime but current OCI image doesn't ship this information by default. So we store this // to the special annotation. StoreUncompressedSizeAnnotation = "io.containers.estargz.uncompressed-size" // PrefetchLandmark is a file entry which indicates the end position of // prefetch in the stargz file. PrefetchLandmark = ".prefetch.landmark" // NoPrefetchLandmark is a file entry which indicates that no prefetch should // occur in the stargz file. NoPrefetchLandmark = ".no.prefetch.landmark" )
Variables ¶
This section is empty.
Functions ¶
func OpenFooter ¶
func OpenFooter(sr *io.SectionReader) (tocOffset int64, footerSize int64, rErr error)
OpenFooter extracts and parses footer from the given blob.
Types ¶
type Blob ¶
type Blob struct {
io.ReadCloser
// contains filtered or unexported fields
}
Blob is an eStargz blob.
func Build ¶
func Build(tarBlob *io.SectionReader, opt ...Option) (_ *Blob, rErr error)
Build builds an eStargz blob which is an extended version of stargz, from a blob (gzip, zstd or plain tar) passed through the argument. If there are some prioritized files are listed in the option, these files are grouped as "prioritized" and can be used for runtime optimization (e.g. prefetch). This function builds a blob in parallel, with dividing that blob into several (at least the number of runtime.GOMAXPROCS(0)) sub-blobs.
type Option ¶
type Option func(o *options) error
func WithAllowPrioritizeNotFound ¶
WithAllowPrioritizeNotFound makes Build continue the execution even if some of prioritized files specified by WithPrioritizedFiles option aren't found in the input tar. Instead, this records all missed file names to the passed slice.
func WithChunkSize ¶
WithChunkSize option specifies the chunk size of eStargz blob to build.
func WithCompressionLevel ¶
WithCompressionLevel option specifies the gzip compression level. The default is gzip.BestCompression. See also: https://godoc.org/compress/gzip#pkg-constants
func WithPrioritizedFiles ¶
WithPrioritizedFiles option specifies the list of prioritized files. These files must be complete paths that are absolute or relative to "/" For example, all of "foo/bar", "/foo/bar", "./foo/bar" and "../foo/bar" are treated as "/foo/bar".
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
A Reader permits random access reads from a stargz file.
func Open ¶
func Open(sr *io.SectionReader) (*Reader, error)
Open opens a stargz file for reading.
Note that each entry name is normalized as the path that is relative to root.
func (*Reader) ChunkEntryForOffset ¶
ChunkEntryForOffset returns the TOCEntry containing the byte of the named file at the given offset within the file. Name must be absolute path or one that is relative to root.
func (*Reader) Lookup ¶
Lookup returns the Table of Contents entry for the given path.
To get the root directory, use the empty string. Path must be absolute path or one that is relative to root.
func (*Reader) OpenFile ¶
func (r *Reader) OpenFile(name string) (*io.SectionReader, error)
OpenFile returns the reader of the specified file payload.
Name must be absolute path or one that is relative to root.
func (*Reader) VerifyTOC ¶
func (r *Reader) VerifyTOC(tocDigest digest.Digest) (TOCEntryVerifier, error)
VerifyTOC checks that the TOC JSON in the passed blob matches the passed digests and that the TOC JSON contains digests for all chunks contained in the blob. If the verification succceeds, this function returns TOCEntryVerifier which holds all chunk digests in the stargz blob.
type TOCEntry ¶
type TOCEntry struct {
// Name is the tar entry's name. It is the complete path
// stored in the tar file, not just the base name.
Name string `json:"name"`
// Type is one of "dir", "reg", "symlink", "hardlink", "char",
// "block", "fifo", or "chunk".
// The "chunk" type is used for regular file data chunks past the first
// TOCEntry; the 2nd chunk and on have only Type ("chunk"), Offset,
// ChunkOffset, and ChunkSize populated.
Type string `json:"type"`
// Size, for regular files, is the logical size of the file.
Size int64 `json:"size,omitempty"`
// ModTime3339 is the modification time of the tar entry. Empty
// means zero or unknown. Otherwise it's in UTC RFC3339
// format. Use the ModTime method to access the time.Time value.
ModTime3339 string `json:"modtime,omitempty"`
// LinkName, for symlinks and hardlinks, is the link target.
LinkName string `json:"linkName,omitempty"`
// Mode is the permission and mode bits.
Mode int64 `json:"mode,omitempty"`
// UID is the user ID of the owner.
UID int `json:"uid,omitempty"`
// GID is the group ID of the owner.
GID int `json:"gid,omitempty"`
// Uname is the username of the owner.
//
// In the serialized JSON, this field may only be present for
// the first entry with the same UID.
Uname string `json:"userName,omitempty"`
// Gname is the group name of the owner.
//
// In the serialized JSON, this field may only be present for
// the first entry with the same GID.
Gname string `json:"groupName,omitempty"`
// Offset, for regular files, provides the offset in the
// stargz file to the file's data bytes. See ChunkOffset and
// ChunkSize.
Offset int64 `json:"offset,omitempty"`
// DevMajor is the major device number for "char" and "block" types.
DevMajor int `json:"devMajor,omitempty"`
// DevMinor is the major device number for "char" and "block" types.
DevMinor int `json:"devMinor,omitempty"`
// NumLink is the number of entry names pointing to this entry.
// Zero means one name references this entry.
NumLink int
// Xattrs are the extended attribute for the entry.
Xattrs map[string][]byte `json:"xattrs,omitempty"`
// Digest stores the OCI checksum for regular files payload.
// It has the form "sha256:abcdef01234....".
Digest string `json:"digest,omitempty"`
// ChunkOffset is non-zero if this is a chunk of a large,
// regular file. If so, the Offset is where the gzip header of
// ChunkSize bytes at ChunkOffset in Name begin.
//
// In serialized form, a "chunkSize" JSON field of zero means
// that the chunk goes to the end of the file. After reading
// from the stargz TOC, though, the ChunkSize is initialized
// to a non-zero file for when Type is either "reg" or
// "chunk".
ChunkOffset int64 `json:"chunkOffset,omitempty"`
ChunkSize int64 `json:"chunkSize,omitempty"`
// ChunkDigest stores an OCI digest of the chunk. This must be formed
// as "sha256:0123abcd...".
ChunkDigest string `json:"chunkDigest,omitempty"`
// contains filtered or unexported fields
}
TOCEntry is an entry in the stargz file's TOC (Table of Contents).
func (*TOCEntry) ForeachChild ¶
ForeachChild calls f for each child item. If f returns false, iteration ends. If e is not a directory, f is not called.
func (*TOCEntry) LookupChild ¶
LookupChild returns the directory e's child by its base name.
func (*TOCEntry) NextOffset ¶
NextOffset returns the position (relative to the start of the stargz file) of the next gzip boundary after e.Offset.
type TOCEntryVerifier ¶
type TOCEntryVerifier interface {
// Verifier provides a content verifier that can be used for verifying the
// contents of the specified TOCEntry.
Verifier(ce *TOCEntry) (digest.Verifier, error)
}
TOCEntryVerifier holds verifiers that are usable for verifying chunks contained in a eStargz blob.
type Writer ¶
type Writer struct {
// ChunkSize optionally controls the maximum number of bytes
// of data of a regular file that can be written in one gzip
// stream before a new gzip stream is started.
// Zero means to use a default, currently 4 MiB.
ChunkSize int
// contains filtered or unexported fields
}
A Writer writes stargz files.
Use NewWriter to create a new Writer.
func NewWriter ¶
NewWriter returns a new stargz writer writing to w.
The writer must be closed to write its trailing table of contents.
func NewWriterLevel ¶
NewWriterLevel returns a new stargz writer writing to w. The compression level is configurable.
The writer must be closed to write its trailing table of contents.
func (*Writer) AppendTar ¶
AppendTar reads the tar or tar.gz file from r and appends each of its contents to w.
The input r can optionally be gzip compressed but the output will always be gzip compressed.
Source Files
Directories