NuGet.Services.Messaging

Overview

NuGet.Services.Messaging is a small, focused library that forms the bridge between the NuGet Gallery frontend (the email sender) and the back-end email processing job (the email consumer). It defines the canonical EmailMessageData model that both sides agree on, the IEmailMessageEnqueuer interface that the frontend uses to dispatch email without knowing the delivery mechanism, and the ServiceBusMessageSerializer that translates between EmailMessageData and Azure Service Bus brokered messages. The library encodes one deliberate GDPR constraint directly in the serializer: every Service Bus message is given a time-to-live of exactly two days. Because email message payloads can contain personally identifiable information (recipient addresses, user names, etc.), this hard-coded TTL ensures that un-processed messages are automatically purged by the broker before they can linger indefinitely. The project targets both net472 and netstandard2.0, which allows it to be referenced by the full-framework NuGetGallery web application and by any future .NET Standard-compatible services without modification. It has no direct Azure SDK dependency of its own; all Azure Service Bus types are abstracted behind interfaces defined in NuGet.Services.Contracts and implemented in NuGet.Services.ServiceBus.

Role in System

NuGet.Services.Messaging sits in the middle of the asynchronous email pipeline. The gallery frontend constructs an EmailMessageData value, hands it to IEmailMessageEnqueuer, which serializes it and publishes it to an Azure Service Bus topic. A separate back-end job subscribes to that topic, deserializes the message using the same IServiceBusMessageSerializer, and performs the actual SMTP delivery.

NuGetGallery (frontend)
  └─ AsynchronousEmailMessageService          (NuGet.Services.Messaging.Email)
       └─ IEmailMessageEnqueuer
            └─ EmailMessageEnqueuer           (NuGet.Services.Messaging)
                 ├─ IServiceBusMessageSerializer
                 │    └─ ServiceBusMessageSerializer  (serializes EmailMessageData to JSON)
                 └─ ITopicClient
                      └─ TopicClientWrapper   (NuGet.Services.ServiceBus -> Azure Service Bus)

Azure Service Bus Topic
  └─ Back-end email job (subscriber)
       └─ IServiceBusMessageSerializer
            └─ ServiceBusMessageSerializer  (deserializes JSON back to EmailMessageData)

Shared Data Contract

EmailMessageData is the single agreed-upon model for an email message. It carries subject, plain-text body, HTML body, sender, To/CC/Bcc/ReplyTo recipient lists, a tracking GUID, and a delivery count populated on the consumer side.

Enqueuing Abstraction

IEmailMessageEnqueuer hides the Service Bus publishing details from callers. The concrete EmailMessageEnqueuer serializes the message, calls ITopicClient.SendAsync, and emits structured log entries at Trace and Information level for each step.

Versioned Schema Serialization

ServiceBusMessageSerializer uses the generic BrokeredMessageSerializer<T> from NuGet.Services.ServiceBus together with a private [Schema(Name = "EmailMessageData", Version = 1)] inner class. Schema name and version are stored as Service Bus message properties and validated on deserialization.

GDPR-Enforced TTL

Messages are given a two-day TTL at serialization time. This is a hard-coded policy (not configuration) that ensures PII-containing email payloads are automatically expired by the broker if they are not consumed promptly.

Key Files and Classes

