home / skills / hoangnguyen0403 / agent-skills-standard / transport

transport skill

safe

This skill helps you design and enforce NestJS microservices patterns with gRPC, RabbitMQ, and mono-repo contracts for scalable, contract-first architectures.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill transport

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.7 KB

---
name: NestJS Microservices
description: gRPC, RabbitMQ standards and Monorepo contracts.
metadata:
  labels: [nestjs, microservices, grpc, rabbitmq]
  triggers:
    files: ['main.ts', '**/*.controller.ts']
    keywords: [Transport.GRPC, Transport.RMQ, MicroserviceOptions]
---

# Microservices & Transport Standards

## **Priority: P0 (FOUNDATIONAL)**

Microservices communication patterns and transport layer standards.

- **Synchronous (RPC)**: Use **gRPC** for low-latency, internal service-to-service calls.
  - **Why**: 10x faster than REST/JSON, centralized `.proto` contracts.
- **Asynchronous (Events)**: Use **RabbitMQ** or **Kafka** for decoupling domains.
  - **Pattern**: Fire-and-forget (`emit()`) for side effects (e.g., "UserCreated" -> "SendEmail").

## Monorepo Architecture

- **Contracts**:
  - **Pattern**: Store all DTOs, `.proto` files, and Interfaces in a **Shared Library** (`libs/contracts`).
  - **Rule**: Services never import code from other services. They only import from `contracts`.
- **Versioning**: Semantic versioning of messages is mandatory. Never change a field type; add a new field.

## Exception Handling

- **Propagation**: Standard `HttpException` is lost over Rpc/Tcp.
- **Standard**: Use `RpcException` and generic Filters.

  ```typescript
  // Global RPC Filter
  @Catch()
  export class RpcExceptionFilter implements RpcExceptionFilter<RpcException> {
    catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
      return throwError(() => exception.getError());
    }
  }
  ```

## Serialization

- **Message DTOs**: Use `class-validator` just like HTTP.
  - **Config**: Apply `useGlobalPipes(new ValidationPipe({ transform: true }))` in the `MicroserviceOptions` setup, not just HTTP app setup.

Overview

This skill codifies NestJS microservice standards for gRPC, RabbitMQ, and monorepo contracts. It focuses on reliable transport choices, shared contract management, validation, and error propagation across RPC boundaries. Use it to align teams on fast internal RPC, event-driven decoupling, and safe schema evolution.

How this skill works

The skill prescribes gRPC for synchronous, low-latency service-to-service RPC and RabbitMQ/Kafka for asynchronous event flows. It enforces a shared contracts library for DTOs, .proto files, and interfaces so services never import each other directly. It also defines global RPC exception filters and validation plumbing to preserve errors and payload integrity across transports.

When to use it

Internal low-latency calls between services requiring strong typing and performance (use gRPC).
Domain decoupling, eventual consistency, and side effects (use RabbitMQ or Kafka events).
Monorepo setups where multiple services must share message contracts and DTOs.
When you need consistent validation and transformation on microservice messages, not just HTTP.
When you require predictable message versioning and backward compatibility.

Best practices

Keep all DTOs, .proto files, and interfaces in a single shared library (e.g., libs/contracts).
Services must import only from contracts; never import code from another service.
Prefer gRPC for synchronous internal RPC—centralize .proto contracts and follow semantic versioning for messages.
Use RabbitMQ/Kafka for fire-and-forget events; emit events for side effects (e.g., UserCreated -> SendEmail).
Apply global validation for microservices: useGlobalPipes(new ValidationPipe({ transform: true })) in MicroserviceOptions.
Handle errors with RpcException and a global RPC filter so exceptions propagate predictably across transports.

Example use cases

Authentication service exposes gRPC methods for token issuance while publishing UserCreated events to RabbitMQ.
Order service subscribes to inventory events; uses shared contract DTOs from libs/contracts to deserialize messages.
Payment microservice uses gRPC for synchronous charge validation and emits PaymentCompleted events for downstream processing.
Legacy REST endpoints interoperate with new services using adapters that translate REST to gRPC or event messages, preserving contracts.

FAQ

Why use gRPC instead of REST/JSON internally?

gRPC offers much lower latency and stronger typing via .proto contracts, improving performance and interoperability for internal calls.

How should I evolve message schemas?

Follow semantic versioning: never change field types in-place. Add new fields with default behavior and increment contract versions so consumers can remain compatible.