API gRPC em tempo real

Este guia é exclusivo para a interface em tempo real do gRPC.

Glossário

• Adapter de entrada — aceita chamadas de protocolo externo e traduz para use-cases.

Responsabilidade no escopo

• Camada: adapter / realtime
• Responsável por: wiring específico deste framework/tecnologia
• Usado com: composição do backend-template, pacotes de persistência/SDK, guia correspondente
• Não responsável por: regras de domínio, autoría OpenAPI ou storage offline no browser

Por que existe

A escolha de framework fica na borda. Este adapter mantém detalhes Express/Fastify/DB/realtime substituíveis.

O que é

Adapter GRPC API para interfaces realtime do Jumentix — monta use-cases sem vazar tipos de framework no domínio.

Escopo

• Transporte: gRPC
• Implementação do servidor: apps/backend-template/src/interface/gRPC/gRPCAPI.ts
• Contrato proto canônico: spec/asyncapi/async-api.proto
• Cliente SDK: sdk-clients/grpc/GrpcApiClient.ts
• Fonte AsyncAPI: spec/asyncapi/1.0.0.grpc.yml

Referências de contrato

• Contratos em tempo real gRPC
• Contratos e respostas de erro
• Mapa de eventos e mensagens

Contrato de serviço

• Nome do serviço: realtime.AsyncApiGateway
• Métodos RPC:
  • Request(AsyncApiRequest) retorna (AsyncApiResponse) (unário)
  • Exchange(stream AsyncApiRequest) retorna (stream AsyncApiResponse) (stream bidirecional)

Fluxo de tempo de execução

Exemplo profundo: solicitação unária

import { GrpcApiClient } from '../sdk-clients/grpc/GrpcApiClient';

const client = new GrpcApiClient('localhost:3002');

const response = await client.request({
  version: '1.0.0',
  operationId: 'createOrganization',
  authorization: 'Bearer <jwt>',
  input: {
    name: 'Acme Group',
    address: [],
    phone: [],
    email: []
  },
  metadata: {
    requestId: 'req-grpc-001',
    correlationId: 'corr-tenant-42'
  }
});

if (!response.ok) {
  console.error(response.error);
} else {
  console.log(response.result);
}

Exemplo profundo: fluxo bidirecional gRPC nativo

import grpc from '@grpc/grpc-js';
import protoLoader from '@grpc/proto-loader';
import { resolveGrpcProtoPath } from '@jumentix/sdk-grpc-client';

const protoPath = resolveGrpcProtoPath();
const packageDefinition = protoLoader.loadSync(protoPath, {
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
});
const grpcObject = grpc.loadPackageDefinition(packageDefinition) as any;
const client = new grpcObject.realtime.AsyncApiGateway(
  'localhost:3002',
  grpc.credentials.createInsecure()
);

const stream = client.exchange();

stream.on('data', (msg: any) => {
  const result = msg.resultJson ? JSON.parse(msg.resultJson) : null;
  console.log('stream response', msg.operationId, result, msg.errorMessage);
});

stream.on('error', (err: Error) => {
  console.error('stream error', err);
});

stream.write({
  version: '1.0.0',
  operationId: 'getAllOrganizations',
  authorization: 'Bearer <jwt>',
  inputJson: JSON.stringify({}),
  paramsJson: JSON.stringify({}),
  queryStringJson: JSON.stringify({ page: 1, size: 20 }),
  metadataJson: JSON.stringify({ requestId: 'stream-1' })
});

stream.end();

Regras de serialização de carga útil

1. Os campos de transporte inputJson, paramsJson, queryStringJson, metadataJson são strings JSON.
2. O servidor mapeia a carga útil de transporte para o envelope de solicitação assíncrona interna.
3. resultJson em resposta deve ser analisado pelos consumidores clientes.
4. errorName e errorMessage fornecem metadados de falha normalizados.

Orientação Operacional

1. Mantenha um cliente por host/porta de serviço para reutilização da conexão.
2. Prefira RPC unário para operações independentes.
3. Use troca de fluxo para lotes de operação de alta frequência.
4. Aplique correlação por solicitação com metadataJson.requestId.

Checklist júnior (“Eu consigo …”)

• Sei quando escolher este adapter
• Consigo iniciá-lo pelo script documentado
• Sei o próximo guia/pacote

Próximo passo

Volte para Começando ou o guia correspondente.