objectstore

Documentation

Index

• Constants
• func ParseLeaseHolderName(name string) error
• func ParseObjectStoreBucketName(s string) (string, error)
• type BackendType
  • func ParseObjectStoreType(s string) (BackendType, error)
  • func (b BackendType) String() string
• type BucketSession
• type Client
• type Metadata
• type ModelObjectStoreGetter
• type ObjectStore
• type ObjectStoreGetter
• type ObjectStoreMetadata
• type ReadObjectStore
• type ReadSession
• type Session
• type UUID
  • func NewUUID() (UUID, error)
  • func ParseUUID(value string) (UUID, error)
  • func (u UUID) IsEmpty() bool
  • func (u UUID) String() string
  • func (u UUID) Validate() error
• type WriteObjectStore
• type WriteSession

Constants

const (
	// ErrHashMismatch is returned when the hash of the object does not match
	// the expected hash.
	ErrHashMismatch = errors.ConstError("hash mismatch")
)

const (
	// ErrObjectStoreDying is used to indicate to *third parties* that the
	// object store worker is dying, instead of catacomb.ErrDying, which is
	// unsuitable for propagating inter-worker.
	// This error indicates to consuming workers that their dependency has
	// become unmet and a restart by the dependency engine is imminent.
	ErrObjectStoreDying = errors.ConstError("object store worker is dying")
)

const (
	// ObjectStoreLeaseHolderName is the name of the lease holder for the
	// object store.
	ObjectStoreLeaseHolderName = "objectstore"
)

Functions

func ParseLeaseHolderName

func ParseLeaseHolderName(name string) error

ParseLeaseHolderName returns true if the supplied name is a valid lease holder. This is used to ensure that the lease manager does not attempt to acquire leases for invalid names.

func ParseObjectStoreBucketName

func ParseObjectStoreBucketName(s string) (string, error)

BucketName is the name of the bucket to use for the object store. See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html

This function doesn't use one big regexp, as it's harder to update when and if they change the naming rules.

Types

type BackendType

type BackendType string

BackendType is the type to identify the backend to use for the object store.

const (
	// FileBackend is the backend type for the file object store.
	FileBackend BackendType = "file"
	// S3Backend is the backend type for the s3 object store.
	S3Backend BackendType = "s3"
)

func ParseObjectStoreType

func ParseObjectStoreType(s string) (BackendType, error)

ParseObjectStoreType parses the given string into a BackendType.

func (BackendType) String

func (b BackendType) String() string

type BucketSession

type BucketSession interface {
	// CreateBucket creates a bucket in the object store based on the bucket name.
	CreateBucket(ctx context.Context, bucketName string) error
}

BucketSession provides additional access to the object store. This allows the manipulation of buckets.

type Client

type Client interface {
	// Session calls the given function with a session.
	// The func maybe called multiple times if the underlying session has
	// invalid credentials. Therefore session might not be the same across
	// calls.
	// It is the caller's responsibility to ensure that f is idempotent.
	Session(ctx context.Context, f func(context.Context, Session) error) error
}

Client provides access to the object store.

type Metadata

type Metadata struct {
	// SHA256 is the 256 hash of the object.
	SHA256 string
	// SHA384 is the 384 hash of the object.
	SHA384 string
	// Path is the path to the object.
	Path string
	// Size is the size of the object.
	Size int64
}

Metadata represents the metadata for an object.

type ModelObjectStoreGetter

type ModelObjectStoreGetter interface {
	// GetObjectStore returns an object store for the given namespace, usually
	// a model UUID or the global controller namespace.
	GetObjectStore(context.Context) (ObjectStore, error)
}

ModelObjectStoreGetter is the interface that is used to get a model object store.

type ObjectStore

type ObjectStore interface {
	ReadObjectStore
	WriteObjectStore
}

ObjectStore represents a full object store for both read and write access.

type ObjectStoreGetter

type ObjectStoreGetter interface {
	// GetObjectStore returns a object store for the given namespace.
	GetObjectStore(context.Context, string) (ObjectStore, error)
}

ObjectStoreGetter is the interface that is used to get a object store.

type ObjectStoreMetadata

