@prairielearn/aws 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# `@prairielearn/aws`
+
+This package contains utilities that help us correctly configure AWS SDK clients.
+
+Specifically, it's meant to address the fact that clients from the v3 AWS SDK don't share resolved credentials with each other. This means that, by default, every time a new client is created, it has to independently resolve credentials for itself. In production, this is problematic, as that requires talking to the IMDS, which will throttle requests if we make a ton of them in rapid succession. This results in clients being unable to obtain credentials, and thus the AWS API operations fail.
+
+We resolve this with this package, which helps ensure that all AWS SDk clients are constructed with a shared and memoized credential provider.
+
+## Usage
+
+Create a config provider with `makeAwsConfigProvider`:
+
+```ts
+import { makeAwsConfigProvider } from '@prairielearn/aws';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+
+import { config } from './config';
+
+const awsConfigProvider = makeAwsConfigProvider({
+  credentials: fromNodeProviderChain(),
+  getClientConfig: () => ({
+    region: config.awsRegion,
+  }),
+});
+
+export const makeAwsClientConfig = awsConfigProvider.makeAwsClientConfig;
+export const makeS3ClientConfig = awsConfigProvider.makeS3ClientConfig;
+```
+
+Then, use the `makeAwsClientConfig` and `makeS3ClientConfig` functions to configure AWS clients:
+
+```ts
+import { EC2Client } from '@aws-sdk/client-ec2';
+import { S3Client } from '@aws-sdk/client-s3';
+
+const ec2 = new EC2Client(makeAwsClientConfig());
+const s3 = new S3Client(makeS3ClientConfig());
+```
+
+### Providing extra config
+
+The `get...` functions support passing in extra config. If this extra config conflicts with other config, such as that returned from `getClientConfig()`, this extra config will take precedence.
+
+```ts
+const s3 = new S3Client(
+  makeS3ClientConfig({
+    maxAttempts: 3,
+  }),
+);
+```
+
+### Customizing S3 config
+
+The config for S3 clients can be customized independently to support pointing it to other S3-compatible stores.
+
+For instance, to use [`s3rver`](https://github.com/jamhall/s3rver) when running in dev mode, you could use something like the following config:
+
+```ts
+const awsConfigProvider = makeAwsConfigProvider({
+  credentials: fromNodeProviderChain(),
+  getClientConfig: () => ({
+    region: config.awsRegion,
+  }),
+  makeS3ClientConfig: () => {
+    if (process.env.NODE_ENV !== 'production') {
+      return {
+        forcePathStyle: true,
+        credentials: {
+          accessKeyId: 'S3RVER',
+          secretAccessKey: 'S3RVER',
+        },
+        endpoint: 'http://localhost:5000',
+      };
+    }
+
+    return {};
+  },
+});
+```

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+import { AwsCredentialIdentityProvider } from '@smithy/types';
+interface AwsClientConfig {
+    region: string;
+    [key: string]: any;
+}
+export declare function makeAwsConfigProvider({ credentials, getClientConfig, getS3ClientConfig, }: {
+    credentials: AwsCredentialIdentityProvider;
+    getClientConfig: () => AwsClientConfig;
+    getS3ClientConfig?: () => Record<string, any>;
+}): {
+    makeAwsClientConfig: <T extends Record<string, any>>(extraConfig?: T) => {
+        region: string;
+        endpoint: string | undefined;
+        credentials: import("@smithy/types").MemoizedProvider<import("@smithy/types").AwsCredentialIdentity>;
+    } & T;
+    makeS3ClientConfig: <T_1 extends Record<string, any>>(extraConfig?: T_1) => {
+        region: string;
+        endpoint: string | undefined;
+        credentials: import("@smithy/types").MemoizedProvider<import("@smithy/types").AwsCredentialIdentity>;
+    } & {
+        [x: string]: any;
+    } & T_1;
+};
+export {};

package/dist/config.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeAwsConfigProvider = void 0;
+const property_provider_1 = require("@smithy/property-provider");
+// Attempt to refresh credentials 5 minutes before they actually expire.
+// This value is the same value that the AWS SDK uses internally:
+// https://github.com/aws/aws-sdk-js-v3/blob/3f8b581af7c0c8146c5b111f92ba6a024310c525/packages/middleware-signing/src/awsAuthConfiguration.ts#L18
+const CREDENTIAL_EXPIRE_WINDOW = 300000;
+function makeAwsConfigProvider({ credentials, getClientConfig, getS3ClientConfig, }) {
+    // Clients don't share credentials by default, which means that we'll flood
+    // the IMDS with requests for credentials if we construct and use a lot of
+    // clients in quick succession. IMDS has rate-limiting, so we'll end up failing
+    // to get credentials.
+    //
+    // To work around this, we'll share a single credential provider chain across
+    // all clients we create. We'll also memoize the credential provider chain so
+    // that we don't end up making unnecessarily many requests to the IMDS.
+    //
+    // Memoization is based on the following:
+    // https://github.com/aws/aws-sdk-js-v3/blob/3f8b581af7c0c8146c5b111f92ba6a024310c525/packages/middleware-signing/src/awsAuthConfiguration.ts#L257
+    const memoizedCredentials = (0, property_provider_1.memoize)(credentials, (credentials) => credentials.expiration !== undefined &&
+        credentials.expiration.getTime() - Date.now() < CREDENTIAL_EXPIRE_WINDOW, (credentials) => credentials.expiration !== undefined);
+    function makeAwsClientConfig(extraConfig = {}) {
+        return {
+            endpoint: process.env.AWS_ENDPOINT,
+            credentials: memoizedCredentials,
+            ...getClientConfig(),
+            ...extraConfig,
+        };
+    }
+    function makeS3ClientConfig(extraConfig = {}) {
+        return makeAwsClientConfig({
+            ...(getS3ClientConfig?.() ?? {}),
+            ...extraConfig,
+        });
+    }
+    return {
+        makeAwsClientConfig,
+        makeS3ClientConfig,
+    };
+}
+exports.makeAwsConfigProvider = makeAwsConfigProvider;
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AAAA,iEAAoD;AAQpD,wEAAwE;AACxE,iEAAiE;AACjE,iJAAiJ;AACjJ,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAExC,SAAgB,qBAAqB,CAAC,EACpC,WAAW,EACX,eAAe,EACf,iBAAiB,GAKlB;IACC,2EAA2E;IAC3E,0EAA0E;IAC1E,+EAA+E;IAC/E,sBAAsB;IACtB,EAAE;IACF,6EAA6E;IAC7E,6EAA6E;IAC7E,uEAAuE;IACvE,EAAE;IACF,yCAAyC;IACzC,kJAAkJ;IAClJ,MAAM,mBAAmB,GAAG,IAAA,2BAAO,EACjC,WAAW,EACX,CAAC,WAAW,EAAE,EAAE,CACd,WAAW,CAAC,UAAU,KAAK,SAAS;QACpC,WAAW,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,wBAAwB,EAC1E,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,UAAU,KAAK,SAAS,CACtD,CAAC;IAEF,SAAS,mBAAmB,CAAgC,cAAiB,EAAO;QAClF,OAAO;YACL,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY;YAClC,WAAW,EAAE,mBAAmB;YAChC,GAAG,eAAe,EAAE;YACpB,GAAG,WAAW;SACf,CAAC;IACJ,CAAC;IAED,SAAS,kBAAkB,CAAgC,cAAiB,EAAO;QACjF,OAAO,mBAAmB,CAAC;YACzB,GAAG,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,CAAC;YAChC,GAAG,WAAW;SACf,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,mBAAmB;QACnB,kBAAkB;KACnB,CAAC;AACJ,CAAC;AAhDD,sDAgDC"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { makeAwsConfigProvider } from './config';

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeAwsConfigProvider = void 0;
+var config_1 = require("./config");
+Object.defineProperty(exports, "makeAwsConfigProvider", { enumerable: true, get: function () { return config_1.makeAwsConfigProvider; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAiD;AAAxC,+GAAA,qBAAqB,OAAA"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@prairielearn/aws",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrairieLearn/PrairieLearn.git",
+    "directory": "packages/aws"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput"
+  },
+  "devDependencies": {
+    "@prairielearn/tsconfig": "*",
+    "@types/node": "^18.17.14",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "@smithy/property-provider": "^2.0.7",
+    "@smithy/types": "^2.3.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,62 @@
+import { memoize } from '@smithy/property-provider';
+import { AwsCredentialIdentityProvider } from '@smithy/types';
+
+interface AwsClientConfig {
+  region: string;
+  [key: string]: any;
+}
+
+// Attempt to refresh credentials 5 minutes before they actually expire.
+// This value is the same value that the AWS SDK uses internally:
+// https://github.com/aws/aws-sdk-js-v3/blob/3f8b581af7c0c8146c5b111f92ba6a024310c525/packages/middleware-signing/src/awsAuthConfiguration.ts#L18
+const CREDENTIAL_EXPIRE_WINDOW = 300000;
+
+export function makeAwsConfigProvider({
+  credentials,
+  getClientConfig,
+  getS3ClientConfig,
+}: {
+  credentials: AwsCredentialIdentityProvider;
+  getClientConfig: () => AwsClientConfig;
+  getS3ClientConfig?: () => Record<string, any>;
+}) {
+  // Clients don't share credentials by default, which means that we'll flood
+  // the IMDS with requests for credentials if we construct and use a lot of
+  // clients in quick succession. IMDS has rate-limiting, so we'll end up failing
+  // to get credentials.
+  //
+  // To work around this, we'll share a single credential provider chain across
+  // all clients we create. We'll also memoize the credential provider chain so
+  // that we don't end up making unnecessarily many requests to the IMDS.
+  //
+  // Memoization is based on the following:
+  // https://github.com/aws/aws-sdk-js-v3/blob/3f8b581af7c0c8146c5b111f92ba6a024310c525/packages/middleware-signing/src/awsAuthConfiguration.ts#L257
+  const memoizedCredentials = memoize(
+    credentials,
+    (credentials) =>
+      credentials.expiration !== undefined &&
+      credentials.expiration.getTime() - Date.now() < CREDENTIAL_EXPIRE_WINDOW,
+    (credentials) => credentials.expiration !== undefined,
+  );
+
+  function makeAwsClientConfig<T extends Record<string, any>>(extraConfig: T = {} as T) {
+    return {
+      endpoint: process.env.AWS_ENDPOINT,
+      credentials: memoizedCredentials,
+      ...getClientConfig(),
+      ...extraConfig,
+    };
+  }
+
+  function makeS3ClientConfig<T extends Record<string, any>>(extraConfig: T = {} as T) {
+    return makeAwsClientConfig({
+      ...(getS3ClientConfig?.() ?? {}),
+      ...extraConfig,
+    });
+  }
+
+  return {
+    makeAwsClientConfig,
+    makeS3ClientConfig,
+  };
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { makeAwsConfigProvider } from './config';

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@prairielearn/tsconfig/tsconfig.package.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  }
+}