Skip to content

Commit 4f5cca2

Browse files
abparticularjpalac
abparticular
and
jpalac
authored
Document TranslateReplyToAddressForFailedMessages for the bridge (#6814)
* Document TranslateReplyToAddressForFailedMessages for the bridge * Bridge does not support same logical endpoint on both sides * Apply suggestions from code review Co-authored-by: Jo Palac <[email protected]> * Documented `TranslateReplyToAddressForFailedMessages` for only the messaging bridge versions where it is available * fix integration tests * update review date --------- Co-authored-by: Jo Palac <[email protected]> Co-authored-by: Jo Palac <[email protected]>
1 parent a680a28 commit 4f5cca2

13 files changed

+132
-2
lines changed

‎Snippets/Bridge/Bridge.sln‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TransportBridge_1", "Transp
99
EndProject
1010
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Bridge_3", "Bridge_3\Bridge_3.csproj", "{E226790D-B7DC-4DE5-A0DB-1C4F98E97741}"
1111
EndProject
12+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Bridge_2.3", "Bridge_2.3\Bridge_2.3.csproj", "{EA38ED6D-F531-4A66-8A30-F72587460C4B}"
13+
EndProject
14+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Bridge_3.1", "Bridge_3.1\Bridge_3.1.csproj", "{3E841EA4-DF6D-4DA4-9704-00EBBA86D335}"
15+
EndProject
1216
Global
1317
GlobalSection(SolutionConfigurationPlatforms) = preSolution
1418
Debug|Any CPU = Debug|Any CPU
@@ -27,6 +31,14 @@ Global
2731
{E226790D-B7DC-4DE5-A0DB-1C4F98E97741}.Debug|Any CPU.Build.0 = Debug|Any CPU
2832
{E226790D-B7DC-4DE5-A0DB-1C4F98E97741}.Release|Any CPU.ActiveCfg = Release|Any CPU
2933
{E226790D-B7DC-4DE5-A0DB-1C4F98E97741}.Release|Any CPU.Build.0 = Release|Any CPU
34+
{EA38ED6D-F531-4A66-8A30-F72587460C4B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
35+
{EA38ED6D-F531-4A66-8A30-F72587460C4B}.Debug|Any CPU.Build.0 = Debug|Any CPU
36+
{EA38ED6D-F531-4A66-8A30-F72587460C4B}.Release|Any CPU.ActiveCfg = Release|Any CPU
37+
{EA38ED6D-F531-4A66-8A30-F72587460C4B}.Release|Any CPU.Build.0 = Release|Any CPU
38+
{3E841EA4-DF6D-4DA4-9704-00EBBA86D335}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
39+
{3E841EA4-DF6D-4DA4-9704-00EBBA86D335}.Debug|Any CPU.Build.0 = Debug|Any CPU
40+
{3E841EA4-DF6D-4DA4-9704-00EBBA86D335}.Release|Any CPU.ActiveCfg = Release|Any CPU
41+
{3E841EA4-DF6D-4DA4-9704-00EBBA86D335}.Release|Any CPU.Build.0 = Release|Any CPU
3042
EndGlobalSection
3143
GlobalSection(SolutionProperties) = preSolution
3244
HideSolutionNode = FALSE

‎Snippets/Bridge/Bridge_2.3/Bridge_2.3.csproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup>
3+
<TargetFramework>net48</TargetFramework>
4+
</PropertyGroup>
5+
<ItemGroup>
6+
<PackageReference Include="NServiceBus.MessagingBridge" Version="2.3.*" />
7+
</ItemGroup>
8+
</Project>

‎Snippets/Bridge/Bridge_2.3/Configuration.cs‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
using NServiceBus;
2+
3+
public class Configuration
4+
{
5+
public void TranslateReplyToAddressForFailedMessages()
6+
{
7+
var bridgeConfiguration = new BridgeConfiguration();
8+
9+
#region translate-reply-to-address-for-failed-messages
10+
11+
bridgeConfiguration.TranslateReplyToAddressForFailedMessages();
12+
13+
#endregion
14+
}
15+
}

‎Snippets/Bridge/Bridge_2/Configuration.cs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,18 @@ public void ConfigureCustomChecks()
242242
#endregion
243243
}
244244

245+
public void TranslateReplyToAddressForFailedMessages()
246+
{
247+
var bridgeConfiguration = new BridgeConfiguration();
248+
249+
#region translate-reply-to-address-for-failed-messages
250+
251+
bridgeConfiguration.TranslateReplyToAddressForFailedMessages();
252+
253+
#endregion
254+
}
255+
256+
245257
string connectionString = string.Empty;
246258
string connectionStringNamepace1 = string.Empty;
247259
string connectionStringNamepace2 = string.Empty;

‎Snippets/Bridge/Bridge_3.1/Bridge_3.1.csproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup>
3+
<TargetFramework>net8.0</TargetFramework>
4+
</PropertyGroup>
5+
<ItemGroup>
6+
<PackageReference Include="NServiceBus.MessagingBridge" Version="3.1.*" />
7+
</ItemGroup>
8+
</Project>

‎Snippets/Bridge/Bridge_3.1/Configuration.cs‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
using NServiceBus;
2+
3+
public class Configuration
4+
{
5+
public void TranslateReplyToAddressForFailedMessages()
6+
{
7+
var bridgeConfiguration = new BridgeConfiguration();
8+
9+
#region translate-reply-to-address-for-failed-messages
10+
11+
bridgeConfiguration.TranslateReplyToAddressForFailedMessages();
12+
13+
#endregion
14+
}
15+
}

‎Snippets/Bridge/Bridge_3/Configuration.cs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,17 @@ public void ConfigureCustomChecks()
242242
#endregion
243243
}
244244

