Hiraeth: A Local AWS SQS Emulator for Fast Integration Testing

Hiraeth is a new open-source project that addresses a common pain point in cloud development: the need for fast, reliable integration testing without the overhead and cost of hitting actual AWS services. The project, which is still in its early stages, focuses specifically on emulating AWS Simple Queue Service (SQS) locally, allowing developers to test their queue-based workflows with the same interface they'd use in production.

The core innovation of Hiraeth lies in its approach to local AWS emulation. Rather than trying to be a full AWS replacement, it targets the specific needs of developers working on integration tests. Signed AWS SDK requests are routed through a local HTTP endpoint, with all state managed in SQLite databases. This design choice makes it particularly well-suited for development environments where speed and reliability are paramount.

Getting Started with Hiraeth

Setting up Hiraeth is straightforward, thanks to its Docker Compose support. After running docker compose up --build, developers get two endpoints: the AWS-compatible endpoint on port 4566 and a web admin UI on port 4567. The project even includes a seeded credential (test/test) to get developers up and running quickly.

The quickstart guide demonstrates the simplicity of the workflow. Using the AWS CLI with the --endpoint-url flag, developers can create queues, send messages, and receive them—all against the local emulator. This approach means existing AWS SDK code can work with minimal changes, making it easy to integrate into existing projects.

Technical Architecture

Under the hood, Hiraeth uses Rust and leverages several modern development tools. The project employs SQLx for database operations with offline query metadata checking, ensuring SQL queries are validated at compile time. This attention to type safety and query correctness is particularly valuable for a project that aims to provide a reliable testing environment.

The web UI, while described as "local admin preview," provides crucial debugging capabilities. It allows developers to inspect queue state, view messages, and manage queue attributes without needing to write additional tooling. The UI currently uses CDN-hosted assets for Tailwind, DaisyUI, and htmx, though the maintainers note that a fully self-contained asset pipeline is planned for the future.

Current Capabilities and Limitations

Hiraeth's SQS API support is comprehensive for core operations. It handles queue creation, message sending and receiving, batch operations, and queue management. The project uses clear labeling to indicate the status of each API operation: Supported, Partial, or Not Implemented. This transparency helps developers understand exactly what they can and cannot do with the current release.

However, the project is upfront about its limitations. IAM and queue policy enforcement aren't implemented yet, and FIFO queue behavior, while storing the necessary fields, doesn't fully model AWS's ordering and deduplication semantics. These are acknowledged gaps that the maintainers plan to address in future releases.

Development Workflow and Quality Assurance

The project's development approach is noteworthy. While the maintainers acknowledge using AI tools for code generation, refactoring, and test writing, they emphasize that all changes undergo human review and are subject to normal engineering checks. This hybrid approach—leveraging AI for productivity while maintaining human oversight—reflects modern software development practices.

The testing strategy is particularly robust. The project includes both unit tests and AWS SDK integration tests, ensuring that the emulator behaves as expected not just in isolation but when used with actual AWS SDKs. This dual approach to testing is crucial for a project that aims to provide a drop-in replacement for AWS services in testing scenarios.

Use Cases and Target Audience

Hiraeth is explicitly designed for local development and test environments, not as a production AWS replacement. This focus makes it ideal for several scenarios:

• Integration testing of applications that use SQS
• Development environments where hitting actual AWS services would be costly or slow
• Automated testing pipelines that need to simulate queue behavior
• Debugging complex queue interactions without the noise of actual AWS services

For teams that heavily rely on SQS in their architecture, Hiraeth could significantly speed up the development and testing cycle by eliminating network latency and potential costs associated with AWS usage during development.

Future Development

The maintainers have outlined clear paths for future development. Beyond expanding SQS support and filling current gaps, there's potential for supporting additional AWS services. The modular architecture, with separate runtime and web UI components, suggests the project could evolve to support other AWS services while maintaining the same development workflow.

The project's early stage also means there's an opportunity for community involvement. With clear contribution guidelines and a focus on practical utility over theoretical completeness, Hiraeth represents an interesting case study in building developer tools that solve specific, well-defined problems rather than trying to be everything to everyone.

Conclusion

Hiraeth represents a pragmatic approach to a common development challenge. By focusing specifically on SQS emulation for testing purposes, it avoids the complexity of trying to be a full AWS clone while still providing significant value to developers. The combination of SQLite for state management, a web UI for debugging, and comprehensive API support makes it a compelling option for teams looking to improve their integration testing workflow.

The project's transparency about its limitations, combined with its clear development roadmap, suggests it's a tool that will continue to evolve based on real developer needs rather than chasing feature completeness for its own sake. For teams struggling with slow or expensive integration tests involving SQS, Hiraeth offers a promising alternative that could significantly improve their development velocity.