decorator

Documentation

Overview

Package decorator provides composable policy wrappers for filesystem adapters without changing their underlying guarantees.

Index

• type Adapter
  • func New(backend Backend, options ...Option) (*Adapter, error)
  • func (a *Adapter) Capabilities() filesystem.CapabilitySet
  • func (a *Adapter) Checksum(ctx context.Context, path filesystem.Path, ...) (filesystem.Checksum, error)
  • func (a *Adapter) Copy(ctx context.Context, source, destination filesystem.Path, ...) error
  • func (a *Adapter) Delete(ctx context.Context, path filesystem.Path) error
  • func (a *Adapter) List(ctx context.Context, path filesystem.Path, options filesystem.ListOptions) (filesystem.EntryIterator, error)
  • func (a *Adapter) Move(ctx context.Context, source, destination filesystem.Path, ...) error
  • func (a *Adapter) Open(ctx context.Context, path filesystem.Path) (io.ReadCloser, error)
  • func (a *Adapter) OpenRange(ctx context.Context, path filesystem.Path, byteRange filesystem.ByteRange) (io.ReadCloser, error)
  • func (a *Adapter) OpenWriter(ctx context.Context, path filesystem.Path, options filesystem.WriteOptions) (io.WriteCloser, error)
  • func (a *Adapter) SetMetadata(ctx context.Context, path filesystem.Path, metadata map[string]string) error
  • func (a *Adapter) SetVisibility(ctx context.Context, path filesystem.Path, visibility filesystem.Visibility) error
  • func (a *Adapter) Stat(ctx context.Context, path filesystem.Path) (filesystem.Metadata, error)
  • func (a *Adapter) TemporaryURL(ctx context.Context, path filesystem.Path, lifetime time.Duration, ...) (string, error)
  • func (a *Adapter) Visibility(ctx context.Context, path filesystem.Path) (filesystem.Visibility, error)
  • func (a *Adapter) Write(ctx context.Context, path filesystem.Path, source io.Reader, ...) (filesystem.Metadata, error)
• type Backend
• type Event
• type Observer
• type Option
  • func ReadOnly() Option
  • func WithChecksums() Option
  • func WithObserver(observer Observer) Option
  • func WithPrefix(prefix string) Option
  • func WithRetry(policy RetryPolicy) Option
• type RetryPolicy

Types

type Adapter

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

Adapter applies configured policies to a backend.

func New

func New(backend Backend, options ...Option) (*Adapter, error)

New constructs a composable adapter decorator.

func (*Adapter) Capabilities

func (a *Adapter) Capabilities() filesystem.CapabilitySet

Capabilities preserves the wrapped adapter's explicit capability set.

func (*Adapter) Checksum

func (a *Adapter) Checksum(ctx context.Context, path filesystem.Path, algorithm filesystem.ChecksumAlgorithm) (filesystem.Checksum, error)

Checksum returns a checksum for a prefixed object.

func (*Adapter) Copy

func (a *Adapter) Copy(ctx context.Context, source, destination filesystem.Path, options filesystem.CopyOptions) error

Copy copies between prefixed object paths.

func (*Adapter) Delete

func (a *Adapter) Delete(ctx context.Context, path filesystem.Path) error

Delete removes a prefixed object.

func (*Adapter) List

func (a *Adapter) List(ctx context.Context, path filesystem.Path, options filesystem.ListOptions) (filesystem.EntryIterator, error)

List lists a prefixed logical directory and removes the private prefix from returned entries.

func (*Adapter) Move

func (a *Adapter) Move(ctx context.Context, source, destination filesystem.Path, options filesystem.MoveOptions) error

Move moves between prefixed object paths.

func (*Adapter) Open

func (a *Adapter) Open(ctx context.Context, path filesystem.Path) (io.ReadCloser, error)

Open opens the prefixed object stream.

func (*Adapter) OpenRange

func (a *Adapter) OpenRange(ctx context.Context, path filesystem.Path, byteRange filesystem.ByteRange) (io.ReadCloser, error)

