1// Package builder defines interfaces for any Docker builder to implement.
2//
3// Historically, only server-side Dockerfile interpreters existed.
4// This package allows for other implementations of Docker builders.
5package builder // import "github.com/docker/docker/builder"
6
7import (
8	"context"
9	"io"
10
11	"github.com/docker/docker/api/types"
12	"github.com/docker/docker/api/types/backend"
13	"github.com/docker/docker/api/types/container"
14	containerpkg "github.com/docker/docker/container"
15	"github.com/docker/docker/image"
16	"github.com/docker/docker/layer"
17	"github.com/docker/docker/pkg/containerfs"
18)
19
20const (
21	// DefaultDockerfileName is the Default filename with Docker commands, read by docker build
22	DefaultDockerfileName = "Dockerfile"
23)
24
25// Source defines a location that can be used as a source for the ADD/COPY
26// instructions in the builder.
27type Source interface {
28	// Root returns root path for accessing source
29	Root() containerfs.ContainerFS
30	// Close allows to signal that the filesystem tree won't be used anymore.
31	// For Context implementations using a temporary directory, it is recommended to
32	// delete the temporary directory in Close().
33	Close() error
34	// Hash returns a checksum for a file
35	Hash(path string) (string, error)
36}
37
38// Backend abstracts calls to a Docker Daemon.
39type Backend interface {
40	ImageBackend
41	ExecBackend
42
43	// CommitBuildStep creates a new Docker image from the config generated by
44	// a build step.
45	CommitBuildStep(backend.CommitConfig) (image.ID, error)
46	// ContainerCreateWorkdir creates the workdir
47	ContainerCreateWorkdir(containerID string) error
48
49	CreateImage(config []byte, parent string) (Image, error)
50
51	ImageCacheBuilder
52}
53
54// ImageBackend are the interface methods required from an image component
55type ImageBackend interface {
56	GetImageAndReleasableLayer(ctx context.Context, refOrID string, opts backend.GetImageAndLayerOptions) (Image, ROLayer, error)
57}
58
59// ExecBackend contains the interface methods required for executing containers
60type ExecBackend interface {
61	// ContainerAttachRaw attaches to container.
62	ContainerAttachRaw(cID string, stdin io.ReadCloser, stdout, stderr io.Writer, stream bool, attached chan struct{}) error
63	// ContainerCreateIgnoreImagesArgsEscaped creates a new Docker container and returns potential warnings
64	ContainerCreateIgnoreImagesArgsEscaped(config types.ContainerCreateConfig) (container.ContainerCreateCreatedBody, error)
65	// ContainerRm removes a container specified by `id`.
66	ContainerRm(name string, config *types.ContainerRmConfig) error
67	// ContainerKill stops the container execution abruptly.
68	ContainerKill(containerID string, sig uint64) error
69	// ContainerStart starts a new container
70	ContainerStart(containerID string, hostConfig *container.HostConfig, checkpoint string, checkpointDir string) error
71	// ContainerWait stops processing until the given container is stopped.
72	ContainerWait(ctx context.Context, name string, condition containerpkg.WaitCondition) (<-chan containerpkg.StateStatus, error)
73}
74
75// Result is the output produced by a Builder
76type Result struct {
77	ImageID   string
78	FromImage Image
79}
80
81// ImageCacheBuilder represents a generator for stateful image cache.
82type ImageCacheBuilder interface {
83	// MakeImageCache creates a stateful image cache.
84	MakeImageCache(cacheFrom []string) ImageCache
85}
86
87// ImageCache abstracts an image cache.
88// (parent image, child runconfig) -> child image
89type ImageCache interface {
90	// GetCache returns a reference to a cached image whose parent equals `parent`
91	// and runconfig equals `cfg`. A cache miss is expected to return an empty ID and a nil error.
92	GetCache(parentID string, cfg *container.Config) (imageID string, err error)
93}
94
95// Image represents a Docker image used by the builder.
96type Image interface {
97	ImageID() string
98	RunConfig() *container.Config
99	MarshalJSON() ([]byte, error)
100	OperatingSystem() string
101}
102
103// ROLayer is a reference to image rootfs layer
104type ROLayer interface {
105	Release() error
106	NewRWLayer() (RWLayer, error)
107	DiffID() layer.DiffID
108}
109
110// RWLayer is active layer that can be read/modified
111type RWLayer interface {
112	Release() error
113	Root() containerfs.ContainerFS
114	Commit() (ROLayer, error)
115}
116