Notifications

Bucket events (PUT, DELETE, COPY, etc.) are dispatched to external targets — Kafka, NATS, MQTT, AMQP, ElasticSearch, MySQL/PostgreSQL, Redis, NSQ, webhook. The transport is internal/event/; the per-target adapters live in internal/event/target/.

Purpose

• Implement the AWS S3 bucket-notification API.
• Reliably deliver events to one or more configured targets without blocking the request path.
• Persist undelivered events on disk so a crash doesn't lose them.

Layout

cmd/
├── event-notification.go             # Source side: turn handler events into Event objects
├── notification.go                   # Cluster-wide bucket notification config + peer fanout
├── notification-summary.go           # Status summary for admin
├── bucket-notification-handlers.go   # PUT/GET/DELETE bucket notification XML
├── listen-notification-handlers.go   # /minio/listen/v1 streaming endpoint
internal/event/
├── event.go                          # Event type
├── name.go, name_test.go             # S3 event names
├── arn.go                            # Target ARNs
├── targetid.go, targetidset.go       # Target identifiers
├── targetlist.go                     # Multiplex to multiple targets
├── rules.go, rulesmap.go             # Filter rules (prefix/suffix/event types)
├── config.go                         # XML model
├── errors.go
└── target/
    ├── kafka.go
    ├── nats.go
    ├── mqtt.go
    ├── amqp.go
    ├── webhook.go
    ├── postgresql.go
    ├── mysql.go
    ├── redis.go
    ├── elasticsearch.go
    ├── nsq.go
    ├── store.go            # Persistent queue
    └── ...
internal/store/
└── store.go                # Generic on-disk queue used by every target
internal/config/notify/
├── parse.go
├── notify_*.go             # One file per target type
└── help.go

Key abstractions

Symbol	File	What it is
event.Event	internal/event/event.go	The S3-shaped event payload.
event.TargetList	internal/event/targetlist.go	Multiplexer to all configured targets.
event.Target	internal/event/target/<x>.go	The interface every adapter implements.
store.Store	internal/store/store.go	Disk-backed FIFO queue used by targets that may be slow or unreachable.
madmin.NotificationConfig	external madmin-go	The wire type for mc admin event.

How it works

graph LR
    H[S3 handler] --> EV[Build event.Event]
    EV --> RULES[Match per-bucket rules]
    RULES --> TL[TargetList.Send]
    TL --> ASYNC[Per-target queue]
    ASYNC --> DISK[On-disk store]
    ASYNC --> ADAPTER[Kafka/NATS/...]
    ADAPTER --> EXT[External system]

• Every handler that mutates state calls globalEventNotifier.Send(...) (defined in cmd/event-notification.go).
• Per-bucket rules (internal/event/rules.go) decide which targets receive the event.
• TargetList fans out to each target asynchronously. A failing or slow target queues to disk via internal/store/. The adapter retries with backoff.
• Targets that crash or fall behind don't block the request — the only failure mode visible to the client is misconfiguration at PUT-config time.

Configuration

Each target is registered under internal/config/notify/notify_<name>.go, with environment variables of the form MINIO_NOTIFY_<TYPE>_<KEY>_<VAR>. Multiple instances are supported via a free-form key, e.g. MINIO_NOTIFY_KAFKA_BROKERS_primary.

mc admin config get / set is the user-facing way to manage notification config; bucket-level rules are configured via the standard PutBucketNotificationConfiguration S3 API (cmd/bucket-notification-handlers.go).

Listen endpoint

cmd/listen-notification-handlers.go exposes /minio/listen/v1 — a streaming endpoint that lets clients subscribe to live events without an external broker. Useful for local development and mc events watch.

Reliability

• The on-disk store (internal/store/) survives restarts.
• Storage capacity is bounded; old entries roll out under MINIO_NOTIFY_<X>_QUEUE_LIMIT.
• The store has a polling worker that drains entries when the target is healthy.

Integration points

• Source-side: every handler that writes data (cmd/object-handlers.go, cmd/object-multipart-handlers.go, lifecycle, replication).
• Sink-side: external brokers via the per-target SDKs.
• Status surface: cmd/notification-summary.go plus the metrics families.

Entry points for modification

• New target type. Add a file under internal/event/target/ implementing the Target interface, register a config in internal/config/notify/, document env vars.
• New bucket-level filter dimension. Extend internal/event/rules.go and the XML schema.
• Tune queue size or batching. Per-target options live in internal/config/notify/notify_<x>.go.