Skip to content

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

fix(iot): route MQTT publishes through topic rules to Lambda (#1080)

maximoosemine220f5b341f66
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc427be5..fabaaaf9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,11 @@ All notable changes to MiniStack will be documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
Versioning follows [Semantic Versioning](https://semver.org/).
+## [Unreleased]
+
+### Added
+- **IoT — MQTT publishes are routed through topic rules to Lambda** — an MQTT/`iot-data` publish is now matched against each account's topic rules by the rule's `FROM '<topic filter>'` clause (with `+`/`#` wildcards), and every matching enabled rule's `lambda` actions are invoked asynchronously with the message payload as the event (`SELECT *`). Basic Ingest is supported: a publish to `$aws/rules/<ruleName>` is delivered straight to that rule's actions and bypasses pub/sub. Disabled rules are skipped.
+
## [1.4.2] — 2026-07-13
### Added
diff --git a/ministack/services/iot.py b/ministack/services/iot.py
index 48db3b5a..0f47832b 100644
--- a/ministack/services/iot.py
+++ b/ministack/services/iot.py
@@ -1606,6 +1606,55 @@ async def broker_stop() -> None:
_persistent_sessions.clear()
+_BASIC_INGEST_PREFIX = "$aws/rules/"
+
+
+def _rules_for_account(account_id: str) -> list[dict]:
+ return [v for (acct, _key), v in _topic_rules._data.items() if acct == account_id]
+
+
+def _rule_event(payload: bytes):
+ """Decode a publish payload into a rule event (JSON, else raw text)."""
+ try:
+ return json.loads(payload.decode("utf-8"))
+ except (UnicodeDecodeError, json.JSONDecodeError):
+ return (payload or b"").decode("utf-8", "replace")
+
+
+def _dispatch_rule_to_lambda(account_id: str, function_arn: str, event) -> None:
+ from ministack.services import lambda_svc
+
+ func, config, name = lambda_svc._get_func_record_for_ref_in_scope(
+ function_arn, account_id=account_id
+ )
+ if not func or not config:
+ _broker_logger.warning("IoT rule → Lambda: function %s not found", function_arn)
+ return
+ exec_record = lambda_svc._execution_record_for_config(func, config)
+ threading.Thread(
+ target=lambda_svc._execute_function_with_config_scope,
+ args=(exec_record, event),
+ daemon=True,
+ ).start()
+
+
+def _run_rule_actions(account_id: str, rule: dict, payload: bytes) -> None:
+ if not rule or rule.get("ruleDisabled"):
+ return
+ event = _rule_event(payload)
+ for action in rule.get("actions", []) or []:
+ lam = action.get("lambda")
+ if lam and lam.get("functionArn"):
+ _dispatch_rule_to_lambda(account_id, lam["functionArn"], event)
+
+
+def _evaluate_topic_rules(account_id: str, topic: str, payload: bytes) -> None:
+ for rule in _rules_for_account(account_id):
+ filter_ = _rule_topic_filter(rule.get("sql", ""))
+ if filter_ and _topic_matches(filter_, topic):
+ _run_rule_actions(account_id, rule, payload)
+
+
async def broker_publish(
account_id: str,
topic: str,
@@ -1613,6 +1662,13 @@ async def broker_publish(
qos: int = 0,
retain: bool = False,
) -> None:
+ # Basic Ingest: a publish to `$aws/rules/<ruleName>` is delivered straight
+ # to that rule's actions and bypasses pub/sub delivery entirely.
+ if topic.startswith(_BASIC_INGEST_PREFIX):
+ rule_name = topic[len(_BASIC_INGEST_PREFIX):].split("/", 1)[0]
+ _run_rule_actions(account_id, _topic_rules.get_scoped(account_id, None, rule_name), payload)
+ return
+
scoped = _scoped_topic(account_id, topic)
if retain:
@@ -1649,6 +1705,8 @@ async def broker_publish(
ps.queued_messages = ps.queued_messages[-_MAX_QUEUED_MESSAGES:]
break
+ _evaluate_topic_rules(account_id, topic, payload)
+
async def broker_subscribe(
account_id: str,
diff --git a/tests/test_iot_data.py b/tests/test_iot_data.py
index e1da7491..02f4d48e 100644
--- a/tests/test_iot_data.py
+++ b/tests/test_iot_data.py
@@ -11,11 +11,14 @@ bridge layer.
from __future__ import annotations
+import io as _io
+import json
import os
import struct
import threading
import time
import uuid
+import zipfile as _zipfile
from urllib.parse import quote, urlparse
import pytest
@@ -357,3 +360,110 @@ def test_iot_ws_same_account_publish_delivers(iot_data_client):
delivered_topic, delivered_payload = received[0]
assert delivered_topic == topic
assert delivered_payload == payload
+
+
+# ---------------------------------------------------------------------------
+# Topic-rule routing (publish → rule → Lambda)
+# ---------------------------------------------------------------------------
+
+# Handler forwards the received rule event to the SQS queue named by SINK_URL,
+# so the test can observe that the rule fired and with what payload.
+_RULE_SINK_HANDLER = (
+ "import boto3, json, os\n"
+ "def handler(event, context):\n"
+ " s = boto3.client('sqs', endpoint_url=os.environ['AWS_ENDPOINT_URL'])\n"
+ " s.send_message(QueueUrl=os.environ['SINK_URL'], MessageBody=json.dumps(event))\n"
+ " return {'ok': True}\n"
+)
+
+
+def _make_sink_lambda(lam, sink_url):
+ buf = _io.BytesIO()
+ with _zipfile.ZipFile(buf, "w") as z:
+ z.writestr("index.py", _RULE_SINK_HANDLER)
+ name = _unique("rulefn")
+ lam.create_function(
+ FunctionName=name,
+ Runtime="python3.12",
+ Role="arn:aws:iam::000000000000:role/test-role",
+ Handler="index.handler",
+ Code={"ZipFile": buf.getvalue()},
+ Environment={"Variables": {"SINK_URL": sink_url}},
+ )
+ return lam.get_function(FunctionName=name)["Configuration"]["FunctionArn"]
+
+
+def _poll_sink(sqs, url, timeout=12):
+ deadline = time.time() + timeout
+ while time.time() < deadline:
+ msgs = sqs.receive_message(QueueUrl=url, MaxNumberOfMessages=1, WaitTimeSeconds=1)
+ if msgs.get("Messages"):
+ return json.loads(msgs["Messages"][0]["Body"])
+ return None
+
+
+def test_iot_topic_rule_routes_publish_to_lambda(iot_client, iot_data_client, lam, sqs):
+ sink = sqs.create_queue(QueueName=_unique("rule-sink"))["QueueUrl"]
+ fn_arn = _make_sink_lambda(lam, sink)
+ rule = _unique("route").replace("-", "_")
+ iot_client.create_topic_rule(
+ ruleName=rule,
+ topicRulePayload={
+ "sql": "SELECT * FROM 'sensors/+/telemetry'",
+ "actions": [{"lambda": {"functionArn": fn_arn}}],
+ },
+ )
+
+ iot_data_client.publish(
+ topic="sensors/a1/telemetry",
+ payload=json.dumps({"temp": 22, "missedReadings": 3}).encode(),
+ )
+ event = _poll_sink(sqs, sink)
+ assert event == {"temp": 22, "missedReadings": 3}
+
+ iot_client.delete_topic_rule(ruleName=rule)
+
+
+def test_iot_basic_ingest_routes_to_lambda(iot_client, iot_data_client, lam, sqs):
+ sink = sqs.create_queue(QueueName=_unique("ingest-sink"))["QueueUrl"]
+ fn_arn = _make_sink_lambda(lam, sink)
+ rule = _unique("ingest").replace("-", "_")
+ iot_client.create_topic_rule(
+ ruleName=rule,
+ topicRulePayload={
+ "sql": "SELECT * FROM 'unused'",
+ "actions": [{"lambda": {"functionArn": fn_arn}}],
+ },
+ )
+
+ # Basic Ingest: publishing to `$aws/rules/<ruleName>` invokes the rule
+ # directly, bypassing the topic filter.
+ iot_data_client.publish(
+ topic=f"$aws/rules/{rule}",
+ payload=json.dumps({"temp": 99, "basic": True}).encode(),
+ )
+ event = _poll_sink(sqs, sink)
+ assert event == {"temp": 99, "basic": True}
+
+ iot_client.delete_topic_rule(ruleName=rule)
+
+
+def test_iot_disabled_rule_does_not_fire(iot_client, iot_data_client, lam, sqs):
+ sink = sqs.create_queue(QueueName=_unique("disabled-sink"))["QueueUrl"]
+ fn_arn = _make_sink_lambda(lam, sink)
+ rule = _unique("disabled").replace("-", "_")
+ iot_client.create_topic_rule(
+ ruleName=rule,
+ topicRulePayload={
+ "sql": "SELECT * FROM 'sensors/+/telemetry'",
+ "ruleDisabled": True,
+ "actions": [{"lambda": {"functionArn": fn_arn}}],
+ },
+ )
+
+ iot_data_client.publish(
+ topic="sensors/a1/telemetry", payload=json.dumps({"temp": 1}).encode()
+ )
+ assert _poll_sink(sqs, sink, timeout=4) is None
+
+ iot_client.delete_topic_rule(ruleName=rule)