@nclabs/nestjs-rpc-module

nestjs-nclabs-rpc-module

Utilitário NestJS para configuração de rotas e cache em microsserviços. Utilizado especificamente para projetos nclabs

Instalação

npm i @nclabs/nestjs-rpc-module

Configuração

Carregar o arquivo de configuração (ex.: docker-compose.env) compartilhado entre todos os serviços.

• As váriáveis descritas no arquivo de configuração são carregadas e tratadas pela biblioteca de configuração.

• Todas as variáveis de ambiente são expostas com seu nome original no atributo env da biblioteca de configuração.

Arquivo de configuração modelo: https://github.com/nclabs-npm/nestjs-nc-template/blob/main/dist/docker-compose.env

Variável de ambiente que DEVE ser setada no docker-compose.yml:

environment:
  SERVICE_NAME: <your-service-name>

Variáveis de ambiente que PODEM ser setada no docker-compose.yml:

environment:
  ...
  # Gerar log de repostas com sucesso
  LOG_RESPONSE=<true | false>

  # Nível de log dos erros
  LOG_ERROR_LEVEL=<debug | info | warn | error | fatal>

Modulo

// app.module.ts

...
import { NclabsRpcModule } from '@nclabs/rpc-module';

@Module({
  imports: [    
    // ...
    NclabsRpcModule.register({ 
      autoInterceptCache: true,   // true ou false: default true
      }),
    // ...
  ],
  // ...
})
export class AppModule {}

Recursos

Recurso	Tipo	Uso	Observação
NclabsConfig	Lib	*	Disponibiliza todas as váriaveis de ambiente
NclabsHttp	Decorator	Controller	Configura requisições HTTP
NclabsAction	Decorator	Controller	Configura requisições RPC
NclabsEvent	Decorator	Controller	Configura envio de eventos RPC
NclabsCtx	Decorator	Controller	Acessa informações do contexto do microserviço
NclabsContext	Interface	*	Tipo de contexto do microserviço
NclabsRpcClientService	Provider	Controller Service	Métodos para requisição de microserviços externos (RPC conf)
NclabsCacherService	Provider	Controller Service	Métodos para o tratamento manual do cache
INclabsException	Interface	*	Tipo de exceção do microserviço

NclabsConfig

const config = NclabsConfig.load();

console.log(config.service);
console.log(config.g5.baseUrl);

console.log(config.env.get('SERVICE_NAME'));
console.log(config.env.get('G5_BASE_URL'));

Controller - Method Configuration

// app.controller.ts

...

@Controller()
export class AppController {

  ...

  /**
   *    HTTP REQUEST
   */
  @NclabsAction({
    path: 'your-path/:id',
    methods: ['GET', 'POST'],
    cache: {
      keys: ['#headers.authorization', '#data.id', 'some-key'],
      ttl: 1200, // seconds
    },
  })
  youRpcMethodName(@NclabsCtx() context: NclabsContext) {
    // Do something
    return;
  }

  /**
   *    RPC CALL 
   */
  @NclabsAction({
    name: 'your-action-name',
    cache: {
      keys: ['#headers.authorization', '#params.id', 'some-key'],
      ttl: 1200, // seconds
    },
  })
  youRpcMethodName(@NclabsCtx() context: NclabsContext) {
    // Do something
    return;
  }

  ...

HTTP REQUEST:

Registra a rota definida em path para os métodos indicados em methods. Quando o parâmetro methods não for informado, todos os métodos são permitidos.

No Exemplo acima:

• GET /your-path/:id
• POST /your-path/:id

RPC:

O método poderá ser requisitado pelo padrão service.name

Onde:

