launchdarkly/node-server-sdk-dynamodb

DynamoDB integration for the LaunchDarkly SDK for Server-side Node.js

LaunchDarkly Server-Side SDK for Node.js - DynamoDB integration

⚠️ Important note

This integration in this does not work with version 8.0+ of the Node.js Server-Side SDK. Future development of this integration will be done here node-server-sdk-dynamodb. Please note the package has also been renamed from launchdarkly-node-server-sdk-dynamodb to @launchdarkly/node-server-sdk-dynamodb.

As mentioned in the node server sdk changelog, the launchdarkly-node-server-sdk project has been renamed to @launchdarkly/node-server-sdk. All future releases will be made from the new repository. Please consider upgrading and filing potential requests in that repository's issue tracker.

This library provides a DynamoDB-backed persistence mechanism (feature store) for the LaunchDarkly Node.js SDK, replacing the default in-memory feature store. It uses the AWS SDK for Node.js.

The minimum version of the LaunchDarkly Node.js SDK for use with this library is 6.2.0.

For more information, read the SDK features guide.

TypeScript API documentation is here.

Quick setup

This assumes that you have already installed the LaunchDarkly Node.js SDK.

1. In DynamoDB, create a table which has the following schema: a partition key called "namespace" and a sort key called "key", both with a string type. The LaunchDarkly library does not create the table automatically, because it has no way of knowing what additional properties (such as permissions and throughput) you would want it to have.

2. Install this package with npm:

    npm install launchdarkly-node-server-sdk-dynamodb --save
   

3. If your application does not already have its own dependency on the aws-sdk package, and if it will not be running in AWS Lambda, add aws-sdk as well:

    npm install aws-sdk --save
   

   The launchdarkly-node-server-sdk-dynamodb package does not provide aws-sdk as a transitive dependency, because it is provided automatically by the Lambda runtime and this would unnecessarily increase the size of applications deployed in Lambda. Therefore, if you are not using Lambda you need to provide aws-sdk separately.

4. Require the package:

    const { DynamoDBFeatureStore } = require('launchdarkly-node-server-sdk-dynamodb');
   

5. When configuring your SDK client, add the DynamoDB feature store:

    const store = DynamoDBFeatureStore('YOUR TABLE NAME');
    const config = { featureStore: store };
    const client = LaunchDarkly.init('YOUR SDK KEY', config);
   

   By default, the DynamoDB client will try to get your AWS credentials and region name from environment variables and/or local configuration files, as described in the AWS SDK documentation. You can also specify any valid DynamoDB client options like this:

    const dynamoDBOptions = { accessKeyId: 'YOUR KEY', secretAccessKey: 'YOUR SECRET' };
    const store = DynamoDBFeatureStore('YOUR TABLE NAME', { clientOptions: dynamoDBOptions });
   

   Alternatively, if you already have a fully configured DynamoDB client object, you can tell LaunchDarkly to use that:

    const store = DynamoDBFeatureStore('YOUR TABLE NAME', { dynamoDBClient: myDynamoDBClientInstance });
   

6. If you are running a LaunchDarkly Relay Proxy instance, or any other process that will prepopulate the DynamoDB table with feature flags from LaunchDarkly, you can use daemon mode, so that the SDK retrieves flag data only from DynamoDB and does not communicate directly with LaunchDarkly. This is controlled by the SDK's useLdd option:

    const config = { featureStore: store, useLdd: true };
    const client = LaunchDarkly.init('YOUR SDK KEY', config);
   

7. If the same DynamoDB table is being shared by SDK clients for different LaunchDarkly environments, set the prefix option to a different short string for each one to keep the keys from colliding:

    const store = DynamoDBFeatureStore('YOUR TABLE NAME', { prefix: 'env1' });
   

Caching behavior

To reduce traffic to DynamoDB, there is an optional in-memory cache that retains the last known data for a configurable amount of time. This is on by default; to turn it off (and guarantee that the latest feature flag data will always be retrieved from DynamoDB for every flag evaluation), configure the store as follows:

    const store = DynamoDBFeatureStore('YOUR TABLE NAME', { cacheTTL: 0 });

Data size limitation

DynamoDB has a 400KB limit on the size of any data item. For the LaunchDarkly SDK, a data item consists of the JSON representation of an individual feature flag or segment configuration, plus a few smaller attributes. You can see the format and size of these representations by querying https://sdk.launchdarkly.com/flags/latest-all and setting the Authorization header to your SDK key.

Most flags and segments won't be nearly as big as 400KB, but they could be if for instance you have a long list of user keys for individual user targeting. If the flag or segment representation is too large, it cannot be stored in DynamoDB. To avoid disrupting storage and evaluation of other unrelated feature flags, the SDK will simply skip storing that individual flag or segment, and will log a message (at ERROR level) describing the problem. For example:

    The item "my-flag-key" in "features" was too large to store in DynamoDB and was dropped

