Affected by 
Documentation
¶
Overview ¶
Package blob implements a content-addressable disk cache for blobs and manifests.
Index ¶
- Variables
- func PutBytes[S string | []byte](c *DiskCache, d Digest, data S) error
- type Chunk
- type Chunker
- type Digest
- type DiskCache
- func (c *DiskCache) Chunked(d Digest, size int64) (*Chunker, error)
- func (c *DiskCache) Get(d Digest) (Entry, error)
- func (c *DiskCache) GetFile(d Digest) string
- func (c *DiskCache) Import(r io.Reader, size int64) (Digest, error)
- func (c *DiskCache) Link(name string, d Digest) error
- func (c *DiskCache) Links() iter.Seq2[string, error]
- func (c *DiskCache) Put(d Digest, r io.Reader, size int64) error
- func (c *DiskCache) Resolve(name string) (Digest, error)
- func (c *DiskCache) Unlink(name string) (ok bool, _ error)
- type Entry
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidDigest = errors.New("invalid digest")
Functions ¶
Types ¶
type Chunker ¶ added in v0.6.1
type Chunker struct {
// contains filtered or unexported fields
}
Chunker writes to a blob in chunks. Its zero value is invalid. Use DiskCache.Chunked to create a new Chunker.
type Digest ¶
type Digest struct {
// contains filtered or unexported fields
}
Digest is a blob identifier that is the SHA-256 hash of a blob's content.
It is comparable and can be used as a map key.
func DigestFromBytes ¶
func ParseDigest ¶
ParseDigest parses a digest from a string. If the string is not a valid digest, a call to the returned digest's IsValid method will return false.
The input string may be in one of two forms:
- ("sha256-<hex>"), where <hex> is a 64-character hexadecimal string.
- ("sha256:<hex>"), where <hex> is a 64-character hexadecimal string.
The Digest.String method will return the canonical form of the digest, "sha256:<hex>".
func (Digest) IsValid ¶
IsValid returns true if the digest is valid, i.e. if it is the SHA-256 hash of some content.
func (Digest) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface. It returns an error if Digest.IsValid returns false.
func (Digest) String ¶
String returns the string representation of the digest in the conventional form "sha256:<hex>".
func (*Digest) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface, and only works for a zero digest. If Digest.IsValid returns true, it returns an error.
type DiskCache ¶
type DiskCache struct {
// contains filtered or unexported fields
}
DiskCache caches blobs and manifests on disk.
The cache is rooted at a directory, which is created if it does not exist.
Blobs are stored in the "blobs" subdirectory, and manifests are stored in the "manifests" subdirectory. A example directory structure might look like:
<dir>/
blobs/
sha256-<digest> - <blob data>
manifests/
<host>/
<namespace>/
<name>/
<tag> - <manifest data>
The cache is safe for concurrent use.
Name casing is preserved in the cache, but is not significant when resolving names. For example, "Foo" and "foo" are considered the same name.
The cache is not safe for concurrent use. It guards concurrent writes, but does not prevent duplicated effort. Because blobs are immutable, duplicate writes should result in the same file being written to disk.
func Open ¶
Open opens a cache rooted at the given directory. If the directory does not exist, it is created. If the directory is not a directory, an error is returned.
func (*DiskCache) Chunked ¶ added in v0.6.1
Chunked returns a new Chunker, ready for use storing a blob of the given size in chunks.
Use Chunker.Put to write data to the blob at specific offsets.
func (*DiskCache) Get ¶
Get retrieves a blob from the cache using the provided digest. The operation fails if the digest is malformed or if any errors occur during blob retrieval.
func (*DiskCache) GetFile ¶
GetFile returns the absolute path to the file, in the cache, for the given digest. It does not check if the file exists.
The returned path should not be stored, used outside the lifetime of the cache, or interpreted in any way.
func (*DiskCache) Import ¶
Import imports a blob from the provided reader into the cache. It reads the entire content of the reader, calculates its digest, and stores it in the cache.
Import should be considered unsafe for use with untrusted data, such as data read from a network. The caller is responsible for ensuring the integrity of the data being imported.
func (*DiskCache) Link ¶
Link creates a symbolic reference in the cache that maps the provided name to a blob identified by its digest, making it retrievable by name using [Resolve].
It returns an error if either the name or digest is invalid, or if link creation encounters any issues.
func (*DiskCache) Links ¶
Links returns a sequence of link names. The sequence is in lexical order. Names are converted from their relative path form to their name form but are not guaranteed to be valid. Callers should validate the names before using.
func (*DiskCache) Put ¶
Put writes a new blob to the cache, identified by its digest. The operation reads content from r, which must precisely match both the specified size and digest.
Concurrent write safety is achieved through file locking. The implementation guarantees write integrity by enforcing size limits and content validation before allowing the file to reach its final state.
func (*DiskCache) Resolve ¶
Resolve resolves a name to a digest. The name is expected to be in either of the following forms:
@<digest> <name>@<digest> <name>
If a digest is provided, it is returned as is and nothing else happens.
If a name is provided for a manifest that exists in the cache, the digest of the manifest is returned. If there is no manifest in the cache, it returns fs.ErrNotExist.
To cover the case where a manifest may change without the cache knowing (e.g. it was reformatted or modified by hand), the manifest data read and hashed is passed to a PutBytes call to ensure that the manifest is in the blob store. This is done to ensure that future calls to [Get] succeed in these cases.
Source Files