Skip to content

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

fix(apigateway): v2 Lambda-proxy honors isBase64Encoded in both directions (#766)

rmlasseterb1612ecddda6
diff --git a/ministack/services/apigateway.py b/ministack/services/apigateway.py
index 2e43b1f8..85275019 100644
--- a/ministack/services/apigateway.py
+++ b/ministack/services/apigateway.py
@@ -921,6 +921,22 @@ def _path_matches(route_path: str, request_path: str) -> bool:
return _extract_path_params(route_path, request_path) is not None
+def _v2_request_body_is_text(content_type: str | None) -> bool:
+ """Whether an HTTP API (v2) request body is delivered as a UTF-8 string.
+
+ Real AWS delivers the body as text (``isBase64Encoded`` false) only for a
+ whitelist of content types; everything else — including a missing content
+ type and ``application/x-www-form-urlencoded`` — is base64-encoded. The docs
+ don't enumerate this, so the set below was verified against live AWS.
+ """
+ ct = (content_type or "").split(";", 1)[0].strip().lower()
+ return ct.startswith("text/") or ct in (
+ "application/json",
+ "application/xml",
+ "application/javascript",
+ )
+
+
async def _invoke_lambda_proxy(
integration,
api_id,
@@ -957,6 +973,15 @@ async def _invoke_lambda_proxy(
# 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)
+ # Binary request bodies are base64-encoded with isBase64Encoded=true; only
+ # the text content types AWS recognizes are passed through as UTF-8 strings.
+ if body:
+ if _v2_request_body_is_text(headers.get("content-type")):
+ req_body, req_is_base64 = body.decode("utf-8", errors="replace"), False
+ else:
+ req_body, req_is_base64 = base64.b64encode(body).decode("ascii"), True
+ else:
+ req_body, req_is_base64 = None, False
event = {
"version": "2.0",
"routeKey": route_key,
@@ -982,8 +1007,8 @@ async def _invoke_lambda_proxy(
"timeEpoch": int(time.time() * 1000),
},
"pathParameters": path_params,
- "body": body.decode("utf-8", errors="replace") if body else None,
- "isBase64Encoded": False,
+ "body": req_body,
+ "isBase64Encoded": req_is_base64,
}
if authorizer_claims is not None:
event["requestContext"]["authorizer"] = {
@@ -1027,7 +1052,13 @@ async def _invoke_lambda_proxy(
del resp_headers[existing]
resp_headers["Set-Cookie"] = list(cookies)
resp_body = lambda_response.get("body", "")
- if isinstance(resp_body, str):
+ # A base64-encoded body (isBase64Encoded=true) is decoded to its raw bytes
+ # before sending. HTTP APIs (v2) honor this unconditionally — there is no
+ # binaryMediaTypes negotiation as in REST (v1) — so a true flag always means
+ # "the body string is base64; emit the decoded bytes."
+ if lambda_response.get("isBase64Encoded") and isinstance(resp_body, str):
+ resp_body = base64.b64decode(resp_body)
+ elif isinstance(resp_body, str):
resp_body = resp_body.encode("utf-8")
elif isinstance(resp_body, dict):
resp_body = json.dumps(resp_body, ensure_ascii=False).encode("utf-8")
diff --git a/tests/test_apigatewayv2.py b/tests/test_apigatewayv2.py
index 83afc5f7..4adbefdc 100644
--- a/tests/test_apigatewayv2.py
+++ b/tests/test_apigatewayv2.py
@@ -570,6 +570,132 @@ def test_apigw_execute_lambda_proxy_header_case_override(apigw, lam):
apigw.delete_api(ApiId=api_id)
lam.delete_function(FunctionName=fname)
+def test_apigw_execute_lambda_proxy_base64_body(apigw, lam):
+ """A base64 response body (isBase64Encoded) is decoded to raw bytes.
+
+ HTTP API (v2) honors isBase64Encoded unconditionally. The response must
+ carry the decoded binary, not the literal base64 string.
+ """
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-apigw-b64-{_uuid.uuid4().hex[:8]}"
+ # All 256 byte values — definitely not valid UTF-8, so a literal-base64
+ # regression would not compare equal.
+ code = (
+ b"import base64\n"
+ b"def handler(event, context):\n"
+ b" raw = bytes(range(256))\n"
+ b" return {\n"
+ b" 'statusCode': 200,\n"
+ b" 'headers': {'Content-Type': 'application/octet-stream'},\n"
+ b" 'isBase64Encoded': True,\n"
+ b" 'body': base64.b64encode(raw).decode('ascii'),\n"
+ b" }\n"
+ )
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ zf.writestr("index.py", code)
+ lam.create_function(
+ FunctionName=fname, Runtime="python3.12",
+ Role="arn:aws:iam::000000000000:role/test-role",
+ Handler="index.handler", Code={"ZipFile": buf.getvalue()},
+ )
+
+ api_id = apigw.create_api(Name=f"b64-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"]
+ route_id = apigw.create_route(
+ ApiId=api_id, RouteKey="GET /bin", Target=f"integrations/{int_id}",
+ )["RouteId"]
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/bin"
+ 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
+ assert resp.read() == bytes(range(256))
+
+ apigw.delete_route(ApiId=api_id, RouteId=route_id)
+ apigw.delete_integration(ApiId=api_id, IntegrationId=int_id)
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
+def test_apigw_execute_lambda_proxy_binary_request_body(apigw, lam):
+ """A binary request body is base64-encoded into the event.
+
+ Verified against real AWS (HTTP API v2): the inbound body is delivered as
+ base64 with isBase64Encoded=true for non-text content types (e.g.
+ application/octet-stream), and as a UTF-8 string for text types (e.g.
+ application/json).
+ """
+ import hashlib
+ import json as _json
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ fname = f"intg-apigw-binreq-{_uuid.uuid4().hex[:8]}"
+ # Echo back what the function actually received in the event.
+ code = (
+ b"import json, base64, hashlib\n"
+ b"def handler(event, context):\n"
+ b" b = event.get('body'); isb = bool(event.get('isBase64Encoded'))\n"
+ b" if b is None: raw = b''\n"
+ b" elif isb: raw = base64.b64decode(b)\n"
+ b" else: raw = b.encode('utf-8', 'surrogateescape')\n"
+ b" return {'statusCode': 200, 'headers': {'content-type': 'application/json'},\n"
+ b" 'body': json.dumps({'isB64': isb, 'sha': hashlib.sha256(raw).hexdigest()})}\n"
+ )
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ zf.writestr("index.py", code)
+ lam.create_function(
+ FunctionName=fname, Runtime="python3.12",
+ Role="arn:aws:iam::000000000000:role/test-role",
+ Handler="index.handler", Code={"ZipFile": buf.getvalue()},
+ )
+
+ api_id = apigw.create_api(Name=f"binreq-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"]
+ route_id = apigw.create_route(
+ ApiId=api_id, RouteKey="POST /echo", Target=f"integrations/{int_id}",
+ )["RouteId"]
+ apigw.create_stage(ApiId=api_id, StageName="$default")
+
+ url = f"http://{api_id}.execute-api.localhost:{_EXECUTE_PORT}/$default/echo"
+ host = f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}"
+
+ # Binary content type -> base64-encoded body, round-tripping the raw bytes.
+ payload = bytes(range(256))
+ expected_sha = hashlib.sha256(payload).hexdigest()
+ req = _urlreq.Request(url, data=payload, method="POST")
+ req.add_header("Host", host)
+ req.add_header("Content-Type", "application/octet-stream")
+ got = _json.loads(_urlreq.urlopen(req).read())
+ assert got["isB64"] is True
+ assert got["sha"] == expected_sha
+
+ # Text content type (application/json) -> passed through as a UTF-8 string.
+ req2 = _urlreq.Request(url, data=b'{"x":1}', method="POST")
+ req2.add_header("Host", host)
+ req2.add_header("Content-Type", "application/json")
+ got2 = _json.loads(_urlreq.urlopen(req2).read())
+ assert got2["isB64"] is False
+ assert got2["sha"] == hashlib.sha256(b'{"x":1}').hexdigest()
+
+ apigw.delete_route(ApiId=api_id, RouteId=route_id)
+ apigw.delete_integration(ApiId=api_id, IntegrationId=int_id)
+ apigw.delete_api(ApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+
def test_apigw_execute_no_route(apigw):
"""execute-api returns 404 when no matching route exists."""
import urllib.error as _urlerr