subscriptions

package
v0.0.0-...-f964ac6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package subscriptions lets readers without an account get an author's new posts by email: subscribing with a confirmation mail, the page where a subscriber manages their subscriptions, the author's list of subscribers, and the mail sent when a post is published.

Index

Constants

View Source
const (
	// InvalidEmailMessage refuses an address that isn't one.
	InvalidEmailMessage = "Invalid email"
	// DisposableMessage refuses a throwaway address.
	DisposableMessage = "Please use a permanent address"
	// PausedMessage is the answer of the subscribe and manage-link forms
	// while the site-wide brake is on.
	PausedMessage = "Subscriptions are paused, try again later"
)

The messages of the service's validation errors, shown to the visitor as they are.

View Source
const (
	// DefaultConfirmLifetime is how long a confirmation link works.
	DefaultConfirmLifetime = 72 * time.Hour
	// DefaultConfirmsPerAddress is how many confirmation mails one mailbox
	// gets.
	DefaultConfirmsPerAddress = 3
	// DefaultManageLinksPerAddress is how many manage-link mails one mailbox
	// gets.
	DefaultManageLinksPerAddress = 3
	// DefaultConfirmsPerHour is how many confirmation mails the whole site
	// sends per hour.
	DefaultConfirmsPerHour = 100
	// DefaultDomainLookupsPerHour is how many DNS lookups of subscribing
	// addresses' domains the whole site makes per hour.
	DefaultDomainLookupsPerHour = 300
	// DefaultPruneEvery is how often RunPruner deletes expired rows.
	DefaultPruneEvery = time.Hour
)

The settings' values when the configuration sets none; they are also the configuration's defaults.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthorRow

type AuthorRow struct {
	ID          string
	Email       string
	ConfirmedAt *time.Time
}

AuthorRow is one subscriber in AuthorView.

type AuthorView

type AuthorView struct {
	Count int
	Rows  []AuthorRow
}

AuthorView is an author's subscribers: how many are active, and each subscription with its address and when it was confirmed (nil while pending).

type BrakedMailArgs

type BrakedMailArgs struct {
	// Hour is the start of the UTC hour the brake was hit in.
	Hour time.Time `json:"hour"`
}

BrakedMailArgs tells the admin that the site-wide brake is on. It is unique by hour, as the mail is.

func (BrakedMailArgs) InsertOpts

func (BrakedMailArgs) InsertOpts() river.InsertOpts

InsertOpts makes the job unique by hour.

func (BrakedMailArgs) Kind

func (BrakedMailArgs) Kind() string

Kind names the job kind.

type ConfirmMailArgs

type ConfirmMailArgs struct {
	SubscriptionID string `json:"subscription_id"`
}

ConfirmMailArgs is the mail that asks a reader to confirm a pending subscription.

func (ConfirmMailArgs) Kind

func (ConfirmMailArgs) Kind() string

Kind names the job kind.

type ConfirmView

type ConfirmView struct {
	AuthorUsername string
	// Email is the address the subscription is for.
	Email  string
	Paused bool
}

ConfirmView is what the confirmation page shows before the subscriber confirms: whose posts they will get, and whether that author has paused subscriptions.

type Limits

type Limits struct {
	ConfirmLifetime       time.Duration
	ConfirmsPerAddress    int
	ManageLinksPerAddress int
	ConfirmsPerHour       int
	DomainLookupsPerHour  int
	PruneEvery            time.Duration
}

Limits are the service's settings, as Limits reports them.

type ManageLinkMailArgs

type ManageLinkMailArgs struct {
	SubscriberID string `json:"subscriber_id"`
	RequestID    string `json:"request_id"`
}

ManageLinkMailArgs is the mail with a subscriber's manage link. RequestID tells the requests apart, so each one is mailed.

func (ManageLinkMailArgs) Kind

func (ManageLinkMailArgs) Kind() string

Kind names the job kind.

type ManageRow

type ManageRow struct {
	ID             string
	AuthorUsername string
	Since          time.Time
	Paused         bool
}

ManageRow is one subscription on the manage page. Paused is set when the author no longer takes subscriptions, so no posts are mailed. Since is when the subscription was confirmed.

type ManageView

type ManageView struct {
	Email string
	Rows  []ManageRow
}

ManageView is a subscriber's subscriptions, for the page their manage link opens.

type NewPostMailArgs

type NewPostMailArgs struct {
	PostID         string `json:"post_id"`
	SubscriptionID string `json:"subscription_id"`
}

NewPostMailArgs is the mail of a post to one subscriber of its author.

func (NewPostMailArgs) Kind

func (NewPostMailArgs) Kind() string

Kind names the job kind.

type NewSubscriberMailArgs

