Connect DynamoDB

connect-dynamodb is a DynamoDB session store backed by the 3.x @aws-sdk/client-dynamodb.

Installation

$ npm install connect-dynamodb

Options

Rational defaults are set but can be overridden in the options object. Credentials and configuration are automatically loaded using AWS defaults unless the client options is provided to override them.

• client Optional AWS DynamoDBClient object from new DynamoDBClient({}) If supplied, this is used instead of standard node defaults.
• table Optional DynamoDB server session table name (defaults to "sessions")
• hashKey Optional hash key (defaults to "id")
• prefix Optional key prefix (defaults to "sess")
• reapInterval Legacy session expiration cleanup in milliseconds. ☣️ Legacy reap behaviors use DynamoDB scan functionality that can incur significant costs. Should instead enable DynamoDB TTL and select the expires field. TODO should we just remove it since we're already making a breaking change?

Usage

var options = {
  // Optional DynamoDB table name, defaults to 'sessions'
  table: "myapp-sessions",
  // Optional client for alternate endpoint, such as DynamoDB Local
  client: new DynamoDBClient({ endpoint: "http://localhost:8000" }),
  // Optional ProvisionedThroughput params, defaults to 5
  readCapacityUnits: 25,
  writeCapacityUnits: 25,
  // Optional special keys that will be inserted directly into your table (in addition to remaining in the session)
  specialKeys: [
    {
      name: "userId", // The session key
      type: "S", // The DyanamoDB attribute type
    },
  ],
  // Optional skip throw missing special keys in session, if set true
  skipThrowMissingSpecialKeys: true,
};

With connect

var connect = require("connect");
var DynamoDBStore = require("connect-dynamodb")(connect);
connect()
  .use(connect.cookieParser())
  .use(
    connect.session({
      store: new DynamoDBStore(options),
      secret: "keyboard cat",
    })
  );

With express 3

var DynamoDBStore = require("connect-dynamodb")(express);
var app = express(
  express.cookieParser(),
  express.session({ store: new DynamoDBStore(options), secret: "keyboard cat" })
);

With express 4

var app = express();
var session = require("express-session");
var DynamoDBStore = require("connect-dynamodb")({ session: session });
app.use(session({ store: new DynamoDBStore(options), secret: "keyboard cat" }));

OR

var app = express();
var session = require("express-session");
var DynamoDBStore = require("connect-dynamodb")(session);
app.use(session({ store: new DynamoDBStore(options), secret: "keyboard cat" }));

OR

import session from "express-session";
import connect from "connect-dynamodb";

interface SessionData {
  name: string;
  animal: "cow" | "pig";
}
const DynamoDBStore = connect<SessionData>(session);
app.use(session({ store: new DynamoDBStore(options), secret: "keyboard cat" }));

Testing

If you want to run the tests locally and have the AWS environment variables setup you can run the command:

npm test

You can also run it locally by running the following two scripts in separate terminals:

docker run -it --rm \
  --name=dynamodb-test \
  -p 127.0.0.1:8000:8000 \
  deangiberson/aws-dynamodb-local

export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=accesskey
export AWS_SECRET_ACCESS_KEY=secretaccesskey
export ENDPOINT=http://127.0.0.1:8000
npm test

IAM Permissions

Connect DynamoDB requires the following IAM permissions for DynamoDB:

• CreateTable
• PutItem
• DeleteItem
• GetItem
• Scan
• UpdateItem

Sample IAM policy (with least privilege):

(Replace <AWS ACCOUNT ID>, <TABLE NAME> and <SOURCE IP AND BITMASK>).

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "dynamodb:CreateTable",
        "dynamodb:DescribeTable",
        "dynamodb:PutItem",
        "dynamodb:DeleteItem",
        "dynamodb:GetItem",
        "dynamodb:Scan",
        "dynamodb:UpdateItem"
      ],
      "Resource": "arn:aws:dynamodb:*:<AWS ACCOUNT ID>:table/<TABLE NAME>"
    }
  ]
}

License

connect-dynamodb is licensed under the MIT license.

Donations

I made this in my spare time, so if you find it useful you can donate at my BTC address: 35dwLrmKHjCgGXyLzBSd6YaTgoXQA17Aoq. Thank you very much!