  - service = SERVICE_NAME  (definido no environment do docker compose)
  - name    = your-action-name (configurado no decorator do método)

CACHE:

O atributo cache disponibiliza párâmetros de configuração do cache para o retorno da requisição com as chaves especificadas no keys e com o TTL especificado no ttl.

O cacher gera a chave do cache com base no serviço, protocolo (HTTP/RCP), nome do método e as chaves especificadas no keys. Que aceita valores estaticos, variáveis previamente carregadas (lembrando que o NestJs carrega os decorator antes de instanciar os módulos) e variáveis do contexto que poderão ser acessadas através do prefixo # sendo possível utilizar qualquer atributo de retorno do contexto.

A sintaxe da chave é:

<SERVICE_NAME>:-.<key 1>.<key 2>.<key 3>

  // Exemplo:

  // SERVICE_NAME = senior-auth

  @NclabsHttp({
    path: '/user-credential:id',
    methods: ['GET'],
    cache: {
      keys: [
        '#headers.authorization',  // value from context.headers
        '#params.id',              // value from context.params
        'some-key'                 // static value
      ],
      ttl: 1200,                   // seconds
    },
  })
  getUserCredential(...) {
    
  }

  ...

A chave gerada para o cache será algo assim:

senior-auth:http-get-getUserCredential.Bearer A8DA9S8Asc8ca9sud0c0sgh.123.some-key

**** IMPORTANTE ****

Os decorator são processados antes da instanciação dos módulos e,
portanto, serviços injetados e providers não estão disponíveis.

Se precisar de variáveis de ambiente para compor a chave do cache,
é necessário utilizar o o acesso através da classe de configuração
`NclabsConfig.load()`.

Contexto

// app.controller.ts
// app.service.ts

...

@Controller()

  ...

  youMethod(@NclabsCtx() context: NclabsContext) {

    const { meta, headers, params, data } = context;

    // meta:    Informações do microserviço 
    // headers: Header do request
    // params:  Path parameters do request
    // data:    Request (Body and Query parameters)

    return;
  }

  ...

   👉      context.params somente terá valores nas requisições HTTP. Levar em consideração as possíveis chamadas RPC.

Client Service

// app.controller.ts
// app.service.ts

...

@Controller()
// ou
@Injectable()

  ...

  constructor(
    private readonly clientRpc: NclabsRpcClientService,
  ) {}

  ...

  /**
   *    CALL - Observable Approach
   */ 
  yourMethod(@NclabsCtx() context: NclabsContext): Observable<Person> {
    
    const payload = { 
      name: context.data.name
    }; 

    return this.clientRpc.call('other-service.action', payload, context); 
  }

  /**
   *    CALL- Promise Approach
   */ 
  async yourAsyncMethod(@NclabsCtx() context: NclabsContext): Promise<Person> {
    
    const payload = { 
      name: context.data.name
    }; 

    const person = await this.clientRpc.callAsync('person.create', payload, context);

    // do something

    return person; 
  }


  /**
   *    CALL with event emitter
   */ 
  otherMethod(@NclabsCtx() context: NclabsContext): Observable<Person> {
    
    const payload = { 
      name: context.data.name
    }; 

    return this.clientRpc.call('person.create', payload, context).pipe(
      // Emit event
      tap((data: Person) => this.clientRpc.emit('person-created', data)),
    ); 
  }


  ...

Exceptions

AS requisições REST e chamadas de serviço (...client.call) abstraem a normalização do objeto de exceções.

Quando for necessário lançar exceções manualmente, utilizar a sintaxe abaixo:

// app.controller.ts
// app.service.ts

...

@Controller()
// ou
@Injectable()

  ...

  /**
   * 
   *  Generate password for G5
   * 
   */
  private _generateEncryptPassword(username: string): string {

    // create/get password

    if (!password || password === 'null') {
      const error = {
        code: 401,
        type: 'UNAUTHORIZED',
        message: 'Não foi possível gerar a senha encriptada do Senior G5',
        error: {
          jar: 'crypt.jar',
          encrypt: 'CBC',
          user: username,
          date: dt.toLocaleString('pt-BR', options).replace(',', ''),
        },
      };

      throw new RpcException(error);
    }

    // do something

    return encryptedPassword;
  }

  ...