reproxy

Reproxy è un semplice server HTTP(s) di perimetro / proxy inverso che supporta vari provider (docker, static, file, consul catalog). Uno o più provider forniscono informazioni sul server richiesto, l'URL richiesto, l'URL di destinazione e l'URL di health check. È distribuito come singolo binario o come container docker.

• Terminazione automatica SSL con Let's Encrypt
• Supporto di certificati SSL forniti dall'utente
• Regole proxy semplici ma flessibili
• Provider di regole proxy statico e da riga di comando
• Provider di regole proxy dinamico basato su file
• Provider Docker con rilevamento automatico
• Provider Consul Catalog con rilevamento tramite tag di servizio
• Supporto per più host (virtuali)
• Compressione del traffico opzionale
• Controllo degli accessi basato su IP opzionale
• Autenticazione di base per rotta
• Limiti di dimensione e timeout definibili dall'utente
• Distribuzione come singolo binario
• Distribuzione come container Docker
• Server integrato per asset statici con modalità "SPA friendly" opzionale
• Supporto per regole di reindirizzamento
• Limitatore opzionale per l'attività complessiva e per l'attività dell'utente
• Health check in tempo reale e fail-over/load-balancing
• Server di gestione con informazioni sulle route e metriche Prometheus
• Supporto per plugin tramite RPC per implementare funzionalità personalizzate
• Logging opzionale sia in Apache Log Format che con report stdout semplificati.

---

Il server (host) può essere impostato come FQDN, ad esempio s.example.com, * (catch-all) o una regex. La corrispondenza esatta ha la priorità, quindi se ci sono due regole con server example.com e example\.(com|org), una richiesta a example.com/some/url corrisponderà alla prima. L'URL richiesto può essere una regex, ad esempio ^/api/(.*) e l'URL di destinazione può contenere gruppi catturati dalla regex, ad esempio http://d.example.com:8080/$1. Per l'esempio sopra, http://s.example.com/api/something?foo=bar verrà inoltrato a http://d.example.com:8080/something?foo=bar.

Per comodità, le richieste con / finale e senza gruppi regex vengono espanse a /(.*), e le destinazioni in tali casi vengono espanse a /$1. Ad esempio /api/ -> http://127.0.0.1/service verrà tradotto in ^/api/(.*) -> http://127.0.0.1/service/$1.

La sostituzione dell'host è supportata nell'URL di destinazione. Ad esempio, /files/${host} verrà sostituito con il nome dell'host corrispondente. È utilizzabile anche $host (senza parentesi).

Sono supportati sia HTTP che HTTPS. Per HTTPS, può essere utilizzato un certificato statico così come certificati ACME automatici (Let's Encrypt). Un server di asset opzionale può essere utilizzato per servire file statici. Avviare reproxy richiede almeno un provider definito. Il resto dei parametri sono strettamente opzionali e hanno valori predefiniti ragionevoli.

Esempi:

• con un provider statico: reproxy --static.enabled --static.rule="*,example.com/api/(.*),https://api.example.com/$1"
• con rilevamento automatico docker: reproxy --docker.enabled --docker.auto
• come container docker: docker up -p 80:8080 umputun/reproxy --docker.enabled --docker.auto
• con SSL automatico: docker up -p 80:8080 -p 443:8443 umputun/reproxy --docker.enabled --docker.auto --ssl.type=auto --ssl.fqdn=example.com

Installazione

Reproxy è distribuito come un piccolo binario autonomo e come immagine docker. Sia il binario che l'immagine supportano più architetture e più sistemi operativi, tra cui linux_x86_64, linux_arm64, linux_arm, macos_x86_64, macos_arm64, windows_x86_64 e windows_arm. Forniamo anche pacchetti deb e rpm sia per arm64 che per x86.

• per una distribuzione binaria, scaricare il file appropriato nella sezione release
• per utenti Homebrew: brew install umputun/apps/reproxy
• il container docker è disponibile su Docker Hub e su Github Container Registry. Ad esempio docker pull umputun/reproxy o docker pull ghcr.io/umputun/reproxy.

L'ultima versione stabile ha il tag docker :vX.Y.Z (con alias :latest) e il master corrente ha il tag :master.

Provider

Le regole del proxy sono fornite da vari provider. Attualmente inclusi: file, docker, static e consul-catalog. Ogni provider può definire più regole di routing sia per le richieste inoltrate che per i file statici (asset). L'utente può impostare più provider contemporaneamente.

Vedi esempi di vari provider in examples

Provider statico

Questo è il provider più semplice che definisce tutte le regole di mappatura direttamente nella riga di comando (o nell'ambiente). Sono supportate più regole. Ogni regola è composta da 3 a 7 elementi separati da virgole: server,sourceurl,destination[,ping-url[,forward-health-checks[,timeout[,throttle]]]]. Ad esempio:

• *,^/api/(.*),https://api.example.com/$1 - proxy tutte le richieste a qualsiasi host/server con prefisso /api verso https://api.example.com
• example.com,/foo/bar,https://api.example.com/zzz,https://api.example.com/ping - proxy tutte le richieste a example.com con URL /foo/bar verso https://api.example.com/zzz e utilizza https://api.example.com/ping per il health check.
• example.com,/foo/bar,https://api.example.com/zzz,https://api.example.com/ping,true - come sopra ma inoltra anche le richieste /ping e /health al backend.
• example.com,^/upload/(.*),https://api.example.com/$1,,,5m - timeout di richiesta per-route di 5 minuti (il 4° e 5° campo lasciati vuoti per saltare ping-url e forward-health-checks).
• example.com,^/login,https://api.example.com/login,,,,2 - limite per-route di 2 req/sec per utente (i campi posizionali precedenti sono lasciati vuoti).

Il 4° elemento definisce un URL di ping opzionale utilizzato per il reporting dello stato. Il 5° elemento abilita opzionalmente l'inoltro delle richieste di health check al backend (true, yes, 1). Vedi la sezione Health check per maggiori dettagli. Il 6° elemento è un timeout di richiesta opzionale per-route (durata Go, ad esempio 5m, 30s); 0 o vuoto eredita l'impostazione globale --timeout.write. Il 7° elemento è un limite opzionale di req/sec per utente per-route; 0 o vuoto eredita --throttle.user. I campi posizionali vuoti sono consentiti (ad esempio ,, per i campi intermedi non utilizzati).

Provider file

Questo provider utilizza un file yaml con regole di routing.

reproxy --file.enabled --file.name=config.yml