Introduce incoming message support for envelope unwrapping #7422

hazel-bohon · 2025-10-01T19:10:13Z

This pull request introduces a new extensibility point in NServiceBus for envelope unwrapping, allowing the registration of envelope handlers for incoming messages, such as CloudEvents. It adds the IEnvelopeHandler interface and supporting infrastructure, integrates envelope handler registration into endpoint and feature configuration, and introduces OpenTelemetry metrics for envelope unwrapping successes and failures. Comprehensive tests are provided for both the envelope unwrapping logic and the new metrics.

This new extensibility point will first be used to enable cloudevents with the Azure Service Bus and Amazon SQS transports:

CloudEvents envelope handling support NServiceBus.Envelope.CloudEvents#22

Samples for will be added to the documentation with:

Adding CloudEvents samples for ASB and SQS docs.particular.net#7933

Envelope Handler Extensibility Infrastructure:

Introduced the IEnvelopeHandler interface, which allows custom logic for unwrapping incoming message envelopes.
Added EnvelopeComponent and EnvelopeUnwrapper classes to manage and invoke registered envelope handlers. The EnvelopeComponent collects handler factories and creates the unwrapper at runtime.
Provided EnvelopeConfigExtensions for registering envelope handlers in endpoint and feature configuration via the new AddEnvelopeHandler<THandler>() extension method.

Integration into Endpoint Lifecycle:

Integrated the envelope handler infrastructure into the endpoint creation and configuration process, ensuring envelope handlers are available during message processing.

Metrics and Observability:

Added OpenTelemetry metric nservicebus.envelope.unwrapping_error (Counter), including new tags such as nservicebus.envelope.unwrapper_type and error.type for observability of envelope unwrapping outcomes.
Implemented recording of metrics for both successful and failed envelope unwrapping attempts in the unwrapper logic.

Testing:

Added comprehensive tests for envelope handler scenarios (success, null, exception, and multiple handlers) in EnvelopeUnwrapperTests.
Added acceptance tests for OpenTelemetry metrics on both successful and failed envelope handler executions.
Updated pipeline and API approval tests to cover the new extensibility point and metrics.

These changes collectively enable advanced envelope customization and improved monitoring for message processing in NServiceBus.

…Core Particular/NServiceBus#7422

Particular/NServiceBus#7422

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs

mauroservienti · 2025-12-19T08:03:18Z

src/NServiceBus.Core/Pipeline/Incoming/IncomingPipelineMetrics.cs

+        if (exception != null)
+        {
+            meterTags.Add(new KeyValuePair<string, object?>(MeterTags.ErrorType, exception.GetType().FullName));
+        }
+
+        totalEnvelopeUnwrappingErrors.Add(succeeded ? 0 : 1, meterTags);


What's the scenario for the exception not null and succeeded true?

Shouldn't be such a scenario, but I didn't want to decide the metric value based on the exception and wanted to make it explicit.

If there is no scenario and the method is called RecordEnvelopeUnwrappingError, I don't see the need for the succeeded argument, and its usage.

Thinking a bit more about it, is there a chance for an unwrapping error with no exception?

Error metrics should be "always" emitted. If there is no error, then emit the metric as 0. This way you can make sure that your dashboards and alerts are configured correctly (because the metric is always there and you don't have a typo in your configuration) and that you can have additional alerts on missing metric data points.

That being said, there is a need to differentiate between "error happened" and "no error" situations.

Thinking a bit more about it, is there a chance for an unwrapping error with no exception?

Sure there is (not with the current implementation, though). .NET guidelines suggest that errors are communicated via exceptions, but there is no way to enforce that via the compiler.

mauroservienti · 2026-01-07T17:20:17Z

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs

+                    messageContext.NativeMessageId, messageContext.Headers, messageContext.Extensions,
+                    messageContext.Body);
+
+                metrics.RecordEnvelopeUnwrappingError(messageContext, envelopeHandler, null, true);


