registry

README

registry-client

A Docker Registry client.

Usage

package main

import (
	"fmt"
	"log"

	"github.com/imagespy/registry-client"
)

func main() {
	reg := &registry.Registry{
		Authenticator: registry.NewTokenAuthenticator(),
		Client:        registry.DefaultClient(),
		Domain:        "docker.io",
	}

	repo, err := reg.RepositoryFromString("golang")
	if err != nil {
		log.Fatal(err)
	}

	img, err := repo.Images().GetByTag("1.12.0")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(img.Digest)
}

Documentation

Index

• Variables
• func DefaultClient() *http.Client
• func ParseImageName(imageName string) (domain, path, tag, digest string, err error)
• type Authenticator
  • func NewBasicAuthenticator(username, password string) Authenticator
  • func NewNullAuthenticator() Authenticator
  • func NewTokenAuthenticator() Authenticator
• type Image
• type ImageService
  • func (i *ImageService) DeleteByDigest(digest string) error
  • func (i *ImageService) GetByDigest(digest string) (Image, error)
  • func (i *ImageService) GetByTag(tag string) (Image, error)
• type ManifestService
  • func (p *ManifestService) Get(digest string) (schema2.Manifest, error)
• type Options
• type Platform
• type Registry
  • func New(o Options) *Registry
  • func (r *Registry) Repositories() ([]*Repository, error)
  • func (r *Registry) Repository(name string) *Repository
  • func (r *Registry) RepositoryFromString(name string) (*Repository, error)
• type Repository
  • func (r *Repository) Domain() string
  • func (r *Repository) Images() *ImageService
  • func (r *Repository) Manifests() *ManifestService
  • func (r *Repository) Name() string
  • func (r *Repository) Registry() *Registry
  • func (r *Repository) Tags() *TagService
• type Requester
  • func (r *Requester) GetByte(req *http.Request) ([]byte, http.Header, error)
  • func (r *Requester) GetJSON(req *http.Request, out interface{}) (http.Header, error)
  • func (r *Requester) NewRequest(method, path string, body io.Reader) (*http.Request, error)
  • func (r *Requester) SendRequest(req *http.Request) (*http.Response, error)
• type TagService
  • func (r *TagService) GetAll() ([]string, error)

Examples

• Registry

Variables

var (
	// ErrAuthTokenInvalid indicates the the registry issued a token but revoked it.
	ErrAuthTokenInvalid = fmt.Errorf("A token was issued but is not longer valid")
	// ErrAuthTokenNoBearer indicates that a registry did not return the expected authenticaton header.
	ErrAuthTokenNoBearer = fmt.Errorf("Www-authenticate header value does not start with 'Bearer'")
)

var (
	// ErrResourceNotFound indicates that an image is not available in the registry.
	ErrResourceNotFound = fmt.Errorf("registry returned status 404 NOT FOUND")
	// ErrSchemaV1NotSupported indicates that this library does not support registry v1
	ErrSchemaV1NotSupported = fmt.Errorf("registry schema v1 is not supported by this library")
	// ErrSchemaUnknown indicates that the registry returned an unknown manifest schema
	ErrSchemaUnknown = fmt.Errorf("registry returned an unknown manifest schema")
)

Functions

func DefaultClient

func DefaultClient() *http.Client

DefaultClient returns a http.Client with a reasonable timeout.

func ParseImageName

func ParseImageName(imageName string) (domain, path, tag, digest string, err error)

ParseImageName parses the name of an image and reurns its parts.

Types

type Authenticator

type Authenticator interface {
	// HandleRequest is called each time before a request is sent to the registry.
	HandleRequest(r *http.Request) error
	// HandleResponse is called each time after a response is received from the registry.
	HandleResponse(resp *http.Response) (*http.Response, bool, error)
}

A Authenticator is responsible for authenticating against the registry.

func NewBasicAuthenticator

func NewBasicAuthenticator(username, password string) Authenticator

NewBasicAuthenticator returns an Authenticator that handles basic authentication.

func NewNullAuthenticator

func NewNullAuthenticator() Authenticator

NewNullAuthenticator returns an Authenticator that does not modify the request or the response. It is used as a fallback if not Authenticator is set.

func NewTokenAuthenticator

func NewTokenAuthenticator() Authenticator

NewTokenAuthenticator returns an Authenticator that handles authentication as described in https://docs.docker.com/registry/spec/auth/.

type Image

type Image struct {
	Digest     string
	Domain     string
	Platforms  []Platform
	Repository string
	Tag        string
}

