ocilayout

package
v0.0.15 Latest Latest
Warning

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

 Go to latest Published: Jun 1, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

README

ocilayout

Package ocilayout provides an oci.Interface implementation backed by an OCI Image Layout directory on disk.

Use it when you want registry-like reads and writes without running a registry server. It stores manifests in index.json, blobs under blobs/, and records named references with the standard org.opencontainers.image.ref.name annotation.

Shared Layout

New opens a single OCI layout directory that can hold multiple repositories. Missing layout files are not created when the registry is opened; write operations create oci-layout, index.json, and blob directories lazily.

package main

import (
	"context"
	"fmt"

	"github.com/docker/oci"
	"github.com/docker/oci/ocilayout"
)

func main() {
	reg, err := ocilayout.New("./layout", &ocilayout.Options{})
	if err != nil {
		panic(err)
	}

	tags, err := oci.All(reg.Tags(context.Background(), "example/app", nil))
	if err != nil {
		panic(err)
	}
	fmt.Println(tags)
}

When reading existing layouts that use tag-only ref.name annotations, set DefaultRepo so those entries can be associated with a repository.

reg, err := ocilayout.New("./layout", &ocilayout.Options{
	DefaultRepo: "example/app",
})

Per-Repository Layouts

NewPerRepository stores each repository in its own nested OCI layout under the given directory. For repository example/app, the underlying layout lives at <dir>/example/app.

reg, err := ocilayout.NewPerRepository("./layouts", &ocilayout.PerRepoOptions{})
if err != nil {
	panic(err)
}

The per-repository constructor has its own options type so its API can evolve independently from New.

Finding Layouts From Paths

FindLayout splits a user-supplied path into the base directory for New and the image reference suffix. It first looks for oci-layout marker files in path prefixes and uses the deepest matching layout. If no marker exists, it falls back to treating the last path component as the reference.

baseDir, ref, err := ocilayout.FindLayout("./foo/bar:baz")
// baseDir == "./foo"
// ref.Repository == "bar"
// ref.Tag == "baz"

baseDir, ref, err := ocilayout.FindLayout("./one/two/three/four:tag")
// If ./one/two/oci-layout exists:
// baseDir == "./one/two"
// ref.Repository == "three/four"
// ref.Tag == "tag"

References may include tags, digests, or both:

baseDir, ref, err := ocilayout.FindLayout("./layout/repo:tag@sha256:...")

Documentation

Overview

Package ocilayout provides an oci.Interface implementation backed by an OCI Image Layout directory.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FindLayout 

func FindLayout(path string) (baseDir string, ref ociref.Reference, err error)

FindLayout splits path into an OCI image layout directory and image reference.

It first looks for OCI layout marker files in directory prefixes of path. If one or more marker files are found, the deepest directory whose remaining suffix parses as a reference is used as the base directory. If no marker file matches, FindLayout falls back to treating the last path component as the reference and the preceding path as the base directory.

func NewPerRepository 

func NewPerRepository(dir string, _ *PerRepoOptions) (oci.Interface, error)

NewPerRepository opens an OCI Image Layout registry that stores each repository in a separate OCI layout under dir.

Types

type Options 

type Options struct {
	// DefaultRepo is used when reading layout entries whose
	// org.opencontainers.image.ref.name annotation is empty or tag-only.
	DefaultRepo string
}

Options holds configuration for opening a layout registry.

type PerRepoOptions 

type PerRepoOptions struct{}

PerRepoOptions holds configuration for opening a per-repository layout registry.

type Registry 

type Registry struct {
	*oci.Funcs
	// contains filtered or unexported fields
}

Registry is an OCI Image Layout backed implementation of oci.Interface.

func New 

func New(dir string, opts *Options) (*Registry, error)

New opens an OCI Image Layout registry rooted at dir.

Missing layout files are not created by New. Write operations create the required layout files and directories lazily.

func (*Registry) DeleteBlob 

