models

package
v3.0.0-dev Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoFetcher indicates that no fetcher was provided for content retrieval.
	ErrNoFetcher = errors.New("no fetcher provided")

	// ErrNoPusher indicates that no pusher was provided for content storage.
	ErrNoPusher = errors.New("no pusher provided")

	// ErrNoContent indicates that no content is available.
	ErrNoContent = errors.New("no content available")

	// ErrInvalidManifest indicates that the manifest is invalid or malformed.
	ErrInvalidManifest = errors.New("invalid manifest")

	// ErrNoClient indicates that no client was provided.
	ErrNoClient = errors.New("no client provided")

	// ErrNotLoaded indicates that the manifest has not been loaded yet.
	// Call Load(ctx) or any method that accepts a context to load the manifest
	// before serializing.
	ErrNotLoaded = errors.New("manifest not loaded: call Load(ctx) first")

	// ErrNoDeleter indicates that the target does not support deletion.
	ErrNoDeleter = errors.New("target does not support deletion")
)

Functions

func WithStorage 

func WithStorage(fetcher content.Fetcher, pusher content.Pusher) func(*Blob)

WithStorage returns a Blob option that sets the fetcher and pusher.

Types

type Artifact 

type Artifact struct {
	// contains filtered or unexported fields
}

Artifact represents an OCI artifact manifest. Artifacts contain typed blobs and can reference a subject manifest.

func NewArtifact 

func NewArtifact(desc ocispec.Descriptor, fetcher content.Fetcher, pusher content.Pusher, client ManifestClient) *Artifact

NewArtifact creates a new Artifact from a descriptor.

func NewArtifactFromManifestBytes 

func NewArtifactFromManifestBytes(desc ocispec.Descriptor, fetcher content.Fetcher, pusher content.Pusher, client ManifestClient, manifestBytes []byte) (*Artifact, error)

NewArtifactFromManifestBytes creates a new Artifact with a pre-loaded manifest. This avoids a redundant network fetch when the manifest bytes are already available (e.g., from type detection).

func (*Artifact) Annotations 

func (a *Artifact) Annotations() map[string]string

Annotations returns a copy of the annotations associated with this artifact. If the manifest is already loaded, annotations are read from the manifest body (where they are authoritative). Otherwise the descriptor annotations are used as a fallback. The returned map is safe to modify.

func (*Artifact) ArtifactType 

func (a *Artifact) ArtifactType(ctx context.Context) (string, error)

ArtifactType returns the artifact type (IANA media type).

func (*Artifact) Blobs 

func (a *Artifact) Blobs(ctx context.Context) ([]*Blob, error)

Blobs returns all blobs referenced by this artifact. The blobs are lazily loaded and cached.

func (*Artifact) Descriptor 

func (a *Artifact) Descriptor() ocispec.Descriptor

Descriptor returns the OCI descriptor for this artifact.

func (*Artifact) Digest 

func (a *Artifact) Digest() digest.Digest

Digest returns the digest of the artifact manifest.

func (*Artifact) Load 

func (a *Artifact) Load(ctx context.Context) error

Load eagerly loads the artifact manifest from storage.

func (*Artifact) MarshalJSON 

func (a *Artifact) MarshalJSON() ([]byte, error)

MarshalJSON marshals the artifact manifest to JSON. The manifest must have been loaded first via Load(ctx) or any method that accepts a context. Returns ErrNotLoaded if not yet loaded.

func (*Artifact) MediaType 

func (a *Artifact) MediaType() string

MediaType returns the media type of the artifact.

func (*Artifact) Predecessors 

func (a *Artifact) Predecessors(ctx context.Context) ([]Manifest, error)

Predecessors returns all manifests that reference this artifact.

func (*Artifact) Push 

func (a *Artifact) Push(ctx context.Context, reference string) error

Push pushes this artifact manifest to the target with the given reference.

func (*Artifact) SetSubject 

func (a *Artifact) SetSubject(subject Manifest)

SetSubject sets the subject manifest for this artifact.

func (*Artifact) Size 

func (a *Artifact) Size() int64

Size returns the size of the artifact manifest in bytes.

func (*Artifact) Subject 

