modregistry

Documentation

Overview

Package modregistry provides functionality for reading and writing CUE modules from an OCI registry.

WARNING: THIS PACKAGE IS EXPERIMENTAL. ITS API MAY CHANGE AT ANY TIME.

Index

• Variables
• type Client
  • func NewClient(registry ociregistry.Interface) *Client
  • func NewClientWithResolver(resolver Resolver) *Client
  • func (c *Client) GetModule(ctx context.Context, m module.Version) (*Module, error)
  • func (c *Client) GetModuleWithManifest(ctx context.Context, m module.Version, contents []byte, mediaType string) (*Module, error)
  • func (c *Client) ModuleVersions(ctx context.Context, m string) ([]string, error)
  • func (c *Client) PutModule(ctx context.Context, m module.Version, r io.ReaderAt, size int64) error
  • func (c *Client) PutModuleWithMetadata(ctx context.Context, m module.Version, r io.ReaderAt, size int64, ...) error
• type Metadata
• type Module
  • func (m *Module) GetZip(ctx context.Context) (io.ReadCloser, error)
  • func (m *Module) ManifestDigest() ociregistry.Digest
  • func (m *Module) Metadata() (*Metadata, error)
  • func (m *Module) ModuleFile(ctx context.Context) ([]byte, error)
  • func (m *Module) Version() module.Version
• type RegistryLocation
• type Resolver

Variables

var ErrNotFound = fmt.Errorf("module not found")

var ErrRegistryNotFound = fmt.Errorf("no registry configured for module")

ErrRegistryNotFound is returned by [Resolver.ResolveToRegistry] when there is no registry configured for a module.

Types

type Client

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

Client represents a OCI-registry-backed client that provides a store for CUE modules.

func NewClient

func NewClient(registry ociregistry.Interface) *Client

NewClient returns a new client that talks to the registry at the given hostname.

func NewClientWithResolver

func NewClientWithResolver(resolver Resolver) *Client

NewClientWithResolver returns a new client that uses the given resolver to decide which registries to fetch from or push to.

func (*Client) GetModule

func (c *Client) GetModule(ctx context.Context, m module.Version) (*Module, error)

GetModule returns the module instance for the given version. It returns an error that satisfies errors.Is(ErrNotFound) if the module is not present in the store at this version.

func (*Client) GetModuleWithManifest

func (c *Client) GetModuleWithManifest(ctx context.Context, m module.Version, contents []byte, mediaType string) (*Module, error)

GetModuleWithManifest returns a module instance given the top level manifest contents, without querying its tag. It assumes that the module will be tagged with the given version.

func (*Client) ModuleVersions

func (c *Client) ModuleVersions(ctx context.Context, m string) ([]string, error)

ModuleVersions returns all the versions for the module with the given path sorted in semver order. If m has a major version suffix, only versions with that major version will be returned.

func (*Client) PutModule

func (c *Client) PutModule(ctx context.Context, m module.Version, r io.ReaderAt, size int64) error

PutModule puts a module whose contents are held as a zip archive inside f. It assumes all the module dependencies are correctly resolved and present inside the cue.mod/module.cue file.

func (*Client) PutModuleWithMetadata

func (c *Client) PutModuleWithMetadata(ctx context.Context, m module.Version, r io.ReaderAt, size int64, meta *Metadata) error

PutModuleWithMetadata is like Client.PutModule except that it also includes the given metadata inside the module's manifest. If meta is nil, no metadata will be included, otherwise all fields in meta must be valid and non-empty.

type Metadata

type Metadata struct {
	VCSType       string    `json:"org.cuelang.vcs-type"`
	VCSCommit     string    `json:"org.cuelang.vcs-commit"`
	VCSCommitTime time.Time `json:"org.cuelang.vcs-commit-time"`
}

Metadata holds extra information that can be associated with a module. It is stored in the module's manifest inside the annotations field. All fields must JSON-encode to strings.

type Module

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

Module represents a CUE module instance.

func (*Module) GetZip

func (m *Module) GetZip(ctx context.Context) (io.ReadCloser, error)

GetZip returns a reader that can be used to read the contents of the zip archive containing the module files. The reader should be closed after use, and the contents should not be assumed to be correct until the close error has been checked.

func (*Module) ManifestDigest

func (m *Module) ManifestDigest() ociregistry.Digest

ManifestDigest returns the digest of the manifest representing the module.

func (*Module) Metadata

func (m *Module) Metadata() (*Metadata, error)

Metadata returns the metadata associated with the module. If there is none, it returns (nil, nil).

func (*Module) ModuleFile

func (m *Module) ModuleFile(ctx context.Context) ([]byte, error)

ModuleFile returns the contents of the cue.mod/module.cue file.

func (*Module) Version

func (m *Module) Version() module.Version

type RegistryLocation

type RegistryLocation struct {
	// Registry holds the registry to use to access the module.
	Registry ociregistry.Interface
	// Repository holds the repository where the module is located.
	Repository string
	// Tag holds the tag for the module version. If an empty version
	// was passed to Resolve, it holds the prefix shared by all
	// version tags for the module.
	Tag string
}

RegistryLocation holds a registry and a location within it that a specific module (or set of versions for a module) will be stored.

type Resolver

type Resolver interface {
	// ResolveToRegistry resolves a base module path (without a version)
	// and optional version to the location for that path.
	//
	// If the version is empty, the Tag in the returned Location
	// will hold the prefix that all versions of the module in its
	// repository have. That prefix will be followed by the version
	// itself.
	//
	// If there is no registry configured for the module, it returns
	// an [ErrRegistryNotFound] error.
	ResolveToRegistry(mpath, vers string) (RegistryLocation, error)
}

Resolver resolves module paths to a registry and a location within that registry.