Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
fix(apigatewayv2): send PostToConnection data as a text frame (#2397)
Toby Nelson64a5ac9b2cd0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6c310a70..6cfa8aea 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -33,6 +33,7 @@ Versioning follows [Semantic Versioning](https://semver.org/).- **CloudFront — `CreateFunction` tags** — the request's `Tags` were dropped, so `ListTagsForResource` on the new function's ARN was empty and Terraform re-planned `tags_all` on `aws_cloudfront_function`; they are now stored, a tag without `Value` is listed with an empty one, a refused create stores none, and `DeleteFunction` removes them so a function created again under the same name starts without them. `CreateFunction` and `UpdateFunction` answer invalid base64 code with `MalformedInput` "Invalid Base64 encoding", and `CreateFunction` now refuses what AWS refuses, before the name lookup: a missing or empty `FunctionCode`, a missing `FunctionConfig` or `Runtime`, an unknown runtime, a missing or empty `Name`, and a tag key that is missing, empty, over 128 characters or outside letters, numbers, spaces and `_ . : / = + - @` (values over 256 characters or outside the same set), listed together (at most ten) in one `MalformedXML`; and after it, `InvalidTagging` for a repeated key, an `aws:` key or more than 50 tags. Contributed by @kharabasz.- **CloudWatch — `PutMetricAlarm` and `PutCompositeAlarm` tags on create** — `Tags` were dropped when either call created an alarm, so Terraform re-planned `tags_all` on `aws_cloudwatch_metric_alarm` and `aws_cloudwatch_composite_alarm`; they are now stored over CBOR, JSON 1.0 and Query, keeping empty values and the last value of a repeated key, and they are still ignored when the call updates an existing alarm, as on AWS (use `TagResource` / `UntagResource`). Both calls now refuse what AWS refuses, before anything is stored (`PutCompositeAlarm` before its `AlarmRule` checks): a wrong JSON type in `Tags` (`MalformedInput`), a missing or empty `Key`, a missing `Value`, a key over 128 or a value over 256 characters, or a `DatapointsToAlarm` below 1, listed together (at most ten) in one `ValidationError`, on create a key or value with characters outside letters, numbers, spaces and `_ . : / = + - @` or too long in UTF-16 units, an `aws:` key on create (`PutMetricAlarm` 403 `AccessDenied`, `PutCompositeAlarm` `ValidationError` "Invalid System Tag"), and more than 50 tags on create. Query error messages are now XML-escaped. Contributed by @kharabasz.- **CloudWatch — `DatapointsToAlarm` only when set** — an alarm created by `PutMetricAlarm` or `AWS::CloudWatch::Alarm` without `DatapointsToAlarm` reported it as `EvaluationPeriods`, so Terraform planned `datapoints_to_alarm = 3 -> null`; `DescribeAlarms` now leaves it out unless the request or template sets it, the Query response includes it when set, and an update that omits it clears it. Contributed by @kharabasz.+- **API Gateway v2 — `PostToConnection` sends a text frame** — data posted to a WebSocket connection reached the client as a binary frame, so a browser `WebSocket` handed `onmessage` a `Blob` where AWS gives a string; it now arrives as a text frame, as on AWS, with bytes that aren't UTF-8 replaced by U+FFFD. Contributed by @toby6578.## [1.5.31] — 2026-10-21diff --git a/ministack/services/apigateway.py b/ministack/services/apigateway.pyindex 1c7422de..f2f90c40 100644--- a/ministack/services/apigateway.py+++ b/ministack/services/apigateway.py@@ -44,6 +44,7 @@ Data plane:import asyncioimport base64+import codecsimport jsonimport loggingimport os@@ -3285,10 +3286,7 @@ async def handle_websocket(scope, receive, send, api_id: str, path_override: strcontinueif item is None:return- if isinstance(item, bytes):- await send({"type": "websocket.send", "bytes": item})- else:- await send({"type": "websocket.send", "text": str(item)})+ await send({"type": "websocket.send", "text": item})drain_task = asyncio.create_task(_drain_outbox())@@ -3377,6 +3375,29 @@ async def handle_websocket(scope, receive, send, api_id: str, path_override: str# @connections management API# ==========================================================================+def _replace_like_api_gateway(error: UnicodeDecodeError) -> tuple[str, int]:+ """Replace one invalid UTF-8 sequence with U+FFFD, as API Gateway does for PostToConnection data.++ API Gateway replaces the same bytes as Python's ``errors="replace"`` except for an encoded+ surrogate: ED followed by A0-BF, plus one continuation byte if present, becomes a single+ U+FFFD where Python emits one per byte.+ """+ data, start = error.object, error.start+ if data[start] == 0xED and start + 1 < len(data) and 0xA0 <= data[start + 1] <= 0xBF:+ end = start + 2+ if end < len(data) and 0x80 <= data[end] <= 0xBF:+ end += 1+ return "\ufffd", end+ return "\ufffd", error.end+++codecs.register_error("ministack-apigateway-replace", _replace_like_api_gateway)+++def _post_to_connection_text(data: bytes) -> str:+ return data.decode("utf-8", errors="ministack-apigateway-replace")++async def handle_connections_api(method: str, api_id: str, stage: str,connection_id: str, body: bytes, headers: dict):"""Serve the @connections runtime API.@@ -3401,7 +3422,7 @@ async def handle_connections_api(method: str, api_id: str, stage: str,# Push the message into the connection outbox; drain_task will forward it.try:if body:- await conn["outbox"].put(body)+ await conn["outbox"].put(_post_to_connection_text(body))except Exception as exc:return 500, {"Content-Type": "application/json"}, json.dumps({"message": str(exc)}diff --git a/tests/test_apigatewayv2.py b/tests/test_apigatewayv2.pyindex e2280848..984d7142 100644--- a/tests/test_apigatewayv2.py+++ b/tests/test_apigatewayv2.py@@ -2609,6 +2609,17 @@ class _WSClient:except socket.timeout:return None+ def recv_frame(self, timeout: float = 15.0) -> tuple[int, bytes] | None:+ """Return the next data or close frame as (opcode, payload), skipping ping/pong."""+ self._sock.settimeout(timeout)+ try:+ while True:+ frame = self._recv_frame()+ if frame is None or frame[0] in (0x1, 0x2, 0x8):+ return frame+ except socket.timeout:+ return None+def _recv_all(self, n: int) -> bytes:while len(self._buf) < n:chunk = self._sock.recv(max(4096, n - len(self._buf)))@@ -2867,6 +2878,63 @@ def test_ws_post_to_connection_from_management_api(apigw, lam):ws.close()+def test_ws_post_to_connection_sends_text_frames(apigw, lam):+ """PostToConnection data arrives as a text frame, with bytes that aren't UTF-8 replaced by U+FFFD, as on AWS."""+ import urllib.request++ api_id, _ = _wire_ws_api(apigw, lam, name_suffix="p2c-text")+ host = f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}"+ ws = _WSClient("localhost", _EXECUTE_PORT, "/prod", headers={"Host": host})+ try:+ ws.send(json.dumps({"action": "sendMessage"}))+ conn_id = json.loads(ws.recv())["connectionId"]++ for data, delivered in (+ (b'{"kind":"changes"}', b'{"kind":"changes"}'),+ (b"\xff\xfe\x00\x01", b"\xef\xbf\xbd\xef\xbf\xbd\x00\x01"),+ (b"\xed\xa0\x80A", b"\xef\xbf\xbdA"),+ ):+ req = urllib.request.Request(+ f"http://{host}/prod/@connections/{conn_id}", data=data, method="POST", headers={"Host": host},+ )+ assert urllib.request.urlopen(req, timeout=30).status == 200+ assert ws.recv_frame(timeout=3) == (0x1, delivered)+ finally:+ ws.close()++[email protected]("posted, delivered", [+ ("fffe0001", "efbfbdefbfbd0001"), # lone-invalid+ ("80", "efbfbd"), # lone-continuation+ ("e282", "efbfbd"), # truncated-3byte+ ("e28241", "efbfbd41"), # truncated-3byte-then-ascii+ ("f09f98", "efbfbd"), # truncated-4byte+ ("f09f9841", "efbfbd41"), # truncated-4byte-then-ascii+ ("c0af", "efbfbdefbfbd"), # overlong-2byte+ ("e080af", "efbfbdefbfbdefbfbd"), # overlong-3byte+ ("f0808080", "efbfbdefbfbdefbfbdefbfbd"), # overlong-4byte+ ("f4908080", "efbfbdefbfbdefbfbdefbfbd"), # above-max-codepoint+ ("f5808080", "efbfbdefbfbdefbfbdefbfbd"), # invalid-lead-f5+ ("f09f9880", "f09f9880"), # valid-emoji+ ("41e282f09f98804280", "41efbfbdf09f988042efbfbd"), # mixed+ ("eda080", "efbfbd"), # high-surrogate+ ("edb080", "efbfbd"), # low-surrogate+ ("edbfbf", "efbfbd"), # max-surrogate+ ("eda0bdedb880", "efbfbdefbfbd"), # surrogate-pair-cesu8+ ("eda0", "efbfbd"), # truncated-surrogate-at-end+ ("eda041", "efbfbd41"), # truncated-surrogate-then-ascii+ ("eda08041", "efbfbd41"), # surrogate-then-ascii+ ("41eda0", "41efbfbd"), # ascii-then-truncated-surrogate+ ("ed41", "efbfbd41"), # lead-ed-then-ascii+ ("ed", "efbfbd"), # lead-ed-at-end+ ("ed9fbf", "ed9fbf"), # below-surrogates-valid+ ("ee8080", "ee8080"), # after-surrogates-valid+])+def test_ws_post_to_connection_text_replaces_invalid_utf8_like_aws(posted, delivered):+ """Each pair is what API Gateway delivered (eu-west-1, 2026-10-22) for data posted with PostToConnection."""+ assert _apigw._post_to_connection_text(bytes.fromhex(posted)).encode().hex() == delivered++def test_ws_non_boot_region_routes_and_management_api():"""A WebSocket API owned by a non-boot region routes frames and @connectionsoperations through the API owner's region, not the server boot region."""