Compatibility¶
Runtimes¶
| Language | Supported | Tested in CI | AWS SDK |
|---|---|---|---|
| TypeScript | Node.js ≥ 22.12, ESM and CommonJS | Node 22, 24 | @aws-sdk/client-secrets-manager v3 (+ @aws-sdk/credential-providers) |
| Rust | MSRV 1.88, edition 2021, tokio | stable, 1.88 | aws-sdk-secretsmanager 1.x + aws-config (no default features; own reqwest/rustls HTTP client) |
| Go | Go ≥ 1.26 | 1.26, 1.27 | AWS SDK for Go v2 (service/secretsmanager, config, credentials/stscreds) |
| Python | ≥ 3.10 | 3.10, 3.13, 3.14 | boto3 (sync); aioboto3 for AsyncAwsSecretsManagerClient via the optional extra [async] |
| Java | ≥ 17 (Java 17 bytecode) | Temurin 17, 21, 25 | AWS SDK for Java v2 (secretsmanager, sts) with an own java.net.http SdkHttpClient |
The Python async extra pins boto3/botocore to the window aioboto3 supports
(pip install "grow-aws-secrets-manager[async]"); sync-only users keep an unpinned boto3.
AWS Secrets Manager versions¶
The packages target the AWS Secrets Manager API 2017-10-17 (constant API_VERSION). AWS exposes no
server version, so serverVersion() raises UNSUPPORTED in every language. The Docker suite runs
against the emulator motoserver/moto:5.2.4 (Apache-2.0, test-only, never bundled) with IAM
authentication enabled; LocalStack needs an auth token since 2026.03 and is not used. An optional
live job against an AWS sandbox account is gated on repository secrets.
Functions the emulator cannot serve¶
Every public function is called against Moto in the Docker suite of each language. These parts cannot be served by Moto 5.2.4; the Docker suites assert Moto's documented answer and the AWS behaviour is covered by unit tests replaying recorded AWS wire shapes:
| Function / case | Languages | Reason | Covered by |
|---|---|---|---|
validateResourcePolicy result |
all | not implemented in Moto 5.2.4: HTTP 500 with an HTML body. The SDK maps that answer (for this operation only) to UNSUPPORTED |
unit tests of the AWS response; Docker asserts UNSUPPORTED |
rotateSecret with a Lambda ARN (real rotation steps) |
all | no Lambda runtime in the fixture (it would need Docker-in-Docker); Moto answers ResourceNotFoundException → NOT_FOUND. Rules-only rotation works and is verified |
unit tests; Docker asserts NOT_FOUND |
cancelRotateSecret |
all | Moto only accepts it after a Lambda ARN has been recorded on the secret (the failed rotateSecret call above records it) |
Docker (after the Lambda call), unit tests |
| assume-role helper | all | STS is not part of the fixture | unit tests against a mocked STS endpoint |
RATE_LIMITED (ThrottlingException, Retry-After) |
all | not emulated | unit tests |
| AWS-exact error statuses (400 JSON for not-found, access denied and auth errors) | all | Moto answers 404 for not-found and 403 XML for IAM errors; the mapping is by AWS error code, so both shapes are tested | unit tests (AWS shapes), Docker (Moto shapes) |
BatchGet 20-id limit, ListSecretVersionIds paging and not-found |
all | Moto does not enforce the limit (chunking is unit-tested), ignores MaxResults and answers HTTP 500 for a missing secret |
unit tests |
Moto 5.2.4 differences from AWS¶
Recorded as fixtures in the prep and handled in the integration tests:
BatchGetSecretValuefails the whole call for a secret whoseAWSCURRENTlabel was moved, instead of reporting it inErrors; the suites read such secrets one by one.GetSecretValuewithout a stage still returns the old version afterAWSCURRENTwas moved withupdateSecretVersionStage; withversionStage: "AWSCURRENT"it is correct, so the suites read back with an explicit stage. After a rules-only rotationGetSecretValue(VersionStage = AWSCURRENT)can answerNOT_FOUND; rotation tests use their own secret.UpdateSecretwithoutClientRequestToken→ResourceExistsException(the AWS SDKs always fill the token, so only raw callers hit this).- Not validated by Moto:
SecretStringandSecretBinarytogether, malformed resource policies,BlockPublicPolicy, KMS key ids, more than 20 ids inBatchGetSecretValue. - The
namefilter matches string prefixes only (AWS also matches word prefixes); the provider'slistalways re-filters client side. NextTokenmay benullor""at the end of a list; both end the paginators.- Moto error messages contain doubled text and runs of spaces — the tests assert codes, never messages.
Error mapping¶
AWS JSON services answer HTTP 400 for throttling and access denied, so errors are mapped by AWS error code first and by HTTP status only as a fallback (same table in all five languages):
| AWS error code(s) | Code |
|---|---|
ResourceNotFoundException |
NOT_FOUND |
ResourceExistsException, PreconditionNotMetException, InvalidRequestException (e.g. scheduled for deletion, rotation in progress) |
CONFLICT |
InvalidParameterException, InvalidParameterValue, ValidationException, InvalidNextTokenException, MalformedPolicyDocumentException, PublicPolicyException, LimitExceededException, EncryptionFailure, DecryptionFailure, SerializationException |
VALIDATION |
AccessDeniedException, AccessDenied |
PERMISSION_DENIED |
UnrecognizedClientException, InvalidClientTokenId, InvalidAccessKeyId, InvalidSignatureException, SignatureDoesNotMatch, IncompleteSignature(Exception), MissingAuthenticationToken(Exception), ExpiredToken(Exception), missing credentials |
AUTHENTICATION |
ThrottlingException, Throttling, TooManyRequestsException, RequestLimitExceeded |
RATE_LIMITED (retryable, honours Retry-After) |
InternalServiceError(Exception), InternalFailure, ServiceUnavailable(Exception), HTTP 5xx |
UNAVAILABLE (retryable) |
RequestTimeout(Exception), SDK timeouts, the total timeout |
TIMEOUT |
| HTTP 403 without a recognised code (Moto's XML) | AUTHENTICATION when the body mentions InvalidClientTokenId, SignatureDoesNotMatch or security token, else PERMISSION_DENIED |
HTTP 500 HTML for validateResourcePolicy |
UNSUPPORTED |
| caller cancellation, any call on a closed client | CANCELLED |
The AWS message is redacted and shortened before it becomes part of error.message
("<operation>: <AwsCode>: <text> (HTTP <status>)"). The AWS error code stays available: Go
AWSErrorCode(err), Rust aws_error_code(&err), Python aws_error_code(err), Java
AwsErrors.awsErrorCode(err), TypeScript through err.cause (the AWS SDK exception, name = the
code).
Skipped conformance scenarios¶
| Scenario | Reason |
|---|---|
core.health → serverVersion step |
skipped by the runner because the service has no version capability (serverVersion() is always UNSUPPORTED) |
All secrets.* scenarios (roundtrip, missing, bulk, redaction) run with the capabilities
write, versions, delete in all five languages.
Parity decisions¶
Binding for all five packages (recorded during the GRO-1370 integration):
- Transport is the official AWS SDK of each language (SPEC exception for cloud SDK services): the
Grow config maps onto it, retries use the AWS SDK standard mode with
maxAttempts = maxRetries + 1, the Grow hooks fire per attempt where the package owns the HTTP client. - Environment:
GROW_AWS_SECRETS_MANAGER_*>AWS_*> AWS SDK chain; static credentials come from one layer only (aGROW_*key id is never paired with anAWS_*secret key). health(): probe timeoutmin(requestTimeout, 5 s), no retries; authentication and permission failures and any other 4xx count asok(with details); details carry canonical codes.deleteSecret: window and force together, or a window outside 7–30, are rejected client side; without options AWS applies its 30-day default.SecretsProvider.deleteuses therecoveryWindowDayssetting (default 30) unlesspermanent: true.getJsonField: an exact key wins over a dot path; JSONnullcounts as absent.getRandomPassword: default length 32.SecretCache: the service exports the AWS-semanticsAwsSecretCache(TTL 1 h, 1 024 entries, stage-aware) and anawsDefaults()preset for the generic SPEC cache (whose own defaults stay 60 s / 1 000).- Any call on a closed client raises
CANCELLED("client is closed").
Language differences¶
The API is the same in every language; only the conventions differ (naming, durations, async model).
- Java cannot change the process environment, so
loadEnvsets system properties instead and returns the names it set. - Go has no optional arguments: zero values mean "not set" (
RecoveryWindowDays: 0,Length: 0→ 32), pointers are used wherefalsemust be sent (RotateImmediately,BlockPublicPolicy,RequireEachIncludedType). Go validatesgetRandomPasswordlength (1–4096) and a batch read without ids or filters client side; the other languages let AWS reject them with the sameVALIDATIONcode. A batch read with an empty id list returns an empty result in TypeScript, Rust, Python and Java. - Go list calls return
iter.Seq2[T, error]; the other languages return a paginator object. - Java
updateSecretVersionStagerejects a call with neithermoveToVersionIdnorremoveFromVersionIdbefore sending it (AWS answersVALIDATIONfor it as well). - Python async needs the
[async]extra (aioboto3); the sync client only needsboto3. - With a caller-supplied AWS SDK client (
sdkClient/withSdkClient), the Grow TLS, proxy, User-Agent and per-attempt hooks do not apply — they are properties of the HTTP client that the caller built.