builder.go 5.6 KB

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