Architecture

trove/
├── trove.go              # Core Trove type and operations (Put, Get, Delete, Head, List, Copy)
├── config.go             # Config type, DefaultConfig(), checksum and retry settings
├── options.go            # Functional options: WithBackend, WithRoute, WithVFS, etc.
├── errors.go             # Sentinel errors (ErrNotFound, ErrBucketEmpty, etc.)
├── driver/               # Driver interface + capability interfaces + option types
│   ├── driver.go         # Core Driver interface, ObjectInfo, ObjectReader, ObjectIterator
│   ├── options.go        # PutOption, GetOption, ListOption, CopyOption, BucketOption
│   ├── capability.go     # MultipartDriver, PresignDriver, VersioningDriver, etc.
│   ├── dsn.go            # DSN parser for connection strings
│   └── registry.go       # Global driver registry
├── drivers/              # Built-in storage backend drivers
│   ├── localdriver/      # Local filesystem (file:///path DSN)
│   ├── memdriver/        # In-memory (testing, no persistence)
│   ├── s3driver/         # AWS S3 / MinIO / S3-compatible
│   ├── gcsdriver/        # Google Cloud Storage
│   ├── azuredriver/      # Azure Blob Storage
│   └── sftpdriver/       # SFTP remote storage
├── middleware/            # Scope-aware middleware pipeline framework
│   ├── middleware.go     # Middleware, ReadMiddleware, WriteMiddleware interfaces
│   ├── registration.go  # Registration type with scope, direction, priority
│   ├── resolver.go       # Resolver: assembles per-operation pipeline with LRU cache
│   ├── scope.go          # Scope interface + built-in scopes (Global, Bucket, Key, etc.)
│   ├── helpers.go        # Convenience constructors: ForBuckets, ForKeys, And, Or, Not
│   ├── cache.go          # LRU scope cache for resolved pipelines
│   ├── encrypt/          # AES-256-GCM encryption with KeyProvider interface
│   ├── compress/         # Zstd compression with min-size and skip-extension logic
│   ├── dedup/            # Content deduplication via CAS integration
│   ├── scan/             # Content scanning (virus, policy)
│   └── watermark/        # Metadata watermarking
├── stream/               # Managed streaming engine
│   ├── stream.go         # Stream type, state machine, lifecycle hooks
│   ├── chunk.go          # Chunk, ChunkAck, ChunkPool (sync.Pool-based)
│   ├── pool.go           # Pool: concurrency-limited stream manager
│   ├── backpressure.go   # Backpressure strategies (Block, Drop, Buffer, Adaptive)
│   └── metrics.go        # Per-stream transfer metrics
├── cas/                  # Content-addressable storage
│   ├── cas.go            # CAS type: Store, Retrieve, Exists, Pin, Unpin, GC
│   ├── index.go          # Index interface + MemoryIndex implementation
│   ├── hash.go           # Hash algorithms (SHA-256, BLAKE3)
│   └── gc.go             # Garbage collection cycle
├── vfs/                  # Virtual filesystem over object storage
│   ├── vfs.go            # FS type: Stat, ReadDir, Walk, Open, Create, Mkdir, Remove, Rename
│   ├── file.go           # File type (read/write with io.Pipe)
│   └── compat.go         # io/fs.FS compatibility adapter
├── id/                   # TypeID-based identifiers
│   └── id.go             # ID type, prefixes (obj_, bkt_, str_, chk_, ...), Parse, New
├── trovetest/            # Conformance test suite for driver implementations
├── internal/             # Internal utilities (router, checksum)
│   ├── router.go         # Multi-backend router (pattern + function routing)
│   └── checksum.go       # SHA-256, BLAKE3, XXHash integrity verification
└── extension/            # Forge extension for DI and lifecycle integration

