railsdrip-engine 0.0.1

data/docs/operations.md

@@ -0,0 +1,104 @@
+# Operations
+
+RailsDrips retains enough state to explain who was enrolled, which frozen campaign version they received, what was scheduled, and what happened to each delivery.
+
+## Secure the admin
+
+Mounting the engine does not expose records by default. Access fails closed with `404` until all required adapters are configured:
+
+```ruby
+# config/routes.rb
+mount RailsDrips::Engine => "/drips"
+```
+
+```ruby
+RailsDrips.configure do |config|
+  config.admin_enabled = true
+
+  config.admin_authenticator = ->(**) { Current.user.present? }
+
+  config.admin_authorizer = ->(action:, **context) { Current.user.admin? }
+
+  config.current_actor_resolver = ->(_controller) { Current.user }
+
+  config.snapshot_authorizer = ->(delivery:, **context) do
+    Current.user.can_view_email_content?
+  end
+end
+```
+
+Authentication establishes that someone is signed in. Authorization decides whether that identity may use the operational interface. Snapshot authorization is separate because stored email bodies may contain sensitive recipient data.
+
+The engine controller currently inherits `ActionController::Base`, not the host's `ApplicationController`. Authentication methods mixed into all controllers may be available, but host-only controller methods are not guaranteed. A request-scoped object such as `Current.user` is the most portable adapter until configurable controller inheritance is added.
+
+With a `/drips` mount, the prototype begins at `/drips/campaigns`. It supports inspection plus campaign pause/resume/archive and delivery retry/cancel. It is not yet the intended authoring experience; see the [admin UI TODO](todo/admin-ui-and-dummy-app.md).
+
+## Campaign operations
+
+```ruby
+RailsDrips.pause_campaign(campaign: campaign, actor: operator)
+RailsDrips.resume_campaign(campaign: campaign, actor: operator)
+RailsDrips.archive_campaign(campaign: campaign, reason: "superseded", actor: operator)
+RailsDrips.unarchive_campaign(campaign: campaign)
+```
+
+Pause leaves scheduled rows intact and prevents sending. Resume returns the campaign to active and enqueues due rows. Archive cancels future scheduled work.
+
+## Retry and cancellation
+
+Failed deliveries do not silently become scheduled again. Retry is explicit and permitted only while enrollment and campaign are active:
+
+```ruby
+RailsDrips::RetryDelivery.call(delivery: delivery, actor: operator)
+RailsDrips::CancelDelivery.call(delivery: delivery, reason: "operator_cancelled", actor: operator)
+```
+
+Failures store a bounded error, attempt count, timestamp, and event before the job exception is re-raised to the host adapter.
+
+## Due-delivery repair
+
+```ruby
+RailsDrips.enqueue_due_deliveries(dry_run: true).count
+RailsDrips.enqueue_due_deliveries(campaign: campaign, dry_run: true).count
+```
+
+Then enqueue due work with `bin/rails rails_drips:enqueue_due`. This is a repair tool, not a replacement for running the normal worker.
+
+## Integrity audit
+
+```ruby
+RailsDrips::IntegrityAudit.call.each do |finding|
+  Rails.logger.warn(
+    code: finding.code,
+    severity: finding.severity,
+    record_type: finding.record_type,
+    record_id: finding.record_id,
+    details: finding.details
+  )
+end
+```
+
+The audit checks missing step deliveries, cross-version steps, stuck sending rows, scheduled work for removed enrollments, failed work on completed enrollments, and sent rows without snapshots.
+
+Active Job has no portable queue-inspection API. A host can optionally add queue evidence:
+
+```ruby
+config.queue_inventory = -> { MyQueueAudit.rails_drips_job_ids }
+```
+
+## The ambiguous transport window
+
+RailsDrips marks a delivery `sending`, releases its lock, and performs transport I/O. If the provider accepts the email and the process dies before `sent` is persisted, database state alone cannot prove delivery.
+
+Before retrying a stuck `sending` row:
+
+1. Search provider logs using the RailsDrips delivery ID or correlation header.
+2. Determine whether the provider accepted the message.
+3. Reconcile accepted work according to the host incident procedure.
+4. Retry only when evidence indicates transport did not accept it.
+
+## Monitoring
+
+Watch scheduled deliveries past their processing window, stuck `sending` rows, failure rate, repeated attempts, due backlog by campaign, cancellation reasons, enrollment completion, and Active Job queue latency.
+
+Pause an affected campaign if content, policy, preference, or transport behavior is wrong. Pausing is the fastest reversible way to stop new sends without deleting evidence.