func (a *Artifact) Subject(ctx context.Context) (Manifest, error)

Subject returns the subject manifest this artifact refers to. Returns nil if no subject is set.

type Blob 

type Blob struct {
	// contains filtered or unexported fields
}

Blob represents a binary content object (layer, config, arbitrary data). Blobs are immutable and content-addressable.

func NewBlob 

func NewBlob(desc ocispec.Descriptor, fetcher content.Fetcher, pusher content.Pusher) *Blob

NewBlob creates a new Blob from a descriptor. The content is not loaded until accessed via Read() or Bytes().

func NewBlobFromBytes 

func NewBlobFromBytes(mediaType string, data []byte, opts ...func(*Blob)) *Blob

NewBlobFromBytes creates a new Blob from raw bytes. The descriptor is computed from the content. Optional fetcher and pusher can be provided for storage operations.

func (*Blob) Annotations 

func (b *Blob) Annotations() map[string]string

Annotations returns a copy of the annotations associated with this blob. The returned map is safe to modify without affecting the blob.

func (*Blob) Bytes 

func (b *Blob) Bytes(ctx context.Context) ([]byte, error)

Bytes returns the blob content as a byte slice. The content is lazily loaded and cached for subsequent calls. On transient errors, the result is NOT cached, allowing retry. Use Read() for streaming large blobs to avoid memory pressure.

func (*Blob) Delete 

func (b *Blob) Delete(ctx context.Context) error

Delete removes this blob from storage. The pusher must implement content.Deleter.

func (*Blob) Descriptor 

func (b *Blob) Descriptor() ocispec.Descriptor

Descriptor returns the OCI descriptor for this blob.

func (*Blob) Digest 

func (b *Blob) Digest() digest.Digest

Digest returns the digest of the blob content.

func (*Blob) MediaType 

func (b *Blob) MediaType() string

MediaType returns the media type of the blob.

func (*Blob) Push 

func (b *Blob) Push(ctx context.Context) error

Push pushes this blob to the target storage.

func (*Blob) Read 

func (b *Blob) Read(ctx context.Context) (io.ReadCloser, error)

Read returns a ReadCloser for streaming the blob content. This is useful for large blobs that should not be loaded entirely into memory. The returned reader verifies the content digest on read. Call VerifyReader.Verify() after reading to confirm integrity, or use Bytes() which verifies automatically.

func (*Blob) Size 

func (b *Blob) Size() int64

Size returns the size of the blob in bytes.

func (*Blob) Verify 

func (b *Blob) Verify(ctx context.Context) error

Verify fetches the content and verifies it matches the descriptor's digest and size. This is useful for checking integrity without retaining the content in memory.

func (*Blob) WithAnnotation 

func (b *Blob) WithAnnotation(key, value string) *Blob

WithAnnotation returns a new Blob with the given annotation added. The original blob is not modified.

type Content 

type Content interface {
	// Descriptor returns the OCI descriptor for this content.
	Descriptor() ocispec.Descriptor

	// Digest returns the digest of the content.
	Digest() digest.Digest

	// MediaType returns the media type of the content.
	MediaType() string

	// Size returns the size of the content in bytes.
	Size() int64

	// Annotations returns the annotations associated with this content.
	Annotations() map[string]string
}

Content represents any OCI content that can be stored and retrieved. This is the base interface for all ORM models (Blob, Artifact, Image, Index).

type Image 

type Image struct {
	// contains filtered or unexported fields
}

Image represents an OCI or Docker image manifest. Images have a config and layers, and may support platform specification.

func NewImage 

func NewImage(desc ocispec.Descriptor, fetcher content.Fetcher, pusher content.Pusher, client ManifestClient) *Image

NewImage creates a new Image from a descriptor.

func NewImageFromManifestBytes 

func NewImageFromManifestBytes(desc ocispec.Descriptor, fetcher content.Fetcher, pusher content.Pusher, client ManifestClient, manifestBytes []byte) (*Image, error)

NewImageFromManifestBytes creates a new Image with a pre-loaded manifest. This avoids a redundant network fetch when the manifest bytes are already available (e.g., from type detection).

func (*Image) Annotations 

