gorz/README.md

# goRZ - Fast Reverse Proxy Server

[![Go Report Card](https://goreportcard.com/badge/github.com/iwasforcedtobehere/goRZ)](https://goreportcard.com/report/github.com/iwasforcedtobehere/goRZ)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/iwasforcedtobehere/goRZ)](https://github.com/iwasforcedtobehere/goRZ/releases)

goRZ is a blazingly fast reverse proxy server designed for local development with NAT/firewall traversal capabilities. It's the perfect tool for developers who enjoy watching their requests bounce around like a confused pinball before reaching their destination.

## Features

- ⚡ **High Performance**: Built with Go, because who has time to wait for slow proxies?
- 🔄 **Multiple Load Balancing Strategies**: Round Robin, Least Connections, and Random (for when you're feeling adventurous)
- 🩺 **Health Checking**: Monitors your targets like an overprotective parent
- 🔍 **Monitoring**: Built-in metrics endpoint because numbers make us feel smart
- 🌐 **NAT/Firewall Traversal**: Punches through NATs and firewalls like they're made of paper
- 🐳 **Docker Support**: Containerized for your convenience (and our sanity)
- ⚙️ **Flexible Configuration**: YAML configuration that's almost as flexible as a yoga instructor

## Installation

### From Source

```bash
git clone https://github.com/iwasforcedtobehere/goRZ.git
cd goRZ
make build
```

### Using Docker

```bash
docker pull ghcr.io/iwasforcedtobehere/gorz:latest
```

## Quick Start

1. Create a configuration file:

```bash
make config
```

2. Edit the generated `config.yaml` to match your needs (or just use the defaults, we won't judge)

3. Run the server:

```bash
make run
```

4. Marvel at your requests being proxied with the speed of a caffeinated cheetah

## Configuration

goRZ uses a YAML configuration file that's so intuitive, you'll think you've been using it for years (even if it's your first time):

```yaml
server:
  port: 8080
  read_timeout: 30
  write_timeout: 30
  idle_timeout: 60

proxy:
  targets:
    - name: "my-awesome-app"
      address: "http://localhost:3000"
      protocol: "http"
      weight: 1
  load_balancer: "roundrobin"
  health_check_path: "/health"
  health_check_interval: 30

nat:
  enabled: false
  stun_server: "stun:stun.l.google.com:19302"

logging:
  level: "info"
  format: "json"
  output: "stdout"

monitor:
  enabled: true
  port: 9090
  path: "/metrics"
  auth: false
```

## Load Balancing

goRZ supports multiple load balancing strategies because we believe in giving you choices (even if you'll probably just stick with round-robin):

### Round Robin
The classic "take turns" approach. Fair, predictable, and about as exciting as a beige wall.

### Least Connections
For when you want to distribute load based on which server is least busy. It's like being a traffic controller, but with less stress and more coffee.

### Random
For when you're feeling lucky or just enjoy chaos. It's surprisingly effective, which says something about the universe.

## NAT/Firewall Traversal

goRZ can help you traverse NATs and firewalls using STUN and TURN protocols. It's like having a secret tunnel that bypasses all those annoying network restrictions:

```yaml
nat:
  enabled: true
  stun_server: "stun:stun.l.google.com:19302"
  turn_server: "turn:your-turn-server:3478"
  turn_username: "your-username"
  turn_password: "your-password"
```

## Monitoring

goRZ includes a built-in monitoring endpoint that provides metrics about the proxy's performance. It's like having a fitness tracker for your proxy:

```bash
curl http://localhost:9090/metrics
```

You'll get a beautiful JSON response with all sorts of numbers and statistics that you can pretend to understand while nodding thoughtfully.

## Development

### Prerequisites

- Go 1.19 or later
- Make (for the Makefile targets)
- Docker (optional, for containerized development)

### Building

```bash
make build
```

### Testing

```bash
make test
```

### Linting

```bash
make lint
```

## Contributing

Contributions are welcome! If you'd like to contribute, please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

We'll review your contribution with the enthusiasm of someone who just discovered coffee.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. It's so permissive, you could probably use it to power a small country if you wanted to.

## Acknowledgments

- The Go team for creating a language that makes us feel productive
- The authors of all the libraries we're using (you're the real MVPs)
- Coffee, for fueling the development of this project
- Our users, for being brave enough to trust a proxy with a name that sounds like a monster from a 1950s B-movie

## Disclaimer

This software is provided "as is", without warranty of any kind, express or implied. In no event shall the authors be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

Basically, if it breaks, you get to keep both pieces. We're programmers, not lawyers.