Skip to content

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

fix(apigatewayv2): send PostToConnection data as a text frame (#2397)

Toby Nelson64a5ac9b2cd0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-21
diff --git a/ministack/services/apigateway.py b/ministack/services/apigateway.py
index 1c7422de..f2f90c40 100644
--- a/ministack/services/apigateway.py
+++ b/ministack/services/apigateway.py
@@ -44,6 +44,7 @@ Data plane:
import asyncio
import base64
+import codecs
import json
import logging
import os
@@ -3285,10 +3286,7 @@ async def handle_websocket(scope, receive, send, api_id: str, path_override: str
continue
if 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.py
index 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 @connections
operations through the API owner's region, not the server boot region."""