data/lib/generators/rails_drips/install/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module RailsDrips
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/rails_drips.rb"
+      end
+
+      def copy_sample_definition
+        template "sample.yml", "config/rails_drips/onboarding.yml"
+      end
+
+      def copy_migration
+        migration_template File.expand_path("../../../../db/migrate/20260829123000_create_rails_drips_tables.rb", __dir__),
+          "db/migrate/create_rails_drips_tables.rb"
+      end
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+    end
+  end
+end

data/lib/generators/rails_drips/install/templates/initializer.rb

@@ -0,0 +1,8 @@
+RailsDrips.configure do |config|
+  config.delivery_queue_name = :default
+
+  # Register Action Mailer messages returned for each delivery.
+  # config.mailers.register("welcome", label: "Welcome") do |delivery|
+  #   DripMailer.welcome(delivery)
+  # end
+end

data/lib/generators/rails_drips/install/templates/sample.yml

@@ -0,0 +1,13 @@
+schema_version: 1
+campaign:
+  key: onboarding
+  name: Onboarding
+  description: A sample onboarding campaign
+  allow_reenrollment: false
+  steps:
+    - position: 1
+      name: Welcome
+      kind: email
+      delay_amount: 0
+      delay_unit: minutes
+      email_key: welcome

data/lib/rails_drips/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class Configuration
+    attr_accessor :delivery_queue_name,
+      :delivery_job_class,
+      :eligibility_evaluator,
+      :logger,
+      :admin_enabled,
+      :admin_authenticator,
+      :admin_authorizer,
+      :preference_evaluator,
+      :queue_inventory,
+      :recipient_email_resolver,
+      :recipient_label_resolver,
+      :current_actor_resolver,
+      :snapshot_authorizer,
+      :time_source,
+      :transport_metadata_hook
+    attr_reader :mailers
+
+    def initialize
+      @delivery_queue_name = :default
+      @delivery_job_class = -> { RailsDrips::DeliveryJob }
+      @eligibility_evaluator = ->(**) { true }
+      @logger = defined?(Rails) ? Rails.logger : nil
+      @admin_enabled = false
+      @admin_authenticator = nil
+      @admin_authorizer = nil
+      @preference_evaluator = ->(**) { true }
+      @queue_inventory = nil
+      @recipient_email_resolver = method(:default_recipient_email)
+      @recipient_label_resolver = ->(recipient) { recipient.respond_to?(:name) ? recipient.name : "#{recipient.class.name} ##{recipient.id}" }
+      @current_actor_resolver = ->(_controller) { nil }
+      @snapshot_authorizer = ->(**) { false }
+      @time_source = -> { Time.current }
+      @transport_metadata_hook = ->(message:, **) { message }
+      @mailers = MailRegistry.new
+    end
+
+    def delivery_job
+      delivery_job_class.respond_to?(:call) ? delivery_job_class.call : delivery_job_class
+    end
+
+    def current_time
+      time_source.call
+    end
+
+    def recipient_email(recipient)
+      value = recipient_email_resolver.call(recipient).to_s.strip
+      return value unless value.empty?
+
+      raise RecipientEmailMissing, "No email address could be resolved for #{recipient.class.name}"
+    end
+
+    private
+
+    def default_recipient_email(recipient)
+      return recipient.email_address if recipient.respond_to?(:email_address)
+      return recipient.email if recipient.respond_to?(:email)
+
+      nil
+    end
+  end
+end

