senderidentity

type Config struct {
	// MaxReconcileAttempts bounds the pending→failed TTL. 0 → default.
	MaxReconcileAttempts int
	// ReaperInterval overrides the orphan-sweep cadence. 0 → default.
	ReaperInterval time.Duration
	// LegacyJobCompat is phase 1 of the two-phase blue/green job-lane rollout
	// (config sender_identity.legacy_job_compat).
	// When true, mutation and reconcile jobs are PRODUCED as the legacy kinds
	// on the default queue — consumable by the previous release — while this
	// binary still CONSUMES both lanes. Deploy this release with the flag on;
	// once it is the stable rollback target, flip the flag off (a config-only
	// deploy) to switch producers to the versioned v2 lane. A rollback of
	// that second deploy lands on a binary that consumes v2, so nothing
	// strands. This only makes the River lanes rollback-compatible: operators
	// must still freeze sender-identity mutations while a pre-ownership worker
	// overlaps or is a possible rollback target (see the deployment design).
	// Default false: single-instance/self-host deployments have no blue/green
	// overlap and want the v2 semantics immediately.
	LegacyJobCompat bool
}

type DNSRecord struct {
	Type  string `json:"type"`  // "TXT" | "CNAME" | "MX"
	Name  string `json:"name"`  // record host
	Value string `json:"value"` // record value
}

type DeprovisionArgs struct {
	Domain string `json:"domain"`
}

type DeprovisionWorker struct {
	river.WorkerDefaults[DeprovisionArgs]
	// contains filtered or unexported fields
}

type EventFirer func(ctx context.Context, domain, userID string, status Status, errMsg string)

type FakeProvider struct {
	ProvisionCalls   []string
	StatusCalls      []string
	DeprovisionCalls []string
	ListCalls        int
	ListPageCalls    int
	// contains filtered or unexported fields
}

type LegacyReapWorker struct {
	river.WorkerDefaults[ReapArgs]
	// contains filtered or unexported fields
}

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

type PostDrainAuditArgs struct {
	Domain string `json:"domain" river:"unique"`
	// Window is the audit's schedule bucket (scheduled-at unix seconds /
	// postDrainConvergenceDelay). It scopes ByArgs uniqueness in time: River's
	// unique state set cannot drop `completed`, so without it a completed
	// audit inside the ~24h retention blocked the next mutation's audit for
	// the same domain. A completed audit's bucket is strictly older than any
	// new mutation's (an audit for bucket B cannot complete before B's start,
	// and any later mutation schedules into a later bucket — modulo replica
	// clock skew, which shrinks that guarantee by the skew), so dedupe can
	// only ever match a still-scheduled job. Mutations straddling a bucket
	// edge produce two audits; the audit is idempotent, so that is noise,
	// not a bug.
	Window int64 `json:"window" river:"unique"`
}

type PostDrainAuditWorker struct {
	river.WorkerDefaults[PostDrainAuditArgs]
	// contains filtered or unexported fields
}

type Provider interface {
	// Provision registers a BYODKIM sending identity for domain, supplying
	// the per-domain DKIM selector + PKCS#1 DER private key that e2a
	// already generated (so DKIM d= aligns with the From domain). Returns
	// the initial Result — typically StatusPending — or an error to retry.
	Provision(ctx context.Context, domain, dkimSelector string, dkimPrivateKeyDER []byte) (Result, error)

	// Status polls the current verification state from the provider.
	// Returns ErrIdentityNotFound if no identity exists for domain.
	Status(ctx context.Context, domain string) (Result, error)

	// Deprovision removes the sending identity. A missing identity MUST be
	// reported as success (idempotent teardown).
	Deprovision(ctx context.Context, domain string) error

	// List returns all domain identities visible to the provider principal.
	// It is retained for the phase-1 compatibility worker only; the v2 reaper
	// uses ListPage so one River job cannot inventory the whole provider account.
	// Neither path treats an unledgered identity as its own.
	List(ctx context.Context) ([]string, error)

	// ListPage returns one provider-bounded page plus the opaque continuation
	// token. The v2 orphan audit uses this so one River job never inventories
	// the whole provider account.
	ListPage(ctx context.Context, nextToken string, limit int) (domains []string, followingToken string, err error)
}

