nats-example/README.md

# NATS Messaging System

A simple NATS client/server setup for testing message publishing and subscribing using Docker Compose.

## Architecture

- **NATS Server**: Message broker running on port 4222
- **Server (index.ts)**: Subscribes to messages and displays them
- **Client (client.ts)**: Interactive CLI for publishing messages

## Prerequisites

- Docker and Docker Compose
- (Optional) Bun runtime for local development

## Running with Docker Compose (Recommended)

### 1. Start the NATS server and message subscriber

```bash
docker compose up --build nats server
```

This starts:

- NATS message broker in the background
- Server that subscribes to messages and displays them

### 2. Run the interactive client

```bash
docker compose run --rm --build client
```

This opens an interactive prompt where you can:

- Type messages and press Enter to send them
- Type `quit` or `exit` to stop the client
- Use Ctrl+C to force exit

### 3. View server logs (optional)

To see incoming messages in real-time:

```bash
docker compose logs -f server
```

### 4. Stop everything

```bash
docker compose down
```

## Example Usage

1. **Terminal 1**: Start the infrastructure

   ```bash
   docker compose up --build nats server
   ```

2. **Terminal 2**: Run the client

   ```bash
   docker compose run --rm --build client
   ```

   You'll see:

   ```
   Connected to NATS at nats://nats:4222
   Enter a message (or 'quit' to exit): Hello World!
   Enter a message (or 'quit' to exit): This is a test
   Enter a message (or 'quit' to exit): quit
   Goodbye!
   ```

3. **Terminal 1**: Check server logs to see received messages
   ```bash
   docker compose logs server
   ```

## Local Development (without Docker)

If you prefer to run locally:

### Install dependencies

```bash
bun install
```

### Start NATS server

```bash
docker run -p 4222:4222 -ti nats:latest --auth s3cr3t
```

### Run the server (in one terminal)

```bash
bun run index.ts
```

### Run the client (in another terminal)

```bash
bun run client.ts
```

## Environment Variables

- `NATS_SERVER`: NATS server URL (default: `nats://localhost:4222`)
- `NATS_AUTH_TOKEN`: NATS server [auth token](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/tokens)

## Troubleshooting

- **Client not accepting input**: Make sure you're using `docker compose run --rm client` instead of `docker compose up client`
- **Connection refused**: Ensure NATS server is running first
- **Messages not appearing**: Check that the server container is running with `docker compose ps`

This project was created using `bun init` in bun v1.2.18. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.