Here is a list of things to consider when using the Nexus Link Services.
Mandatory knowledge
To have a robust digital platform, there are some rules regarding the use of Nexus Link Services.
Async Caller
Guaranteed delivery
Nexus Async Caller gurantees that a request is delivered to the designated server, but only if it has accepted the request.
You must provide your own retry mechanism in the case that Async Caller doesn't accept your requests.
If the Async Caller service doesn't accept a request, you could store the request in local storage and have a mechanism for resending it to Async Caller when it accepts requests again.
At-least-once delivery
Nexus AsyncCaller uses the at least once pattern for delivery of a request to a server. This means that a specific request could be delivered multiple times to the server.
If you have requests that must not be executed more than once, you have to provide the logic to prevent this.
The client could mark the request with a unique identifier, e.g. a ClientRequestId. If the Async Caller service does not accept the request first and you later send it again to the service, then you must use the same ClientRequestId. When the server accepts a request for execution it stores the ClientRequestId with the response and if the same ClientRequestId appears again, it could return the same response again.
Maximum payload size
Nexus Async Caller uses Azure Storage queues, which means there is a limit of 64 kB per message. With wrapping metadata some of this is used up, leaving approximately 40 kB for the payload of a request or a response. If the message contains multibyte characters, the available number of bytes could be reduced further. If the message is too large to fit, it will be arbitrarily truncated.
You must be careful not to surpass the payload size limit in your messages.
Save large payloads in some storage that is accessible for the receiver and send a reference to stored data in the actual payload.
Request timeout
When Nexus AsyncCaller sends the request to the server, the send action will timeout after 100 seconds and the request will be put back on the queue to be tried later.
In the function app, prior to AsyncCaller version 1.4 this timeout can cause an exponentially growing queue of duplicate requests.
The problem is that the function app also has a timeout of 100 seconds, so when the Async Caller send method times out, it will put the request back on the queue. This means that before it can return the information about this to the function app, the function app also times out. The function app will then retry (up to 5 times), each time resulting in a new duplicate of the request on the queue.
In the function app, set the HttpClient to timeout after 120 seconds. See the example below
public class AsyncCallsClient
{
private static readonly HttpClient HttpClient = new HttpClient() { Timeout = TimeSpan.FromSeconds(120) };
Business Events
Dependency on Async Caller
Nexus Business Events uses the Nexus Async Caller service to deliver events. This means that it is susceptible to the same limitations.
Take measures for guaranteed delivery, at-least-once delivery and payload size, as described above for the Nexus Async Caller service.
Changing endpoint for subscription webhook
This is especially relevant for clients with DynamicalRegsitration turned on.
When changing the endpoint for a subscription, make sure to keep the old one around until the time is out for possible retires on failed attempts to deliver the event.
"MetaData" attribute not available in event payload
You cannot use MetaData as an attribute in event contracts, since Business Events add that itself to every outgoing event.
Logging
Nexus Logging uses Azure Storage queues, which means there is a limit of 64 kB per message. With wrapping metadata some of this is used up, leaving approximately 50 kB for the actual log message. If the message contains multibyte characters, the available number of bytes could be reduced further. If the message is too large to fit, it will be arbitrarily truncated.
If you have long log messages, e.g. verbose call stacks, your messages can be truncated before they are sent from your application.