type ProvisionArgs struct {
	Domain string `json:"domain"`
}

type ProvisionWorker struct {
	river.WorkerDefaults[ProvisionArgs]
	// contains filtered or unexported fields
}

type RawStore interface {
	WithSendingIdentityMutationLock(ctx context.Context, domain string, fn func(context.Context) error) error
	LoadSendingIdentityState(ctx context.Context, domain string) (incarnation, owner string, verified bool, status, selector string, privateKeyDER []byte, appliedIncarnation string, ledgerUpdatedAt time.Time, err error)
	SetSendingStatusForIncarnation(ctx context.Context, domain, incarnation, status, dkimStatus, mailFromStatus, errMsg string, recordsJSON []byte) error
	TouchSendingCheckedForIncarnation(ctx context.Context, domain, incarnation string) error
	MarkSendingIdentityManaged(ctx context.Context, domain, incarnation string) error
	MarkSendingIdentityApplied(ctx context.Context, domain, incarnation string) error
	SendingIdentityLedgerExpired(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	ObserveSendingIdentityProviderPending(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	ClearSendingIdentityProviderPending(ctx context.Context, domain, incarnation string) error
	ForgetSendingIdentityManaged(ctx context.Context, domain string) error
	FinalizeSendingIdentityTombstone(ctx context.Context, domain string, olderThan time.Duration) error
	SetDomainTeardownState(ctx context.Context, domain string, state domainteardown.State) error
	ListManagedSendingIdentityDomains(ctx context.Context) ([]string, map[string]bool, error)
	ListManagedSendingIdentityDomainsPage(ctx context.Context, afterDomain string, limit int) ([]string, map[string]bool, bool, error)
	LookupManagedSendingIdentityDomain(ctx context.Context, domain string) (bool, bool, error)
	DomainExists(ctx context.Context, domain string) (bool, error)
}

type ReapArgs struct{}

type ReapV2Args struct {
	SweepID       int64  `json:"sweep_id,omitempty" river:"unique"`
	AfterDomain   string `json:"after_domain,omitempty" river:"unique"`
	Phase         string `json:"phase,omitempty" river:"unique"`
	ProviderToken string `json:"provider_token,omitempty" river:"unique"`
}

type ReapWorker struct {
	river.WorkerDefaults[ReapV2Args]
	// contains filtered or unexported fields
}

type ReconcileArgs struct {
	Domain      string `json:"domain"`
	Incarnation string `json:"incarnation,omitempty"`
}

type ReconcileV2Args struct {
	Domain      string `json:"domain"`
	Incarnation string `json:"incarnation"`
}

type ReconcileV2Worker struct {
	river.WorkerDefaults[ReconcileV2Args]
	// contains filtered or unexported fields
}

type ReconcileWorker struct {
	river.WorkerDefaults[ReconcileArgs]
	// contains filtered or unexported fields
}

type Result struct {
	Status         Status      `json:"status"`
	DkimStatus     Status      `json:"dkim_status,omitempty"`
	MailFromStatus Status      `json:"mail_from_status,omitempty"`
	Error          string      `json:"error,omitempty"`
	DNSRecords     []DNSRecord `json:"dns_records,omitempty"`
}

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

type SendingIdentityState struct {
	Incarnation string
	Owner       string
	Verified    bool
	Status      Status
	Selector    string
	PrivateKey  []byte
	// AppliedIncarnation is the ledger's provider-confirmed incarnation ("" if
	// none). Equal to Incarnation only when THIS registration's key was
	// confirmed installed — the gate for the healthy-recheck no-op.
	AppliedIncarnation string
	// LedgerUpdatedAt remains available for diagnostics and adapters. Timeout
	// decisions use Store.SendingIdentityLedgerExpired so clocks are not mixed.
	LedgerUpdatedAt time.Time
}

type Status string

type Store interface {
	// WithSendingIdentityMutationLock serializes provider create/delete calls
	// for one domain across processes and passes a context pinned to the lock.
	WithSendingIdentityMutationLock(ctx context.Context, domain string, fn func(context.Context) error) error
	// LoadSendingIdentityState returns the current domain incarnation and its
	// desired provider state. pgx.ErrNoRows means the desired state is absent.
	LoadSendingIdentityState(ctx context.Context, domain string) (SendingIdentityState, error)
	// SetSendingStatus writes a terminal/transition status (+ the per-axis
	// dkim/mailFrom breakdown + error + DNS records) and stamps
	// sending_last_checked_at. dkimStatus/mailFromStatus may be empty ("")
	// when the caller has no per-axis signal (e.g. provision, or a terminal
	// failure with no SES poll); persisting empty lets the read path fall back
	// to the all-or-nothing rollup.
	SetSendingStatus(ctx context.Context, domain, incarnation string, status, dkimStatus, mailFromStatus Status, errMsg string, records []DNSRecord) error
	// TouchSendingChecked stamps sending_last_checked_at without changing the
	// status — used on a still-pending poll.
	TouchSendingChecked(ctx context.Context, domain, incarnation string) error
	// The managed-domain ledger survives domain deletion so exhausted River
	// jobs remain repairable without scanning/deleting unrelated identities in
	// the provider account.
	MarkSendingIdentityManaged(ctx context.Context, domain, incarnation string) error
	MarkSendingIdentityApplied(ctx context.Context, domain, incarnation string) error
	// SendingIdentityLedgerExpired compares entirely on the database clock so
	// application/DB clock skew cannot shorten or extend the pending TTL.
	SendingIdentityLedgerExpired(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	// ObserveSendingIdentityProviderPending persists the first provider-pending
	// observation for a DB-verified identity and reports whether its grace has
	// expired, also using the database clock. Clear removes that drift marker
	// once the provider agrees or a terminal transition is committed.
	ObserveSendingIdentityProviderPending(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	ClearSendingIdentityProviderPending(ctx context.Context, domain, incarnation string) error
	ForgetSendingIdentityManaged(ctx context.Context, domain string) error
	// FinalizeSendingIdentityTombstone removes the ledger row ONLY when its
	// last mutation (updated_at) is older than olderThan. An audit or sweep
	// that runs inside a later mutation's drain window therefore cannot
	// finalize that mutation's tombstone out from under a still-draining
	// legacy slot; the reaper (or that mutation's own audit) finalizes once
	// the window has truly elapsed.
	FinalizeSendingIdentityTombstone(ctx context.Context, domain string, olderThan time.Duration) error
	SetDomainTeardownState(ctx context.Context, domain string, state domainteardown.State) error
	ListManagedSendingIdentityDomains(ctx context.Context) ([]string, map[string]bool, error)
	ListManagedSendingIdentityDomainsPage(ctx context.Context, afterDomain string, limit int) ([]string, map[string]bool, bool, error)
	LookupManagedSendingIdentityDomain(ctx context.Context, domain string) (needsProvision, found bool, err error)
	// DomainExists reports whether a live domain row exists. The reaper uses
	// it to ALERT on provider identities that are neither ledgered nor backed
	// by a row (pre-upgrade orphans the migration backfill could not see).
	DomainExists(ctx context.Context, domain string) (bool, error)
}

type SyncArgs struct {
	Domain string `json:"domain"`
}

type SyncWorker struct {
	river.WorkerDefaults[SyncArgs]
	// contains filtered or unexported fields
}