# goswarm
Go Stale While Asynchronously Revalidate Memoization
## DESCRIPTION
goswarm is a library written in Go for storing the results of
expensive function calls and returning the cached result when the same
input key occurs again.
In addition to the examples provided below, documentation can be found
at
[](https://godoc.org/github.com/karrick/goswarm).
```Go
simple, err := goswarm.NewSimple(nil)
if err != nil {
log.Fatal(err)
}
// you can store any Go type in a Swarm
simple.Store("someKeyString", 42)
simple.Store("anotherKey", struct{}{})
simple.Store("yetAnotherKey", make(chan interface{}))
// but when you retrieve it, you are responsible to perform type assertions
key := "yetAnotherKey"
value, ok := simple.Load(key)
if !ok {
panic(fmt.Errorf("cannot find %q", key))
}
value = value.(chan interface{})
simple.Delete("anotherKey")
```
As seen above, goswarm's API is similar to that of any associative
array, also known as a map in Go terminology: It allows storing a
value to be retrieved using a specified key, and overwriting any value
that might already be present in the map. It allows loading the value
associated with the specified key already stored in the map. It allows
deleting a specified key and its associated value stored in the map.
goswarm differs from most traditional associative array APIs in that
it provides a method to load the value associated with a specified
key, and if that key is not found in the map, to invoke a specified
lookup function to fetch the value for that key.
```Go
simple, err := goswarm.NewSimple(&goswarm.Config{
Lookup: func(key string) (interface{}, error) {
// TODO: do slow calculation or make a network call
result := key // example
return result, nil
},
})
if err != nil {
log.Fatal(err)
}
defer func() { _ = simple.Close() }()
value, err := simple.Query("%version")
if !err {
panic(fmt.Errorf("cannot retrieve value for key %q: %s", key, err))
}
fmt.Printf("The value is: %v\n", value)
```
## Stale-While-Revalidate and Stale-If-Error
In addition, goswarm provides stale-while-revalidate and
stale-if-error compatible features in its simple API.
### Stale-While-Revalidate
When the user requests the value associated with a particular key,
goswarm determines whether that key-value pair is present, and if so,
whether that value has become stale. If the value is stale, goswarm
will return the previously stored value to the client, but spawn an
asynchronous routine to fetch a new value for that key and store that
value in the map to be used for future queries.
When the user requests the value associated with a particular key that
has expired, goswarm will not return that value, but rather
synchronously fetch an updated value to store in the map and return to
the user.
### Stale-If-Error
When fetching a new value to replace a value that has become stale,
the lookup callback funciton might return an error. Perhaps the remote
network resource used to fetch responses is offline. In these cases,
goswarm will not overwrite the stale value with the error, but
continue to serve the stale value until the lookup callback function
returns a new value rather than an error, or the value expires, in
which case, the error is returned to the user.
## Periodic Removal Of Expired Keys
If `GCPeriodicty` configuration value is greater than the zero-value
for time.Duration, goswarm spawns a separate go-routine that invokes
the `GC` method periodically, removing all key-value pairs from the
data map that have an expired time. When this feature is used, the
`Close` method must be invoked to stop and release that go-routine.
```Go
simple, err := goswarm.NewSimple(&goswarm.Config{
GoodExpiryDuration: 24 * time.Hour,
BadExpiryDuration: 5 * time.Minute,
GCPeriodicity: time.Hour,
Lookup: func(key string) (interface{}, error) {
// TODO: do slow calculation or make a network call
result := key // example
return result, nil
},
})
if err != nil {
log.Fatal(err)
}
defer func() { _ = simple.Close() }()
```
## Note About Choosing Stale and Expiry Durations
Different applications may require different logic, however if your
application needs to continue processing data and serving requests
even when a downstream dependency is subject to frequent high latency
periods or faults, it is recommended to set the GoodStaleDuration
period to a low enough value to ensure data is reasonably up-to-date,
but extend the GoodExpiryDuration to be long enough that your
application can still operate using possibly stale data. The goswarm
library will repeatedly attempt to fetch a new value from the
downstream service, but until a defined very long period of time
transpires, your service will be relatively insulated from these type
of downstream faults and latencies.
```Go
simple, err := goswarm.NewSimple(&goswarm.Config{
GoodStaleDuration: time.Minute,
GoodExpiryDuration: 24 * time.Hour,
BadStaleDuration: time.Minute,
BadExpiryDuration: 5 * time.Minute,
GCPeriodicity: time.Hour,
Lookup: func(key string) (interface{}, error) {
// TODO: do slow calculation or make a network call
result := key // example
return result, nil
},
})
if err != nil {
log.Fatal(err)
}
defer func() { _ = simple.Close() }()
value, err := simple.Query("%version")
if !err {
panic(fmt.Errorf("cannot retrieve value for key %q: %s", key, err))
}
fmt.Printf("The value is: %v\n", value)
```