Comunicação entre serviços: endereços internos e serviços somente internos.
Como os serviços de uma aplicação se comunicam pelo endereço interno, as variáveis RIVERVO_<NAME>_URL, serviços sem endereço público, várias instâncias, e timeouts e novas tentativas com exemplos em Node.js, Laravel e Python.
Os serviços de uma aplicação conversam entre si diretamente, sem passar pela internet. Um site pode chamar a própria API, um worker pode chamar um serviço interno — e esse tráfego é grátis: ele 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, configurado como Somente interno.
O endereço interno
Todo serviço web — com endereço público ou somente interno — tem um Endereço interno no formato http://<service-name>:<port>, por exemplo http://api:8080. Ele aparece na página do serviço e na Visão geral da aplicação, com um botão de copiar e a dica «Os outros serviços desta aplicação chegam a ele por aqui — sem internet e sem cobrança de tráfego.»
- A porta é 8080 para um serviço criado a partir de um repositório, ou a Porta que você definiu para um serviço de imagem pronta.
- Só os serviços da mesma aplicação chegam a esse endereço. Ele não abre pela internet nem a partir de outras aplicações.
- O endereço usa
http://. A conexão fica dentro da aplicação, então não há certificado para configurar.
Variáveis com os endereços
Você não precisa 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 letras maiúsculas, com os hifens trocados por _:
| 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 (de uma imagem pronta, porta 7700) | RIVERVO_SEARCH_URL=http://search:7700 |
- Um serviço não recebe variável para si mesmo.
- Os bancos de dados e o Valkey mantêm a própria
RIVERVO_<NAME>_URLcom o endereço de conexão. Os nomes de serviço são únicos dentro de uma aplicação, então os nomes nunca entram em conflito. - As variáveis aparecem na aba Variáveis, entre as Definidas automaticamente. Como acontece com qualquer variável automática, uma variável sua (ou uma variável compartilhada) com o mesmo nome toma o lugar dela — veja Variáveis de ambiente.
- As variáveis chegam a um serviço no próximo deploy dele. Quando você adiciona um novo serviço web ou renomeia um, os outros serviços recebem a variável nova ou alterada no próximo deploy. Faça o deploy deles de novo para que a recebam, por exemplo com
rivervo deploy <app> --no-build— isso reinicia a versão em execução com as novas variáveis, sem um novo build.
Serviços somente internos
Um serviço web que só os outros serviços da aplicação chamam — uma API por trás do seu site, um backend de administração, um mecanismo de busca — não precisa estar na internet. Configure-o como Somente interno:
| Endereço público | Somente interno | |
|---|---|---|
Endereço na internet https://<name>.rivervo.app | sim | não |
| Domínios próprios | sim | não |
| Prévias de branches | sim | não |
| Endereço interno para os outros serviços | sim | sim |
| Várias instâncias e escalonamento automático, logs, monitoramento, verificações de saúde | sim | sim |
Um serviço somente interno roda como qualquer outro serviço; só os outros serviços da mesma aplicação chegam até ele.
A escolha ao criar um serviço
Ao criar um serviço web — inclusive 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 Somente interno. Nada vem marcado de antemão, então a escolha é sempre sua. Workers em segundo plano, tarefas agendadas e bancos de dados nunca têm endereço público, então não há escolha para eles.
Os serviços criados antes de essa opção existir mantêm o endereço público.
Como mudar depois
No serviço → Configurações → Endereço público: mude a chave e confirme. Só um Administrador da aplicação ou o titular da conta pode alterar isso. Nada é reiniciado.
- Mudar para somente interno é recusado enquanto o serviço tiver domínios conectados — remova-os antes na aba Domínios dele. As prévias também precisam ser desativadas antes.
- Reativar o endereço público devolve ao serviço o mesmo endereço
https://<name>.rivervo.app. O certificado pode levar cerca de um minuto. - Adicionar um domínio a um serviço somente interno é recusado — ative o endereço público dele primeiro.
A aba Terminal funciona num serviço somente interno do mesmo jeito que em qualquer outro.
Comunicação assíncrona
As chamadas acima esperam uma resposta. Quando um serviço deve entregar um trabalho e seguir em frente — tarefas em segundo plano, eventos aos quais vários serviços reagem —, envie mensagens por uma fila ou por um broker de mensagens: Valkey, NATS ou RabbitMQ. Veja Eventos e filas.
Várias instâncias
Quando o serviço que você chama roda várias instâncias, o nome interno leva a todas as instâncias em execução, e as conexões são distribuídas entre elas.
Um cliente que mantém as conexões abertas e as reutiliza (um pool de conexões keep-alive) pode continuar mandando as requisições para a mesma instância; as conexões novas são distribuídas de novo. Isso é normal e não precisa de configuração.
Timeouts e novas tentativas
Durante um deploy, ou quando o escalonamento automático para uma instância, uma requisição em andamento pode falhar. Dois hábitos deixam as chamadas entre serviços confiáveis:
- Um timeout curto — alguns segundos, para que uma chamada nunca fique travada enquanto a instância que a recebeu está parando.
- Uma ou duas novas tentativas com uma pausa curta, para requisições que podem ser repetidas com segurança — leitura de dados com
GET. Não repita requisições que alteram dados (pagamentos, pedidos), a menos que a sua API saiba distinguir uma requisição repetida de uma nova.
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 arquivos de configuração não retorna 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 entre elas.
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 que falha — erro de conexão ou resposta 502, 503 ou 504 — é repetido até 2 vezes, com uma pausa curta que aumenta a cada vez.
Pela linha de comando e pelo Rivervo MCP
rivervo appse os detalhes do serviço mostram o endereço interno de cada serviço web e se ele tem endereço público.rivervo services set-public <service> on|offliga ou desliga o endereço público. Exige o papel de Administrador e um token com Acesso total.- No Rivervo MCP, a mesma opção é a ferramenta
set_public_address.
Veja Ferramentas para desenvolvedores para tokens e a linha de comando.