data/lib/rails_drips/definition_loader.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RailsDrips
+  class DefinitionLoader
+    def self.load_file(path)
+      load_string(File.read(path), source: path.to_s)
+    rescue Errno::ENOENT => error
+      raise DefinitionInvalid, [error.message]
+    end
+
+    def self.load_string(yaml, source: nil)
+      raw = YAML.safe_load(yaml, permitted_classes: [], permitted_symbols: [], aliases: false)
+      definition = deep_stringify(raw)
+      normalize!(definition)
+      errors = DefinitionSchema.validate(definition)
+      raise DefinitionInvalid, errors.map { |error| source ? "#{source}: #{error}" : error } if errors.any?
+
+      definition
+    rescue Psych::Exception => error
+      raise DefinitionInvalid, [source ? "#{source}: #{error.message}" : error.message]
+    end
+
+    def self.deep_stringify(value)
+      case value
+      when Hash then value.to_h { |key, nested| [key.to_s, deep_stringify(nested)] }
+      when Array then value.map { |nested| deep_stringify(nested) }
+      else value
+      end
+    end
+
+    def self.normalize!(definition)
+      return definition unless definition.is_a?(Hash) && definition["campaign"].is_a?(Hash)
+
+      campaign = definition["campaign"]
+      campaign["steps"]&.each { |step| step["kind"] ||= "email" if step.is_a?(Hash) }
+      definition
+    end
+    private_class_method :deep_stringify, :normalize!
+  end
+end

data/lib/rails_drips/definition_schema.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class DefinitionSchema
+    SCHEMA_VERSION = 1
+
+    def self.validate(definition)
+      errors = []
+      return ["definition must be a mapping"] unless definition.is_a?(Hash)
+
+      errors << "schema_version must be #{SCHEMA_VERSION}" unless definition["schema_version"] == SCHEMA_VERSION
+      campaign = definition["campaign"]
+      return errors << "campaign must be a mapping" unless campaign.is_a?(Hash)
+
+      errors << "campaign.key cannot be blank" if campaign["key"].to_s.strip.empty?
+      errors << "campaign.name cannot be blank" if campaign["name"].to_s.strip.empty?
+      steps = campaign["steps"]
+      return errors << "campaign.steps must be a non-empty list" unless steps.is_a?(Array) && steps.any?
+
+      positions = steps.filter_map { |step| step["position"] if step.is_a?(Hash) }
+      errors << "campaign.steps positions must be unique" if positions.uniq.length != positions.length
+      steps.each_with_index { |step, index| validate_step(step, index, errors) }
+      errors
+    end
+
+    def self.validate_step(step, index, errors)
+      path = "campaign.steps[#{index}]"
+      return errors << "#{path} must be a mapping" unless step.is_a?(Hash)
+
+      errors << "#{path}.position must be a positive integer" unless step["position"].is_a?(Integer) && step["position"].positive?
+      errors << "#{path}.name cannot be blank" if step["name"].to_s.strip.empty?
+      errors << "#{path}.delay_amount must be a non-negative integer" unless step["delay_amount"].is_a?(Integer) && step["delay_amount"] >= 0
+      errors << "#{path}.delay_unit must be minutes, hours, or days" unless Step::DELAY_UNITS.include?(step["delay_unit"].to_s)
+      email_key = step["email_key"].to_s
+      errors << "#{path}.email_key #{email_key.inspect} is not registered" unless RailsDrips.configuration.mailers.registered?(email_key)
+      errors << "#{path}.kind must be email" unless step.fetch("kind", "email").to_s == "email"
+    end
+    private_class_method :validate_step
+  end
+end

data/lib/rails_drips/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsDrips
+    engine_name "rails_drips"
+  end
+end
+

data/lib/rails_drips/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class DuplicateMailerKey < ConfigurationError; end
+  class MailerNotRegistered < ConfigurationError; end
+  class RecipientEmailMissing < Error; end
+  class DefinitionInvalid < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = Array(errors)
+      super(@errors.join("; "))
+    end
+  end
+end

data/lib/rails_drips/instrumentation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  module Instrumentation
+    module_function
+
+    def instrument(name, payload = {}, &block)
+      ActiveSupport::Notifications.instrument("#{name}.rails_drips", payload, &block)
+    end
+  end
+end

