Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

fix(apigateway): populate pathParameters and fix queryStringParameters in v2 proxy event (#239)

Stephan Mielkec67c5e7b9bf7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f2d68233..a7a30ae3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,9 @@ Versioning follows [Semantic Versioning](https://semver.org/).
### Fixed
- **API Gateway v1/v2 returns mock response for Node.js Lambdas** — `_invoke_lambda_proxy` in both `apigateway.py` (v2) and `apigateway_v1.py` (v1) only dispatched to the warm worker pool for Python runtimes. Node.js Lambdas received a hardcoded `"Mock response"` instead of being executed, even though the warm worker pool in `lambda_runtime.py` already supports Node.js. Now checks for both `python` and `nodejs` runtimes.
+- **API Gateway v2 missing `pathParameters` in Lambda event** — Routes with path parameters (e.g. `GET /items/{itemId}`) did not extract parameter values into the Lambda proxy event's `pathParameters` field. Handlers received `undefined` instead of `{ "itemId": "..." }`. Now extracts parameters from both `{param}` and `{proxy+}` route templates.
+- **API Gateway v2 `queryStringParameters` incorrect for multi-value params** — Multi-value query parameters (e.g. `?tag=a&tag=b`) were passed as Python lists instead of comma-joined strings. Now joins values with commas (`"tag": "a,b"`) matching the AWS API Gateway v2 payload format 2.0 spec.
+- **API Gateway v2 `rawQueryString` stringified lists** — Multi-value query parameters were rendered as `tag=['a', 'b']` instead of `tag=a&tag=b`. Now expands repeated keys correctly.
- **Lambda Docker executor fails for `provided` runtimes** — `_execute_function_docker()` mounted Lambda code only at `/var/task` and overrode CMD to `["/var/task/bootstrap"]`, but the AWS RIE entrypoint (`/lambda-entrypoint.sh`) in `public.ecr.aws/lambda/provided:al2023` expects the bootstrap binary at `/var/runtime/bootstrap`. Now mounts code at both `/var/task` and `/var/runtime` (matching real AWS layout) and passes `"bootstrap"` as CMD so the RIE finds the handler correctly. Contributed by @jayjanssen.
---
diff --git a/ministack/services/apigateway.py b/ministack/services/apigateway.py
index 130fa270..5ecb4083 100644
--- a/ministack/services/apigateway.py
+++ b/ministack/services/apigateway.py
@@ -266,7 +266,12 @@ async def handle_execute(api_id, stage, path, method, headers, body, query_param
integration_type = integration.get("integrationType", "")
if integration_type == "AWS_PROXY":
- return await _invoke_lambda_proxy(integration, api_id, stage, path, method, headers, body, query_params, route.get("routeKey", "$default"))
+ route_key = route.get("routeKey", "$default")
+ path_params = None
+ rk_parts = route_key.split(" ", 1)
+ if len(rk_parts) == 2:
+ path_params = _extract_path_params(rk_parts[1], path) or None
+ return await _invoke_lambda_proxy(integration, api_id, stage, path, method, headers, body, query_params, route_key, path_params)
elif integration_type == "HTTP_PROXY":
return await _invoke_http_proxy(integration, path, method, headers, body, query_params)
else:
@@ -293,32 +298,41 @@ def _match_route(api_id, method, path):
return None
-def _path_matches(route_path: str, request_path: str) -> bool:
+def _extract_path_params(route_path: str, request_path: str) -> dict | None:
"""
- Match a route path against a request path.
+ Extract path parameter values from a request path using the route template.
+ Returns a dict of {paramName: value} on match, or None if no match.
Supports:
{param} — single path segment (no slashes)
{proxy+} — greedy match (one or more path segments, may include slashes)
"""
- # Build regex by splitting on placeholders
parts = re.split(r"(\{[^}]+\})", route_path)
pattern_parts = []
+ param_names = []
for part in parts:
if part.startswith("{") and part.endswith("}"):
inner = part[1:-1]
if inner.endswith("+"):
- # greedy — matches one or more characters including slashes
- pattern_parts.append(".+")
+ param_names.append(inner[:-1])
+ pattern_parts.append("(.+)")
else:
- # single segment — no slashes
- pattern_parts.append("[^/]+")
+ param_names.append(inner)
+ pattern_parts.append("([^/]+)")
else:
pattern_parts.append(re.escape(part))
- return bool(re.fullmatch("".join(pattern_parts), request_path))
+ m = re.fullmatch("".join(pattern_parts), request_path)
+ if not m:
+ return None
+ return dict(zip(param_names, m.groups())) if param_names else {}
+
+
+def _path_matches(route_path: str, request_path: str) -> bool:
+ """Match a route path against a request path."""
+ return _extract_path_params(route_path, request_path) is not None
-async def _invoke_lambda_proxy(integration, api_id, stage, path, method, headers, body, query_params, route_key="$default"):
+async def _invoke_lambda_proxy(integration, api_id, stage, path, method, headers, body, query_params, route_key="$default", path_params=None):
"""Invoke a Lambda function using the API Gateway v2 proxy event format."""
from ministack.core.lambda_runtime import get_or_create_worker
from ministack.services import lambda_svc
@@ -333,12 +347,14 @@ async def _invoke_lambda_proxy(integration, api_id, stage, path, method, headers
return 502, {"Content-Type": "application/json"}, json.dumps({"message": f"Lambda function '{func_name}' not found"}).encode()
# Build API Gateway v2 proxy event (payload format 2.0)
- qs = {k: v[0] if len(v) == 1 else v for k, v in query_params.items()}
+ # AWS API Gateway v2 joins multi-value query params with commas
+ qs = {k: ",".join(v) for k, v in query_params.items()} if query_params else None
+ raw_qs = "&".join(f"{k}={val}" for k, vals in query_params.items() for val in vals)
event = {
"version": "2.0",
"routeKey": route_key,
"rawPath": path,
- "rawQueryString": "&".join(f"{k}={v}" for k, v in query_params.items()),
+ "rawQueryString": raw_qs,
"headers": dict(headers),
"queryStringParameters": qs,
"requestContext": {
@@ -358,6 +374,7 @@ async def _invoke_lambda_proxy(integration, api_id, stage, path, method, headers
"time": time.strftime("%d/%b/%Y:%H:%M:%S +0000"),
"timeEpoch": int(time.time() * 1000),
},
+ "pathParameters": path_params,
"body": body.decode("utf-8", errors="replace") if body else None,
"isBase64Encoded": False,
}
diff --git a/tests/test_apigw.py b/tests/test_apigw.py
index 775d00ee..2d78c982 100644
--- a/tests/test_apigw.py
+++ b/tests/test_apigw.py
@@ -385,6 +385,269 @@ def test_apigw_path_param_route(apigw, lam):
apigw.delete_api(ApiId=api_id)
lam.delete_function(FunctionName=fname)
+def test_apigw_path_parameters_in_event(apigw, lam):
+ """API Gateway v2 should populate pathParameters in the Lambda event."""
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-pathparam-{_uuid.uuid4().hex[:8]}"
+ code = (
+ "import json\n"
+ "def handler(event, context):\n"
+ " return {'statusCode': 200, 'body': json.dumps(event.get('pathParameters'))}\n"
+ )
+ lam.create_function(
+ FunctionName=fname,
+ Runtime="python3.9",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(code)},
+ )
+ api_id = apigw.create_api(Name=f"pp-api-{fname}", ProtocolType="HTTP")["ApiId"]
+ int_id = apigw.create_integration(
+ ApiId=api_id,
+ IntegrationType="AWS_PROXY",
+ IntegrationUri=f"arn:aws:lambda:us-east-1:000000000000:function:{fname}",
+ PayloadFormatVersion="2.0",
+ )["IntegrationId"]
+ apigw.create_route(ApiId=api_id, RouteKey="GET /items/{itemId}", Target=f"integrations/{int_id}")
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ try:
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/items/my-item-42"
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}")
+ resp = _urlreq.urlopen(req)
+ assert resp.status == 200
+ body = json.loads(resp.read())
+ assert body == {"itemId": "my-item-42"}
+ finally:
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
+
+def test_apigw_greedy_path_parameters_in_event(apigw, lam):
+ """{proxy+} greedy path parameter should be extracted into pathParameters."""
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-greedy-pp-{_uuid.uuid4().hex[:8]}"
+ code = (
+ "import json\n"
+ "def handler(event, context):\n"
+ " return {'statusCode': 200, 'body': json.dumps(event.get('pathParameters'))}\n"
+ )
+ lam.create_function(
+ FunctionName=fname,
+ Runtime="python3.9",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(code)},
+ )
+ api_id = apigw.create_api(Name=f"greedy-pp-{fname}", ProtocolType="HTTP")["ApiId"]
+ int_id = apigw.create_integration(
+ ApiId=api_id,
+ IntegrationType="AWS_PROXY",
+ IntegrationUri=f"arn:aws:lambda:us-east-1:000000000000:function:{fname}",
+ PayloadFormatVersion="2.0",
+ )["IntegrationId"]
+ apigw.create_route(ApiId=api_id, RouteKey="GET /files/{proxy+}", Target=f"integrations/{int_id}")
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ try:
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/files/a/b/c.txt"
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}")
+ resp = _urlreq.urlopen(req)
+ assert resp.status == 200
+ body = json.loads(resp.read())
+ assert body == {"proxy": "a/b/c.txt"}
+ finally:
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
+
+def test_apigw_query_params_and_headers_in_event(apigw, lam):
+ """API Gateway v2 should pass queryStringParameters, rawQueryString, and headers to Lambda."""
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-qp-{_uuid.uuid4().hex[:8]}"
+ code = (
+ "import json\n"
+ "def handler(event, context):\n"
+ " return {'statusCode': 200, 'body': json.dumps({\n"
+ " 'qs': event.get('queryStringParameters'),\n"
+ " 'rawQs': event.get('rawQueryString'),\n"
+ " 'customHeader': event.get('headers', {}).get('x-custom-header'),\n"
+ " })}\n"
+ )
+ lam.create_function(
+ FunctionName=fname,
+ Runtime="python3.9",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(code)},
+ )
+ api_id = apigw.create_api(Name=f"qp-api-{fname}", ProtocolType="HTTP")["ApiId"]
+ int_id = apigw.create_integration(
+ ApiId=api_id,
+ IntegrationType="AWS_PROXY",
+ IntegrationUri=f"arn:aws:lambda:us-east-1:000000000000:function:{fname}",
+ PayloadFormatVersion="2.0",
+ )["IntegrationId"]
+ apigw.create_route(ApiId=api_id, RouteKey="GET /search", Target=f"integrations/{int_id}")
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ try:
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/search?q=hello&tag=a&tag=b"
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}")
+ req.add_header("X-Custom-Header", "test-value")
+ resp = _urlreq.urlopen(req)
+ assert resp.status == 200
+ body = json.loads(resp.read())
+ assert body["qs"]["q"] == "hello"
+ # Multi-value params should be comma-joined per AWS API Gateway v2 spec
+ assert body["qs"]["tag"] == "a,b"
+ assert "q=hello" in body["rawQs"]
+ assert "tag=a" in body["rawQs"]
+ assert "tag=b" in body["rawQs"]
+ assert body["customHeader"] == "test-value"
+ finally:
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
+
+def test_apigw_multiple_path_parameters(apigw, lam):
+ """Multiple path parameters in one route should all be extracted."""
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-multi-pp-{_uuid.uuid4().hex[:8]}"
+ code = (
+ "import json\n"
+ "def handler(event, context):\n"
+ " return {'statusCode': 200, 'body': json.dumps(event.get('pathParameters'))}\n"
+ )
+ lam.create_function(
+ FunctionName=fname,
+ Runtime="python3.9",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(code)},
+ )
+ api_id = apigw.create_api(Name=f"multi-pp-{fname}", ProtocolType="HTTP")["ApiId"]
+ int_id = apigw.create_integration(
+ ApiId=api_id,
+ IntegrationType="AWS_PROXY",
+ IntegrationUri=f"arn:aws:lambda:us-east-1:000000000000:function:{fname}",
+ PayloadFormatVersion="2.0",
+ )["IntegrationId"]
+ apigw.create_route(
+ ApiId=api_id,
+ RouteKey="GET /projects/{projectKey}/items/{itemId}",
+ Target=f"integrations/{int_id}",
+ )
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ try:
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/projects/bunya/items/prod-42"
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}")
+ resp = _urlreq.urlopen(req)
+ assert resp.status == 200
+ body = json.loads(resp.read())
+ assert body == {"projectKey": "bunya", "itemId": "prod-42"}
+ finally:
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
+
+def test_apigw_no_path_parameters_returns_null(apigw, lam):
+ """Routes without path parameters should have pathParameters as null."""
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-no-pp-{_uuid.uuid4().hex[:8]}"
+ code = (
+ "import json\n"
+ "def handler(event, context):\n"
+ " return {'statusCode': 200, 'body': json.dumps({'pp': event.get('pathParameters')})}\n"
+ )
+ lam.create_function(
+ FunctionName=fname,
+ Runtime="python3.9",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(code)},
+ )
+ api_id = apigw.create_api(Name=f"no-pp-{fname}", ProtocolType="HTTP")["ApiId"]
+ int_id = apigw.create_integration(
+ ApiId=api_id,
+ IntegrationType="AWS_PROXY",
+ IntegrationUri=f"arn:aws:lambda:us-east-1:000000000000:function:{fname}",
+ PayloadFormatVersion="2.0",
+ )["IntegrationId"]
+ apigw.create_route(ApiId=api_id, RouteKey="GET /products", Target=f"integrations/{int_id}")
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ try:
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/products"
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}")
+ resp = _urlreq.urlopen(req)
+ assert resp.status == 200
+ body = json.loads(resp.read())
+ assert body["pp"] is None
+ finally:
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
+
+def test_apigw_url_encoded_path_parameter(apigw, lam):
+ """URL-encoded characters in path parameters are decoded by the ASGI layer."""
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-enc-pp-{_uuid.uuid4().hex[:8]}"
+ code = (
+ "import json\n"
+ "def handler(event, context):\n"
+ " return {'statusCode': 200, 'body': json.dumps(event.get('pathParameters'))}\n"
+ )
+ lam.create_function(
+ FunctionName=fname,
+ Runtime="python3.9",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(code)},
+ )
+ api_id = apigw.create_api(Name=f"enc-pp-{fname}", ProtocolType="HTTP")["ApiId"]
+ int_id = apigw.create_integration(
+ ApiId=api_id,
+ IntegrationType="AWS_PROXY",
+ IntegrationUri=f"arn:aws:lambda:us-east-1:000000000000:function:{fname}",
+ PayloadFormatVersion="2.0",
+ )["IntegrationId"]
+ apigw.create_route(ApiId=api_id, RouteKey="GET /items/{itemId}", Target=f"integrations/{int_id}")
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ try:
+ # URL-encode a value with special characters
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/items/hello%20world"
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}")
+ resp = _urlreq.urlopen(req)
+ assert resp.status == 200
+ body = json.loads(resp.read())
+ # AWS passes the decoded value in pathParameters
+ assert body["itemId"] == "hello world"
+ finally:
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
+
def test_apigw_greedy_path_param(apigw, lam):
"""{proxy+} greedy path parameter matches paths with multiple segments."""
import urllib.request as _urlreq