Soto AWS Workflow

Soto AWS Workflow

Purpose

Make Soto the one default AWS integration path for Gale-owned server-side Swift components. This skill owns SDK choice, manifest wiring, credentials and region configuration, AWSClient lifecycle, service-object reuse, tests, and migration boundaries.

Standard Path

1. Add https://github.com/soto-project/soto.git and only the Soto service products the component uses.
2. Create one AWSClient for the application or Lambda execution environment.
3. Construct S3, SES, DynamoDB, SQS, or other Soto service objects with that shared client. Do not create an AWSClient per request, route, repository, actor, or service object.
4. Use the normal credential provider chain and runtime configuration. Never commit static credentials or put them in generated examples.
5. Give one lifecycle owner responsibility for shutdown. Call async shutdown() or syncShutdown() exactly once before the owner is released; do not let every consumer attempt cleanup.
6. In Lambda, create the client outside per-invocation work so warm invocations reuse it, and connect the single shutdown to the Lambda environment lifecycle.
7. Unit-test domain adapters behind narrow first-party protocols. Use live AWS tests only in an explicitly protected GitHub Actions environment.

SDK Decision

• Soto is the default for all new server-side Swift AWS work.
• Existing Soto integrations stay on Soto.
• Existing official AWS SDK for Swift integrations stay in place unless the task explicitly authorizes migration.
• Choose the official AWS SDK for Swift only when a required AWS capability is absent or materially incompatible in Soto, or an existing public contract already exposes official-SDK types. Record the concrete service/API/version evidence for the exception.
• Record an approved exception with references/official-sdk-exception.template.md so the deviation is specific and reviewable.
• “AWS publishes it,” familiarity, generated examples, or another skill default are not sufficient exceptions.

Local And Cloud Boundary

• Compile and test Soto integrations natively on macOS.
• Use local fakes or protocol-backed test doubles for ordinary local tests. Do not start LocalStack, a Linux VM, or a container runtime.
• Run live AWS integration tests, Linux artifact builds, and deployments only in GitHub Actions with OIDC and protected environments.

Evidence

• Soto AWSClient guide
• Soto AWS service objects
• Using Soto on AWS Lambda
• Official AWS SDK for Swift
• references/awsclient-lifecycle.md
• references/official-sdk-exception.template.md