type NewSubscriberMailArgs struct {
	SubscriptionID string `json:"subscription_id"`
}

NewSubscriberMailArgs tells an author that a subscription was confirmed.

func (NewSubscriberMailArgs) Kind

Kind names the job kind.

type Option

type Option func(*Service)

Option changes how New builds the service.

func WithClock

func WithClock(now func() time.Time) Option

WithClock replaces the clock links and limits are timed by, for tests.

func WithConfirmLifetime

func WithConfirmLifetime(d time.Duration) Option

WithConfirmLifetime sets how long a confirmation link works; zero keeps DefaultConfirmLifetime.

func WithConfirmsPerAddress

func WithConfirmsPerAddress(n int) Option

WithConfirmsPerAddress sets how many confirmation mails one mailbox gets; zero keeps DefaultConfirmsPerAddress.

func WithConfirmsPerHour

func WithConfirmsPerHour(n int) Option

WithConfirmsPerHour sets how many confirmation mails the site sends per hour; zero keeps DefaultConfirmsPerHour.

func WithDomainLookupsPerHour

func WithDomainLookupsPerHour(n int) Option

WithDomainLookupsPerHour sets how many DNS lookups of subscribing addresses' domains the site makes per hour; zero keeps DefaultDomainLookupsPerHour.

func WithEmailChecker

func WithEmailChecker(c *emailaddr.Checker) Option

WithEmailChecker sets what asks DNS whether an address's domain can receive mail; nil keeps emailaddr.NewChecker().

func WithIdentity

func WithIdentity(ident mail.Identity) Option

WithIdentity tells the service the site its links point to and the addresses its mail uses. Without it links are relative and mail has no sender.

func WithJobs

func WithJobs(q repo.JobQueue) Option

WithJobs sets the queue the service enqueues its background jobs on.

func WithLogger

func WithLogger(l *zap.Logger) Option

WithLogger sets the logger of the background pruner (RunPruner); requests log through the logger their context carries. The default logs nothing.

func WithManageLinksPerAddress

func WithManageLinksPerAddress(n int) Option

WithManageLinksPerAddress sets how many manage-link mails one mailbox gets; zero keeps DefaultManageLinksPerAddress.

func WithPruneEvery

func WithPruneEvery(d time.Duration) Option

WithPruneEvery sets how often RunPruner runs; zero keeps DefaultPruneEvery.

type PostPublishedArgs

type PostPublishedArgs struct {
	PostID string `json:"post_id"`
}

PostPublishedArgs is the job NotifyPost enqueues: its worker mails the post to the author's active subscribers. It is unique by post.

func (PostPublishedArgs) InsertOpts

func (PostPublishedArgs) InsertOpts() river.InsertOpts

InsertOpts makes the job unique by post.

func (PostPublishedArgs) Kind

func (PostPublishedArgs) Kind() string

Kind names the job kind.

type Service

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

Service is email subscriptions to authors.

func New

func New(store *repo.Store, opts ...Option) *Service

New builds the service. Its mail is enqueued as jobs on the queue WithJobs sets; the pruner needs none.

func (*Service) ActiveCount

func (s *Service) ActiveCount(ctx context.Context, tx *repo.Store, authorID string) (int, error)

