DEV Community

Cover image for O Que É ConnectRPC? O Protocolo Connect
Lucas
Lucas

Posted on • Originally published at apidog.com

O Que É ConnectRPC? O Protocolo Connect

Se você já tentou chamar um serviço gRPC diretamente de um navegador, encontrou a limitação principal: navegadores não conseguem controlar “trailers” HTTP, então não conseguem falar gRPC puro. O caminho tradicional é colocar um proxy, como Envoy, entre o navegador e o backend. O ConnectRPC remove essa etapa ao permitir APIs baseadas em Protobuf que podem ser chamadas por navegadores, por curl e por clientes gRPC.

Experimente o Apidog hoje

Neste guia, você verá o que é o ConnectRPC, qual problema ele resolve, como ele se compara a gRPC, gRPC-Web e REST, como uma requisição Connect funciona via HTTP e como testar endpoints Connect e gRPC com ferramentas comuns de API.

O que é o ConnectRPC

ConnectRPC é uma família de bibliotecas para criar APIs HTTP compatíveis com navegadores e com gRPC usando Protocol Buffers.

O fluxo básico é:

  1. Definir o contrato em um arquivo .proto.
  2. Gerar código com buf.
  3. Implementar os handlers do serviço.
  4. Expor o serviço como handlers HTTP.

O Connect cuida de roteamento, serialização, compressão e geração de clientes.

O projeto foi criado pela Buf, a empresa por trás das ferramentas buf para Protobuf, e hoje é um projeto sandbox da Cloud Native Computing Foundation (CNCF). Isso faz com que o Connect se encaixe bem em fluxos “schema-first” já usados por equipes que trabalham com Protobuf.

Um servidor ConnectRPC pode falar três protocolos ao mesmo tempo:

  • gRPC: compatibilidade com clientes gRPC, incluindo streaming e trailers.
  • gRPC-Web: suporte para clientes gRPC-Web sem exigir um proxy separado.
  • Connect: protocolo HTTP próprio, mais simples de chamar de navegadores e ferramentas HTTP.

Na prática, isso significa que o mesmo backend pode atender:

  • um frontend TypeScript no navegador;
  • um serviço Go usando gRPC;
  • uma chamada manual com curl;
  • uma ferramenta de teste de API.

O problema que o Connect resolve

gRPC é eficiente e fortemente tipado, mas depende de características que não são expostas diretamente ao JavaScript no navegador, especialmente os HTTP trailers.

Por isso, um navegador não consegue atuar como cliente gRPC nativo. A solução comum é usar gRPC-Web junto com um proxy de tradução, como Envoy, entre o frontend e o backend gRPC.

Essa arquitetura funciona, mas adiciona complexidade:

  • mais um componente para configurar;
  • mais um ponto de falha;
  • mais um salto de rede para depurar;
  • mais configuração para ambientes locais, staging e produção.

O Connect usa outra abordagem. O protocolo Connect roda sobre HTTP padrão, então chamadas unárias podem ser feitas diretamente pelo navegador ou por qualquer cliente HTTP.

Você mantém:

  • contrato Protobuf;
  • geração de código;
  • tipagem forte;
  • interoperabilidade com gRPC.

Mas remove a necessidade de proxy apenas para permitir chamadas do navegador.

Connect vs gRPC vs gRPC-Web vs REST

As quatro abordagens resolvem problemas parecidos, mas com trade-offs diferentes.

gRPC

gRPC usa Protobuf sobre HTTP/2, com framing binário e trailers HTTP. É eficiente e suporta os quatro modos de streaming, mas não é simples de chamar diretamente de um navegador ou de um terminal.

Se quiser revisar a camada de transporte, veja como gRPC e HTTP/2 funcionam juntos.

gRPC-Web

gRPC-Web adapta gRPC para navegadores. Ele continua baseado em Protobuf e normalmente é usado com um proxy que traduz o tráfego para um backend gRPC nativo.

Veja também: o que é gRPC-Web.

Connect

Connect mantém o modelo de serviço do gRPC e o contrato Protobuf, mas usa um protocolo HTTP mais simples para chamadas unárias.

