@turbot/guardrails-aws-sdk-v3

@turbot/guardrails-aws-sdk-v3

A lightweight, Turbot-optimized wrapper around AWS SDK v3, designed to simplify and standardize AWS interactions within Guardrails. This wrapper provides intelligent defaults, automatic configuration detection, and enterprise-ready features.

Features

• Zero Configuration: Sensible defaults work out of the box
• Advanced Proxy Support: Per-service proxy control with wildcard patterns
• Custom Retry Strategies: Turbot-optimized retry logic with exponential backoff
• Smart Region Fallback: 3-level region resolution (params → env var → config)
• IAM Signed Requests: Built-in support for AWS signature v4 signed HTTP requests
• Discovery Parameters: Specialized retry strategy for AWS discovery operations

Installation

npm install @turbot/guardrails-aws-sdk-v3

Quick Start

Basic Usage

const taws = require("@turbot/guardrails-aws-sdk-v3");
const { S3Client, ListBucketsCommand } = require("@aws-sdk/client-s3");

// Simple connection with explicit region
const s3 = taws.connect(S3Client, { region: "us-east-1" });

async function listBuckets() {
  const data = await s3.send(new ListBucketsCommand({}));
  console.log("Buckets:", data.Buckets);
}

listBuckets();

Region Configuration

The wrapper automatically resolves regions using a 3-level fallback:

// 1. Explicit params (highest priority)
const s3 = taws.connect(S3Client, { region: "us-east-1" });

// 2. Environment variable (if params not provided)
process.env.AWS_DEFAULT_REGION = "us-west-2";
const s3 = taws.connect(S3Client, {});

// 3. TURBOT_CONFIG_ENV (lowest priority)
process.env.TURBOT_CONFIG_ENV = JSON.stringify({
  env: { region: "ap-southeast-2" },
});
const s3 = taws.connect(S3Client, {});

Proxy Configuration

Simple Proxy (All Services)

// Set environment variable
process.env.HTTPS_PROXY = "http://proxy.company.com:8080";

// All AWS service calls automatically use proxy
const s3 = taws.connect(S3Client, { region: "us-east-1" });

Advanced Proxy (Per-Service Control)

// Configure via TURBOT_CONFIG_ENV
process.env.TURBOT_CONFIG_ENV = JSON.stringify({
  aws: {
    proxy: {
      https_proxy: "http://proxy.company.com:8080",
      enabled: ["s3*", "dynamodb*", "sqs*"], // Services to proxy
      disabled: ["sts*", "iam*"], // Services to bypass
    },
  },
});

const s3 = taws.connect(S3Client, { region: "us-east-1" }); // Uses proxy
const sts = taws.connect(STSClient, { region: "us-east-1" }); // Bypasses proxy

Wildcard patterns:

• * matches all services
• s3* matches S3Client, S3ControlClient, etc.
• iam* matches IAMClient, IAMRolesAnywhereClient, etc.

Custom Retry Strategy

The wrapper includes Turbot-optimized retry logic:

const s3 = taws.connect(S3Client, {
  region: "us-east-1",
  maxAttempts: 5, // Default is 10
});

// For discovery operations (uses different backoff)
const ec2 = taws.connect(EC2Client, taws.discoveryParams({ region: "us-east-1" }));

IAM Signed Requests

Make SigV4-signed HTTPS requests to AWS endpoints that have no SDK client, such as an AppSync GraphQL API:

const taws = require("@turbot/guardrails-aws-sdk-v3");

const options = {
  uri: "https://example.appsync-api.us-east-1.amazonaws.com/graphql",
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: { query: "{ __typename }" },
};

const credentials = {
  AccessKeyId: "AKIAIOSFODNN7EXAMPLE",
  SecretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
};

taws.awsIamSignedRequest(options, "appsync", credentials, (err, result) => {
  if (err) console.error(err);
  else console.log(result);
});

The request goes through the same proxy that connect() would use, with the service name (appsync here) matched against the enabled / disabled patterns. To send it direct while other services use the proxy, add appsync to disabled.

Development Mode

For local development, automatically uses AWS CLI profile credentials:

process.env.NODE_ENV = "local-development";
process.env.TURBOT_DEV_PROFILE = "developer";
process.env.TURBOT_DEV_MASTER_REGION = "ap-southeast-2";

const s3 = taws.connect(S3Client, {}); // Uses "developer" profile

API Reference

connect(ServiceClient, params)

Creates and configures an AWS SDK v3 client.

Parameters:

• ServiceClient (class) - AWS SDK v3 client class (e.g., S3Client, DynamoDBClient)
• params (object) - Configuration options:
  • region (string) - AWS region
  • maxAttempts (number) - Maximum retry attempts (default: 10)
  • retryStrategy (object) - Custom retry strategy
  • customUserAgent (string) - Custom user agent (default: "Turbot/5 (APN_137229)")
  • signatureVersion (string) - AWS signature version (default: "v4")
  • Any other AWS SDK v3 client options

Returns: Configured AWS SDK v3 client instance

discoveryParams(params)

Returns parameters optimized for AWS discovery operations (uses CustomDiscoveryRetryStrategy).

Parameters:

• params (object) - Base configuration options

Returns: Configuration object with discovery retry strategy

awsIamSignedRequest(options, service, credentials, callback)

Makes a SigV4-signed HTTPS request to an AWS service, through the proxy connect() would use for that service.

Parameters:

• options (object):
  • uri (string) - Target AWS service URL
  • method (string) - HTTP method
  • headers (object) - HTTP headers
  • body (object, optional) - Request body, sent as JSON
  • timeout (number, optional) - Milliseconds before the request fails with a timeout error (default: 300000)
• service (string) - AWS signing name (e.g. appsync), also matched against the proxy enabled / disabled patterns
• credentials (object):
  • AccessKeyId (string) - AWS access key ID
  • SecretAccessKey (string) - AWS secret access key
  • SessionToken (string, optional) - AWS session token
• callback (function) - Called with (err, body), where body is the parsed JSON response

CustomRetryStrategy

Turbot-optimized retry strategy with custom backoff logic.

CustomDiscoveryRetryStrategy

Specialized retry strategy for AWS discovery operations.

Environment Variables

Variable	Purpose	Example
AWS_DEFAULT_REGION	Default AWS region	us-east-1
HTTPS_PROXY / https_proxy	Proxy server URL	http://proxy:8080
TURBOT_CONFIG_ENV	JSON config (region, proxy)	See examples above
NODE_ENV	Enable dev mode	local-development
TURBOT_DEV_PROFILE	Dev mode AWS profile	silverwater
TURBOT_DEV_MASTER_REGION	Dev mode default region	ap-southeast-2

Changelog

See CHANGELOG.md for version history.

License

See LICENSE file for details.