notify

type Announcement struct {
	// Kind is what happened, as the application names it. A string here and the
	// project's own Go enum type when it narrows rig_notification.kind to a
	// Postgres enum of its own — worth doing for one reason, which is that a
	// switch over kinds inside NotifyWho becomes one the compiler can see.
	Kind string

	// Subject is the row this is about. A generated helper builds it, so the
	// table name is written by rig and never by a request.
	Subject Subject

	// Payload is what a template needs beyond the linked row. It is stored as
	// jsonb and handed back whole; give the column a Go type with the `go_type`
	// key if it has a shape.
	Payload json.RawMessage

	// At is when this is due, and Due is whether it is due at all.
	//
	// They come from the subject's own NotifyAt, called by the hook that
	// announces — where the row is in hand. The zero time with Due means now,
	// which is the ordinary case and is not a special path: an immediate
	// notification and one scheduled for Friday are the same row with a
	// different column.
	//
	// Due false writes the notification and cancels it. The row is still
	// written and still linked, because a notification that was decided against
	// is a thing that happened and something has to be able to say so.
	At  time.Time
	Due bool

	// Group collapses several events into one inbox line. Nil is one line per
	// event; [GroupBySubject] is the ordinary answer; [GroupBy] sets a coarser
	// key of your own.
	Group *string

	// AccountIDs skips NotifyWho for this announcement, and is the documented
	// exception to everything above.
	//
	// Some audiences genuinely cannot be re-derived: the five people who were
	// @-mentioned in a body that has since been edited. Without this, NotifyWho
	// would have to read a version row to reconstruct a list somebody already
	// had in their hand.
	//
	// It is named as the exception rather than offered as the parameter, because
	// a list captured at write time is a list that stops being true, and that is
	// what late resolution exists to prevent.
	AccountIDs []uuid.UUID
}

type Channel string

type Config struct {
	// DB is the pool the subject tables are in. The same one, deliberately: an
	// announcement is written in the transaction that caused it, and it cannot
	// be if the two live in different pools.
	DB DB

	// Registry is how the dispatcher reaches each notifiable table's answers.
	// Nil resolves nothing and says so in every report.
	Registry *Registry

	// Now is the clock, so a test can move it. Nil means time.Now.
	Now func() time.Time
}

type DB = dbx.Pool

type Delivery struct {
	// ID is stable across retries, and it is the whole of what rig can do about
	// exactly-once.
	//
	// Hand it to the provider as its own idempotency key — Message-ID, apns-id,
	// whatever the SDK calls it. rig cannot enforce that, and saying so is
	// better than implying exactly-once and letting somebody find out: the send
	// and the bookkeeping are two systems, no transaction spans both, and a
	// process that handed a message over and died will hand it over again when
	// its lease expires.
	ID uuid.UUID

	TenantID    uuid.UUID
	AccountID   uuid.UUID
	RecipientID uuid.UUID

	Channel Channel
	Kind    string
	// Digest is what the setting said when this row was written. Immediate rows
	// go out on their own; the rest are batched per account and channel.
	Digest Digest

	// Attempts is how many times this has been claimed, including this one.
	Attempts  int
	DeliverAt time.Time
}

type DeliveryState string

type Device struct {
	ID        uuid.UUID
	AccountID uuid.UUID
	Channel   Channel
	// Token is what the provider was given. Opaque to rig.
	Token string
	// Label is what a person sees in a list of their devices, and the field that
	// makes revoking one possible for somebody who has four.
	Label      string
	LastSeenAt *time.Time
}

type Digest string

type DispatchReport struct {
	// Claimed is how many rows this pass took, Sent how many a channel
	// accepted, and Failed how many reached max_attempts and stopped.
	Claimed int
	Sent    int
	Failed  int
	// Retrying is how many failed this time and will be tried again.
	Retrying int
	// Rejected is how many a channel refused permanently, with [Permanent], and
	// which were failed on this attempt rather than spending the rest of the
	// schedule.
	//
	// It is worth telling apart from Failed because the two mean opposite things
	// about the provider. A rising Failed is rig giving up after eight hours of
	// trying; a rising Rejected is the provider answering immediately and
	// definitively, which usually means a list of addresses has gone stale
	// rather than that anything is wrong.
	Rejected int
	// Deferred is how many were rescheduled at a channel's own request, with
	// [RetryAfter], rather than on the computed backoff.
	//
	// A steady non-zero one is a provider telling this project it is sending too
	// fast, which is a different problem from a provider being down and is not
	// visible in Retrying, where it would otherwise be counted.
	Deferred int
	// Held is how many were outside somebody's window and moved to its next
	// opening rather than being sent or dropped.
	Held int
	// Digested is how many were folded into a message with others.
	Digested int
	// Released is how many claims a clean shutdown gave back rather than
	// leaving to expire.
	Released int
	// Abandoned is how many the pass did not reach because the lease ran out
	// before it got to them.
	//
	// It is the number that says a channel is slow enough to be a problem. Zero
	// is the ordinary case and a steady non-zero one means the batch cannot be
	// sent inside a claim — either the provider got slower or claim_ttl and
	// send_timeout no longer fit each other. Those rows are Pending again, with
	// the attempt the claim charged them given back, so nothing is lost; what is
	// lost is the assumption that a pass drains what it claims.
	Abandoned int
}

