github.com/walkingsparrow/docker@v1.4.2-0.20151218153551-b708a2249bfa/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 "time" 11 12 "github.com/docker/docker/api/types" 13 "github.com/docker/docker/daemon" 14 "github.com/docker/docker/image" 15 "github.com/docker/docker/runconfig" 16 ) 17 18 // Builder abstracts a Docker builder whose only purpose is to build a Docker image referenced by an imageID. 19 type Builder interface { 20 // Build builds a Docker image referenced by an imageID string. 21 // 22 // Note: Tagging an image should not be done by a Builder, it should instead be done 23 // by the caller. 24 // 25 // TODO: make this return a reference instead of string 26 Build() (imageID string) 27 } 28 29 // Context represents a file system tree. 30 type Context interface { 31 // Close allows to signal that the filesystem tree won't be used anymore. 32 // For Context implementations using a temporary directory, it is recommended to 33 // delete the temporary directory in Close(). 34 Close() error 35 // Stat returns an entry corresponding to path if any. 36 // It is recommended to return an error if path was not found. 37 // If path is a symlink it also returns the path to the target file. 38 Stat(path string) (string, FileInfo, error) 39 // Open opens path from the context and returns a readable stream of it. 40 Open(path string) (io.ReadCloser, error) 41 // Walk walks the tree of the context with the function passed to it. 42 Walk(root string, walkFn WalkFunc) error 43 } 44 45 // WalkFunc is the type of the function called for each file or directory visited by Context.Walk(). 46 type WalkFunc func(path string, fi FileInfo, err error) error 47 48 // ModifiableContext represents a modifiable Context. 49 // TODO: remove this interface once we can get rid of Remove() 50 type ModifiableContext interface { 51 Context 52 // Remove deletes the entry specified by `path`. 53 // It is usual for directory entries to delete all its subentries. 54 Remove(path string) error 55 } 56 57 // FileInfo extends os.FileInfo to allow retrieving an absolute path to the file. 58 // TODO: remove this interface once pkg/archive exposes a walk function that Context can use. 59 type FileInfo interface { 60 os.FileInfo 61 Path() string 62 } 63 64 // PathFileInfo is a convenience struct that implements the FileInfo interface. 65 type PathFileInfo struct { 66 os.FileInfo 67 // FilePath holds the absolute path to the file. 68 FilePath string 69 // Name holds the basename for the file. 70 FileName string 71 } 72 73 // Path returns the absolute path to the file. 74 func (fi PathFileInfo) Path() string { 75 return fi.FilePath 76 } 77 78 // Name returns the basename of the file. 79 func (fi PathFileInfo) Name() string { 80 if fi.FileName != "" { 81 return fi.FileName 82 } 83 return fi.FileInfo.Name() 84 } 85 86 // Hashed defines an extra method intended for implementations of os.FileInfo. 87 type Hashed interface { 88 // Hash returns the hash of a file. 89 Hash() string 90 SetHash(string) 91 } 92 93 // HashedFileInfo is a convenient struct that augments FileInfo with a field. 94 type HashedFileInfo struct { 95 FileInfo 96 // FileHash represents the hash of a file. 97 FileHash string 98 } 99 100 // Hash returns the hash of a file. 101 func (fi HashedFileInfo) Hash() string { 102 return fi.FileHash 103 } 104 105 // SetHash sets the hash of a file. 106 func (fi *HashedFileInfo) SetHash(h string) { 107 fi.FileHash = h 108 } 109 110 // Backend abstracts calls to a Docker Daemon. 111 type Backend interface { 112 // TODO: use digest reference instead of name 113 114 // GetImage looks up a Docker image referenced by `name`. 115 GetImage(name string) (*image.Image, error) 116 // Pull tells Docker to pull image referenced by `name`. 117 Pull(name string) (*image.Image, error) 118 // ContainerWsAttachWithLogs attaches to container. 119 ContainerWsAttachWithLogs(name string, cfg *daemon.ContainerWsAttachWithLogsConfig) error 120 // ContainerCreate creates a new Docker container and returns potential warnings 121 ContainerCreate(params *daemon.ContainerCreateConfig) (types.ContainerCreateResponse, error) 122 // ContainerRm removes a container specified by `id`. 123 ContainerRm(name string, config *types.ContainerRmConfig) error 124 // Commit creates a new Docker image from an existing Docker container. 125 Commit(string, *types.ContainerCommitConfig) (string, error) 126 // Kill stops the container execution abruptly. 127 ContainerKill(containerID string, sig uint64) error 128 // Start starts a new container 129 ContainerStart(containerID string, hostConfig *runconfig.HostConfig) error 130 // ContainerWait stops processing until the given container is stopped. 131 ContainerWait(containerID string, timeout time.Duration) (int, error) 132 133 // ContainerUpdateCmd updates container.Path and container.Args 134 ContainerUpdateCmd(containerID string, cmd []string) error 135 136 // ContainerCopy copies/extracts a source FileInfo to a destination path inside a container 137 // specified by a container object. 138 // TODO: make an Extract method instead of passing `decompress` 139 // TODO: do not pass a FileInfo, instead refactor the archive package to export a Walk function that can be used 140 // with Context.Walk 141 //ContainerCopy(name string, res string) (io.ReadCloser, error) 142 // TODO: use copyBackend api 143 BuilderCopy(containerID string, destPath string, src FileInfo, decompress bool) error 144 } 145 146 // ImageCache abstracts an image cache store. 147 // (parent image, child runconfig) -> child image 148 type ImageCache interface { 149 // GetCachedImage returns a reference to a cached image whose parent equals `parent` 150 // and runconfig equals `cfg`. A cache miss is expected to return an empty ID and a nil error. 151 GetCachedImage(parentID string, cfg *runconfig.Config) (imageID string, err error) 152 }