github.com/a4a881d4/docker@v1.9.0-rc2/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 6 7 import ( 8 "io" 9 "os" 10 11 // TODO: remove dependency on daemon 12 "github.com/docker/docker/daemon" 13 "github.com/docker/docker/image" 14 "github.com/docker/docker/runconfig" 15 ) 16 17 // Builder abstracts a Docker builder whose only purpose is to build a Docker image referenced by an imageID. 18 type Builder interface { 19 // Build builds a Docker image referenced by an imageID string. 20 // 21 // Note: Tagging an image should not be done by a Builder, it should instead be done 22 // by the caller. 23 // 24 // TODO: make this return a reference instead of string 25 Build() (imageID string) 26 } 27 28 // Context represents a file system tree. 29 type Context interface { 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 // Stat returns an entry corresponding to path if any. 35 // It is recommended to return an error if path was not found. 36 Stat(path string) (FileInfo, error) 37 // Open opens path from the context and returns a readable stream of it. 38 Open(path string) (io.ReadCloser, error) 39 // Walk walks the tree of the context with the function passed to it. 40 Walk(root string, walkFn WalkFunc) error 41 } 42 43 // WalkFunc is the type of the function called for each file or directory visited by Context.Walk(). 44 type WalkFunc func(path string, fi FileInfo, err error) error 45 46 // ModifiableContext represents a modifiable Context. 47 // TODO: remove this interface once we can get rid of Remove() 48 type ModifiableContext interface { 49 Context 50 // Remove deletes the entry specified by `path`. 51 // It is usual for directory entries to delete all its subentries. 52 Remove(path string) error 53 } 54 55 // FileInfo extends os.FileInfo to allow retrieving an absolute path to the file. 56 // TODO: remove this interface once pkg/archive exposes a walk function that Context can use. 57 type FileInfo interface { 58 os.FileInfo 59 Path() string 60 } 61 62 // PathFileInfo is a convenience struct that implements the FileInfo interface. 63 type PathFileInfo struct { 64 os.FileInfo 65 // FilePath holds the absolute path to the file. 66 FilePath string 67 } 68 69 // Path returns the absolute path to the file. 70 func (fi PathFileInfo) Path() string { 71 return fi.FilePath 72 } 73 74 // Hashed defines an extra method intended for implementations of os.FileInfo. 75 type Hashed interface { 76 // Hash returns the hash of a file. 77 Hash() string 78 SetHash(string) 79 } 80 81 // HashedFileInfo is a convenient struct that augments FileInfo with a field. 82 type HashedFileInfo struct { 83 FileInfo 84 // FileHash represents the hash of a file. 85 FileHash string 86 } 87 88 // Hash returns the hash of a file. 89 func (fi HashedFileInfo) Hash() string { 90 return fi.FileHash 91 } 92 93 // SetHash sets the hash of a file. 94 func (fi *HashedFileInfo) SetHash(h string) { 95 fi.FileHash = h 96 } 97 98 // Docker abstracts calls to a Docker Daemon. 99 type Docker interface { 100 // TODO: use digest reference instead of name 101 102 // LookupImage looks up a Docker image referenced by `name`. 103 LookupImage(name string) (*image.Image, error) 104 // Pull tells Docker to pull image referenced by `name`. 105 Pull(name string) (*image.Image, error) 106 107 // TODO: move daemon.Container to its own package 108 109 // Container looks up a Docker container referenced by `id`. 110 Container(id string) (*daemon.Container, error) 111 // Create creates a new Docker container and returns potential warnings 112 // TODO: put warnings in the error 113 Create(*runconfig.Config, *runconfig.HostConfig) (*daemon.Container, []string, error) 114 // Remove removes a container specified by `id`. 115 Remove(id string, cfg *daemon.ContainerRmConfig) error 116 // Commit creates a new Docker image from an existing Docker container. 117 Commit(*daemon.Container, *daemon.ContainerCommitConfig) (*image.Image, error) 118 // Copy copies/extracts a source FileInfo to a destination path inside a container 119 // specified by a container object. 120 // TODO: make an Extract method instead of passing `decompress` 121 // TODO: do not pass a FileInfo, instead refactor the archive package to export a Walk function that can be used 122 // with Context.Walk 123 Copy(c *daemon.Container, destPath string, src FileInfo, decompress bool) error 124 125 // Retain retains an image avoiding it to be removed or overwritten until a corresponding Release() call. 126 // TODO: remove 127 Retain(sessionID, imgID string) 128 // Release releases a list of images that were retained for the time of a build. 129 // TODO: remove 130 Release(sessionID string, activeImages []string) 131 } 132 133 // ImageCache abstracts an image cache store. 134 // (parent image, child runconfig) -> child image 135 type ImageCache interface { 136 // GetCachedImage returns a reference to a cached image whose parent equals `parent` 137 // and runconfig equals `cfg`. A cache miss is expected to return an empty ID and a nil error. 138 GetCachedImage(parentID string, cfg *runconfig.Config) (imageID string, err error) 139 }