File	Class / Type	Purpose
`EmailMessageData.cs`	`EmailMessageData`	Immutable data transfer object representing a fully composed email message. Constructor enforces that `To` is non-null and non-empty, and that `MessageTrackingId` is not `Guid.Empty`. `CC`, `Bcc`, and `ReplyTo` default to empty lists when `null` is passed. `DeliveryCount` is set by the consumer during deserialization and is `0` when constructing a new message for sending.
`IEmailMessageEnqueuer.cs`	`IEmailMessageEnqueuer`	Single-method interface with `SendEmailMessageAsync(EmailMessageData)`. Consumed by `AsynchronousEmailMessageService` in `NuGet.Services.Messaging.Email` and registered in the NuGetGallery DI container.
`EmailMessageEnqueuer.cs`	`EmailMessageEnqueuer`	Concrete implementation of `IEmailMessageEnqueuer`. Depends on `ITopicClient`, `IServiceBusMessageSerializer`, and `ILogger<EmailMessageEnqueuer>`. Logs the tracking ID at each step (serialize start, serialize success, enqueue start, enqueue success).
`IServiceBusMessageSerializer.cs`	`IServiceBusMessageSerializer`	Two-method interface: `SerializeEmailMessageData(EmailMessageData) → IBrokeredMessage` and `DeserializeEmailMessageData(IReceivedBrokeredMessage) → EmailMessageData`. Used by both the producer (frontend) and consumer (back-end job).
`ServiceBusMessageSerializer.cs`	`ServiceBusMessageSerializer`	Concrete serializer. Internally defines a private `EmailMessageData1` class decorated with `[Schema(Name = "EmailMessageData", Version = 1)]`. Serialization produces a JSON-body `IBrokeredMessage` with `SchemaName` and `SchemaVersion` properties and a two-day TTL. Deserialization validates those properties via `BrokeredMessageSerializer<T>` before JSON deserialization, and populates `DeliveryCount` from the received message’s broker metadata.

Dependencies

NuGet Package References

Package	Purpose
`Azure.Core`	Transitively required for Azure Service Bus type compatibility; not directly referenced in project code.
`Microsoft.Extensions.Logging`	Provides `ILogger<T>` used in `EmailMessageEnqueuer` for structured logging.

Internal Project References

Project	Purpose
`NuGet.Services.Contracts`	Provides the `IBrokeredMessage`, `IReceivedBrokeredMessage`, and `ITopicClient` interfaces that decouple this library from any specific Azure SDK version.
`NuGet.Services.ServiceBus`	Provides `BrokeredMessageSerializer<T>`, `SchemaAttribute`, and the `AssertTypeAndSchemaVersion` extension used by `ServiceBusMessageSerializer` to handle JSON serialization and schema validation of Service Bus messages.

Notable Patterns and Implementation Details

The EmailMessageData1 inner class in ServiceBusMessageSerializer is private and versioned with [Schema(Name = "EmailMessageData", Version = 1)]. This versioning scheme means that a schema change (adding, removing, or modifying a property) requires incrementing the version number and adding a new inner class (e.g., EmailMessageData2). The deserializer enforces the version at runtime and throws FormatException if the message was produced by a different schema version.

The two-day TTL on Service Bus messages is enforced unconditionally in ServiceBusMessageSerializer.SerializeEmailMessageData. It is not configurable. Any email message payload that remains unconsumed in the topic for longer than 48 hours will be dead-lettered or discarded by the broker. This is intentional GDPR policy, but it means that extended outages of the back-end email consumer will result in lost email notifications.

EmailMessageEnqueuer logs the MessageTrackingId GUID at every step using structured logging. This allows operators to correlate a specific email message across the frontend log (where it was enqueued) and the backend log (where it was processed or failed) by searching for the same tracking ID value.

The DeliveryCount field on EmailMessageData is not set by the sender. It is populated only during deserialization in ServiceBusMessageSerializer.DeserializeEmailMessageData from the broker’s own IReceivedBrokeredMessage.DeliveryCount property. Back-end consumers can use this value to detect and handle repeated delivery attempts (e.g., to avoid sending duplicate emails after transient failures).

Getting Started

Specifications

Implementation Plan

Legacy (NuGetGallery)

Specs

NuGet.Services.Messaging

Overview

Role in System

Shared Data Contract

Enqueuing Abstraction

Versioned Schema Serialization

GDPR-Enforced TTL

Key Files and Classes

Dependencies

NuGet Package References

Internal Project References

Notable Patterns and Implementation Details

​Overview

​Role in System

Shared Data Contract

Enqueuing Abstraction

Versioned Schema Serialization

GDPR-Enforced TTL

​Key Files and Classes

​Dependencies

​NuGet Package References

​Internal Project References

​Notable Patterns and Implementation Details

Overview

Role in System

Key Files and Classes

Dependencies

NuGet Package References

Internal Project References

Notable Patterns and Implementation Details