# Hummingbird Events Topic

LLMS index: [llms.txt](/llms.txt) | Full content: [llms-full.txt](/llms-full.txt)

---

An SNS topic for all Hummingbird project events. This topic serves as a central
hub for distributing events from multiple sources (GitLab webhooks, Kubernetes,
etc.) to multiple subscribers, enabling event-driven architectures and
integrations.

## Features

- **Central Event Hub**: Dedicated SNS topic per environment (production and
  staging) for all project events from multiple sources
- **Multiple Subscribers**: Supports Lambda, SQS, HTTP endpoints, email, SMS,
  and more
- **Event Filtering**: Subscribers can filter events using SNS subscription
  filter policies

## Prerequisites

- AWS CLI configured with appropriate credentials (IAM permissions for SNS,
  CloudFormation)
- Podman or Docker (for containerized SAM build/deploy)

## Deployment

Build and deploy using containerized AWS SAM CLI:

```bash
cd hummingbird-events-topic
make build     # Build SAM application
make deploy    # First deployment (interactive/guided)
make redeploy  # Subsequent deployments (non-interactive)
```

**Deployment outputs:**

- `TopicArn` - SNS topic ARN (for event publishers)
- `TopicName` - SNS topic name

### Parameters

| Parameter   | Description    | Default             |
|-------------|----------------|---------------------|
| `TopicName` | SNS topic name | `myapp-prod-events` |

**Resource naming:** The SNS topic uses the provided `TopicName` parameter.

## Usage

### Publishing Events

Event publishers need the topic ARN to publish messages:

```bash
# Get topic ARN from CloudFormation stack
aws cloudformation describe-stacks \
  --stack-name <stack-name> \
  --query 'Stacks[0].Outputs[?OutputKey==`TopicArn`].OutputValue' \
  --output text
```

**Event publishers:**

- [gitlab-event-forwarder][gef-docs] - Publishes GitLab webhook events
- [kubernetes-event-forwarder][kef-docs] - Publishes Kubernetes resource changes
- Custom event sources

### Subscribing to Events

Subscribe services to receive events:

**Via AWS Console:**

1. Open SNS console → Topics
2. Select the topic
3. Create subscription (choose protocol: Lambda, SQS, HTTP, Email, etc.)
4. Add subscription filter policy (optional)

**Via AWS CLI:**

```bash
aws sns subscribe \
  --topic-arn <topic-arn> \
  --protocol lambda \
  --notification-endpoint <lambda-arn>
```

**Add filter policy:**

```bash
aws sns set-subscription-attributes \
  --subscription-arn <subscription-arn> \
  --attribute-name FilterPolicy \
  --attribute-value '{"source": ["gitlab"], "event_type": ["push"]}'
```

### Subscription Filter Examples

GitLab push events from specific project:

```json
{
  "source": ["gitlab"],
  "event_type": ["push"],
  "project_path": ["redhat/hummingbird/containers"]
}
```

All merge request events:

```json
{
  "source": ["gitlab"],
  "event_type": ["merge_request"]
}
```

All events from GitLab:

```json
{
  "source": ["gitlab"]
}
```

**Event metadata:** See publisher documentation for available metadata:

- [gitlab-event-forwarder][gef-docs] - GitLab webhook event metadata
- [kubernetes-event-forwarder][kef-docs] - Kubernetes resource event metadata

## Development

This is a pure infrastructure project (no application code). See the main
[README][readme] for SAM build/deploy commands.

## Security & Limitations

**Security:**

- SNS topic follows least privilege principle
- Access controlled via IAM policies
- Supports server-side encryption (optional)
- Publishers require `sns:Publish` permission
- Subscribers require appropriate protocol permissions

**Limitations:**

- Message size: Up to 256 KB
- Maximum subscriptions: 12,500,000 per topic
- Message retention: Not supported (use SQS for durable queuing)
- Delivery retries: Protocol-dependent

## License

This project is licensed under the GNU General Public License v3.0 or later -
see the [LICENSE][license] file for details.

[gef-docs]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/documentation/gitlab-event-forwarder.md
[kef-docs]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/documentation/kubernetes-event-forwarder.md
[readme]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/README.md
[license]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/LICENSE