data/lib/rails_drips/mail_registry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class MailRegistry
+    Definition = Struct.new(:key, :label, :callable, keyword_init: true) do
+      def call(delivery)
+        callable.call(delivery)
+      end
+    end
+
+    include Enumerable
+
+    def initialize
+      @definitions = {}
+    end
+
+    def register(key, label:, callable: nil, &block)
+      normalized_key = normalize_key(key)
+      delivery_callable = callable || block
+
+      raise ConfigurationError, "A mailer callable is required for #{normalized_key.inspect}" unless delivery_callable.respond_to?(:call)
+      raise ConfigurationError, "A mailer label is required for #{normalized_key.inspect}" if label.to_s.strip.empty?
+      raise DuplicateMailerKey, "Mailer key #{normalized_key.inspect} is already registered" if registered?(normalized_key)
+
+      @definitions[normalized_key] = Definition.new(
+        key: normalized_key,
+        label: label.to_s,
+        callable: delivery_callable
+      )
+    end
+
+    def fetch(key)
+      normalized_key = normalize_key(key)
+      @definitions.fetch(normalized_key) do
+        raise MailerNotRegistered, "No mailer is registered for #{normalized_key.inspect}"
+      end
+    end
+
+    def registered?(key)
+      @definitions.key?(key.to_s)
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @definitions.values.each(&block)
+    end
+
+    def clear
+      @definitions.clear
+      self
+    end
+
+    private
+
+    def normalize_key(key)
+      key.to_s.strip.tap do |normalized_key|
+        raise ConfigurationError, "Mailer key cannot be blank" if normalized_key.empty?
+      end
+    end
+  end
+end

data/lib/rails_drips/queue_inventory.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  class QueueInventory
+    def self.call
+      adapter = RailsDrips.configuration.queue_inventory
+      adapter ? adapter.call : nil
+    end
+  end
+end

data/lib/rails_drips/result.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  Result = Struct.new(:status, :enrollment, :campaign, :delivery, :reason, :count, keyword_init: true) do
+    def success?
+      %i[enrolled removed activated paused resumed archived unarchived enqueued retried cancelled sent completed created version_created metadata_updated unchanged].include?(status)
+    end
+  end
+end

data/lib/rails_drips/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsDrips
+  VERSION = "0.0.1"
+end

data/lib/rails_drips.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_record/railtie"
+require "active_job/railtie"
+require "action_mailer/railtie"
+
+require "rails_drips/version"
+require "rails_drips/errors"
+require "rails_drips/result"
+require "rails_drips/mail_registry"
+require "rails_drips/configuration"
+require "rails_drips/instrumentation"
+require "rails_drips/definition_schema"
+require "rails_drips/definition_loader"
+require "rails_drips/queue_inventory"
+require "rails_drips/engine"
+
+module RailsDrips
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def enroll(**attributes)
+      Enroll.call(**attributes)
+    end
+
+    def remove(**attributes)
+      Remove.call(**attributes)
+    end
+
+    def pause_campaign(**attributes)
+      PauseCampaign.call(**attributes)
+    end
+
+    def resume_campaign(**attributes)
+      ResumeCampaign.call(**attributes)
+    end
+
+    def archive_campaign(**attributes)
+      ArchiveCampaign.call(**attributes)
+    end
+
+    def unarchive_campaign(**attributes)
+      UnarchiveCampaign.call(**attributes)
+    end
+
+    def enqueue_due_deliveries(**attributes)
+      EnqueueDueDeliveries.call(**attributes)
+    end
+
+    def table_name_prefix
+      "rails_drips_"
+    end
+  end
+end

data/lib/tasks/rails_drips_tasks.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+namespace :rails_drips do
+  desc "Validate a campaign definition (DEFINITION=path)"
+  task validate: :environment do
+    definition = RailsDrips::DefinitionLoader.load_file(ENV.fetch("DEFINITION"))
+    puts "Valid: #{definition.dig("campaign", "key")}" # rubocop:disable Rails/Output
+  end
+
+  desc "Import a definition; dry-run unless APPLY=true (DEFINITION=path)"
+  task import: :environment do
+    definition = RailsDrips::DefinitionLoader.load_file(ENV.fetch("DEFINITION"))
+    result = RailsDrips::ImportDefinition.call(definition: definition, dry_run: ENV["APPLY"] != "true")
+    puts "#{result.status}: #{definition.dig("campaign", "key")}" # rubocop:disable Rails/Output
+  end
+
+  desc "Activate a draft campaign version (CAMPAIGN=key VERSION=number)"
+  task activate: :environment do
+    campaign = RailsDrips::Campaign.find_by!(key: ENV.fetch("CAMPAIGN"))
+    version = campaign.campaign_versions.find_by!(version_number: ENV.fetch("VERSION"))
+    puts RailsDrips::ActivateCampaign.call(campaign: campaign, version: version).status # rubocop:disable Rails/Output
+  end
+
+  desc "Enqueue due scheduled deliveries"
+  task enqueue_due: :environment do
+    puts RailsDrips.enqueue_due_deliveries.count # rubocop:disable Rails/Output
+  end
+end