Skip to content

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

S3 → EventBridge: emit AWS-conformant detail-type, reason, and deletion-type (#1006)

Lucasb846fa79a3c0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6dfa080b..938c97e6 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]
+
+### Fixed
+- **S3 — S3 → EventBridge events use AWS-conformant `detail-type`, `reason`, and `deletion-type`** — S3 → EventBridge delivery built the `detail-type` by string-mangling the granular notification event name (`Object ObjectCreated Put` instead of AWS's fixed `Object Created`), hardcoded `detail.reason` to `PutObject` for every event, and omitted `detail.deletion-type` on deletes. Because EventBridge rules match on `detail-type`, any rule written to the AWS-documented type (e.g. `["Object Created"]`) silently never matched. Each S3 event family now maps to its fixed EventBridge `detail-type`, with the per-API `reason` (`PutObject`/`POST Object`/`CopyObject`/`CompleteMultipartUpload`/`DeleteObject`) and a `deletion-type` on `Object Deleted`. Fixes #1005.
+
## [1.3.69] — 2026-06-27
diff --git a/ministack/services/s3.py b/ministack/services/s3.py
index d2ef4216..48cfdd85 100644
--- a/ministack/services/s3.py
+++ b/ministack/services/s3.py
@@ -1758,8 +1758,43 @@ def _key_matches_filter(key: str, prefix: str | None, suffix: str | None) -> boo
return True
+# Amazon S3 → EventBridge uses a fixed set of detail-types (per event family) and a per-API `reason`.
+# See https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventBridge.html
+_S3_EVENTBRIDGE_DETAIL_TYPE = {
+ "ObjectCreated": "Object Created",
+ "ObjectRemoved": "Object Deleted",
+}
+# `reason` reflects the S3 API that produced the event.
+_S3_EVENTBRIDGE_REASON = {
+ "Put": "PutObject",
+ "Post": "POST Object",
+ "Copy": "CopyObject",
+ "CompleteMultipartUpload": "CompleteMultipartUpload",
+ "Delete": "DeleteObject",
+}
+
+
+def _s3_event_to_eventbridge(event_name: str) -> tuple[str, str]:
+ """Map an S3 notification event name (e.g. ``s3:ObjectCreated:Put``) to the EventBridge
+ ``detail-type`` and ``reason`` Amazon S3 emits. The detail-type is per-family, so any
+ sub-action of a family collapses to the same type, exactly as real S3 does."""
+ parts = event_name.split(":")
+ family = parts[1] if len(parts) > 1 else ""
+ action = parts[2] if len(parts) > 2 else ""
+ detail_type = _S3_EVENTBRIDGE_DETAIL_TYPE.get(family, "Object Created")
+ reason = _S3_EVENTBRIDGE_REASON.get(
+ action, "DeleteObject" if family == "ObjectRemoved" else "PutObject"
+ )
+ return detail_type, reason
+
+
def _fire_s3_event(
- bucket_name: str, key: str, event_name: str, size: int = 0, etag: str = ""
+ bucket_name: str,
+ key: str,
+ event_name: str,
+ size: int = 0,
+ etag: str = "",
+ deletion_type: str | None = None,
) -> None:
"""Build and deliver an S3 event notification. Best-effort — errors are logged."""
try:
@@ -1836,19 +1871,26 @@ def _fire_s3_event(
try:
if has_eventbridge:
from ministack.services import eventbridge as _eb
+ detail_type, reason = _s3_event_to_eventbridge(event_name)
+ detail = {
+ "version": "0",
+ "event-version": "1.0",
+ "bucket": {"name": bucket_name},
+ "object": {"key": key, "size": size, "etag": clean_etag, "sequencer": "0"},
+ "request-id": request_id,
+ "requester": get_account_id(),
+ "source-ip-address": "127.0.0.1",
+ "reason": reason,
+ }
+ if detail_type == "Object Deleted":
+ # AWS always carries a deletion-type on Object Deleted; default to the
+ # unversioned/permanent case unless the caller created a delete marker.
+ detail["deletion-type"] = deletion_type or "Permanently Deleted"
eb_event = {
"EventId": request_id,
"Source": "aws.s3",
- "DetailType": event_name.replace("s3:", "Object ").replace(":", " ").replace("*", ""),
- "Detail": json.dumps({
- "version": "0",
- "bucket": {"name": bucket_name},
- "object": {"key": key, "size": size, "etag": clean_etag, "sequencer": "0"},
- "request-id": request_id,
- "requester": get_account_id(),
- "source-ip-address": "127.0.0.1",
- "reason": "PutObject",
- }),
+ "DetailType": detail_type,
+ "Detail": json.dumps(detail),
"EventBusName": "default",
"Time": event_time,
"Resources": [f"arn:aws:s3:::{bucket_name}"],
@@ -1856,7 +1898,7 @@ def _fire_s3_event(
"Region": os.environ.get("MINISTACK_REGION", "us-east-1"),
}
_eb._dispatch_event(eb_event)
- logger.debug("S3→EventBridge: %s for %s/%s", event_name, bucket_name, key)
+ logger.debug("S3→EventBridge: %s (%s) for %s/%s", detail_type, event_name, bucket_name, key)
except Exception:
logger.exception("S3→EventBridge delivery failed for %s/%s", bucket_name, key)
@@ -1924,7 +1966,12 @@ def _deliver_event_to_lambda(arn: str, event_payload: dict) -> None:
def _fire_s3_event_async(
- bucket_name: str, key: str, event_name: str, size: int = 0, etag: str = ""
+ bucket_name: str,
+ key: str,
+ event_name: str,
+ size: int = 0,
+ etag: str = "",
+ deletion_type: str | None = None,
) -> None:
"""Fire S3 event notification in a background thread (non-blocking)."""
if bucket_name not in _bucket_notifications:
@@ -1938,7 +1985,7 @@ def _fire_s3_event_async(
ctx = contextvars.copy_context()
t = threading.Thread(
target=ctx.run,
- args=(_fire_s3_event, bucket_name, key, event_name, size, etag),
+ args=(_fire_s3_event, bucket_name, key, event_name, size, etag, deletion_type),
daemon=True,
)
t.start()
@@ -2456,7 +2503,9 @@ def _delete_object(bucket_name: str, key: str, headers: dict | None = None):
existed = key in bucket["objects"]
bucket["objects"].pop(key, None)
if existed:
- _fire_s3_event_async(bucket_name, key, "s3:ObjectRemoved:Delete")
+ _fire_s3_event_async(
+ bucket_name, key, "s3:ObjectRemoved:Delete", deletion_type="Delete Marker Created"
+ )
return 204, {"x-amz-delete-marker": "true", "x-amz-version-id": delete_marker_id}, b""
existed = key in bucket["objects"]
diff --git a/tests/test_s3.py b/tests/test_s3.py
index 525769f2..bb1701a8 100644
--- a/tests/test_s3.py
+++ b/tests/test_s3.py
@@ -1539,7 +1539,13 @@ def test_s3_put_notification_no_test_event_for_missing_bucket(s3, sqs):
def test_s3_eventbridge_notification(s3, sqs, eb):
- """S3 EventBridgeConfiguration sends events to EventBridge, routed to SQS via rule."""
+ """S3 EventBridgeConfiguration sends AWS-conformant events to EventBridge, routed to SQS.
+
+ The emitted ``detail-type`` must be the fixed value Amazon S3 uses (``Object Created``),
+ not the granular ``s3:ObjectCreated:Put`` event name — so the rule below matches on the
+ documented detail-type, not on ``source`` alone, and would fail to route a non-conformant
+ event.
+ """
s3.create_bucket(Bucket="s3-eb-bkt")
queue_url = sqs.create_queue(QueueName="s3-eb-target-q")["QueueUrl"]
queue_arn = sqs.get_queue_attributes(
@@ -1552,10 +1558,10 @@ def test_s3_eventbridge_notification(s3, sqs, eb):
NotificationConfiguration={"EventBridgeConfiguration": {}},
)
- # Create EventBridge rule matching S3 events → SQS target
+ # Rule matches the AWS-documented detail-type, not source alone.
eb.put_rule(
Name="s3-to-sqs-rule",
- EventPattern=json.dumps({"source": ["aws.s3"]}),
+ EventPattern=json.dumps({"source": ["aws.s3"], "detail-type": ["Object Created"]}),
State="ENABLED",
)
eb.put_targets(
@@ -1571,8 +1577,78 @@ def test_s3_eventbridge_notification(s3, sqs, eb):
assert "Messages" in msgs and len(msgs["Messages"]) > 0
body = json.loads(msgs["Messages"][0]["Body"])
assert body["source"] == "aws.s3"
+ assert body["detail-type"] == "Object Created"
assert body["detail"]["bucket"]["name"] == "s3-eb-bkt"
assert body["detail"]["object"]["key"] == "hello.txt"
+ assert body["detail"]["reason"] == "PutObject"
+
+
+def test_s3_eventbridge_notification_copy_reason(s3, sqs, eb):
+ """A CopyObject create carries reason ``CopyObject`` (not a hardcoded ``PutObject``)."""
+ s3.create_bucket(Bucket="s3-eb-copy-bkt")
+ queue_url = sqs.create_queue(QueueName="s3-eb-copy-q")["QueueUrl"]
+ queue_arn = sqs.get_queue_attributes(
+ QueueUrl=queue_url, AttributeNames=["QueueArn"],
+ )["Attributes"]["QueueArn"]
+ s3.put_bucket_notification_configuration(
+ Bucket="s3-eb-copy-bkt",
+ NotificationConfiguration={"EventBridgeConfiguration": {}},
+ )
+ eb.put_rule(
+ Name="s3-copy-rule",
+ EventPattern=json.dumps(
+ {
+ "source": ["aws.s3"],
+ "detail-type": ["Object Created"],
+ "detail": {"reason": ["CopyObject"]},
+ }
+ ),
+ State="ENABLED",
+ )
+ eb.put_targets(Rule="s3-copy-rule", Targets=[{"Id": "t", "Arn": queue_arn}])
+
+ s3.put_object(Bucket="s3-eb-copy-bkt", Key="src.txt", Body=b"x")
+ s3.copy_object(
+ Bucket="s3-eb-copy-bkt", Key="dst.txt", CopySource="s3-eb-copy-bkt/src.txt"
+ )
+ time.sleep(0.5)
+
+ msgs = sqs.receive_message(QueueUrl=queue_url, MaxNumberOfMessages=10, WaitTimeSeconds=2)
+ assert "Messages" in msgs and len(msgs["Messages"]) > 0
+ body = json.loads(msgs["Messages"][0]["Body"])
+ assert body["detail-type"] == "Object Created"
+ assert body["detail"]["object"]["key"] == "dst.txt"
+ assert body["detail"]["reason"] == "CopyObject"
+
+
+def test_s3_eventbridge_notification_object_deleted(s3, sqs, eb):
+ """A delete emits ``Object Deleted`` with reason ``DeleteObject`` and a deletion-type."""
+ s3.create_bucket(Bucket="s3-eb-del-bkt")
+ queue_url = sqs.create_queue(QueueName="s3-eb-del-q")["QueueUrl"]
+ queue_arn = sqs.get_queue_attributes(
+ QueueUrl=queue_url, AttributeNames=["QueueArn"],
+ )["Attributes"]["QueueArn"]
+ s3.put_bucket_notification_configuration(
+ Bucket="s3-eb-del-bkt",
+ NotificationConfiguration={"EventBridgeConfiguration": {}},
+ )
+ eb.put_rule(
+ Name="s3-del-rule",
+ EventPattern=json.dumps({"source": ["aws.s3"], "detail-type": ["Object Deleted"]}),
+ State="ENABLED",
+ )
+ eb.put_targets(Rule="s3-del-rule", Targets=[{"Id": "t", "Arn": queue_arn}])
+
+ s3.put_object(Bucket="s3-eb-del-bkt", Key="gone.txt", Body=b"x")
+ s3.delete_object(Bucket="s3-eb-del-bkt", Key="gone.txt")
+ time.sleep(0.5)
+
+ msgs = sqs.receive_message(QueueUrl=queue_url, MaxNumberOfMessages=10, WaitTimeSeconds=2)
+ assert "Messages" in msgs and len(msgs["Messages"]) > 0
+ body = json.loads(msgs["Messages"][0]["Body"])
+ assert body["detail-type"] == "Object Deleted"
+ assert body["detail"]["reason"] == "DeleteObject"
+ assert body["detail"]["deletion-type"] == "Permanently Deleted"
def test_s3_list_object_versions(s3):
s3.create_bucket(Bucket="s3-ver-bkt")