@prairielearn/config 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# `@prairielearn/config`
+
+Utilities to help load configuration from various sources including a JSON file and AWS Secrets Manager. Config is made type-safe through a [Zod](https://github.com/colinhacks/zod) schema.
+
+This package _should not_ be depended upon by other packages directly. Instead, import it into your application, load the config, and then provide any necessary values to other packages.
+
+## Usage
+
+```ts
+import { ConfigLoader, makeFileConfig } from '@prairielearn/config';
+import { z } from 'zod';
+
+const ConfigSchema = z.object({
+  hello: z.string().default('world'),
+});
+
+const configLoader = new ConfigLoader(ConfigSchema);
+
+await configLoader.loadAndValidate([makeFileConfig('config.json')]);
+
+console.log(configLoader.config);
+// { hello: "world" }
+```
+
+Typically, you'll want to have a `config.ts` file in your own project that encapsulates this. Then, you can import the config elsewhere in the project.
+
+```ts
+import { ConfigLoader, makeFileConfig } from '@prairielearn/config';
+import { z } from 'zod';
+
+const configLoader = new ConfigLoader(z.any());
+
+export async function loadAndValidate(path: string) {
+  await configLoader.loadAndValidate([makeFileConfig(path)]);
+}
+
+export default configLoader.config;
+```
+
+### Loading config from AWS
+
+If you're running in AWS, you can use `makeImdsConfig()` and `makeSecretsManagerConfig()` to load config from IMDS and Secrets Manager, respectively:
+
+- `makeImdsConfig()` will load `hostname`, `instanceId`, and `region`, which will be available if you config schema contains these values.
+- `makeSecretsManagerConfig()` will look for a `ConfSecret` tag on the instance. If found, the value of that tag will be used treated as a Secrets Manager secret ID, and that secret's value will be parsed as JSON and merged into the config.
+
+Note that both of these config sources are no-ops by default. To active them, you must do one of the following:
+
+- Set `CONFIG_LOAD_FROM_AWS=1` in the process environment.
+- Chain them after `makeFileConfig()`, and ensure that the config file contains `{"runningInEc2": true}`.

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+declare const AbstractConfigSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+type AbstractConfig = z.infer<typeof AbstractConfigSchema>;
+interface ConfigSource {
+    load: (existingConfig: AbstractConfig) => Promise<AbstractConfig>;
+}
+export declare function makeLiteralConfigSource(config: AbstractConfig): {
+    load: () => Promise<Record<string, unknown>>;
+};
+export declare function makeFileConfigSource(path: string): ConfigSource;
+export declare function makeSecretsManagerConfigSource(tagKey: string): ConfigSource;
+export declare function makeImdsConfigSource(): ConfigSource;
+export declare class ConfigLoader<Schema extends z.ZodTypeAny> {
+    private readonly schema;
+    private readonly resolvedConfig;
+    constructor(schema: Schema);
+    loadAndValidate(sources?: ConfigSource[]): Promise<void>;
+    get config(): z.TypeOf<Schema>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = exports.makeImdsConfigSource = exports.makeSecretsManagerConfigSource = exports.makeFileConfigSource = exports.makeLiteralConfigSource = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const zod_1 = require("zod");
+const client_ec2_1 = require("@aws-sdk/client-ec2");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const aws_imds_1 = require("@prairielearn/aws-imds");
+const AbstractConfigSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.unknown());
+function makeLiteralConfigSource(config) {
+    return {
+        load: async () => config,
+    };
+}
+exports.makeLiteralConfigSource = makeLiteralConfigSource;
+function makeFileConfigSource(path) {
+    return {
+        load: async () => {
+            if (!(await fs_extra_1.default.pathExists(path)))
+                return {};
+            const config = await fs_extra_1.default.readJson(path);
+            return zod_1.z.record(zod_1.z.string(), zod_1.z.any()).parse(config);
+        },
+    };
+}
+exports.makeFileConfigSource = makeFileConfigSource;
+function makeSecretsManagerConfigSource(tagKey) {
+    return {
+        load: async (existingConfig) => {
+            if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {
+                return {};
+            }
+            const identity = await (0, aws_imds_1.fetchInstanceIdentity)();
+            const ec2Client = new client_ec2_1.EC2Client({ region: identity.region });
+            const tags = await ec2Client.send(new client_ec2_1.DescribeTagsCommand({
+                Filters: [{ Name: 'resource-id', Values: [identity.instanceId] }],
+            }));
+            const secretId = tags.Tags?.find((tag) => tag.Key === tagKey)?.Value;
+            if (!secretId)
+                return {};
+            const secretsManagerClient = new client_secrets_manager_1.SecretsManagerClient({ region: identity.region });
+            const secretValue = await secretsManagerClient.send(new client_secrets_manager_1.GetSecretValueCommand({ SecretId: secretId }));
+            if (!secretValue.SecretString)
+                return {};
+            const config = JSON.parse(secretValue.SecretString);
+            return zod_1.z.record(zod_1.z.string(), zod_1.z.any()).parse(config);
+        },
+    };
+}
+exports.makeSecretsManagerConfigSource = makeSecretsManagerConfigSource;
+function makeImdsConfigSource() {
+    return {
+        load: async (existingConfig) => {
+            if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {
+                return {};
+            }
+            const hostname = await (0, aws_imds_1.fetchInstanceHostname)();
+            const identity = await (0, aws_imds_1.fetchInstanceIdentity)();
+            return {
+                hostname,
+                instanceId: identity.instanceId,
+                region: identity.region,
+            };
+        },
+    };
+}
+exports.makeImdsConfigSource = makeImdsConfigSource;
+class ConfigLoader {
+    constructor(schema) {
+        this.schema = schema;
+        // Get the default values from the schema. This ensures that all values
+        // have defaults, and also allows us to override nested defaults with
+        // `_.merge()` in `loadAndValidate()`.
+        this.resolvedConfig = schema.parse({});
+    }
+    async loadAndValidate(sources = []) {
+        let config = this.schema.parse({});
+        for (const source of sources) {
+            config = lodash_1.default.merge(config, await source.load(config));
+        }
+        const parsedConfig = this.schema.parse(config);
+        lodash_1.default.merge(this.resolvedConfig, parsedConfig);
+    }
+    get config() {
+        return this.resolvedConfig;
+    }
+}
+exports.ConfigLoader = ConfigLoader;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const promises_1 = require("node:fs/promises");
+const tmp_promise_1 = require("tmp-promise");
+const zod_1 = require("zod");
+const index_1 = require("./index");
+describe('config', () => {
+    it('loads config with defaults', async () => {
+        const schema = zod_1.z.object({
+            foo: zod_1.z.string().nullable().default(null),
+            bar: zod_1.z.string().default('bar'),
+        });
+        const loader = new index_1.ConfigLoader(schema);
+        await loader.loadAndValidate();
+        chai_1.assert.equal(loader.config.foo, null);
+        chai_1.assert.equal(loader.config.bar, 'bar');
+    });
+    it('loads config from a file', async () => {
+        const schema = zod_1.z.object({
+            foo: zod_1.z.string().optional().nullable(),
+            bar: zod_1.z.string().default('bar'),
+            baz: zod_1.z.string().default('baz'),
+        });
+        const loader = new index_1.ConfigLoader(schema);
+        await (0, tmp_promise_1.withFile)(async ({ path }) => {
+            await (0, promises_1.writeFile)(path, JSON.stringify({ foo: 'bar', bar: 'bar' }));
+            await loader.loadAndValidate([(0, index_1.makeFileConfigSource)(path)]);
+        });
+        chai_1.assert.equal(loader.config.foo, 'bar');
+        chai_1.assert.equal(loader.config.bar, 'bar');
+        chai_1.assert.equal(loader.config.baz, 'baz');
+    });
+    it('overrides deep objects', async () => {
+        const schema = zod_1.z.object({
+            features: zod_1.z.record(zod_1.z.string(), zod_1.z.boolean()).default({
+                foo: true,
+                bar: false,
+            }),
+        });
+        const loader = new index_1.ConfigLoader(schema);
+        await loader.loadAndValidate([
+            (0, index_1.makeLiteralConfigSource)({
+                features: {
+                    foo: false,
+                    baz: true,
+                },
+            }),
+        ]);
+        chai_1.assert.equal(loader.config.features.foo, false);
+        chai_1.assert.equal(loader.config.features.bar, false);
+        chai_1.assert.equal(loader.config.features.baz, true);
+    });
+    it('maintains object identity when loading config', async () => {
+        const schema = zod_1.z.object({});
+        const loader = new index_1.ConfigLoader(schema);
+        const config = loader.config;
+        await loader.loadAndValidate();
+        chai_1.assert.strictEqual(config, loader.config);
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@prairielearn/config",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "test": "mocha --no-config --require ts-node/register src/**/*.test.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-ec2": "^3.304.0",
+    "@aws-sdk/client-secrets-manager": "^3.303.0",
+    "@prairielearn/aws-imds": "workspace:^",
+    "fs-extra": "^11.1.1",
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "@prairielearn/tsconfig": "*",
+    "@types/fs-extra": "^11.0.1",
+    "@types/lodash": "^4.14.194",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^18.14.2",
+    "mocha": "^10.2.0",
+    "tmp-promise": "^3.0.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.5"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,72 @@
+import { assert } from 'chai';
+import { writeFile } from 'node:fs/promises';
+import { withFile } from 'tmp-promise';
+import { z } from 'zod';
+
+import { ConfigLoader, makeLiteralConfigSource, makeFileConfigSource } from './index';
+
+describe('config', () => {
+  it('loads config with defaults', async () => {
+    const schema = z.object({
+      foo: z.string().nullable().default(null),
+      bar: z.string().default('bar'),
+    });
+    const loader = new ConfigLoader(schema);
+
+    await loader.loadAndValidate();
+
+    assert.equal(loader.config.foo, null);
+    assert.equal(loader.config.bar, 'bar');
+  });
+
+  it('loads config from a file', async () => {
+    const schema = z.object({
+      foo: z.string().optional().nullable(),
+      bar: z.string().default('bar'),
+      baz: z.string().default('baz'),
+    });
+    const loader = new ConfigLoader(schema);
+
+    await withFile(async ({ path }) => {
+      await writeFile(path, JSON.stringify({ foo: 'bar', bar: 'bar' }));
+      await loader.loadAndValidate([makeFileConfigSource(path)]);
+    });
+
+    assert.equal(loader.config.foo, 'bar');
+    assert.equal(loader.config.bar, 'bar');
+    assert.equal(loader.config.baz, 'baz');
+  });
+
+  it('overrides deep objects', async () => {
+    const schema = z.object({
+      features: z.record(z.string(), z.boolean()).default({
+        foo: true,
+        bar: false,
+      }),
+    });
+    const loader = new ConfigLoader(schema);
+
+    await loader.loadAndValidate([
+      makeLiteralConfigSource({
+        features: {
+          foo: false,
+          baz: true,
+        },
+      }),
+    ]);
+
+    assert.equal(loader.config.features.foo, false);
+    assert.equal(loader.config.features.bar, false);
+    assert.equal(loader.config.features.baz, true);
+  });
+
+  it('maintains object identity when loading config', async () => {
+    const schema = z.object({});
+    const loader = new ConfigLoader(schema);
+    const config = loader.config;
+
+    await loader.loadAndValidate();
+
+    assert.strictEqual(config, loader.config);
+  });
+});

package/src/index.ts

@@ -0,0 +1,109 @@
+import _ from 'lodash';
+import fs from 'fs-extra';
+import { z } from 'zod';
+import { EC2Client, DescribeTagsCommand } from '@aws-sdk/client-ec2';
+import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
+import { fetchInstanceHostname, fetchInstanceIdentity } from '@prairielearn/aws-imds';
+
+const AbstractConfigSchema = z.record(z.string(), z.unknown());
+type AbstractConfig = z.infer<typeof AbstractConfigSchema>;
+
+interface ConfigSource {
+  load: (existingConfig: AbstractConfig) => Promise<AbstractConfig>;
+}
+
+export function makeLiteralConfigSource(config: AbstractConfig) {
+  return {
+    load: async () => config,
+  };
+}
+
+export function makeFileConfigSource(path: string): ConfigSource {
+  return {
+    load: async () => {
+      if (!(await fs.pathExists(path))) return {};
+
+      const config = await fs.readJson(path);
+      return z.record(z.string(), z.any()).parse(config);
+    },
+  };
+}
+
+export function makeSecretsManagerConfigSource(tagKey: string): ConfigSource {
+  return {
+    load: async (existingConfig) => {
+      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {
+        return {};
+      }
+
+      const identity = await fetchInstanceIdentity();
+
+      const ec2Client = new EC2Client({ region: identity.region });
+      const tags = await ec2Client.send(
+        new DescribeTagsCommand({
+          Filters: [{ Name: 'resource-id', Values: [identity.instanceId] }],
+        })
+      );
+
+      const secretId = tags.Tags?.find((tag) => tag.Key === tagKey)?.Value;
+      if (!secretId) return {};
+
+      const secretsManagerClient = new SecretsManagerClient({ region: identity.region });
+      const secretValue = await secretsManagerClient.send(
+        new GetSecretValueCommand({ SecretId: secretId })
+      );
+      if (!secretValue.SecretString) return {};
+
+      const config = JSON.parse(secretValue.SecretString);
+      return z.record(z.string(), z.any()).parse(config);
+    },
+  };
+}
+
+export function makeImdsConfigSource(): ConfigSource {
+  return {
+    load: async (existingConfig) => {
+      if (!existingConfig.runningInEc2 && !process.env.CONFIG_LOAD_FROM_AWS) {
+        return {};
+      }
+
+      const hostname = await fetchInstanceHostname();
+      const identity = await fetchInstanceIdentity();
+
+      return {
+        hostname,
+        instanceId: identity.instanceId,
+        region: identity.region,
+      };
+    },
+  };
+}
+
+export class ConfigLoader<Schema extends z.ZodTypeAny> {
+  private readonly schema: Schema;
+  private readonly resolvedConfig: z.infer<Schema>;
+
+  constructor(schema: Schema) {
+    this.schema = schema;
+
+    // Get the default values from the schema. This ensures that all values
+    // have defaults, and also allows us to override nested defaults with
+    // `_.merge()` in `loadAndValidate()`.
+    this.resolvedConfig = schema.parse({});
+  }
+
+  async loadAndValidate(sources: ConfigSource[] = []) {
+    let config = this.schema.parse({});
+
+    for (const source of sources) {
+      config = _.merge(config, await source.load(config));
+    }
+
+    const parsedConfig = this.schema.parse(config);
+    _.merge(this.resolvedConfig, parsedConfig);
+  }
+
+  get config() {
+    return this.resolvedConfig;
+  }
+}

package/tsconfig.json

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