Comunicazione tra servizi: indirizzi interni e servizi solo interni.
Come i servizi di un'applicazione si raggiungono tramite l'indirizzo interno, le variabili RIVERVO_<NAME>_URL, i servizi senza indirizzo pubblico, più istanze, timeout e nuovi tentativi con esempi per Node.js, Laravel e Python.
I servizi di un'applicazione comunicano tra loro direttamente, senza passare da internet. Un sito può chiamare la propria API, un worker può chiamare un servizio interno, e questo traffico è gratuito: non viene conteggiato come traffico.
Gli esempi qui sotto usano due servizi web: web, il sito che aprono i visitatori, con Indirizzo pubblico, e api, che chiamano solo web e gli altri servizi, impostato su Solo interno.
L'indirizzo interno
Ogni servizio web, con indirizzo pubblico o solo interno, ha un Indirizzo interno nella forma http://<service-name>:<port>, ad esempio http://api:8080. Lo trovi nella pagina del servizio e nella Panoramica dell'applicazione, con un pulsante per copiarlo e l'indicazione «Gli altri servizi di questa applicazione lo raggiungono qui: niente internet, niente costi di traffico.»
- La porta è 8080 per un servizio costruito da un repository, oppure la Porta che hai indicato per un servizio da immagine pronta.
- Solo i servizi della stessa applicazione possono raggiungere questo indirizzo. Non si apre da internet né da altre applicazioni.
- L'indirizzo usa
http://. La connessione resta dentro l'applicazione, quindi non c'è nessun certificato da configurare.
Variabili con gli indirizzi
Non devi copiare gli indirizzi nel tuo codice. Ogni servizio con codice dell'applicazione (servizi web, worker in background e attività pianificate) riceve una variabile con l'indirizzo interno di ciascun altro servizio web dell'applicazione:
RIVERVO_<NAME>_URL=http://<name>:<port>
NAME è il nome del servizio in maiuscolo, con i trattini trasformati in _:
| Servizio | Variabile |
|---|---|
api | RIVERVO_API_URL=http://api:8080 |
admin-api | RIVERVO_ADMIN_API_URL=http://admin-api:8080 |
web | RIVERVO_WEB_URL=http://web:8080 |
search (da immagine pronta, porta 7700) | RIVERVO_SEARCH_URL=http://search:7700 |
- Un servizio non riceve una variabile per sé stesso.
- Database e Valkey mantengono la loro
RIVERVO_<NAME>_URLcon l'indirizzo di connessione. I nomi dei servizi sono unici all'interno di un'applicazione, quindi i nomi non si sovrappongono mai. - Le variabili sono elencate nella scheda Variabili, tra quelle Impostate automaticamente. Come per ogni variabile automatica, una tua variabile (o una variabile condivisa) con lo stesso nome prende il suo posto: vedi Variabili d'ambiente.
- Le variabili arrivano a un servizio con il suo deploy successivo. Quando aggiungi un nuovo servizio web o ne rinomini uno, gli altri servizi ricevono la variabile nuova o modificata al loro deploy successivo. Rifai il deploy perché la ricevano, ad esempio con
rivervo deploy <app> --no-build: riavvia la versione in esecuzione con le nuove variabili, senza una nuova build.
Servizi solo interni
Un servizio web che chiamano solo gli altri servizi dell'applicazione (un'API dietro il tuo sito, un backend di amministrazione, un motore di ricerca) non ha bisogno di stare su internet. Impostalo su Solo interno:
| Indirizzo pubblico | Solo interno | |
|---|---|---|
Indirizzo su internet https://<name>.rivervo.app | sì | no |
| I tuoi domini | sì | no |
| Anteprime dei branch | sì | no |
| Indirizzo interno per gli altri servizi | sì | sì |
| Più istanze e scalabilità automatica, log, monitoraggio, controlli di stato | sì | sì |
Un servizio solo interno funziona come qualsiasi altro servizio; solo che lo possono raggiungere soltanto gli altri servizi della stessa applicazione.
Scegliere quando crei un servizio
Quando crei un servizio web, compreso il primo servizio di una nuova applicazione, da un repository, da un modello o da un'immagine pronta, scegli Indirizzo pubblico o Solo interno. Non c'è nulla di preselezionato, quindi la scelta è sempre tua. Worker in background, attività pianificate e database non hanno mai un indirizzo pubblico, quindi per loro non c'è scelta.
I servizi creati prima che esistesse questa scelta mantengono il loro indirizzo pubblico.
Cambiare in seguito
Il servizio → Impostazioni → Indirizzo pubblico: sposta l'interruttore e conferma. Solo un Amministratore dell'applicazione o il proprietario dell'account può cambiarlo. Non si riavvia nulla.
- Il passaggio a solo interno viene rifiutato finché il servizio ha domini collegati: rimuovili prima nella sua scheda Domini. Anche le anteprime vanno disattivate prima.
- Riattivando l'indirizzo pubblico il servizio riprende lo stesso indirizzo
https://<name>.rivervo.app. Per il certificato può servire circa un minuto. - Aggiungere un dominio a un servizio solo interno viene rifiutato: prima attiva il suo indirizzo pubblico.
La scheda Terminale funziona in un servizio solo interno come in qualsiasi altro.
Comunicazione asincrona
Le chiamate viste sopra aspettano una risposta. Quando un servizio deve passare un lavoro e andare avanti (job in background, eventi a cui reagiscono più servizi), invia invece messaggi tramite una coda o un message broker: Valkey, NATS o RabbitMQ. Vedi Eventi e code.
Più istanze
Quando il servizio che chiami gira su più istanze, il suo nome interno porta a tutte le sue istanze in esecuzione e le connessioni vengono distribuite tra loro.
Un client che tiene aperte le connessioni e le riutilizza (un pool di connessioni keep-alive) può continuare a mandare le richieste alla stessa istanza; le nuove connessioni vengono distribuite di nuovo. È normale e non richiede configurazione.
Timeout e nuovi tentativi
Durante un deploy, o quando la scalabilità automatica ferma un'istanza, una richiesta in corso può fallire. Due abitudini rendono affidabili le chiamate tra servizi:
- Un timeout breve, di pochi secondi, così una chiamata non resta mai appesa mentre l'istanza a cui è arrivata si sta fermando.
- Uno o due nuovi tentativi con una breve pausa, per le richieste che si possono ripetere senza rischi, cioè la lettura di dati con
GET. Non ripetere le richieste che modificano dati (pagamenti, ordini), a meno che la tua API non sappia distinguere una richiesta ripetuta da una nuova.
Esempio: Node.js
const api = process.env.RIVERVO_API_URL
async function getWithRetry(url, attempts = 3) {
for (let i = 1; ; i++) {
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5000) })
if (res.status < 500 || i === attempts) return res
} catch (err) {
if (i === attempts) throw err
}
await new Promise((resolve) => setTimeout(resolve, 200 * i))
}
}
const res = await getWithRetry(`${api}/orders`)
const orders = await res.json()Esempio: Laravel
Metti l'indirizzo in config/services.php:
'api' => [
'url' => env('RIVERVO_API_URL'),
],Poi leggilo con config(). In produzione la configurazione è in cache e env() chiamato fuori dai file di configurazione non restituisce nulla:
use Illuminate\Support\Facades\Http;
$orders = Http::timeout(5)
->retry(2, 200)
->get(config('services.api.url').'/orders')
->json();timeout(5) aspetta al massimo 5 secondi; retry(2, 200) fa fino a 2 tentativi con 200 ms tra l'uno e l'altro.
Esempio: Python
import os
import requests
API = os.environ["RIVERVO_API_URL"]
orders = requests.get(f"{API}/orders", timeout=5).json()Con nuovi tentativi per GET:
import os
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
API = os.environ["RIVERVO_API_URL"]
session = requests.Session()
retry = Retry(total=2, backoff_factor=0.2, allowed_methods=["GET"], status_forcelist=[502, 503, 504])
session.mount("http://", HTTPAdapter(max_retries=retry))
orders = session.get(f"{API}/orders", timeout=5).json()Una GET fallita (un errore di connessione o una risposta 502, 503 o 504) viene ripetuta fino a 2 volte, con una breve pausa che cresce ogni volta.
Dalla riga di comando e da Rivervo MCP
rivervo appse i dettagli del servizio mostrano l'indirizzo interno di ogni servizio web e se ha un indirizzo pubblico.rivervo services set-public <service> on|offattiva o disattiva l'indirizzo pubblico. Servono il ruolo di Amministratore e un token con Accesso completo.- In Rivervo MCP la stessa funzione è lo strumento
set_public_address.
Vedi Strumenti per sviluppatori per i token e la riga di comando.