Skip to content

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

License

Notifications You must be signed in to change notification settings

kukymbr/filecache

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

90 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

📦 FileCache v2

Make GoDoc GoReport

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.