Documentation
¶
Overview ¶
Package imagefetch admits registry content before giving Docker any bytes. A Prepared capability owns bounded, verified image blobs; only its issuing Loader can import them. Docker never re-fetches content from a tenant registry. Mutable tags are re-resolved with a manifest HEAD on every preparation, and manifests the Loader already verified are reused by repository and digest.
Index ¶
- type ImportAdmission
- type Imported
- type Importer
- type Loader
- func (l *Loader) CleanupAbandoned() error
- func (l *Loader) Import(ctx context.Context, p *Prepared) (Imported, error)
- func (l *Loader) ImportAdmitted(ctx context.Context, admission *ImportAdmission) (Imported, error)
- func (l *Loader) PendingBytes() (int64, error)
- func (l *Loader) Prepare(ctx context.Context, ref string, platform ocispec.Platform) (*Prepared, error)
- func (l *Loader) PrepareResolved(ctx context.Context, resolution Resolution) (*Prepared, error)
- func (l *Loader) ReserveImport(ctx context.Context, p *Prepared) (*ImportAdmission, error)
- func (l *Loader) Resolve(ctx context.Context, ref string, platform ocispec.Platform) (Resolution, error)
- func (l *Loader) Shutdown(ctx context.Context) error
- func (l *Loader) UnknownBytes() (int64, error)
- func (l *Loader) VerificationBudget() imagebudget.VerificationBudget
- func (l *Loader) WithBudget(budget imagebudget.VerificationBudget) (*Loader, error)
- type Option
- type Prepared
- func (p *Prepared) Budget() imagebudget.Budget
- func (p *Prepared) Close() error
- func (p *Prepared) ConfigID() string
- func (p *Prepared) ImportBytes() int64
- func (p *Prepared) ManifestID() string
- func (p *Prepared) Metadata() imageexec.Metadata
- func (p *Prepared) Platform() ocispec.Platform
- func (p *Prepared) SourceReference() string
- type Resolution
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ImportAdmission ¶
type ImportAdmission struct {
// contains filtered or unexported fields
}
ImportAdmission owns a persisted allocation and a single possible dispatch. Copies share its lifecycle. Close cancels an undispatched admission with positive evidence that Docker never received it, or waits for its exchange.
func (*ImportAdmission) CancelBeforeDispatch ¶
func (a *ImportAdmission) CancelBeforeDispatch() (bool, error)
CancelBeforeDispatch consumes this exact admission and proves it cannot issue a daemon request. A copied capability cannot race a later dispatch past this check. False means the admission already dispatched or was consumed; an error means allocation release could not be proven. Neither permits replacement work.
func (*ImportAdmission) Close ¶
func (a *ImportAdmission) Close() error
Close releases only an allocation that is proven never dispatched. An uncertain completed request retains its durable debit for operator recovery.
type Imported ¶
type Imported struct {
// contains filtered or unexported fields
}
Imported is the identity established by a completed exact-content import.
func (Imported) ManifestID ¶
func (Imported) SourceReference ¶
type Importer ¶
type Importer interface {
ImageLoad(context.Context, io.Reader, ...client.ImageLoadOption) (image.LoadResponse, error)
}
Importer is the only daemon mutation available to a Loader.
type Loader ¶
type Loader struct {
// contains filtered or unexported fields
}
Loader owns the registry preparation and exact-content import boundary.
func NewLoader ¶
func NewLoader(source Importer, stageRoot string, maxBytes int64, options ...Option) (*Loader, error)
NewLoader creates a bounded importer in an existing writable directory. Its caller must hold exclusive authority for that directory while this Loader is used. Copies of a Loader share the same durable debit synchronization.
func (*Loader) CleanupAbandoned ¶
CleanupAbandoned removes only recognizable empty staging directories and zero-byte creation remnants. Call only after acquiring exclusive backend storage ownership; live preparation directories must never be scavenged. Actual content is unlinked before downloading and needs no crash scavenger.
func (*Loader) ImportAdmitted ¶
ImportAdmitted dispatches only this Loader's single-use reserved capability. Original verified blobs prevent registry changes from introducing new data.
func (*Loader) PendingBytes ¶
PendingBytes reports import allocations whose completion has not been established. The caller must charge these bytes before any new admission. An unreadable record is an admission refusal, never evidence of zero debt.
func (*Loader) Prepare ¶
func (l *Loader) Prepare(ctx context.Context, ref string, platform ocispec.Platform) (*Prepared, error)
Prepare performs bounded registry I/O and decompression without extracting anything into Docker or the host filesystem.
func (*Loader) PrepareResolved ¶
PrepareResolved verifies the exact selection without resolving its tag again. Staged blobs are unlinked while open, so a crash releases their disk space.
func (*Loader) ReserveImport ¶
ReserveImport durably charges allocation before a caller releases its storage admission gate. The returned owner must be closed on every subsequent path.
func (*Loader) Resolve ¶
func (l *Loader) Resolve(ctx context.Context, ref string, platform ocispec.Platform) (Resolution, error)
Resolve verifies bounded manifest/config metadata without downloading layers.
func (*Loader) Shutdown ¶
Shutdown closes admission and lets admitted exchanges finish within the backend's drain budget. Only expiry of that budget cancels daemon work; tenant cancellation cannot terminate an import this owner already dispatched.
func (*Loader) UnknownBytes ¶
UnknownBytes excludes live owned admissions from durable unfinished imports. A reopened loader has no such owners and therefore charges the complete debt.
func (*Loader) VerificationBudget ¶
func (l *Loader) VerificationBudget() imagebudget.VerificationBudget
VerificationBudget is this issuer's staging and decoding ceiling. Flight admission derives its identity and reservation from this same typed value.
func (*Loader) WithBudget ¶
func (l *Loader) WithBudget(budget imagebudget.VerificationBudget) (*Loader, error)
WithBudget derives a distinct preparation issuer for bounded recovery while retaining this owner's transport, durable debit ledger and shutdown lifetime. The caller supplies an independently verified recovery allowance, rather than changing the admission limit of the existing issuer.
type Option ¶
Option configures registry transport while retaining the mandatory HTTPS and response-byte boundaries.
func WithRegistryTransport ¶
WithRegistryTransport projects operator trust and routing settings into an owned native transport. Fred controls HTTP protocol negotiation and replay; custom TLS dialers cannot bypass that construction boundary.
type Prepared ¶
type Prepared struct {
// contains filtered or unexported fields
}
Prepared owns immutable, already verified content. Its zero value grants no import authority. Close releases all staging space, including after errors.
func (*Prepared) Budget ¶
func (p *Prepared) Budget() imagebudget.Budget
Budget returns the separate verified content and physical allocation bounds.
func (*Prepared) ImportBytes ¶
ImportBytes returns a conservative allowance for the daemon's archive, expanded layer data and filesystem metadata; Fred's staging is already used.
func (*Prepared) ManifestID ¶
ManifestID and ConfigID expose the immutable identity before dispatch, for callers that durably protect content while admission is in flight.
func (*Prepared) SourceReference ¶
SourceReference identifies the original repository and selected manifest.
type Resolution ¶
type Resolution struct {
// contains filtered or unexported fields
}
Resolution binds one immutable manifest to digest-verified configuration and an admitted platform/layer schema. Its zero value carries no authority; copies retain the same original evidence. It grants no layer/import budget.
func (Resolution) ConfigID ¶
func (r Resolution) ConfigID() string
ConfigID identifies the exact image config selected through the verified manifest. Classic Docker can address already-extracted content by this ID even when its repository digests contain only the multi-platform index. It is selection evidence only; the local admitter still validates the image.
func (Resolution) ManifestID ¶
func (r Resolution) ManifestID() string
func (Resolution) Platform ¶
func (r Resolution) Platform() ocispec.Platform
func (Resolution) SourceReference ¶
func (r Resolution) SourceReference() string
Source Files