@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

Carrega o arquivo de configuração (ex.: docker-compose.env) compartilhado entre todos os serviços e disponibiliza uma biblioteca de configuração com os valores de ambientes do serviço.

• 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-nclabs-rpc-module/blob/main/config.md

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

environment:
  SERVICE_NAME: <your-service-name>

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
NclabsAction	Decorator	Controller	Configura requisições RPC e HTTP (opcional)
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
NclabsRxjsErrorHandler	Lib	Observable Approach	Trata exceções do microserviço (catchError)
NclabsException	Lib	Promise Approach	Trata exceções do microserviço
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 {

  ...

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

  ...

• 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)
  

• HTTP: A configuração rest do decorator irá disponibilizar 1 rotas de acesso HTTP para cada method:

  - GET /your-path
  - POST /your-path
  

• CACHE: A configuração cache irá disponibilizar um 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, o nome da ação 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>.<action_name>.<key 1>.<key 2>.<key 3>
  

    // Exemplo:
  
    // SERVICE_NAME = senior-auth
  
    @NclabsAction({
      name: 'user-credential',
      cache: {
        keys: [
          '#headers.authorization',  // value from context.headers
          '#data.id',                // value from context.data
          'some-key'                 // static value
        ],
        ttl: 1200,                   // seconds
      },
    })
  
    ...
  
  

  No código exemplo, chave do cache será algo assim:
  
  senior-auth.user-credential.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 (handler, subject e cadeia de chamadas)
    // headers: Header do request
    // params:  Path parameters do request
    // data:    Body do request mesclado com os query parameters

    return;
  }

  ...

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

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

...

@Controller()
// ou
@Injectable()

  ...


  /**
   * 
   * 
   */ 
  youMethod(token: string, includeG5 = false): Observable<IUser> {

    const url = `${baseUrl}platform/user/queries/getUser`;

    const headers = {
      Authorization: `Bearer ${token}`,
    };

    return this.httpService.get<IUser>(url, { headers }).pipe(
      // get data
      map((response: AxiosResponse<IUser>) => response.data),
      // append authentication
      map((data: IUser) => ({ ...data, authentication: `Bearer ${token}` })),
      // map response to IUser
      map(this._mapResponseToIUser),
      // generate password for G5
      map((user: IUser) => {
        if (includeG5) {
          const password = this._generateEncryptPassword(user.username);
          user.password = password;
          user.encryption = 2;
        }
        return user;
      }),
      catchError(NclabsRxjsErrorHandler),
    );
  }


  /**
   * 
   *  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 NclabsException(error);
    }

    // do something

    return encryptedPassword;
  }

  ...