Go Packages

type Trove struct {
    // contains filtered or unexported fields
}

func Open(drv driver.Driver, opts ...Option) (*Trove, error)

func (t *Trove) Put(ctx context.Context, bucket, key string, r io.Reader, opts ...driver.PutOption) (*driver.ObjectInfo, error)
func (t *Trove) Get(ctx context.Context, bucket, key string, opts ...driver.GetOption) (*driver.ObjectReader, error)
func (t *Trove) Delete(ctx context.Context, bucket, key string, opts ...driver.DeleteOption) error
func (t *Trove) Head(ctx context.Context, bucket, key string) (*driver.ObjectInfo, error)
func (t *Trove) List(ctx context.Context, bucket string, opts ...driver.ListOption) (*driver.ObjectIterator, error)
func (t *Trove) Copy(ctx context.Context, srcBucket, srcKey, dstBucket, dstKey string, opts ...driver.CopyOption) (*driver.ObjectInfo, error)

func (t *Trove) CreateBucket(ctx context.Context, name string, opts ...driver.BucketOption) error
func (t *Trove) DeleteBucket(ctx context.Context, name string) error
func (t *Trove) ListBuckets(ctx context.Context) ([]driver.BucketInfo, error)

func (t *Trove) Backend(name string) (*Trove, error)
func (t *Trove) Driver() driver.Driver
func (t *Trove) Config() Config
func (t *Trove) Pool() *stream.Pool
func (t *Trove) Stream() *stream.Pool
func (t *Trove) Resolver() *middleware.Resolver
func (t *Trove) CAS() *cas.CAS
func (t *Trove) VFS() *vfs.FS

func (t *Trove) UseMiddleware(mw ...middleware.Middleware)
func (t *Trove) RemoveMiddleware(name string)
func (t *Trove) Health(ctx context.Context) error
func (t *Trove) Close(ctx context.Context) error

type Config struct {
    DefaultBucket    string
    ChunkSize        int64
    PoolSize         int
    ChecksumAlgorithm ChecksumAlgorithm
    StreamBufferSize int
    Retry            RetryPolicy
}

type ChecksumAlgorithm int

const (
    SHA256 ChecksumAlgorithm = iota
    Blake3
    XXHash
)

type RetryPolicy struct {
    Strategy    RetryStrategy // None, Fixed, Exponential
    MaxAttempts int
    BaseDelay   time.Duration
    MaxDelay    time.Duration
}

var (
    ErrNotFound         = errors.New("trove: not found")
    ErrBucketNotFound   = errors.New("trove: bucket not found")
    ErrBucketExists     = errors.New("trove: bucket already exists")
    ErrObjectNotFound   = errors.New("trove: object not found")
    ErrKeyEmpty         = errors.New("trove: key is required")
    ErrBucketEmpty      = errors.New("trove: bucket name is required")
    ErrDriverClosed     = errors.New("trove: driver is closed")
    ErrNilDriver        = errors.New("trove: driver is required")
    ErrInvalidDSN       = errors.New("trove: invalid DSN")
    ErrChecksumMismatch = errors.New("trove: checksum mismatch")
    ErrQuotaExceeded    = errors.New("trove: quota exceeded")
    ErrContentBlocked   = errors.New("trove: content blocked")
    ErrStreamClosed     = errors.New("trove: stream is closed")
    ErrUploadExpired    = errors.New("trove: upload session expired")
    ErrBackendNotFound  = errors.New("trove: backend not found")
    ErrPoolClosed       = errors.New("trove: stream pool is closed")
    ErrStreamNotActive  = errors.New("trove: stream is not active")
    ErrMaxStreamsReached = errors.New("trove: maximum concurrent streams reached")
)

type Driver interface {
    Name() string
    Open(ctx context.Context, dsn string, opts ...Option) error
    Close(ctx context.Context) error
    Ping(ctx context.Context) error

    Put(ctx context.Context, bucket, key string, r io.Reader, opts ...PutOption) (*ObjectInfo, error)
    Get(ctx context.Context, bucket, key string, opts ...GetOption) (*ObjectReader, error)
    Delete(ctx context.Context, bucket, key string, opts ...DeleteOption) error
    Head(ctx context.Context, bucket, key string) (*ObjectInfo, error)
    List(ctx context.Context, bucket string, opts ...ListOption) (*ObjectIterator, error)
    Copy(ctx context.Context, srcBucket, srcKey, dstBucket, dstKey string, opts ...CopyOption) (*ObjectInfo, error)

    CreateBucket(ctx context.Context, name string, opts ...BucketOption) error
    DeleteBucket(ctx context.Context, name string) error
    ListBuckets(ctx context.Context) ([]BucketInfo, error)
}

drv := s3driver.New()
err := drv.Open(ctx, "s3://access:secret@us-east-1/my-bucket?endpoint=...")

type Direction int

const (
    DirectionRead      Direction = iota // read path only
    DirectionWrite                      // write path only
    DirectionReadWrite                  // both paths
)

type Middleware interface {
    Name() string
    Direction() Direction
    ProcessRead(ctx context.Context, bucket, key string, r io.Reader) (io.Reader, error)
    ProcessWrite(ctx context.Context, bucket, key string, r io.Reader) (io.Reader, error)
}

