Add Mockoon extension

[whummer]

Summary

Adds a new extension that runs Mockoon (mockoon/cli image) next to LocalStack, serving mock APIs under http://mockoon.localhost.localstack.cloud:4566. The setup follows the WireMock extension: same Makefile targets, CI workflow, and a Terraform sample app (API Gateway + Lambda calling a mocked Orders API).

How mocks are loaded

Mockoon's admin API can update responses at runtime but can't add routes, so mocks get loaded at container start via MOCKOON_DATA:

• absolute host path to an environment file (mounted and watched, so edits reload without a restart)
• a URL, or cloud://<id> (with MOCKOON_CLOUD_TOKEN)
• unset: a bundled default environment with a GET /welcome route

The admin API is proxied at /mockoon-admin, with bearer token MOCKOON_ADMIN_API_TOKEN (default test). MOCKOON_IMAGE overrides the image.

Testing

• make test: integration tests for templating, response rules, admin API auth, logs, global vars, and runtime environment updates
• make sample: deploys the sample app and checks the Lambda response
• CI starts LocalStack with LOCALSTACK_MOCKOON_DATA pointing to sample-app/environment.json, then runs both

All passed locally against LocalStack Pro.

Notes

• Requests to the bare root path / aren't forwarded by the shared ProxyResource in utils (route is /<path:path>), which is why the default route is /welcome. Left utils untouched here.
• Package name is localstack-mockoon to match localstack-wiremock.

🤖 Generated with Claude Code

[whummer]

Commands for testing this directly from the branch, no checkout needed (requires LOCALSTACK_AUTH_TOKEN).

Note: installing via git+https://... currently fails with the latest LocalStack image (git in the image is a dulwich shim that doesn't support git version, which pip calls), so this uses the GitHub archive URL instead.

# 1. Install the extension from the branch
localstack extensions install 'localstack-mockoon @ https://github.com/localstack/localstack-extensions/archive/refs/heads/add-mockoon-extension.tar.gz#subdirectory=mockoon'

# 2. Start LocalStack; Mockoon loads the sample environment from the branch via URL
#    (stop a running instance first: env vars only apply at startup)
localstack stop
LOCALSTACK_MOCKOON_DATA="https://raw.githubusercontent.com/localstack/localstack-extensions/add-mockoon-extension/mockoon/sample-app/environment.json" \
  localstack start -d
localstack wait -t 120

# 3. Mock routes
curl -s http://mockoon.localhost.localstack.cloud:4566/orders/42          # templated: "id": "42", status shipped
curl -s -i http://mockoon.localhost.localstack.cloud:4566/orders/unknown  # response rule: 404 "Order not found"
curl -s -X POST -H "Content-Type: application/json" -d '{"sku":"SKU-42"}' \
  http://mockoon.localhost.localstack.cloud:4566/orders                   # 201, echoes "sku": "SKU-42"

# 4. Admin API (default token: test)
curl -s -o /dev/null -w "%{http_code}\n" http://mockoon.localhost.localstack.cloud:4566/mockoon-admin/logs   # 401
curl -s -H "Authorization: Bearer test" http://mockoon.localhost.localstack.cloud:4566/mockoon-admin/logs     # transaction logs

# 5. Optional: default mode (no MOCKOON_DATA)
localstack stop
localstack start -d && localstack wait -t 120
curl -s http://mockoon.localhost.localstack.cloud:4566/welcome

# 6. Optional: hot reload with a local file (path must be absolute, edit the file in place)
localstack stop
curl -sO https://raw.githubusercontent.com/localstack/localstack-extensions/add-mockoon-extension/mockoon/sample-app/environment.json
LOCALSTACK_MOCKOON_DATA="$PWD/environment.json" localstack start -d && localstack wait -t 120
curl -s http://mockoon.localhost.localstack.cloud:4566/orders/42          # edit environment.json, re-run: changes appear after ~2s

# 7. Clean up
localstack stop
localstack extensions uninstall localstack-mockoon