AWS Ktor Integration

Latest stable Based on AWS release 0.4.0

Library manual grounded in the 0.4.0 release source.

Problem

Ktor 3 client signing plus server plugins and runtimes for S3, DynamoDB, SQS, Exposed, CloudWatch, IMDS, Access Grants, and S3 Vectors.

When to use it

Use it when a Ktor application needs coroutine-native AWS integration without adopting Spring’s lifecycle model.

Coordinates

Applications select one central BOM version.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.aws:bluetape4k-aws-ktor")
}

AWS service SDKs follow a compileOnly policy; add the services actually used as runtime dependencies.

Core concepts

AwsSigV4Plugin signs outbound Ktor client requests. Application plugins create typed runtimes, store them in attributes, start background jobs, and close owned resources on application stop.

Quick start

install(SqsConsumer) {
    queueUrl = config.queueUrl
    deleteOnSuccess = true
    onMessage<OrderMessage> { message -> process(message) }
}

API by task

SigV4 client auth, S3 REST and encryption helpers, DynamoDB repository runtime, SQS consumer, Exposed database plugin, CloudWatch/Logs, IMDS, Access Grants, and S3 Vectors.

Recommended patterns

Put client and background-job ownership at one application boundary. Configure region, credentials, and endpoints once instead of rebuilding them per call.

Integrations

Add this library through bluetape4k-dependencies, then add only the Java or Kotlin AWS service SDKs used by installed plugins.

Configuration

Keep region, service, credential provider, signing options, queue polling, concurrency, endpoint override, and shutdown timeout in application configuration.

Failure modes

Wrong SigV4 service/region, consumed request bodies, clock skew, missing service SDKs, duplicate plugin installation, and uncoordinated coroutine shutdown are common faults.

Operations

Use structured application scopes, bound consumers, expose Micrometer observations, and ensure plugins stop before shared clients are closed.

Testing

Use Ktor testApplication, deterministic credentials and clocks for signing, and Floci for service runtimes. Assert stop hooks leave no jobs or clients running.

Workshops and learning path

Read client-and-sigv4, then service-plugins, then runtime-lifecycle; run the released Ktor S3, DynamoDB, SQS, and Exposed examples.

Limitations

The Ktor REST helpers do not replace the full AWS SDK surface, and installing a plugin does not provision AWS resources.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.4.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.