Client¶
AwsSecretsManagerClient is the entry point. Create one per process (or per set of credentials), share
it between threads/tasks and close it on shutdown. Service functions hang off the client (see
Functions).
| Function | Returns | Notes |
|---|---|---|
constructor / create / new / builder() |
client | validates the config (CONFIG error); region, credentials, endpoint override (url), assume role, timeouts, retries, proxy and TLS go to the AWS SDK client |
fromEnv() |
client | config from GROW_AWS_SECRETS_MANAGER_* > standard AWS_* variables > AWS SDK default chain |
withSdkClient(client) |
client | wraps an existing AWS SDK client; close() leaves it open |
health() |
HealthStatus { healthy, status, details } |
signed ListSecrets {MaxResults: 1}, no retries; never throws for an unhealthy or unreachable service (rejected credentials still count as reachable, details.auth = "failed"), only for CANCELLED and CONFIG |
ping() |
latency | the same call with retries; AUTHENTICATION on bad credentials, PERMISSION_DENIED without secretsmanager:ListSecrets |
serverVersion() |
— | always UNSUPPORTED: AWS exposes no server version (the API contract is the constant API_VERSION, 2017-10-17) |
close() |
— | idempotent; stops the watchers of every provider from secrets() and releases the SDK client this instance built |
status is ok, degraded (throttled), unhealthy (HTTP 5xx) or unreachable (network error
or timeout). AWS-specific details are on Client setup.
Create, use and close¶
import { AwsSecretsManagerClient } from "@grow-codes/aws-secrets-manager";
const client = new AwsSecretsManagerClient({ region: "eu-central-1" }); // or AwsSecretsManagerClient.fromEnv()
try {
const health = await client.health(); // { healthy, status, details }
const latencyMs = await client.ping(); // number (ms)
const secret = await client.getSecretValue("prod/app/db");
// Cancellation and per-call deadline: every I/O method accepts { signal }
const status = await client.health({ signal: AbortSignal.timeout(2_000) });
} finally {
await client.close(); // safe to call twice
}
use grow_aws_secrets_manager::{AwsSecretsManagerClient, AwsSecretsManagerConfig};
let config = AwsSecretsManagerConfig::builder().region("eu-central-1").build()?;
let client = AwsSecretsManagerClient::new(config)?;
let health = client.health().await?; // HealthStatus
let latency = client.ping().await?; // Duration
let secret = client.get_secret_value("prod/app/db", Default::default()).await?;
client.close().await; // safe to call twice
// Cancellation: drop the future, e.g. with a deadline
let status = tokio::time::timeout(std::time::Duration::from_secs(2), client.health()).await;
Without an async runtime, enable the blocking feature:
client, err := asm.NewClient(asm.Config{Region: "eu-central-1"}) // or asm.NewClientFromEnv()
if err != nil {
return err
}
defer client.Close() // safe to call twice
health, err := client.Health(ctx) // HealthStatus
latency, err := client.Ping(ctx) // time.Duration
secret, err := client.GetSecretValue(ctx, "prod/app/db", nil)
// Cancellation and deadlines come from ctx
ctx2, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
health, err = client.Health(ctx2)
from grow_aws_secrets_manager import AwsSecretsManagerClient, AwsSecretsManagerConfig, CancelToken
with AwsSecretsManagerClient(AwsSecretsManagerConfig(region="eu-central-1")) as client:
health = client.health() # HealthStatus
latency_ms = client.ping() # float (ms)
secret = client.get_secret_value("prod/app/db")
# Cancel from another thread
token = CancelToken()
health = client.health(cancel=token)
# close() ran; calling it again is safe
AsyncAwsSecretsManagerClient (aioboto3, extra [async]) has the same methods as coroutines
(await client.health(), await client.aclose(), async with), and honours task cancellation.
try (AwsSecretsManagerClient client =
AwsSecretsManagerClient.builder().region("eu-central-1").build()) {
HealthStatus health = client.health();
Duration latency = client.ping();
AwsSecretValue secret = client.getSecretValue("prod/app/db");
// Async variants return CompletableFuture; cancel(true) cancels the request
CompletableFuture<HealthStatus> pending = client.healthAsync();
pending.orTimeout(2, TimeUnit.SECONDS).join();
} // close() is idempotent
For an emulator (Moto, LocalStack) set url (GROW_AWS_SECRETS_MANAGER_URL), for example
http://127.0.0.1:5000, together with a region and static credentials.
Lifecycle rules¶
- The client is safe for concurrent use. Reuse it: it keeps a connection pool.
close()flushes queued work (for example log batches) within the configured deadline and is safe to call more than once. Any call on a closed client fails withCANCELLED("<operation>: client is closed").- Each language also offers its idiomatic scope: TypeScript
try/finally, Rustclose().await(plus best-effortDrop), Godefer client.Close(), Pythonwith/async with, Java try-with-resources.