github.com/moby/docker@v26.1.3+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  	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
    18  )
    19  
    20  const (
    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.
    27  type Source interface {
    28  	// Root returns root path for accessing source
    29  	Root() string
    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.
    39  type 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(context.Context, backend.CommitConfig) (image.ID, error)
    46  	// ContainerCreateWorkdir creates the workdir
    47  	ContainerCreateWorkdir(containerID string) error
    48  	CreateImage(ctx context.Context, config []byte, parent string, contentStoreDigest digest.Digest) (Image, error)
    49  
    50  	ImageCacheBuilder
    51  }
    52  
    53  // ImageBackend are the interface methods required from an image component
    54  type ImageBackend interface {
    55  	GetImageAndReleasableLayer(ctx context.Context, refOrID string, opts backend.GetImageAndLayerOptions) (Image, ROLayer, error)
    56  }
    57  
    58  // ExecBackend contains the interface methods required for executing containers
    59  type ExecBackend interface {
    60  	// ContainerAttachRaw attaches to container.
    61  	ContainerAttachRaw(cID string, stdin io.ReadCloser, stdout, stderr io.Writer, stream bool, attached chan struct{}) error
    62  	// ContainerCreateIgnoreImagesArgsEscaped creates a new Docker container and returns potential warnings
    63  	ContainerCreateIgnoreImagesArgsEscaped(ctx context.Context, config backend.ContainerCreateConfig) (container.CreateResponse, error)
    64  	// ContainerRm removes a container specified by `id`.
    65  	ContainerRm(name string, config *backend.ContainerRmConfig) error
    66  	// ContainerStart starts a new container
    67  	ContainerStart(ctx context.Context, containerID string, checkpoint string, checkpointDir string) error
    68  	// ContainerWait stops processing until the given container is stopped.
    69  	ContainerWait(ctx context.Context, name string, condition containerpkg.WaitCondition) (<-chan containerpkg.StateStatus, error)
    70  }
    71  
    72  // Result is the output produced by a Builder
    73  type Result struct {
    74  	ImageID   string
    75  	FromImage Image
    76  }
    77  
    78  // ImageCacheBuilder represents a generator for stateful image cache.
    79  type ImageCacheBuilder interface {
    80  	// MakeImageCache creates a stateful image cache.
    81  	MakeImageCache(ctx context.Context, cacheFrom []string) (ImageCache, error)
    82  }
    83  
    84  // ImageCache abstracts an image cache.
    85  // (parent image, child runconfig) -> child image
    86  type ImageCache interface {
    87  	// GetCache returns a reference to a cached image whose parent equals `parent`
    88  	// and runconfig equals `cfg`. A cache miss is expected to return an empty ID and a nil error.
    89  	GetCache(parentID string, cfg *container.Config, platform ocispec.Platform) (imageID string, err error)
    90  }
    91  
    92  // Image represents a Docker image used by the builder.
    93  type Image interface {
    94  	ImageID() string
    95  	RunConfig() *container.Config
    96  	MarshalJSON() ([]byte, error)
    97  	OperatingSystem() string
    98  }
    99  
   100  // ROLayer is a reference to image rootfs layer
   101  type ROLayer interface {
   102  	Release() error
   103  	NewRWLayer() (RWLayer, error)
   104  	DiffID() layer.DiffID
   105  	ContentStoreDigest() digest.Digest
   106  }
   107  
   108  // RWLayer is active layer that can be read/modified
   109  type RWLayer interface {
   110  	Release() error
   111  	Root() string
   112  	Commit() (ROLayer, error)
   113  }