Help us shape the future of Go! Take the 2026 Go Developer Survey

ocistore

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

README

ocistore

github.com/sysson/ocistore is a Go library for storing OCI registry content and metadata. ocistore.Store implements github.com/docker/oci.Interface, with pluggable blob and metadata storage. It is a library, not an HTTP registry server.

Getting started

Requires Go 1.27.1 or newer. Add the module with go get github.com/sysson/ocistore.

This example uses a local directory for blobs and a bbolt database for metadata:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/sysson/ocistore"
	"github.com/sysson/ocistore/blobstore/fileblob"
	"github.com/sysson/ocistore/kv/boltkv"
	"github.com/sysson/ocistore/kvmeta"
)

func main() {
	ctx := context.Background()
	content, err := fileblob.Open(ctx, "/var/lib/ocistore/blobs")
	if err != nil {
		log.Fatal(err)
	}
	defer content.Close()

	metadata, err := kvmeta.Open(ctx, boltkv.Config{Path: "/var/lib/ocistore/metadata.db"})
	if err != nil {
		log.Fatal(err)
	}
	defer metadata.Close()

	store, err := ocistore.New(content, metadata)
	if err != nil {
		log.Fatal(err)
	}
	repositories, err := store.Index().Repositories(ctx, "", 100)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(repositories)
}

Use absolute paths for the local drivers. bbolt holds an exclusive file lock, so use a remote KV driver when multiple processes need to share metadata.

For remote metadata, etcdkv.Config.Prefix defaults to /ocistore; natskv.Options defaults to stream OCISTORE_METADATA and subject ocistore.metadata. Set these fields to choose a different namespace.

Serve a registry

The store implements oci.Interface, so github.com/docker/oci/ociserver can expose it as an OCI distribution registry. After creating store in the example above, replace the repository listing with:

registry, err := ociserver.New(store, nil)
if err != nil {
	log.Fatal(err)
}
log.Fatal(http.ListenAndServe(":5000", registry))

Add "net/http" and "github.com/docker/oci/ociserver" to the imports. The server handles OCI registry requests under /v2/. ListenAndServe uses plain HTTP; configure TLS and authentication (for example, via ociserver.ServerConfig.AuthMiddleware) before exposing the registry beyond a trusted local environment.

Packages

  • ocistore: OCI store, read-only metadata Index, and cleanup/garbage-collection methods.
  • backend: content and metadata store interfaces.
  • blobstore: blob storage via Go CDK, with fileblob, memblob, s3blob, gcsblob, and azureblob drivers.
  • kv: transactional key/value storage, with boltkv, memkv, etcdkv, and natskv drivers; remotekv provides remote KV support.
  • kvmeta: indexed metadata storage over a kv.Store.
  • query package guide: read-only GraphQL queries over store.Index(), with in-process and HTTP examples.

Call store.CollectGarbage(ctx) to remove unreferenced content after deletions. With the bundled Go CDK blobstore, it also scans stored blobs for objects left behind by interrupted writes; custom content backends can support this by implementing backend.ContentLister. Scanning the full bucket can be expensive on large stores.

store.CleanupExpiredUploads(ctx, cutoff) and store.CleanupExpiredReservations(ctx, cutoff) clear abandoned metadata and uploads. For a Go CDK blobstore, content.CleanupStaged(ctx, cutoff) removes pending/ objects from interrupted writes. Choose cutoffs older than any operation that may still be active, and invoke these methods as appropriate for your deployment; no background cleanup is started automatically.

Manifest parsers

ocistore.New accepts optional ocistore.WithManifestParser handlers. A handler matches both manifest media type and artifact type, then returns normalized ManifestMetadata: blob dependencies, child manifests, subject, annotations, and optional JSON Details. Blob dependencies are validated and indexed for garbage collection; details are available from GraphQL as the Manifest.details JSON scalar. Unhandled formats use the generic parser for common OCI fields such as blobs, manifests, and subject. Missing child manifests are rejected by default; add ocistore.WithAllowMissingManifestChildren() for partial pulls. Image config/history remain available through the image-specific imageConfig field. GraphQL manifest resolves by digest or tag; image remains as a compatibility alias.

Documentation

Index

Constants

View Source 
const (

	// MaxImageConfigSize bounds how much of an image config Index.ImageConfig reads.
	MaxImageConfigSize = 4 << 20
)

Variables

This section is empty.

Functions

func IsImageConfig 

func IsImageConfig(mediaType string) bool

Types

type ClosureEntry 

type ClosureEntry struct {
	Descriptor oci.Descriptor
	Role       ClosureRole
	// RetainedInRepository is true if removing the closure from its
	// repository must keep the digest there: a manifest in the repository
	// outside the closure references it, or it is a tagged non-root manifest.
	RetainedInRepository bool
	// Shared is true if the content outlives removal of the closure from its
	// repository.
	Shared bool
	// SharedWith are the manifests outside the closure referencing the digest.
	SharedWith []backend.Dependent
	// Locations are every repository holding the digest.
	Locations []backend.Location
}

ClosureEntry is a digest in a manifest closure, classified against everything outside the closure.

type ClosureRole 

type ClosureRole string

ClosureRole is how content takes part in a manifest closure. 

const (
	RoleManifest  ClosureRole = "MANIFEST"
	RoleConfig    ClosureRole = "CONFIG"
	RoleLayer     ClosureRole = "LAYER"
	RoleReference ClosureRole = "REFERENCE"
)

type Index 

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

Index is the typed, read-only view of a Store's metadata indexes. Results are snapshots: they never authorize deletion, which garbage collection re-checks itself.

func (*Index) Blobs 