If caching is enabled in your configuration, the flag or segment may still be available in the SDK from the in-memory cache, but do not rely on this. If you see this message, consider redesigning your flag/segment configurations, or else do not use DynamoDB for the environment that contains this data item.

This limitation does not apply to target lists in Big Segments.

A future version of the LaunchDarkly DynamoDB integration may use different strategies to work around this limitation, such as compressing the data or dividing it into multiple items. However, this integration is required to be interoperable with the DynamoDB integrations used by all the other LaunchDarkly SDKs and by the Relay Proxy, so any such change will only be made as part of a larger cross-platform release.

About LaunchDarkly

• LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
  • Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
  • Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
  • Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
  • Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan). Disable parts of your application to facilitate maintenance, without taking everything offline.
• LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Check out our documentation for a complete list.
• Explore LaunchDarkly
  • launchdarkly.com for more information
  • docs.launchdarkly.com for our documentation and SDK reference guides
  • apidocs.launchdarkly.com for our API documentation
  • blog.launchdarkly.com for the latest product updates

node-server-sdk-dynamodb's Issues

NPM bundle is kinda on the huge side

We are using this package in a lambda (as might be a pretty common use case for using DynamoDB as a flag store).

When this package is included it adds nearly 100MB to the lambda bundle.

Half of that is because it ships the AWS SDK as a required dep, which maybe be moved to a peerDep, unless you think the specific version you are using is critical to stability.

The other half is becuase typedoc is also shipped as a required dep. Seems like that could be moved to a devDep since I'm assuming it is used to generate your documentation, and not part of the production executed library.

We had one of our lambdas tip over the size limit when we included this package.

Typescript definitions are wrong

The current TypeScript definitions throw type errors when the package is imported.

When imported as such:

import DynamoDBFeatureStore from 'launchdarkly-node-server-sdk-dynamodb'

The following type error is emitted from the compiler:

Cannot invoke an expression whose type lacks a call signature. Type 'typeof import("launchdarkly-node-server-sdk-dynamodb")' has no compatible call signatures.

This is because the default import has not been properly tagged, and so typescript thinks that DynamoDBFeatureStore is a named import and wants you to import like so:

import { DynamoDBFeatureStore } from 'launchdarkly-node-server-sdk-dynamodb'

But then at run time, this throws an error because that named import does not actually exist.

Support for @aws-sdk v3

aws-sdk has gone into maintenance mode as of 2023 and will not be receiving new updates. We are looking to migrate all of our existing uses into @AWS-SDK v3 clients which helps reduce our bundle size while running on Node20 lambdas as the sdk v2 is no longer provided by default it now has to be installed in each of our packages and increases our bundles.

I tried to update our launchdarkly package wrapper and noticed when trying to pass sdk v3 DocumentClient into launchdarkly-node-server-sdk-dynamodb it won't accept it because it's only accepting the type from sdk v2

dynamoDBClient?: DynamoDB.DocumentClient; which is defined here: https://github.com/launchdarkly/node-server-sdk-dynamodb/blob/main/index.d.ts#L55

Ideally we would be able to provide appropriate classes for aws-sdk v3 instead of only using v2.

LD Client with DynamoDBFeatureStore fails with 'cannot read property error from undefined' on any error with DynamoDB

Hey! I am trying to adopt LD in AWS Serverless and trying to use DynamoDBFeatureStore and found a little issue there.

If there is any error with DymamoDB (like lack of permissions or not such table) I receive crash from LD CLient with cannot read property error from undefined message.

After some investigation I found out that:

1. config (DynamoDBFeatureStore(...)(config)) is LDOptions
2. LDOptions does not require logger
3. But DynamoDBFeatureStore actually requires it.
4. So if anything bad happens (like here), SDK will just crash.

My assumption that logger should not be required in DynamoDBFeatureStore (it might be default to something like console perhaps).

I might be wrong as well, and it would be nice if someone explains this behavior to me)

Thanks for looking into it :)

Required DynamoDB permissions for `feature store` and `big segments`

Hi LaunchDarkly team,

Our team is so keen to know which DynamoDB permissions are required in our infrastructure in order to benefit from feature store and big segments in Node SDK. Would you be able to elaborate on this or steer me to the right documents or more info, please?

Any plans to migrate to `aws-sdk` v3?

AWS recently announced the deprecation of aws-sdk v2. Do you have a timeframe on migrating to the v3 SDK?

Deprecation info: https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/#Version_2_x_Support

Ignore documents bigger than 400KB

Is it possible to automatically ignore documents which are greater than 400KB in size?

This would not break synchronization process.

I can create a PR if you will accept it