cloops.nats.schema 1.0.6

CLOOPS Nats Schema

The official Connection Loops SDK for defining strongly typed schemas across all the microservices in Connection Loops.

🚀 Overview

The goal here is to have strong types for every single message passed between any two microservices in Connection Loops.

This repo makes our cloops.nats SDK generic to handle NATS connection logic and this repo defines all the messages.

The aim here is to reduce potential errors due to loose types and weak contracts

⚡ Benefits of having strong types for nats

• Less chance of surprise failures.
• Better developer experience
• Lock down a subject with a specific message
• Automatic input validation before publishing/requesting

📋 Subject Types

This SDK supports three types of NATS subjects, each serving a specific communication pattern:

P_Subject - Publish Subject

• Purpose: Core NATS publishing for fire-and-forget messaging
• Use Case: When you need to broadcast events without expecting a response
• Example: Publishing events, notifications, or logging messages
• Method: Publish(T payload) - validates and publishes the message

S_Subject - Stream Subject (JetStream)

• Purpose: JetStream publishing for durable, persistent messaging
• Use Case: When you need message persistence, delivery tracking, and guaranteed delivery
• Features: Supports deduplication, message acknowledgment, and stream-based delivery
• Method: StreamPublish(T payload, ...) - validates and publishes with JetStream guarantees

R_Subject - Request-Reply Subject

• Purpose: Request-response pattern for synchronous communication
• Use Case: When you need to send a request and wait for a specific reply
• Pattern: Request-reply is only applicable in core NATS (not JetStream)
• Method: Request(Q payload) - validates the request and returns the reply

Note: All subject names should start with their type prefix (P, S, or R) when defined in subject builders.

🧩 Installation

This SDK is part of cloops.microservices. It is recommended that you bring in the whole package that cloops.microservices offers.

🔄 Existing Projects

Add cloops.nats.schema package reference to your .csproj file. Please note we deliberately want all of our consumers to stay on latest version of the SDK.

<PackageReference Include="cloops.nats.schema" Version="*" />

Once added, just run dotnet restore to pull in the SDK.

📝 Message Validation

All messages in this SDK inherit from BaseMessage and support automatic validation using Data Annotations. Validation is automatically performed when you publish or send messages through subjects.

How It Works

1. Inherit from BaseMessage: All message classes inherit from BaseMessage
2. Add Validation Attributes: Use Data Annotations attributes like [Required], [Range], [Url], etc.
3. Automatic Validation: Validation is triggered automatically when you call:
   • P_Subject.Publish() - validates before publishing
   • S_Subject.StreamPublish() - validates before stream publishing
   • R_Subject.Request() - validates the request before sending

Example

public class MyMessage : BaseMessage
{
    [Required(ErrorMessage = "Id is required")]
    public string Id { get; set; }

    [Range(1, 100, ErrorMessage = "Value must be between 1 and 100")]
    public int Value { get; set; }

    [Url(ErrorMessage = "Url must be a valid URL")]
    public string Url { get; set; }
}

// Usage - validation happens automatically
var message = new MyMessage { Id = "123", Value = 50, Url = "https://example.com" };
await subject.Publish(message); // Validates and publishes, throws ValidationException if invalid

If validation fails, a ValidationException is thrown with details about what failed.

🤝 Contribution Guidelines

Please see our Contribution Guidelines for detailed information on how to contribute to this SDK, including:

• Subject and message type conventions
• Validation requirements
• Testing requirements
• Best practices for compiler-level validation