# NATS Message Broker

> 🚀 **Event-driven communication** powered by NATS + JetStream

Message broker for CloudEvents-based microservices communication using [`@crossdelta/cloudevents`](https://github.com/crossdelta/platform/tree/main/packages/cloudevents).

## ⚡ Quick Start

```bash
# Start NATS in Docker (auto-started with `bun dev`)
bun run start:dev

# Check health
curl http://localhost:8222/healthz

# View JetStream status
curl http://localhost:8222/jsz
```

## 🔌 Connecting to NATS

Services connect via environment variables:

| Environment | URL | Description |
|-------------|-----|-------------|
| **Local** | `nats://localhost:4222` | Docker container |
| **Kubernetes** | `nats://nats.<namespace>.svc.cluster.local:4222` | Internal service DNS |

**Example:**
```typescript
import { publish } from '@crossdelta/cloudevents'

await publish('orders.created', { orderId: 'ord_123', total: 99.99 })
```

## 📊 Monitoring & Health Checks

NATS exposes HTTP endpoints for monitoring:

| Endpoint | Purpose |
|----------|---------|
| `http://localhost:8222/healthz` | Health check (`{"status":"ok"}`) |
| `http://localhost:8222/jsz` | JetStream statistics (streams, consumers, messages) |
| `http://localhost:8222/varz` | Server variables (connections, memory, uptime) |
| `http://localhost:8222/connz` | Active connections |

## 🗄️ JetStream Persistence

JetStream provides durable event streaming with at-least-once delivery:

- **Local Dev:** `.nats-data/` directory (git-ignored)
- **Production:** Persistent volume mounted at `/data`
- **Streams:** Auto-created by `@crossdelta/cloudevents` consumer setup

**Stream Configuration:**
- Retention: Interest-based (messages deleted after all consumers ack)
- Deduplication: 2-minute window
- Max message age: 24 hours (configurable via `nats.prod.conf`)

## 🛠️ Configuration

### Local Development (`nats.conf`)
- JetStream enabled with local file storage
- No authentication (Docker network isolation)
- Ports: 4222 (client), 8222 (HTTP monitoring)

### Production (`nats.prod.conf`)
- Token-based authentication (via `NATS_TOKEN` env var)
- Persistent storage at `/data`
- Resource limits configured via Kubernetes

## 📦 Environment Variables

Generated automatically in `.env.local` via `bun dev`:

```bash
NATS_PORT=4222                # Client port
NATS_HTTP_PORT=8222           # HTTP monitoring port
NATS_IMAGE=nats:2.10-alpine   # Docker image
```

## 🐳 Docker Commands

```bash
# Start (via npm script)
bun run start:dev

# Manual start
docker run -d --name my-nats \
  -p 4222:4222 -p 8222:8222 \
  -v $(pwd)/.nats-data:/data \
  -v $(pwd)/nats.conf:/etc/nats/nats.conf:ro \
  nats:2.10-alpine -c /etc/nats/nats.conf

# View logs
docker logs -f my-nats

# Stop & remove
docker rm -f my-nats
```

## 📚 Learn More

- [NATS Documentation](https://docs.nats.io/)
- [JetStream Guide](https://docs.nats.io/nats-concepts/jetstream)
- [`@crossdelta/cloudevents` Package](https://github.com/crossdelta/platform/tree/main/packages/cloudevents)
- [CloudEvents Specification](https://cloudevents.io/)