User Code
   │
   t.Put(ctx, bucket, key, reader, opts...)
   │
   ├── 1. Validate
   │       Reject empty bucket or key.
   │       Apply default bucket if configured.
   │
   ├── 2. Middleware Pipeline (Write)
   │       Resolver evaluates all registrations against
   │       (ctx, bucket, key). Matching WriteMiddleware
   │       are sorted by priority and chained.
   │
   │       reader → [encrypt] → [compress] → ... → transformed reader
   │
   ├── 3. Router
   │       Resolve the backend for this (bucket, key):
   │         a. Route functions  (highest priority)
   │         b. Pattern routes   (filepath.Match)
   │         c. Default driver   (fallback)
   │
   └── 4. Driver
           drv.Put(ctx, bucket, key, reader, opts...)
           Backend-specific storage (filesystem, S3, GCS, ...)

User Code
   │
   t.Get(ctx, bucket, key, opts...)
   │
   ├── 1. Validate
   ├── 2. Router → resolve backend
   ├── 3. Driver.Get → *ObjectReader
   └── 4. Middleware Pipeline (Read)
           reader → [decompress] → [decrypt] → ... → caller

t, err := trove.Open(primaryDriver,
    // Named backends
    trove.WithBackend("archive", archiveDriver),
    trove.WithBackend("cache", cacheDriver),

    // Pattern-based routes
    trove.WithRoute("*.log", "archive"),
    trove.WithRoute("tmp/*", "cache"),

    // Function-based route
    trove.WithRouteFunc(func(bucket, key string) string {
        if bucket == "compliance" {
            return "archive"
        }
        return "" // empty string = fall through
    }),
)

archiveTrove, err := t.Backend("archive")
// All operations on archiveTrove go directly to the archive driver.
archiveTrove.Put(ctx, "backups", "db.sql.gz", reader)

// ReadMiddleware intercepts data being read (downloaded).
type ReadMiddleware interface {
    WrapReader(ctx context.Context, r io.ReadCloser, info *driver.ObjectInfo) (io.ReadCloser, error)
}

// WriteMiddleware intercepts data being written (uploaded).
type WriteMiddleware interface {
    WrapWriter(ctx context.Context, w io.WriteCloser, key string) (io.WriteCloser, error)
}

// Encrypt images in the "private" bucket only.
scope := middleware.And(
    middleware.ForBuckets("private"),
    middleware.ForKeys("*.jpg", "*.png", "*.gif"),
)

// Compress everything except the "raw" bucket.
scope := middleware.Not(middleware.ForBuckets("raw"))

t.UseMiddleware(middleware.Registration{
    Middleware: encrypt.New(encrypt.WithKeyProvider(kp)),
    Scope:     middleware.ForBuckets("secrets"),
    Priority:  -10, // runs before default priority (0)
})

Registration[]
   │
   ├── Filter by direction (Read or Write)
   ├── Filter by scope match (ctx, bucket, key)
   ├── Sort by priority (ascending), then registration order
   │
   └── Pipeline: [mw1, mw2, mw3, ...]

          ┌──────────┐
          │   Idle   │  ← NewStream()
          └────┬─────┘
               │ Start()
          ┌────▼─────┐
    ┌─────│  Active  │─────┐
    │     └────┬─────┘     │
    │ Pause    │ Complete() │ Fail()
    │          │            │
┌───▼────┐ ┌──▼────────┐ ┌─▼───────┐
│ Paused │ │ Completing │ │ Failed  │
└───┬────┘ └──┬────────┘ └─────────┘
    │ Resume   │
    │          │
    └──────────┘ ┌──────────┐
               └►│ Completed│
                 └──────────┘

pool := stream.NewChunkPool(8 * 1024 * 1024) // 8 MB chunks

buf := pool.Get()   // allocate or reuse
defer pool.Put(buf)  // return to pool