func (x *Index) Blobs(ctx context.Context, repository string, after oci.Digest, limit int) ([]backend.BlobRecord, error)

func (*Index) Closure 

func (x *Index) Closure(ctx context.Context, repository string, digest oci.Digest) ([]ClosureEntry, error)

Closure walks the manifest digest names and everything it transitively references in repository, root first. Child manifests absent from the repository are skipped.

func (*Index) Dependents 

func (x *Index) Dependents(ctx context.Context, digest oci.Digest, limit int) ([]backend.Dependent, error)

func (*Index) ImageConfig 

func (x *Index) ImageConfig(ctx context.Context, config oci.Descriptor) ([]byte, error)

ImageConfig returns the raw image config config describes, or nil when it is not an image config.

func (*Index) Locations 

func (x *Index) Locations(ctx context.Context, digest oci.Digest) ([]backend.Location, error)

func (*Index) Manifest 

func (x *Index) Manifest(ctx context.Context, repository string, digest oci.Digest) (backend.ManifestRecord, error)

func (*Index) Manifests 

func (x *Index) Manifests(ctx context.Context, repository string, after oci.Digest, limit int) ([]backend.ManifestRecord, error)

func (*Index) Referrers 

func (x *Index) Referrers(ctx context.Context, repository string, digest oci.Digest, artifactType, after string, limit int) ([]oci.Descriptor, error)

func (*Index) Repositories 

func (x *Index) Repositories(ctx context.Context, after string, limit int) ([]string, error)

func (*Index) Reserved 

func (x *Index) Reserved(ctx context.Context, digest oci.Digest) (bool, error)

func (*Index) ResolveTag 

func (x *Index) ResolveTag(ctx context.Context, repository, tag string) (oci.Descriptor, error)

func (*Index) TagRecords 

func (x *Index) TagRecords(ctx context.Context, repository, after string, limit int) ([]backend.TagRecord, error)

type ManifestMetadata added in v1.2.0 

type ManifestMetadata struct {
	ArtifactType string
	Subject      *oci.Digest
	Annotations  map[string]string
	Config       *oci.Descriptor
	Layers       []oci.Descriptor
	Manifests    []oci.Descriptor
	Dependencies []oci.Descriptor
	Details      json.RawMessage
}

ManifestMetadata is the normalized metadata a parser extracts from a manifest. Dependencies are blob descriptors; Manifests are child manifests. Config and Layers retain the image-specific projections used by existing registry and query APIs.

type ManifestParser added in v1.2.0 

type ManifestParser interface {
	Supports(mediaType, artifactType string) bool
	ParseManifest(mediaType string, content []byte) (ManifestMetadata, error)
}

ManifestParser handles a manifest format identified by its media type and, when present, artifact type.

type Metadata 

type Metadata interface {
	backend.MetadataStore
	backend.MetadataQuerier
}

Metadata is a metadata store together with the indexes it maintains.

type Option added in v1.2.0 

type Option func(*storeOptions) error

Option configures a Store.

func WithAllowMissingManifestChildren added in v1.2.0 

func WithAllowMissingManifestChildren() Option

WithAllowMissingManifestChildren allows a manifest to reference child manifests that are not present in the same repository. Present children must still match their descriptor. This is useful for partial index pulls.

func WithManifestParser added in v1.2.0 

func WithManifestParser(parser ManifestParser) Option

WithManifestParser registers a parser for additional manifest formats. When multiple registered parsers support the same manifest, the push fails rather than selecting one ambiguously.

type Store 

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

func New 

func New(content backend.ContentStore, metadata Metadata, options ...Option) (*Store, error)

func (*Store) CleanupExpiredReservations 

func (r *Store) CleanupExpiredReservations(ctx context.Context, cutoff time.Time) error

func (*Store) CleanupExpiredUploads 

func (r *Store) CleanupExpiredUploads(ctx context.Context, cutoff time.Time) error

func (*Store) CollectGarbage 

func (r *Store) CollectGarbage(ctx context.Context) error

func (*Store) Index 

func (r *Store) Index() *Index

Index returns the typed metadata view of the store.

Source Files

View all Source files

Directories

Path Synopsis
Package backend defines the storage and metadata contracts used by the standalone registry implementation.
 Package backend defines the storage and metadata contracts used by the standalone registry implementation.
azureblob
fileblob
gcsblob
memblob
s3blob
kv
Package kv defines the ordered, transactional key-value contract that registry metadata is stored in.
 Package kv defines the ordered, transactional key-value contract that registry metadata is stored in.
boltkv
Package boltkv is a kv.Store backed by a local bbolt database.
 Package boltkv is a kv.Store backed by a local bbolt database.
etcdkv
Package etcdkv is a kv.Store backed by etcd.
 Package etcdkv is a kv.Store backed by etcd.
kvtest
Package kvtest is a conformance suite every kv.Store driver must pass.
 Package kvtest is a conformance suite every kv.Store driver must pass.
memkv
Package memkv is an in-process kv.Store.
 Package memkv is an in-process kv.Store.
natskv
Package natskv is a kv.Store backed by a NATS JetStream stream.
 Package natskv is a kv.Store backed by a NATS JetStream stream.
remotekv
Package remotekv turns a networked key-value service with an atomic, revision-guarded multi-key commit into a serializable kv.Store.
 Package remotekv turns a networked key-value service with an atomic, revision-guarded multi-key commit into a serializable kv.Store.
Package kvmeta implements backend.MetadataStore and backend.MetadataQuerier over any kv.Store.
 Package kvmeta implements backend.MetadataStore and backend.MetadataQuerier over any kv.Store.
Package query is ocistore's GraphQL metadata query layer.
 Package query is ocistore's GraphQL metadata query layer.

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.