Skip to content

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:

let client = grow_aws_secrets_manager::blocking::AwsSecretsManagerClient::from_env()?;
let health = client.health()?;
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 with CANCELLED ("<operation>: client is closed").
  • Each language also offers its idiomatic scope: TypeScript try/finally, Rust close().await (plus best-effort Drop), Go defer client.Close(), Python with/async with, Java try-with-resources.