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 layout of other extensions in the repo: Makefile targets, CI workflow, and a Terraform sample app (API Gateway + Lambda calling a mocked Orders API).

/cc @HarshCasper @remotesynth @255kb

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). The default image is pinned to mockoon/cli:9 (the extension relies on the v9 CLI flags and admin API), and MOCKOON_IMAGE overrides it. Relative MOCKOON_DATA paths are rejected at startup, since Docker would otherwise mount an empty directory.

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 uses the new lstk CLI (installed via npm, pinned): the built extension is mounted into the container and installed at startup via EXTENSION_AUTO_INSTALL, LocalStack is started with LOCALSTACK_MOCKOON_DATA pointing to sample-app/environment.json, and the sample app is deployed via lstk terraform

All passed in CI (latest and dev images).

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.
• The README now uses lstk. As lstk has no extension commands, the extension is installed via EXTENSION_AUTO_INSTALL; developer mode still requires the legacy localstack CLI (it mounts the extension sources into the container).

🤖 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

[purcell]

I looked through this and tested it out locally, so it's good to go. Ideally we'd use the regular CLI rather than lstk with LOCALSTACK_EXTENSION_AUTO_INSTALL: it introduces yet another pattern in the extension workflows, and the README tells the user to use the former anyway. That's not a blocker though.