Options Reference¶

type WriterOption func(*WriterConfig)

type WriterConfig struct {
    BufferSize  int               // Buffer size in bytes (0 = default)
    ContentType string            // MIME type hint
    Metadata    map[string]string // Backend-specific metadata
}

// Set content type
omnistorage.WithContentType("application/json")

// Set custom metadata
omnistorage.WithMetadata(map[string]string{
    "author": "john",
    "version": "1.0",
})

// Set buffer size
omnistorage.WithBufferSize(64 * 1024) // 64 KB

w, _ := backend.NewWriter(ctx, "data.json",
    omnistorage.WithContentType("application/json"),
    omnistorage.WithMetadata(map[string]string{
        "source": "api",
    }),
)

type ReaderOption func(*ReaderConfig)

type ReaderConfig struct {
    BufferSize int   // Buffer size in bytes (0 = default)
    Offset     int64 // Start reading from offset (if supported)
    Limit      int64 // Maximum bytes to read (0 = no limit)
}

// Set buffer size
omnistorage.WithReaderBufferSize(64 * 1024)

// Set offset (range read)
omnistorage.WithOffset(1024)

// Set limit
omnistorage.WithLimit(4096)

// Read bytes 1024-5120
r, _ := backend.NewReader(ctx, "large-file.dat",
    omnistorage.WithOffset(1024),
    omnistorage.WithLimit(4096),
)

type Options struct {
    // Comparison
    DeleteExtra   bool // Delete files in dst not in src
    Checksum      bool // Compare by checksum vs modtime/size
    SizeOnly      bool // Compare by size only
    IgnoreTime    bool // Ignore modification time
    IgnoreSize    bool // Ignore size differences

    // Behavior
    DryRun         bool // Report changes without making them
    IgnoreExisting bool // Skip files that exist in destination
    MaxErrors      int  // Stop after N errors (0 = first error)

    // Transfer controls
    Concurrency    int              // Parallel transfers (default: 4)
    BandwidthLimit int64            // Rate limit in bytes/second
    Retry          *RetryConfig     // Retry configuration
    Progress       func(Progress)   // Progress callback

    // Filtering
    Filter         *filter.Filter   // Include/exclude filter
    DeleteExcluded bool             // Delete excluded files from dst

    // Metadata
    PreserveMetadata *MetadataOptions // Metadata preservation
}

// Mirror sync (make dst match src exactly)
sync.Options{
    DeleteExtra: true,
}

// Safe copy (don't delete, skip existing)
sync.Options{
    IgnoreExisting: true,
}

// Checksum verification
sync.Options{
    Checksum: true,
}

// Dry run preview
sync.Options{
    DryRun: true,
}

// Full featured
sync.Options{
    DeleteExtra:    true,
    Checksum:       true,
    Concurrency:    8,
    BandwidthLimit: 10 * 1024 * 1024, // 10 MB/s
    Progress: func(p sync.Progress) {
        fmt.Printf("%s: %d/%d\n", p.Phase, p.FilesTransferred, p.TotalFiles)
    },
}

type RetryConfig struct {
    MaxRetries   int           // Maximum retry attempts
    InitialDelay time.Duration // Initial delay between retries
    MaxDelay     time.Duration // Maximum delay
    Multiplier   float64       // Delay multiplier for exponential backoff
    Jitter       float64       // Random jitter factor (0-1)
}

func DefaultRetryConfig() RetryConfig {
    return RetryConfig{
        MaxRetries:   3,
        InitialDelay: time.Second,
        MaxDelay:     30 * time.Second,
        Multiplier:   2.0,
        Jitter:       0.1,
    }
}

retryConfig := sync.DefaultRetryConfig()
retryConfig.MaxRetries = 5
retryConfig.MaxDelay = time.Minute

result, _ := sync.Sync(ctx, src, dst, "", "", sync.Options{
    Retry: &retryConfig,
})

type MetadataOptions struct {
    ContentType    bool // Preserve MIME type
    CustomMetadata bool // Preserve custom metadata
    ModTime        bool // Preserve modification time
}

func DefaultMetadataOptions() MetadataOptions {
    return MetadataOptions{
        ContentType:    true,
        CustomMetadata: true,
        ModTime:        false,
    }
}

result, _ := sync.Sync(ctx, src, dst, "", "", sync.Options{
    PreserveMetadata: &sync.MetadataOptions{
        ContentType:    true,
        CustomMetadata: true,
        ModTime:        true, // Requires SetModTime support
    },
})

// Pattern matching
filter.Include("*.json")
filter.Exclude("*.tmp")

// Size filters
filter.MinSize(1024)       // Minimum 1 KB
filter.MaxSize(100 * MB)   // Maximum 100 MB

// Age filters
filter.MinAge(24 * time.Hour)  // Older than 1 day
filter.MaxAge(7 * 24 * time.Hour) // Newer than 7 days

f := filter.New(
    filter.Include("*.json"),
    filter.Exclude("test_*.json"),
    filter.MinSize(100),
    filter.MaxAge(30 * 24 * time.Hour),
)

result, _ := sync.Sync(ctx, src, dst, "", "", sync.Options{
    Filter: f,
})

// Set channel buffer size
channel.WithBufferSize(100) // Default: 100

// Enable persistence (buffer for late readers)
channel.WithPersistence(true) // Default: false

backend := channel.New(
    channel.WithBufferSize(50),
    channel.WithPersistence(true),
)

type WriteMode int

const (
    WriteAll        WriteMode = iota // All backends must succeed
    WriteBestEffort                   // Continue on failure
    WriteQuorum                       // Majority must succeed
)

// Set write mode
multi.WithMode(multi.WriteQuorum)

mw, _ := multi.NewWriterWithOptions(
    []omnistorage.Backend{b1, b2, b3},
    multi.WithMode(multi.WriteBestEffort),
)