gRPC

Exemplo em Node gRPC

Exemplo da criação de um Pact entre:

• 1 consumidor (account-api)
• 1 provedor (client-api)

Ferramentas

• Node + npm
• Express
• Typescript
• Pact
• Pact Broker
• grpc-js
• Jest

Índice

• Cenário
• Compatibilidade com gRPC
  • Solução no lado do Consumidor
  • Solução no lado do Provedor
• Mas se o gRPC já é uma espécie de contrato, porque preciso do PACT?
• Como executar

Cenário

Este exemplo aborda um cenário comum no setor bancário. Nosso objetivo é obter o dado de saldo de determinado cliente. Para isto, vamos considerar que este dado será recuperado da seguinte forma:

1 - Com o identificador do cliente, solicitamos ao serviço de dominio do cliente (client-api) o valor do saldo em conta.
2 - Por sua vez, o client-api pergunta ao serviço de domínio da conta (account-api) qual o saldo contido na conta atrelada aquele cliente.
3 - Tendo a informação do saldo em conta, o client-api retorna a informação a quem a solicitou.

De forma resumida, temos os seguintes serviços:

• account-api: mantém e gerencia informações relacionadas a contas bancárias.
• client-api: mantém e gerencia informações sobre clientes/correntistas.

A imagem abaixo representa esta interação que acabamos de definir.

Compatibilidade com gRPC

Atualmente, o Pact suporta cenários de integração via REST, Mensageria e GraphQL. No entanto, como podemos ver no roadmap do framework, o suporte oficial para gRPC já está planejado. Enquanto esperamos este novo recurso, preparamos uma solução para que você possa iniciar seus testes desde já, de forma que seja fácil migrar para uma solução definitiva no futuro.

De forma bastante resumida, esta solução define padrões para representarmos cada parte do contrato gRPC em REST, possibilitando assim a validação dos contratos. A seguir explicamos a solução de forma mais detalhada.

Como dizemos acima, hoje o Pact não tem suporte para protocolo gRPC, mas e se conseguissemos transformar, ou representar, esta chamada em outro protocolo que o Pact entenda (ex: REST) ? É exatamente esta a abordagem adotada aqui.

• Solução no lado do Consumidor

Quando uma chamada é feita no lado do consumidor, assim como em frameworks REST, o gRPC nos possibilita interceptá-la através da definição de um Interceptor. Desta forma, conseguimos obter informações destas chamadas, incluindo dados definidos no protofile, como package, service e method. A partir destas informações conseguimos montar uma chamada REST, baseado na seguinte convenção:

POST http://{{address}}/grpc/{{packagaName}}.{{service}}/{{method}}

Tendo gerado então esta chamada REST, conseguimos seguir o fluxo de teste do Pact no lado do consumidor. Para maiores detalhes sobre a implementação dos testes, vide o arquivo de teste em client-api/src/tests/pact.spec.ts.

• Solução no lado do Provedor

De forma análoga a solução proposta no lado do Consumidor, no lado do Provedor precisamos fazer a tradução entre a chamada gRPC e REST, mas de forma inversa (REST > gRPC). Para isto, precisamos criar um servidor REST como proxy, que escute as chamadas que definimos no lado do consumidor e as encaminhe para o servidor gRPC. Neste caso utilizamos Express para criar implementarmos este proxy seguindo a convenção definida anteriormente. Para maiores detalhes sobre a implementação dos testes, vide o arquivo de teste em account-api/src/tests/verify-pact.spec.ts.

A imagem a seguir representa esta solução:

Mas se o gRPC já é uma espécie de contrato, porque preciso do PACT?

Como em muitos sistemas RPC, o gRPC é baseado na ideia de definir um serviço, especificando os métodos que podem ser chamados remotamente com seus parâmetros e tipos de retorno. No lado do servidor, o servidor implementa esse contrato (interface) e executa um servidor gRPC para lidar com as chamadas do cliente. Entretanto, devemos observar pontos que podem levar a quebra de integrações, por exemplo:

• Redefinir tipo de atributo - ao alterar o tipo de um atributo, por exemplo, de int32 para double no arquivo .proto, o provedor do serviço continuará funcionando, porém se o consumidor não receber essa alteração, haverá quebra na comunicação, esse tipo de alteração é identificado pelo PACT realizando o teste de contrato preventivamente.

• Renomear um pacote, serviço ou método - o gRPC usa o nome do pacote, o nome do serviço e o nome do método para criar a URL, caso algum desses itens sejam modificados sem a devida comunicação aos consumidores do serviço, haverá uma quebra de integração, esse tipo de alteração também é identificado pelo PACT realizando o teste de contrato preventivamente.

• Removendo um serviço ou método - haverá quebra de integração pois o cliente tentará acessar um recurso inexistente, esse tipo de alteração também é identificado pelo PACT realizando o teste de contrato preventivamente.

Como executar

Aqui, temos o passo a passo para conseguirmos averiguar o cenário acima.

1. Garanta que você tenha uma instância do Pact Broker rodando localmente. Vide sessão configuração do Pact Broker caso tenha dúvida.

2. Com o Broker funcionando, podemos iniciar os testes. Primeiro, precisamos instalar as dependencias da API. Para isto, va até o diretório client-api e execute o seguinte comando:

npm install

Em seguida, precisamos gerar o contrato do PACT para a nossa API consumidora e o publicamos no Broker.
No mesmo diretório, execute os seguintes comandos:

npm run test

npm run pact:publish

Acesse o Pact Broker (http://localhost:9292) em seu navegador. Você deverá ver o contrato publicado.

Caso tenha interesse, o contrato gerado pode ser conferido no diretório client-api/pacts.

3. Para validar o contrato gerado, vamos até o diretório da nossa API provedora (provider) account-api. Novamente, precisamos instalar as dependencias da API. Para isto, execute o seguinte comando:

npm install

Para testarmos o contrato com a API consumidora, precisamos apenas rodar o teste da API. Para isto, execute:

npm run test

Este teste irá verificar no Broker os contratos disponiveis para validação, baixá-los e testá-los de acordo com a API. Ao final, podemos conferir o resultado do teste que é publicado no Broker.