Documentation
¶
Overview ¶
Package notify implements the warden.INotifier delivery backends used by the watchdog:
- SMTPNotifier sends incident emails over STARTTLS (production).
- LogNotifier writes a structured log line via core.Logger (used when SMTP is not configured).
- FileNotifier appends one JSON-encoded incident per line to a file (used by the e2e harness).
(A test that wants to assert on calls rather than deliver anywhere uses the generated warden.INotifier mock instead; see services/warden/internal/mocks.)
All notifiers are safe for concurrent use, which is the contract the watchdog relies on when it delivers from short-lived goroutines. The SMTP notifier fails closed: it refuses to transmit credentials or mail if the server does not advertise STARTTLS, so secrets never traverse a cleartext link. That refusal is deliberate behaviour, reported as ErrSTARTTLSRequired — a caller must not "fall back" to plaintext around it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Compatibility aliases preserve errors.Is behavior for existing callers. ErrSTARTTLSRequired = sharedemail.ErrSTARTTLSRequired ErrAuthUnsupported = sharedemail.ErrAuthUnsupported ErrNoRecipients = sharedemail.ErrNoRecipients ErrNoSender = sharedemail.ErrNoSender ErrHeaderInjection = sharedemail.ErrHeaderInjection )
Functions ¶
This section is empty.
Types ¶
type FileNotifier ¶
type FileNotifier struct {
// contains filtered or unexported fields
}
FileNotifier appends one JSON-encoded incident per line to a file. It is used by the e2e harness as a durable, greppable sink.
It is safe for concurrent use without any lock: each Notify opens the file with O_APPEND, writes the fully marshaled line (a single []byte, one Write syscall) and closes it. On a local filesystem the kernel guarantees an O_APPEND write is positioned at end-of-file and applied atomically, so concurrent callers never interleave or lose lines.
func NewFileNotifier ¶
func NewFileNotifier(path string) *FileNotifier
NewFileNotifier returns a FileNotifier writing to path.
type LogNotifier ¶
type LogNotifier struct{}
LogNotifier delivers incidents by writing a structured log line via core.Logger. It is the default notifier when SMTP is not configured. It holds no mutable state and core.Logger is safe for concurrent use, so no synchronization is needed.
type SMTPConfig ¶
type SMTPConfig struct {
Host string
Port int
Username string
Password string
From string
To []string
}
SMTPConfig preserves the Warden configuration surface while delegating transport and message policy to services/email.
type SMTPNotifier ¶
type SMTPNotifier struct {
// contains filtered or unexported fields
}
SMTPNotifier adapts Warden incidents to the shared Mailer.
func NewSMTPNotifier ¶
func NewSMTPNotifier(config SMTPConfig, options ...SMTPOption) *SMTPNotifier
NewSMTPNotifier preserves the historical one-argument call while accepting host provenance, durable receipt, and metrics options.
type SMTPOption ¶
type SMTPOption func(config *smtpNotifierConfig) error
SMTPOption configures the Warden adapter without changing existing callers.
func WithMetrics ¶
func WithMetrics(registerer prometheus.Registerer) SMTPOption
WithMetrics registers the shared bounded email metrics.
func WithProvenance ¶
func WithProvenance(source sharedemail.IProvenanceSource) SMTPOption
WithProvenance configures host-observed provenance. When absent or failing, the notifier still identifies the incident's ReportedBy node.
func WithReceiptSink ¶
func WithReceiptSink(sink sharedemail.IReceiptSink) SMTPOption
WithReceiptSink configures durable receipt evidence retention.
type TerminalDeliveryError ¶
type TerminalDeliveryError struct {
Outcome emailv1.DeliveryOutcome
ErrorCode string
ReceiptID string
// contains filtered or unexported fields
}
TerminalDeliveryError marks an outcome that the watchdog must not blindly retry because the remote server may already have accepted the message.
func (*TerminalDeliveryError) Error ¶
func (deliveryError *TerminalDeliveryError) Error() string
Error returns a bounded description without SMTP details or addresses.
func (*TerminalDeliveryError) Retryable ¶
func (deliveryError *TerminalDeliveryError) Retryable() bool
Retryable prevents blind retransmission of a possibly accepted message.
func (*TerminalDeliveryError) Unwrap ¶
func (deliveryError *TerminalDeliveryError) Unwrap() error
Unwrap exposes the underlying operational error to errors.Is/errors.As.
Source Files