Why are we calling RecordEnvelopeUnwrappingError here? There is no error, at least not yet.

Looks like we want to record three different metrics:

Successful unwrappings, before line 40

Failed unwrappings due to unwrapping errors, at line 51, as we already do

Skipped unwrappers, at line 42

Additionally:

Do we want to count the number of messages going through as regular NServiceBus messages? (line 74/75)

Do we want/need to report metrics about how long unwrapping took?

Why are we calling RecordEnvelopeUnwrappingError here? There is no error, at least not yet.

There is no error and we want to explicitly indicate that. As mentioned above, the metric should "always" be emitted.

Looks like we want to record three different metrics:

This only increases the observability cost and makes the configuration more cumbersome. Success vs failure should be (and currently is) captured with one metric.

Skipped unwrappers, at line 42

The unwrapper should emit the metric in that case as it knows the skipping reason (and it indeed does that now). Not sure if we want to have another "generic" metric for that.

Would it be more clear if there was an RecordEnvelopeUnwrappingSuccess or simlar? (to avoid passing null as the exception, I also reacted to calling "error" when it actually succeeded)

Sure, I can rename. The reasoning behind the name is to record the EnvelopeUnwrappingError metric. Given that convention, RecordEnvelopeUnwrappingSuccess would record a different metric. I personally would find that misleading.

mauroservienti · 2026-01-07T17:20:42Z

src/NServiceBus.Core/Pipeline/Incoming/IncomingPipelineMetrics.cs

+        if (exception != null)
+        {
+            meterTags.Add(new KeyValuePair<string, object?>(MeterTags.ErrorType, exception.GetType().FullName));
+        }
+
+        totalEnvelopeUnwrappingErrors.Add(succeeded ? 0 : 1, meterTags);


If there is no scenario and the method is called RecordEnvelopeUnwrappingError, I don't see the need for the succeeded argument, and its usage.

Thinking a bit more about it, is there a chance for an unwrapping error with no exception?

src/NServiceBus.Testing.Fakes/TestableMessageContext.cs

src/NServiceBus.AcceptanceTests/Core/OpenTelemetry/Metrics/When_envelope_handler_succeeds.cs

# Conflicts: # src/NServiceBus.Core/Receiving/ReceiveComponent.cs

andreasohlund · 2026-01-09T06:17:39Z

Raised #7583 with a proposal to use the new syntax for done conditions

src/NServiceBus.Core/Pipeline/Incoming/IncomingPipelineMetrics.cs

* Convert to new style of acceptance tests * Fix warning * Field --------- Co-authored-by: Daniel Marbach <daniel.marbach@openplace.net>

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs

src/NServiceBus.Core/Envelopes/IEnvelopeHandler.cs

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs

src/NServiceBus.Core/Pipeline/MainPipelineExecutor.cs

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs

src/NServiceBus.Core/Envelopes/IEnvelopeHandler.cs

ramonsmits · 2026-01-09T10:04:32Z

Could potentially multiple envelopes be nested? As in a sort of envelope inception? In general there should only be 1 envelope but suddenly I got enterprise integration nostalgia where I was at a project that did that. Have a custom format wrapped in XML and then again in a SOAP envelope.

mauroservienti · 2026-01-09T11:12:05Z

Could potentially multiple envelopes be nested? As in a sort of envelope inception? In general there should only be 1 envelope but suddenly I got enterprise integration nostalgia where I was at a project that did that. Have a custom format wrapped in XML and then again in a SOAP envelope.

It could. To our knowledge, it's neither known nor supported by any spec.

ramonsmits · 2026-01-09T15:08:18Z

Could potentially multiple envelopes be nested? As in a sort of envelope inception? In general there should only be 1 envelope but suddenly I got enterprise integration nostalgia where I was at a project that did that. Have a custom format wrapped in XML and then again in a SOAP envelope.

It could. To our knowledge, it's neither known nor supported by any spec.

Current flow stops when an unwrapper was successful in the current EnvelopeUnwrapper.

