Rene Nochebuena
b7da0e37ed
The package-doc examples showed a fictional launcher.Register / health.Register API (and launcher.Append as a package func). Corrected to the real wiring: lc.Append + web/health.NewHandler(...).ServeHTTP. Documentation-only. No code, API, or dependency changes; version stays v1.1.0 (the v1.1.0 tag is moved to include this fix). Verified by compiling the corrected pattern against the real API.
57 lines
2.1 KiB
Go
57 lines
2.1 KiB
Go
// Package smtp provides a lifecycle-managed SMTP client for sending email
|
|
// in Einherjar applications.
|
|
//
|
|
// # Overview
|
|
//
|
|
// [New] returns a [Component] that satisfies [lifecycle.Component] lifecycle
|
|
// hooks, [observability.Checkable] with degraded priority, and the [Sender]
|
|
// interface for dispatching email. When [Config.Host] is empty, [New] returns
|
|
// a no-op implementation that logs a warning and silently discards every message —
|
|
// email failure must never block a transaction.
|
|
//
|
|
// # Lifecycle Registration
|
|
//
|
|
// client := smtp.New(logger, cfg)
|
|
// lc.Append(client) // lifecycle: OnInit → OnStop
|
|
//
|
|
// client satisfies [observability.Checkable], so it can back a health endpoint via
|
|
// web/health.NewHandler:
|
|
//
|
|
// srv.Get("/health", health.NewHandler(logger, client).ServeHTTP)
|
|
//
|
|
// # Sending
|
|
//
|
|
// Services depend only on [Sender]. Build a [Message] with a pre-rendered body,
|
|
// then call Send:
|
|
//
|
|
// msg := smtp.Message{
|
|
// To: []string{"alice@example.com"},
|
|
// Subject: "Your receipt",
|
|
// Body: rendered, // pre-rendered string from Template.Render
|
|
// ContentType: "text/html",
|
|
// }
|
|
// if err := mailer.Send(ctx, msg); err != nil {
|
|
// return err
|
|
// }
|
|
//
|
|
// # Template Rendering
|
|
//
|
|
// [ParseFS] wraps stdlib html/template for HTML email rendering. Rendering is
|
|
// intentionally separate from Send — callers render to a string and assign it
|
|
// to Message.Body. This keeps Send unit-testable without template involvement.
|
|
//
|
|
// tmpl, err := smtp.ParseFS(os.DirFS("templates"), "*.html")
|
|
// body, err := tmpl.Render("receipt.html", data)
|
|
// msg := smtp.Message{Body: body, ContentType: "text/html", ...}
|
|
//
|
|
// # Configuration
|
|
//
|
|
// All fields are read from environment variables with the EINHERJAR_SMTP_* prefix:
|
|
//
|
|
// - EINHERJAR_SMTP_HOST — SMTP server hostname (empty = no-op mode)
|
|
// - EINHERJAR_SMTP_PORT — default: 587 (STARTTLS)
|
|
// - EINHERJAR_SMTP_USER — auth username (optional)
|
|
// - EINHERJAR_SMTP_PASSWORD — auth password (optional)
|
|
// - EINHERJAR_SMTP_FROM — envelope sender address
|
|
package smtp
|