storage

type BaseIterator interface {
	// Next advances an iterator.
	Next() bool
	// Err returns last error encountered by iterator.
	Err() error
	// Close frees resources associated with this iterator.
	Close() error
}

type BlobIndexer interface {
	// FetchSchema fetches a schema blob from storage.
	// It returns a schema.ErrNotSchema if a blob contains raw data or is not a CAS schema blob.
	FetchSchema(ctx context.Context, ref types.Ref) (io.ReadCloser, uint64, error)
	// IterateSchema lists all schema blobs, optionally only with specific types.
	IterateSchema(ctx context.Context, typs ...string) SchemaIterator
	// ReindexSchema rebuilds an index of schema blobs.
	// If force parameter is false, an index is only updated for new blobs that were not indexed.
	// If force is true, an index is rebuilt for all blobs.
	ReindexSchema(ctx context.Context, force bool) error
}

type BlobSource interface {
	// StatBlob checks if a blob is in the storage and returns its size.
	// It returns ErrNotFound if this blob does not exist.
	// Calling it with a zero Ref will result in ErrInvalidRef.
	StatBlob(ctx context.Context, ref types.Ref) (uint64, error)
	// FetchBlob opens a blob for reading and returns its size.
	// It returns ErrNotFound if this blob does not exist.
	// Calling it with a zero Ref will result in ErrInvalidRef.
	// Caller should close a reader to free resources.
	FetchBlob(ctx context.Context, ref types.Ref) (io.ReadCloser, uint64, error)
	// IterateBlobs creates an iterator that lists all blobs in the storage.
	// Caller should close an iterator to free resources.
	//
	// TODO: clarify sorting
	IterateBlobs(ctx context.Context) Iterator
}

type BlobStorage interface {
	BlobSource
	// BeginBlob starts writing a blob to the storage.
	// See BlobWriter for more details.
	BeginBlob(ctx context.Context) (BlobWriter, error)
}

type BlobWriter interface {
	io.Writer
	// Size reports how many bytes were already written.
	Size() uint64
	// Complete returns the hash and size of the written blob.
	// User should either Close the writer to discard the blob or Commit to store the blob.
	// All writes after this call will fail.
	Complete() (types.SizedRef, error)
	// Close will discard the blob. Calling Close after Commit will still preserve the blob,
	// thus it's safe to use it in defer.
	Close() error
	// Commit stores the blob and closes it automatically.
	Commit() error
}

type Config interface {
	schema.Object
	// OpenStorage uses the config to make a new storage implementation.
	OpenStorage(ctx context.Context) (Storage, error)
}

type ErrRefMissmatch struct {
	Exp, Got types.Ref
}

type ErrSizeMissmatch struct {
	Exp, Got uint64
}

type Iterator interface {
	BaseIterator
	// SizedRef returns the size and ref of current blob.
	SizedRef() types.SizedRef
}

type PinIterator interface {
	BaseIterator
	// Pin returns current pin.
	Pin() types.Pin
}

type PinStorage interface {
	// SetPin overwrites or creates a named pin with a specified blob ref.
	SetPin(ctx context.Context, name string, ref types.Ref) error
	// DeletePin removes a named pin.
	DeletePin(ctx context.Context, name string) error
	// GetPin returns a ref associated with a named pin.
	// It returns ErrNotFound if a named pin does not exist.
	GetPin(ctx context.Context, name string) (types.Ref, error)
	// IteratePins lists all pins in the storage.
	IteratePins(ctx context.Context) PinIterator
}

type SchemaIterator interface {
	Iterator
	// SchemaRef returns the size, ref and the type of current schema blob.
	SchemaRef() types.SchemaRef
	// Decode reads and decodes current schema object. Implementations might optimize this call
	// by serving an object from a different data store.
	Decode() (schema.Object, error)
}

type Storage interface {
	BlobStorage
	PinStorage
	Close() error
}