Second, this seems to be the only way to have multiple unwrappers applied. For example if a use would want to have separate unwrappers for (de)compression and/or (un)encryption.

danielmarbach · 2026-01-09T15:10:32Z

Second, this seems to be the only way to have multiple unwrappers applied. For example if a use would want to have separate unwrappers for (de)compression and/or (un)encryption.

If that becomes a real requirement we could simply make our unwrappers public and then a user could decorate an unwrapper given they already said you can remove or add unwrappers, no?

every time I write wrapper I silently whisper an eminem song

afprtclr · 2026-01-09T15:28:32Z

Second, this seems to be the only way to have multiple unwrappers applied. For example if a use would want to have separate unwrappers for (de)compression and/or (un)encryption.

This is not fully correct. It's not just unwrapper, it's envelope unwrapper. We are dealing with envelopes only. Encryption, compression, obfuscation, and other stuff - these are not envelopes. It's just like in the OSI/ISO networking model - both Layers 2 and 3 have their own envelopes, but they are not covered by one spec and are not on the same level. One can't just add encryption on Layer 3 and expect Layer 2 to deal with that.

Our envelope unwrappers are meant to support some specification. If the specification supports recursive unwrapping - the unwrapper will need to handle that. When you say have multiple unwrappers applied, we are not trying to cover that because there is no specification that would be doing that.

Jokingly, one can obviously come up with another incarnation of decorator pattern to which I can only reply with https://xkcd.com/927/

…e-methods Use a multiple methods to report the envelope unwrapping metric counter

* Adjust envelope handler signature to allow proper pooling provided by an ArrayPoolBufferWriter * Better grouping of incoming message information vs output * Move writer * Pooling only needs to happen when an unwrapper actually does something * Remove the WrittenCount check because it is the responsibility of the unwrapper to write the body to the writer * Always clear the buffer before trying the following unwrapper --------- Co-authored-by: Daniel Marbach <danielmarbach@users.noreply.github.com> Co-authored-by: Mauro Servienti <mauro.servienti@gmail.com>

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs

internalautomation bot assigned hazel-bohon Oct 1, 2025

hazel-bohon requested review from afprtclr and mauroservienti October 1, 2025 19:12

hazel-bohon changed the title ~~Added IMarshalMessages interface.~~ Add IMarshalMessages interface Oct 1, 2025

mauroservienti assigned mauroservienti and afprtclr Oct 2, 2025

hazel-bohon changed the title ~~Add IMarshalMessages interface~~ [Spike] Add IMarshalMessages interface Oct 2, 2025

This comment was marked as off-topic.

Sign in to view

github-actions bot added the stale label Nov 3, 2025

github-actions bot closed this Nov 11, 2025

github-actions bot deleted the CloudEvents branch November 11, 2025 00:10

mauroservienti restored the CloudEvents branch November 24, 2025 12:50

mauroservienti reopened this Nov 24, 2025

mauroservienti changed the title ~~[Spike] Add IMarshalMessages interface~~ Introduce incoming message support for envelope unwrapping Nov 24, 2025

mauroservienti force-pushed the CloudEvents branch from 883a7a4 to 9f82a75 Compare November 24, 2025 12:54

mauroservienti removed the stale label Nov 24, 2025

mauroservienti added a commit to Particular/NServiceBus.Envelope.CloudEvents that referenced this pull request Nov 27, 2025

Move here the CloudEventJsonStructuredEnvelopeHandler from the PR in …

6e86d43

…Core Particular/NServiceBus#7422

mauroservienti added a commit to Particular/NServiceBus.Envelope.CloudEvents that referenced this pull request Nov 27, 2025

Move the unit tests from the PR in Core

38e250f

Particular/NServiceBus#7422

This was referenced Dec 4, 2025

NServiceBus and CloudEvents #7159

Open

Alternative envelope handling API approach #7514

Closed

mauroservienti force-pushed the CloudEvents branch from 9b71ba2 to a8b908e Compare December 9, 2025 10:19

