blobserver

type BlobEnumerator interface {
	// EnumerateBobs sends at most limit SizedBlobRef into dest,
	// sorted, as long as they are lexigraphically greater than
	// after (if provided).
	// limit will be supplied and sanity checked by caller.
	// EnumerateBlobs must close the channel.  (even if limit
	// was hit and more blobs remain, or an error is returned, or
	// the ctx is canceled)
	EnumerateBlobs(ctx *context.Context,
		dest chan<- blob.SizedRef,
		after string,
		limit int) error
}

type BlobHub interface {

	// NotifyBlobReceived notes that a storage target has successfully received
	// a blob and asynchronously notifies registered listeners.
	//
	// If any synchronous receive hooks are registered, they're run before
	// NotifyBlobReceived returns and their error is returned.
	NotifyBlobReceived(blob.SizedRef) error

	// AddReceiveHook adds a hook that is synchronously run
	// whenever blobs are received.  All registered hooks are run
	// on each blob upload but if more than one returns an error,
	// NotifyBlobReceived will only return one of the errors.
	AddReceiveHook(func(blob.SizedRef) error)

	RegisterListener(ch chan<- blob.Ref)
	UnregisterListener(ch chan<- blob.Ref)

	RegisterBlobListener(blob blob.Ref, ch chan<- blob.Ref)
	UnregisterBlobListener(blob blob.Ref, ch chan<- blob.Ref)
}

type BlobReceiveConfiger interface {
	BlobReceiver
	Configer
}

type BlobReceiver interface {
	// ReceiveBlob accepts a newly uploaded blob and writes it to
	// permanent storage.
	//
	// Implementations of BlobReceiver downstream of the HTTP
	// server can trust that the source isn't larger than
	// MaxBlobSize and that its digest matches the provided blob
	// ref. (If not, the read of the source will fail before EOF)
	//
	// To ensure those guarantees, callers of ReceiveBlob should
	// not call ReceiveBlob directly but instead use either
	// blobserver.Receive or blobserver.ReceiveString, which also
	// take care of notifying the BlobReceiver's "BlobHub"
	// notification bus for observers.
	ReceiveBlob(br blob.Ref, source io.Reader) (blob.SizedRef, error)
}

type BlobRemover interface {
	// RemoveBlobs removes 0 or more blobs.  Removal of
	// non-existent items isn't an error.  Returns failure if any
	// items existed but failed to be deleted.
	// ErrNotImplemented may be returned for storage types not implementing removal.
	RemoveBlobs(blobs []blob.Ref) error
}

type BlobStatter interface {
	// Stat checks for the existence of blobs, writing their sizes
	// (if found back to the dest channel), and returning an error
	// or nil.  Stat() should NOT close the channel.
	// TODO(bradfitz): redefine this to close the channel? Or document
	// better what the synchronization rules are.
	StatBlobs(dest chan<- blob.SizedRef, blobs []blob.Ref) error
}

type BlobStreamer interface {
	// StreamBlobs sends blobs to dest in unspecified order. It is
	// expected that a blobstorage implementing BlobStreamer will
	// send blobs to dest in the most efficient order
	// possible. StreamBlobs will stop sending blobs to dest and
	// return an opaque continuation token (in the string return
	// parameter) when the total size of the blobs it has sent
	// equals or exceeds limit. A succeeding call to StreamBlobs
	// should pass the string returned from the previous call in
	// contToken, or an empty string if the caller wishes to
	// receive blobs from "the start". StreamBlobs must
	// unconditionally close dest before returning, and it must
	// return if ctx.Done() becomes readable.
	StreamBlobs(ctx *context.Context, dest chan<- blob.Blob, contToken string, limitBytes int64) (nextContinueToken string, err error)
}

type Cache interface {
	blob.SeekFetcher
	BlobReceiver
	BlobStatter
}

type Config struct {
	Writable    bool
	Readable    bool
	Deletable   bool
	CanLongPoll bool

	// the "http://host:port" and optional path (but without trailing slash) to have "/camli/*" appended
	URLBase       string
	HandlerFinder FindHandlerByTyper
}

type Configer interface {
	Config() *Config
}

type FetcherEnumerator interface {
	blob.StreamingFetcher
	BlobEnumerator
}

type FindHandlerByTyper interface {
	// FindHandlerByType finds a handler by its handlerType and
	// returns its prefix and handler if it's loaded.  If it's not
	// loaded, the error will be ErrHandlerTypeNotFound.
	//
	// This is used by handlers to find siblings (such as the "ui" type handler)
	// which might have more knowledge about the configuration for discovery, etc.
	//
	// Note that if this is called during handler construction
	// time, only the prefix may be returned with a nil handler
	// and nil err.  Unlike GetHandler and GetStorage, this does
	// not cause the prefix to load immediately. At runtime (after
	// construction of all handlers), then prefix and handler will
	// both be non-nil when err is nil.
	FindHandlerByType(handlerType string) (prefix string, handler interface{}, err error)
}

type GenerationNotSupportedError string

type Generationer interface {
	// Generation returns a Storage's initialization time and
	// and unique random string (or UUID).  Implementations
	// should call ResetStorageGeneration on demand if no
	// information is known.
	// The error will be of type GenerationNotSupportedError if an underlying
	// storage target doesn't support the Generationer interface.
	StorageGeneration() (initTime time.Time, random string, err error)

	// ResetGeneration deletes the information returned by Generation
	// and re-generates it.
	ResetStorageGeneration() error
}

type HandlerConstructor func(Loader, jsonconfig.Obj) (http.Handler, error)

type HandlerIniter interface {
	InitHandler(FindHandlerByTyper) error
}

type Loader interface {
	FindHandlerByTyper

	// MyPrefix returns the prefix of the handler currently being constructed.
	MyPrefix() string

	// GetHandlerType returns the handler's configured type, but does
	// not force it to start being loaded yet.
	GetHandlerType(prefix string) string // returns "" if unknown

	// GetHandler returns either a Storage or an http.Handler.
	// It forces the handler to be loaded and returns an error if
	// a cycle is created.
	GetHandler(prefix string) (interface{}, error)

	// GetStorage is like GetHandler but requires that the Handler be
	// a storage Handler.
	GetStorage(prefix string) (Storage, error)
}

type MaxEnumerateConfig interface {
	Storage

	// MaxEnumerate returns the max that this storage interface is
	// capable of enumerating at once.
	MaxEnumerate() int
}

type NoImplStorage struct{}

type ShutdownStorage interface {
	Storage
	io.Closer
}

type StatReceiver interface {
	BlobReceiver
	BlobStatter
}

type Storage interface {
	blob.StreamingFetcher
	BlobReceiver
	BlobStatter
	BlobEnumerator
	BlobRemover
}

type StorageConfiger interface {
	Storage
	Configer
}

type StorageConstructor func(Loader, jsonconfig.Obj) (Storage, error)

type StorageHandler interface {
	Storage
	http.Handler
}