245+
public void TranslateReplyToAddressForFailedMessages()
246+
{
247+
var bridgeConfiguration = new BridgeConfiguration();
248+
249+
#region translate-reply-to-address-for-failed-messages
250+
251+
bridgeConfiguration.TranslateReplyToAddressForFailedMessages();
252+
253+
#endregion
254+
}
255+
245256
string connectionString = string.Empty;
246257
string connectionStringNamepace1 = string.Empty;
247258
string connectionStringNamepace2 = string.Empty;

‎nservicebus/bridge/configuration.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Bridge configuration options
33
summary: Configuration options for the messaging bridge.
44
component: Bridge
5-
reviewed: 2023-07-04
5+
reviewed: 2024-09-05
66
---
77

88
## Hosting
@@ -21,6 +21,11 @@ If a logical endpoint communicates with other endpoints that use a different tra
2121

2222
snippet: endpoint-registration
2323

24+
> [!NOTE]
25+
> Having the same logical endpoint running on both transports is not supported. The bridge will throw an exception if an endpoint is registered on more than one transport.
26+
>
27+
> If a duplicate endpoint it is not registered with the bridge, any messages it sends that need to be forwarded across the bridge will fail and get sent to the [bridge error queue](#recoverability-error-queue).
28+
2429
## Registering publishers
2530

2631
When NServiceBus discovers a message handler in an endpoint for an event, it automatically subscribes to this event on the transport. The publisher itself is not aware of this, since it does not receive a notification when a subscriber subscribes to an event. This represents a challenge for the bridge.
@@ -115,7 +120,7 @@ If a message fails while it is being forwarded to the target transport, the foll
115120

116121
The error queue used by the bridge is named `bridge.error` by default. Note that the default `error` queue used by other platform components can not be used to enable bridging of the system-wide error queue since a bridged queue may not be used as the error queue. See the documentation around [bridging platform queues](#bridging-platform-queues) for more details.
117122

118-
A different error queue may configured as follows:
123+
A different error queue may be configured as follows:
119124

120125
snippet: custom-error-queue
121126

@@ -142,6 +147,8 @@ snippet: platform-bridging
142147
> [!WARNING]
143148
> The endpoint name used when creating a `BridgeEndpoint` is case-sensitive, even if one or both transports don't require it. This is to accommodate all transports, some of which require a case-sensitive endpoint name. More details can be found on [this issue](https://github.com/Particular/NServiceBus.MessagingBridge/issues/175).
144149
150+
partial: failed-messages
151+
145152
### Audit queue
146153

147154
Special considerations are required for the audit queue due to potentially high message volume. For example, a [dedicated ServiceControl audit instance](/servicecontrol/audit-instances/) could be created for each bridged transport, to make audit ingestion more efficient.

‎nservicebus/bridge/configuration_failed-messages_bridge_[2,2.3).partial.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
### Error queue
2+
3+
By default, when the bridge transfers a message to the ServiceControl error queue it will not attempt to translate the [`NServiceBus.ReplyToAddress`](/nservicebus/messaging/headers.md#messaging-interaction-headers-nservicebus-replytoaddress) message header.
4+
This means that endpoints only need to be registered with the bridge if they are directly involved with messages transferred between transports.
5+
The drawback is that if an endpoint is moved to a different transport, then any failed messages from that endpoint that perform a `ReplyTo` operation as part of the handler logic, cannot be retried since the value in the `NServiceBus.ReplyToAddress` header is unreachable.

‎nservicebus/bridge/configuration_failed-messages_bridge_[2.3,3).partial.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### Error queue
2+
3+
By default, when the bridge transfers a message to the ServiceControl error queue it will not attempt to translate the [`NServiceBus.ReplyToAddress`](/nservicebus/messaging/headers.md#messaging-interaction-headers-nservicebus-replytoaddress) message header.
4+
This means that endpoints only need to be registered with the bridge if they are directly involved with messages transferred between transports.
5+
The drawback is that if an endpoint is moved to a different transport, then any failed messages from that endpoint that perform a `ReplyTo` operation as part of the handler logic, cannot be retried since the value in the `NServiceBus.ReplyToAddress` header is unreachable.
6+
7+
This behavior can be changed by configuring the bridge to translate the `NServiceBus.ReplyToAddress` message header for failed messages.
8+
9+
snippet: translate-reply-to-address-for-failed-messages
10+
11+
> [!WARNING]
12+
> Since any endpoint can generate a failed message, enabling translation of the `NServiceBus.ReplyToAddress` header requires that all endpoints are registered with the bridge.
13+
> Message that fail during bridge address translation due to unknown endpoints will be moved to the `bridge.error` queue.
14+
15+
> [!NOTE]
16+
> Translating the `NServiceBus.ReplyToAddress` message header for failed messages will become the default behavior in a future major version of the bridge.

0 commit comments

Comments
 (0)