Documentation
¶
Overview ¶
Package notifydelivery assembles the email-notification substrate into one startable handle: the settings, preference, and queue stores, the trigger-side enqueuer, the renderer and SMTP sender, and the send worker with its LISTEN/NOTIFY wakeup adapter.
It is the only place that names every layer of the substrate at once. Each layer is a package of its own (pkg/notification for the domain, pkg/notification/smtp for the mail-server settings, internal/notification/* for persistence, rendering, transport and the worker) and knows only the layers below it; the composition happens here.
The package must not import pkg/platform. The composition root (the HTTP server, which owns the portal and admin surfaces the feature serves) passes in the *sql.DB, DSN, encryptor, and branding values it already holds, and brackets Start/Stop around its serve loop.
Index ¶
- Constants
- type AccessNotice
- type ChannelSender
- type Config
- type EventRetractor
- type GeneralRecipients
- type Handle
- func (h *Handle) AlertChannels() *notifyalert.Sender
- func (h *Handle) ChannelActivity(ctx context.Context, name string) (notification.ChannelActivity, error)
- func (h *Handle) Channels() notification.ChannelStore
- func (h *Handle) Enqueuer() *notification.Enqueuer
- func (h *Handle) History() notification.HistoryStore
- func (h *Handle) Inbox() notification.InboxStore
- func (h *Handle) PortalNotifier(stores PortalStores, baseURL string) *PortalNotifier
- func (h *Handle) Prefs() notification.PrefsStore
- func (h *Handle) SendChannelTest(ctx context.Context, name string) error
- func (h *Handle) SendDocumentEmail(ctx context.Context, to string, doc notification.Document) error
- func (h *Handle) SendGuestLink(ctx context.Context, to, link string) error
- func (h *Handle) SendTest(ctx context.Context, to string) error
- func (h *Handle) Settings() smtp.SettingsStore
- func (h *Handle) Start(ctx context.Context)
- func (h *Handle) Stop()
- type PortalNotifier
- func (n *PortalNotifier) NotifyAccessDecision(ctx context.Context, a AccessNotice)
- func (n *PortalNotifier) NotifyAccessRequest(ctx context.Context, a AccessNotice)
- func (n *PortalNotifier) NotifyApprovalDecision(ctx context.Context, a AccessNotice)
- func (n *PortalNotifier) NotifyApprovalRequest(ctx context.Context, approvers []string, a AccessNotice)
- func (n *PortalNotifier) NotifyShare(ctx context.Context, share *portal.Share, ev portal.ShareEvent)
- func (n *PortalNotifier) NotifyThreadEvent(ctx context.Context, thread *portal.Thread, actorEmail, body string, ...)
- func (n *PortalNotifier) NotifyThreadMessage(ctx context.Context, msg threads.MessageNotice)
- func (n *PortalNotifier) RetractThreadMessage(ctx context.Context, eventID string)
- type PortalStores
- type TargetReach
- type ThreadEvents
- type ThreadGrantees
- type ThreadParticipants
Constants ¶
const HistoryRetention = notifyworker.DefaultResolvedRetention
HistoryRetention is how long a resolved row survives before the worker's purge removes it -- the window History can report on. Both surfaces show it so a reader knows the listing is recent history, not an archive.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AccessNotice ¶ added in v1.149.0
type AccessNotice struct {
To, Actor, ItemTitle, ItemID, Message, Link string
}
AccessNotice is one email about a request for access (#2090): To is who is told, Actor who acted, Message the requester's note or the answer.
type ChannelSender ¶ added in v1.158.0
type ChannelSender interface {
Send(ctx context.Context, names []string, key string, p notification.Payload) int
}
ChannelSender posts a payload to named channels. Satisfied by notifyalert.Sender.
type Config ¶
type Config struct {
// DB is the shared platform database pool. Required.
DB *sql.DB
// DSN is the raw database DSN for the LISTEN connection. Empty disables
// LISTEN/NOTIFY; the worker degrades to poll-only.
DSN string
// Encryptor protects the SMTP password at rest. Required (may be a
// nil-wrapping passthrough when encryption is disabled).
Encryptor smtp.StringEncryptor
// Branding is the deployment identity emails render with.
Branding notifyrender.Branding
// DigestHourUTC is the UTC hour daily digests are scheduled for.
DigestHourUTC int
// UnsubscribeURL builds the no-login unsubscribe link for a recipient
// address (#1001). nil omits the footer link from notification emails.
UnsubscribeURL func(email string) string
// ChannelUpstream resolves the api connection a chat or webhook channel
// delivers through to its authorized transport (#1720). nil leaves the
// three HTTP channel kinds undeliverable -- their rows stay pending, as
// email rows do with no mail server -- while email channels, which need
// no connection, keep working.
//
// It is a function rather than a toolkit because this package must not
// import the api gateway: the composition root, which already walks the
// live toolkit registry, resolves the name.
ChannelUpstream notifypost.UpstreamFunc
// Attachments reads a channel document's files at delivery. nil sends
// every attachment as its link.
Attachments notifyworker.AttachmentLoader
}
Config carries everything the substrate needs. No platform types.
type EventRetractor ¶ added in v1.153.2
EventRetractor takes a deleted thread message's text out of the notification queue (#2514). Satisfied by the PostgreSQL queue store.
type GeneralRecipients ¶ added in v1.158.0
type GeneralRecipients interface {
Recipients(ctx context.Context) (people, channels []string, acknowledge bool)
}
GeneralRecipients is who the General feedback list reaches now. Satisfied by internal/portal/generalfeedback.Service.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle owns the running substrate.
func New ¶
New composes the substrate. Returns nil when cfg.DB is nil (no database: the feature is unavailable and every accessor degrades gracefully).
func (*Handle) AlertChannels ¶ added in v1.143.0
func (h *Handle) AlertChannels() *notifyalert.Sender
AlertChannels is how the platform's own alerts reach the channels an operator names for them (#1724): this handle's channel store and enqueuer. Nil-safe: a nil handle yields a nil sender, which sends nothing.
func (*Handle) ChannelActivity ¶ added in v1.143.0
func (h *Handle) ChannelActivity(ctx context.Context, name string) (notification.ChannelActivity, error)
ChannelActivity reports what one channel has done recently.
func (*Handle) Channels ¶ added in v1.134.0
func (h *Handle) Channels() notification.ChannelStore
Channels returns the store the operator's channel records live in, or nil when the feature is unavailable (no database).
func (*Handle) Enqueuer ¶
func (h *Handle) Enqueuer() *notification.Enqueuer
Enqueuer returns the trigger-side entry point. Nil-safe: a nil handle returns a nil enqueuer, whose Notify drops everything.
func (*Handle) History ¶ added in v1.118.0
func (h *Handle) History() notification.HistoryStore
History returns the delivery-history reader the admin monitoring surface and each user's own notification screen read from, or nil when the feature is unavailable. It is the same PostgreSQL store the worker writes through, narrowed to its read contract.
func (*Handle) Inbox ¶ added in v1.153.2
func (h *Handle) Inbox() notification.InboxStore
Inbox returns the read state of each person's own notifications, or nil when the feature is unavailable.
func (*Handle) PortalNotifier ¶
func (h *Handle) PortalNotifier(stores PortalStores, baseURL string) *PortalNotifier
PortalNotifier builds the portal-facing notifier over this handle's enqueuer. Returns nil when the handle is nil (feature unavailable); the caller must then leave the portal's Notifier dependency unset.
func (*Handle) Prefs ¶
func (h *Handle) Prefs() notification.PrefsStore
Prefs returns the preference store, or nil when the feature is unavailable.
func (*Handle) SendChannelTest ¶ added in v1.134.0
SendChannelTest delivers a test message to one channel immediately and reports what its upstream said.
It bypasses the queue deliberately, and unlike every other send in this package that is not a shortcut but the point: an administrator pressing "send test" is asking whether this configuration works, so the answer has to be the transport's own, now, in the response they are waiting on. A queued test would report only that a row was written, which is the one thing never in doubt.
A disabled channel is still tested: the administrator is configuring it, and refusing to test until it is enabled would mean enabling it untested.
func (*Handle) SendDocumentEmail ¶ added in v1.134.0
SendDocumentEmail renders one document as a branded email and sends it directly, outside the queue. It is the transactional counterpart of a queued channel row, used by the admin test send.
func (*Handle) SendGuestLink ¶ added in v1.106.0
SendGuestLink delivers a one-time view link email directly through the sender (#1001). The send is transactional: the recipient requested it from a share landing page, so it bypasses the queue (no digest deferral) and the preference gate (an opted-out recipient still gets the link they asked for). It uses the same stored SMTP settings and deliverability gate as every other send.
func (*Handle) SendTest ¶
SendTest delivers a test email to the given recipient using the currently stored SMTP settings, so an admin can verify the configuration end to end.
The admin API answers a failed test with fixed text that does not vary with the failure mode (#1072), so this log is the only place the underlying error survives. Every failure below is therefore recorded, with the host and port that produced it.
func (*Handle) Settings ¶
func (h *Handle) Settings() smtp.SettingsStore
Settings returns the settings store, or nil when the feature is unavailable.
type PortalNotifier ¶
type PortalNotifier struct {
// contains filtered or unexported fields
}
PortalNotifier implements portal.Notifier: it turns portal share and thread events into queued email notifications. All failures are logged, never surfaced -- a share or comment must succeed regardless of notification state.
func NewPortalNotifier ¶
func NewPortalNotifier(enq *notification.Enqueuer, stores PortalStores, baseURL string) *PortalNotifier
NewPortalNotifier builds a notifier over an enqueuer directly; tests and the handle-based constructor below share it.
func (*PortalNotifier) NotifyAccessDecision ¶ added in v1.149.0
func (n *PortalNotifier) NotifyAccessDecision(ctx context.Context, a AccessNotice)
NotifyAccessDecision tells a requester how their request was answered; approved, the link opens the item.
func (*PortalNotifier) NotifyAccessRequest ¶ added in v1.149.0
func (n *PortalNotifier) NotifyAccessRequest(ctx context.Context, a AccessNotice)
NotifyAccessRequest tells an item's owner that someone asked for access to it, with the link to the requests waiting on them.
func (*PortalNotifier) NotifyApprovalDecision ¶ added in v1.153.2
func (n *PortalNotifier) NotifyApprovalDecision(ctx context.Context, a AccessNotice)
NotifyApprovalDecision tells a requester how their request was decided.
func (*PortalNotifier) NotifyApprovalRequest ¶ added in v1.153.2
func (n *PortalNotifier) NotifyApprovalRequest(ctx context.Context, approvers []string, a AccessNotice)
NotifyApprovalRequest tells each approver that a request waits on them (#2437, #2494), once, with the link to the Approvals page.
func (*PortalNotifier) NotifyShare ¶
func (n *PortalNotifier) NotifyShare(ctx context.Context, share *portal.Share, ev portal.ShareEvent)
NotifyShare queues a "shared with you" email for a direct share. Token-only shares (no recipient email) queue nothing: a share targeted by user ID alone carries no email address anywhere in the system.
func (*PortalNotifier) NotifyThreadEvent ¶
func (n *PortalNotifier) NotifyThreadEvent(ctx context.Context, thread *portal.Thread, actorEmail, body string, mentioned []string)
NotifyThreadEvent queues the notifications one thread event produces. It is NotifyThreadMessage for a caller that does not name the message.
func (*PortalNotifier) NotifyThreadMessage ¶ added in v1.153.2
func (n *PortalNotifier) NotifyThreadMessage(ctx context.Context, msg threads.MessageNotice)
NotifyThreadMessage queues the notifications one message produces: a mention for each person the body named, and a "new comment/feedback" notification for everyone else attached to the thread -- the target's owner, the people it is shared with, and its participants: the thread's author, everyone who wrote in it and everyone mentioned in it (#2512). Every one of them must be able to open the target now; a person who lost access is told nothing. Each row names the message, so deleting it can take its text back out of the queue (#2514).
Mentions are queued first, per recipient: the author chose those addresses, so each one costs a token of their rate limit. The general fan-out then goes out as one batch, because who a thread involves is a property of the thread rather than something the author picked.
Only a mention that was actually queued removes someone from the general fan-out. A recipient whose mention was dropped -- they muted the mention category, or the enqueue failed -- has been told nothing, so they still get the comment notification they would have had without being named.
func (*PortalNotifier) RetractThreadMessage ¶ added in v1.153.2
func (n *PortalNotifier) RetractThreadMessage(ctx context.Context, eventID string)
RetractThreadMessage removes a deleted message's text from every notification it produced and drops the ones not yet sent (#2514).
type PortalStores ¶
type PortalStores struct {
Assets portal.AssetStore
Collections portal.CollectionStore
Prompts portal.PromptStore
KnowledgePages knowledgepage.Store
// Grantees lists the people holding an explicit grant on a thread target.
// Optional: nil narrows thread notifications to the target owner and the
// thread author.
Grantees ThreadGrantees
// External reports whether an address has an external account (#2092).
// An internal thread notifies none of them (#2227). nil treats no address
// as one.
External func(ctx context.Context, email string) bool
// Participants lists the people a thread involves: everyone who wrote a
// message in it and everyone a message mentions (#2512). nil narrows the
// fan-out to the owner, the thread author and the grantees.
Participants ThreadParticipants
// Reach reports whether a person can open a thread's target now, by the
// rule the target's read applies (#2512). Every comment recipient passes
// it, so a person who lost access is told nothing. nil checks nobody.
Reach TargetReach
// General names who hears about a thread on the General (standalone)
// channel, which has no owner, and about a thread whose target's owner
// cannot be found (#2603). nil tells nobody beyond the thread's own people.
General GeneralRecipients
// Channels posts a new General thread to the channels the list names;
// nil posts to none.
Channels ChannelSender
// Events reads a thread's messages, to name a reply on a thread that has
// no item and no stored title by its first line (#2603). nil names it
// generically.
Events ThreadEvents
}
PortalStores bundles the read access the notifier needs to resolve a thread's target (title, deep link, owner email) and the people attached to it.
type TargetReach ¶ added in v1.153.2
type TargetReach interface {
CanOpen(ctx context.Context, email, targetType, targetID string) bool
}
TargetReach reports whether the person at an address can open a thread target. Satisfied by internal/portal/threadreach.Reach.
type ThreadEvents ¶ added in v1.158.0
type ThreadEvents interface {
ListEvents(ctx context.Context, threadID string) ([]threads.ThreadEvent, error)
}
ThreadEvents lists a thread's messages, oldest first. Satisfied by the PostgreSQL thread store.
type ThreadGrantees ¶ added in v1.114.0
type ThreadGrantees interface {
Grantees(ctx context.Context, targetType, targetID string) ([]string, error)
}
ThreadGrantees lists the addresses holding an explicit grant on a thread target: its owner and the recipients of active shares. Satisfied by pkg/portal/mention.Audience.