func (i *Image) Annotations() map[string]string

Annotations returns a copy of the annotations associated with this image. If the manifest is already loaded, annotations are read from the manifest body (where they are authoritative). Otherwise the descriptor annotations are used as a fallback. The returned map is safe to modify.

func (*Image) Config 

func (i *Image) Config(ctx context.Context) (*Blob, error)

Config returns the config blob for this image. The config is lazily loaded and cached.

func (*Image) Descriptor 

func (i *Image) Descriptor() ocispec.Descriptor

Descriptor returns the OCI descriptor for this image.

func (*Image) Digest 

func (i *Image) Digest() digest.Digest

Digest returns the digest of the image manifest.

func (*Image) Layers 

func (i *Image) Layers(ctx context.Context) ([]*Blob, error)

Layers returns all layer blobs for this image. The layers are lazily loaded and cached.

func (*Image) Load 

func (i *Image) Load(ctx context.Context) error

Load eagerly loads the image manifest from storage.

func (*Image) MarshalJSON 

func (i *Image) MarshalJSON() ([]byte, error)

MarshalJSON marshals the image manifest to JSON. The manifest must have been loaded first via Load(ctx) or any method that accepts a context. Returns ErrNotLoaded if not yet loaded.

func (*Image) MediaType 

func (i *Image) MediaType() string

MediaType returns the media type of the image.

func (*Image) Platform 

func (i *Image) Platform(ctx context.Context) (*ocispec.Platform, error)

Platform returns the platform specification for this image. Returns nil if no platform is specified.

func (*Image) Predecessors 

func (i *Image) Predecessors(ctx context.Context) ([]Manifest, error)

Predecessors returns all manifests that reference this image.

func (*Image) Push 

func (i *Image) Push(ctx context.Context, reference string) error

Push pushes this image manifest to the target with the given reference.

func (*Image) SetSubject 

func (i *Image) SetSubject(subject Manifest)

SetSubject sets the subject manifest for this image.

func (*Image) Size 

func (i *Image) Size() int64

Size returns the size of the image manifest in bytes.

func (*Image) Subject 

func (i *Image) Subject(ctx context.Context) (Manifest, error)

Subject returns the subject manifest this image refers to. Returns nil if no subject is set.

type Index 

type Index struct {
	// contains filtered or unexported fields
}

Index represents an OCI image index (manifest list). Indexes contain multiple manifests, typically for different platforms.

func NewIndex 

func NewIndex(desc ocispec.Descriptor, fetcher content.Fetcher, pusher content.Pusher, client ManifestClient) *Index

NewIndex creates a new Index from a descriptor.

func NewIndexFromManifestBytes 

func NewIndexFromManifestBytes(desc ocispec.Descriptor, fetcher content.Fetcher, pusher content.Pusher, client ManifestClient, indexBytes []byte) (*Index, error)

NewIndexFromManifestBytes creates a new Index with a pre-loaded manifest. This avoids a redundant network fetch when the manifest bytes are already available (e.g., from type detection).

func (*Index) Annotations 

func (idx *Index) Annotations() map[string]string

Annotations returns a copy of the annotations associated with this index. If the index manifest is already loaded, annotations are read from the manifest body (where they are authoritative). Otherwise the descriptor annotations are used as a fallback. The returned map is safe to modify.

func (*Index) Descriptor 

func (idx *Index) Descriptor() ocispec.Descriptor

Descriptor returns the OCI descriptor for this index.

func (*Index) Digest 

func (idx *Index) Digest() digest.Digest

Digest returns the digest of the index.

func (*Index) FilterByPlatform 

func (idx *Index) FilterByPlatform(ctx context.Context, target *ocispec.Platform) ([]Manifest, error)

FilterByPlatform returns manifests matching the given platform. Uses the library's internal/platform.Match which handles Architecture, OS, Variant, OSVersion, and OSFeatures comparison.

func (*Index) Load 

func (idx *Index) Load(ctx context.Context) error

Load eagerly loads the index from storage.

func (*Index) Manifests 

func (idx *Index) Manifests(ctx context.Context) ([]Manifest, error)

Manifests returns all manifests in this index. The manifests are lazily loaded and cached.