Uma chamada Connect pode usar:

  • HTTP/1.1, HTTP/2 ou HTTP/3;
  • corpo JSON ou Protobuf;
  • status HTTP real;
  • caminhos derivados diretamente do schema Protobuf.

Isso torna uma chamada Connect tão fácil de inspecionar quanto uma chamada REST.

REST

REST é orientado a recursos e amplamente suportado. É simples de chamar, depurar e integrar, mas não exige tipagem forte nem geração de código por padrão.

Se você está avaliando os dois modelos, veja gRPC vs REST.

Resumo prático:

  • Use gRPC quando precisar de alto desempenho, streaming completo e controle entre serviços.
  • Use gRPC-Web quando já tiver um backend gRPC e precisar expô-lo para navegadores.
  • Use Connect quando quiser Protobuf, geração de código e chamadas HTTP fáceis de testar.
  • Use REST quando compatibilidade universal e simplicidade forem mais importantes que contratos Protobuf.

O Connect se apoia no modelo de método do Protobuf e do gRPC, mas evita partes que navegadores e shells não conseguem lidar bem.

Como uma requisição Connect funciona via HTTP

Uma chamada unária Connect é um POST HTTP comum.

O caminho da URL vem do schema Protobuf no formato:

/<pacote>.<Serviço>/<Método>
Enter fullscreen mode Exit fullscreen mode

Por exemplo, se você tiver:

  • pacote: greet.v1
  • serviço: GreetService
  • método: Greet

O endpoint será:

/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

Você pode chamar esse método com curl:

curl \
  --header "Content-Type: application/json" \
  --data '{"name": "Jane"}' \
  http://localhost:8080/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

Resposta:

{"greeting": "Hello, Jane!"}
Enter fullscreen mode Exit fullscreen mode

Não há cliente especial, proxy ou decodificação manual. Para chamadas unárias, o corpo pode ser JSON simples.

O Connect suporta dois tipos de conteúdo para requisições unárias:

  • application/json: útil durante desenvolvimento e depuração.
  • application/proto: útil quando você quer payloads binários menores.

Exemplo usando Protobuf binário:

curl \
  --header "Content-Type: application/proto" \
  --data-binary @request.bin \
  http://localhost:8080/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

Chamadas de streaming usam tipos de conteúdo diferentes:

application/connect+proto
application/connect+json
Enter fullscreen mode Exit fullscreen mode

Nesses casos, cada mensagem é encapsulada em um envelope com:

  1. um byte de sinalização;
  2. quatro bytes de comprimento em big-endian;
  3. a mensagem.

Chamadas unárias não usam esse envelope, por isso mapeiam tão bem para HTTP comum.

Se estiver escolhendo entre formatos de payload, veja Protobuf vs JSON.

Exemplo de contrato Protobuf

Um serviço Connect começa com um arquivo .proto.

Exemplo:

syntax = "proto3";

package greet.v1;

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse) {}
}

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  string greeting = 1;
}
Enter fullscreen mode Exit fullscreen mode

A partir desse contrato, você gera:

  • tipos Protobuf;
  • interfaces de servidor;
  • clientes;
  • handlers Connect.

Geração de código com buf

O ConnectRPC oferece implementações em várias linguagens. Go e TypeScript, para navegador e Node.js, são estáveis e prontas para produção. Swift está disponível para plataformas Apple, Kotlin para JVM e Android, e Python está em beta.

A geração de código é feita com a cadeia de ferramentas buf.

Em um projeto Go, você normalmente usa:

  • protoc-gen-go para mensagens Protobuf;
  • protoc-gen-connect-go para handlers e clientes Connect.

Um arquivo buf.gen.yaml lista os plugins usados na geração.

Depois, execute:

buf generate
Enter fullscreen mode Exit fullscreen mode

O resultado inclui estruturas tipadas e código de servidor/cliente.

Em Go, o código gerado integra com net/http, então um handler Connect é um handler HTTP comum. Isso permite montar endpoints Connect ao lado de rotas HTTP existentes.

Testando endpoints Connect com curl

Como chamadas unárias Connect são HTTP simples, comece testando com curl.

Exemplo com JSON:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{"name": "Jane"}' \
  http://localhost:8080/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

