Skip to main content

​
AWS Sandbox Provider

@smthrs/aws is a Smithers SandboxProvider that runs a <Sandbox> child workflow’s request on AWS: Fargate (ECS RunTask, the default) or CodeBuild. AWS shares no filesystem with the orchestrator, so the request/result bundle transports through an S3 bucket. The shared provider-kit handles the request/result protocol, egress, secret scrubbing, and cleanup; this package adds the S3 transport plus the ECS/CodeBuild runners. Provider id: aws-sandbox (exported as AWS_SANDBOX_PROVIDER_ID).

​
Credentials

Authentication uses the standard AWS SDK v3 credential chain (env vars, shared config, SSO, or an instance/task role). The factory takes no explicit credentials and forwards none into the remote task env; the task or build authenticates with its own IAM role. The @aws-sdk/* clients are optional, lazily-imported dependencies. Install what your mode needs:
  • @aws-sdk/client-s3 (always).
  • @aws-sdk/client-ecs (Fargate).
  • @aws-sdk/client-codebuild (CodeBuild).
  • @aws-sdk/client-cloudwatch-logs (with captureLogs).

​
Prerequisites

The provider provisions nothing; set these up first:
  • An S3 bucket that already exists. The provider only manages the key prefix smithers/sandbox/<runId>/<sandboxId>/ under it.
  • Fargate: an ECS cluster, a registered taskDefinition, at least one VPC subnet, optional securityGroups, and the containerName inside the task definition.
  • CodeBuild: a CodeBuild projectName.
The task or build role needs S3 read/write on the prefix.

​
Usage

Or register either provider once and reference it by id with registerAwsSandboxProvider(...) then <Sandbox provider="aws-sandbox" />.

​
Request/result contract

The kit hands the entry command SMITHERS_SANDBOX_REQUEST_PATH and SMITHERS_SANDBOX_RESULT_PATH. The container round-trips those files through S3; the provider injects four more vars so the entry can find them:
  • SMITHERS_SANDBOX_S3_BUCKET: the transport bucket.
  • SMITHERS_SANDBOX_S3_PREFIX: smithers/sandbox/<runId>/<sandboxId>.
  • SMITHERS_SANDBOX_REQUEST_S3_KEY: S3 key of the request JSON.
  • SMITHERS_SANDBOX_RESULT_S3_KEY: S3 key the entry must write the result to.
Every workdir path maps to s3://<bucket>/<prefix>/<runId>/<sandboxId>/<encodeURIComponent(workdir-relative path)>, so files sharing a basename never collide. The entry prints the result JSON to stdout or writes it to the result key. An infra failure (task or build fails with no result written) throws, while a result file with status: "failed" is a normal failed bundle. Fargate reports a real numeric exit code; CodeBuild reports a status (SUCCEEDED maps to 0, else 1).

​
Factory options

  • mode: "fargate" (default) or "codebuild".
  • region, bucket: required in both modes.
  • Fargate: cluster, taskDefinition, subnets, containerName (required), securityGroups, assignPublicIp, logGroupName.
  • CodeBuild: projectName (required).
  • captureLogs: pull CloudWatch logs, truncated to maxOutputBytes.
  • command, workdir (default /workspace), env.
  • cleanup: "destroy" (default) or "keep".
  • clients / client / clientOptions: inject SDK doubles or client options.

​
Cleanup and cost

cleanup: "destroy" (default) stops the task or build if still running and deletes the transient S3 objects; cleanup: "keep" leaves them. You pay for Fargate task time or CodeBuild build minutes, plus S3 storage of those small objects. Set a short lifecycle TTL on the smithers/sandbox/ prefix to reap crash leftovers. EC2 mode is future work. createMockAwsSandboxEnvironment(handler, mockOptions?) provides in-memory S3, ECS, CodeBuild, and CloudWatch Logs doubles for tests, needing zero AWS credentials, so unit tests run in CI without touching AWS.