Começar

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.

6 MIN DE LEITURA

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çoVariável
apiRIVERVO_API_URL=http://api:8080
admin-apiRIVERVO_ADMIN_API_URL=http://admin-api:8080
webRIVERVO_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>_URL com 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úblicoSomente interno
Endereço na internet https://<name>.rivervo.appsimnão
Domínios própriossimnão
Prévias de branchessimnão
Endereço interno para os outros serviçossimsim
Várias instâncias e escalonamento automático, logs, monitoramento, verificações de saúdesimsim

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 apps e 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|off liga 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.

Ainda com dúvidas?

Fale com a gente no chat — a AI responde na hora e um engenheiro entra quando é preciso, a qualquer hora do dia.

Falar com o suporte