Verifique:

  • status HTTP;
  • corpo da resposta;
  • headers;
  • formato do JSON;
  • mensagens de erro.

Essa etapa é útil para validar se o endpoint está acessível antes de integrar o cliente gerado.

Testando e depurando Connect e gRPC com Apidog

No Apidog, você pode testar uma chamada unária Connect como uma requisição HTTP.

Configure:

  • método: POST;
  • URL: http://localhost:8080/greet.v1.GreetService/Greet;
  • header: Content-Type: application/json;
  • body: 
{"name": "Jane"}
Enter fullscreen mode Exit fullscreen mode

Você recebe a resposta JSON e o status HTTP real, da mesma forma que faria com curl, mas com interface visual, histórico e requisições salvas.

Para revisar os verbos HTTP usados nesse tipo de teste, veja o que são métodos HTTP.

Como um servidor Connect também fala gRPC, você pode testar o lado gRPC do mesmo serviço. O Apidog suporta endpoints gRPC: importe o arquivo .proto, navegue pelos métodos disponíveis e envie uma requisição tipada.

Assim, uma única ferramenta cobre:

  • chamadas Connect via HTTP;
  • chamadas gRPC nativas;
  • depuração manual;
  • cenários de teste salvos.

Se o foco for gRPC, veja como testar APIs gRPC de forma eficiente.

Automatizando testes em CI

Depois que as chamadas estiverem funcionando, mova os testes para execução automatizada.

Instale o Apidog CLI com Node:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Execute um cenário ou suíte salvo:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

O CLI roda em modo headless e pode ser usado em pipelines de CI que executam Node.

Use esse fluxo para:

  • validar regressões em endpoints Connect;
  • testar métodos gRPC;
  • gerar relatórios em HTML ou JUnit;
  • bloquear deploys quando cenários críticos falharem.

Para um passo a passo completo, veja o tutorial do Apidog CLI para testar uma API pela linha de comando.

Checklist de implementação

Use este roteiro ao adotar ConnectRPC em um serviço:

  1. Defina o contrato em .proto.
  2. Configure buf e os plugins da linguagem usada.
  3. Rode buf generate.
  4. Implemente os handlers gerados.
  5. Registre os handlers no servidor HTTP.
  6. Teste uma chamada unária com curl.
  7. Teste a mesma chamada em uma ferramenta de API.
  8. Se necessário, valide também o lado gRPC importando o .proto.
  9. Salve cenários de teste.
  10. Execute os testes em CI.

Perguntas frequentes

ConnectRPC é o mesmo que gRPC?

Não. ConnectRPC é um framework que implementa três protocolos: gRPC, gRPC-Web e Connect.

Um servidor Connect pode interoperar com clientes e servidores gRPC, mas o protocolo Connect é um protocolo HTTP separado, projetado para ser chamado diretamente por navegadores e ferramentas HTTP.

Ainda preciso de um proxy como Envoy para alcançar um navegador?

Não para o protocolo Connect.

O Connect funciona sobre HTTP padrão, então um navegador pode chamar um servidor Connect sem proxy de tradução. Você só precisa de um proxy como Envoy se estiver fazendo a ponte entre tráfego de navegador e um backend que fala apenas gRPC nativo.

Quais linguagens o ConnectRPC suporta?

Go e TypeScript, para navegador e Node.js, são estáveis e prontas para produção. Swift, Kotlin e Python também estão disponíveis, com Python em beta.

Todas elas geram código a partir do mesmo schema Protobuf.

Qual é a relação entre Connect e buf?

ConnectRPC foi criado pela Buf e usa a cadeia de ferramentas buf para geração de código.

Você executa:

buf generate
Enter fullscreen mode Exit fullscreen mode

com plugins como protoc-gen-connect-go para gerar handlers e clientes a partir dos arquivos .proto.

Posso testar um endpoint Connect com um cliente de API normal?

Sim. Chamadas unárias Connect são requisições HTTP POST com corpo JSON ou Protobuf e status HTTP real.

Você pode usar curl, Apidog ou qualquer cliente HTTP. O Apidog também pode testar o lado gRPC do mesmo servidor importando o arquivo .proto.

Top comments (0)