shiplog 0.3.2 → 0.4.0

data/app/models/shiplog/newsletter/content.rb

@@ -0,0 +1,172 @@
+module Shiplog
+  module Newsletter
+    # What a newsletter says in one locale: the announcement's title, subject and body (the current translation,
+    # English when there is none), the Markdown rendered once as inline-styled HTML and as plain text, the
+    # month's feature highlights (cards with a screenshot, a sentence and a link), and the links.
+    # SendNewsletterJob builds one per locale and hands it to every message of that locale.
+    #
+    # The split rule: when there are highlights and the body has at least two "## " sections, the email shows
+    # the intro (the text before the first heading), the highlight cards in place of the body's FIRST section,
+    # then the rest of the body from the second section on ("Also improved"). Otherwise the body is shown whole.
+    # The split is made on the Markdown of the locale's text, so it works for translations whatever the headings
+    # say. Card texts come from the features' own approved (translated) entries, not from the body.
+    class Content
+      MAX_HIGHLIGHTS = 3
+      SUMMARY_LENGTH = 180
+      PREHEADER_LENGTH = 150
+      # A "## " heading at the start of a line (Markdown allows up to three leading spaces).
+      SECTION = /^ {0,3}\#{2}[ \t]/
+
+      # One highlight card: a feature's title, first sentence and permalink, and its first screenshot (absolute
+      # URL, alt text, size when the blob was analysed) or nil without one.
+      Highlight = Data.define(:title, :summary, :url, :image_url, :image_alt, :image_width, :image_height) do
+        def image? = image_url.present?
+      end
+
+      # The inline styles of the body's tags in the HTML part (email clients ignore stylesheets; see Markdown).
+      BODY_STYLES = {
+        "h1" => "margin:28px 0 10px;font-size:20px;line-height:1.3;font-weight:700;color:#1f2328;",
+        "h2" => "margin:28px 0 10px;font-size:18px;line-height:1.3;font-weight:700;color:#1f2328;",
+        "h3" => "margin:20px 0 6px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "h4" => "margin:16px 0 4px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "h5" => "margin:16px 0 4px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "h6" => "margin:16px 0 4px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "p" => "margin:0 0 12px;font-size:16px;line-height:1.6;color:#1f2328;",
+        "ul" => "margin:0 0 12px;padding:0 0 0 20px;",
+        "ol" => "margin:0 0 12px;padding:0 0 0 20px;",
+        "li" => "margin:0 0 4px;font-size:15px;line-height:1.55;color:#1f2328;",
+        "blockquote" => "margin:0 0 12px;padding:0 0 0 12px;border-left:3px solid #d1d9e0;color:#59636e;",
+        "hr" => "border:0;border-top:1px solid #d1d9e0;margin:20px 0;",
+        "code" => "font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:14px;background-color:#f6f8fa;padding:1px 4px;border-radius:3px;",
+        "img" => "display:block;max-width:100%;height:auto;border-radius:8px;margin:0 0 12px;"
+      }.freeze
+
+      attr_reader :entry, :locale
+
+      # `highlights:` replaces the ones built from the month's features (the mailer preview, with no rows).
+      def initialize(entry, locale, highlights: nil)
+        @entry = entry
+        @locale = Newsletter.locale_for(locale)
+        @highlights = highlights
+      end
+
+      def title = entry.display_title(locale).to_s
+
+      def subject = title
+
+      # The month the announcement covers ("October 2026"), in the locale when its I18n data has month names.
+      def month = Period.month_name(entry.released_on || Date.current, locale: Newsletter.i18n_locale(locale))
+
+      # The whole body as HTML, each tag inline-styled, links in the accent colour. Rendered once per Content.
+      def html = @html ||= render_html(markdown)
+
+      def text = @text ||= entry.to_text(locale)
+
+      # The body's first line, cut short, for the preheader (the preview line next to the subject).
+      def preheader = (intro_text.presence || text).lines.first.to_s.squish.truncate(PREHEADER_LENGTH)
+
+      # Up to MAX_HIGHLIGHTS of the month's approved features, in the changelog's order, each with a permalink
+      # (features without one are skipped). Built once per Content.
+      def highlights
+        @highlights ||= features.lazy.filter_map { |feature| highlight(feature) }.first(MAX_HIGHLIGHTS)
+      end
+
+      # Whether the email shows the intro, the cards and the rest instead of the whole body (the split rule).
+      def highlights_shown? = highlights.any? && sections.size >= 2
+
+      # The text before the body's first "## " heading, as HTML; nil unless the split rule applies.
+      def intro_html
+        @intro_html ||= render_html(intro_markdown) if highlights_shown?
+      end
+
+      # The body from its second "## " heading on, as HTML; nil unless the split rule applies. It opens a card, whose
+      # padding already spaces it, so the opening heading's top margin is dropped.
+      def rest_html
+        @rest_html ||= flush_top(render_html(rest_markdown)) if highlights_shown?
+      end
+
+      def intro_text
+        @intro_text ||= Markdown.to_text(intro_markdown) if highlights_shown?
+      end
+
+      def rest_text
+        @rest_text ||= Markdown.to_text(rest_markdown) if highlights_shown?
+      end
+
+      def view_url = @view_url ||= Newsletter.announcement_url(entry, locale)
+
+      def changelog_url = @changelog_url ||= Newsletter.changelog_url
+
+      def accent = Shiplog.config.newsletter_accent || "#0969da"
+
+      def logo_url = Shiplog.config.newsletter_logo_url
+
+      def address = Shiplog.config.newsletter_address
+
+      def product_name = Newsletter.product_name
+
+      # The absolute URL of an attachment's file through Active Storage's redirect route (the host's), or nil.
+      def self.image_url(attachment)
+        path = Rails.application.routes.url_helpers.rails_blob_path(attachment.blob, only_path: true)
+        Newsletter.absolute_url(path)
+      end
+
+      private
+
+      def markdown = @markdown ||= entry.to_markdown(locale).gsub(/\r\n?/, "\n")
+
+      # The body cut at its "## " headings: the text before the first one, then one String per section.
+      def sections = @sections ||= markdown.split(/(?=#{SECTION.source})/).tap { |parts| parts.shift unless parts.first.to_s.match?(SECTION) }
+
+      def intro_markdown = markdown.match?(SECTION) ? markdown.split(SECTION, 2).first.to_s : markdown
+
+      def rest_markdown = sections.drop(1).join
+
+      # The HTML with the top margin of a leading heading set to 0 (its style is BODY_STYLES', so it starts "margin:").
+      def flush_top(html)
+        html.sub(/\A(\s*<h[1-6] style=")margin:\d+px/) { "#{Regexp.last_match(1)}margin:0" }.html_safe # rubocop:disable Rails/OutputSafety
+      end
+
+      def render_html(source) = Markdown.to_html(source, styles: BODY_STYLES.merge("a" => "color:#{accent};text-decoration:underline;"))
+
+      # The month's approved features, images and this locale's translations loaded at once.
+      def features
+        period = entry.subject
+        return [] unless period.is_a?(Period)
+
+        features = period.changelog_entries.with_images_loaded.to_a.select(&:feature?)
+        Entry.preload_translations(features, locale:)
+        features
+      end
+
+      def highlight(feature)
+        url = Newsletter.absolute_url(PublicLinks.entry_url(feature))
+        return unless url
+
+        image = Shiplog.images? ? feature.ordered_images.first : nil
+        image_url = image && screenshot_url(feature, image)
+        metadata = image_url ? image.blob.metadata : {}
+        feature_title = feature.display_title(locale).to_s
+        Highlight.new(title: feature_title, summary: first_sentence(feature.display_body(locale)), url:, image_url:,
+          image_alt: (image_url ? feature.custom_image_alt(image) || feature_title : nil),
+          image_width: metadata[:width].to_i.positive? ? metadata[:width].to_i : nil,
+          image_height: metadata[:height].to_i.positive? ? metadata[:height].to_i : nil)
+      end
+
+      # A screenshot's absolute URL; nil, after a log line (no address in it), when the host's routes cannot give one.
+      def screenshot_url(feature, image)
+        self.class.image_url(image)
+      rescue StandardError => error
+        Rails.logger.warn("[shiplog] Newsletter: the screenshot of entry #{feature.id} is left out: #{error.class}")
+        nil
+      end
+
+      # The first sentence of a plain-text body (punctuation kept), cut at SUMMARY_LENGTH.
+      def first_sentence(body)
+        text = body.to_s.squish
+        match = text.match(Rewriter::SENTENCE_END)
+        (match ? text[0...match.end(0)] : text).truncate(SUMMARY_LENGTH)
+      end
+    end
+  end
+end

data/app/models/shiplog/newsletter/csv.rb

@@ -0,0 +1,32 @@
+module Shiplog
+  module Newsletter
+    # The admin's CSV export of subscribers, written by hand: the csv gem is no longer a default gem and Shiplog
+    # adds no dependency for a few lines. Every cell is quoted, and a cell that a spreadsheet would read as a
+    # formula (starting with =, +, -, @, a tab or a carriage return) gets a leading apostrophe, so an address
+    # like "=HYPERLINK(...)@evil.example" cannot run anything when the file is opened.
+    module Csv
+      HEADERS = %w[email locale status source subscribed_at confirmed_at unsubscribed_at].freeze
+      FORMULA = /\A[=+\-@\t\r]/
+
+      # The CSV text of a scope of subscribers, read in batches.
+      def self.generate(scope)
+        lines = [ line(HEADERS) ]
+        scope.find_each { |subscriber| lines << line(row(subscriber)) }
+        lines.join("\n") + "\n"
+      end
+
+      def self.row(subscriber)
+        [ subscriber.email, subscriber.locale, subscriber.status, subscriber.source,
+          *[ subscriber.created_at, subscriber.confirmed_at, subscriber.unsubscribed_at ].map { |time| time&.utc&.iso8601 } ]
+      end
+
+      def self.line(values) = values.map { |value| cell(value) }.join(",")
+
+      def self.cell(value)
+        text = value.to_s
+        text = "'#{text}" if FORMULA.match?(text)
+        %("#{text.gsub('"', '""')}")
+      end
+    end
+  end
+end

data/app/models/shiplog/newsletter/recipients.rb

@@ -0,0 +1,92 @@
+module Shiplog
+  module Newsletter
+    # The recipients of a newsletter, in batches: the host's users (config.newsletter_recipients, read in batches
+    # with find_each when the callable returns a relation) and then the confirmed subscribers. An address with an
+    # unsubscribed row (a suppression record, whatever the source of the address) is skipped, one query per
+    # batch; so is a duplicate: the first host recipient with an address wins, and a subscriber whose address a
+    # host user has is skipped. A host object without a usable email or id (or not responding to email, locale
+    # and id) is skipped with a warning that names no address, never a crash.
+    class Recipients
+      Recipient = Data.define(:key, :email, :locale, :source, :record) do
+        def host? = source == :host
+        def subscriber? = source == :subscriber
+      end
+
+      EMAIL = URI::MailTo::EMAIL_REGEXP
+
+      def initialize(batch_size: Shiplog.config.newsletter_batch_size)
+        @batch_size = batch_size
+      end
+
+      # Yields Arrays of at most batch_size Recipients (fewer once suppressed and duplicate addresses are dropped).
+      def each_batch(&block)
+        seen = Set.new
+        host_batches { |records| emit(records.filter_map { |record| host_recipient(record) }, seen, suppressed: true, &block) }
+        NewsletterSubscriber.confirmed.in_batches(of: @batch_size) do |subscribers|
+          emit(subscribers.map { |subscriber| subscriber_recipient(subscriber) }, seen, suppressed: false, &block)
+        end
+      end
+
+      # Yields each Recipient once, host users first.
+      def each(&block) = each_batch { |batch| batch.each(&block) }
+
+      # { "en" => 120, "es" => 30 }: how many recipients get each locale's email, after deduplication.
+      def counts_by_locale
+        counts = Hash.new(0)
+        each { |recipient| counts[recipient.locale] += 1 }
+        counts.sort_by { |locale, _| locale }.to_h
+      end
+
+      private
+
+      # Yields the candidates that are neither suppressed (checked in one query when `suppressed`; the confirmed
+      # subscribers' scope rules it out already) nor seen before.
+      def emit(candidates, seen, suppressed:)
+        skipped = suppressed ? suppressed_emails(candidates.map(&:email)) : Set.new
+        batch = candidates.select { |recipient| !skipped.include?(recipient.email) && seen.add?(recipient.email) }
+        yield batch if batch.any?
+      end
+
+      # The addresses among `emails` that unsubscribed (NewsletterSubscriber.suppress), lowercased.
+      def suppressed_emails(emails)
+        return Set.new if emails.empty?
+
+        NewsletterSubscriber.unsubscribed.where("lower(email) IN (?)", emails).pluck(:email).map(&:downcase).to_set
+      end
+
+      # The host's recipient objects, batch_size at a time (a relation is read with find_each).
+      def host_batches(&block)
+        callable = Shiplog.config.newsletter_recipients
+        return unless callable
+
+        records = callable.call
+        return if records.nil?
+
+        if records.respond_to?(:find_each)
+          records.find_each(batch_size: @batch_size).each_slice(@batch_size, &block)
+        else
+          records.each_slice(@batch_size, &block)
+        end
+      end
+
+      def host_recipient(record)
+        return skip("#{record.class.name}, which does not respond to email, locale and id") unless %i[email locale id].all? { |name| record.respond_to?(name) }
+        return skip("a #{record.class.name} without an id") if record.id.blank?
+
+        email = record.email.to_s.strip.downcase
+        return if email.empty? || !EMAIL.match?(email) || email.length > NewsletterSubscriber::EMAIL_MAX_LENGTH
+
+        Recipient.new(key: "#{record.class.name}/#{record.id}", email:, locale: Newsletter.locale_for(record.locale), source: :host, record:)
+      end
+
+      def subscriber_recipient(subscriber)
+        Recipient.new(key: subscriber.recipient_key, email: subscriber.email, locale: Newsletter.locale_for(subscriber.locale), source: :subscriber, record: subscriber)
+      end
+
+      def skip(what)
+        Rails.logger.warn("[shiplog] newsletter_recipients gave #{what}: skipped")
+        nil
+      end
+    end
+  end
+end

data/app/models/shiplog/newsletter/tokens.rb

@@ -0,0 +1,77 @@
+module Shiplog
+  module Newsletter
+    # The tokens in newsletter links: encrypted and signed (AES-256-GCM through ActiveSupport::MessageEncryptor,
+    # URL-safe, JSON), keyed from the host's secret_key_base, each with its own purpose so one cannot stand in for
+    # another. Nothing in a token is readable without the key (no id, no address in clear in logs or caches); a
+    # tampered or expired token decrypts to nil.
+    #   confirmation(subscriber)  the double opt-in link: the row's single-use confirmation_nonce, valid
+    #                             CONFIRMATION_VALIDITY; the nonce is cleared when the link is used or the address
+    #                             unsubscribes, so an old link confirms nothing
+    #   unsubscribe(email)        the one-click and footer unsubscribe link: the address, encrypted, so the host's
+    #                             users need no row in Shiplog; it does not expire (footers live long)
+    # The preferences page uses the subscriber's stored token instead (NewsletterSubscriber#token), rotated after
+    # each change made there.
+    #
+    # Rotating secret_key_base: call `Shiplog::Newsletter::Tokens.rotate(old_secret_key_base)` in an initializer
+    # while old unsubscribe links must keep working (they are decrypted with the old key too).
+    module Tokens
+      CONFIRMATION_VALIDITY = 7.days
+      SALT = "shiplog newsletter".freeze
+      KEY_LENGTH = 32
+
+      # The confirmation link's token, or nil when the row has no pending confirmation.
+      def self.confirmation(subscriber)
+        nonce = subscriber.confirmation_nonce
+        encryptor.encrypt_and_sign({ "nonce" => nonce }, purpose: :confirm, expires_in: CONFIRMATION_VALIDITY) if nonce.present?
+      end
+
+      # The subscriber whose pending confirmation this token is, or nil (tampered, expired, used, or unsubscribed since).
+      def self.subscriber_for(token)
+        data = read(token, :confirm)
+        nonce = data["nonce"] if data.is_a?(Hash)
+        NewsletterSubscriber.find_by(confirmation_nonce: nonce) if nonce.is_a?(String) && nonce.present?
+      end
+
+      def self.unsubscribe(email) = encryptor.encrypt_and_sign({ "email" => email.to_s.strip.downcase }, purpose: :unsubscribe)
+
+      # The address of an unsubscribe token, or nil when it does not verify.
+      def self.email_for(token)
+        data = read(token, :unsubscribe)
+        data["email"].presence if data.is_a?(Hash) && data["email"].is_a?(String)
+      end
+
+      # Adds a previous secret_key_base whose tokens must still be accepted.
+      def self.rotate(secret_key_base)
+        previous_secrets << secret_key_base.to_s
+        @encryptor = nil
+      end
+
+      def self.reset_rotation!
+        previous_secrets.clear
+        @encryptor = nil
+      end
+
+      def self.previous_secrets = (@previous_secrets ||= [])
+
+      def self.encryptor
+        @encryptor ||= ActiveSupport::MessageEncryptor.new(Rails.application.key_generator.generate_key(SALT, KEY_LENGTH), url_safe: true, serializer: JSON).tap do |encryptor|
+          previous_secrets.each { |secret| encryptor.rotate(key_generator(secret).generate_key(SALT, KEY_LENGTH)) }
+        end
+      end
+
+      def self.key_generator(secret)
+        ActiveSupport::KeyGenerator.new(secret, iterations: 1000, hash_digest_class: ActiveSupport::KeyGenerator.hash_digest_class)
+      end
+      private_class_method :key_generator
+
+      def self.read(token, purpose)
+        return if token.blank?
+
+        encryptor.decrypt_and_verify(token.to_s, purpose:)
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage, ActiveSupport::MessageVerifier::InvalidSignature, ArgumentError
+        nil
+      end
+      private_class_method :read
+    end
+  end
+end

data/app/models/shiplog/newsletter.rb

@@ -0,0 +1,180 @@
+module Shiplog
+  # The newsletter: an approved announcement emailed, in each recipient's language, to the host's users who opted
+  # in (config.newsletter_recipients, never stored) and to the visitors who subscribed through Shiplog's form
+  # (NewsletterSubscriber, double opt-in). Approving publishes the announcement; sending is a separate, explicit
+  # admin action (SendNewsletterJob, once per recipient: NewsletterDelivery). Off by default: config.newsletter.
+  # An unsubscribe is honoured whatever the source of the address: Shiplog keeps a suppression row for it (the
+  # one thing it stores about a host's user) and tells the host (config.on_newsletter_unsubscribe).
+  module Newsletter
+    def self.enabled? = Shiplog.newsletter?
+
+    # Whether the newsletter's tables exist: the unsubscribe and preferences pages keep working while they do,
+    # even with config.newsletter off (a link in an old email must still unsubscribe).
+    def self.available? = NewsletterSubscriber.table_exists?
+
+    # Why an announcement cannot be sent, as symbols the admin page explains (empty when it can): :not_approved,
+    # :translations (a configured locale has no current translation, listed in `missing_locales`), :from,
+    # :address and :base_url (config.newsletter_from, newsletter_address, and an origin for absolute links). A
+    # test send (`test: true`) needs only a sender and an origin.
+    def self.blockers(entry, test: false)
+      blockers = []
+      unless test
+        blockers << :not_approved unless entry.approved?
+        blockers << :translations if missing_locales(entry).any?
+        blockers << :address if Shiplog.config.newsletter_address.blank?
+      end
+      blockers << :from if from.blank?
+      blockers << :base_url if base_url.blank?
+      blockers
+    end
+
+    def self.sendable?(entry) = blockers(entry).empty?
+
+    # The configured locales with no current translation of the entry.
+    def self.missing_locales(entry) = Shiplog.config.locales.reject { |locale| entry.translation(locale) }
+
+    # The sender: config.newsletter_from, else ActionMailer's default From (the confirmation email needs one too).
+    def self.from = Shiplog.config.newsletter_from.presence || ActionMailer::Base.default[:from].presence
+
+    # The origin of the links in emails: config.canonical_url, else the host and protocol of
+    # action_mailer.default_url_options (what every mailer uses), else nil (a blocker).
+    def self.base_url
+      return Shiplog.config.canonical_url if Shiplog.config.canonical_url
+
+      options = ActionMailer::Base.default_url_options || {}
+      host = options[:host].to_s.strip
+      return if host.empty?
+
+      protocol = options[:protocol].to_s.delete_suffix("://").presence || "https"
+      port = options[:port].presence
+      "#{protocol}://#{host}#{":#{port}" if port}"
+    end
+
+    # The absolute URL of an engine route (`:newsletter_preferences_path`, ...): the base URL plus the path, which
+    # carries the engine's mount.
+    def self.url(helper, *args) = "#{base_url}#{PublicLinks.path(helper, *args)}"
+
+    # The page a newsletter's "View in browser" link opens: config.announcement_url (:external, called with the
+    # entry and the locale; a failing or unsafe result is logged and gives no link), else the announcement's
+    # own page (the default locale's URL: Shiplog cannot know how the host puts a locale in its URLs).
+    def self.announcement_url(entry, locale)
+      if Shiplog.config.announcements == :external
+        callable = Shiplog.config.announcement_url
+        return unless callable
+
+        value = callable.call(entry, locale.to_sym)
+        return value if Configuration.safe_url?(value) && value.match?(%r{\Ahttps?://}i)
+
+        Rails.logger.warn("[shiplog] config.announcement_url gave no absolute http(s) URL for the newsletter of entry #{entry.id}: #{value.inspect}")
+        nil
+      else
+        absolute(entry.public_url)
+      end
+    rescue StandardError => error
+      Rails.logger.error("[shiplog] config.announcement_url failed for the newsletter of entry #{entry.id}: #{error.class}: #{error.message}")
+      nil
+    end
+
+    def self.changelog_url = absolute(PublicLinks.changelog_url)
+
+    # The one-click and footer unsubscribe target for any address, host user or subscriber: an encrypted token of
+    # the email, so Shiplog stores nothing about the host's users until they unsubscribe (see Tokens).
+    def self.unsubscribe_url(email) = url(:newsletter_unsubscription_path, Tokens.unsubscribe(email))
+
+    def self.preferences_url(subscriber) = url(:newsletter_preferences_path, subscriber.token)
+
+    # The confirmation link of a pending subscriber, or nil when there is no pending confirmation.
+    def self.confirmation_url(subscriber)
+      token = Tokens.confirmation(subscriber)
+      url(:newsletter_confirmation_path, token) if token
+    end
+
+    # What a host user's footer links as "Preferences": config.newsletter_unsubscribe_url for the recipient, when
+    # it gives a safe absolute URL (a failure is logged), else nil (the footer then links Shiplog's unsubscribe page).
+    def self.host_unsubscribe_url(recipient)
+      callable = Shiplog.config.newsletter_unsubscribe_url
+      return unless callable
+
+      value = callable.call(recipient)
+      return value if Configuration.safe_url?(value) && value.match?(%r{\Ahttps?://}i)
+
+      Rails.logger.warn("[shiplog] config.newsletter_unsubscribe_url gave no absolute http(s) URL for #{recipient.class.name}/#{recipient.id}: #{value.inspect}")
+      nil
+    rescue StandardError => error
+      Rails.logger.error("[shiplog] config.newsletter_unsubscribe_url failed for #{recipient.class.name}/#{recipient.id}: #{error.class}: #{error.message}")
+      nil
+    end
+
+    # Removes an address from both lists: Shiplog's row is marked unsubscribed (created as a suppression record
+    # when there is none, so Recipients skips the address whatever the host's list says), and
+    # config.on_newsletter_unsubscribe is called with the email so the host turns its user's setting off. A hook
+    # that raises is logged; the visitor still sees the confirmation. False for an address that is not an email.
+    def self.unsubscribe(email)
+      subscriber = NewsletterSubscriber.suppress(email)
+      return false unless subscriber
+
+      notify_unsubscribe(subscriber.email)
+      true
+    end
+
+    # The host's user opted in again: lifts the suppression. A row that was only a suppression record is deleted
+    # (nothing is left to store); a visitor who had confirmed through the form is confirmed again. False when the
+    # address was not suppressed.
+    def self.resubscribe(email)
+      subscriber = NewsletterSubscriber.find_by_email(email)
+      return false unless subscriber&.unsubscribed?
+
+      subscriber.never_confirmed? ? subscriber.destroy! : subscriber.resubscribe!
+      true
+    end
+
+    def self.notify_unsubscribe(email)
+      Shiplog.config.on_newsletter_unsubscribe&.call(email)
+    rescue StandardError => error
+      Rails.logger.error("[shiplog] on_newsletter_unsubscribe failed for #{digest(email)}: #{error.class}: #{error.message}\n#{error.backtrace&.first(5)&.join("\n")}")
+    end
+    private_class_method :notify_unsubscribe
+
+    # A short digest of an address, for log lines (never the address itself).
+    def self.digest(email) = "email:#{Digest::SHA256.hexdigest(email.to_s.strip.downcase).first(12)}"
+
+    # What the subscribe form's per-address rate limit counts: the address lowercased, without a +tag, and
+    # without dots for Gmail (where they are ignored), digested so the cache never holds an address.
+    def self.rate_limit_key(email)
+      local, domain = email.to_s.strip.downcase.split("@", 2)
+      local = local.to_s.split("+", 2).first.to_s
+      if %w[gmail.com googlemail.com].include?(domain)
+        local = local.delete(".")
+        domain = "gmail.com"
+      end
+      Digest::SHA256.hexdigest("#{local}@#{domain}")
+    end
+
+    # The locale a recipient's email is written in: theirs when it is the default or a configured one, else the
+    # default (as a String).
+    def self.locale_for(locale) = NewsletterSubscriber.resolve_locale(locale)
+
+    # The locale I18n can switch to for the email's chrome and the public pages: the one given when the host's
+    # I18n knows it, else the default (a configured translation locale need not be an available one).
+    def self.i18n_locale(locale)
+      candidate = locale.to_s.presence
+      candidate && I18n.locale_available?(candidate) ? candidate.to_sym : I18n.default_locale
+    end
+
+    # The product's name for the email texts: config.product_name, else the "shiplog.newsletter.product" text.
+    def self.product_name = Shiplog.config.product_name.presence || I18n.t("shiplog.newsletter.product", default: "Product updates")
+
+    # An absolute URL for a path (or an absolute URL as is), with the origin the emails use (base_url); nil for a
+    # blank value or without a base URL.
+    def self.absolute_url(url)
+      return if url.blank?
+      return url if url.match?(%r{\Ahttps?://}i)
+      return unless base_url
+
+      "#{base_url}#{url}"
+    end
+
+    def self.absolute(url) = absolute_url(url)
+    private_class_method :absolute
+  end
+end

data/app/models/shiplog/newsletter_delivery.rb

@@ -0,0 +1,83 @@
+module Shiplog
+  # One newsletter email to one recipient: a row per announcement and recipient key ("User/42" for the host's
+  # users, "Subscriber/7" for Shiplog's), unique on both. The row is inserted BEFORE the email is sent (status
+  # "pending"), then marked "sent" or "failed" (with the error, scrubbed of any address). So a retried job, a
+  # worker that runs twice or a second click on Send never emails anyone twice: at most once per recipient. No
+  # email address is stored here; a subscriber's rows go with its row, and rows older than RETENTION are purged
+  # (PurgeNewsletterJob). The admin's "Retry failed" sends the failed rows again, and the pending rows untouched
+  # for STALLED_AFTER, which a dying worker left behind (a row is touched right before its email is sent).
+  class NewsletterDelivery < ApplicationRecord
+    STALLED_AFTER = 1.hour
+    RETENTION = 180.days
+    # How many rows a run claims at once: small, so a claimed row waits little before its send (and its touch).
+    CLAIM_SIZE = 100
+    ERROR_MAX_LENGTH = 500
+    EMAIL_LIKE = /[^\s@<>()\[\]"']+@[^\s@<>()\[\]"']+/
+    MISSING_RECIPIENT = "Shiplog::Newsletter::MissingRecipient: not among the recipients anymore".freeze
+
+    belongs_to :announcement, class_name: "Shiplog::Entry", inverse_of: :newsletter_deliveries
+
+    enum :status, %w[pending sent failed].index_by(&:itself), validate: true
+
+    scope :stalled, -> { pending.where(updated_at: ...STALLED_AFTER.ago) }
+
+    # { sent:, failed:, pending:, stalled: } for an announcement; two COUNT queries.
+    def self.progress(announcement)
+      scope = where(announcement:)
+      counts = scope.group(:status).count
+      { sent: counts.fetch("sent", 0), failed: counts.fetch("failed", 0), pending: counts.fetch("pending", 0), stalled: scope.stalled.count }
+    end
+
+    # Inserts a pending row for each recipient that has none yet (one statement) and returns the keys of the rows
+    # inserted: the recipients this run may email. Rows that exist already (sent, failed, or pending in another
+    # run) are left alone.
+    def self.claim(announcement, recipients)
+      return [] if recipients.empty?
+
+      rows = recipients.map { |recipient| { announcement_id: announcement.id, recipient_key: recipient.key, locale: recipient.locale, status: "pending" } }
+      insert_all(rows, unique_by: [ :announcement_id, :recipient_key ], returning: [ :recipient_key ]).rows.flatten
+    end
+
+    # Puts the failed and stalled rows of an announcement back to pending in one statement and returns the keys
+    # it changed: two retries at once each get their own rows, and a run sends only what it reclaimed itself.
+    # The one place a recipient can receive the email twice: a stalled row whose email did leave before the
+    # worker died. The admin triggers it knowingly.
+    def self.reclaim(announcement)
+      sql = sanitize_sql_array([ <<~SQL.squish, { now: Time.current, id: announcement.id, stalled_before: STALLED_AFTER.ago } ])
+        UPDATE #{table_name} SET status = 'pending', error = NULL, updated_at = :now
+        WHERE announcement_id = :id AND (status = 'failed' OR (status = 'pending' AND updated_at < :stalled_before))
+        RETURNING recipient_key
+      SQL
+      with_connection { |connection| connection.exec_query(sql, "Shiplog::NewsletterDelivery Reclaim").rows.flatten }
+    end
+
+    # Touches the row right before its email is sent, so a row in flight never looks stalled.
+    def self.mark_sending(announcement, key)
+      where(announcement:, recipient_key: key).update_all(updated_at: Time.current)
+    end
+
+    def self.mark_sent(announcement, key)
+      where(announcement:, recipient_key: key).update_all(status: "sent", sent_at: Time.current, error: nil, updated_at: Time.current)
+    end
+
+    # Records a failure as the exception's class and its message with anything address-like removed.
+    def self.mark_failed(announcement, key, error)
+      where(announcement:, recipient_key: key).update_all(status: "failed", error: "#{error.class}: #{scrub(error.message)}", updated_at: Time.current)
+    end
+
+    # Reclaimed rows whose recipient is gone (a deleted subscriber, a user that left the host's list): failed,
+    # with the reason, rather than pending forever.
+    def self.mark_missing(announcement, keys)
+      return if keys.empty?
+
+      where(announcement:, recipient_key: keys.to_a, status: "pending").update_all(status: "failed", error: MISSING_RECIPIENT, updated_at: Time.current)
+    end
+
+    # Deletes the rows older than `older_than`, whatever their status. Returns how many.
+    def self.purge(older_than: RETENTION)
+      where(created_at: ...older_than.ago).delete_all
+    end
+
+    def self.scrub(text) = text.to_s.gsub(EMAIL_LIKE, "[email]").first(ERROR_MAX_LENGTH)
+  end
+end