type ReadMiddleware interface {
    Name() string
    ProcessRead(ctx context.Context, bucket, key string, r io.Reader) (io.Reader, error)
}

type WriteMiddleware interface {
    Name() string
    ProcessWrite(ctx context.Context, bucket, key string, r io.Reader) (io.Reader, error)
}

type Registration struct {
    Middleware Middleware
    Priority   int
    Scope      Scope
}

type Resolver struct { /* ... */ }
func (r *Resolver) Add(reg Registration)
func (r *Resolver) Remove(name string)
func (r *Resolver) Resolve(direction Direction, bucket, key, contentType string) []Middleware

type Pool struct { /* ... */ }
func NewPool(cfg PoolConfig) *Pool
func (p *Pool) Open(ctx context.Context, bucket, key string, dir Direction, opts ...StreamOption) (*Stream, error)
func (p *Pool) Metrics() PoolMetrics
func (p *Pool) Close() error

type PoolConfig struct {
    MaxStreams      int
    ChunkSize      int64
    BufferSize     int
    IdleTimeout    time.Duration
}

type PoolMetrics struct {
    ActiveStreams   int
    TotalOpened    int64
    TotalClosed    int64
    BytesUploaded  int64
    BytesDownloaded int64
}

type Stream struct { /* ... */ }
func (s *Stream) Write(data []byte) (int, error)
func (s *Stream) Read(buf []byte) (int, error)
func (s *Stream) Pause() error
func (s *Stream) Resume() error
func (s *Stream) Cancel() error
func (s *Stream) Complete() error
func (s *Stream) State() State
func (s *Stream) ID() id.ID

type Direction int

const (
    Upload   Direction = iota
    Download
    BiDi
)

type State int

const (
    Idle       State = iota
    Active
    Paused
    Completing
    Completed
    Failed
    Cancelled
)

type Chunk struct {
    Index    int
    Data     []byte
    Checksum string
}

type ChunkAck struct {
    Index int
    OK    bool
    Err   error
}

type ChunkPool struct { /* ... */ }
func (cp *ChunkPool) Get() *Chunk
func (cp *ChunkPool) Put(c *Chunk)
func (cp *ChunkPool) Stats() ChunkPoolStats

type ChunkPoolStats struct {
    Gets    int64
    Puts    int64
    Misses  int64
}

type Backpressure int

const (
    Block    Backpressure = iota // block the writer until the reader catches up
    Drop                        // drop chunks when the buffer is full
    Buffer                      // buffer chunks in memory without limit
    Adaptive                    // switch between block and buffer based on memory pressure
)

type ProgressHook func(bytesSent, totalBytes int64)
type ChunkHook    func(chunk Chunk)
type CompleteHook func(info driver.ObjectInfo)
type ErrorHook    func(err error)

type CAS struct { /* ... */ }
func (c *CAS) Store(ctx context.Context, r io.Reader) (hash string, err error)
func (c *CAS) Retrieve(ctx context.Context, hash string) (io.ReadCloser, error)
func (c *CAS) Exists(ctx context.Context, hash string) (bool, error)
func (c *CAS) Pin(ctx context.Context, hash string) error
func (c *CAS) Unpin(ctx context.Context, hash string) error
func (c *CAS) GC(ctx context.Context) (*GCResult, error)

type HashAlgorithm int

const (
    AlgSHA256 HashAlgorithm = iota
    AlgBlake3
    AlgXXHash
)

type GCResult struct {
    Removed   int
    Reclaimed int64 // bytes freed
}

type Index interface {
    AddRef(ctx context.Context, hash string) error
    RemoveRef(ctx context.Context, hash string) error
    RefCount(ctx context.Context, hash string) (int, error)
    IsPinned(ctx context.Context, hash string) (bool, error)
}

type FS struct { /* ... */ }
func New(store *trove.Trove, bucket string) *FS

func (f *FS) Stat(name string) (FileInfo, error)
func (f *FS) ReadDir(name string) ([]DirEntry, error)
func (f *FS) Walk(root string, fn WalkFunc) error
func (f *FS) Open(name string) (io.ReadCloser, error)
func (f *FS) Create(name string, r io.Reader) error
func (f *FS) Mkdir(name string) error
func (f *FS) Remove(name string) error
func (f *FS) RemoveAll(name string) error
func (f *FS) Rename(oldName, newName string) error
func (f *FS) SetMetadata(name string, meta map[string]string) error
func (f *FS) GetMetadata(name string) (map[string]string, error)

type ID struct { /* ... */ }
func New(prefix string) ID
func Parse(s string) (ID, error)
func (id ID) String() string
func (id ID) Prefix() string
func (id ID) IsZero() bool

// RunDriverSuite runs the full conformance suite against a driver implementation.
func RunDriverSuite(t *testing.T, drv driver.Driver)

type MockDriver struct {
    PutFunc    func(ctx context.Context, bucket, key string, r io.Reader, opts ...driver.PutOption) (*driver.ObjectInfo, error)
    GetFunc    func(ctx context.Context, bucket, key string, opts ...driver.GetOption) (*driver.ObjectReader, error)
    DeleteFunc func(ctx context.Context, bucket, key string, opts ...driver.DeleteOption) error
    // ... all Driver interface methods
}

func New(opts ...ExtOption) forge.Extension

type Config struct {
    BasePath        string
    DisableRoutes   bool
    DisableMigrate  bool
}