From 6f7f8e2024db0ab0eefff17f3096fdd05112f1c2 Mon Sep 17 00:00:00 2001 From: Jeevanandam M Date: Fri, 26 Oct 2018 07:37:10 -0700 Subject: [PATCH] go-aah/aah#203 cache docs added --- cache.md | 232 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 cache.md diff --git a/cache.md b/cache.md new file mode 100644 index 0000000..c5631f7 --- /dev/null +++ b/cache.md @@ -0,0 +1,232 @@ +Title: Cache Manager +Desc: Cache manager for aah application cache use cases. Its pluggable design as providers and caches. +Keywords: cache, cache manager, cache provider, in-memory, inmemory, redis, memcache +--- +# aah Cache Manager + +This document provides the insight into aah Cache Manager design and usage. Introduced in v0.12.0. + +### Table of Contents + + * [Registering Cache Provider](#registering-cache-provider) + * [Creating a Cache](#creating-a-cache) + * [Using Created Cache in aah Application](#using-created-cache-in-aah-application) + * [Getting underlying Cache Client from Provider](#getting-underlying-cache-client-from-provider) + * [Configuration: In-Memory Cache Provider](#configuration-in-memory-cache-provider) + * [Configuration: Redis Cache Provider](#configuration-redis-cache-provider) + * [Configuration: Memcache Cache Provider](#configuration-memcache-cache-provider) + * [Adding your Own Cache Provider](#adding-your-own-cache-provider-and-cache) + +
+
![aah-Cache-Manager-Design]({{aah_cdn_host}}/assets/img/docs/aah-cache-manager-design.svg)
+
+ +## Registering Cache Provider + +Its easy to register any cache provider into aah application that implements `cache.Provider`. Best spot would be at file `/init.go`. + +#### Register provider + +```go +// importing aah pluggable cache provider library +import "aahframe.work/cache/provider/redis" + +// import "aahframe.work/cache/provider/inmemory" +// import "aahframe.work/cache/provider/memcache" + +cacheMgr := aah.App().CacheManager() + +if err := cacheMgr.AddProvider("redis1", &redis.Provider{}); err != nil { + log.Error(err) // provider might be already exists +} + +if err := cacheMgr.AddProvider("redis2", &redis.Provider{}); err != nil { + log.Error(err) // provider might be already exists +} +``` + +#### Configure Provider + +Configuring added provider in the `aah.conf` under section `cache { ... }`. + +```bash +# Sample configuration config multiple redis cache server. +cache { + redis1 { + provider = "redis" + address = "localhost:6379" + } + + redis2 { + provider = "redis" + address = "localhost:6380" + } +} +``` + +## Creating a Cache + +aah supports to create one or more cache using each provider based on use cases. Generally it also know as **cache region**. aah user could create a cache anytime they want. + +
+

Note: Cache name must be unique regardless of provider is used to create a cache.

+
+ +```go +// Create a cache configuration +cacheConfig := &cache.Config{ + Name: "app_user_ratelimit", + ProviderName: "redis", + + // Supported eviction modes are EvictionModeTTL, EvictionModeNoTTL and EvictionModeSlide + EvictionMode: cache.EvictionModeSlide, + + // SweepInterval only applicable to in-memory cache provider. + // SweepInterval: time.Minute * 90, // default is 60 minutes +} + +// Supply cache config to create a cache using cache manager +cacheMgr := aah.App().CacheManager() + +if err := cacheMgr.CreateCache(cacheConfig); err != nil { + log.Error(err) // error occured while creating cache +} +``` + +## Using Created Cache in aah Application + +Once cache is created in the application, simply get the cache instance from cache manager to perform operation supported by interface [`cache.Cache`](https://godoc.org/aahframe.work/cache#Cache). + +```go +cacheMgr := aah.App().CacheManager() + +// getting cache instance from cache manager +appUserRatelimitCache := cacheMgr.Cache("app_user_ratelimit") + +// get value from cache +value := appUserRatelimitCache.Get("cacheId") +fmt.Println(value) +``` + +## Getting underlying Cache Client from Provider + +Typically interface [`Cache`](https://godoc.org/aahframe.work/cache#Cache) provides **common** set of operation methods. However in real world usage needs option to perform dedicated operations using `Cache Client`. aah understands the need and provides way to get the client. + +```go +// E.g.: Getting underlying Cache Client of Redis +cacheMgr := aah.App().CacheManager() +redisProvider := cacheMgr.Provider("redis2").(*redis.Provider) // provider names used during a registeration + +// use the client directly to call `Incr` +result, err := redisProvider.Client().Incr("counter").Result() +``` + +## Configuration: In-Memory Cache Provider + +In-memory cache provider (`aahframe.work/cache/provider/inmemory`) is configuration free. + +* [Register provider](#registering-cache-provider) and +* [Create a Cache](#creating-a-cache) then use it + +## Configuration: Redis Cache Provider + +aah user have to configure redis provider (`aahframe.work/cache/provider/redis`) based on no of the providers they have registered. As explained [here](#registering-cache-provider). + +Provider configuration goes into `aah.conf` under section `cache { ... }`. + +```bash +cache { + # List of supported configuration for redis cache provider + redis1 { + provider = "redis" + + # Redis server address + # Default value id `:6379`. + address = "localhost:6379" + + # Default value is ``. + password = "" + + # DB number + # Default value is `0`. + db = 0 + + # Default value is `10 * No. of CPUs` + pool_size = 20 + + # Provider timeouts + # s => seconds + # m => minutes + timeout { + # Default value is `5s`. + connect = "5s" + + # Default value is `3s`. + read = "3s" + + # Default value is `3s`. + write = "3s" + + # Default value is `3s`. + pool = "3s" + + # Default value is `5m`. + idle = "5m" + } + + # Default value is `1m`. + idle_check_interval = "1m" + + # Retry Backoff time limits + # ms => milliseconds + retry_backoff { + # Default value is `8ms`. + min = "8ms" + + # Default value is `512ms`. + max = "512ms" + } + } +} +``` + + +## Configuration: Memcache Cache Provider + +aah user have to configure memcache provider (`aahframe.work/cache/provider/memcache`) based on no of the providers they have registered. As explained [here](#registering-cache-provider). + +Provider configuration goes into `aah.conf` under section `cache { ... }`. + +```bash +cache { + memcache1 { + # List of memcache server addresses + # Default value is `0.0.0.0:11211`. + addresses = [ + "0.0.0.0:11211", + "0.0.0.0:11212", + "0.0.0.0:11213" + ] + + # Maximum Idle connections + # Default value is `2`. + max_idle_conns = 2 + + # Client Timeout + # s => seconds + # + # Default value is `5s`. + timeout = "5s" + } +} +``` + +## Adding your Own Cache Provider and Cache + +As you have reached, you might have pretty good guess on how to implement own cache provider. Here we go - + +* Implement interface [`cache.Provider`](https://godoc.org/aahframe.work/cache#Provider) and +* Implement interface [`cache.Cache`](https://godoc.org/aahframe.work/cache#Cache) + +Then follow this documentation to register and use it. Refer to aah [Redis Cache Provider](https://github.com/go-aah/redis-cache-provider) and aah [Memcache Cache Provider](https://github.com/go-aah/memcache-cache-provider) for a implementation reference. +