📦 FileCache v2

Store data from io.Reader or bytes to cache files with TTL and metadata.

Installation

go get github.com/kukymbr/filecache/v2 

Usage

Initializing the cache instance

// With target dir specified
fc, err := filecache.New("/path/to/cache/dir")

// With temp dir as a target
fc, err := filecache.NewInTemp()

// With options
fc, err := filecache.New(
    "/path/to/cache/dir",
    filecache.InstanceOptions{
        PathGenerator: filecache.FilteredKeyPath,
        DefaultTTL:    time.Hour,
        GC:            filecache.NewIntervalGarbageCollector("/path/to/cache/dir", time.Hour),
    },
)

See the InstanceOptions godoc for the instance configuration values.

Saving data to the cache

// From the io.Reader
_, err := fc.Write(context.Background(), "key1", strings.NewReader("value1"))

// From the byte array
_, err := fc.WriteData(context.Background(), "key2", []byte("value2"))

// With the item options
_, err := fc.Write(
    context.Background(), 
    "key3", 
    strings.NewReader("value3"),
    filecache.ItemOptions{
        Name:   "Key 3",
        TTL:    time.Hour * 24,
        Fields: filecache.NewValues("field1", "val1", "field2", "val2"),
    },
)

See the ItemOptions godoc for the instance configuration values.

Reading from cache

// Opening the cache file reader
res, err := fc.Open(context.Background(), "key1")
if err != nil { 
    // Handle the error...
}

if res.Hit() {
    reader := res.Reader()
    // Read the data...
}

// Read all the data
res, err := fc.Read(context.Background(), "key2")
if err == nil && res.Hit() {
    data := res.Data()
}

// Read options
res, err := fc.Read(context.Background(), "key3")
if err == nil && res.Hit() {
    name := res.Options().Name
}

The Open() and Read() functions return an error only if context is canceled or if the file open operation has failed. If there is no error, this doesn't mean the result is found, the res.Hit() function should be called.

Iterate through the cached items

To iterate through the cached items, use the Scanner tool:

scanner := filecache.NewScanner("/path/to/cache/dir")

err := scanner.Scan(func(entry filecache.ScanEntry) error {
    // Do something with the found entry...
    return nil
})
if err := nil {
    // Handle the error...
}

Removing the expired items

The expired cache items are removed by the GarbageCollector, assigned to the FileCache instance.

There are three predefined realizations of the GarbageCollector:

• filecache.NewNopGarbageCollector() — the GarbageCollector doing nothing, all the files are kept;
• filecache.NewProbabilityGarbageCollector() — the GarbageCollector running with the defined probability, used by default;
• filecache.NewIntervalGarbageCollector() — the GarbageCollector running by the time interval.

See the gc.go's godocs for more info.

License

MIT.