Multi-strategy object caching service
catbox is a multi-strategy key-value object store. It includes support for Redis, MongoDB,
and a limited memory store (not suitable for production environments). catbox provides two interfaces: a low-level Client
and a high-level
Policy
.
Installation
In order to reduce module dependencies, catbox does not depend on the mongodb or redis modules. To use these strategies, each service must be available on the network and each module must be manually installed.
Client
The Client
object provides a low-level cache abstraction. The object is constructed using new Client(options)
where:
-
options
- is an object with the following keys:-
engine
- the cache server implementation. Options are:redis
mongodb
memory
- an object with catbox compatible interface (use the
memory
cache implementation as prototype).
-
partition
- the partition name used to isolate the cached results across multiple clients. The partition name is used as the MongoDB database name or as a key prefix in Redis. To share the cache across multiple clients, use the same partition name. - additional strategy specific options:
- MongoDB:
-
host
- the MongoDB server hostname. Defaults to127.0.0.1
. -
port
- the MongoDB server port. Defaults to27017
. -
username
- when the mongo server requires authentication. Defaults to no authentication. -
password
- the authentication password whenusername
is configured. -
poolSize
- number of connections. Defaults to5
.
-
- Redis:
-
host
- the Redis server hostname. Defaults to127.0.0.1
. -
port
- the Redis server port. Defaults to6379
. -
password
- the Redis authentication password when required. -
database
- the Redis database number to connect to. Defaults to null (uses the Redis default of0
).
-
- Memory:
-
maxByteSize
- sets an upper limit on the number of bytes that can be stored in the cached. Once this limit is reached no additional items will be added to the cache until some expire. The utilized memory calculation is a rough approximation and must not be relied on. Defaults to104857600
(100MB).
-
- MongoDB:
-
API
The Client
object provides the following methods:
-
start(callback)
- creates a connection to the cache server. Must be called before any other method is available. Thecallback
signature isfunction(err)
. -
stop()
- terminates the connection to the cache server. -
get(key, callback)
- retrieve an item from the cache engine if found where:-
key
- a cache key object (see below). -
callback
- a function with the signaturefunction(err, cached)
. If the item is not found, botherr
andcached
arenull
. If found, thecached
object contains the following:-
item
- the value stored in the cache usingset()
. -
stored
- the timestamp when the item was stored in the cache (in milliseconds). -
ttl
- the remaining time-to-live (not the original value used when storing the object).
-
-
-
set(key, value, ttl, callback)
- store an item in the cache for a specified length of time, where:-
key
- a cache key object (see below). -
value
- the string or object value to be stored. -
ttl
- a time-to-live value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). -
callback
- a function with the signaturefunction(err)
.
-
-
drop(key, callback)
- remove an item from cache where:-
key
- a cache key object (see below). -
callback
- a function with the signaturefunction(err)
.
-
Any method with a key
argument takes an object with the following required properties:
-
segment
- a caching segment name. Enables using a single cache server for storing different sets of items with overlapping ids. -
id
- a unique item identifies (per segment).
Policy
The Policy
object provides a convenient cache interface by setting a global policy which is automatically applied to every storage action.
The object is constructed using new Policy(options, [cache, segment])
where:
-
options
- is an object with the following keys:-
expiresIn
- relative expiration expressed in the number of milliseconds since the item was saved in the cache. Cannot be used together withexpiresAt
. -
expiresAt
- time of day expressed in 24h notation using the 'MM:HH' format, at which point all cache records for the route expire. Cannot be used together withexpiresIn
. -
staleIn
- number of milliseconds to mark an item stored in cache as stale and reload it. Must be less thanexpiresIn
. -
staleTimeout
- number of milliseconds to wait before checking if an item is stale.
-
-
cache
- aClient
instance (which has already been started). -
segment
- required whencache
is provided. The segment name used to isolate cached items within the cache partition.
API
The Policy
object provides the following methods:
-
get(id, callback)
- retrieve an item from the cache where:-
id
- the unique item identifier (within the policy segment). -
callback
- a function with the signaturefunction(err, cached)
wherecached
is the object returned by theclient.get()
with the additionalisStale
boolean key.
-
-
set(id, value, ttl, callback)
- store an item in the cache where:-
id
- the unique item identifier (within the policy segment). -
value
- the string or object value to be stored. -
ttl
- a time-to-live override value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). This should be set to0
in order to use the caching rules configured when creating thePolicy
object. -
callback
- a function with the signaturefunction(err)
.
-
-
drop(id, callback)
- remove the item from cache where:-
id
- the unique item identifier (within the policy segment). -
callback
- a function with the signaturefunction(err)
.
-
-
ttl(created)
- given acreated
timestamp in milliseconds, returns the time-to-live left based on the configured rules. -
getOrGenerate(id, generateFunc, callback)
- get an item from the cache if found, otherwise calls thegenerateFunc
to produce a new value and stores it in the cache. This method applies the staleness rules. Its arguments are:-
id
- the unique item identifier (within the policy segment). -
generateFunc
- a function with the signaturefunction(callback = function (err, result))
whereresult
is the value to be stored. -
callback
- a function with the signaturefunction(err, value, cached, report)
where:-
err
- any errors encountered. -
value
- the fetched or generated value. -
cached
- thecached
object returned bypolicy.get()
is the item was found in the cache. -
report
- an object with logging information about the operation.
-
-