type Engine struct {
	// contains filtered or unexported fields
}

type EngineConfig struct {
	Config

	// Links is one entry per notifiable table: its join table and the column in
	// it. A generator writes them from the document, so no name here came from
	// a request.
	Links []Subject

	// Interval is how often a pass runs without a nudge. Zero means a minute,
	// which is the number a scheduled notification's lateness is bounded by.
	Interval time.Duration

	// Senders are the channels this project can actually send on. A channel
	// with nothing here has no delivery rows written for it at all, which is
	// the right answer: the alternative is a table of copies nobody will take.
	//
	// Empty is a working configuration: the inbox is not a channel, so an
	// application with no transport still has one.
	Senders map[Channel]Sender

	// ClaimTTL is how long this process's claim is honoured. Zero means
	// [DefaultClaimTTL]; under [MinClaimTTL] panics.
	ClaimTTL time.Duration

	// SendTimeout bounds one call into a [Sender]. Zero means
	// [DefaultSendTimeout]; ClaimTTL or longer panics.
	//
	// It is the deadline on the context a channel is handed, and it is the only
	// thing standing between a provider that never answers and a dispatcher that
	// never runs again.
	SendTimeout time.Duration

	// MaxAttempts, BackoffBase and BackoffCap are the retry arithmetic, and the
	// three of them are one decision — see the constants they default to for what
	// the numbers add up to. Zero means the defaults.
	MaxAttempts int
	BackoffBase time.Duration
	// BackoffCap bounds one wait, so a long schedule's tail is a series of
	// knocks rather than a sleep nobody will be awake for. Zero means
	// [DefaultBackoffCap]; under BackoffBase panics.
	BackoffCap time.Duration

	// Jitter is where the spread on a retry comes from: given n, it returns
	// something in [0, n).
	//
	// It exists to be replaced in a test, and for nothing else. A schedule is
	// asserted on by fixing this to the floor or the ceiling of its range, which
	// is not something a test can do to a package-level random source. Nil means
	// math/rand/v2's, which is per-P and needs no seeding and no lock.
	Jitter func(int64) int64

	// DefaultDigest is what an account with no setting for a channel gets.
	// Empty means Immediate.
	DefaultDigest Digest

	// Logger is where a pass says what it did.
	//
	// Nil is not silence: it is [log/slog.Default], the reading every other
	// Logger in rig gives it. Before this field the goroutine threw both of its
	// reports away — [Report] and [DispatchReport] were built for "the log line
	// the task writes" and only the cron half ever wrote one — so a project
	// running the engine in-process could not tell a dispatcher that was
	// working from one that had stopped.
	//
	// The lines are DEBUG, because there is one pair of them per interval
	// forever. What is not debug is a pass that failed, and a pass that found
	// notifications whose subject nothing answers for: both are ERROR and WARN,
	// and both are invisible today.
	Logger *slog.Logger
}

type InboxQuery struct {
	// UnreadOnly is the filter the badge and the list share.
	UnreadOnly bool
	// Kind narrows to one kind of event. Empty is all of them.
	Kind string

	// Before pages backwards through created_at, which is the order the list is
	// in. A cursor rather than an offset, because an inbox gains rows at the top
	// while somebody is reading it and an offset would show them a line twice.
	Before *time.Time
	Limit  int
}

type Message struct {
	Channel   Channel
	AccountID uuid.UUID
	TenantID  uuid.UUID

	// Deliveries are what this message stands for, oldest first. One for an
	// immediate send; several for a digest.
	Deliveries []Delivery

	// Devices are where to send, for a push channel. Empty for Email, whose
	// address is on the account.
	Devices []Device
	// EmailAddress is where to send for Email, and empty otherwise.
	EmailAddress string
}

type NoSender struct{ Channel Channel }

