Skip to content

Commit 268ea1e

Browse files
dreamorosidreamorosi
committed
docs: wrote api docs for SecretsProvider
1 parent c02149e commit 268ea1e

File tree

3 files changed

+277
-0
lines changed

3 files changed

+277
-0
lines changed

Diff for: ‎packages/parameters/src/secrets/SecretsProvider.ts

+166
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,146 @@ import type {
99
SecretsGetOptionsInterface
1010
} from '../types/SecretsProvider';
1111

12+
/**
13+
* ## Intro
14+
* The Parameters utility provides a SecretsProvider that allows to retrieve secrets from AWS Secrets Manager.
15+
*
16+
* ## Getting started
17+
*
18+
* This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only
19+
* the SDK packages you need and keep your bundle size small.
20+
*
21+
* To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for Secrets Manager:
22+
*
23+
* ```sh
24+
* npm install @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager
25+
* ```
26+
*
27+
* ## Basic usage
28+
*
29+
* @example
30+
* ```typescript
31+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
32+
*
33+
* const secretsProvider = new SecretsProvider();
34+
*
35+
* export const handler = async (): Promise<void> => {
36+
* // Retrieve a single secret
37+
* const secret = await secretsProvider.get('my-secret');
38+
* };
39+
* ```
40+
*
41+
* If you want to retrieve secrets without customizing the provider, you can use the {@link getSecret} function instead.
42+
*
43+
* ## Advanced usage
44+
*
45+
* ### Caching
46+
*
47+
* By default, the provider will cache parameters retrieved in-memory for 5 seconds.
48+
* You can adjust how long values should be kept in cache by using the `maxAge` parameter.
49+
*
50+
* @example
51+
* ```typescript
52+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
53+
*
54+
* const secretsProvider = new SecretsProvider();
55+
*
56+
* export const handler = async (): Promise<void> => {
57+
* // Retrieve a single secret and cache it for 10 seconds
58+
* const secret = await secretsProvider.get('my-secret', { maxAge: 10 });
59+
* };
60+
* ```
61+
*
62+
* If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the `forceFetch` parameter.
63+
*
64+
* @example
65+
* ```typescript
66+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
67+
*
68+
* const secretsProvider = new SecretsProvider();
69+
*
70+
* export const handler = async (): Promise<void> => {
71+
* // Retrieve a single secret and always fetch the latest value
72+
* const secret = await secretsProvider.get('my-secret', { forceFetch: true });
73+
* };
74+
* ```
75+
*
76+
* ### Transformations
77+
*
78+
* For parameters stored in JSON or Base64 format, you can use the transform argument for deserialization.
79+
*
80+
* @example
81+
* ```typescript
82+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
83+
*
84+
* const secretsProvider = new SecretsProvider();
85+
*
86+
* export const handler = async (): Promise<void> => {
87+
* // Retrieve a single secret and deserialize it as JSON
88+
* const secret = await secretsProvider.get('my-secret', { transform: 'json' });
89+
* };
90+
* ```
91+
*
92+
* ### Extra SDK options
93+
*
94+
* When retrieving a secret, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter.
95+
*
96+
* @example
97+
* ```typescript
98+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
99+
*
100+
* const secretsProvider = new SecretsProvider();
101+
*
102+
* export const handler = async (): Promise<void> => {
103+
* // Retrieve a single secret and pass extra options to the AWS SDK v3 for JavaScript client
104+
* const secret = await secretsProvider.get('my-secret', {
105+
* sdkOptions: {
106+
* VersionId: 1,
107+
* },
108+
* });
109+
* };
110+
* ```
111+
*
112+
* This object accepts the same options as the [AWS SDK v3 for JavaScript Secrets Manager client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-secrets-manager/interfaces/getsecretvaluecommandinput.html).
113+
*
114+
* ### Customize AWS SDK v3 for JavaScript client
115+
*
116+
* By default, the provider will create a new Secrets Manager client using the default configuration.
117+
*
118+
* You can customize the client by passing a custom configuration object to the provider.
119+
*
120+
* @example
121+
* ```typescript
122+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
123+
*
124+
* const secretsProvider = new SecretsProvider({
125+
* clientConfig: { region: 'eu-west-1' },
126+
* });
127+
* ```
128+
*
129+
* This object accepts the same options as the [AWS SDK v3 for JavaScript Secrets Manager client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-secrets-manager/interfaces/secretsmanagerclientconfig.html).
130+
*
131+
* Otherwise, if you want to use a custom client altogether, you can pass it to the provider.
132+
*
133+
* @example
134+
* ```typescript
135+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
136+
* import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
137+
*
138+
* const client = new SecretsManagerClient({ region: 'eu-west-1' });
139+
* const secretsProvider = new SecretsProvider({
140+
* awsSdkV3Client: client,
141+
* });
142+
* ```
143+
*
144+
* This object must be an instance of the [AWS SDK v3 for JavaScript Secrets Manager client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-secrets-manager/classes/secretsmanagerclient.html).
145+
*
146+
* For more usage examples, see [our documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/).
147+
*
148+
* @class
149+
* @implements {BaseProvider}
150+
* @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/
151+
*/
12152
class SecretsProvider extends BaseProvider {
13153
public client: SecretsManagerClient;
14154

@@ -28,6 +168,32 @@ class SecretsProvider extends BaseProvider {
28168

29169
}
30170

171+
/**
172+
* Retrieve a secret from AWS Secrets Manager.
173+
*
174+
* @example
175+
* ```typescript
176+
* import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
177+
*
178+
* const secretsProvider = new SecretsProvider();
179+
*
180+
* export const handler = async (): Promise<void> => {
181+
* // Retrieve a single secret
182+
* const secret = await secretsProvider.get('my-secret');
183+
* };
184+
* ```
185+
*
186+
* You can customize the retrieval of the secret by passing options to the function:
187+
* * `maxAge` - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
188+
* * `forceFetch` - Whether to always fetch a new value from the store regardless if already available in cache
189+
* * `transform` - Whether to transform the value before returning it. Supported values: `json`, `base64`
190+
* * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
191+
*
192+
* For usage examples check {@link SecretsProvider}.
193+
*
194+
* @param {string} name - The name of the secret
195+
* @param {SecretsGetOptionsInterface} options - Options to customize the retrieval of the secret
196+
*/
31197
public async get(
32198
name: string,
33199
options?: SecretsGetOptionsInterface

Diff for: ‎packages/parameters/src/secrets/getSecret.ts

+100
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,106 @@ import { DEFAULT_PROVIDERS } from '../BaseProvider';
22
import { SecretsProvider } from './SecretsProvider';
33
import type { SecretsGetOptionsInterface } from '../types/SecretsProvider';
44

5+
/**
6+
* ## Intro
7+
* The Parameters utility provides a SecretsProvider that allows to retrieve secrets from AWS Secrets Manager.
8+
*
9+
* ## Getting started
10+
*
11+
* This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only
12+
* the SDK packages you need and keep your bundle size small.
13+
*
14+
* To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for Secrets Manager:
15+
*
16+
* ```sh
17+
* npm install @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager
18+
* ```
19+
*
20+
* ## Basic usage
21+
*
22+
* @example
23+
* ```typescript
24+
* import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
25+
*
26+
* export const handler = async (): Promise<void> => {
27+
* // Retrieve a single secret
28+
* const secret = await getSecret('my-secret');
29+
* };
30+
* ```
31+
*
32+
* ## Advanced usage
33+
*
34+
* ### Caching
35+
*
36+
* By default, the provider will cache parameters retrieved in-memory for 5 seconds.
37+
* You can adjust how long values should be kept in cache by using the `maxAge` parameter.
38+
*
39+
* @example
40+
* ```typescript
41+
* import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
42+
*
43+
* export const handler = async (): Promise<void> => {
44+
* // Retrieve a single secret and cache it for 10 seconds
45+
* const secret = await getSecret('my-secret', { maxAge: 10 });
46+
* };
47+
* ```
48+
*
49+
* If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the `forceFetch` parameter.
50+
*
51+
* @example
52+
* ```typescript
53+
* import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
54+
*
55+
* export const handler = async (): Promise<void> => {
56+
* // Retrieve a single secret and always fetch the latest value
57+
* const secret = await getSecret('my-secret', { forceFetch: true });
58+
* };
59+
* ```
60+
*
61+
* ### Transformations
62+
*
63+
* For parameters stored in JSON or Base64 format, you can use the transform argument for deserialization.
64+
*
65+
* @example
66+
* ```typescript
67+
* import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
68+
*
69+
* export const handler = async (): Promise<void> => {
70+
* // Retrieve a single secret and deserialize it as JSON
71+
* const secret = await getSecret('my-secret', { transform: 'json' });
72+
* ```
73+
*
74+
* ### Extra SDK options
75+
*
76+
* When retrieving a secret, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter.
77+
*
78+
* @example
79+
* ```typescript
80+
* import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
81+
*
82+
* export const handler = async (): Promise<void> => {
83+
* // Retrieve a single secret and pass extra options to the AWS SDK v3 for JavaScript client
84+
* const secret = await getSecret('my-secret', {
85+
* sdkOptions: {
86+
* VersionId: 1,
87+
* },
88+
* });
89+
* };
90+
* ```
91+
*
92+
* This object accepts the same options as the [AWS SDK v3 for JavaScript Secrets Manager client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-secrets-manager/interfaces/getsecretvaluecommandinput.html).
93+
*
94+
* ### Built-in provider class
95+
*
96+
* For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SecretsProvider} class.
97+
*
98+
* For more usage examples, see [our documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/).
99+
*
100+
*
101+
* @param {string} name - The name of the secret to retrieve
102+
* @param {SecretsGetOptionsInterface} options - Options to configure the provider
103+
* @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/
104+
*/
5105
const getSecret = async (name: string, options?: SecretsGetOptionsInterface): Promise<undefined | string | Uint8Array | Record<string, unknown>> => {
6106
if (!DEFAULT_PROVIDERS.hasOwnProperty('secrets')) {
7107
DEFAULT_PROVIDERS.secrets = new SecretsProvider();

Diff for: ‎packages/parameters/src/types/SecretsProvider.ts

+11
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,19 @@ interface SecretsProviderOptionsWithClientInstance {
1111
clientConfig?: never
1212
}
1313

14+
/**
15+
* Options to configure the SecretsProvider.
16+
*/
1417
type SecretsProviderOptions = SecretsProviderOptionsWithClientConfig | SecretsProviderOptionsWithClientInstance;
1518

19+
/**
20+
* Options to configure the retrieval of a secret.
21+
*
22+
* @property {number} maxAge - Maximum age of the value in the cache, in seconds.
23+
* @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache.
24+
* @property {Omit<Partial<GetSecretValueCommandInput>, 'SecretId'>} sdkOptions - Options to pass to the underlying SDK.
25+
* @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'.
26+
*/
1627
interface SecretsGetOptionsInterface extends GetOptionsInterface {
1728
sdkOptions?: Omit<Partial<GetSecretValueCommandInput>, 'SecretId'>
1829
}

0 commit comments

Comments
 (0)