From 95dbcfd84124aee42b28e16833cd877c084946b4 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Fri, 31 Mar 2023 16:31:33 +0200 Subject: [PATCH] config-loader: document the rest of the config sources Signed-off-by: Patrik Oldsberg --- .../src/sources/EnvConfigSource.ts | 48 +++++++++++++++++-- .../src/sources/FileConfigSource.ts | 23 ++++++++- .../src/sources/RemoteConfigSource.ts | 29 +++++++++++ .../src/sources/StaticConfigSource.ts | 16 +++++++ 4 files changed, 110 insertions(+), 6 deletions(-) diff --git a/packages/config-loader/src/sources/EnvConfigSource.ts b/packages/config-loader/src/sources/EnvConfigSource.ts index f2c74704c4..ccd7e37e11 100644 --- a/packages/config-loader/src/sources/EnvConfigSource.ts +++ b/packages/config-loader/src/sources/EnvConfigSource.ts @@ -19,12 +19,48 @@ import { assertError } from '@backstage/errors'; import { JsonObject } from '@backstage/types'; import { AsyncConfigSourceIterator, ConfigSource } from './types'; +/** + * Options for {@link EnvConfigSource.create}. + * + * @public + */ +export interface EnvConfigSourceOptions { + /** + * The environment variables to use, defaults to {@link process.env}. + */ + env?: Record; +} + +/** + * A config source that reads configuration from the environment. + * + * @remarks + * + * Only environment variables prefixed with APP_CONFIG_ will be considered. + * + * For each variable, the prefix will be removed, and rest of the key will + * be split by '_'. Each part will then be used as keys to build up a nested + * config object structure. The treatment of the entire environment variable + * is case-sensitive. + * + * The value of the variable should be JSON serialized, as it will be parsed + * and the type will be kept intact. For example "true" and true are treated + * differently, as well as "42" and 42. + * + * For example, to set the config app.title to "My Title", use the following: + * + * APP_CONFIG_app_title='"My Title"' + * + * @public + */ export class EnvConfigSource implements ConfigSource { - static create(options: { - env?: { - [name: string]: string | undefined; - }; - }): ConfigSource { + /** + * Creates a new config source that reads from the environment. + * + * @param options - Options for the config source. + * @returns A new config source that reads from the environment. + */ + static create(options: EnvConfigSourceOptions): ConfigSource { return new EnvConfigSource(options?.env ?? process.env); } @@ -47,6 +83,8 @@ const CONFIG_KEY_PART_PATTERN = /^[a-z][a-z0-9]*(?:[-_][a-z][a-z0-9]*)*$/i; /** * Read runtime configuration from the environment. * + * @remarks + * * Only environment variables prefixed with APP_CONFIG_ will be considered. * * For each variable, the prefix will be removed, and rest of the key will diff --git a/packages/config-loader/src/sources/FileConfigSource.ts b/packages/config-loader/src/sources/FileConfigSource.ts index f7b98c26cb..7d2e14700d 100644 --- a/packages/config-loader/src/sources/FileConfigSource.ts +++ b/packages/config-loader/src/sources/FileConfigSource.ts @@ -27,18 +27,39 @@ import { } from './types'; import { createConfigTransformer } from './transform'; +/** + * Options for {@link FileConfigSource.create}. + * + * @public + */ export interface FileConfigSourceOptions { /** * The path to the config file that should be loaded. */ path: string; + /** - * Function used to resolve environment variables. + * A substitution function to use instead of the default environment substitution. */ substitutionFunc?: SubstitutionFunc; } +/** + * A config source that loads configuration from a local file. + * + * @public + */ export class FileConfigSource implements ConfigSource { + /** + * Creates a new config source that loads configuration from the given path. + * + * @remarks + * + * The source will watch the file for changes, as well as any referenced files. + * + * @param options - Options for the config source. + * @returns A new config source that loads from the given path. + */ static create(options: FileConfigSourceOptions): ConfigSource { if (!isAbsolute(options.path)) { throw new Error(`Config load path is not absolute: '${options.path}'`); diff --git a/packages/config-loader/src/sources/RemoteConfigSource.ts b/packages/config-loader/src/sources/RemoteConfigSource.ts index b7fb5b81af..64e3c082ad 100644 --- a/packages/config-loader/src/sources/RemoteConfigSource.ts +++ b/packages/config-loader/src/sources/RemoteConfigSource.ts @@ -29,13 +29,42 @@ import { const DEFAULT_RELOAD_INTERVAL_SECONDS = 60; +/** + * Options for {@link RemoteConfigSource.create}. + * + * @public + */ export interface RemoteConfigSourceOptions { + /** + * The URL to load the config from. + */ url: string; + + /** + * The interval in seconds to reload the config from the remote URL. + * + * Set to Infinity to disable reloading. + */ reloadIntervalSeconds?: number; + + /** + * A substitution function to use instead of the default environment substitution. + */ substitutionFunc?: SubstitutionFunc; } +/** + * A config source that loads configuration from a remote URL. + * + * @public + */ export class RemoteConfigSource implements ConfigSource { + /** + * Creates a new {@link RemoteConfigSource}. + * + * @param options - Options for the source. + * @returns A new remote config source. + */ static create(options: RemoteConfigSourceOptions): ConfigSource { try { // eslint-disable-next-line no-new diff --git a/packages/config-loader/src/sources/StaticConfigSource.ts b/packages/config-loader/src/sources/StaticConfigSource.ts index 22b53abded..7f813b228e 100644 --- a/packages/config-loader/src/sources/StaticConfigSource.ts +++ b/packages/config-loader/src/sources/StaticConfigSource.ts @@ -22,6 +22,11 @@ import { } from './types'; import { simpleDefer } from './utils'; +/** + * Options for {@link StaticConfigSource.create}. + * + * @public + */ export interface StaticConfigSourceOptions { data: | JsonObject @@ -81,7 +86,18 @@ function isAsyncIterable(value: {}): value is AsyncIterable { return Symbol.asyncIterator in value; } +/** + * A configuration source that reads from a static object, promise, iterable, or observable. + * + * @public + */ export class StaticConfigSource implements ConfigSource { + /** + * Creates a new {@link StaticConfigSource}. + * + * @param options - Options for the config source + * @returns A new static config source + */ static create(options: StaticConfigSourceOptions): ConfigSource { const { data, context = 'static-config' } = options; if (!data) {