Documentation
¶
Overview ¶
Package ingest receives provider events: the webhook endpoint (POST /hooks/{adapter}/{token}) verifies the signature, stores the raw payload and answers immediately; a River job normalizes it later. SMTP bounces arrive through the bounce mailbox poller and take the same path.
Index ¶
- Constants
- func RegisterLog(h huma.API, e *EventLog)
- func SourceLabel(campaign, automation string, node *string, kind string) string
- type BackfillWorker
- type Engagement
- type EngagementBatch
- type EventLog
- type Handler
- type LogFilter
- type MailboxArgs
- type MailboxWorker
- type MessageHook
- type NormalizeArgs
- type NormalizeWorker
- type Normalizer
- func (n *Normalizer) Apply(ctx context.Context, tx pgx.Tx, p store.Provider, rawID *uuid.UUID, ...) (int, error)
- func (n *Normalizer) ApplyAll(ctx context.Context, tx pgx.Tx, p store.Provider, rawID *uuid.UUID, ...) (int, error)
- func (n *Normalizer) Backfill(ctx context.Context, providerID uuid.UUID) (int, error)
- func (n *Normalizer) Normalize(ctx context.Context, rawID uuid.UUID) error
- type ProviderEngagement
- type ProviderEventLog
- type ProviderLogEvent
- type SweepArgs
- type SweepWorker
- type Tokens
Constants ¶
const MaxBody = 5 << 20
MaxBody is the largest webhook payload accepted.
const RetentionDays = 90
RetentionDays is how long raw payloads and the event log are kept.
Variables ¶
This section is empty.
Functions ¶
func RegisterLog ¶
RegisterLog adds the event log operations.
Types ¶
type BackfillWorker ¶
type BackfillWorker struct {
river.WorkerDefaults[manage.BackfillArgs]
N *Normalizer
}
BackfillWorker pulls message status from a provider's API for messages that got no webhook event (manage.BackfillArgs).
func (*BackfillWorker) Timeout ¶
func (w *BackfillWorker) Timeout(*river.Job[manage.BackfillArgs]) time.Duration
Timeout bounds one backfill.
func (*BackfillWorker) Work ¶
func (w *BackfillWorker) Work(ctx context.Context, job *river.Job[manage.BackfillArgs]) error
Work implements river.Worker.
type Engagement ¶
type Engagement interface {
// Begin starts a transaction's opens and clicks. Their counter moves
// go to ledger, which the normalizer flushes with the transaction's
// other moves; the batch's Flush applies the rest (the contacts'
// activity) after everything else, in contact order.
Begin(ledger *counters.Ledger) EngagementBatch
}
Engagement records provider-reported opens and clicks (the tracking service implements it).
type EngagementBatch ¶
type EngagementBatch interface {
Record(ctx context.Context, tx pgx.Tx, ev ProviderEngagement) error
Flush(ctx context.Context, q *store.Queries) error
}
EngagementBatch records one transaction's provider opens and clicks.
type EventLog ¶
type EventLog struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Now func() time.Time
}
EventLog serves the provider event log.
type Handler ¶
type Handler struct {
Pool *pgxpool.Pool
Q *store.Queries
Factory *manage.Factory
Jobs func() *jobs.Client
Log *slog.Logger
Now func() time.Time
}
Handler serves the webhook endpoint.
func (*Handler) ServeHTTP ¶
func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP verifies, stores and acknowledges one webhook request.
func (*Handler) Validate ¶
func (h *Handler) Validate(w http.ResponseWriter, r *http.Request)
Validate answers the CloudEvents webhook validation handshake (an OPTIONS request with WebHook-Request-Origin, as Azure Event Grid sends before it delivers CloudEvents): only a known webhook URL is confirmed.
type MailboxArgs ¶
type MailboxArgs struct{}
MailboxArgs polls the bounce mailboxes of SMTP providers.
func (MailboxArgs) InsertOpts ¶
func (MailboxArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type MailboxWorker ¶
type MailboxWorker struct {
river.WorkerDefaults[MailboxArgs]
N *Normalizer
Jobs func() *jobs.Client
// Open overrides bouncebox.Open (tests).
Open func(ctx context.Context, c bouncebox.Config) (bouncebox.Box, error)
// OnPoll is told how each read of a bounce mailbox went, so a mailbox
// that can't be read reaches the provider's health (PR-10).
OnPoll func(ctx context.Context, p store.Provider, err error)
}
MailboxWorker reads bounce reports from every SMTP provider's mailbox.
func (*MailboxWorker) Poll ¶
Poll reads up to 200 new reports from a provider's bounce mailbox, stores each as a raw event and queues its normalization.
func (*MailboxWorker) Timeout ¶
func (w *MailboxWorker) Timeout(*river.Job[MailboxArgs]) time.Duration
Timeout bounds one poll.
func (*MailboxWorker) Work ¶
func (w *MailboxWorker) Work(ctx context.Context, _ *river.Job[MailboxArgs]) error
Work implements river.Worker.
type MessageHook ¶
type MessageHook func(ctx context.Context, tx pgx.Tx, p store.Provider, messageID uuid.UUID, stream string, ev providers.Event) error
MessageHook is told about an event applied to a message of a stream.
type NormalizeArgs ¶
NormalizeArgs normalizes one stored webhook payload.
func (NormalizeArgs) InsertOpts ¶
func (NormalizeArgs) InsertOpts() river.InsertOpts
InsertOpts puts normalization on the events queue.
type NormalizeWorker ¶
type NormalizeWorker struct {
river.WorkerDefaults[NormalizeArgs]
N *Normalizer
}
NormalizeWorker is the River worker for NormalizeArgs.
func (*NormalizeWorker) Work ¶
func (w *NormalizeWorker) Work(ctx context.Context, job *river.Job[NormalizeArgs]) error
Work implements river.Worker.
type Normalizer ¶
type Normalizer struct {
Pool *pgxpool.Pool
Q *store.Queries
Factory *manage.Factory
Log *slog.Logger
Now func() time.Time
// OnSuppressed is called after new addresses joined the shared
// suppression list, so other providers get them soon (sync job).
OnSuppressed func(ctx context.Context, workspaceID uuid.UUID)
// Hooks are told about each event applied to a known message, inside
// the transaction that applied it (transactional mail's webhooks).
Hooks []MessageHook
// Engagement counts the opens and clicks a provider reports when the
// workspace keeps the provider's tracking (review AN-4); without it
// they are only logged.
Engagement Engagement
}
Normalizer turns raw provider events into ReputeCast's model.
func (*Normalizer) Apply ¶
func (n *Normalizer) Apply(ctx context.Context, tx pgx.Tx, p store.Provider, rawID *uuid.UUID, source string, receivedAt time.Time, ev providers.Event) (int, error)
Apply records one normalized event: the delivery event, the message's state, campaign counters, provider outcome stats and, for hard bounces, complaints and provider unsubscribes, the shared suppression list. It returns how many addresses were newly suppressed. A caller applying several events in one transaction uses ApplyAll, so the rows they share are locked once, in key order.
func (*Normalizer) ApplyAll ¶
func (n *Normalizer) ApplyAll(ctx context.Context, tx pgx.Tx, p store.Provider, rawID *uuid.UUID, source string, receivedAt time.Time, evs []providers.Event) (int, error)
ApplyAll records a payload's events in one transaction: the messages they name in id order (the order every writer locks messages in), then what they change beyond them (counters, provider stats, the suppression list), each in key order.
type ProviderEngagement ¶
type ProviderEngagement struct {
EventID uuid.UUID
MessageID uuid.UUID
Click bool
// URL is the clicked link as the provider reports it (the email's own
// link, before the provider's redirect).
URL string
UserAgent string
IP string
At time.Time
}
ProviderEngagement is an open or a click a provider reported, already stored as the delivery event EventID.
type ProviderEventLog ¶
type ProviderEventLog struct {
Items []ProviderLogEvent `json:"items"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"pageSize"`
RetentionDays int `json:"retentionDays"`
}
ProviderEventLog is one page of the event log.
type ProviderLogEvent ¶
type ProviderLogEvent struct {
ID string `json:"id"`
ReceivedAt time.Time `json:"receivedAt"`
OccurredAt time.Time `json:"occurredAt"`
ProviderID string `json:"providerId,omitempty"`
Provider string `json:"provider"`
// Channel is how the event arrived: a webhook, the bounce mailbox, a
// provider's queue (SES through SQS), a backfill, or ReputeCast itself.
Channel string `json:"channel" enum:"webhook,bounce_mailbox,queue,backfill,test,internal"`
RawType string `json:"rawType"`
Type string `json:"type" enum:"delivered,deferred,hard_bounce,soft_bounce,complaint,rejected"`
Code string `json:"code"`
Diagnostic string `json:"diagnostic"`
BounceClass string `json:"bounceClass"`
Recipient string `json:"recipient" doc:"Masked"`
ProviderMsgID string `json:"providerMessageId"`
Source string `json:"source"`
CampaignID string `json:"campaignId,omitempty"`
}
ProviderLogEvent is one row of the event log: the raw provider event beside the normalized ReputeCast event and the original code.
type SweepArgs ¶
type SweepArgs struct{}
SweepArgs re-queues payloads whose normalization never finished and purges raw payloads past retention.
func (SweepArgs) InsertOpts ¶
func (SweepArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type SweepWorker ¶
type SweepWorker struct {
river.WorkerDefaults[SweepArgs]
N *Normalizer
Jobs func() *jobs.Client
}
SweepWorker runs SweepArgs.
type Tokens ¶
Tokens keeps the one-time tokens of webhook signatures that cover a token but not the event (Mailgun's) in webhook_tokens, where every process and every restart sees them (providers.TokenStore). The sweep drops them once their signature is no longer accepted.
func (Tokens) BindToken ¶
func (t Tokens) BindToken(ctx context.Context, scope string, token, payload [32]byte, now, expires time.Time) ([32]byte, error)
BindToken implements providers.TokenStore in one statement: of two requests with the same token at once, the second gets the first one's payload back.