gorz/README.md

goRZ - Fast Reverse Proxy Server

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

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

Using Docker

docker pull ghcr.io/iwasforcedtobehere/gorz:latest

Quick Start

1. Create a configuration file:

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:

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):

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:

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:

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

make build

Testing

make test

Linting

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 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.