type ObjectStoreMetadata interface {
	// GetMetadata returns the persistence metadata for the specified path.
	GetMetadata(ctx context.Context, path string) (Metadata, error)

	// GetMetadataBySHA256 returns the persistence metadata for the object with
	// the specified SHA256.
	GetMetadataBySHA256(ctx context.Context, sha256 string) (Metadata, error)

	// GetMetadataBySHA256Prefix returns the persistence metadata for the object
	// with SHA256 starting with the provided prefix.
	GetMetadataBySHA256Prefix(ctx context.Context, sha256Prefix string) (Metadata, error)

	// PutMetadata adds a new specified path for the persistence metadata.
	PutMetadata(ctx context.Context, metadata Metadata) (UUID, error)

	// RemoveMetadata removes the specified path for the persistence metadata.
	RemoveMetadata(ctx context.Context, path string) error

	// ListMetadata returns the persistence metadata.
	ListMetadata(ctx context.Context) ([]Metadata, error)

	// Watch returns a watcher that emits the path changes that either have been
	// added or removed.
	Watch() (watcher.StringsWatcher, error)
}

Metadata represents the metadata for an object store.

type ReadObjectStore

type ReadObjectStore interface {
	// Get returns an io.ReadCloser for data at path, namespaced to the
	// model.
	//
	// If the object does not exist, an [objectstore.ObjectNotFound]
	// error is returned.
	Get(context.Context, string) (io.ReadCloser, int64, error)

	// GetBySHA256 returns an io.ReadCloser for the object with the given SHA256
	// hash, namespaced to the model.
	//
	// If no object is found, an [objectstore.ObjectNotFound] error is returned.
	GetBySHA256(context.Context, string) (io.ReadCloser, int64, error)

	// GetBySHA256Prefix returns an io.ReadCloser for any object with the a SHA256
	// hash starting with a given prefix, namespaced to the model.
	//
	// If no object is found, an [objectstore.ObjectNotFound] error is returned.
	GetBySHA256Prefix(context.Context, string) (io.ReadCloser, int64, error)
}

ReadObjectStore represents an object store that can only be read from.

type ReadSession

type ReadSession interface {
	// ObjectExists returns nil if the object exists, or an error if it does
	// not.
	ObjectExists(ctx context.Context, bucketName, objectName string) error

	// GetObject returns a reader for the specified object.
	GetObject(ctx context.Context, bucketName, objectName string) (io.ReadCloser, int64, string, error)

	// ListObjects returns a list of objects in the specified bucket.
	ListObjects(ctx context.Context, bucketName string) ([]string, error)
}

ReadSession provides read access to the object store.

type Session

type Session interface {
	ReadSession
	WriteSession
	BucketSession
}

Session provides access to the object store.

type UUID

type UUID string

UUID represents a object store unique identifier.

func NewUUID

func NewUUID() (UUID, error)

NewUUID is a convince function for generating a new object store uuid.

func ParseUUID

func ParseUUID(value string) (UUID, error)

ParseUUID returns a new UUID from the given string. If the string is not a valid uuid an error satisfying errors.NotValid will be returned.

func (UUID) IsEmpty

func (u UUID) IsEmpty() bool

IsEmpty returns true if the UUID is empty.

func (UUID) String

func (u UUID) String() string

String implements the stringer interface for UUID.

func (UUID) Validate

func (u UUID) Validate() error

Validate ensures the consistency of the UUID. If the uuid is invalid an error satisfying errors.NotValid will be returned.

type WriteObjectStore

type WriteObjectStore interface {
	// Put stores data from reader at path, namespaced to the model.
	Put(ctx context.Context, path string, r io.Reader, size int64) (UUID, error)

	// PutAndCheckHash stores data from reader at path, namespaced to the model.
	// It also ensures the stored data has the correct sha384.
	PutAndCheckHash(ctx context.Context, path string, r io.Reader, size int64, sha384 string) (UUID, error)

	// Remove removes data at path, namespaced to the model.
	Remove(ctx context.Context, path string) error
}

WriteObjectStore represents an object store that can only be written to.

type WriteSession

type WriteSession interface {
	// PutObject puts an object into the object store based on the bucket name and
	// object name.
	PutObject(ctx context.Context, bucketName, objectName string, body io.Reader, hash string) error

	// DeleteObject deletes an object from the object store based on the bucket name
	// and object name.
	DeleteObject(ctx context.Context, bucketName, objectName string) error
}

WriteSession provides read access to the object store.