read-through-s3-decrypting-memory-cache

Stability: 1 - Experimental

Read-through in-memory cache for AWS S3 objects that are reasonable to cache in memory and need to be decrypted using AWS KMS.

Contributors

@tristanls

Contents

• Overview
• Installation
• Tests
• Usage
• Documentation
• Releases

Overview

This module offers a read-through in-memory cache for small objects that are stored in S3 and need to be decrypted using KMS. It assumes it is running in an environment where aws-sdk has access to its standard credentials chain with s3:GetObject permission to the configured S3 Bucket, kms:decrypt permission. Further, this module assumes appropriate AWS KMS key policies or grants allow decryption invocations to succeed.

Installation

npm install read-through-s3-decrypting-memory-cache

Tests

npm test

Usage

const Cache = require("read-through-s3-decrypting-memory-cache");
const cache = new Cache(
{
    bucket: "name-of-my-s3-bucket",
    encryptionContext: {
        some: "encryption context"
    },
    region: "us-east-1"
});
cache.get("myKey", (error, value) =>
{
    console.log(error, value);
});
 
const initialCache = new Map();
initialCache.set("myKey", Buffer.from("myValue"));
const cache2 = new Cache(
{
    bucket: "name-of-my-other-s3-bucket",
    encryptionContext: {
        some: "encryption context"
    },
    initialCache,
    region: "us-east-1"
});
cache2.get("myKey", (error, value) =>
{
    console.log(error, value);
});

Documentation

Cache

Public API

• Cache.S3_NOT_FOUND_CODES
• new Cache(config)
• cache.get(key, callback, [context])

Cache.S3_NOT_FOUND_CODES

• ["AccessDenied", "NoSuchKey"]

Default S3 error codes to treat as "not found" (AccessDenied can occur if the object does not exist but the caller has no s3:ListBucket permission).

new Cache(config)

• config: Object Cache configuration.
  • bucket: String Name of S3 bucket to retrieve values from.
  • credentials: AWS.Credentials (Default: undefined) AWS credentials to use with S3 and KMS. If not provided, the default credential provider chain will be used.
  • encryptionContext: Object Encryption context to extend when attempting KMS decryption.
  • initialCache: Map (Default: undefined) Initial cached values to use.
  • region: String AWS region to configure KMS with for decryption.
  • stderrTelemetry: Boolean (Default: false) If true, telemetry will be emitted to stderr.

Creates a new Cache.

cache.get(key, callback, [context])

• key: String S3 Key to retrieve from cache.
• callback: Function function(error, value){}
  • error: Error Error, if any.
  • value: Buffer S3 Object, if it exists, undefined otherwise.
• context: Object Optional context.
  • parentSpan: TraceTelemetryEvents.Span Parent span to use to trace execution.

Retrieves the cached value from memory. If not found in memory, attempts to retrieve the value from S3. If not found in S3, caches undefined locally, otherwise, decrypts using KMS. If decryption fails, caches undefined locally, otherwise caches the platinext value locally.

The EncryptionContext used in KMS.decrypt() operation is the configured encryptionContext with addition of keyId field that equals the value of key. For example, cache.get("foo", callback) will add keyId: "foo" to the configured encryptionContext when attempting decryption.

Releases

Current releases.

Policy

We follow the semantic versioning policy (semver.org) with a caveat:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

caveat: Major version zero is a special case indicating development version that may make incompatible API changes without incrementing MAJOR version.