type Notification struct {
	ID       uuid.UUID
	TenantID uuid.UUID

	Kind    string
	State   State
	Payload json.RawMessage

	// DeliverAt is when this is due. It is the only difference between a
	// notification that goes out now and one scheduled for Friday.
	DeliverAt  time.Time
	ResolvedAt *time.Time
	CreatedAt  time.Time

	// GroupKey is what will collapse this into an existing inbox line, decided
	// when the announcement was written because that is where the subject was
	// in hand, and read when the audience is resolved.
	GroupKey *string

	// AccountIDs is a list captured at write time, and empty in the ordinary
	// case. See [Announcement.AccountIDs] for why the exception exists and why
	// it is an exception.
	AccountIDs []uuid.UUID
}

type PruneReport struct {
	// Lines are inbox lines that were read and dismissed, past retention.
	Lines int
	// Deliveries are the copies of them, which have to go first: a delivery
	// points at a line.
	Deliveries int
	// Notifications are the ones left with no inbox line and no link pointing at
	// them — which is what a hard-deleted subject leaves behind, deliberately.
	Notifications int
}

type Recipient struct {
	ID             uuid.UUID
	TenantID       uuid.UUID
	NotificationID uuid.UUID
	AccountID      uuid.UUID

	Kind     string
	GroupKey *string
	// EventCount is how many events this line stands for. One, unless a group
	// key collapsed them.
	EventCount int
	ReadAt     *time.Time

	CreatedAt time.Time
	DeletedAt *time.Time
}

type Registry struct {
	// contains filtered or unexported fields
}

type Report struct {
	// Resolved is how many notifications had their audience computed.
	Resolved int
	// Recipients is how many inbox lines were written, and Collapsed how many
	// joined an existing unread line instead.
	Recipients int
	Collapsed  int

	// Empty is how many resolutions produced no recipients at all.
	//
	// It is here because it is the one failure mode of this design that is
	// otherwise silent: a notification with no audience looks exactly like a
	// notification nobody was owed. The commonest cause is an owner-scoped read
	// inside an Audience method, which returns nothing under System claims until
	// it is told not to narrow.
	Empty int

	// Unregistered is how many notifications named a table nothing answers for.
	// A build whose registry lost a service, most often.
	Unregistered int

	// Deliveries is how many copies were written for channels somebody's
	// settings allow, and Held how many were moved into a window rather than
	// being due at once.
	Deliveries int
	Held       int
}

type Sender interface {
	Send(ctx context.Context, m Message) error
}

type SenderFunc func(ctx context.Context, m Message) error

type Service struct {
	// contains filtered or unexported fields
}

type Setting struct {
	Channel Channel
	// Kind is empty for the row that answers for every kind, which is the second
	// step of the resolution.
	Kind string

	// Enabled false writes no delivery row at all, rather than a Skipped one.
	// See [DigestOff] for how the two differ.
	Enabled bool
	Digest  Digest

	// ActiveFrom and ActiveUntil bound the window, in the account's own zone.
	// Both nil means all day.
	//
	// The window is stated as when to deliver rather than when to stay quiet,
	// and that is not a naming preference. "Mobile, weekdays, nine to five" is
	// one row; as quiet hours it is two, because the quiet period wraps a
	// weekend and a night, and somebody changing the end of their working day
	// would have to reason about the complement.
	ActiveFrom  *time.Duration
	ActiveUntil *time.Duration

	// ActiveDays are ISO weekdays, 1 being Monday. Empty means every day.
	//
	// An array rather than a bitmask, because it appears in a settings payload a
	// client renders and [1,2,3,4,5] is legible in a way 62 is not.
	ActiveDays []int

	// Zone is the account's own, from rig_account.time_zone. Nil means UTC,
	// which is what that column's own documentation says a null means.
	Zone *time.Location
}

type State string

type Subject struct {
	// Table is the subject's own table, not the join. The join's name is derived
	// from it.
	Table string
	// LinkTable is the join table pointing at rig_notification, and Column is
	// the subject's own key in it.
	LinkTable string
	Column    string

	ID uuid.UUID
}

type Subjects interface {
	// Table is the subject's own table, which is how the dispatcher finds the
	// right entry for a notification's link row.
	Table() string

	// Audience answers, at the moment of sending, which accounts should hear
	// about a row.
	//
	// It runs under System claims for the row's own tenant, which is what makes
	// the answer current: an account added to the group after the notification
	// was written is in this list, because this list is built now.
	//
	// It must be a pure read, and it may be called more than once for the same
	// notification. The unique index on (notification_id, account_id) makes a
	// repeat harmless; a method with side effects would make it visible.
	Audience(ctx context.Context, n *Notification, subjectID uuid.UUID) ([]uuid.UUID, error)
}