Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterProvider ¶
func RegisterProvider(name string, factory ProviderFactory) error
RegisterProvider registers a named mail provider factory.
func RegisteredProviders ¶
func RegisteredProviders() []string
RegisteredProviders returns the currently registered provider names sorted alphabetically. Built-in providers are included.
func SetPluginHost ¶
SetPluginHost overrides the plugin runtime host used for external providers. Passing nil resets the default local executable host.
Types ¶
type CircuitBreakerConfig ¶
type CircuitBreakerConfig struct {
// Enabled turns on circuit-breaker wrapping around Send.
Enabled bool `koanf:"enabled"`
// FailureThreshold is the number of consecutive Send failures
// required to trip the breaker open. Non-positive falls back to
// pkg/circuit's default (1).
FailureThreshold int `koanf:"failure_threshold"`
// Cooldown is the duration the breaker stays open before admitting
// half-open probes. Non-positive falls back to pkg/circuit's
// default (30s).
Cooldown time.Duration `koanf:"cooldown"`
// HalfOpenMaxConcurrent caps in-flight probes in the half-open
// state. Non-positive falls back to pkg/circuit's default (1).
HalfOpenMaxConcurrent int `koanf:"half_open_max_concurrent"`
}
CircuitBreakerConfig configures the optional circuit breaker that wraps mail sender Send calls. Zero values are not used directly; pkg/app applies framework defaults before constructing the breaker.
The breaker is wrapped around Send only. Healthy (when the underlying sender implements HealthChecker) bypasses the breaker so /healthz can observe a recovering dependency even while Send is short-circuited.
type Config ¶
type Config struct {
Driver string
Timeout time.Duration
// SMTP
SMTPHost string
SMTPPort int
SMTPUser string
SMTPPass string
// CircuitBreaker, when Enabled, wraps the returned Sender.Send
// with a pkg/circuit breaker. Healthy (if the underlying provider
// implements HealthChecker) bypasses the breaker so /healthz
// observes a recovering dependency.
CircuitBreaker CircuitBreakerConfig
// Logger receives the circuit breaker's state-transition lines
// (NF-9: the breaker used to open and close in silence). Nil falls
// back to slog.Default().
Logger *slog.Logger
}
Config holds provider-agnostic and provider-specific mail settings. Only protocol-universal providers (SMTP) ship in-tree; provider- specific senders (SendGrid, Mailgun, AWS SES, Postmark, …) are installed as `nucleus-plugin-<provider>` binaries on PATH and discovered via the external sender. The `mail.send` capability contract is documented in `docs/reference/PLUGIN_SDK.md`.
type HealthChecker ¶
HealthChecker is an optional interface a Sender may implement to expose a non-destructive liveness check. The /healthz handler in pkg/app type-asserts for this interface; senders that do not implement it are not probed (so the response stays free of information-free "skipped" rows).
Implementations should keep Healthy cheap and non-destructive — at minimum, no actual mail is sent. For SMTP that means a TCP dial plus HELO/QUIT; for HTTP API providers it typically means a HEAD against a documented health endpoint.
type Message ¶
type Message struct {
From string
To []string
Subject string
Body string
// Headers holds optional custom headers appended after the
// framework-generated ones (From, To, Subject, MIME-Version,
// Content-Type). The built-in senders (SMTP and external
// plugins) validate the map on Send: a key must be non-empty
// and neither key nor value may contain CR or LF, so
// caller-supplied input cannot inject additional headers (e.g.
// an extra Bcc). Values are trimmed; a header whose value is
// empty after trimming is omitted. Custom providers registered
// via RegisterProvider are responsible for their own emission.
Headers map[string]string
}
Message represents one outbound email.
type ProviderFactory ¶
ProviderFactory builds a Sender from provider-specific configuration.
Source Files