add wiremock extension

.github/workflows/wiremock.yml

@@ -0,0 +1,57 @@
+name: LocalStack WireMock Extension Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'wiremock/**'
+  push:
+    branches:
+      - main
+    paths:
+      - 'wiremock/**'
+  workflow_dispatch:
+
+env:
+  LOCALSTACK_DISABLE_EVENTS: "1"
+  LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
+
+jobs:
+  integration-tests:
+    name: Run WireMock Extension Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Set up LocalStack and extension
+        run: |
+          cd wiremock
+
+          docker pull localstack/localstack-pro &
+          docker pull wiremock/wiremock &
+          docker pull public.ecr.aws/lambda/python:3.9 &
+          pip install localstack terraform-local awscli-local[ver1]
+
+          make install
+          make dist
+          localstack extensions -v install file://$(ls ./dist/localstack_wiremock-*.tar.gz)
+
+          DEBUG=1 localstack start -d
+          localstack wait
+
+      - name: Run sample app test
+        run: |
+          cd wiremock
+          make sample
+
+      - name: Print logs
+        if: always()
+        run: |
+          localstack logs
+          localstack stop

wiremock/.gitignore

@@ -0,0 +1,9 @@
+.venv
+dist
+build
+**/*.egg-info
+.eggs
+.terraform*
+terraform.tfstate*
+*.zip
+.wiremock

wiremock/Makefile

@@ -0,0 +1,54 @@
+VENV_BIN = python3 -m venv
+VENV_DIR ?= .venv
+VENV_ACTIVATE = $(VENV_DIR)/bin/activate
+VENV_RUN = . $(VENV_ACTIVATE)
+
+usage:          ## Shows usage for this Makefile
+	@cat Makefile | grep -E '^[a-zA-Z_-]+:.*?## .*$$' | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+venv: $(VENV_ACTIVATE)
+
+$(VENV_ACTIVATE): pyproject.toml
+	test -d .venv || $(VENV_BIN) .venv
+	$(VENV_RUN); pip install --upgrade pip setuptools plux
+	$(VENV_RUN); pip install -e .[dev]
+	touch $(VENV_DIR)/bin/activate
+
+clean:
+	rm -rf .venv/
+	rm -rf build/
+	rm -rf .eggs/
+	rm -rf *.egg-info/
+
+install: venv   ## Install dependencies
+	$(VENV_RUN); python -m plux entrypoints
+
+dist: venv      ## Create distribution
+	$(VENV_RUN); python -m build
+
+publish: clean-dist venv dist   ## Publish extension to pypi
+	$(VENV_RUN); pip install --upgrade twine; twine upload dist/*
+
+entrypoints: venv   # Generate plugin entrypoints for Python package
+	$(VENV_RUN); python -m plux entrypoints
+
+format:		    ## Run ruff to format the whole codebase
+	$(VENV_RUN); python -m ruff format .; python -m ruff check --output-format=full --fix .
+
+test:		    ## Run integration tests (requires LocalStack running with the Extension installed)
+	$(VENV_RUN); pytest tests $(PYTEST_ARGS)
+
+sample:		    ## Deploy sample app
+	echo "Creating stubs in WireMock ..."
+	bin/create-stubs.sh
+	echo "Deploying sample app into LocalStack via Terraform ..."
+	(cd sample-app-oss; tflocal init; tflocal apply -auto-approve)
+	apiId=$$(awslocal apigateway get-rest-apis | jq -r '.items[0].id'); \
+	    endpoint=https://$$apiId.execute-api.us-east-1.localhost.localstack.cloud/dev/time-off; \
+	    echo "Invoking local API Gateway endpoint: $$endpoint"; \
+	    curl -k -v $$endpoint | grep time_off_date
+
+clean-dist: clean
+	rm -rf dist/
+
+.PHONY: clean clean-dist dist install publish usage venv format test

wiremock/README.md

@@ -0,0 +1,117 @@
+WireMock on LocalStack
+========================
+
+This repo contains a [LocalStack Extension](https://github.com/localstack/localstack-extensions) that facilitates developing [WireMock](https://wiremock.org)-based applications locally.
+
+The extension supports two modes:
+- **OSS WireMock**: Uses the open-source `wiremock/wiremock` image (default)
+- **WireMock Runner**: Uses `wiremock/wiremock-runner` with WireMock Cloud integration (requires API token)
+
+## Prerequisites
+
+* Docker
+* LocalStack Pro (free trial available)
+* `localstack` CLI
+* `make`
+* [WireMock CLI](https://docs.wiremock.io/cli/overview) (for WireMock Runner mode)
+
+## Install from GitHub repository
+
+This extension can be installed directly from this Github repo via:
+
+```bash
+localstack extensions install "git+https://github.com/localstack/localstack-extensions.git#egg=localstack-wiremock&subdirectory=wiremock"
+```
+
+## Install local development version
+
+To install the extension into localstack in developer mode, you will need Python 3.11, and create a virtual environment in the extensions project.
+
+In the newly generated project, simply run
+
+```bash
+make install
+```
+
+Then, to enable the extension for LocalStack, run
+
+```bash
+localstack extensions dev enable .
+```
+
+You can then start LocalStack with `EXTENSION_DEV_MODE=1` to load all enabled extensions:
+
+```bash
+EXTENSION_DEV_MODE=1 localstack start
+```
+
+## Usage
+
+### OSS WireMock Mode (Default)
+
+Start LocalStack without any special configuration:
+
+```bash
+localstack start
+```
+
+The WireMock server will be available at `http://wiremock.localhost.localstack.cloud:4566`.
+
+You can import stubs using the WireMock Admin API:
+
+```bash
+curl -X POST -H "Content-Type: application/json" \
+  --data-binary "@stubs.json" \
+  "http://wiremock.localhost.localstack.cloud:4566/__admin/mappings/import"
+```
+
+### WireMock Runner Mode (Cloud Integration)
+
+To use WireMock Runner with WireMock Cloud, you need:
+1. A WireMock Cloud API token
+2. A `.wiremock` directory with your mock API configuration
+
+#### Step 1: Get your WireMock Cloud API Token
+
+1. Sign up at [WireMock Cloud](https://app.wiremock.cloud)
+2. Go to Settings → API Tokens
+3. Create a new token
+
+#### Step 2: Create your Mock API configuration
+
+First, create a Mock API in WireMock Cloud, then pull the configuration locally:
+
+```bash
+# Install WireMock CLI if not already installed
+npm install -g wiremock
+
+# Login with your API token
+wiremock login
+
+# Pull your Mock API configuration
+# Find your Mock API ID from the WireMock Cloud URL (e.g., https://app.wiremock.cloud/mock-apis/zwg1l/...)
+wiremock pull mock-api <mock-api-id>
+```
+
+This creates a `.wiremock` directory with your `wiremock.yaml` configuration.
+
+#### Step 3: Start LocalStack with WireMock Runner
+
+```bash
+LOCALSTACK_WIREMOCK_API_TOKEN="your-api-token" \
+LOCALSTACK_WIREMOCK_CONFIG_DIR="/path/to/your/project" \
+localstack start
+```
+
+**Environment Variables:**
+- `WIREMOCK_API_TOKEN`: Your WireMock Cloud API token (required for runner mode)
+- `WIREMOCK_CONFIG_DIR`: Path to the directory containing your `.wiremock` folder (required for runner mode)
+
+Note: When using the LocalStack CLI, prefix environment variables with `LOCALSTACK_` to forward them to the container.
+
+## Sample Application
+
+See the `sample-app/` directory for a complete example using Terraform that demonstrates:
+- Creating an API Gateway
+- Lambda function that calls WireMock stubs
+- Integration testing with mocked external APIs

wiremock/bin/create-stubs.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# Import stubs into OSS WireMock (for WireMock Runner, use setup-wiremock-runner.sh)
+
+STUBS_URL="${STUBS_URL:-https://library.wiremock.org/catalog/api/p/personio.de/personio-de-personnel/personio.de-personnel-stubs.json}"
+TMP_STUBS_FILE="/tmp/personio-stubs.json"
+WIREMOCK_URL="${WIREMOCK_URL:-http://wiremock.localhost.localstack.cloud:4566}"
+
+echo "Downloading stubs from ${STUBS_URL}..."
+curl -s -o "$TMP_STUBS_FILE" "$STUBS_URL"
+
+echo "Importing stubs into WireMock at ${WIREMOCK_URL}..."
+curl -v -X POST -H "Content-Type: application/json" --data-binary "@$TMP_STUBS_FILE" "${WIREMOCK_URL}/__admin/mappings/import"
+
+echo ""
+echo "Verify stubs at: ${WIREMOCK_URL}/__admin/mappings"

wiremock/bin/setup-wiremock-runner.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+# Setup WireMock Runner for LocalStack
+
+set -e
+
+MOCK_API_NAME="${MOCK_API_NAME:-wiremock}"
+MOCK_API_PORT="${MOCK_API_PORT:-8080}"
+WIREMOCK_DIR="${WIREMOCK_DIR:-.wiremock}"
+STUBS_URL="${STUBS_URL:-https://library.wiremock.org/catalog/api/p/personio.de/personio-de-personnel/personio.de-personnel-stubs.json}"
+
+echo "=== WireMock Runner Setup ==="
+
+# Check prerequisites
+if ! command -v wiremock &> /dev/null; then
+    echo "Error: WireMock CLI not installed. Run: npm install -g wiremock"
+    exit 1
+fi
+
+if ! wiremock mock-apis list &> /dev/null; then
+    echo "Error: Not logged in. Run: wiremock login"
+    exit 1
+fi
+
+echo "✓ CLI authenticated"
+
+# Create Mock API
+echo "Creating Mock API '${MOCK_API_NAME}'..."
+wiremock mock-apis create "${MOCK_API_NAME}" 2>&1 || echo "Note: May already exist"
+
+wiremock mock-apis list
+echo ""
+echo "Enter Mock API ID:"
+read -r MOCK_API_ID
+
+[ -z "$MOCK_API_ID" ] && { echo "Error: Mock API ID required"; exit 1; }
+
+# Create config
+mkdir -p "${WIREMOCK_DIR}/stubs/${MOCK_API_NAME}/mappings"
+
+cat > "${WIREMOCK_DIR}/wiremock.yaml" << EOF
+services:
+  ${MOCK_API_NAME}:
+    type: 'REST'
+    name: '${MOCK_API_NAME}'
+    port: ${MOCK_API_PORT}
+    path: '/'
+    cloud_id: '${MOCK_API_ID}'
+EOF
+
+echo "✓ Created ${WIREMOCK_DIR}/wiremock.yaml"
+
+# Download stubs
+TMP_STUBS_FILE="/tmp/wiremock-stubs.json"
+curl -s -o "$TMP_STUBS_FILE" "$STUBS_URL"
+
+if [ -f "$TMP_STUBS_FILE" ] && command -v jq &> /dev/null; then
+    MAPPING_COUNT=$(jq '.mappings | length' "$TMP_STUBS_FILE" 2>/dev/null || jq 'length' "$TMP_STUBS_FILE" 2>/dev/null || echo "0")
+    if [ "$MAPPING_COUNT" != "0" ] && [ "$MAPPING_COUNT" != "null" ]; then
+        for i in $(seq 0 $((MAPPING_COUNT - 1))); do
+            jq ".mappings[$i] // .[$i]" "$TMP_STUBS_FILE" > "${WIREMOCK_DIR}/stubs/${MOCK_API_NAME}/mappings/mapping-$i.json" 2>/dev/null
+        done
+        echo "✓ Extracted ${MAPPING_COUNT} stubs"
+    fi
+fi
+
+echo ""
+echo "=== Setup Complete ==="
+echo ""
+echo "Start LocalStack with:"
+echo "  LOCALSTACK_WIREMOCK_API_TOKEN=\"your-token\" \\"
+echo "  LOCALSTACK_WIREMOCK_CONFIG_DIR=\"$(pwd)\" \\"
+echo "  localstack start"
+echo ""
+echo "WireMock available at: http://wiremock.localhost.localstack.cloud:4566"

wiremock/localstack_wiremock/__init__.py

@@ -0,0 +1 @@
+name = "localstack_wiremock"