baggageclaim

type COWStrategy struct {
	// The parent volume that we should base the new volume on.
	Parent Volume
}

type Client interface {
	// CreateVolume will create a volume on the remote server. By passing in a
	// VolumeSpec with a different strategy you can choose the type of volume
	// that you want to create.
	//
	// You are required to pass in a logger to the call to retain context across
	// the library boundary.
	//
	// CreateVolume returns the volume that was created or an error as to why it
	// could not be created.
	CreateVolume(lager.Logger, string, VolumeSpec) (Volume, error)

	// ListVolumes lists the volumes that are present on the server. A
	// VolumeProperties object can be passed in to filter the volumes that are in
	// the response.
	//
	// You are required to pass in a logger to the call to retain context across
	// the library boundary.
	//
	// ListVolumes returns the volumes that were found or an error as to why they
	// could not be listed.
	ListVolumes(lager.Logger, VolumeProperties) (Volumes, error)

	// LookupVolume finds a volume that is present on the server. It takes a
	// string that corresponds to the Handle of the Volume.
	//
	// You are required to pass in a logger to the call to retain context across
	// the library boundary.
	//
	// LookupVolume returns a bool if the volume is found with the matching volume
	// or an error as to why the volume could not be found.
	LookupVolume(lager.Logger, string) (Volume, bool, error)

	// DestroyVolumes deletes the list of volumes that is present on the server. It takes
	// a string of volumes
	//
	// You are required to pass in a logger to the call to retain context across
	// the library boundary.
	//
	// DestroyVolumes returns an error if any of the volume deletion fails. It does not
	// return an error if volumes were not found on the server.
	// DestroyVolumes returns an error as to why one or more volumes could not be deleted.
	DestroyVolumes(lager.Logger, []string) error

	// DestroyVolume deletes the volume with the provided handle that is present on the server.
	//
	// You are required to pass in a logger to the call to retain context across
	// the library boundary.
	//
	// DestroyVolume returns an error if the volume deletion fails. It does not
	// return an error if the volume was not found on the server.
	DestroyVolume(lager.Logger, string) error
}

type EmptyStrategy struct{}

type Encoding string

type ImportStrategy struct {
	// The location on the host to import. If the path is a directory, its
	// contents will be copied in. If the path is a file, it is assumed to be a
	// .tar.gz file, and its contents will be unpacked in to the volume.
	Path string

	// Follow symlinks and import them as files instead of links.
	FollowSymlinks bool
}

type PrivilegedRequest struct {
	Value bool `json:"value"`
}

type PropertyRequest struct {
	Value string `json:"value"`
}

type Strategy interface {
	Encode() *json.RawMessage
}

type Volume interface {
	// Handle returns a per-server unique identifier for the volume. The URL of
	// the server and a handle is enough to universally identify a volume.
	Handle() string

	// Path returns the filesystem path to the volume on the server. This can be
	// supplied to other systems in order to let them use the volume.
	Path() string

	// SetProperty sets a property on the Volume. Properties can be used to
	// filter the results in the ListVolumes call above.
	SetProperty(key string, value string) error

	// SetPrivileged namespaces or un-namespaces the UID/GID ownership of the
	// volume's contents.
	SetPrivileged(bool) error

	// GetPrivileged returns a bool indicating if the volume is privileged.
	GetPrivileged() (bool, error)

	// StreamIn calls BaggageClaim API endpoint in order to initialize tarStream
	// to stream the contents of the Reader into this volume at the specified path.
	StreamIn(ctx context.Context, path string, encoding Encoding, tarStream io.Reader) error

	StreamOut(ctx context.Context, path string, encoding Encoding) (io.ReadCloser, error)

	// Properties returns the currently set properties for a Volume. An error is
	// returned if these could not be retrieved.
	Properties() (VolumeProperties, error)

	// Destroy removes the volume and its contents. Note that it does not
	// safeguard against child volumes being present.
	Destroy() error

	// GetStreamInP2pUrl returns a modified StreamIn URL for this volume. The
	// returned URL contains a hostname that is reachable by other baggageclaim
	// servers on the same network. The URL can be passed to another
	// baggageclaim server to stream the contents of its source volume into
	// this target volume.
	GetStreamInP2pUrl(ctx context.Context, path string) (string, error)

	// StreamP2pOut streams the contents of this volume directly to another
	// baggageclaim server on the same network.
	StreamP2pOut(ctx context.Context, path string, streamInURL string, encoding Encoding) error
}

type VolumeFuture interface {
	// Wait will wait until the future has been provided with a value, which is
	// either the volume that was created or an error as to why it could not be
	// created.
	Wait() (Volume, error)

	// Destroy removes the future from the remote server. This can be used to
	// either stop waiting for a value, or remove the value from the remote
	// server after it is no longer needed.
	Destroy() error
}

type VolumeFutureResponse struct {
	Handle string `json:"handle"`
}

type VolumeProperties map[string]string

type VolumeRequest struct {
	Handle     string           `json:"handle"`
	Strategy   *json.RawMessage `json:"strategy"`
	Properties VolumeProperties `json:"properties"`
	Privileged bool             `json:"privileged,omitempty"`
}

type VolumeResponse struct {
	Handle     string           `json:"handle"`
	Path       string           `json:"path"`
	Properties VolumeProperties `json:"properties"`
}

type VolumeSpec struct {
	// Strategy is the information that the server requires to materialise the
	// volume. There are examples of these in this package.
	Strategy Strategy

	// Properties is the set of initial properties that the Volume should have.
	Properties VolumeProperties

	// Privileged is used to determine whether or not we need to perform a UID
	// translation of the files in the volume so that they can be read by a
	// non-privileged user.
	Privileged bool
}

type Volumes []Volume