s, err := t.Stream(ctx, "uploads", "video.mp4", stream.DirectionUpload,
    stream.WithOnProgress(func(p stream.Progress) {
        fmt.Printf("progress: %d%%  speed: %.1f MB/s\n", p.Percent, p.Speed/1e6)
    }),
    stream.WithOnComplete(func(info *driver.ObjectInfo) {
        fmt.Printf("upload complete: %s\n", info.ETag)
    }),
    stream.WithResumable(),
    stream.WithBackpressure(stream.BackpressureAdaptive),
)

GC(ctx)
   │
   ├── 1. Index.ListUnpinned()
   │       Returns all entries with RefCount=0 AND Pinned=false
   │
   ├── 2. For each entry:
   │       ├── driver.Delete(bucket, key)  -- remove from storage
   │       └── index.Delete(hash)          -- remove from index
   │
   └── 3. Return GCResult { Scanned, Deleted, FreedBytes, Errors }

cas := cas.New(driver,
    cas.WithAlgorithm(cas.AlgSHA256),
    cas.WithBucket("cas-store"),
    cas.WithIndex(myDatabaseIndex),
)

hash, info, err := cas.Store(ctx, reader)

vfs := t.VFS("documents")

// Create a file.
f, _ := vfs.Create(ctx, "reports/q4.txt")
f.Write([]byte("Q4 earnings report"))
f.Close()

// Read it back.
f, _ = vfs.Open(ctx, "reports/q4.txt")
data, _ := io.ReadAll(f)
f.Close()

// List a directory.
entries, _ := vfs.ReadDir(ctx, "reports")
for _, e := range entries {
    fmt.Println(e.Name(), e.IsDir())
}

drv := t.Driver()

// Check if the driver supports pre-signed URLs.
if presigner, ok := drv.(driver.PresignDriver); ok {
    url, err := presigner.PresignGet(ctx, "uploads", "report.pdf", 15*time.Minute)
    fmt.Println("download URL:", url)
}

// Check for multipart upload support.
if mp, ok := drv.(driver.MultipartDriver); ok {
    uploadID, _ := mp.InitiateMultipart(ctx, "uploads", "large-file.bin")
    // ... upload parts ...
    mp.CompleteMultipart(ctx, "uploads", "large-file.bin", uploadID, parts)
}

import "github.com/xraph/trove/id"

// Generate a new object ID.
objID := id.NewObjectID()
fmt.Println(objID) // "obj_01h455vb4pex5vsknk084sn02q"

// Parse and validate.
parsed, err := id.ParseObjectID("obj_01h455vb4pex5vsknk084sn02q")

// Check the prefix.
fmt.Println(parsed.Prefix()) // "obj"

// IDs implement encoding.TextMarshaler, sql.Scanner, and bson.ValueMarshaler
// for seamless serialization to JSON, databases, and MongoDB.

trove (core)
├── trove/driver           (zero deps -- defines Driver, ObjectInfo, capability interfaces)
├── trove/id               (external: go.jetify.com/typeid)
├── trove/internal          (depends on driver)
├── trove/middleware         (depends on driver)
│   ├── middleware/encrypt  (depends on middleware)
│   ├── middleware/compress (depends on middleware, klauspost/compress)
│   ├── middleware/dedup    (depends on middleware, cas)
│   ├── middleware/scan     (depends on middleware)
│   └── middleware/watermark(depends on middleware)
├── trove/stream            (depends on driver, id)
├── trove/cas               (depends on driver)
├── trove/vfs               (depends on driver -- uses Storage interface to avoid circular import)
├── trove/drivers/localdriver   (depends on driver)
├── trove/drivers/memdriver     (depends on driver)
├── trove/drivers/s3driver      (depends on driver, aws-sdk-go-v2)
├── trove/drivers/gcsdriver     (depends on driver, cloud.google.com/go/storage)
├── trove/drivers/azuredriver   (depends on driver, azure-sdk-for-go)
├── trove/drivers/sftpdriver    (depends on driver, pkg/sftp)
├── trove/trovetest         (depends on driver)
└── trove/extension          (depends on trove, Forge framework)