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
- type AuthorRow
- type AuthorView
- type BrakedMailArgs
- type ConfirmMailArgs
- type ConfirmView
- type Limits
- type ManageLinkMailArgs
- type ManageRow
- type ManageView
- type NewPostMailArgs
- type NewSubscriberMailArgs
- type Option
- func WithClock(now func() time.Time) Option
- func WithConfirmLifetime(d time.Duration) Option
- func WithConfirmsPerAddress(n int) Option
- func WithConfirmsPerHour(n int) Option
- func WithDomainLookupsPerHour(n int) Option
- func WithEmailChecker(c *emailaddr.Checker) Option
- func WithIdentity(ident mail.Identity) Option
- func WithJobs(q repo.JobQueue) Option
- func WithLogger(l *zap.Logger) Option
- func WithManageLinksPerAddress(n int) Option
- func WithPruneEvery(d time.Duration) Option
- type PostPublishedArgs
- type Service
- func (s *Service) ActiveCount(ctx context.Context, tx *repo.Store, authorID string) (int, error)
- func (s *Service) Confirm(ctx context.Context, token string) error
- func (s *Service) ConfirmView(ctx context.Context, token string) (*ConfirmView, error)
- func (s *Service) FanOutPost(ctx context.Context, a PostPublishedArgs) error
- func (s *Service) ForAuthor(ctx context.Context, actor *model.User) (*AuthorView, error)
- func (s *Service) Limits() Limits
- func (s *Service) Manage(ctx context.Context, manageToken string) (*ManageView, error)
- func (s *Service) NotifyPost(ctx context.Context, tx *repo.Store, author *model.User, post *model.Post) error
- func (s *Service) Prune(ctx context.Context) error
- func (s *Service) RegisterJobs(r *jobs.Registry)
- func (s *Service) Remove(ctx context.Context, actor *model.User, subscriptionID string) error
- func (s *Service) RenderBraked(_ context.Context, a BrakedMailArgs) (*mail.Envelope, error)
- func (s *Service) RenderConfirm(ctx context.Context, a ConfirmMailArgs) (*mail.Envelope, error)
- func (s *Service) RenderManageLink(ctx context.Context, a ManageLinkMailArgs) (*mail.Envelope, error)
- func (s *Service) RenderNewPost(ctx context.Context, a NewPostMailArgs) (*mail.Envelope, error)
- func (s *Service) RenderNewSubscriber(ctx context.Context, a NewSubscriberMailArgs) (*mail.Envelope, error)
- func (s *Service) RenderSubscriberLeft(ctx context.Context, a SubscriberLeftMailArgs) (*mail.Envelope, error)
- func (s *Service) RequestManageLink(ctx context.Context, email string) error
- func (s *Service) RunPruner(ctx context.Context)
- func (s *Service) Subscribable(author *model.User) bool
- func (s *Service) Subscribe(ctx context.Context, authorUsername, email string) error
- func (s *Service) Unsubscribe(ctx context.Context, manageToken, subscriptionID string) error
- func (s *Service) UnsubscribeAll(ctx context.Context, manageToken string) error
- type SubscriberLeftMailArgs
Constants ¶
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.
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 AuthorView ¶
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.
type ConfirmMailArgs ¶
type ConfirmMailArgs struct {
SubscriptionID string `json:"subscription_id"`
}
ConfirmMailArgs is the mail that asks a reader to confirm a pending subscription.
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.
type ManageRow ¶
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 ¶
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.
type NewSubscriberMailArgs ¶
type NewSubscriberMailArgs struct {
SubscriptionID string `json:"subscription_id"`
}
NewSubscriberMailArgs tells an author that a subscription was confirmed.
func (NewSubscriberMailArgs) Kind ¶
func (NewSubscriberMailArgs) Kind() string
Kind names the job kind.
type Option ¶
type Option func(*Service)
Option changes how New builds the service.
func WithConfirmLifetime ¶
WithConfirmLifetime sets how long a confirmation link works; zero keeps DefaultConfirmLifetime.
func WithConfirmsPerAddress ¶
WithConfirmsPerAddress sets how many confirmation mails one mailbox gets; zero keeps DefaultConfirmsPerAddress.
func WithConfirmsPerHour ¶
WithConfirmsPerHour sets how many confirmation mails the site sends per hour; zero keeps DefaultConfirmsPerHour.
func WithDomainLookupsPerHour ¶
WithDomainLookupsPerHour sets how many DNS lookups of subscribing addresses' domains the site makes per hour; zero keeps DefaultDomainLookupsPerHour.
func WithEmailChecker ¶
WithEmailChecker sets what asks DNS whether an address's domain can receive mail; nil keeps emailaddr.NewChecker().
func WithIdentity ¶
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 WithLogger ¶
WithLogger sets the logger of the background pruner (RunPruner); requests log through the logger their context carries. The default logs nothing.
func WithManageLinksPerAddress ¶
WithManageLinksPerAddress sets how many manage-link mails one mailbox gets; zero keeps DefaultManageLinksPerAddress.
func WithPruneEvery ¶
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.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is email subscriptions to authors.
func New ¶
New builds the service. Its mail is enqueued as jobs on the queue WithJobs sets; the pruner needs none.
func (*Service) ActiveCount ¶
ActiveCount is how many confirmed subscribers the author has, read on tx (the service's store when nil).
func (*Service) Confirm ¶
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 ¶
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 ¶
ForAuthor is the actor's own confirmed subscribers, the most recently confirmed first; pending subscriptions are neither counted nor listed.
func (*Service) Manage ¶
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 ¶
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 ¶
RegisterJobs registers the workers of the service's job kinds on r.
func (*Service) Remove ¶
Remove ends a subscription to the actor's posts. Nobody is mailed about it. A subscription to somebody else is ErrNotFound.
func (*Service) RenderBraked ¶
RenderBraked builds the admin's alert that subscriptions are braked.
func (*Service) RenderConfirm ¶
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 (*Service) RenderManageLink ¶
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 ¶
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 (*Service) RequestManageLink ¶
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 ¶
RunPruner deletes expired pending subscriptions and old mail log rows every PruneEvery until ctx is done.
func (*Service) Subscribable ¶
Subscribable reports whether readers may subscribe to the author: their profile is public and they turned email subscriptions on.
func (*Service) Subscribe ¶
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 ¶
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.
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 ¶
func (SubscriberLeftMailArgs) Kind() string
Kind names the job kind.