func (r *Registry) DeleteBlob(ctx context.Context, repo string, digest oci.Digest) error

DeleteBlob deletes the blob with the given digest from the named repository.

func (*Registry) DeleteManifest 

func (r *Registry) DeleteManifest(ctx context.Context, repo string, digest oci.Digest) error

DeleteManifest deletes top-level index entries for the manifest digest.

func (*Registry) DeleteTag 

func (r *Registry) DeleteTag(ctx context.Context, repo string, tagName string) error

DeleteTag deletes the given tag from the named repository.

func (*Registry) GetBlob 

func (r *Registry) GetBlob(ctx context.Context, repo string, digest oci.Digest) (oci.BlobReader, error)

GetBlob returns the content of the blob with the given digest.

func (*Registry) GetBlobRange 

func (r *Registry) GetBlobRange(ctx context.Context, repo string, digest oci.Digest, offset0, offset1 int64) (oci.BlobReader, error)

GetBlobRange returns a range of bytes from the blob with the given digest.

func (*Registry) GetManifest 

func (r *Registry) GetManifest(ctx context.Context, repo string, digest oci.Digest) (oci.BlobReader, error)

GetManifest returns the content of the manifest with the given digest.

func (*Registry) GetTag 

func (r *Registry) GetTag(ctx context.Context, repo string, tagName string) (oci.BlobReader, error)

GetTag returns the content of the manifest with the given tag.

func (*Registry) MountBlob 

func (r *Registry) MountBlob(ctx context.Context, fromRepo, toRepo string, dig oci.Digest) (oci.Descriptor, error)

MountBlob makes a blob from one repository available in another.

func (*Registry) PushBlob 

func (r *Registry) PushBlob(ctx context.Context, repo string, desc oci.Descriptor, content io.Reader) (oci.Descriptor, error)

PushBlob pushes a blob described by desc to the given repository.

func (*Registry) PushBlobChunked 

func (r *Registry) PushBlobChunked(ctx context.Context, repo string, chunkSize int) (oci.BlobWriter, error)

PushBlobChunked starts a chunked blob upload to the given repository.

func (*Registry) PushBlobChunkedResume 

func (r *Registry) PushBlobChunkedResume(ctx context.Context, repo string, id string, offset int64, chunkSize int) (oci.BlobWriter, error)

PushBlobChunkedResume resumes a previous chunked blob upload.

func (*Registry) PushManifest 

func (r *Registry) PushManifest(ctx context.Context, repo string, data []byte, mediaType string, params *oci.PushManifestParameters) (oci.Descriptor, error)

PushManifest pushes a manifest to the named repository, optionally tagging it.

func (*Registry) Referrers 

func (r *Registry) Referrers(ctx context.Context, repo string, digest oci.Digest, params *oci.ReferrersParameters) iter.Seq2[oci.Descriptor, error]

Referrers returns descriptors that refer to the given digest.

func (*Registry) Repositories 

func (r *Registry) Repositories(ctx context.Context, startAfter string) iter.Seq2[string, error]

Repositories returns an iterator over repository names in the layout registry.

func (*Registry) ResolveBlob 

func (r *Registry) ResolveBlob(ctx context.Context, repo string, digest oci.Digest) (oci.Descriptor, error)

ResolveBlob returns the descriptor for the blob with the given digest.

func (*Registry) ResolveManifest 

func (r *Registry) ResolveManifest(ctx context.Context, repo string, digest oci.Digest) (oci.Descriptor, error)

ResolveManifest returns the descriptor for the manifest with the given digest.

func (*Registry) ResolveTag 

func (r *Registry) ResolveTag(ctx context.Context, repo string, tagName string) (oci.Descriptor, error)

ResolveTag returns the descriptor for the manifest with the given tag.

func (*Registry) Tags 

func (r *Registry) Tags(ctx context.Context, repo string, params *oci.TagsParameters) iter.Seq2[string, error]

Tags returns an iterator over tags in the named repository.

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.