github.com/rish1988/moby@v25.0.2+incompatible/builder/builder.go (about)

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