Copy page

Microservices

NATS Messaging Layer

NATS Messaging Layer

Relevant source files

The following files were used as context for generating this wiki page:

• emailsender/src/nats/client.ts
• emailsender/src/nats/handlers.ts
• emailsender/src/nats/types.ts

The NATS Messaging Layer serves as the primary communication backbone for the EmailSender microservice. It facilitates an asynchronous request/response pattern for dispatching emails and provides the infrastructure for JetStream-based persistence. The implementation leverages the nats library to handle high-performance messaging between microservices.

Messaging Architecture

The EmailSender service operates as a consumer of messages published to specific subjects. It follows a decoupled architecture where the requester does not wait for a synchronous HTTP response but instead listens for a correlated response on a dedicated subject.

Request/Response Flow

1. Subscription: The service subscribes to emailsender.send emailsender/src/nats/handlers.ts:5-12.
2. Request: An external service publishes a SendEmailRequest to that subject.
3. Processing: The subscribeToEmailSendRequests function iterates over the message stream, decodes the payload, and invokes the business logic handler emailsender/src/nats/handlers.ts:16-21.
4. Response: After processing, the service publishes a SendEmailResponse to a specific response subject: emailsender.response.{requestId} emailsender/src/nats/handlers.ts:24-27.

Data Flow Diagram

The following diagram illustrates the interaction between the NATS Server, the handlers.ts logic, and the core EmailService.

NATS Message Flow

Code
sequenceDiagram
    participant Requester as "External Service"
    participant NATS as "NATS Server"
    participant Handlers as "nats/handlers.ts"
    participant EmailService as "EmailService (Logic)"

    Handlers->>NATS: subscribe("emailsender.send")
    Requester->>NATS: publish("emailsender.send", SendEmailRequest)
    NATS->>Handlers: Delivery (Msg)
    Handlers->>EmailService: handleSendEmail(request)
    EmailService-->>Handlers: SendEmailResponse
    Handlers->>NATS: publish("emailsender.response." + requestId, SendEmailResponse)
    NATS-->>Requester: Response Delivery

Sources: emailsender/src/nats/handlers.ts:5-27, emailsender/src/nats/types.ts:1-20

Client Initialization & JetStream

The connection management is centralized in client.ts. It maintains singleton instances of the NATS connection and the JetStream client to ensure resource efficiency.

Connection Management

The getNatsConnection() function initializes the connection using the NATS_URL environment variable (defaulting to nats://127.0.0.1:4222) emailsender/src/nats/client.ts:9-10. Once connected, it initializes the JetStream client via nc.jetstream() emailsender/src/nats/client.ts:11.

Key Entities in client.ts

Entity	Type	Description
nc	NatsConnection	Singleton NATS connection instance emailsender/src/nats/client.ts:3.
js	JetStreamClient	Singleton JetStream client for persistent messaging emailsender/src/nats/client.ts:4.
getNatsConnection	Function	Asynchronous getter that connects if no instance exists emailsender/src/nats/client.ts:6-15.
getJetStream	Function	Returns the JetStream client; throws if NATS is not yet connected emailsender/src/nats/client.ts:17-22.

NATS Client Initialization

Code
graph TD
    subgraph "client.ts"
        A["getNatsConnection()"] --> B{"nc exists?"}
        B -- "No" --> C["connect(process.env.NATS_URL)"]
        C --> D["nc.jetstream()"]
        D --> E["Store nc & js"]
        B -- "Yes" --> F["Return nc"]
    end
    
    subgraph "handlers.ts"
        G["subscribeToEmailSendRequests()"] --> A
    end

Sources: emailsender/src/nats/client.ts:1-31, emailsender/src/nats/handlers.ts:8-9

Message Types

The messaging layer uses strictly typed interfaces to ensure contract safety between services.

SendEmailRequest

The input payload required to trigger an email dispatch.

• Path: emailsender/src/nats/types.ts:1-12
• Fields:
  • requestId: Unique identifier for correlation.
  • templateCode: Handlebars template identifier.
  • languageIso: Language code (e.g., 'en', 'it').
  • to, cc, bcc: Recipient arrays.
  • variables: Key-value pairs for template injection.
  • entityTable/entityId/entityUuid: Optional metadata for linking the email to database records.

SendEmailResponse

The output payload returned after processing.

• Path: emailsender/src/nats/types.ts:14-20
• Fields:
  • requestId: Correlated ID from the request.
  • success: Boolean indicating if the provider accepted the request.
  • providerMessageId: The ID returned by the external provider (e.g., Brevo).
  • error: Error message if success is false.
  • logId: The ID of the communication log entry in the database.

Sources: emailsender/src/nats/types.ts:1-20

Error Handling

The subscription loop in handlers.ts is wrapped in a try...catch block to prevent the subscriber from crashing on malformed messages.

1. Parsing Errors: If JSON.parse fails, the error is logged, and the loop continues to the next message emailsender/src/nats/handlers.ts:30-31.
2. Graceful Degradation: If an error occurs during processing, the service attempts to parse the requestId from the raw message data to send a failure response back to the requester emailsender/src/nats/handlers.ts:41-50.
3. Unknown Requests: If the requestId cannot be determined, no response is published to the response subject emailsender/src/nats/handlers.ts:48-50.

Sources: emailsender/src/nats/handlers.ts:17-52

---