afprtclr force-pushed the CloudEvents branch from a62cd95 to a48da28 Compare December 12, 2025 12:22

hazel-bohon commented Dec 15, 2025

View reviewed changes

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs Outdated Show resolved Hide resolved

mauroservienti reviewed Dec 19, 2025

View reviewed changes

mauroservienti requested changes Jan 7, 2026

View reviewed changes

afprtclr and others added 5 commits January 8, 2026 09:30

Introducing API for envelope handlers

007720a

# Conflicts: # src/NServiceBus.Core/Receiving/ReceiveComponent.cs

Removing CanUnwrap API

795c96a

Tweak "no envelope handler found" message

f7fc349

Fix formatting

4dad761

Adding metrics to envelopes

9a29660

afprtclr added 2 commits January 8, 2026 09:31

Importing explicitly

2cbebc7

Rebasing and fixing imports

8515ce5

afprtclr force-pushed the CloudEvents branch from 173df83 to 8515ce5 Compare January 8, 2026 08:35

Honor tests conventions

cf4937c

hazel-bohon marked this pull request as ready for review January 8, 2026 19:16

Delete src/NServiceBus.Testing.Fakes/TestableMessageContext.cs

e153b6b

jpalac reviewed Jan 9, 2026

View reviewed changes

src/NServiceBus.Core/Pipeline/Incoming/IncomingPipelineMetrics.cs Outdated Show resolved Hide resolved

Update to new style of acceptance tests for cloud events (#7583)

5aa64aa

* Convert to new style of acceptance tests * Fix warning * Field --------- Co-authored-by: Daniel Marbach <daniel.marbach@openplace.net>

ramonsmits reviewed Jan 9, 2026

View reviewed changes

Use new syntax for done conditions (#7584)

91aa40b

mauroservienti and others added 6 commits January 10, 2026 08:38

Use a multiple methods to report the envelope unwrapping metric counter

0183239

Improve method and metric name

ca98bad

Merge pull request #7587 from Particular/cloud-events-metrics-multipl…

1d65958

…e-methods Use a multiple methods to report the envelope unwrapping metric counter

Switching to formatted logging

84eddf5

Bringing new test style to OTel tests

39e8cad

afprtclr requested a review from mauroservienti January 19, 2026 13:43

afprtclr approved these changes Jan 19, 2026

View reviewed changes

mauroservienti reviewed Jan 19, 2026

View reviewed changes

src/NServiceBus.Core/Envelopes/EnvelopeUnwrapper.cs Show resolved Hide resolved

hazel-bohon requested a review from mauroservienti January 22, 2026 14:58

hazel-bohon enabled auto-merge January 22, 2026 14:59

mauroservienti approved these changes Jan 22, 2026

View reviewed changes

hazel-bohon merged commit 99356b7 into master Jan 22, 2026
4 checks passed

hazel-bohon deleted the CloudEvents branch January 22, 2026 15:15

Introduce incoming message support for envelope unwrapping #7422

Introduce incoming message support for envelope unwrapping #7422

Uh oh!

Conversation

hazel-bohon commented Oct 1, 2025 • edited by ramonsmits Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as off-topic.

Uh oh!

mauroservienti Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

afprtclr Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

mauroservienti Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

afprtclr Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

mauroservienti Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

afprtclr Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreasohlund Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afprtclr Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

mauroservienti Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

andreasohlund commented Jan 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ramonsmits commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mauroservienti commented Jan 9, 2026

Uh oh!

ramonsmits commented Jan 9, 2026

Uh oh!

danielmarbach commented Jan 9, 2026

Uh oh!

afprtclr commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

hazel-bohon commented Oct 1, 2025 •

edited by ramonsmits

Loading

afprtclr Jan 8, 2026 •

edited

Loading

andreasohlund Jan 9, 2026 •

edited

Loading

ramonsmits commented Jan 9, 2026 •

edited

Loading

afprtclr commented Jan 9, 2026 •

edited

Loading