aws-appconfig-poller

This library polls AWS AppConfig on a background thread so your app has instant access to a cached version of your configuration. It relies on the official @aws-sdk/client-appconfigdata library to fetch the data.

Although AWS seems to recommend their simplified retrieval methods for fetching AppConfig, i.e. running an agent in a separate process, you may prefer to use this library:

• You don't need to set up a lambda extension.
• You easily get parity between your local development server and prod.
• The parsed version of your config is conveniently cached.
• You get reporting of transient errors while the library works in the background to recover.

Usage

Initialize:

import { AppConfigDataClient } from '@aws-sdk/client-appconfigdata';
import { Poller } from 'aws-appconfig-poller';

const dataClient = new AppConfigDataClient({
  // Set up credentials, region, etc, as necessary.
  credentials: undefined,
});

const poller = new Poller({
  dataClient: dataClient,
  sessionConfig: {
    // This configuration will be specific to your app
    ApplicationIdentifier: 'MyApp',
    EnvironmentIdentifier: 'Test',
    ConfigurationProfileIdentifier: 'Config1',
  },
  logger: console.log,
  // Turn the config string into an object however you like,
  // we'll cache the result (and also the raw string).
  configParser: (s: string) => JSON.parse(s),
});

// We avoid bubbling up exceptions, and keep trying in the background
// even if we were  not initially successful.
const { isInitiallySuccessful, error } = await poller.start();

Fetch:

// Instantly returns the cached configuration object that was
// polled in the background.
const { latestValue } = poller.getConfigurationObject();

For full working code, see examples/infinitePoller.ts.

Error handling

A few things can go wrong when polling for AppConfig, such as:

• Permissions or networking error connecting to AWS.
• The config document could have been changed to something your configParser can't handle.

If there's an immediate connection problem during startup, and we're unable to retrieve the configuration even once, we'll report it in the response from poller.start(), and continue attempting to connect in the background.

If we startup successfully, but some time later there are problems polling, we'll report the error via the errorCausingStaleValue response attribute and continue polling in hopes that the error resolves itself. You may wish to monitor or alarm on this situation because your config object is potentially outdated.

const { latestValue, errorCausingStaleValue } = poller.getConfigurationObject();
if (errorCausingStaleValue) {
  // Log some metric
}

License

Licensed under the MIT license. See the LICENSE file for details.