Documentation
¶
Overview ¶
Package notify tells someone about alerts (docs/PHASE3.md §9.3): one digest per evaluation and channel, sent by e-mail (net/smtp) or as a signed webhook, queued in system.db with retries. The channels and their secrets come from the configuration and files, never from the database, so a sealed server still reports that it is sealed.
Index ¶
Constants ¶
const ( Opened = "opened" // new alert Raised = "raised" // warning → critical Reminder = "reminder" // still open after repeat_every Resolved = "resolved" Test = "test" // `myownpki notify test` )
States of an event in a digest.
const ActionTest = "notification.test"
ActionTest is the audit action of a test message.
const SignatureHeader = "X-MyOwnPKI-Signature"
SignatureHeader carries the HMAC-SHA256 of the body: "sha256=<hex>".
Variables ¶
var ErrNoChannel = errors.New("no notification channel is configured – set notify.email or notify.webhook in the server's configuration")
ErrNoChannel: nothing to test, because neither notify.email nor notify.webhook is configured.
var Retries = []time.Duration{time.Minute, 5 * time.Minute, 30 * time.Minute, 2 * time.Hour}
Retries are the waits after the 1st, 2nd, … failed attempt; after the last one the message is dropped (and logged as an error).
Functions ¶
Types ¶
type Digest ¶
type Digest struct {
Server string `json:"server"`
Created time.Time `json:"created"`
Events []Event `json:"events"`
}
Digest is one message: everything that changed in one evaluation.
func ParseDigest ¶
ParseDigest reads a queued payload.
func TestDigest ¶
TestDigest is the message of `myownpki notify test`.
type Email ¶
type Email struct {
Addr string // host:port
Security string // config.SMTPStartTLS, SMTPTLS or SMTPNone
Username string
PasswordFile string
From string
To []string
CAFile string // extra roots; "" = the system roots
Hello string // name for EHLO; "" = localhost
}
Email sends a digest over SMTP.
type Event ¶
type Event struct {
Kind string `json:"kind"`
Subject string `json:"subject"`
Severity string `json:"severity"`
State string `json:"state"`
Since time.Time `json:"since"`
Detail string `json:"detail"`
Link string `json:"link,omitempty"`
}
Event is one alert in a digest.
type Queue ¶
type Queue struct {
DB *sql.DB // system.db, the write connection
Log *slog.Logger
Channels []Channel
}
Queue delivers the queued digests of system.db.
func (*Queue) Deliver ¶
Deliver sends every due message once. A failure schedules the next attempt; the error is logged, never returned – one broken channel must not stop the other one.
type Result ¶
type Result struct {
Channel string `json:"channel"`
OK bool `json:"ok"`
Error string `json:"error,omitempty"`
}
Result is the outcome of one channel. Error is the channel's own error text, shortened: never a secret (password, HMAC key, webhook path or query), but it may name hosts, file paths and recipient addresses.
type Tester ¶
type Tester struct {
Channels []Channel
Server string // the host name in the message
Clock clock.Clock
Audit *sql.DB // writer of the tenant's audit log
Scope string
Tenant string
// contains filtered or unexported fields
}
Tester sends the test message of the web UI and the REST API (`myownpki notify test` uses SendAll directly). It checks the role, sends synchronously and audits the attempt.
func (*Tester) Send ¶
Send checks that who may send a test (tenant admin), sends it through every channel and appends one audit entry with the result per channel – never a secret (password, HMAC key, webhook path or query); the error texts may name hosts, file paths and recipient addresses. A refusal is audited as denied; with no channel there is nothing to send and nothing to audit. The audit entry is written after the send (it holds the result), so an audit failure is reported although the message went out.
Source Files