# Get a Secrets Manager secret value using Go with client-side caching
<a name="retrieving-secrets_cache-go"></a>

When you retrieve a secret, you can use the Secrets Manager Go-based caching component to cache it for future use. Retrieving a cached secret is faster than retrieving it from Secrets Manager. Because there is a cost for calling Secrets Manager APIs, using a cache can reduce your costs. For all of the ways you can retrieve secrets, see [Get secrets](retrieving-secrets.md).

The cache policy is Least Recently Used (LRU), so when the cache must discard a secret, it discards the least recently used secret. By default, the cache refreshes secrets every hour. You can configure [how often the secret is refreshed](retrieving-secrets_cache-go_CacheConfig.md) in the cache, and you can [hook into the secret retrieval](retrieving-secrets_cache-go_CacheHook.md) to add more functionality.

The cache does not force garbage collection once cache references are freed. The cache implementation does not include cache invalidation. The cache implementation is focused around the cache itself, and is not security hardened or focused. If you require additional security such as encrypting items in the cache, use the interfaces and abstract methods provided.

To use the component, you must have the following:
+ AWS SDK for Go. See [AWS SDKs](asm_access.md#asm-sdks).

To download the source code, see [Secrets Manager Go caching client](https://github.com/aws/aws-secretsmanager-caching-go ) on GitHub.

To set up a Go development environment, see [Golang Getting Started](https://golang.org/doc/install) on the Go Programming Language website.

**Required permissions: **
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`

For more information, see [Permissions reference](auth-and-access.md#reference_iam-permissions).

**Topics**
+ [type Cache](retrieving-secrets_cache-go_cache.md)
+ [type CacheConfig](retrieving-secrets_cache-go_CacheConfig.md)
+ [type CacheHook](retrieving-secrets_cache-go_CacheHook.md)

**Example Retrieve a secret**  
The following code example shows a Lambda function that retrieves a secret.  

```
package main

import (
	 "github.com/aws/aws-lambda-go/lambda"
	 "github.com/aws/aws-secretsmanager-caching-go/secretcache"
)

var (
	 secretCache, _ = secretcache.New()
)

func HandleRequest(secretId string) string {
	 result, _ := secretCache.GetSecretString(secretId)
	 
	 // Use the secret, return success
}

 func main() {
	 lambda. Start( HandleRequest)
}
```

# type Cache
<a name="retrieving-secrets_cache-go_cache"></a>

An in-memory cache for secrets requested from Secrets Manager. You use [GetSecretString](#retrieving-secrets_cache-go_cache_operations_GetCachedSecret) or [GetSecretBinary](#retrieving-secrets_cache-go_cache_operations_GetSecretBinary) to retrieve a secret from the cache. 

The following example shows how to configure the cache settings.

```
// Create a custom secretsmanager client
client := getCustomClient()

// Create a custom CacheConfig struct 
config := secretcache. CacheConfig{
    MaxCacheSize:  secretcache.DefaultMaxCacheSize + 10,
    VersionStage:  secretcache.DefaultVersionStage,
    CacheItemTTL:  secretcache.DefaultCacheItemTTL,
}
	
// Instantiate the cache 
cache, _ := secretcache.New(
    func( c *secretcache.Cache) {  c. CacheConfig = config },
    func( c *secretcache.Cache) {  c. Client = client },
)
```

For more information, including examples, see [Get a Secrets Manager secret value using Go with client-side caching](retrieving-secrets_cache-go.md).

## Methods
<a name="retrieving-secrets_cache-go_cache_operations"></a>

### New
<a name="retrieving-secrets_cache-go_cache_operations_New"></a>

`func New(optFns ...func(*Cache)) (*Cache, error)`

New constructs a secret cache using functional options, uses defaults otherwise. Initializes a SecretsManager Client from a new session. Initializes CacheConfig to default values. Initialises LRU cache with a default max size.

### GetSecretString
<a name="retrieving-secrets_cache-go_cache_operations_GetCachedSecret"></a>

`func (c *Cache) GetSecretString(secretId string) (string, error)`

GetSecretString gets the secret string value from the cache for given secret ID. Returns the secret string and an error if operation failed.

### GetSecretStringWithStage
<a name="retrieving-secrets_cache-go_cache_operations_GetSecretStringWithStage"></a>

`func (c *Cache) GetSecretStringWithStage(secretId string, versionStage string) (string, error)`

GetSecretStringWithStage gets the secret string value from the cache for given secret ID and [version stage](whats-in-a-secret.md#term_version). Returns the secret string and an error if operation failed.

### GetSecretBinary
<a name="retrieving-secrets_cache-go_cache_operations_GetSecretBinary"></a>

`func (c *Cache) GetSecretBinary(secretId string) ([]byte, error) {`

GetSecretBinary gets the secret binary value from the cache for given secret ID. Returns the secret binary and an error if operation failed.

### GetSecretBinaryWithStage
<a name="retrieving-secrets_cache-go_cache_operations_GetSecretBinaryWithStage"></a>

`func (c *Cache) GetSecretBinaryWithStage(secretId string, versionStage string) ([]byte, error)`

GetSecretBinaryWithStage gets the secret binary value from the cache for given secret ID and [version stage](whats-in-a-secret.md#term_version). Returns the secret binary and an error if operation failed. 

# type CacheConfig
<a name="retrieving-secrets_cache-go_CacheConfig"></a>

Cache configuration options for a [Cache](retrieving-secrets_cache-go_cache.md), such as maximum cache size, default [version stage](whats-in-a-secret.md#term_version), and Time to Live (TTL) for cached secrets.

```
type CacheConfig struct {

    // The maximum cache size. The default is 1024 secrets.
    MaxCacheSize int
            
    // The TTL of a cache item in nanoseconds. The default is 
    // 3.6e10^12 ns or 1 hour.
    CacheItemTTL int64
            
    // The version of secrets that you want to cache. The default 
    // is "AWSCURRENT".
    VersionStage string
            
    // Used to hook in-memory cache updates.
    Hook CacheHook
}
```

# type CacheHook
<a name="retrieving-secrets_cache-go_CacheHook"></a>

An interface to hook into a [Cache](retrieving-secrets_cache-go_cache.md) to perform actions on the secret being stored in the cache.

## Methods
<a name="retrieving-secrets_cache-go_CacheHook_operations"></a>

### Put
<a name="retrieving-secrets_cache-go_CacheHook_operations_Put"></a>

`Put(data interface{}) interface{}`

Prepares the object for storing in the cache.

### Get
<a name="retrieving-secrets_cache-go_CacheHook_operations_Get"></a>

`Get(data interface{}) interface{}`

Derives the object from the cached object.