func (*Index) MarshalJSON 

func (idx *Index) MarshalJSON() ([]byte, error)

MarshalJSON marshals the index to JSON. The index must have been loaded first via Load(ctx) or any method that accepts a context. Returns ErrNotLoaded if not yet loaded.

func (*Index) MediaType 

func (idx *Index) MediaType() string

MediaType returns the media type of the index.

func (*Index) Predecessors 

func (idx *Index) Predecessors(ctx context.Context) ([]Manifest, error)

Predecessors returns all manifests that reference this index.

func (*Index) Push 

func (idx *Index) Push(ctx context.Context, reference string) error

Push pushes this index to the target with the given reference.

func (*Index) SetSubject 

func (idx *Index) SetSubject(subject Manifest)

SetSubject sets the subject manifest for this index.

func (*Index) Size 

func (idx *Index) Size() int64

Size returns the size of the index in bytes.

func (*Index) Subject 

func (idx *Index) Subject(ctx context.Context) (Manifest, error)

Subject returns the subject manifest this index refers to. Returns nil if no subject is set.

type Manifest 

type Manifest interface {
	Content

	// Load eagerly loads the manifest data from storage.
	// This must be called before MarshalJSON if the manifest was created
	// from a descriptor (lazy loading).
	Load(ctx context.Context) error

	// Subject returns the subject (parent) manifest this manifest refers to.
	// Returns nil if no subject is set.
	Subject(ctx context.Context) (Manifest, error)

	// SetSubject sets the subject (parent) manifest for this manifest.
	SetSubject(subject Manifest)

	// Predecessors returns all manifests that reference this manifest.
	// This is useful for finding referrers (signatures, SBOMs, etc.).
	Predecessors(ctx context.Context) ([]Manifest, error)

	// Push pushes this manifest to the target with the given reference.
	Push(ctx context.Context, reference string) error
}

Manifest represents content that is a manifest (Artifact, Image, or Index). Manifests can reference other content and have subjects.

type ManifestClient 

type ManifestClient interface {
	// FetchManifest fetches a manifest by descriptor.
	FetchManifest(ctx context.Context, desc ocispec.Descriptor) (Manifest, error)

	// FetchByReference fetches a manifest by reference (tag or digest string).
	FetchByReference(ctx context.Context, reference string) (Manifest, error)

	// FindPredecessors finds all manifests that reference the given content.
	FindPredecessors(ctx context.Context, content Content) ([]Manifest, error)

	// PushManifest pushes a manifest with a reference.
	PushManifest(ctx context.Context, manifest Manifest, reference string) error
}

ManifestClient provides operations for manifest relationships.

type ObjectsError 

type ObjectsError struct {
	Op     string        // Operation that failed (e.g., "load", "fetch_blobs").
	Digest digest.Digest // Digest of the content involved, if known.
	Err    error         // Underlying error.
}

ObjectsError provides structured error context for objects operations.

func (*ObjectsError) Error 

func (e *ObjectsError) Error() string

func (*ObjectsError) Unwrap 

func (e *ObjectsError) Unwrap() error

type Reference 

type Reference struct {
	// contains filtered or unexported fields
}

Reference represents a named reference to a manifest (tag or other reference). Reference is safe for concurrent use.

func NewReference 

func NewReference(name string, manifest Manifest, client ManifestClient) *Reference

NewReference creates a new Reference. If manifest is non-nil, it is pre-cached (Resolve will return it immediately).

func (*Reference) Manifest 

func (r *Reference) Manifest() (Manifest, bool)

Manifest returns the cached manifest if already resolved. Returns (manifest, true) if resolved, or (nil, false) if not yet resolved.

func (*Reference) Name 

func (r *Reference) Name() string

Name returns the reference name (e.g., tag name).

func (*Reference) Resolve 

func (r *Reference) Resolve(ctx context.Context) (Manifest, error)

Resolve resolves the reference to a manifest. If the manifest is not yet loaded, it will be fetched via the client. Concurrent calls are safe; only one fetch will occur.

func (*Reference) Tag 

func (r *Reference) Tag(ctx context.Context, manifest Manifest) error

Tag tags the given manifest with this reference name.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.