OpenRange opens a prefixed bounded byte range.

func (*Adapter) OpenWriter

func (a *Adapter) OpenWriter(ctx context.Context, path filesystem.Path, options filesystem.WriteOptions) (io.WriteCloser, error)

OpenWriter opens an incremental prefixed upload.

func (*Adapter) SetMetadata

func (a *Adapter) SetMetadata(ctx context.Context, path filesystem.Path, metadata map[string]string) error

SetMetadata replaces metadata on a prefixed object.

func (*Adapter) SetVisibility

func (a *Adapter) SetVisibility(ctx context.Context, path filesystem.Path, visibility filesystem.Visibility) error

SetVisibility changes visibility for a prefixed object.

func (*Adapter) Stat

func (a *Adapter) Stat(ctx context.Context, path filesystem.Path) (filesystem.Metadata, error)

Stat retrieves metadata for a prefixed object.

func (*Adapter) TemporaryURL

func (a *Adapter) TemporaryURL(ctx context.Context, path filesystem.Path, lifetime time.Duration, options filesystem.TemporaryURLOptions) (string, error)

TemporaryURL creates a URL for a prefixed object when the backend supports URL signing.

func (*Adapter) Visibility

func (a *Adapter) Visibility(ctx context.Context, path filesystem.Path) (filesystem.Visibility, error)

Visibility returns visibility for a prefixed object.

func (*Adapter) Write

func (a *Adapter) Write(ctx context.Context, path filesystem.Path, source io.Reader, options filesystem.WriteOptions) (filesystem.Metadata, error)

Write publishes a prefixed object from source.

type Backend

type Backend interface {
	filesystem.CapabilityReporter
	filesystem.Reader
	filesystem.RangeReader
	filesystem.Writer
	filesystem.WriteOpener
	filesystem.Deleter
	filesystem.Lister
	filesystem.Statter
	filesystem.Copier
	filesystem.Mover
	filesystem.MetadataSetter
	filesystem.Checksummer
	filesystem.VisibilityManager
}

Backend is the common adapter surface wrapped by decorators. Optional operations still report support through Capabilities.

type Event

type Event struct {
	// Operation identifies the public action.
	Operation filesystem.Operation
	// Path is the caller-visible logical source path.
	Path filesystem.Path
	// Destination is populated for copy and move operations.
	Destination filesystem.Path
	// Started is the operation setup start time.
	Started time.Time
	// Duration is the elapsed setup time.
	Duration time.Duration
	// Error is the returned setup or operation error.
	Error error
}

Event describes one decorator operation setup without including object content, credentials, metadata values, or signed URLs.

type Observer

type Observer func(Event)

Observer receives synchronous operation events and must be concurrency-safe.

type Option

type Option func(*configuration) error

Option configures an Adapter decorator.

func ReadOnly

func ReadOnly() Option

ReadOnly removes every mutating capability and returns typed capability errors from mutation methods.

func WithChecksums

func WithChecksums() Option

WithChecksums adds MD5, SHA-256, and CRC-32C by streaming reads through the wrapper. It is explicit because it performs an additional full object read.

func WithObserver

func WithObserver(observer Observer) Option

WithObserver instruments operation setup and completion. Stream lifetime is represented by OpenWriter's Close result rather than an observer event.

func WithPrefix

func WithPrefix(prefix string) Option

WithPrefix isolates every logical path beneath prefix in the wrapped backend.

func WithRetry

func WithRetry(policy RetryPolicy) Option

WithRetry retries only Open, OpenRange, List, Stat, Checksum, TemporaryURL, and Visibility setup. Mutating operations are never replayed.

type RetryPolicy

type RetryPolicy struct {
	// Attempts includes the initial call and must be positive.
	Attempts int
	// Retryable classifies errors whose operation setup may be repeated.
	Retryable func(error) bool
	// Backoff returns the delay before the next attempt; nil means no delay.
	Backoff func(attempt int) time.Duration
}

RetryPolicy controls retries for read-safe setup operations. Retryable and Backoff may be called concurrently and must be safe for concurrent use.