stow

type ClientMethod int

type Config interface {
	// Config gets a string configuration value and a
	// bool indicating whether the value was present or not.
	Config(name string) (string, bool)
	// Set sets the configuration name to specified value
	Set(name, value string)
}

type ConfigMap map[string]string

type Container interface {
	// ID gets a unique string describing this Container.
	ID() string
	// Name gets a human-readable name describing this Container.
	Name() string
	// Item gets an item by its ID.
	Item(id string) (Item, error)
	// Items gets a page of items with the specified
	// prefix for this Container.
	// The specified cursor is a pointer to the start of
	// the items to get. It should be obtained from a previous
	// call to this method, or should be CursorStart for the
	// first page.
	// count is the number of items to return per page.
	// The returned cursor can be checked with IsCursorEnd to
	// decide if there are any more items or not.
	Items(prefix, cursor string, count int) ([]Item, string, error)
	// RemoveItem removes the Item with the specified ID.
	RemoveItem(id string) error
	// Put creates a new Item with the specified name, and contents
	// read from the reader.
	Put(name string, r io.Reader, size int64, metadata map[string]any) (Item, error)
	// PreSignRequest generates a pre-signed url for the given id (key after bucket/container) and a given clientMethod.
	PreSignRequest(ctx context.Context, clientMethod ClientMethod, id string, params PresignRequestParams) (response PresignResponse, err error)
}

type ContextContainer interface {
	// ItemContext is Item with a context.
	ItemContext(ctx context.Context, id string) (Item, error)
	// ItemsContext is Items with a context.
	ItemsContext(ctx context.Context, prefix, cursor string, count int) ([]Item, string, error)
	// RemoveItemContext is RemoveItem with a context.
	RemoveItemContext(ctx context.Context, id string) error
	// PutContext is Put with a context.
	PutContext(ctx context.Context, name string, r io.Reader, size int64, metadata map[string]any) (Item, error)
}

type ContextItem interface {
	// OpenContext is Open with a context. The context also covers reading
	// from the returned io.ReadCloser, so it must not be cancelled before
	// the content is read.
	OpenContext(ctx context.Context) (io.ReadCloser, error)
	// ETagContext is ETag with a context.
	ETagContext(ctx context.Context) (string, error)
	// LastModContext is LastMod with a context.
	LastModContext(ctx context.Context) (time.Time, error)
	// MetadataContext is Metadata with a context.
	MetadataContext(ctx context.Context) (map[string]any, error)
}

type ContextItemRanger interface {
	// OpenRangeContext is OpenRange with a context. The context also covers
	// reading from the returned io.ReadCloser.
	OpenRangeContext(ctx context.Context, start, end uint64) (io.ReadCloser, error)
}

type ContextLocation interface {
	// CreateContainerContext is CreateContainer with a context.
	CreateContainerContext(ctx context.Context, name string) (Container, error)
	// ContainersContext is Containers with a context.
	ContainersContext(ctx context.Context, prefix, cursor string, count int) ([]Container, string, error)
	// ContainerContext is Container with a context.
	ContainerContext(ctx context.Context, id string) (Container, error)
	// RemoveContainerContext is RemoveContainer with a context.
	RemoveContainerContext(ctx context.Context, id string) error
	// ItemByURLContext is ItemByURL with a context.
	ItemByURLContext(ctx context.Context, url *url.URL) (Item, error)
}

type ContextTaggable interface {
	// TagsContext is Tags with a context.
	TagsContext(ctx context.Context) (map[string]any, error)
}

type Copier interface {
	// Copy copies src into the container as an item called name, replacing
	// any existing item, and returns the new item. When src comes from the
	// same kind of location and the backend supports it, the copy is made
	// on the server side and the content never passes through the caller.
	// Otherwise the content is streamed from src to the container.
	Copy(ctx context.Context, src Item, name string) (Item, error)
}

type HttpMethod = string

type Item interface {
	// ID gets a unique string describing this Item.
	ID() string
	// Name gets a human-readable name describing this Item.
	Name() string
	// URL gets a URL for this item.
	// For example:
	// local: file:///path/to/something
	// azure: azure://host:port/api/something
	//    s3: s3://host:post/etc
	URL() *url.URL
	// Size gets the size of the Item's contents in bytes.
	Size() (int64, error)
	// Open opens the Item for reading.
	// Calling code must close the io.ReadCloser.
	Open() (io.ReadCloser, error)
	// ETag is a string that is different when the Item is
	// different, and the same when the item is the same.
	// Usually this is the last modified datetime.
	ETag() (string, error)
	// LastMod returns the last modified date of the file.
	LastMod() (time.Time, error)
	// Metadata gets a map of key/values that belong
	// to this Item.
	Metadata() (map[string]any, error)
}

type ItemRanger interface {
	// OpenRange opens the item for reading starting at byte start and ending
	// at byte end.
	OpenRange(start, end uint64) (io.ReadCloser, error)
}

type Location interface {
	io.Closer
	// CreateContainer creates a new Container with the
	// specified name.
	CreateContainer(name string) (Container, error)
	// Containers gets a page of containers
	// with the specified prefix from this Location.
	// The specified cursor is a pointer to the start of
	// the containers to get. It it obtained from a previous
	// call to this method, or should be CursorStart for the
	// first page.
	// count is the number of items to return per page.
	// The returned cursor can be checked with IsCursorEnd to
	// decide if there are any more items or not.
	Containers(prefix string, cursor string, count int) ([]Container, string, error)
	// Container gets the Container with the specified
	// identifier.
	Container(id string) (Container, error)
	// RemoveContainer removes the container with the specified ID.
	RemoveContainer(id string) error
	// ItemByURL gets an Item at this location with the
	// specified URL.
	ItemByURL(url *url.URL) (Item, error)
}

type PresignRequestParams struct {
	ExpiresIn             time.Duration
	ContentMD5            string
	ExtraParams           map[string]any
	HttpMethod            HttpMethod
	AddContentMD5Metadata bool
}

type PresignResponse struct {
	Url                    string
	RequiredRequestHeaders map[string]string
}

type Taggable interface {
	// Tags returns a list of tags that belong to a given Item
	Tags() (map[string]any, error)
}

type WalkContainersFunc func(container Container, err error) error

type WalkFunc func(item Item, err error) error