Documentation
¶
Overview ¶
Package bufremoteplugindocker contains utilities for building Buf plugins using the Docker API.
Index ¶
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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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').
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.
Source Files