Começar

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.

6 MIN DE LEITURA

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çoVariável
apiRIVERVO_API_URL=http://api:8080
admin-apiRIVERVO_ADMIN_API_URL=http://admin-api:8080
webRIVERVO_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>_URL com 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úblicoApenas interno
Endereço na internet https://<name>.rivervo.appsimnão
Os seus próprios domíniossimnão
Pré-visualizações de branchessimnão
Endereço interno para os outros serviçossimsim
Várias instâncias e escala automática, logs, monitorização, verificações de estadosimsim

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

Ainda com dúvidas?

Fale connosco por chat — a AI responde de imediato e um engenheiro entra quando for preciso, a qualquer hora.

Contactar o suporte