feat(serverless-offline-sqs): opt-in autoStart ElasticMQ for self-contained operation (Fixes #146)

[silouone]

Fixes #146

What / why

Adds opt-in self-contained operation to serverless-offline-sqs: with autoStart: true the plugin spawns an ElasticMQ container from its own lifecycle, points the SQS client at it, and tears it down on stop/SIGINT — so you no longer have to stand up ElasticMQ yourself. Paired with autoCreate: true it's a true zero-setup local SQS:

custom:
  serverless-offline-sqs:
    autoStart: true      # spin up ElasticMQ automatically
    autoCreate: true     # create the declared/event queues inside it

Default is OFF — with autoStart unset, behavior is byte-for-byte identical to today (no Docker invocation, no endpoint mutation).

Design decision: Docker-managed, not a vendored pure-JS emulator

The earlier discussion leaned toward bundling a pure-JS SQS server. I went with Docker-managed softwaremill/elasticmq-native instead, because the only credible JS option (sqslite) is unmaintained (last publish 2022, Fastify v3 EOL) and — critically — does not implement FIFO semantics, which would silently diverge from the FIFO (#189) and DLQ-ordering (#167) work this repo validates against ElasticMQ. Docker-managed reuses the exact engine the whole test suite already targets, so there's zero behavioral drift.

Honest caveat (also noted on the issue): this is "self-contained given Docker", not zero-runtime — true JVM-free bundling isn't possible without an incomplete emulator. Docker is the smallest reliable common denominator for this codebase (every integration test is already docker-compose-based). sqslite remains a possible future engine: opt-in for Docker-less, non-FIFO users.

Safety / lifecycle

• Endpoint is set before the SQS client is built, so autoCreate + polling all target the container.
• Explicit user endpoint always wins (autoStart skipped + warned).
• Fail-fast with a clear, Docker-naming error if Docker is unavailable — before any container is started.
• Readiness-polled with a timeout (tears down + throws on timeout).
• Teardown on offline:start:end and SIGINT/SIGTERM; stop() is idempotent.
• Container run --rm + fixed --name so a leaked container (hard crash) is reclaimed on the next start; and if a later start() step throws after the container is up, it's torn down immediately (no single-session leak).
• No new runtime dependency — Docker via the built-in child_process CLI, readiness via built-in fetch.

Credit

Thanks @tstackhouse for the well-framed proposal and @tristan-mastrodicasa for the +1.

Verification

npx ava → 175 unit tests pass (149 pre-existing untouched + 26 new #146), npx eslint clean, zero new runtime deps. The real Docker integration test ran green (Docker 29, ~6.4s): container boots, both an event-wired and a resource-only queue autoCreate inside it, a message round-trips, end() removes the container, docker ps -a shows no leftover. Independently re-run by the orchestrator after a mid-start-leak hardening commit.

Touches serverless-offline-sqs index.js/test/index.js, so it overlaps the in-flight #294 (B2 destinations) and the resilience-polish branch — straightforward rebase, just a deliberate merge order.

🤖 Generated with Claude Code