Vai al contenuto

nestjs-amqp

Microservizi NestJS che si parlano su RabbitMQ, con un gateway HTTP e WebSocket davanti.

MITTypeScriptAttivoVersione 3.2.0

A cosa serve

Quando un'applicazione è divisa in tanti servizi piccoli, serve un modo affidabile per farli parlare tra loro e con l'esterno. Con NestJS e RabbitMQ di solito vuol dire scrivere a mano code, exchange, risposte RPC, riconnessioni e un gateway che trasformi le chiamate HTTP in messaggi, con autenticazione e permessi. Abbiamo raccolto tutto questo in nestjs-amqp, una libreria per NestJS 11: ogni servizio si scrive con pochi decoratori, la topologia sta in un file YAML e il gateway si configura invece di scriverlo. La sviluppiamo su GitHub e la pubblichiamo su npm con licenza MIT.

Installazione

npm i @open-rlb/nestjs-amqp

Esempio

import { Injectable } from '@nestjs/common';
import { BrokerAction, BrokerParam } from '@open-rlb/nestjs-amqp';

@Injectable()
export class OrdersService {
  // (topic, action) = ('orders', 'order.create') — unique across the app
  @BrokerAction('orders', 'order.create', 'rpc')
  create(
    @BrokerParam('header', 'X-GTW-AUTH-USERID') userId: string, // one header
    @BrokerParam('body', 'sku') sku: string,                    // one body field
    @BrokerParam('body-full') payload: any,                     // whole body
    @BrokerParam('action') action: string,                      // the action string
  ) {
    return { ok: true, userId, sku, action };
  }
}

Cosa fa

Decoratori e un file YAML

Un metodo con @BrokerAction diventa un'azione su RabbitMQ, da chiamare in RPC o come evento: la libreria lo trova all'avvio e lo collega alla sua coda. Exchange, code, topic e rotte si dichiarano in un file YAML, e all'avvio la libreria crea o verifica exchange, code e binding.

Gateway HTTP e WebSocket

Ogni rotta HTTP porta a un'azione sul broker, e gli errori dei servizi tornano con lo status giusto (400, 401, 403, 404, 500). Gli eventi del broker arrivano ai client WebSocket o a un webhook, anche con più istanze del gateway.

Accessi e permessi

Ogni rotta e ogni evento può chiedere un token JWT o JWKS: il gateway lo verifica e passa i dati dell'utente ai servizi in header che la richiesta non può sovrascrivere. Un modulo ACL facoltativo decide quali azioni ha un utente su una risorsa, e gli eventi WebSocket si possono limitare ai dati di chi li riceve.

Quando qualcosa va storto

Un messaggio che fallisce ha al massimo 5 tentativi (il valore predefinito), poi può finire in una coda dead-letter invece di girare all'infinito. Le pubblicazioni aspettano la conferma del broker, la connessione si riapre da sola e allo spegnimento il servizio smette di ricevere e finisce il lavoro in corso, con un limite di 25 secondi.

Rotte che si aggiornano da sole

All'avvio un servizio può annunciare le sue rotte HTTP: il gateway applica solo le differenze, le annota in un registro e le ricarica senza riavvio. Un modulo facoltativo tiene rotte e autenticazioni in un database, con le metriche delle richieste e una sonda /health.

Pronta con un comando

Il comando nest add @open-rlb/nestjs-amqp prepara AppModule, main.ts e config.yaml, con o senza gateway, e copia nel progetto sette skill per Claude Code che aiutano ad aggiungere azioni, rotte, eventi e permessi. Altri 16 schematic cambiano la configurazione un pezzo alla volta: una rotta, un topic, una coda, la riprova.

Requisiti

  • NestJS 11
  • Un server RabbitMQ raggiungibile
  • Nel progetto anche @nestjs/config, @nestjs/axios e js-yaml; @nestjs/platform-ws se si usa il gateway
  • Per i moduli ACL e gateway-admin, un database e una cache a scelta, collegati dall'applicazione (gli esempi usano MongoDB o la memoria)

Codice, versioni e segnalazioni stanno su GitHub.