feat(notifications): no-SDK EWS SOAP mail sender with typed transient/permanent classification

src/ZB.MOM.WW.ScadaBridge.NotificationService/Ews/EwsSoapMailSender.cs

@@ -0,0 +1,203 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Text;
+using Microsoft.Extensions.Logging;
+
+namespace ZB.MOM.WW.ScadaBridge.NotificationService.Ews;
+
+/// <summary>
+/// Sends notification mail through Exchange Web Services over plain HTTPS + SOAP — no EWS SDK,
+/// honouring the project's no-new-NuGet-package rule.
+/// <para>
+/// Authentication is an explicit <c>Authorization: Basic</c> header set on each
+/// <see cref="HttpRequestMessage"/>, never on the shared <see cref="HttpClient"/>: the factory's
+/// handler is pooled and shared across every configuration, so a client-level credential would
+/// leak between callers. Negotiate/NTLM is the documented follow-on if Basic is ever disabled on
+/// the EWS virtual directory.
+/// </para>
+/// <para>
+/// Classification (see the design's §4.3) prefers what Exchange <em>said</em> over what HTTP
+/// reported: a parsed response code decides the outcome even on a 500, and only an unparseable
+/// body falls back to the status code. Unclassified failures default to permanent, matching the
+/// SMTP adapter's stance.
+/// </para>
+/// <para>
+/// The password and the base64 Basic-auth value never appear in a thrown message or a log line:
+/// attempts are logged at Debug with the endpoint host and a recipient <em>count</em> only, and
+/// every surfaced message runs through <see cref="CredentialRedactor"/>.
+/// </para>
+/// </summary>
+public sealed class EwsSoapMailSender : IEwsMailSender
+{
+    /// <summary>The named <see cref="HttpClient"/> registered for EWS in <c>ServiceCollectionExtensions</c>.</summary>
+    public const string HttpClientName = "EwsMail";
+
+    /// <summary>Mask applied to the base64 credential, matching <see cref="CredentialRedactor"/>'s.</summary>
+    private const string Mask = "***REDACTED***";
+
+    /// <summary>
+    /// EWS response codes that describe load or availability rather than a defect in the request.
+    /// Everything else — schema faults, recipient rejections, authorization — is permanent.
+    /// </summary>
+    private static readonly HashSet<string> TransientResponseCodes = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "ErrorServerBusy",
+        "ErrorInternalServerTransientError",
+        "ErrorTimeoutExpired",
+        "ErrorMailboxStoreUnavailable",
+        "ErrorInsufficientResources",
+    };
+
+    private readonly IHttpClientFactory _httpClientFactory;
+    private readonly ILogger<EwsSoapMailSender> _logger;
+
+    /// <summary>Initializes a new instance of <see cref="EwsSoapMailSender"/>.</summary>
+    /// <param name="httpClientFactory">Factory creating the named <c>"EwsMail"</c> HTTP client per send.</param>
+    /// <param name="logger">Logger instance.</param>
+    public EwsSoapMailSender(IHttpClientFactory httpClientFactory, ILogger<EwsSoapMailSender> logger)
+    {
+        ArgumentNullException.ThrowIfNull(httpClientFactory);
+        ArgumentNullException.ThrowIfNull(logger);
+
+        _httpClientFactory = httpClientFactory;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public async Task SendAsync(EwsSendRequest request, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        var envelope = EwsSoapEnvelope.BuildCreateItem(
+            request.FromAddress, request.BccRecipients, request.Subject, request.Body);
+
+        var packedCredential = $"{request.Username}:{request.Password}";
+        var base64Credential = Convert.ToBase64String(Encoding.UTF8.GetBytes(packedCredential));
+
+        // Recipient COUNT only — addresses are notification content and do not belong in the log.
+        _logger.LogDebug(
+            "Submitting EWS CreateItem to {EwsHost} for {RecipientCount} recipient(s).",
+            request.Endpoint.Host,
+            request.BccRecipients.Count);
+
+        // Per-request timeout layered over the caller's token, so a stalled Exchange surfaces as
+        // a TaskCanceledException with no caller cancel — classified transient below — while a
+        // genuine caller cancel still propagates unwrapped. HttpClient.Timeout is left alone: the
+        // client is shared and its timeout is not per-configuration.
+        using var linkedCts = request.TimeoutSeconds > 0
+            ? CancellationTokenSource.CreateLinkedTokenSource(cancellationToken)
+            : null;
+        linkedCts?.CancelAfter(TimeSpan.FromSeconds(request.TimeoutSeconds));
+        var sendToken = linkedCts?.Token ?? cancellationToken;
+
+        var httpClient = _httpClientFactory.CreateClient(HttpClientName);
+
+        try
+        {
+            using var httpRequest = new HttpRequestMessage(HttpMethod.Post, request.Endpoint)
+            {
+                Content = new StringContent(envelope, Encoding.UTF8, "text/xml"),
+            };
+            httpRequest.Headers.Authorization =
+                new AuthenticationHeaderValue("Basic", base64Credential);
+
+            using var response = await httpClient.SendAsync(httpRequest, sendToken);
+            var responseBody = await response.Content.ReadAsStringAsync(sendToken);
+
+            ThrowOnFailure(response.StatusCode, responseBody, packedCredential, base64Credential);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            // The caller cancelled: neither a success nor a delivery failure, so it propagates
+            // unchanged rather than being recorded as a transient send error.
+            throw;
+        }
+        catch (Exception ex) when (ex is HttpRequestException or OperationCanceledException)
+        {
+            // Transport failure or our own timeout — availability-shaped, so retry.
+            throw new EwsTransientException(
+                Scrub(
+                    $"EWS request to {request.Endpoint.Host} failed: {ex.Message}",
+                    packedCredential,
+                    base64Credential),
+                ex);
+        }
+    }
+
+    /// <summary>
+    /// Classifies one EWS response, returning quietly on success and throwing the matching typed
+    /// exception otherwise. The parsed response body wins over the HTTP status whenever it is
+    /// intelligible; only an unparseable body falls back to the status code.
+    /// </summary>
+    private void ThrowOnFailure(
+        HttpStatusCode statusCode,
+        string responseBody,
+        string packedCredential,
+        string base64Credential)
+    {
+        var parsed = EwsResponseParser.Parse(responseBody);
+
+        // Exchange accepted the message. A non-2xx status alongside a Success response class is
+        // not a thing Exchange does, but if a proxy rewrites the status the message still went.
+        if (parsed.Kind == EwsResponseKind.Success
+            || string.Equals(parsed.ResponseCode, "NoError", StringComparison.OrdinalIgnoreCase))
+        {
+            return;
+        }
+
+        var status = (int)statusCode;
+
+        if (parsed.Kind is EwsResponseKind.Error or EwsResponseKind.Fault)
+        {
+            var code = parsed.ResponseCode ?? "(no response code)";
+            var detail = Scrub(
+                $"EWS returned {code} (HTTP {status}): {parsed.MessageText ?? "(no message text)"}",
+                packedCredential,
+                base64Credential);
+
+            if (parsed.ResponseCode is not null && TransientResponseCodes.Contains(parsed.ResponseCode))
+            {
+                _logger.LogWarning("Transient EWS failure: {Detail}", detail);
+                throw new EwsTransientException(detail);
+            }
+
+            // Includes a fault carrying no response code: the default-permanent stance keeps an
+            // unrecognised failure from retrying forever.
+            _logger.LogError("Permanent EWS failure: {Detail}", detail);
+            throw new EwsPermanentException(detail);
+        }
+
+        // Unparseable body — nothing but the HTTP status is left to judge on.
+        var message = $"EWS endpoint returned {status} ({statusCode}) with an unrecognised body";
+
+        // 401/403 credential or authorization, 404/410 wrong URL, 405 wrong verb/endpoint: all
+        // configuration defects, and retrying 401 burns a domain account's lockout budget.
+        if (status is 401 or 403 or 404 or 405 or 410)
+        {
+            _logger.LogError("Permanent EWS failure: {Detail}", message);
+            throw new EwsPermanentException(message);
+        }
+
+        if (status is 408 or 429 || status >= 500)
+        {
+            _logger.LogWarning("Transient EWS failure: {Detail}", message);
+            throw new EwsTransientException(message);
+        }
+
+        // A 2xx whose body is not an EWS response is a protocol violation from something in the
+        // path (proxy error page, captive portal); anything else non-success is unclassified.
+        // Neither is fixed by replaying the same request.
+        _logger.LogError("Permanent EWS failure: {Detail}", message);
+        throw new EwsPermanentException(message);
+    }
+
+    /// <summary>
+    /// Masks both credential shapes — the packed <c>user:password</c> (via the shared
+    /// <see cref="CredentialRedactor"/>, which also covers the bare password) and the base64
+    /// Basic-auth value — out of text bound for an exception message or a log line.
+    /// </summary>
+    private static string Scrub(string text, string packedCredential, string base64Credential)
+        => CredentialRedactor
+            .Scrub(text, packedCredential)
+            .Replace(base64Credential, Mask, StringComparison.Ordinal);
+}

