railsdrip-engine 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0087d769a2177893bb95fe903b455d38e619e33d7274ac3d271c8f2c6204af3f'
+  data.tar.gz: 461a3ad1a89b7b0f75b599c15abaae649aa1d0a3fc3910b65b3e6029b1db946c
+SHA512:
+  metadata.gz: e8c44a70be5cde255f649f8732696c42f16c906634857b50f54b887f01900e1c3d77a8de9c73d4fff358e12f57350d27d4d32f490f8734ea86dcc25d018fa3c4
+  data.tar.gz: 9eb078a5628ea4d649427fd153b9ae29c76fbc58130d926d00fe5a0fbd5afac0d1ea1c3dd50c06f9e4408e1a4a93cba72d782b00f36df5e30cc456e35e922c40

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## Unreleased
+
+- Add the initial isolated Rails engine, configuration object, and mail registry.
+- Add namespaced campaign, version, step, enrollment, event, and delivery persistence with a Rails 7 migration API.

data/LICENSE.txt

@@ -0,0 +1,4 @@
+Copyright (c) 2026 RailsDrips contributors.
+
+All rights reserved. No license is granted at this time.
+

data/README.md

@@ -0,0 +1,80 @@
+# RailsDrips
+
+RailsDrips is a Rails engine for versioned, auditable email drip campaigns. It stores campaign definitions, enrolls any Active Record model as a recipient, schedules steps through Active Job, and delivers mail through the host application's Action Mailer classes.
+
+RailsDrips owns the workflow. Your application owns the product decisions and email content.
+
+| RailsDrips provides | Your application provides |
+| --- | --- |
+| Campaigns, immutable versions, and ordered steps | Action Mailer classes and templates |
+| Enrollment, scheduling, retries, and cancellation | The business event that enrolls or removes a recipient |
+| Active Job delivery orchestration | A production Active Job adapter and worker process |
+| Delivery snapshots and an append-only event history | Optional eligibility, preference, and transport hooks |
+| YAML definitions and import tooling | Admin authentication and authorization if the UI is mounted |
+
+RailsDrips supports Rails 7.0 through Rails 8.x. Its public API is still pre-release.
+
+## Quick start
+
+Add the gem, install its files, and migrate:
+
+```ruby
+# Gemfile
+gem "railsdrip-engine"
+```
+
+```bash
+bundle install
+bin/rails generate rails_drips:install
+bin/rails db:migrate
+```
+
+Register a host mailer in `config/initializers/rails_drips.rb`:
+
+```ruby
+RailsDrips.configure do |config|
+  config.delivery_queue_name = :mailers
+
+  config.mailers.register "welcome", label: "Welcome" do |delivery|
+    OnboardingMailer.welcome(delivery)
+  end
+end
+```
+
+Define `OnboardingMailer#welcome`, edit the generated campaign YAML, import and activate it, then enroll a recipient:
+
+```bash
+bin/rails rails_drips:validate DEFINITION=config/rails_drips/onboarding.yml
+bin/rails rails_drips:import DEFINITION=config/rails_drips/onboarding.yml APPLY=true
+bin/rails rails_drips:activate CAMPAIGN=onboarding VERSION=1
+```
+
+```ruby
+RailsDrips.enroll(
+  campaign: "onboarding",
+  recipient: account,
+  source: "account_created"
+)
+```
+
+That call creates the enrollment, event history, and scheduled deliveries in one transaction. Delivery jobs are enqueued only after the transaction commits.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) — complete host setup and first campaign
+- [Host integration](docs/host-integration.md) — every code path a host can or must implement
+- [Architecture](docs/architecture.md) — ownership boundaries, records, and runtime flow
+- [Campaign definitions](docs/campaign-definitions.md) — YAML format, versioning, and import behavior
+- [Operations](docs/operations.md) — admin access, audits, failures, and recovery
+
+The current admin pages are an operational prototype, not the finished UI. The [admin UI and dummy-app TODO](docs/todo/admin-ui-and-dummy-app.md) defines the next design and demonstration iteration.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rake build
+```
+
+Extraction research and implementation plans live under `docs/research/extracting-drip-engine/` and `plans/`.

data/app/controllers/concerns/rails_drips/admin_access.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  module AdminAccess
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :require_admin_access
+    end
+
+    private
+
+    def require_admin_access
+      config = RailsDrips.configuration
+      return head(:not_found) unless config.admin_enabled && config.admin_authenticator && config.admin_authorizer
+      return head(:unauthorized) unless config.admin_authenticator.call(controller: self)
+      return head(:forbidden) unless config.admin_authorizer.call(controller: self, action: action_name, record: nil)
+    end
+
+    def current_rails_drips_actor
+      RailsDrips.configuration.current_actor_resolver.call(self)
+    end
+
+    def recipient_label(recipient)
+      RailsDrips.configuration.recipient_label_resolver.call(recipient)
+    end
+  end
+end

data/app/controllers/rails_drips/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class ApplicationController < ActionController::Base
+    include AdminAccess
+  end
+end

data/app/controllers/rails_drips/campaign_archivals_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class CampaignArchivalsController < ApplicationController
+    def create
+      campaign = Campaign.find(params[:campaign_id])
+      ArchiveCampaign.call(campaign: campaign, actor: current_rails_drips_actor, reason: params[:reason])
+      redirect_to campaign_path(campaign)
+    end
+  end
+end

data/app/controllers/rails_drips/campaign_pauses_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class CampaignPausesController < ApplicationController
+    def create
+      campaign = Campaign.find(params[:campaign_id])
+      PauseCampaign.call(campaign: campaign, actor: current_rails_drips_actor)
+      redirect_to campaign_path(campaign)
+    end
+  end
+end

data/app/controllers/rails_drips/campaign_resumptions_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class CampaignResumptionsController < ApplicationController
+    def create
+      campaign = Campaign.find(params[:campaign_id])
+      ResumeCampaign.call(campaign: campaign, actor: current_rails_drips_actor)
+      redirect_to campaign_path(campaign)
+    end
+  end
+end

data/app/controllers/rails_drips/campaigns_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class CampaignsController < ApplicationController
+    def index
+      @campaigns = Campaign.order(:key)
+    end
+
+    def show
+      @campaign = Campaign.includes(campaign_versions: :steps).find(params[:id])
+      @enrollments = @campaign.enrollments.includes(:recipient).recent_first.limit(100)
+    end
+  end
+end

data/app/controllers/rails_drips/deliveries_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class DeliveriesController < ApplicationController
+    def show
+      @delivery = Delivery.includes(enrollment: :recipient).find(params[:id])
+      @show_snapshot = params[:snapshot] == "1"
+      return unless @show_snapshot
+
+      allowed = RailsDrips.configuration.snapshot_authorizer.call(controller: self, delivery: @delivery)
+      head(:forbidden) unless allowed
+    end
+  end
+end

data/app/controllers/rails_drips/delivery_cancellations_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class DeliveryCancellationsController < ApplicationController
+    def create
+      delivery = Delivery.find(params[:delivery_id])
+      CancelDelivery.call(delivery: delivery, actor: current_rails_drips_actor, reason: params[:reason].presence || "operator")
+      redirect_to delivery_path(delivery)
+    end
+  end
+end

data/app/controllers/rails_drips/delivery_retries_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class DeliveryRetriesController < ApplicationController
+    def create
+      delivery = Delivery.find(params[:delivery_id])
+      RetryDelivery.call(delivery: delivery, actor: current_rails_drips_actor)
+      redirect_to delivery_path(delivery)
+    end
+  end
+end

data/app/controllers/rails_drips/enrollments_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class EnrollmentsController < ApplicationController
+    helper_method :recipient_label
+
+    def show
+      @enrollment = Enrollment.includes(:recipient, :campaign, :campaign_version, :enrollment_events, :deliveries).find(params[:id])
+    end
+  end
+end

data/app/jobs/rails_drips/delivery_job.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class DeliveryJob < ActiveJob::Base
+    queue_as { RailsDrips.configuration.delivery_queue_name }
+
+    discard_on ActiveRecord::RecordNotFound
+
+    def perform(delivery_id)
+      delivery = Delivery.includes(enrollment: :campaign).find(delivery_id)
+      return unless prepare?(delivery)
+
+      message = RailsDrips.configuration.mailers.fetch(delivery.email_key).call(delivery).message
+      message = RailsDrips.configuration.transport_metadata_hook.call(message: message, delivery: delivery)
+      snapshot = MailSnapshot.call(message)
+
+      delivery.with_lock do
+        return unless delivery.scheduled?
+        delivery.update!(
+          subject_snapshot: snapshot[:subject],
+          html_body_snapshot: snapshot[:html_body],
+          text_body_snapshot: snapshot[:text_body],
+          data: delivery.data_value.merge("message_sha256" => snapshot[:sha256], "message_byte_size" => snapshot[:byte_size])
+        )
+        delivery.mark_sending!
+      end
+
+      message.deliver
+
+      delivery.with_lock do
+        delivery.mark_sent!(provider: "action_mailer", provider_message_id: message.message_id)
+        RecordEvent.call(enrollment: delivery.enrollment, event_type: "delivery_sent",
+          data: { "delivery_id" => delivery.id, "step_id" => delivery.step_id })
+      end
+      CompleteEnrollment.call(enrollment: delivery.enrollment)
+      Instrumentation.instrument("delivery.sent", delivery_id: delivery.id,
+        enrollment_id: delivery.enrollment_id, campaign_key: delivery.campaign_key)
+    rescue ActiveRecord::RecordNotFound
+      nil
+    rescue StandardError => error
+      record_failure(delivery, error) if delivery
+      raise
+    end
+
+    private
+
+    def prepare?(delivery)
+      delivery.with_lock do
+        return false unless delivery.scheduled?
+        enrollment = delivery.enrollment
+        campaign = enrollment.campaign
+        return false if campaign.paused?
+        return cancel(delivery, "campaign_inactive") unless campaign.active?
+        return cancel(delivery, "enrollment_inactive") unless enrollment.active?
+        return true if enrollment.forced?
+
+        preference = RailsDrips.configuration.preference_evaluator.call(
+          recipient: enrollment.recipient, category: delivery.email_category, delivery: delivery
+        )
+        return cancel(delivery, "preference_rejected") unless PolicyDecision.allowed?(preference)
+
+        eligibility = RailsDrips.configuration.eligibility_evaluator.call(
+          recipient: enrollment.recipient, campaign: campaign, delivery: delivery, phase: :delivery
+        )
+        return cancel(delivery, "ineligible") unless PolicyDecision.allowed?(eligibility)
+
+        true
+      end
+    end
+
+    def cancel(delivery, reason)
+      delivery.cancel!(reason: reason)
+      RecordEvent.call(enrollment: delivery.enrollment, event_type: "delivery_cancelled",
+        data: { "delivery_id" => delivery.id, "reason" => reason })
+      false
+    end
+
+    def record_failure(delivery, error)
+      delivery.with_lock do
+        return if delivery.sent? || delivery.cancelled?
+        delivery.mark_failed!(message: error.message)
+        RecordEvent.call(enrollment: delivery.enrollment, event_type: "delivery_failed",
+          data: { "delivery_id" => delivery.id, "error_class" => error.class.name })
+      end
+      Instrumentation.instrument("delivery.failed", delivery_id: delivery.id,
+        enrollment_id: delivery.enrollment_id, error_class: error.class.name)
+    end
+  end
+end

data/app/models/concerns/rails_drips/json_data.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  module JsonData
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def normalize_json_value(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), normalized|
+            normalized[key.to_s] = normalize_json_value(nested_value)
+          end
+        when Array
+          value.map { |item| normalize_json_value(item) }
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+    end
+
+    def data_value
+      data || {}
+    end
+  end
+end
+

data/app/models/rails_drips/application_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end
+

data/app/models/rails_drips/campaign.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class Campaign < ApplicationRecord
+    include JsonData
+
+    has_many :campaign_versions,
+      class_name: "RailsDrips::CampaignVersion",
+      dependent: :destroy,
+      inverse_of: :campaign
+    has_many :steps, through: :campaign_versions
+    has_many :enrollments,
+      class_name: "RailsDrips::Enrollment",
+      dependent: :restrict_with_error,
+      inverse_of: :campaign
+    belongs_to :current_version,
+      class_name: "RailsDrips::CampaignVersion",
+      optional: true
+
+    enum :status, { draft: 0, active: 1, archived: 2, paused: 3 }, prefix: true
+
+    validates :key, presence: true, uniqueness: true
+    validates :name, presence: true
+    validates :status, presence: true
+    validate :current_version_belongs_to_campaign
+
+    def draft? = status_draft?
+    def active? = status_active?
+    def archived? = status_archived?
+    def paused? = status_paused?
+
+    def active_version
+      current_version if active? && current_version&.active?
+    end
+
+    def active_for_enrollment?
+      active_version.present?
+    end
+
+    def activate_version!(version, actor: nil)
+      raise ArgumentError, "Version does not belong to this campaign" unless version.campaign == self
+      raise ArgumentError, "Archived campaigns must be unarchived before activation" if archived?
+      raise ArgumentError, "Only draft versions can be activated" unless version.draft?
+
+      with_lock do
+        campaign_versions.status_active.where.not(id: version.id).find_each(&:retire!)
+        version.created_by ||= actor if actor
+        version.update!(status: :active, activated_at: Time.current)
+        update!(status: :active, current_version: version)
+      end
+    end
+
+    private
+
+    def current_version_belongs_to_campaign
+      return if current_version.blank? || current_version.campaign_id == id
+
+      errors.add(:current_version, "must belong to the campaign")
+    end
+  end
+end
+

data/app/models/rails_drips/campaign_version.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class CampaignVersion < ApplicationRecord
+    belongs_to :campaign,
+      class_name: "RailsDrips::Campaign",
+      inverse_of: :campaign_versions
+    belongs_to :created_by, polymorphic: true, optional: true
+    has_many :steps,
+      class_name: "RailsDrips::Step",
+      dependent: :destroy,
+      inverse_of: :campaign_version
+    has_many :enrollments,
+      class_name: "RailsDrips::Enrollment",
+      dependent: :restrict_with_error,
+      inverse_of: :campaign_version
+
+    enum :status, { draft: 0, active: 1, retired: 2 }, prefix: true
+
+    validates :version_number,
+      presence: true,
+      numericality: { only_integer: true, greater_than: 0 },
+      uniqueness: { scope: :campaign_id }
+    validates :status, presence: true
+
+    def draft? = status_draft?
+    def active? = status_active?
+    def retired? = status_retired?
+
+    def retire!
+      update!(status: :retired)
+    end
+  end
+end
+

data/app/models/rails_drips/delivery.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class Delivery < ApplicationRecord
+    include JsonData
+
+    belongs_to :enrollment,
+      class_name: "RailsDrips::Enrollment",
+      inverse_of: :deliveries
+    belongs_to :step,
+      class_name: "RailsDrips::Step",
+      inverse_of: :deliveries
+    belongs_to :recipient, polymorphic: true, optional: true
+
+    enum :status, { scheduled: 0, sending: 1, sent: 2, failed: 3, cancelled: 4 }, prefix: true
+
+    validates :recipient_email, :scheduled_for, :campaign_key, :email_key, :status, presence: true
+    validate :step_belongs_to_enrollment_version
+    validate :preserve_sent_snapshots, on: :update
+
+    scope :scheduled, -> { where(status: :scheduled) }
+    scope :due, -> { scheduled.where("scheduled_for <= ?", Time.current) }
+    scope :future, -> { scheduled.where("scheduled_for > ?", Time.current) }
+    scope :recent, -> { order(created_at: :desc) }
+
+    after_create_commit :enqueue_delivery_job
+
+    def scheduled? = status_scheduled?
+    def sending? = status_sending?
+    def sent? = status_sent?
+    def failed? = status_failed?
+    def cancelled? = status_cancelled?
+
+    def cancel!(reason:)
+      update!(
+        status: :cancelled,
+        cancelled_at: Time.current,
+        data: data_value.merge("cancel_reason" => reason.to_s)
+      )
+    end
+
+    def mark_sending!
+      update!(status: :sending, attempts: attempts.to_i + 1, failed_at: nil, last_error: nil)
+    end
+
+    def mark_sent!(provider: nil, provider_message_id: nil)
+      update!(
+        status: :sent,
+        sent_at: Time.current,
+        provider: provider,
+        provider_message_id: provider_message_id
+      )
+    end
+
+    def mark_failed!(message:)
+      update!(
+        status: :failed,
+        failed_at: Time.current,
+        attempts: attempts.to_i + (sending? ? 0 : 1),
+        last_error: message.to_s.byteslice(0, 10_000)
+      )
+    end
+
+    private
+
+    def enqueue_delivery_job
+      return unless scheduled?
+
+      RailsDrips.configuration.delivery_job
+        .set(queue: RailsDrips.configuration.delivery_queue_name, wait_until: scheduled_for)
+        .perform_later(id)
+    end
+
+    def step_belongs_to_enrollment_version
+      return if step.blank? || enrollment.blank?
+      return if step.campaign_version_id == enrollment.campaign_version_id
+
+      errors.add(:step, "must belong to the enrollment campaign version")
+    end
+
+    def preserve_sent_snapshots
+      return unless status_in_database == "sent"
+
+      snapshot_attributes = %w[subject_snapshot html_body_snapshot text_body_snapshot]
+      return unless snapshot_attributes.any? { |attribute| will_save_change_to_attribute?(attribute) }
+
+      errors.add(:base, "Sent email snapshots are immutable")
+    end
+  end
+end

data/app/models/rails_drips/enrollment.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class Enrollment < ApplicationRecord
+    include JsonData
+
+    belongs_to :campaign,
+      class_name: "RailsDrips::Campaign",
+      inverse_of: :enrollments
+    belongs_to :campaign_version,
+      class_name: "RailsDrips::CampaignVersion",
+      inverse_of: :enrollments
+    belongs_to :recipient, polymorphic: true
+    belongs_to :added_by, polymorphic: true, optional: true
+    belongs_to :removed_by, polymorphic: true, optional: true
+    has_many :deliveries,
+      class_name: "RailsDrips::Delivery",
+      dependent: :destroy,
+      inverse_of: :enrollment
+    has_many :enrollment_events,
+      class_name: "RailsDrips::EnrollmentEvent",
+      dependent: :destroy,
+      inverse_of: :enrollment
+
+    enum :status, { active: 0, paused: 1, removed: 2, completed: 3, failed: 4 }, prefix: true
+
+    validates :status, presence: true
+    validate :campaign_version_belongs_to_campaign
+
+    scope :open, -> { where(status: [:active, :paused]) }
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    def active? = status_active?
+    def paused? = status_paused?
+    def removed? = status_removed?
+    def completed? = status_completed?
+    def failed? = status_failed?
+
+    def open?
+      active? || paused?
+    end
+
+    def forced?
+      data_value["forced_enrollment"] == true
+    end
+
+    def remove!(reason:, actor: nil)
+      update!(
+        status: :removed,
+        exit_reason: reason.to_s,
+        removed_by: actor,
+        removed_at: Time.current
+      )
+    end
+
+    def complete!
+      update!(status: :completed, completed_at: Time.current)
+    end
+
+    def fail!(message:)
+      update!(
+        status: :failed,
+        failed_at: Time.current,
+        data: data_value.merge("error_message" => message.to_s)
+      )
+    end
+
+    private
+
+    def campaign_version_belongs_to_campaign
+      return if campaign.blank? || campaign_version.blank?
+      return if campaign_version.campaign_id == campaign_id
+
+      errors.add(:campaign_version, "must belong to the campaign")
+    end
+  end
+end

data/app/models/rails_drips/enrollment_event.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class EnrollmentEvent < ApplicationRecord
+    include JsonData
+
+    belongs_to :enrollment,
+      class_name: "RailsDrips::Enrollment",
+      inverse_of: :enrollment_events
+    belongs_to :actor, polymorphic: true, optional: true
+
+    validates :event_type, :occurred_at, presence: true
+
+    scope :chronological, -> { order(:occurred_at, :id) }
+    scope :recent_first, -> { order(occurred_at: :desc, id: :desc) }
+
+    before_update :prevent_mutation
+    before_destroy :prevent_mutation
+
+    private
+
+    def prevent_mutation
+      errors.add(:base, "Enrollment events are append-only")
+      throw(:abort)
+    end
+  end
+end
+