Image is an identifiable resource in a repository. An Image can be identified by a tag or a digest. A tag (e.g. "latest") can move between images. A digest is unique within the repository and does not change unless teh image is deleted.

type ImageService

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

ImageService exposes images.

func (*ImageService) DeleteByDigest

func (i *ImageService) DeleteByDigest(digest string) error

DeleteByDigest deletes an image. It uses the digest of an image to reference it.

func (*ImageService) GetByDigest

func (i *ImageService) GetByDigest(digest string) (Image, error)

GetByDigest queries the repository for an image identified by its digest. The `Tag` field of an image returned by this method always is an empty string.

func (*ImageService) GetByTag

func (i *ImageService) GetByTag(tag string) (Image, error)

GetByTag queries the repository for an image identified by its tag.

type ManifestService

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

ManifestService exposes the manifest of an image in a repository.

func (*ManifestService) Get

func (p *ManifestService) Get(digest string) (schema2.Manifest, error)

Get returns the manifest schema v2 of an image.

type Options

type Options struct {
	Authenticator Authenticator
	Client        *http.Client
	Domain        string
	Protocol      string
	Proxy         string
}

Options are used to create a new Registry.

type Platform

type Platform struct {
	Architecture string
	Digest       string
	Features     []string
	MediaType    string
	OS           string
	OSFeatures   []string
	OSVersion    string
	Size         int
	Variant      string
}

Platform is the platform on which an image can run.

type Registry

type Registry struct {
	Requester *Requester
}

Registry exposes the repositories in a registry.

Example

// Query an image in the Docker Hub.
reg := New(Options{
	Authenticator: NewTokenAuthenticator(),
	Client:        DefaultClient(),
	Domain:        "docker.io",
})
repo, err := reg.RepositoryFromString("golang")
if err != nil {
	log.Fatal(err)
}

img, err := repo.Images().GetByTag("1.12.0")
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Image Digest of Tag %s: %s\n", img.Tag, img.Digest)
for _, p := range img.Platforms {
	fmt.Printf("Platform OS %s Architecture %s", p.OS, p.Architecture)
	m, err := repo.Manifests().Get(p.Digest)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Manifest of type %s", m.MediaType)
}

func New

func New(o Options) *Registry

New returns a new Registry.

func (*Registry) Repositories

func (r *Registry) Repositories() ([]*Repository, error)

Repositories queries the registry and returns all available repositories.

func (*Registry) Repository

func (r *Registry) Repository(name string) *Repository

Repository returns one repository in the registry. It does not check if the repository actually exists in the registry.

func (*Registry) RepositoryFromString

func (r *Registry) RepositoryFromString(name string) (*Repository, error)

RepositoryFromString is a convenience function to create a repository from an image as used in `docker pull`.

type Repository

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

Repository exposes the images in a repository in a registry.

func (*Repository) Domain

func (r *Repository) Domain() string

Domain returns the domain of the registry that the repository belongs to.

func (*Repository) Images

func (r *Repository) Images() *ImageService

Images returns an ImageService.

func (*Repository) Manifests

func (r *Repository) Manifests() *ManifestService

Manifests returns a ManifestService.

func (*Repository) Name

func (r *Repository) Name() string

Name returns the name of the repository.

func (*Repository) Registry

func (r *Repository) Registry() *Registry

Registry returns the registry of the repository.

func (*Repository) Tags

func (r *Repository) Tags() *TagService

Tags returns a TagService.

type Requester

type Requester struct {
	Auth     Authenticator
	Client   *http.Client
	Domain   string
	Protocol string
	Proxy    string
}

Requester handles all communication with the Docker registry.

func (*Requester) GetByte

func (r *Requester) GetByte(req *http.Request) ([]byte, http.Header, error)

GetByte sends a request and returns the payload of the response as bytes.

func (*Requester) GetJSON

func (r *Requester) GetJSON(req *http.Request, out interface{}) (http.Header, error)

GetJSON sends a request and returns the payload of the response decoded from JSON.

func (*Requester) NewRequest

func (r *Requester) NewRequest(method, path string, body io.Reader) (*http.Request, error)

NewRequest creates a new request to send to the registry.

func (*Requester) SendRequest

func (r *Requester) SendRequest(req *http.Request) (*http.Response, error)

SendRequest sends a request to the registry. It also handles authentication.

type TagService

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

TagService exposes tags in a repository.

func (*TagService) GetAll

func (r *TagService) GetAll() ([]string, error)

GetAll returns all tags in the repository. Note that this method does not implement pagination as described in the official documentation of the Docker Registry API V2 as the spec has not been implemented in the registry. See https://github.com/docker/distribution/issues/1936 for more information.