ActiveCount is how many confirmed subscribers the author has, read on tx (the service's store when nil).

func (*Service) Confirm

func (s *Service) Confirm(ctx context.Context, token string) error

Confirm activates the subscription the token was mailed for and tells the author. Confirming an active subscription again changes nothing; an unknown or expired token is ErrNotFound.

func (*Service) ConfirmView

func (s *Service) ConfirmView(ctx context.Context, token string) (*ConfirmView, error)

ConfirmView is what the confirmation link's page shows. It changes nothing, since mail scanners open links. An unknown or expired token is ErrNotFound.

func (*Service) FanOutPost

func (s *Service) FanOutPost(ctx context.Context, a PostPublishedArgs) error

FanOutPost enqueues the post's mail to each active subscriber of its author, in one transaction, if the post is still published and public and its author can still be subscribed to. A mail already sent is dropped by its unique id, so running the job again sends nothing twice.

func (*Service) ForAuthor

func (s *Service) ForAuthor(ctx context.Context, actor *model.User) (*AuthorView, error)

ForAuthor is the actor's own confirmed subscribers, the most recently confirmed first; pending subscriptions are neither counted nor listed.

func (*Service) Limits

func (s *Service) Limits() Limits

Limits reports the settings the service runs with.

func (*Service) Manage

func (s *Service) Manage(ctx context.Context, manageToken string) (*ManageView, error)

Manage is the active subscriptions of the subscriber the manage token belongs to, by author; an unknown token is ErrNotFound.

func (*Service) NotifyPost

func (s *Service) NotifyPost(ctx context.Context, tx *repo.Store, author *model.User, post *model.Post) error

NotifyPost marks a published post mailed to the author's subscribers and enqueues the job that mails them (PostPublishedArgs), once per post, inside the caller's transaction (a transaction of its own when tx is nil), so the post is marked only together with its job. It does nothing for an author who can't be subscribed to, a post that isn't public and published, a post already mailed, or an author without subscribers. The job picks the subscribers as they are when it runs.

func (*Service) Prune

func (s *Service) Prune(ctx context.Context) error

Prune deletes the pending subscriptions whose link expired, the subscribers left without a subscription, and the mail log rows no limit counts any more, whatever their kind.

func (*Service) RegisterJobs

func (s *Service) RegisterJobs(r *jobs.Registry)

RegisterJobs registers the workers of the service's job kinds on r.

func (*Service) Remove

func (s *Service) Remove(ctx context.Context, actor *model.User, subscriptionID string) error

Remove ends a subscription to the actor's posts. Nobody is mailed about it. A subscription to somebody else is ErrNotFound.

func (*Service) RenderBraked

func (s *Service) RenderBraked(_ context.Context, a BrakedMailArgs) (*mail.Envelope, error)

RenderBraked builds the admin's alert that subscriptions are braked.

func (*Service) RenderConfirm

func (s *Service) RenderConfirm(ctx context.Context, a ConfirmMailArgs) (*mail.Envelope, error)

RenderConfirm builds the confirmation mail of a subscription still pending, with its link still valid, to an author who can still be subscribed to.

func (s *Service) RenderManageLink(ctx context.Context, a ManageLinkMailArgs) (*mail.Envelope, error)

RenderManageLink builds the mail with the manage link of a subscriber who still has subscriptions.

func (*Service) RenderNewPost

func (s *Service) RenderNewPost(ctx context.Context, a NewPostMailArgs) (*mail.Envelope, error)

RenderNewPost builds the mail of a post to a subscriber, while the subscription is active and the post may still be mailed.

func (*Service) RenderNewSubscriber

func (s *Service) RenderNewSubscriber(ctx context.Context, a NewSubscriberMailArgs) (*mail.Envelope, error)

RenderNewSubscriber builds the mail that tells the author about a subscription confirmed and still active.

func (*Service) RenderSubscriberLeft

func (s *Service) RenderSubscriberLeft(ctx context.Context, a SubscriberLeftMailArgs) (*mail.Envelope, error)

RenderSubscriberLeft builds the mail that tells the author an address unsubscribed, unless the author's account is gone.

func (s *Service) RequestManageLink(ctx context.Context, email string) error

RequestManageLink mails the address its manage link, if it subscribes to anyone and the mailbox had fewer than ManageLinksPerAddress of them today. The answer is the same either way.

func (*Service) RunPruner

func (s *Service) RunPruner(ctx context.Context)

RunPruner deletes expired pending subscriptions and old mail log rows every PruneEvery until ctx is done.

func (*Service) Subscribable

func (s *Service) Subscribable(author *model.User) bool

Subscribable reports whether readers may subscribe to the author: their profile is public and they turned email subscriptions on.

func (*Service) Subscribe

func (s *Service) Subscribe(ctx context.Context, authorUsername, email string) error

Subscribe starts a subscription of email to the author's posts and mails a confirmation link. An author who can't be subscribed to is ErrNotFound. The answer is the same whatever the address's state: a new subscription, or a pending one whose link expired, gets a confirmation mail unless the mailbox had its share of them today; a pending one whose link still works and an active one get nothing. Only an address that would get a mail has its domain checked (checkDomain), and one whose domain can't receive mail is refused.

func (*Service) Unsubscribe

func (s *Service) Unsubscribe(ctx context.Context, manageToken, subscriptionID string) error

Unsubscribe ends one subscription of the manage token's subscriber and tells the author. An unknown token, or a subscription of somebody else, is ErrNotFound.

func (*Service) UnsubscribeAll

func (s *Service) UnsubscribeAll(ctx context.Context, manageToken string) error

UnsubscribeAll ends every subscription of the manage token's subscriber, telling each author whose subscriber left.

type SubscriberLeftMailArgs

type SubscriberLeftMailArgs struct {
	SubscriptionID  string `json:"subscription_id"`
	AuthorID        string `json:"author_id"`
	SubscriberEmail string `json:"subscriber_email"`
}

SubscriberLeftMailArgs tells an author that a subscriber unsubscribed. The subscription is deleted with the change that enqueues it, so the args carry the address the mail names.

func (SubscriberLeftMailArgs) Kind

Kind names the job kind.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL