From 0b9b0f5704774dd5176f328f83edea5c0797f8f8 Mon Sep 17 00:00:00 2001 From: Ara Sadoyan Date: Tue, 15 Apr 2025 19:53:07 +0200 Subject: [PATCH] README.md --- README.md | 133 +++++++++++++++++++++++++++++++++++++++++++++ etc/main.yaml | 25 +++++---- etc/upstreams.yaml | 9 +-- 3 files changed, 151 insertions(+), 16 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d1f97f9 --- /dev/null +++ b/README.md @@ -0,0 +1,133 @@ +# Gazan, Reverse proxy, service mesh based on Cloudflare's Pingora + +Built on Rust, on top of **Cloudflareโ€™s battle-tested Pingora engine**, **Gazan** delivers world-class performance, security, and scalability โ€” right out of the box. + +**Pingora** powers millions of requests per second at Cloudflareโ€™s edge, and now you can harness its core in your own infrastructure. This project brings that power into a lean and flexible reverse proxy with dynamic upstream configuration and +automatic websocket support. + +--- + +## ๐ŸŒ Highlights + +- โš™๏ธ **Upstream Providers:** Supports `file`-based static upstreams, dynamic service discovery via `Consul`, and upcoming `Kubernetes` integration +- ๐Ÿ” **Hot Reloading:** Modify upstreams on the fly via `upstreams.yaml` โ€” no restart needed +- ๐Ÿ”ฎ **Automatic WebSocket Support:** No special config required โ€” connection upgrades are handled seamlessly +- ๐Ÿ” **TLS Termination:** Fully supports TLS for incoming and upstream traffic +- ๐Ÿ›ก๏ธ **Built-in Auth Support:** (Basic and API Key ready) +- ๐Ÿง  **CORS & Header Injection:** Global and per-route header configuration +- ๐Ÿงช **Health Checks:** Pluggable health check methods for upstreams +- ๐Ÿ›ฐ๏ธ **Remote Config Push:** Lightweight HTTP API to update configs from CI/CD or other systems + +--- + +## ๐Ÿ“ File Structure + +``` +. +โ”œโ”€โ”€ main.yaml # Main configuration loaded at startup +โ”œโ”€โ”€ upstreams.yaml # Watched config with upstream mappings +โ”œโ”€โ”€ etc/ +โ”‚ โ”œโ”€โ”€ server.crt # TLS certificate (required if using TLS) +โ”‚ โ””โ”€โ”€ key.pem # TLS private key +``` + +--- + +## ๐Ÿ›  Configuration Overview + +### ๐Ÿ”ง `main.yaml` + +- `proxy_address_http`: `0.0.0.0:6193` (HTTP listener) +- `proxy_address_tls`: `0.0.0.0:6194` (TLS listener, optional) +- `config_address`: `0.0.0.0:3000` (HTTP API for remote config push) +- `upstreams_conf`: `etc/upstreams.yaml` (location of upstreams config) +- `log_level`: `info` (verbosity of logs) +- `hc_method`: `HEAD`, `hc_interval`: `2s` (upstream health checks) +- Other defaults: thread count, keep-alive pool size, etc. + +### ๐ŸŒ `upstreams.yaml` + +- `provider`: `file` or `consul` +- File-based upstreams define: + - Hostnames and routing paths + - Backend servers (load-balanced) + - Optional request headers + - Optional TLS for upstreams +- Global headers (e.g., CORS) apply to all proxied responses +- Optional authentication (Basic, API Key) โ€” currently commented for example + +--- + +## ๐Ÿ”Œ Running the Proxy + +```bash +./gazan -c path/to/main.yaml +``` + +Replace `APP_BINARY` with your compiled binary. + +--- + +## ๐Ÿ’ก Example + +A sample `upstreams.yaml` entry: + +```yaml +myhost.mydomain.com: + paths: + "/": + ssl: false + headers: + - "X-Some-Thing:Yaaaaaaaaaaaaaaa" + - "X-Proxy-From:Hopaaaaaaaaaaaar" + servers: + - "127.0.0.1:8000" + - "127.0.0.2:8000" +``` + +This means: + +- Requests to `myhost.mydomain.com/` will be load balanced to those servers. +- You can choose any path, deep nested paths are supported, the best match will be chosen +- Additional headers will be injected into the request. +- TLS is disabled for upstreams (but can be enabled). + +--- + +## ๐Ÿ”„ Hot Reload + +- Changes to `upstreams.yaml` are applied immediately. +- No need to restart the proxy โ€” just save the file. + +--- + +## ๐Ÿ” TLS Support + +To enable TLS for Proxy server: Currently only OpenSSL is supported, working on Boringssl and Rustls + +1. Set `proxy_address_tls` in `main.yaml` +2. Provide `tls_certificate` and `tls_key_file` + +--- + +## ๐Ÿ“ก Remote Config API + +You can push new `upstreams.yaml` over HTTP to `config_address` (`:3000` by default). Useful for CI/CD automation or remote config updates. + +```bash +curl -XPOST --data-binary @./etc/upstreams.txt 127.0.0.1:3000/conf +``` + +--- + +## ๐Ÿ“ƒ License + +The product is distributed under [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) + +--- + +## ๐Ÿง  Notes + +- Uses Pingora under the hood for efficiency and flexibility. +- Designed for edge proxying, internal routing, or hybrid cloud scenarios. +- WebSocket upgrade support is fully automatic. \ No newline at end of file diff --git a/etc/main.yaml b/etc/main.yaml index 7074835..d13abc6 100644 --- a/etc/main.yaml +++ b/etc/main.yaml @@ -1,17 +1,18 @@ -version: 1 -threads: 8 -#idle_timeout: 1000 -upstream_keepalive_pool_size: 100 -pid_file: /tmp/load_balancer.pid -error_log: /tmp/load_balancer_err.log -upgrade_sock: /tmp/load_balancer.sock -config_address: 0.0.0.0:3000 -proxy_address_http: 0.0.0.0:6193 +# Default configuration file for Pingora, read only once at startup +version: 1 # Pingora default setting +threads: 8 # Pingora default setting +#idle_timeout: 1000 # Pingora default setting +upstream_keepalive_pool_size: 100 # Pingora default setting +pid_file: /tmp/load_balancer.pid # Pingora default setting +error_log: /tmp/load_balancer_err.log # Pingora default setting +upgrade_sock: /tmp/load_balancer.sock # Pingora default setting +config_address: 0.0.0.0:3000 # HTTP API address for pushing upstreams.yaml from remote location +proxy_address_http: 0.0.0.0:6193 # Pingora default setting proxy_address_tls: 0.0.0.0:6194 # Optional tls_certificate: etc/server.crt # Mandatory if proxy_address_tls is set tls_key_file: etc/key.pem # Mandatory if proxy_address_tls is set -upstreams_conf: etc/upstreams.yaml +upstreams_conf: etc/upstreams.yaml # the location of upstreams file log_level: info # info, warn, error, debug, trace, off -hc_method: HEAD -hc_interval: 2 +hc_method: HEAD # Healthcheck method (HEAD, GET, POST are supported) +hc_interval: 2 #Intervak for Healthcheck in seconds diff --git a/etc/upstreams.yaml b/etc/upstreams.yaml index 2cd71d1..ca788ec 100644 --- a/etc/upstreams.yaml +++ b/etc/upstreams.yaml @@ -1,15 +1,16 @@ -provider: "file" +# The file is under watch and hot reload , changes are applied immediately, no need to restart of reload app +provider: "file" # consul globals: headers: - "Access-Control-Allow-Origin:*" - "Access-Control-Allow-Methods:POST, GET, OPTIONS" - "Access-Control-Max-Age:86400" -# authorization: +# authorization: # if enabled # - "basic" # - "zangag:Anhnazand1234" # - "apikey" # - "qweasdqweadhbk" -consul: +consul: # read only if provider is consul servers: - "http://master1:8500" - "http://192.168.22.1:8500" @@ -22,7 +23,7 @@ consul: - proxy: "proxy-backoffice-dev-backoffice-srv" real: "backoffice-dev-backoffice-srv" token: "8e2db809-845b-45e1-8b47-2c8356a09da0-a4370955-18c2-4d6e-a8f8-ffcc0b47be81" -upstreams: +upstreams: # read only if provider is files myip.netangels.net: paths: "/":