dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine Notification Service: SMTP config, OAuth2, delivery behavior, error handling

Browse Source 
Expand SMTP configuration with OAuth2 Client Credentials support for Microsoft 365,
connection timeout, and max concurrent connections. Single email per send with all
recipients in BCC. Plain text only. Classify SMTP errors: transient (4xx/connection)
to S&F, permanent (5xx) returned to script. No app-level rate limiting.
This commit is contained in:
Joseph Doherty
2026-03-16 08:38:38 -04:00
parent cd03b77913
commit a540912782
2 changed files with 74 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/plans/2026-03-16-notification-service-refinement-design.md Normal file
View File

@@ -0,0 +1,45 @@
# Notification Service Refinement — Design
**Date**: 2026-03-16
**Component**: Notification Service (`Component-NotificationService.md`)
**Status**: Approved
## Problem
The Notification Service doc covered notification lists and the script API but lacked concrete SMTP configuration details, OAuth2 support for Microsoft 365, delivery behavior (recipient handling, error classification), and content format specification.
## Decisions
### SMTP Configuration
- Standard fields: server hostname, port, TLS mode, from address.
- **Dual authentication modes**: Basic Auth (username/password) for on-prem relays, and OAuth2 Client Credentials (Tenant ID, Client ID, Client Secret) for Microsoft 365.
- OAuth2 token lifecycle (fetch, cache, refresh) handled internally by the Notification Service.
- Connection timeout (default 30s) and max concurrent connections (default 5) configurable.
### Email Delivery
- **Single email per send** with all recipients in BCC. From address in To field. Recipients don't see each other.
- **Plain text only** — no HTML content. Operational notifications don't need rich formatting.
### Error Classification
- Consistent with External System Gateway pattern:
- **Transient failures** (connection errors, SMTP 4xx): Go to Store-and-Forward for retry.
- **Permanent failures** (SMTP 5xx): Error returned synchronously to calling script. No retry.
### Rate Limiting
- **No application-level rate limiting**. SMTP server limits (e.g., Microsoft 365 throttling) manifest as transient failures handled by S&F naturally.
## Affected Documents
| Document | Change |
|----------|--------|
| `Component-NotificationService.md` | Expanded SMTP configuration with OAuth2 support, connection settings. Added Email Delivery Behavior section (recipient handling, error classification, rate limiting). Specified plain text content. |
## Alternatives Considered
- **Basic Auth only**: Rejected — Microsoft 365 has deprecated basic auth for SMTP. OAuth2 Client Credentials is required.
- **Individual email per recipient**: Rejected — adds SMTP traffic and S&F complexity for rare partial-failure scenario.
- **All recipients in To (visible)**: Rejected — BCC is safer, avoids exposing email addresses across teams.
- **All SMTP failures to S&F**: Rejected — permanent 5xx errors (bad address) would waste buffer space and never succeed.
- **HTML email support**: Rejected — YAGNI. Operational notifications are plain text. HTML adds injection risk with script-generated content.
- **App-level rate limiting**: Rejected — SMTP server enforces its own limits. S&F handles transient throttling naturally.
- **No OAuth2 / connection tuning**: Rejected — user requires Microsoft 365 support (OAuth2 mandatory) and wants connection timeout/concurrency control.