Add AWS World implementation with DynamoDB and SQS

[ataylorme]

Summary

This PR introduces a complete AWS-based World implementation for the Workflow DevKit, providing a production-ready backend using AWS managed services. The implementation includes DynamoDB for persistent storage, SQS for message queuing, and DynamoDB-backed streaming.

Key Changes

• DynamoDB Storage Layer (storage.ts): Comprehensive storage implementation for all workflow entities (runs, events, steps, hooks, waits) with:

  • Full CRUD operations with proper validation and error handling
  • Support for pagination and filtering via Global Secondary Indexes
  • CBOR encoding for efficient binary serialization of complex data
  • Idempotent operations and conditional writes for consistency
  • Legacy spec version compatibility handling

• SQS Queue Implementation (queue.ts): Message queue backed by AWS SQS with:

  • Per-message delay support (up to 15 minutes) for workflow retries
  • Integration with local queue executor for message processing
  • Idempotency tracking for message deduplication
  • Concurrent message processing with configurable limits
  • Automatic message deletion on successful processing

• DynamoDB Streamer (streamer.ts): Real-time streaming using DynamoDB with:

  • ULID-based chunk ordering for consistency across process boundaries
  • Polling-based delivery for stream subscribers
  • Automatic cleanup of completed streams

• Infrastructure & Configuration:

  • dynamo.ts: DynamoDB table creation and schema definitions with on-demand billing
  • config.ts: Flexible configuration via environment variables or programmatic API
  • cli.ts: Setup CLI tool for initializing DynamoDB tables
  • Comprehensive test coverage for queue and table definitions

• Documentation: Complete README with architecture overview, configuration guide, and setup instructions

Notable Implementation Details

• Uses CBOR encoding for efficient storage of complex JavaScript objects in DynamoDB
• Implements proper validation of ULID timestamps for client-provided IDs
• Handles version compatibility for legacy workflow specifications
• Supports both standard and custom DynamoDB/SQS endpoints for local development
• Provides on-demand DynamoDB billing model for cost-effective scaling
• Includes idempotency caching for SQS message processing to prevent duplicates

https://claude.ai/code/session_01V2KJGt7ihWsSGb5Jzcsu5Q

[changeset-bot]

🦋 Changeset detected

Latest commit: 6fb169f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-aws	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@claude is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​aws-sdk/​util-dynamodb@​3.750.0
	npm/​@​aws-sdk/​client-dynamodb@​3.750.0
	npm/​@​aws-sdk/​client-sqs@​3.750.0
	npm/​@​aws-sdk/​client-s3@​3.750.0

View full report

[socket-security]

Caution

Review the following alerts detected in dependencies.

According to your organization's Security Policy, you must resolve all "Block" alerts before proceeding. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Block		Critical CVE: npm fast-xml-parser has an entity encoding bypass via regex injection in DOCTYPE entity names CVE: GHSA-m7jm-9gc2-mpf2 fast-xml-parser has an entity encoding bypass via regex injection in DOCTYPE entity names (CRITICAL) Affected versions: >= 5.0.0 < 5.3.5; >= 4.1.3 < 4.5.4 Patched version: 4.5.4 From: pnpm-lock.yaml → npm/@aws-sdk/client-dynamodb@3.750.0 → npm/@aws-sdk/client-s3@3.750.0 → npm/@aws-sdk/client-sqs@3.750.0 → npm/fast-xml-parser@4.4.1 ℹ Read more on: This package | This alert | What is a critical CVE? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Remove or replace dependencies that include known critical CVEs. Consumers can use dependency overrides or npm audit fix --force to remove vulnerable dependencies. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/fast-xml-parser@4.4.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		High CVE: npm fast-xml-parser affected by DoS through entity expansion in DOCTYPE (no expansion limit) CVE: GHSA-jmr7-xgp7-cmfj fast-xml-parser affected by DoS through entity expansion in DOCTYPE (no expansion limit) (HIGH) Affected versions: >= 4.1.3 < 4.5.4; >= 5.0.0 < 5.3.6 Patched version: 4.5.4 From: pnpm-lock.yaml → npm/@aws-sdk/client-dynamodb@3.750.0 → npm/@aws-sdk/client-s3@3.750.0 → npm/@aws-sdk/client-sqs@3.750.0 → npm/fast-xml-parser@4.4.1 ℹ Read more on: This package | This alert | What is a CVE? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Remove or replace dependencies that include known high severity CVEs. Consumers can use dependency overrides or npm audit fix --force to remove vulnerable dependencies. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/fast-xml-parser@4.4.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[VaguelySerious]

Hi @ataylorme

We love seeing World contributions. The approach we're taking with community Worlds is that we'd like them to be published as third-party Worlds, which we then add/advertise on our list of Worlds. In order to get on this list, all you need is:

• Publish your World as an npm package
• Make a PR to our docs and the world-manifest.json file in this repo adding yourself

Once that's done, we'll verify whether the package works, is deployable/redeployable, and passes at least basic workflow e2e tests. If that looks good, we'll merge the PR! If your package gets significant community attention, we may consider moving to first-party support inside the workflow repository.