bufremoteplugindocker

Documentation

Overview

Package bufremoteplugindocker contains utilities for building Buf plugins using the Docker API.

Index

• Constants
• type Client
  • func NewClient(logger *slog.Logger, cliVersion string, options ...ClientOption) (Client, error)
• type ClientOption
  • func WithHost(host string) ClientOption
  • func WithVersion(version string) ClientOption
• type DeleteResponse
• type InspectResponse
• type LoadResponse
• type PushResponse
• type RegistryAuthConfig
  • func (r *RegistryAuthConfig) ToHeader() (string, error)
• type TagResponse

Constants

const (
	// Setting this value on the buf docker client allows us to propagate a custom
	// value to the OCI registry. This is a useful property that enables registries
	// to differentiate between the buf cli vs other tools like docker cli.
	// Note, this does not override the final User-Agent entirely, but instead adds
	// the value to the final outgoing User-Agent value in the form: [docker client's UA] UpstreamClient(buf-cli-1.11.0)
	//
	// Example: User-Agent = [docker/20.10.21 go/go1.18.7 git-commit/3056208 kernel/5.15.49-linuxkit os/linux arch/arm64 UpstreamClient(buf-cli-1.11.0)]
	BufUpstreamClientUserAgentPrefix = "buf-cli-"
)

const ImagePath = "image.tar"

ImagePath is the default location for the Docker image archive in a plugin zip file.

Types

type Client

type Client interface {
	// Load imports a Docker image into the local Docker Engine.
	Load(ctx context.Context, image io.Reader) (*LoadResponse, error)
	// Push the Docker image to the remote registry.
	Push(ctx context.Context, image string, auth *RegistryAuthConfig) (*PushResponse, error)
	// Delete removes the Docker image from local Docker Engine.
	Delete(ctx context.Context, image string) (*DeleteResponse, error)
	// Tag creates a Docker image tag from an existing image and plugin config.
	Tag(ctx context.Context, image string, config *bufremotepluginconfig.Config) (*TagResponse, error)
	// Inspect inspects an image and returns the image id.
	Inspect(ctx context.Context, image string) (*InspectResponse, error)
	// Close releases any resources used by the underlying Docker client.
	Close() error
}

Client is a small abstraction over a Docker API client, providing the basic APIs we need to build plugins. It ensures that we pass the appropriate parameters to build images (i.e. platform 'linux/amd64').

func NewClient

func NewClient(logger *slog.Logger, cliVersion string, options ...ClientOption) (Client, error)

NewClient creates a new Client to use to build Docker plugins.

type ClientOption

type ClientOption func(options *clientOptions)

ClientOption defines options for the NewClient call to customize the underlying Docker client.

func WithHost

func WithHost(host string) ClientOption

WithHost allows specifying a Docker engine host to connect to (instead of the default lookup using DOCKER_HOST env var). This makes it suitable for use by parallel tests.

func WithVersion

func WithVersion(version string) ClientOption

WithVersion allows specifying a Docker API client version instead of using the default version negotiation algorithm. This allows tests to implement the Docker engine API using stable URLs.

type DeleteResponse

type DeleteResponse struct{}

DeleteResponse is a placeholder for data to be returned from a successful image delete call.

type InspectResponse

type InspectResponse struct {
	// ImageID contains the Docker image's ID.
	ImageID string
}

InspectResponse returns the image id for a given image.

type LoadResponse

type LoadResponse struct {
	// ImageID specifies the Docker image id in the format <hash_algorithm>:<hash>.
	// Example: sha256:65001659f150f085e0b37b697a465a95cbfd885d9315b61960883b9ac588744e
	ImageID string
}

LoadResponse returns details of a successful load image call.

type PushResponse

type PushResponse struct {
	// Digest specifies the Docker image digest in the format <hash_algorithm>:<hash>.
	// The digest returned from Client.Push differs from the image id returned in Client.Build.
	Digest string
}

PushResponse is a placeholder for data to be returned from a successful image push call.

type RegistryAuthConfig

type RegistryAuthConfig struct {
	Username      string `json:"username,omitempty"`
	Password      string `json:"password,omitempty"`
	Email         string `json:"email,omitempty"`
	ServerAddress string `json:"serveraddress,omitempty"` // domain/ip without a protocol
}

RegistryAuthConfig represents the fields required to authenticate with the Docker Engine API. Ref: https://docs.docker.com/engine/api/v1.41/#section/Authentication

func (*RegistryAuthConfig) ToHeader

func (r *RegistryAuthConfig) ToHeader() (string, error)

ToHeader marshals the auth information as a base64 encoded JSON object. This is suitable for passing to the Docker API as the X-Registry-Auth header.

type TagResponse

type TagResponse struct {
	// Image contains the Docker image name in the local Docker engine including the tag.
	// It is created from the bufremotepluginconfig.Config's Name.IdentityString() and a unique id.
	Image string
}

TagResponse returns details of a successful image tag call.