umputun/reproxyServer HTTP(S) leggero perimetrale e reverse proxy con SSL automatico, discovery Docker/Consul, autenticazione per route, limitazione del tasso e failover basato su health check.
<div align="center">
<img class="logo" src="https://raw.githubusercontent.com/umputun/reproxy/master/site/logo-bg.svg" width="355px" height="142px" alt="Reproxy | Simple Reverse Proxy"/>
</div>
Reproxy è un semplice server HTTP(s) edge / reverse proxy che supporta vari provider (docker, static, file, consul catalog). Uno o più provider forniscono informazioni sul server richiesto, sull'URL richiesto, sull'URL di destinazione e sull'URL di health check. È distribuito come binario singolo o come container docker.
- Terminazione SSL automatica con <a href="https://letsencrypt.org/" rel="nofollow noopener noreferrer" target="_blank">Let's Encrypt</a>
- Supporto per certificati SSL forniti dall'utente
- Regole proxy semplici ma flessibili
- Provider di regole proxy statico, da riga di comando
- Provider di regole proxy dinamico, basato su file
- Provider Docker con scoperta automatica
- Provider Consul Catalog con scoperta tramite tag di servizio
- Supporto per host multipli (virtuali)
- Compressione del traffico opzionale
- Controllo degli accessi basato su IP opzionale
- Autenticazione di base per singola rotta
- Limiti di dimensione e timeout definiti dall'utente
- Distribuzione come binario singolo
- Distribuzione come container Docker
- Server di asset statici integrato con modalità "SPA friendly" opzionale
- Supporto per regole di redirect
- Limitatore opzionale per l'attività complessiva e per l'attività dell'utente
- Health check live e fail-over/load-balancing
- Server di gestione con informazioni sulle rotte e metriche prometheus
- Supporto ai plugin tramite RPC per implementare funzionalità personalizzate
- Logging opzionale con sia Apache Log Format che report semplificati su stdout.
---
<div align="center">
[](https://github.com/umputun/reproxy/actions/workflows/ci.yml) [](https://coveralls.io/github/umputun/reproxy?branch=master) [](https://goreportcard.com/report/github.com/umputun/reproxy) [](https://hub.docker.com/r/umputun/reproxy)
</div>
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 corrispondenti dalla regex, ad esempio `http://d.example.com:8080/$1`. Per l'esempio precedente `http://s.example.com/api/something?foo=bar` sarà inoltrato tramite proxy 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 questi casi vengono espanse a `/$1`. Ad esempio, `/api/` -> `http://127.0.0.1/service` sarà tradotto in `^/api/(.*)` -> `http://127.0.0.1/service/$1`.
La sostituzione dell'host è supportata nell'URL di destinazione. Ad esempio, `/files/${host}` sarà sostituito con il nome dell'host corrispondente. È possibile utilizzare anche `$host` (senza parentesi graffe).
Sono supportati sia HTTP che HTTPS. Per HTTPS, è possibile utilizzare sia un certificato statico che certificati ACME automatici (Let's Encrypt). Un server di asset opzionale può essere utilizzato per servire file statici. L'avvio di reproxy richiede almeno un provider definito. Il resto dei parametri è strettamente opzionale e ha valori predefiniti ragionevoli.
Esempi:
- con un provider statico: `reproxy --static.enabled --static.rule="*,example.com/api/(.*),https://api.example.com/$1"`
- con scoperta automatica 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`
## Install
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 inoltre pacchetti deb e rpm sia per arm64 che per x86.
- per una distribuzione binaria scarica il file appropriato nella [sezione release](https://github.com/umputun/reproxy/releases)
- per gli utenti Homebrew: `brew install umputun/apps/reproxy`
- container docker disponibile su [Docker Hub](https://hub.docker.com/r/umputun/reproxy) così come su [Github Container Registry](https://github.com/users/umputun/packages/container/reproxy/versions). 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
Regole di proxy fornite da vari provider. Attualmente inclusi - `file`, `docker`, `static` e `consul-catalog`. Ogni provider può definire più regole di routing sia per le richieste proxate che per quelle statiche (asset). L'utente può impostare più provider contemporaneamente.
_Consulta esempi di vari provider in [examples](https://github.com/umputun/reproxy/tree/master/examples)_
### Provider static
Questo è il provider più semplice che definisce tutte le regole di mapping direttamente nella riga di comando (o nell'ambiente). Sono supportate più regole. Ogni regola è composta da 3 a 7 elementi separati da virgola `server,sourceurl,destination[,ping-url[,forward-health-checks[,timeout[,throttle]]]]`. Ad esempio:
- `*,^/api/(.*),https://api.example.com/$1` - inoltra 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` - inoltra tutte le richieste a `example.com` e con url `/foo/bar` verso `https://api.example.com/zzz` e usa `https://api.example.com/ping` per il controllo di integrità.
- `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 della richiesta per rotta di 5 minuti (il 4° e il 5° campo lasciati vuoti per saltare ping-url e forward-health-checks).
- `example.com,^/login,https://api.example.com/login,,,,2` - throttle per rotta di 2 req/sec per utente (i campi posizionali precedenti sono lasciati vuoti).
Il 4° elemento definisce un ping url opzionale usato per la segnalazione dello stato di integrità. Il 5° elemento abilita opzionalmente l'inoltro delle richieste di controllo di integrità al backend (`true`, `yes`, `1`). Consulta la sezione [Controllo di integrità](#ping-and-health-checks) per maggiori dettagli. Il 6° elemento è un timeout opzionale della richiesta per rotta (durata Go, ad es. `5m`, `30s`); `0` o vuoto eredita l'impostazione globale `--timeout.write`. Il 7° elemento è un limite opzionale di req/sec per utente per rotta; `0` o vuoto eredita `--throttle.user`. I campi posizionali vuoti sono consentiti (ad es. `,,` per i campi centrali non utilizzati).
### Provider file
Questo provider usa un file yaml con le regole di routing.
`reproxy --file.enabled --file.name=config.yml`
Esempio di `config.yml`:
```yaml
default: # the same as * (catch-all) server
- { route: "^/api/svc1/(.*)", dest: "http://127.0.0.1:8080/blah1/$1" }
- {
route: "/api/svc3/xyz",
dest: "http://127.0.0.3:8080/blah3/xyz",
ping: "http://127.0.0.3:8080/ping",
remote: "192.168.1.0/24, 127.0.0.1", # optional, restrict access to the route
forward-health-checks: true # optional, forward /ping and /health to backend
}
- {
route: "^/admin/(.*)",
dest: "http://127.0.0.4:8080/$1",
auth: "admin:$2y$05$..." # optional, per-route basic auth (htpasswd bcrypt format)
}
- {
route: "^/upload/(.*)",
dest: "http://127.0.0.5:8080/$1",
timeout: 5m # optional, per-route request timeout (Go duration). 0 or omitted inherits --timeout.write
}
- {
route: "^/login",
dest: "http://127.0.0.6:8080/login",
throttle: 2 # optional, per-route req/sec per user. 0 or omitted inherits --throttle.user
}
srv.example.com:
- { route: "^/api/svc2/(.*)", dest: "http://127.0.0.2:8080/blah2/$1/abc" }
- { route: "/web/", dest: "/var/www", "assets": true }
"*.files.example.com":
- { route: "^/files/(.*)", dest: "http://123.123.200.200:8080/$host/$1" }
```
Questo è un provider dinamico e le modifiche ai file verranno applicate automaticamente.
**Più siti statici su domini diversi** possono essere serviti utilizzando i nomi dei server come chiavi con `assets: true`:
```yaml
site-en.example.com:
- { route: "/", dest: "/var/www/en", "assets": true }
site-ru.example.com:
- { route: "/", dest: "/var/www/ru", "assets": true }
```
**Importante:** il campo `route` per le regole degli asset deve essere un prefisso di percorso (ad es. `/`, `/web/`), non una regex. I pattern regex come `^/(.*)` non funzioneranno con `assets: true` perché la corrispondenza degli asset statici utilizza il confronto per prefisso di percorso, non le regex.
### Provider Docker
Il provider Docker supporta una scoperta completamente automatica (con `--docker.auto`) senza necessità di configurazione aggiuntiva. Per impostazione predefinita, reindirizza tutte le richieste come `http://<url>/<container name>/(.*)` all'IP interno del container specificato e alla porta esposta. Verranno rilevati solo i container attivi (in esecuzione).
Questo comportamento predefinito può essere modificato tramite le label:
- `reproxy.server` - server (hostname) da far corrispondere. Può anche essere una lista di server separati da virgola.
- `reproxy.route` - route di origine (location)
- `reproxy.dest` - percorso di destinazione. Nota: non è l'URL completo, ma solo il percorso che verrà aggiunto a ip:porta del container
- `reproxy.port` - porta di destinazione per il container rilevato
- `reproxy.ping` - percorso di ping per il container di destinazione.
- `reproxy.remote` - limita l'accesso alla route con una lista di subnet o IP separati da virgola
- `reproxy.auth` - richiede l'autenticazione basic per la route con coppie `user:bcrypt_hash` separate da virgola (generate da `htpasswd -nbB`)
- `reproxy.assets` - imposta la mappatura degli asset come `web-root:location`, ad esempio `reproxy.assets=/web:/var/www`
- `reproxy.keep-host` - mantiene l'header host così com'è (`yes`, `true`, `1`) oppure lo sostituisce con l'host di destinazione (`no`, `false`, `0`)
- `reproxy.forward-health-checks` - inoltra le richieste `/ping` e `/health` al backend invece di farle gestire da reproxy (`yes`, `true`, `1`). Utile quando il backend dispone di propri endpoint di health check con risposte specifiche dell'applicazione.
- `reproxy.timeout` - timeout della richiesta per route come durata Go (ad es. `5m`, `30s`). `0` o non impostato eredita il valore globale `--timeout.write`. I valori non validi vengono ignorati con un avviso.
- `reproxy.throttle` - limite di richieste/sec per utente per route. `0` o non impostato eredita `--throttle.user`. I valori non validi o negativi vengono ignorati con un avviso.
- `reproxy.enabled` - abilita (`yes`, `true`, `1`) o disabilita (`no`, `false`, `0`) il container dalle destinazioni di reproxy.
Nota bene: senza `--docker.auto` il container di destinazione deve avere almeno una delle label `reproxy.*` per essere considerato una potenziale destinazione.
Con `--docker.auto`, tutti i container con porta esposta verranno considerati destinazioni di routing. Ci sono 3 modi per limitarlo:
- Escludere esplicitamente alcuni container con `--docker.exclude`, ad es. `--docker.exclude=c1 --docker.exclude=c2 ...`
- Consentire solo una particolare rete docker con `--docker.network`
- Impostare la label `reproxy.enabled=false` o `reproxy.enabled=no` o `reproxy.enabled=0`
Se non è definita alcuna `reproxy.route`, la route predefinita è `^/<container_name>/(.*)`. Nel caso in cui tutte le sorgenti proxate debbano avere lo stesso pattern di prefisso, ad esempio `/api/(.*)`, l'utente può definire il prefisso comune (in questo caso `/api`) per tutte le route basate su container. Questo può essere fatto con il parametro `--docker.prefix`.
Il provider Docker consente inoltre di definire più set di label `reproxy.N.something` per far corrispondere più route distinte sullo stesso container. Questo è utile poiché in alcuni casi un singolo container può esporre più endpoint, ad esempio un'API pubblica e un'API di amministrazione. Tutte le label sopra indicate possono essere utilizzate con "N-index", ad es. `reproxy.1.server`, `reproxy.1.port` e così via. N deve essere compreso nell'intervallo da 0 a 9.
Questo è un provider dinamico e qualsiasi modifica allo stato del container verrà applicata automaticamente.
### Provider Consul Catalog
Uso: `reproxy --consul-catalog.enabled`
Il provider Consul Catalog chiama periodicamente l'API di Consul (ogni secondo per impostazione predefinita) per ottenere i servizi che hanno un qualsiasi tag con prefisso `reproxy.`. L'utente può ridefinire l'intervallo di controllo con il flag da riga di comando `--consul-catalog.interval` così come l'indirizzo di consul con l'opzione da riga di comando `--consul-catalog.address`. L'indirizzo predefinito è `http://127.0.0.1:8500`.
Ad esempio:
```
reproxy --consul-catalog.enabled --consul-catalog.address=http://192.168.1.100:8500 --consul-catalog.interval=10s
```
Per impostazione predefinita, il provider imposta i valori per ogni servizio:
- enabled `false`
- server `*`
- route `^/(.*)`
- dest `http://<SERVICE_ADDRESS_FROM_CONSUL>/$1`
- ping `http://<SERVICE_ADDRESS_FROM_CONSUL>/ping`
Questo comportamento predefinito può essere modificato tramite i tag:
- `reproxy.server` - server (hostname) da confrontare. Può anche essere una lista di server separati da virgola.
- `reproxy.route` - route di origine (location)
- `reproxy.dest` - percorso di destinazione. Nota: non è l'URL completo, ma solo il percorso che verrà aggiunto all'ip:porta del servizio
- `reproxy.port` - porta di destinazione per il servizio individuato
- `reproxy.remote` - limita l'accesso alla route con una lista di subnet o ip separati da virgola
- `reproxy.auth` - richiede l'autenticazione basic per la route con coppie `user:bcrypt_hash` separate da virgola (generate da `htpasswd -nbB`)
- `reproxy.ping` - percorso di ping per il servizio di destinazione.
- `reproxy.forward-health-checks` - inoltra le richieste `/ping` e `/health` al backend (`true`, `yes`, `1`).
- `reproxy.timeout` - timeout della richiesta per route come durata Go (ad es. `5m`, `30s`). `0` o non impostato eredita il valore globale `--timeout.write`. I valori non validi vengono ignorati con un avviso.
- `reproxy.throttle` - limite di richieste/sec per utente per route. `0` o non impostato eredita `--throttle.user`. I valori non validi o negativi vengono ignorati con un avviso.
- `reproxy.enabled` - abilita (`yes`, `true`, `1`) o disabilita (`qualsiasi altro valore`) il servizio dalle destinazioni di reproxy.
### Dettagli specifici di Compose
Nel caso in cui le regole siano impostate come parte dell'ambiente di docker compose, la destinazione con il gruppo regex entrerà in conflitto con la sintassi di compose. Ovvero, il tentativo di usare `https://api.example.com/$1` nell'ambiente compose fallirà a causa di un errore di sintassi. La soluzione standard in questo caso è "eseguire l'escape" del segno `$` sostituendolo con `$$`, ovvero `https://api.example.com/$$1`. Questa sostituzione è supportata da docker compose e non ha nulla a che fare con reproxy stesso. Un altro modo è usare `@` invece di `$`, che è supportato a livello di reproxy, ovvero `https://api.example.com/@1`_
## Supporto SSL
La modalità SSL (per impostazione predefinita nessuna) può essere impostata su `auto` (certificati ACME/LE), `static` (certificato esistente) o `none`. Se `auto` è attivo, il certificato SSL verrà emesso automaticamente per tutti i nomi dei server individuati. L'utente può sovrascriverlo impostando il valore o i valori di `--ssl.fqdn`. In modalità SSL `auto` e `static`, Reproxy aggiungerà automaticamente gli header `X-Forwarded-Proto` e `X-Forwarded-Port`. Questi header sono utili ai servizi dietro il proxy per conoscere il protocollo originale (http o https) e il numero di porta usato dal client.
Quando si utilizza ACME con i provider di discovery (docker, file, consul), i certificati SSL vengono ottenuti automaticamente per i server appena individuati senza richiedere un riavvio di reproxy.
### Sfide ACME
Reproxy supporta due tipi di sfide ACME per la validazione dei certificati SSL:
1. **Sfida HTTP-01** (predefinita): convalida la proprietà del dominio servendo un token a uno specifico URL HTTP. Richiede che la porta 80 sia accessibile pubblicamente.
2. **Sfida DNS-01**: convalida la proprietà del dominio creando record DNS TXT. Questo metodo:
- Non richiede che la porta 80 sia accessibile
- Funziona con certificati wildcard
- Richiede la configurazione di un provider DNS supportato
#### Selezione della sfida
Reproxy determina automaticamente quale metodo di sfida utilizzare in base alla configurazione:
- **HTTP-01** (predefinita): usata quando non è configurato alcun provider DNS
- **DNS-01**: usata quando è configurato un provider DNS
Non è necessario selezionare esplicitamente un tipo di sfida: basta configurare un provider DNS se si desidera utilizzare le sfide DNS-01.
I controlli di propagazione DNS scadono dopo 2 minuti per impostazione predefinita. Aumentare questo valore con `--ssl.dns.propagation-timeout=5m` per le zone che pubblicano i record di sfida lentamente. L'opzione `--ssl.dns.ttl` controlla il TTL dei record e non modifica il timeout di propagazione.
#### Provider DNS attualmente supportati
Reproxy include attualmente il supporto per i seguenti provider DNS:
- **Cloudflare**: `--ssl.dns.type=cloudflare --ssl.dns.cloudflare.api-token=TOKEN`
- **Route53 (AWS)**: `--ssl.dns.type=route53 --ssl.dns.route53.region=REGION --ssl.dns.route53.hosted-zone-id=ID`
- **Gandi**: `--ssl.dns.type=gandi --ssl.dns.gandi.bearer-token=TOKEN`
- **DigitalOcean**: `--ssl.dns.type=digitalocean --ssl.dns.digitalocean.api-token=TOKEN`
- **Hetzner**: `--ssl.dns.type=hetzner --ssl.dns.hetzner.api-token=TOKEN`
- **Linode**: `--ssl.dns.type=linode --ssl.dns.linode.api-token=TOKEN`
- **GoDaddy**: `--ssl.dns.type=godaddy --ssl.dns.godaddy.api-token=TOKEN`
- **Namecheap**: `--ssl.dns.type=namecheap --ssl.dns.namecheap.api-key=KEY --ssl.dns.namecheap.user=USER`
- **Scaleway**: `--ssl.dns.type=scaleway --ssl.dns.scaleway.secret-key=KEY --ssl.dns.scaleway.organization-id=ID`
- **Porkbun**: `--ssl.dns.type=porkbun --ssl.dns.porkbun.api-key=KEY --ssl.dns.porkbun.api-secret-key=SECRET`
- **DNSimple**: `--ssl.dns.type=dnsimple --ssl.dns.dnsimple.api-access-token=TOKEN --ssl.dns.dnsimple.account-id=ID`
- **DuckDNS**: `--ssl.dns.type=duckdns --ssl.dns.duckdns.api-token=TOKEN`
Esempio con Cloudflare come provider DNS:
```
export CLOUDFLARE_API_TOKEN=your_api_token
reproxy --ssl.type=auto [email protected] --ssl.fqdn=example.com
```
La challenge DNS-01 è particolarmente utile quando:
- Il tuo server non ha la porta 80 esposta pubblicamente
- Hai bisogno di certificati wildcard (ad es., *.example.com)
- Sei dietro firewall restrittivi
## Header
Reproxy consente di sanitizzare (rimuovere) gli header in ingresso passando il parametro `--drop-header` (può essere ripetuto). Questo parametro può essere utile per assicurarsi che alcuni degli header, impostati internamente dai servizi, non possano essere impostati/contraffatti dall'utente finale. Ad esempio, se alcuni dei servizi responsabili dell'autenticazione impostano `X-Auth-User` e `X-Auth-Token`, è probabile che abbia senso rimuovere tali header dalle richieste in ingresso passando il parametro `--drop-header=X-Auth-User --drop-header=X-Auth-Token` o tramite la variabile d'ambiente `DROP_HEADERS=X-Auth-User,X-Auth-Token`
È supportata anche la funzione opposta, ovvero l'impostazione degli header in uscita. Può essere utile in molti casi, ad esempio per applicare alcune regole CORS personalizzate, header relativi alla sicurezza e così via. Questo può essere fatto con il parametro `--header` (può essere ripetuto) o con la variabile d'ambiente `HEADER`. Ad esempio, ecco come può essere fatto con docker compose:
```yaml
environment:
- HEADER=
X-Frame-Options:SAMEORIGIN,
X-XSS-Protection:1; mode=block;,
Content-Security-Policy:default-src 'self'; style-src 'self' 'unsafe-inline';
```
## Logging
Per impostazione predefinita non viene generato alcun log delle richieste. Questo può essere attivato impostando `--logger.enabled`. Il log (con rotazione automatica) utilizza il [Apache Combined Log Format](http://httpd.apache.org/docs/2.2/logs.html#combined)
L'utente può anche attivare il log su stdout con `--logger.stdout`. Non influirà sul logging su file descritto sopra, ma restituirà alcune informazioni minime sulle richieste elaborate, simili a queste:
```
2021/04/16 01:17:25.601 [INFO] GET - /echo/image.png - xxx.xxx.xxx.xxx - 200 (155400) - 371.661251ms
2021/04/16 01:18:18.959 [INFO] GET - /api/v1/params - xxx.xxx.xxx.xxx - 200 (74) - 1.217669m
```
## Assets Server
Gli utenti possono attivare il server degli asset (disattivato per impostazione predefinita) per servire file statici. Finché `--assets.location` è impostato, tratta ogni richiesta non inoltrata al proxy sotto `assets.root` come una richiesta di file statici. Il server degli asset può essere utilizzato senza alcun provider proxy; in questa modalità, reproxy agisce come un semplice server web per il contenuto statico. Il server degli asset supporta anche la "spa mode" con `--assets.spa`, in cui tutte le richieste non trovate vengono inoltrate a `index.html`.
Oltre al server degli asset comune, sono supportati più server degli asset personalizzati. Ogni provider ha un modo diverso di definire tale regola statica, e alcuni provider potrebbero non supportarla affatto. Ad esempio, più server degli asset hanno senso nel provider static (provider da riga di comando), nel provider file e persino con i provider docker, tuttavia ha molto poco senso con il provider consul catalog.
1. provider static - se l'elemento sorgente è preceduto da `assets:` o `spa:` verrà trattato come file-server. Ad esempio `*,assets:/web,/var/www,` servirà tutte le richieste `/web/*` con un file server sopra la directory `/var/www`.
2. provider file - impostando i campi opzionali `assets: true` o `spa: true`. Nota: il campo `route` deve essere un prefisso di percorso (ad es., `/`, `/web/`), non un pattern regex.
3. provider docker - `reproxy.assets=web-root:location`, cioè `reproxy.assets=/web:/var/www`. Il passaggio alla spa mode avviene impostando `reproxy.spa` a `yes` o `true`
### Caching
Il server degli asset supporta il controllo della cache con il parametro `--assets.cache=<duration>`. Una durata `0s` (predefinita) disattiva il controllo della cache. Una durata è una sequenza di numeri decimali, ciascuno con una frazione opzionale e un suffisso di unità, come "300ms", "1.5h" o "2h45m". Le unità di tempo valide sono "ns", "us" (o "µs"), "ms", "s", "m", "h" e "d".
Ci sono due modi per impostare la durata della cache:
1. Un singolo valore per tutti gli asset statici. È semplice come `--assets.cache=48h`.
2. Durata personalizzata per diversi tipi mime. Deve includere due parti: il valore predefinito e le coppie mime:durata. Nella riga di comando questo appare come più opzioni `--assets.cache`, cioè `--assets.cache=48h --assets.cache=text/html:24h --assets.cache=image/png:2h`. I valori delle variabili d'ambiente devono essere separati da virgole, cioè `ASSETS_CACHE=48h,text/html:24h,image/png:2h`
Una pagina 404 personalizzata (non trovato) può essere impostata con il parametro `--assets.not-found=<path>`. Il percorso deve essere relativo alla radice degli asset.
## Utilizzare reproxy come immagine di base
Servire contenuto puramente statico è uno dei casi d'uso più diffusi. Di solito viene utilizzato per il container frontend separato che fornisce solo l'interfaccia utente. Con il server degli asset, realizzare un tale container è quasi banale. Questo è un esempio tratto dal container che serve [reproxy.io](http://reproxy.io)
```docker
FROM node:22-alpine as build
WORKDIR /build
COPY site/ /build
COPY README.md /build/src/index.md
RUN yarn --frozen-lockfile
RUN yarn build
RUN ls -la /build/public
FROM ghcr.io/umputun/reproxy
COPY --from=build /build/public /srv/site
EXPOSE 8080
USER app
ENTRYPOINT ["/srv/reproxy", "--assets.location=/srv/site"]
```
Tutto ciò che serve è copiare gli asset statici in una posizione e passare questa posizione come `"--assets.location` all'entrypoint di reproxy.
## Modalità compatibile con le SPA
Alcune applicazioni SPA contano sul proxy per gestire i 404 sugli asset statici in modo speciale, reindirizzandoli a "/index.html". Questo è simile alla direttiva `try_files $uri $uri/ …` di nginx e, apparentemente, questa funzionalità è in qualche modo importante per le moderne web app.
Questa modalità è disattivata per impostazione predefinita e può essere attivata impostando `--assets.spa` o la variabile d'ambiente `ASSETS_SPA=true`.
## Redirect
Per impostazione predefinita reproxy tratta la destinazione come una posizione proxy, ovvero effettua una chiamata http internamente e restituisce la risposta al client. Tuttavia, anteponendo `@code` all'url di destinazione, questo comportamento può essere modificato in redirect permanenti (codice di stato 301) o temporanei (codice di stato 302). Ovvero, impostando la destinazione a `@301 https://example.com/something` si causerà un redirect http permanente verso `Location: https://example.com/something`
codici supportati:
- `@301`, `@perm` - redirect permanente
- `@302`, `@temp`, `@tmp` - redirect temporaneo
## Ulteriori opzioni
- `--gzip` abilita la compressione gzip (o deflate) per le risposte. La decisione viene presa per ogni risposta, in base ai suoi header finali:
- i media type che corrispondono a `--gzip-exclude` vengono inviati così come sono. Il valore è una lista separata da virgole di tipi esatti (`image/png`) o prefissi (`audio/*`). Il valore predefinito esclude audio, video, immagini compresse (jpeg, png, gif, webp, avif), font woff e archivi comuni. Una lista personalizzata sostituisce quella predefinita, e un valore vuoto (`--gzip-exclude=`) disattiva le esclusioni.
- le risposte parziali (`206`, o qualsiasi risposta con `Content-Range`) non vengono mai compresse, così le richieste `Range` continuano a funzionare.
- reproxy non ricomprime le risposte che contengono già `Content-Encoding`. L'header `Accept-Encoding` del client viene inoltrato all'upstream, quindi un upstream che comprime autonomamente decide per le proprie risposte, e la lista di esclusione si applica solo alla compressione effettuata da reproxy.
- una risposta compressa rimuove `Accept-Ranges` e il `Content-Length` originale, e un `ETag` forte diventa debole (`W/"..."`), poiché i suoi byte differiscono dall'originale.
- `--max=N` consente di impostare la dimensione massima della richiesta (predefinita 64k). Impostandola a `0` si disattiva il controllo della dimensione.
- `--timeout.*` vari timeout sia per il server che per il trasporto del proxy. Vedi la sezione `timeout` in [All Application Options](#all-application-options). Un valore zero o negativo significa che non ci sarà alcun timeout.
- `--insecure` disattiva la verifica SSL sull'host di destinazione. Utile per i certificati autofirmati.
## Porte predefinite
Per eliminare la necessità di passare parametri/variabili d'ambiente personalizzati, il valore predefinito di `--listen` è dinamico e cerca di essere ragionevole e utile per i casi tipici:
- Se l'utente imposta qualcosa in `--listen`, tutta la logica seguente viene ignorata e host:porta passati vengono usati direttamente.
- Se l'utente non imposta nulla in `--listen` e reproxy viene eseguito al di fuori del container docker, il valore predefinito è `127.0.0.1:80` per la modalità http (`ssl.type=none`) e `127.0.0.1:443` per la modalità ssl (`ssl.type=auto` o `ssl.type=static`).
- Se l'utente non imposta nulla in `--listen` e reproxy viene eseguito all'interno di docker, il valore predefinito è `0.0.0.0:8080` per la modalità http, e `0.0.0.0:8443` per la modalità ssl.
Un altro valore predefinito impostato in modo dinamico simile è `--ssl.http-port`. Per l'esecuzione all'interno del container docker è impostato a `8080` e al di fuori a `80`.
## Ping, health check e fail-over
reproxy fornisce due endpoint per questo scopo:
- `/ping` risponde con `pong` e indica che reproxy è attivo e funzionante
- `/health` restituisce lo stato `200 OK` se tutti i server di destinazione hanno risposto alla loro richiesta di ping con `200` oppure `417 Expectation Failed` se uno qualsiasi dei server ha risposto con un codice diverso da 200. Restituisce inoltre un corpo json con i dettagli sui servizi superati/falliti.
Oltre agli endpoint sopra, reproxy supporta controlli di integrità live opzionali. In questo caso (se abilitato), ogni destinazione viene verificata periodicamente per la risposta al ping e le route delle destinazioni non funzionanti vengono escluse. È possibile che vengano restituite più destinazioni identiche dallo stesso o da diversi provider, e viene scelta solo quella che supera il controllo. Se vengono scoperte e superate numerose corrispondenze, viene scelta quella finale secondo la strategia `lb-type` (per impostazione predefinita selezione casuale).
Per attivare il controllo di integrità live, l'utente deve impostare `--health-check.enabled` (o la variabile d'ambiente `HEALTH_CHECK_ENABLED=true`). Per personalizzare l'intervallo di controllo è possibile usare `--health-check.interval=`.
## API di gestione
Opzionale, può essere attivata con `--mgmt.enabled`. Espone 2 endpoint su `mgmt.listen` (indirizzo:porta):
- `GET /routes` - elenco di tutte le route scoperte
- `GET /metrics` - restituisce le metriche prometheus (`http_requests_total`, `response_status` e `http_response_time_seconds`)
Per impostazione predefinita, `http_response_time_seconds` utilizza i percorsi grezzi delle richieste come label, il che può causare un'elevata cardinalità con URL dinamici (ad es., `/api/users/123`, `/api/users/456`). Usare `--mgmt.low-cardinality` per passare invece ai pattern delle route (ad es., `^/api/users/(.*)`), riducendo significativamente la cardinalità delle metriche.
_vedi anche [examples/metrics](https://github.com/umputun/reproxy/tree/master/examples/metrics)_
## Segnalazione degli errori
Reproxy restituisce un errore 502 (Bad Gateway) nel caso in cui la richiesta non corrisponda a nessuna delle route e degli asset forniti. Nel caso in cui si verifichi un errore interno imprevisto, restituisce 500. Per impostazione predefinita reproxy genera la versione testuale più semplice dell'errore - "Server error". Impostando `--error.enabled` si attiva il messaggio di errore html predefinito e con `--error.template` l'utente può impostare qualsiasi file template html personalizzato per la generazione dell'errore. Il template ha due variabili: `{{.ErrCode}}` e `{{.ErrMessage}}`. Ad esempio questo template `oh my! {{.ErrCode}} - {{.ErrMessage}}` verrà generato come `oh my! 502 - Bad Gateway`
## Throttling
Reproxy consente di definire un valore massimo di req/sec a livello di sistema per l'attività complessiva del sistema e per singolo utente. I valori 0 (predefiniti) sono considerati illimitati.
---
[Read more](https://github.com/umputun/reproxy)