GitHub – SethPyle376/hiraeth · GitHub

Hirath is a local AWS emulator focused on fast integration testing. The first release target is SQS: signed AWS SDK requests go through a local HTTP endpoint, state is stored in SQLite, and an optional web UI exposes local emulator state for debugging.

This project is quick. It is intended for local development and test environments, not as a production AWS replacement.

• AWS SigV4 header authentication with seeded local test credentials.
• SQLite-supported principals, access keys, queues, messages, attributes, and tags.
• SQS-compliant endpoint for common queuing and messaging operations.
• Web Admin UI on a separate port to inspect local emulator status.
• Docker and Docker Compose support.
• SQLx offline query metadata for the tested SQL builds.

Start Hirath with Docker Compose:

docker compose up --build

AWS-compliant endpoint listens http://localhost:4566. Admin UI listens http://localhost:4567.

The default preferred credential is:

export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

Create and inspect a queue with the AWS CLI:

aws --endpoint-url http://localhost:4566 sqs create-queue --queue-name local-orders
aws --endpoint-url http://localhost:4566 sqs list-queues
aws --endpoint-url http://localhost:4566 sqs send-message \
  --queue-url http://localhost:4566/000000000000/local-orders \
  --message-body "hello from hiraeth"
aws --endpoint-url http://localhost:4566 sqs receive-message \
  --queue-url http://localhost:4566/000000000000/local-orders \
  --message-attribute-names All

Compose stores SQLite data in a named volume hiraeth-data.

Release images are published to the GitHub container registry:

docker pull ghcr.io/sethpyle376/hiraeth:v0.1.0

Release maintainers can publish a multi-architecture image for linux/amd64
And linux/arm64 From local Docker BuildX environment:

docker login ghcr.io
scripts/publish-image.sh v0.1.0

publish script pushes ghcr.io/sethpyle376/hiraeth:. Tags must match release format v*.*.*.

mkdir -p .local
HIRAETH_DATABASE_URL=sqlite://.local/db.sqlite cargo run -p hiraeth_runtime

Default:

When running from source, prioritize settings HIRAETH_DATABASE_URL down to a path
.local/ Or any other directory that already exists.

The web UI is an admin/debug surface for local emulator status. It currently supports SQS queue browsing, queue details, message inspection, attributes, tags, purge, delete queue and delete message.

The web UI does not use SigV4 authentication. Keep HIRAETH_WEB_HOST Unless you intentionally want to expose local test state, it will remain connected to a trusted interface.

The current UI uses CDN-hosted Tailwind, DaisyUI, and HTML assets. Fully self-contained/offline UI asset pipeline still in the works in the future.

Status Label:

• Supported: Implemented and covered by unit and/or AWS SDK integration tests.
• Partial: Implemented, but the known AWS Edge behavior is incomplete.
• Not implemented:requests return currently UnsupportedOperation.

• IAM and queue policy enforcement are not implemented yet.
• Error responses are SDK-compatible for common paths, but not the same as AWS.
• Request validation is practical and still requires a deeper AWS Parity pass.
• FIFO behavior stores FIFO fields, but does not yet fully model the ordering, deduplication window, or throughput behavior.
• The web UI is a local administrator preview and is not certified.

AI tools are used as part of the development workflow of this project for code generation, refactoring, test writing, documentation drafts, and design discussions.

Most of the runtime code is written by hand, most of the test code is generated. Regardless, all changes are reviewed, edited, and accepted by a human maintainer, and the project relies on general engineering checks such as testing, SQLX query checking, and manual review rather than treating AI outputs as official.

Hirath is licensed under the MIT License.

Format and Test:

Prepare the local database to be used by SQLx query checking:

cargo run -p xtask -- prepare-db

Refresh SQLx offline metadata:

DATABASE_URL=sqlite://.local/db.sqlite cargo sqlx prepare --workspace -- --all-targets

Check SQLx metadata in CI-style mode:

DATABASE_URL=sqlite://.local/db.sqlite cargo sqlx prepare --workspace --check -- --all-targets

SQL metadata checked below .sqlx/ Must be committed when changes to queries or migrations occur.