src/ZB.MOM.WW.ScadaBridge.NotificationService/Ews/IEwsMailSender.cs

@@ -0,0 +1,80 @@
+namespace ZB.MOM.WW.ScadaBridge.NotificationService.Ews;
+
+/// <summary>
+/// One-shot EWS mail submission (<c>CreateItem</c>, <c>SendOnly</c>, BCC-only).
+/// <para>
+/// The seam the central Notification Outbox's <c>EmailNotificationDeliveryAdapter</c> calls when a
+/// <c>SmtpConfiguration</c> selects the EWS transport, mirroring the role
+/// <c>ISmtpClientWrapper</c> plays for the SMTP transport.
+/// </para>
+/// </summary>
+public interface IEwsMailSender
+{
+    /// <summary>
+    /// Sends one message through Exchange Web Services.
+    /// </summary>
+    /// <param name="request">The endpoint, credential, sender, recipients and content to submit.</param>
+    /// <param name="cancellationToken">Token cancelling the send; propagates unwrapped when the caller cancels.</param>
+    /// <returns>A task completing when Exchange has accepted the message.</returns>
+    /// <exception cref="EwsPermanentException">
+    /// The send failed for a reason retrying cannot fix — authentication (401/403), a wrong URL
+    /// (404), a schema fault, or a recipient rejection.
+    /// </exception>
+    /// <exception cref="EwsTransientException">
+    /// The send failed for an availability-shaped reason — network/DNS/timeout, HTTP 5xx/408/429,
+    /// or an <c>ErrorServerBusy</c>-class response code — and is worth retrying.
+    /// </exception>
+    Task SendAsync(EwsSendRequest request, CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Everything one EWS submission needs. Carried per call rather than held on the sender so the
+/// sender stays a stateless singleton and the credential never outlives the request.
+/// </summary>
+/// <param name="Endpoint">The absolute HTTPS EWS URL (for example <c>https://host/EWS/Exchange.asmx</c>).</param>
+/// <param name="Username">The service account, which may be domain-qualified (<c>domain\user</c>).</param>
+/// <param name="Password">The service account password.</param>
+/// <param name="FromAddress">The sending mailbox address.</param>
+/// <param name="BccRecipients">The recipients; all addressed BCC so they cannot see one another.</param>
+/// <param name="Subject">The message subject.</param>
+/// <param name="Body">The plain-text message body.</param>
+/// <param name="TimeoutSeconds">
+/// The per-request timeout; a non-positive value leaves the <see cref="HttpClient"/> default in force.
+/// </param>
+public sealed record EwsSendRequest(
+    Uri Endpoint,
+    string Username,
+    string Password,
+    string FromAddress,
+    IReadOnlyList<string> BccRecipients,
+    string Subject,
+    string Body,
+    int TimeoutSeconds);
+
+/// <summary>
+/// Signals an availability-shaped EWS failure that is worth retrying.
+/// </summary>
+public class EwsTransientException : Exception
+{
+    /// <summary>
+    /// Initializes the exception with a message and optional inner exception.
+    /// </summary>
+    /// <param name="message">Message describing the transient EWS failure; never carries the credential.</param>
+    /// <param name="innerException">Optional underlying transport exception.</param>
+    public EwsTransientException(string message, Exception? innerException = null)
+        : base(message, innerException) { }
+}
+
+/// <summary>
+/// Signals an EWS failure that retrying cannot fix, so the notification parks immediately.
+/// </summary>
+public class EwsPermanentException : Exception
+{
+    /// <summary>
+    /// Initializes the exception with a message and optional inner exception.
+    /// </summary>
+    /// <param name="message">Message describing the permanent EWS failure; never carries the credential.</param>
+    /// <param name="innerException">Optional underlying transport exception.</param>
+    public EwsPermanentException(string message, Exception? innerException = null)
+        : base(message, innerException) { }
+}

src/ZB.MOM.WW.ScadaBridge.NotificationService/ServiceCollectionExtensions.cs

@@ -1,15 +1,17 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.ScadaBridge.NotificationService.Ews;
 
 namespace ZB.MOM.WW.ScadaBridge.NotificationService;
 
 public static class ServiceCollectionExtensions
 {
     /// <summary>
-    /// Registers the shared SMTP delivery primitives consumed by the central Notification
+    /// Registers the shared email delivery primitives consumed by the central Notification
     /// Outbox's <c>EmailNotificationDeliveryAdapter</c>: <see cref="NotificationOptions"/>,
-    /// <see cref="OAuth2TokenService"/>, and the <see cref="ISmtpClientWrapper"/> factory.
+    /// <see cref="OAuth2TokenService"/>, the <see cref="ISmtpClientWrapper"/> factory, and —
+    /// for the EWS transport — <see cref="IEwsMailSender"/> with its named HTTP client.
     /// Central-only — sites no longer deliver notifications (see
     /// <c>Component-NotificationService.md</c>), and the orphaned site-shaped
     /// <c>NotificationDeliveryService</c> + <c>INotificationDeliveryService</c> contract
@@ -30,6 +32,11 @@ public static class ServiceCollectionExtensions
         services.AddSingleton<OAuth2TokenService>();
         services.AddSingleton<Func<ISmtpClientWrapper>>(_ => () => new MailKitSmtpClientWrapper());
 
+        // EWS transport: a named client so the EWS calls get their own handler pool, and a
+        // stateless singleton sender (credentials travel per request, never on the client).
+        services.AddHttpClient(EwsSoapMailSender.HttpClientName);
+        services.TryAddSingleton<IEwsMailSender, EwsSoapMailSender>();
+
         return services;
     }