Comunicação entre serviços: endereços internos e serviços apenas internos.
Como os serviços de uma aplicação comunicam entre si pelo endereço interno, as variáveis RIVERVO_<NAME>_URL, os serviços sem endereço público, as várias instâncias, e tempos limite e novas tentativas com exemplos para Node.js, Laravel e Python.
Os serviços de uma aplicação comunicam diretamente entre si, sem passar pela internet. Um site pode chamar a sua própria API, um worker pode chamar um serviço interno — e este tráfego é gratuito: não conta como tráfego.
Os exemplos abaixo usam dois serviços web: web, o site que os visitantes abrem, com Endereço público, e api, que só o web e os outros serviços chamam, definido como Apenas interno.
O endereço interno
Cada serviço web — com endereço público ou apenas interno — tem um Endereço interno no formato http://<service-name>:<port>, por exemplo http://api:8080. Aparece na página do serviço e na Visão geral da aplicação, com um botão para copiar e a indicação «Os outros serviços desta aplicação acedem-lhe por aqui — sem internet e sem custos de tráfego.»
- A porta é 8080 num serviço compilado a partir de um repositório, ou a Porta que definiu num serviço a partir de uma imagem pronta.
- Só os serviços da mesma aplicação chegam a este endereço. Não abre a partir da internet nem de outras aplicações.
- O endereço usa
http://. A ligação fica dentro da aplicação, por isso não há certificado para configurar.
Variáveis com os endereços
Não precisa de copiar os endereços para o código. Cada serviço de código da aplicação — serviços web, workers em segundo plano e tarefas agendadas — recebe uma variável com o endereço interno de cada um dos outros serviços web da aplicação:
RIVERVO_<NAME>_URL=http://<name>:<port>
NAME é o nome do serviço em maiúsculas, com os hífenes transformados em _:
| Serviço | Variável |
|---|---|
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 (a partir de uma imagem pronta, porta 7700) | RIVERVO_SEARCH_URL=http://search:7700 |
- Um serviço não recebe uma variável para si próprio.
- As bases de dados e o Valkey mantêm o seu próprio
RIVERVO_<NAME>_URLcom o endereço de ligação. Os nomes dos serviços são únicos dentro de uma aplicação, por isso os nomes nunca entram em conflito. - As variáveis aparecem no separador Variáveis, entre as variáveis Definidas automaticamente. Como em todas as variáveis automáticas, uma variável sua (ou uma variável partilhada) com o mesmo nome substitui-a — consulte Variáveis de ambiente.
- As variáveis chegam a um serviço na publicação seguinte. Quando adiciona um novo serviço web ou muda o nome de um, os outros serviços recebem a variável nova ou alterada na publicação seguinte. Volte a publicá-los para que a recebam, por exemplo com
rivervo deploy <app> --no-build— arranca de novo a versão em execução com as novas variáveis, sem nova compilação.
Serviços apenas internos
Um serviço web que só é chamado por outros serviços da aplicação — uma API por trás do seu site, um backend de administração, um motor de pesquisa — não precisa de estar na internet. Defina-o como Apenas interno:
| Endereço público | Apenas interno | |
|---|---|---|
Endereço na internet https://<name>.rivervo.app | sim | não |
| Os seus próprios domínios | sim | não |
| Pré-visualizações de branches | sim | não |
| Endereço interno para os outros serviços | sim | sim |
| Várias instâncias e escala automática, logs, monitorização, verificações de estado | sim | sim |
Um serviço apenas interno funciona como qualquer outro serviço; só os outros serviços da mesma aplicação chegam até ele.
Escolher ao criar um serviço
Ao criar um serviço web — incluindo o primeiro serviço de uma nova aplicação, a partir de um repositório, de um modelo ou de uma imagem pronta — escolha Endereço público ou Apenas interno. Nada vem selecionado à partida, por isso a escolha é sempre sua. Os workers em segundo plano, as tarefas agendadas e as bases de dados nunca têm endereço público, por isso não há escolha para eles.
Os serviços criados antes de existir esta opção mantêm o endereço público.
Mudar mais tarde
No serviço → Definições → Endereço público: mude o interruptor e confirme. Só um Administrador da aplicação ou o titular da conta pode fazer esta alteração. Nada é reiniciado.
- Passar a apenas interno é recusado enquanto o serviço tiver domínios ligados — remova-os primeiro no separador Domínios do serviço. As pré-visualizações também têm de ser desativadas antes.
- Voltar a ativar o endereço público dá ao serviço o mesmo endereço
https://<name>.rivervo.app. O certificado pode demorar cerca de um minuto. - Adicionar um domínio a um serviço apenas interno é recusado — ative primeiro o endereço público.
O separador Terminal funciona num serviço apenas interno da mesma forma que em qualquer outro.
Comunicação assíncrona
As chamadas acima esperam por uma resposta. Quando um serviço deve entregar trabalho e seguir em frente — tarefas em segundo plano, eventos a que vários serviços reagem — envie antes mensagens através de uma fila ou de um message broker: Valkey, NATS ou RabbitMQ. Consulte Eventos e filas.
Várias instâncias
Quando o serviço que chama corre em várias instâncias, o nome interno leva a todas as instâncias em execução e as ligações são distribuídas por elas.
Um cliente que mantém as ligações abertas e as reutiliza (um pool de ligações keep-alive) pode continuar a enviar os pedidos para a mesma instância; as novas ligações voltam a ser distribuídas. Isto é normal e não precisa de configuração.
Tempos limite e novas tentativas
Durante uma publicação, ou quando a escala automática para uma instância, um pedido em curso pode falhar. Dois hábitos tornam fiáveis as chamadas entre serviços:
- Um tempo limite curto — alguns segundos, para que uma chamada nunca fique pendurada enquanto a instância a que chegou está a parar.
- Uma ou duas novas tentativas com uma pausa curta, nos pedidos que podem ser repetidos sem risco — ler dados com
GET. Não repita pedidos que alteram dados (pagamentos, encomendas), a não ser que a sua API saiba distinguir um pedido repetido de um novo.
Exemplo: 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()Exemplo: Laravel
Coloque o endereço em config/services.php:
'api' => [
'url' => env('RIVERVO_API_URL'),
],Depois leia-o com config(). Em produção a configuração fica em cache, e env() chamado fora dos ficheiros de configuração não devolve nada:
use Illuminate\Support\Facades\Http;
$orders = Http::timeout(5)
->retry(2, 200)
->get(config('services.api.url').'/orders')
->json();timeout(5) espera no máximo 5 segundos; retry(2, 200) faz até 2 tentativas com 200 ms de intervalo.
Exemplo: Python
import os
import requests
API = os.environ["RIVERVO_API_URL"]
orders = requests.get(f"{API}/orders", timeout=5).json()Com novas tentativas para 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()Um GET falhado — um erro de ligação ou uma resposta 502, 503 ou 504 — é repetido até 2 vezes, com uma pausa curta que aumenta de cada vez.
A partir da linha de comandos e do Rivervo MCP
rivervo appse os detalhes do serviço mostram o endereço interno de cada serviço web e se tem endereço público.rivervo services set-public <service> on|offativa ou desativa o endereço público. Exige a função de Administrador e um token com Acesso total.- No Rivervo MCP, a mesma opção é a ferramenta
set_public_address.
Consulte Ferramentas para programadores para os tokens e a linha de comandos.